Phase 4 — Docs and AI ergonomics

[rsml]

Part of the demo-quality refactor tracked in docs/plans/refactor/. Branch phase-4-docs. Depends on Phases 2 and 3.

Objective

Make the repo legible to a cold reader and to an AI agent picking it up for the first time. Documentation lives where it is needed rather than in one big file, and the parts that drift get generated and gated in CI.

Contents

• Six ADRs covering filesystem as database, just in time generation with quiz masking latency, local kokoro text to speech, the single package monorepo shape, AI behind a text generation port, and the Electron hoisting constraints
• A CONTEXT.md glossary that resolves the Skill collision, meaning the learner facing Skill in the learning profile against Agent Skills under .claude/skills
• Seven fractal READMEs in load bearing folders only
• Roughly 140 terse JSDoc blocks stating constraints the signature cannot show
• CLAUDE.md rewritten after the restructure, with the hand maintained API routes table replaced by a generated doc
• A routes doc generator reading the live Fastify route registry, plus a CI drift gate
• A standard .mcp.json, and two project skills named verify and add-feature

Gate

• Every documented path actually exists
• pnpm docs:routes is idempotent, and the CI drift job fails when the doc is stale
• Both skills pass a dry run

[rsml]

Closed by PR #56, the docs phase. ARCHITECTURE.md five-diagram hub, CONTEXT.md glossary, eight ADRs, ten folder READMEs, the generated API reference with its CI drift gate, CLAUDE.md rewritten to 152 accurate lines, .mcp.json, and the verify and add-feature Agent Skills.