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 the link, not the file. In therootnote builder, your answers live in the address. Regenerate from it later and you get the current version of every document with your answers re-applied — so taking an improvement never means retyping them, and keeping your answers never means keeping a stale copy. A question several documents ask is answered once.

Every rootnote here is in the builder, chosen by the kind of project — software, writing, research or design — with one exception that is not really one: the pointer rootnote is what the builder's generated index already is, so it is not offered as a second index inside the set. Filling a document in on its own page, below, still produces a copy with nothing to regenerate it from; the builder is the route that keeps your answers.