The README says what the project does; nothing said why any of it works the
way it does. This adds design notes written to be read end to end: each
section states the decision, the reasoning, and what it cost.
docs/GUIDE.md is the readable source. docs/guide.html is the same material as
a self-contained reading page for the project site — no webfonts, no scripts
beyond a progress rail, so it also works saved to disk and opened offline.
Covers the context budget allocator, the propose-and-referee world-state
engine, the measured length-hint result, the memory bank's settled-action and
cursor rules, the two coordinate systems behind the summarization bugs, the
retry variant machinery, the egress fix, and the demo-key pinning. Closes with
the measured numbers, the known limitations, and a pointer to the cleanup
backlog in self-review.md.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PoBAfwRzHozF2bhZumxjPk
The demo sleeps on Render's free tier, so a cold link looks broken to
anyone who won't wait 30-60s. A static page on GitHub Pages is never
asleep: it shows the screenshots immediately and sets the expectation
before the visitor clicks through to the demo.
Served from main:/docs, reusing the screenshots already committed there.
Palette and type match the app so the two read as one product.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015sygnUWH8WnaoKPDp7hXM1
The README claimed screenshots were "coming" and stopped describing the
project around phase 10, so the world-state engine, the retry/undo state
revert and the egress work — the most interesting parts — were invisible.
- Screenshots of the play screen, Insights, the schema editor and the
script editor, captured from the running app.
- Document the world-state engine, undo/retry rewind, and the two measured
performance fixes; correct the context assembly order to match
context/builder.py; drop the stale "phases 1-6 complete" note.
- Add CI (backend pytest, frontend lint + build, Docker image build) and
its badge. Nothing ran the 151 tests but me.
- Move CODE_REVIEW_FINDINGS.md to docs/self-review.md and say up front
that every correctness finding is resolved.
- Drop a dead import that the newly-wired lint flagged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015sygnUWH8WnaoKPDp7hXM1
- When a model streams reasoning but no story text, return a specific,
actionable error (raise Max output tokens / set a reasoning cap / use a
non-reasoning model) instead of the opaque "empty response".
- Bump default max_output_tokens 400 -> 800: 400 truncated scenes and
left reasoning models with no room after thinking. Affects new settings
rows; existing users keep their value.
- README: add a "Try it live" link to the Render deployment.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TEpWMjnfPqzZ13nPMoGhs5
Guest-first multi-user mode behind AIDND_MULTI_USER (local installs
unchanged): signed-cookie guest sessions bootstrapped by /api/auth/me,
register upgrades the guest in place, login/logout, per-IP rate limits.
Every router scoped by user_id; Settings become per-user with the API
key Fernet-encrypted at rest and write-only through the API. Users
without a key get a server-funded demo key (OpenRouter free models,
20 turns/day, memory bank disabled on demo turns). Public read-only
demo scenarios (seed_demo.py); debug log restricted to local mode.
Frontend: auth modal + guest nudge, 401 re-establish/retry, demo
banner and key management in Settings.
Migrations 13-23 adopt existing data under a local user and encrypt
stored keys. Verified: migration on a copy of real data.db, two-session
isolation + register/login via curl and Chrome, demo cap 429, live
OpenRouter turn through the encrypted-key path, vite build + oxlint.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KFsGHju9szibJJa2YJcdbg
- LICENSE: MIT
- README: rewritten as portfolio-grade docs (features with code pointers,
architecture, Docker/Windows/macOS quick starts, BYO-model table)
- Dockerfile (3-stage: SPA build, pip wheels, slim runtime) + compose with
a /data volume; .dockerignore keeps secrets and local data out
- database.py: AIDND_DB_PATH env override so deployments can relocate the
SQLite file; documented in backend/.env.example
- start.sh: macOS/Linux dev script with first-run setup
Verified locally: production SPA build served by the backend (deep links
OK), DB created at the override path. Docker image itself untested here
(Docker not installed); flagged in plan/07.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KFsGHju9szibJJa2YJcdbg
Claude