Governance

Allocation — what goes where

Home	May contain	Must NOT contain
AGENTS.md (per repo, committed, ≤ ~40 lines)	Repo identity (role only) · pointers to docs/ pages · the docs-repo pointer block with clone instruction (identical in all repos) · inviolables short list · its own update rule	Anything a routine feature PR can make stale — no feature surfaces, no how-tos, no env tables
repo docs/ (run / test / structure / release)	Everything needed to work in this repo alone; repo-specific conventions and test patterns	Cross-repo flows, product rationale, other repos' internals
internal/ (this site)	Platform decisions, product truth, cross-repo systems, the shared test rig, release policy, history	"How to run repo X" (→ that repo's docs/), single-repo conventions
published files (README/CHANGELOG on npm, pub.dev, Maven Central)	What / install / quickstart / support statement · links to the public /docs site	Any reference to internal/, private repos, or repo-local docs/ paths

Tie-breaker: "would this sentence still be true if this repo were rewritten in another framework?" Yes → internal/. No → repo docs/. If it was only true once → archive/history.md (one entry) + git history (full text).

Three hard rules

1. Final paths only. New files reference final internal paths — never legacy monorepo paths (docs/, misc/, TESTS-NOTES.md). Legacy paths appear in exactly one place: the source: field of an internal stub, once the stub is update remove any legacy references . If a referenced internal page doesn't exist, create the stub (or, when the content is small, write the real page in the same pass).
2. No stale facts in evergreen files. Identity lines name roles, never current feature surfaces. Test every line of AGENTS.md / intro.md against: "does a routine feature PR invalidate this?" If yes, the line moves to a page that is supposed to change.
3. Reference sweep on retirement. When a source file or section is retired, grep internal/ for references to it and fix them in the same pass — stale pointers are how docs rot invisibly.

Page contract

Every page (no exceptions):

1. Frontmatter: title, description, sidebar_position, status (stub → draft → stable), source.
2. A one-line scope statement directly under the title — what this page covers, and (when confusable) what it does not.
3. A maintenance comment: Update when: triggers, Never add: items. JSX form {/* … */} on these MDX pages; HTML <!-- … --> in plain-markdown repos. Invisible rendered, visible raw.
4. One topic per page, ≤ ~150 lines. Longer → split and link.
5. Claims about code carry > Verified against <repo> @ <sha>, <date>.
6. No append-only files, ever. New information gets its own page or section — a single file with no natural boundary attracts dumps (the TESTS-NOTES lesson).

Structure rules

• Internal root holds only: intro, decisions, backlog, governance + the six sections (product, research, systems, testing, operations, archive).
• Every section opens with an index page (the folder's index.md) stating the section's one job in one paragraph — a listing must answer "what kind of thing lives here".
• systems/<domain>/ pages are self-contained: architecture + domain-specific verification + gotchas together. Adding a domain = folder + _category_.json + scope-statement stub.
• testing/ holds the shared rig (infrastructure, accounts, cross-repo procedures); domain verification lives in systems/<domain>/.
• Live work tracking happens only in backlog.md; internal receives outcomes, never work-in-progress — WIP detail lives wherever the effort chooses outside these docs.

Templates

Copy-paste sources in templates/ at the docs-repo root: internal-page.md, agents-router.md, repo-run.md, repo-test.md, repo-structure.md, repo-release.md, readme-public.md, readme-private.md.

Adding a new repo

1. Open a fresh session at the project root and run /repo-docs <repo> — the personal prompt in .pi/prompts/repo-docs.md (kept out of the shared templates on purpose). It interviews you first, then produces and verifies the skeleton.
2. Pick the README variant (readme-public.md for registry-published repos, readme-private.md otherwise); keep it template-shaped.
3. Add the repo to the table in intro and a row in backlog.
4. If it introduces a new subsystem, add systems/<domain>/ with a stub.