Site assembly

This site is a build artifact. One pass — sdlc docs generate site — assembles every page under the content root and the entire sidebar. Nothing under sites/df-docs/src/content/docs/ is hand-edited; the page you are reading was written elsewhere and placed here by the generator.

This page documents the machinery. The design rationale lives in decision D-0010 (docs/planning/decisions/); operational instructions live in the docs skill.

The one-pass model

Source	Becomes
Plugin surface (skills, entity schemas, the op registry)	Reference pages
Planning entities (`docs/planning/<plural>/`)	Rosters and per-entity pages — Glossary, References, the Data model tables, and (rolling out) the Planning sections and Roadmap
Supplemental pages (`sites/df-docs/supplemental/`)	Hand-written pages, mirrored in per the manifest — this page, the other architecture pages, the Changelog
`sites/df-docs/site.yaml`	The sidebar (`sites/df-docs/src/generated/sidebar.mjs`)

The pass is idempotent: run twice against unchanged sources, the second run writes nothing. Generated pages are committed; the git diff is the drift signal.

The manifest: sites/df-docs/site.yaml

The manifest declares the landing page and the nav as an ordered list of slots:

Slot	Meaning
`generated: <key>`	A generated family expands here — `reference`, `appendix`, `data-model`, `planning`, `roadmap`
`file: <path>`	A supplemental page from `sites/df-docs/supplemental/<path>`
`subsite: <slug>`	A link into a nested child site declared under `subsites:` — an independent Astro project built into the deploy at `/<slug>/`
`group: <label>` + `items:`	A labelled group of the above. Two levels max — a group cannot nest a group

Groups mix freely: the Architecture group holds hand-written pages with the generated Data model page slotted between them. Reordering slots reorders the sidebar; no other file changes.

Ownership and collisions

After placing every page, the pass sweeps the whole content root. A file it did not place is classified by its banner:

Found	Classification	What happens
`AUTO-GENERATED` banner present	Stale generated page	Deleted, loudly
No banner, undeclared	Foreign hand-written content	The pass fails, naming the file and the fix

Naming collisions fail the same way — exit code 7 (NAMESPACE_CONFLICT) in every case:

Collision	Example
Two placements claim one route	A supplemental `glossary.md` vs. the generated roster
A supplemental route inside a generated namespace	`file: reference/anything.md` — `reference/`, `glossary/`, `references/`, `planning/` are reserved
Duplicate nav labels at the same level	A manifest group named `Reference` beside the generated Reference group
A route inside a subsite’s namespace	Any page at or under `/intersect/` vs. the `intersect` subsite — a subsite owns its whole `/<slug>/` subtree

The error names both claimants. Rename or relocate the supplemental page; generated namespaces always win.

How do I…

Task	Steps
Add a hand-written page	Author under `sites/df-docs/supplemental/`, add a `file:` entry to `site.yaml`, run `sdlc docs generate site`
Reorder the nav	Reorder `site.yaml` slots, regenerate
Edit an existing hand-written page	Edit the source under `sites/df-docs/supplemental/` — never the mirrored copy — and regenerate
Add vocabulary or sources	`sdlc term create` / `sdlc reference create`, fill the body, regenerate — the rosters and pages follow
Add a new entity type	Nothing site-side: a type with a schema projects onto the site by construction (generic roster + entity pages)
Nest a library’s doc site	Declare it under `subsites:` in `site.yaml` (slug + dir), optionally add a `subsite:` nav slot; `bun run build:doc-site` builds it into `dist/<slug>/` via `sdlc docs build-subsites`

If you edit a file under the content root directly, the next pass either overwrites it (generated) or fails on it (foreign). Both are the system working.

Rollout status

The supplemental model, generated sidebar, and ownership sweep are live. Landing next under milestone M-0005: Planning-corpus rosters and entity pages (decisions, standards, principles, milestones, tasks, and the rest), the Roadmap page generated from milestone entities, and a --check mode gating drift in the quality checks.