writing-documentationlisted

# Writing documentation Docs are part of the change. They ship in the same commit or PR as the code they describe, and they describe the system as it is now. A doc that is wrong is worse than no doc: readers and agents act on it. ## Follow the project first Read what the repo already has: README, `docs/`, decision records or an RFC process, CONTRIBUTING, the language the docs are written in, the changelog style. Extend that structure. Introduce the layout below only where nothing exists, and say so. ## Where each thing goes | Document | Answers | Place | |---|---|---| | README | What is this, how do I run it, where is the rest | repo root (and one per package in a monorepo) | | Topic docs | How does X work today | `docs/NN-topic.md`, one topic per file, indexed in `docs/README.md` | | Decision record (ADR) | Why did we choose X over Y | `docs/decisions/NNNN-title.md`: context, decision, consequences. Never edited after acceptance; a new ADR supersedes it | | CHANGELOG | What changed for users in each version | `CHANGELOG.md`, Keep a Changelog sections, grouped from Conventional Commits | | Agent manifest | Commands, rules and boundaries for AI agents | CLAUDE.md / AGENTS.md: short, links to docs instead of copying them | | API reference | Exact contract of an interface | generated from the source of truth (OpenAPI from schemas or code, typedoc, KDoc, DocC); never hand-maintained in parallel | | Code comments | Why this code is the way it is | next to the code | Keep dec