One page per module, holding what used to live in its header block: why the module is the
way it is, the measurements behind each number, and what was tried and rejected.
Rule 2 used to allow a header block "as long as it needs to be". Measured on 16/08/2026, that
had grown into 6062 comment lines out of 16634 across the tree, 36%, with one module
(home/shell/claude-code.nix) carrying a 123-line header. A header that long stops being
documentation and becomes a wall you scroll past to reach the code. Worse, none of that
reasoning was reachable from docs/: to find out why Caddy has a jail, you had to already know
to open system/services/caddy.nix.
So the reasoning moved here instead of being deleted. The module keeps a 2-line header that says
what it is and points at its page. After the sweep the tree is at 1601 comment lines out of
13299, 12%, and no comment anywhere runs longer than 2 lines.
Nothing was deleted. Every measurement, every rejected alternative and every correction that
was in a header is on one of these pages. If you find something here that the code no longer
does, that is rule 16 and the page is the bug.
"What do I type to redo this by hand?" Steps outside Nix's reach
The history is a diary and keeps its entries even when they go stale, because a diary that gets
edited stops being evidence. These notes are the opposite: they describe the CURRENT state, and
rule 16 applies in full, so a note that stops being true is a bug.
Grouped by SUBJECT, not by repo path. A mirror of the tree was measured and rejected: 16 of
the 51 pages cross the system/ and home/ boundary (arch-legacy, claude-code, monitors, theme,
restic, vpn, fonts and others) and 19 reference two or more modules. They cross because the
ARTIFACT crosses, so a mirror would have to split a third of the pages or file them under a
half-truth. The folder answers "where would I go looking", which is the question a reader
actually has.
The file name mirrors the module, so system/services/caddy.nix becomes
network/caddy.md. When a page covers several modules it takes the name of the SUBJECT
(desktop-plumbing.md, apps-and-mime.md).
A page is created only when there is something to say. A module whose header compresses to
2 lines with nothing lost does not get a page.
The module points here, never the other way around. The pointer lives in the 2-line header,
and repo/link-checker.md is what keeps those pointers honest: a broken
one fails nix flake check.