9a9ccf56

docs: add CLAUDE.md, a context budget for this repo

a73x   2026-08-18 12:38

docs: add CLAUDE.md, a context budget for this repo

A retrospective over this project's ten session transcripts put 84% of
the token bill in cache reads — context already in the window, re-sent
every turn. Growth across all sessions totalled 6.9M tokens and was
billed as 2,198M: every token added is paid for roughly 317 more times
before the session ends. The baseline at turn one is 35-40k, so nearly
all of it is self-inflicted, and reading the tree is what inflicts it —
822k tokens tracked, 9.1k lines in server.zig alone.

So this file is a budget, not an introduction. The "never cat these"
list and the //! header trick exist because grep-then-window costs a
fiftieth of a read; the toolchain pin is here because rediscovering it
costs a failed build first; the invariants are the design facts that
reviews kept re-deriving from source. Kept to ~990 tokens on the same
logic it teaches — it loads every session and is re-billed with the
rest.

The build steps were taken from `zig build --help` and the layer table
from build.zig's module table, which caught a `make check` that does
not exist: the gate is a zig step with no Makefile target.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>