Skip to content

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/.

CheckFails when
notes-header, notes-id, notes-summary, notes-tagsA 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-linkrelated, replaced_by, or a code: path does not resolve
notes-indexThe committed docs/ai/INDEX.md differs from the generated text
notes-handoff-ageA 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:index

That 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.

RecordA later change may
An accepted ADRReplace the status line with Status: Superseded by NNNN, naming an ADR file that exists. The rest of the file stays
0001-phase-0-defaults.mdAdd lines at the end. This file is the append-only log
A new decisionAdd 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.

PracticeWhat a page does
One topicOne short page
ReferenceTables, the command the repository runs, and a path
On this siteDescribe only what is in the code on main. Do not describe planned work. Roadmap: docs/ai/PLAN.md
Agent text and ADRsLink the file. The page keeps the path and the status line
SecuritySay what the check is for, and link the source
Orderweight 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

ScriptRole
scripts/guards/notes.tsRewrites docs/ai/INDEX.md
scripts/docs/docs.tsChecks CLAUDE.md, the ADR set, the pull-request template, the book snapshot and the architecture rule table
scripts/docs/legal.tsChecks docs/human/legal/
scripts/docs/compliance.tsChecks docs/human/compliance/
scripts/docs/outline.tsChecks the step-book dependency graph
scripts/docs/triage.tsParses the severity triage comment
scripts/docs/endpoints.tsWrites 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.

PathWriter
docs/site/content/endpoints/*.mdThe command below. Hand-editing a page fails endpoint_pages_match_every_route_policy
docs/site/data/endpoints/web.yamlOptional 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 --write

main 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.

RunFailure when the pages are stale
npm testscripts/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 checkThe 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-siteHugo build only. It does not run this test

The generated section is Endpoints.