Docs: introduce the two-tier colocated docs convention (CLAUDE.md push tier + DETAILS.md pull tier)

Colocated `CLAUDE.md`s auto-inject into context whenever an agent reads files in their directory, so every word there costs tokens in every session touching the area; the repo carries ~206k words of them. The new contract caps the push tier at must-knows and gives depth a designated colocated home:

- `CLAUDE.md`: invariants, gotchas, don't-do-X-because-Y, a 2–3 line module map, and a pointer; target ~400–600 words. Litmus: could an agent editing a random file here silently break something without this line?
- `DETAILS.md`: the area's real docs (architecture narrative, data flows, decision rationale, edge-case catalogs), read on demand; in whole before structural changes.
- Never `@`-import `DETAILS.md` from a `CLAUDE.md` (would rebuild the auto-load cost).

Wired into `AGENTS.md` § File structure, `docs/architecture.md`'s framing, and the `docs-maintenance` rule (Gotcha/Why → CLAUDE.md, Decision/Why → DETAILS.md, evidence → docs/notes/).

Author: vdavid

.claude/rules/docs-maintenance.md

@@ -1,19 +1,22 @@
 When modifying code in a directory that contains a `CLAUDE.md` file, check whether your changes affect the documented
-architecture, key decisions, or gotchas. If they do, update the `CLAUDE.md` to stay in sync. If you notice a `CLAUDE.md`
-missing in a directory where there should be one, add it. Skip this for trivial changes (bug fixes, formatting, small
-refactors that don't change the architecture).
+architecture, key decisions, or gotchas. If they do, update the colocated docs to stay in sync: `CLAUDE.md` for
+must-knows, `DETAILS.md` for depth, per the litmus in `AGENTS.md` § File structure (could an agent editing a random
+file here silently break something without this line? Then `CLAUDE.md`, target ~400–600 words; everything else
+`DETAILS.md`). If you notice a `CLAUDE.md` missing in a directory where there should be one, add it. Skip this for
+trivial changes (bug fixes, formatting, small refactors that don't change the architecture).
 
 If something failed due to a wrong assumption, add a `Gotcha/Why` entry to the nearest `CLAUDE.md`.
 
-Add `Decision/Why` entries to the nearest colocated `CLAUDE.md` for key decisions. If the decision has rich evidence
-(benchmarks, detailed analysis), put the evidence in `docs/notes/` and link from the CLAUDE.md.
+Add `Decision/Why` entries to the nearest colocated `DETAILS.md` (plus a one-line guardrail in `CLAUDE.md` only if
+ignoring the decision can silently break something). If the decision has rich evidence (benchmarks, detailed analysis),
+put the evidence in `docs/notes/` and link from the `DETAILS.md`.
 
 When writing guides, see [this diff](https://github.com/vdavid/cmdr/commit/13ad8f3#diff-795210f) for the formatting
 standard. (Before: AI-written. After: matching our standards for conciseness and clarity.)
 
 ## Describe current behavior, not history
 
-`CLAUDE.md` files describe the current state of the code and app; git history is for history. Drop narration of previous
+`CLAUDE.md` and `DETAILS.md` files describe the current state of the code and app; git history is for history. Drop narration of previous
 code shapes ("we originally tried X", "no longer applicable as of Z", date-stamped milestone framing on Decisions). Keep
 the non-obvious why, actionable guardrails ("don't switch to X, it breaks Y"), and historical pain that encodes a
 constraint the current code must defend. Litmus: if removing the history still leaves current state described AND enough

AGENTS.md

@@ -95,8 +95,15 @@ Core structure:
   - `style-guide.md` - Writing, code, and design style rules
   - `security.md` - Security policies
   - `maintenance.md` - Recurring maintenance tasks (dep bumps, allowlist trims, doc sweeps) and a log of past runs
-- Feature-level docs live in **colocated `CLAUDE.md` files** next to the code (for example,
-  `src/lib/settings/CLAUDE.md`). Claude Code auto-discovers these. See `docs/architecture.md` for the full map.
+- Feature-level docs live in **colocated `CLAUDE.md` + `DETAILS.md` files** next to the code (for example,
+  `src/lib/settings/CLAUDE.md`). `CLAUDE.md` is the push tier: Claude Code auto-injects it whenever files in that
+  directory are read, so every word costs tokens in every session that touches the area. `DETAILS.md` is the pull tier:
+  the area's real docs, read on demand. The litmus: could an agent editing a random file here silently break something
+  without this line? Then it's `CLAUDE.md`. Everything else is `DETAILS.md`. So `CLAUDE.md` = invariants, gotchas,
+  don't-do-X-because-Y, a 2–3 line module map, and a pointer; target ~400–600 words. `DETAILS.md` = architecture
+  narrative, data flows, decision rationale with depth, edge-case catalogs. Read it in whole before structural changes
+  in an area. Never `@`-import `DETAILS.md` from a `CLAUDE.md` (that would rebuild the auto-load cost the split exists
+  to remove). See `docs/architecture.md` for the full map.
 
 ## Testing and checking
 

docs/architecture.md

@@ -1,8 +1,10 @@
 # Architecture
 
-The orientation map: what each subsystem is and where it lives. Per-subsystem detail (invariants, gotchas, decisions)
-lives in each directory's colocated `CLAUDE.md`. Cross-cutting platform constraints that belong to no single subsystem
-are in the [Cross-cutting patterns](#cross-cutting-patterns) section below.
+The orientation map: what each subsystem is and where it lives. Per-subsystem must-knows (invariants, gotchas,
+guardrails) live in each directory's colocated `CLAUDE.md`; each area's full docs (architecture narrative, flows,
+decision detail) live in its colocated `DETAILS.md` (see `AGENTS.md` § File structure for the split contract).
+Cross-cutting platform constraints that belong to no single subsystem are in the
+[Cross-cutting patterns](#cross-cutting-patterns) section below.
 
 ## Frontend (Svelte 5 + TypeScript)