# /docs — cross-cutting docs

Anything affecting **both** client and api, plus planning and roadmap. Side-specific docs live in [`/api/docs`](../api/docs) and [`/client/docs`](../client/docs).

Put here:

- [`roadmap.md`](roadmap.md) — phases, POC scope, what's next
- [`traps.md`](traps.md) — **bugs we have already shipped, and the guards that catch them.** Read before writing tests: every one of them passed a green suite.
- [`adr/`](adr/) — Architecture Decision Records
- [`canon-log.md`](canon-log.md) — the cross-boundary contract (§11)
- Shared contracts — canon log schema, tag syntax, retry policy (§11, §12)
- Anything spanning the HTTP boundary

The charter itself — [`CLAUDE.md`](../CLAUDE.md) — stays at the repo root. It is the source of truth; these docs elaborate, they do not override it.