Rootnotes

A rootnote is a document that lives in a project root and carries what the repository cannot state: the commercial facts, the conventions, the constraints somebody decided once and never wrote down — and the points at which an agent should stop and ask rather than proceed.

The name is literal. They sit at the root, and they are the things everything else rests on.

What makes a rootnote, rather than documentation

Four properties, and a document needs all of them:

• It encodes what cannot be discovered. If an agent with the repository in front of it could work the answer out, that belongs in code or in ordinary documentation. A rootnote carries the things no file states — which jurisdiction's rules apply, which word you use for a concept, why a constraint exists.
• It says where to stop. Every good rootnote names the decisions that are not an agent's to make. Prepare them, argue for them, draft them — but a human enacts them. That boundary is the most valuable line in most of these documents.
• It is portable. Not tied to one tool. A rootnote can be dropped into aCLAUDE.md, an AGENTS.md, a rules directory, or read on its own. Instruction files are tool-specific and behavioural; rootnotes are neither.
• It is scoped to one topic. One subject per file, so an agent needing the editorial conventions does not spend context on the commercial plan to reach them.

What a rootnote is not

Not a CLAUDE.md. That is an instruction file: tool-specific, auto-loaded, about behaviour in one repository. Rootnotes get referenced by or pasted into one. The two are complementary, and conflating them is why so many instruction files grow into unmaintainable walls.

Not a README. A README orients a human arriving at a repository. A rootnote briefs whoever is about to change it.

Not code narration. A document describing what the code does is the least valuable kind and the fastest to rot — correct on the day it is written, silently wrong after the next refactor, and adding nothing while it is correct.

Filling them in

Some rootnotes carry fill-in fields. Rather than handing you a long document to trawl for the parts needing changed, they ask for those parts and hand back a file you can commit. Two rules govern what earns a field, both learned by getting them wrong:

• Template what the reader chooses, never what an agent can discover. A project name is in the directory, the manifest and the git remote. Asking for it is asking the reader to do the agent's job — and it is wrong outright for a document meant to sit at the root of many projects.
• Only where the choice is genuinely open. Where one option is simply better, a field moves a decision the author was better placed to make and dresses it up as flexibility.

Filling one in produces a derivative rather than the published document, so it says so, and any field left blank keeps its visible placeholder rather than silently emptying.

Keep your answers. The pack builder can save them as a small handover.values.json file. Commit it beside the documents, and when one is updated later, load it back and download again — your values are re-applied to the current text rather than retyped. Without it a customised copy is a dead end: taking the improved version means losing your answers, and keeping your answers means keeping a stale document.