# docs/

Everything an agent needs that is not a rule and not code. `CLAUDE.md` at the
root carries the rules and points here. Nothing here restates a rule.

The tier is the path, so staleness is visible from the filename.

| path | holds | lifetime |
| --- | --- | --- |
| `docs/*.md` | living. One file per subsystem: the reasoning, corrected in place. Each carries `Last verified: <date> @ <sha>`. | until it is wrong |
| `docs/evals/` | dated measurements, one file per measurement. **Never edited after the day.** A newer number is a new file. | forever |
| `docs/caveats/` | known limits, one entry per limit, each with a task id and a revisit trigger. Indexed in `docs/caveats/CLAUDE.md`. | until fixed, then deleted |
| `docs/plans/` | the plan for one piece of work, frozen once it starts | until the work lands |
| `docs/archive/` | dead. Read by nobody by default. | forever |

## Rules for this directory

* One fact, one home. A measurement is cited from a living doc, never copied
  into it. The two drift the moment they are both edited.
* A living doc is corrected in place and its `Last verified` line moves with the
  correction. Do not append a changelog to it.
* A number in prose with no `docs/evals/` file behind it is an opinion.
* Fixing something deletes its caveat. It does not edit the eval that found it.

## Where a subsystem's reasoning lives

`routing.md`, `language.md`, `world.md`, `offload.md`, `deployment.md`,
`ecosystem.md`, `workflow.md`, `design.md`, `rearchitecture.md`,
`determinism.md`, `protocol.md`, `handler-wiring.md`, `operations.md`, `qa.md`.
The root `CLAUDE.md` says which one to read before touching what.