Code Documentation

Write documentation that stays close to the code, tells the next reader what to do, and remains maintainable by both humans and agents.

Core model

Documentation in this repo falls into five surfaces:

1. Inline docs — docstrings, JSDoc/TSDoc, comments, types
2. In-folder docs — README.md, ARCHITECTURE.md, TESTS.md, and related files that explain one directory
3. Root instruction docs — AGENTS.md, PLAN.md, SPEC.md, SOUL.md, PRINCIPLES.md, DESIGN.md
4. Operational runbooks — workflow-specific procedures in runbooks/ or a local RUNBOOK.md
5. Project docs — docs/ for references, audits, guides, memories, specs, and longer-form artifacts

Default rule: put the doc in the narrowest place that future readers will naturally look first.

Quick routing