docs: split CLAUDE.md into an always-loaded core plus dev-docs/

CLAUDE.md had grown to 152 KB (~21k words, ~40k tokens) and is loaded into every coding-agent session. The cost is not the cache read, it is attention: the rules that are genuinely invariant were drowning in the mechanics of subsystems that most tasks never touch. The split criterion is blast radius, not importance. A rule a change anywhere could violate stays in CLAUDE.md — the commit rule, the production/schema constraint, domain neutrality, the event-bus rule, the crate boundaries, and the module map. The mechanism of one subsystem moves to dev-docs/, opened on entry to that subsystem via a routing table at the top of CLAUDE.md. Nothing was rewritten: every section was moved verbatim by line range and verified line-by-line against the original. The only edits are cross-reference repairs ("see the DB section" -> a link), the promotion of headings in the extracted files, and a condensed "Current state" whose full text now lives in dev-docs/users-auth-and-boot.md. CLAUDE.md: 152 KB -> 31 KB. Twelve subsystem files plus an index under dev-docs/, which now carries the same standing rule as docs/ and CHANGELOG.md: a change to a subsystem updates its dev-doc in the same change. No CHANGELOG entry: this is documentation for coding agents with no observable effect on the application.
2026-08-24 18:04:43 +01:00
parent 52a63286ce
commit 902f47ecd8
14 changed files with 569 additions and 398 deletions
@@ -0,0 +1,29 @@
+*Skald dev-docs — architectural reference for coding agents. Entry point: [../CLAUDE.md](../CLAUDE.md)*
+
+# dev-docs — index
+
+These files hold the **design rationale of one subsystem each**. They are not loaded into an agent's context automatically: [`../CLAUDE.md`](../CLAUDE.md) is, and it names the file to open before touching a given area.
+
+The split criterion is *not* importance. Everything here is load-bearing — most paragraphs exist to record a trap somebody already fell into ("the obvious alternative is X, and it is wrong because Y"). The criterion is **blast radius**: a rule a change *anywhere* can violate stays in `CLAUDE.md`; the mechanism of one subsystem lives here and is read on entry to that subsystem.
+
+**When you change one of these areas, update its file in the same change** — same standing rule as `docs/` and `CHANGELOG.md`. A doc written later is written from the diff, which is the version nobody can use.
+
+| File | Read it before touching |
+| ---- | ---- |
+| [users-auth-and-boot.md](users-auth-and-boot.md) | login, sessions, `UserManager`, `UserContext`, per-user DB encryption, what boot unlocks and spawns |
+| [database.md](database.md) | any table or accessor under `db/`, the registry/owner bucket split, memory notes, reports, prompt substitutions |
+| [filesystem-and-containers.md](filesystem-and-containers.md) | `container/`, the fs-tools, mounts, path routing, skills, the memory signposts, built-in tools |
+| [projects-and-files.md](projects-and-files.md) | projects, shared folders, `<file-explorer>`, the `#files` page |
+| [agent-loop.md](agent-loop.md) | `crates/agent-loop/`, `loop_adapters/`, `session/handler/`, sub-agents, cancellation, restart recovery, the approval gate |
+| [context-and-compaction.md](context-and-compaction.md) | compaction, the history window, the cached system-prompt prefix |
+| [llm-stack.md](llm-stack.md) | LLM clients, `providers.yaml`, retriability, request logging, token streaming, multimodal attachments |
+| [mcp-connectors.md](mcp-connectors.md) | MCP runtimes, connectors, marketplace installs, OAuth, device/QR login |
+| [plugins.md](plugins.md) | plugin visibility, per-user config, HTTP routers, plugin-contributed web pages |
+| [default-access.md](default-access.md) | anything grantable (plugin, connector) and who receives it by default |
+| [system-agents.md](system-agents.md) | event triage, the memory lints, the conversation review, their scheduler and settings |
+| [frontend.md](frontend.md) | anything under `web/` — components, chat tabs, routing, i18n, theme, the security-group picker |
+
+Two sources of truth sit outside this directory and outrank it:
+
+- **`blueprint/project-family.md`** — the design document, gitignored and not under version control. Referenced by section number (§0.1, §5.1, §6, §7, §9, §11, §12, §14, §15, §16, §17, §19). Never assume a section says what you remember; open it.
+- **`../CLAUDE.md`** — the always-loaded rules: the commit rule, the production/schema constraint, domain neutrality, the event-bus rule, the crate boundaries.