Docs rules
Notes, decision records, and the pages on this site. Where a fact already lives in code, these pages link the file.
Notes
The vault rules are docs/ai/README.md. scripts/guards/notes.ts enforces the header, the links, the index, and handoff age, and warns on a moved code: path. The header parser is scripts/guards/notes-header.ts. Both run under npm run guards.
Five types, one folder each under docs/ai/notes/: area, reference, pitfall, how-to, handoff. Nothing else goes in notes/.
| Check | Fails when |
|---|---|
notes-header, notes-id, notes-summary, notes-tags | A field is missing, unreadable, or outside its list. The id disagrees with the file name. The summary is empty or over 120 characters. tags are not the type plus the area names |
notes-link | related, replaced_by, or a code: path does not resolve |
notes-index | The committed docs/ai/INDEX.md differs from the generated text |
notes-handoff-age | A handoff’s checked date is more than 14 days ago |
A change that touches a path named in code: and leaves that note untouched is a warning (notes-code-moved). A current note whose checked date is more than 90 days ago is a warning. An area folder with no docs/ai/notes/area/<area>.md hub is a warning. Warnings leave the command green.
INDEX.md
docs/ai/INDEX.md is generated. Hand-editing it fails notes-index on the next guard run.
npm run notes:indexThat is node scripts/guards/notes.ts. When every header parses, the command rewrites the index. A header error prints the findings and leaves the file alone.
ADRs
Records in docs/human/decisions/ stay as history. scripts/docs/docs.ts checks the index and, through adrChangeProblem, what a later change may do.
| Record | A later change may |
|---|---|
| An accepted ADR | Replace the status line with Status: Superseded by NNNN, naming an ADR file that exists. The rest of the file stays |
0001-phase-0-defaults.md | Add lines at the end. This file is the append-only log |
| A new decision | Add the next numbered file, with the headings Context, Decision, Alternatives, Consequences and Compliance, and a row in the index |
docs/human/decisions/** is outside the docs-only allowlist on Commits and pull requests. DO-1 and DO-2 are the written rules. The index introduction states the same limit for an accepted record.
This site
Pages under docs/site/content/ follow the outline in issue #1161. Hugo reads that tree. docs/ai/ and docs/human/ stay where the checks read them, and these pages link them.
| Practice | What a page does |
|---|---|
| One topic | One short page |
| Reference | Tables, the command the repository runs, and a path |
| On this site | Describe only what is in the code on main. Do not describe planned work. Roadmap: docs/ai/PLAN.md |
| Agent text and ADRs | Link the file. The page keeps the path and the status line |
| Security | Say what the check is for, and link the source |
| Order | weight in front matter. The navbar entries are menu.main in docs/site/hugo.yaml |
Preview from the repository root, with the image in docs/site/README.md. The image is Hugo extended v0.168.0. The theme is Hextra v0.13.0 (docs/site/go.mod).
docker run --rm --entrypoint hugo -v "$PWD:/project" -w /project/docs/site ghcr.io/gohugoio/hugo:v0.168.0@sha256:1fb8fe7f417abd5802d86747d297728aa48078d763159e7dff6559fe3f8bb8e7 build --gc --minify --panicOnWarning--entrypoint hugo skips the image entrypoint that runs npm i when a package.json is present. docs/site/ has no package.json. public/ and resources/ are build output and are git-ignored.
Generators on this tree
| Script | Role |
|---|---|
scripts/guards/notes.ts | Rewrites docs/ai/INDEX.md |
scripts/docs/docs.ts | Checks CLAUDE.md, the ADR set, the pull-request template, the book snapshot and the architecture rule table |
scripts/docs/legal.ts | Checks docs/human/legal/ |
scripts/docs/compliance.ts | Checks docs/human/compliance/ |
scripts/docs/outline.ts | Checks the step-book dependency graph |
scripts/docs/triage.ts | Parses the severity triage comment |
scripts/docs/endpoints.ts | Writes docs/site/content/endpoints/. Endpoint pages |
Endpoint pages
scripts/docs/endpoints.ts reads the web route tree under interfaces/web/src/routes: each route folder’s policy.ts export and the methods its +page, +page.server and +server files declare. It parses the handlers without running them. It also reads the policies export of interfaces/web/src/lib/server/limits.ts and, when it exists, the prose in docs/site/data/endpoints/web.yaml. A route folder with no policy.ts is a problem, not a skipped row.
| Path | Writer |
|---|---|
docs/site/content/endpoints/*.md | The command below. Hand-editing a page fails endpoint_pages_match_every_route_policy |
docs/site/data/endpoints/web.yaml | Optional and hand-written; not on main today. Keys are "METHOD path". The generator reads the prose and leaves the file as written. A missing file or key renders as not recorded; a key with no route fails as an orphan |
node scripts/docs/endpoints.ts --writemain defaults a missing argument to --write, so node scripts/docs/endpoints.ts rewrites the pages too. --check compares them and writes nothing. No package.json script and no workflow runs --check.
| Run | Failure when the pages are stale |
|---|---|
npm test | scripts/docs/endpoints.test.ts endpoint_pages_match_every_route_policy. It expects one row per policy.ts and checkEndpoints to return no problems |
npm run check | The same test. Root package.json check runs npm test |
CI job code | .github/workflows/ci.yml runs npm test -- --units. scripts/test/run.ts includes this file. Job check needs code |
CI job docs-site | Hugo build only. It does not run this test |
The generated section is Endpoints.