Phase 16 plan — documentation refresh

[mmacy]

Adds `docs/phase-16-plan.md` and the phase 16 roadmap entry to `docs/spec.md`. Phase 16 is the technical-writer pass over the documentation phases 10–15 updated incrementally, chartered by a five-track review of the published site, docstrings, and examples conducted after phase 15 landed.

What the review found

The docs are in better shape than "updated along the way" suggests — every phase 10–15 surface has a learning-oriented home, all doc examples pass under the CI harness, the TUI transcripts are byte-accurate, and the generated references picked up everything with zero wiring. What needs fixing: six published sentences later phases falsified (the victory entrance, the trigger-unlock "later release" line, the schema version, save/load-as-replay on both front-door carriers, the TUI delta-loop rationale, two stale surface counts), the three pages phase 15 never touched (the FastAPI and LLM-referee walkthroughs, the front door), and an IA drift — the authored layer's teaching home is a getting-started page the navigation gives no name.

Notable decisions

• The split: gates, triggers, quests, and narrator steering move from `building-an-adventure.md` into a new guide, `guides/gates-triggers-quests.md`, after "Listeners and flags"; both pages keep complete runnable programs under the harness. The stale "later release" sentence dies in the move.
• The vocabulary pass rides the one-way-bridge rule: jobs-to-be-done language locates a concept, the project term is introduced once and then committed to — no parallel vocabulary, docstrings stay precise. Concepts table on the index, "The kernel à la carte" retitled "Using the rules without a session" — navigation label, H1, and file (`rules-without-a-session.md`; docs URLs carry no compatibility contract) — and four documentation conventions added to `AGENTS.md`.
• Example changes are pinned as a closed list (result-events loop, refusal-text rendering with the `(refused:` tripwire literal preserved, quest status, a `journal` verb plus its one milestone-script line, snippet markers) with the invariant that no command sequence or draw moves — goldens byte-identical by definition.
• One spec amendment beyond the roadmap entry, applied with the implementation PR: the spec's blanket "re-registering the same listeners during a replay reproduces their state too" is true only of observe-only listeners and false for the interpreter; the amendment scopes it.
• Declined with rationale: redirects plugin (docs URLs aren't a compatibility contract and the inbound-link surface is effectively zero — no scaffolding for consumers nobody can name), a published changelog page (its repo-relative links fail the strict build; index links GitHub), the example-agent promise (reworded to fact), new mechanical gates for prose counts.

Review provenance

The five-track review fanned out over getting-started, the seven guides, the front-end walkthroughs, the phase 10–15 docstrings, and the site IA; its findings are folded into the plan directly (no separate audit artifact — the output was already work-item-shaped). The plan's rubber-duck verified every staleness claim against live files (including a live seed-21 transcript check and an empirical result-events/log-delta equality check) and returned two blocking findings — a pinned examples/ change list that omitted a marker its own work item required, and the replay-listener rule contradicting the spec with no pinned amendment — plus seven non-blocking. All nine were accepted and fixed; re-review verdict SOLID, with one sign-off note folded in (the journal verb and its script line land in one commit). Maintainer review then overturned one decline the duck had endorsed: the plan kept the kernel guide's filename under its new title for URL stability — a consumer nobody can name — so the file now renames with its title.

https://claude.ai/code/session_01GeUYYGfPQYGPRuk8C5Ju88