Skip to content
sdlc

T-FQ7A-site-self-documentation

Status: closed/done · Impact: medium · Complexity: medium

Goal

Section titled “Goal”

The deterministic site has no reader-facing explanation of itself: how pages and nav are assembled, what site/site.yaml declares, the ownership rule, and — critically — the contributor workflow (“how do I add a page?”). Author that documentation, and serve it on the site as a supplemental architecture page — dogfooding the exact API it documents.

Today

Section titled “Today”
LocationRole today
site/src/content/docs/architecture/Architecture pages cover the substrate, data model, leases — nothing covers the site’s own assembly
docs/planning/decisions/D-0010-deterministic-site-assembly.mdThe design — decision-shaped (options, consequences), not reader-facing how-it-works prose
plugin/skills/docs/SKILL.mdOperator instructions for regenerating, not an explanation

Proposed

Section titled “Proposed”

site/supplemental/architecture/site-assembly.md, declared in site/site.yaml’s Architecture group → /architecture/site-assembly/. Content (reader-facing, Hemingway, tables + one Mermaid flow):

  • The one-pass assembly model: sources (plugin surface, planning entities, supplemental pages) → pages + nav; everything under the content root is machine-placed.
  • site/site.yaml: landing, nav slots, generated: keys, groups, two-level cap — with the real manifest as the worked example.
  • The ownership rule and collision semantics: banner-split sweep, reserved namespaces, NAMESPACE_CONFLICT failures and what each error means for the person who hit it.
  • The contributor workflow: add a supplemental page (author under site/supplemental/, declare, regenerate), add an entity (it appears via projection with zero wiring), reorder the nav (edit site.yaml).
  • Pointers: D-0010-deterministic-site-assembly for rationale, the docs skill for operation.

The design and milestone themselves reach the site via the P5 decision/milestone projections; this page is the prose explanation those rosters can’t carry.

Approach

Section titled “Approach”
  1. Author the page against the machinery as actually shipped (P1–P3 at minimum; revise for projections when P4–P7 land or write to the design and verify at P8).
  2. Declare it in site.yaml (Architecture group, after data-model).
  3. Regenerate; confirm route, sidebar entry, and build.
  4. Cross-link: docs skill and /dev-update-docs point at the page as the canonical explanation.

Files to touch

Section titled “Files to touch”
LocationKindChange
site/supplemental/architecture/site-assembly.mdnewThe page
site/site.yamlmodifyArchitecture-group entry
plugin/skills/docs/SKILL.mdmodifyPointer to the page
.claude/skills/dev-update-docs/SKILL.mdmodifyPointer to the page

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: /architecture/site-assembly/ renders on the built site, reachable from the Architecture sidebar group.
  • AC-2: The page documents manifest shape, ownership/collision semantics, and the add-a-page / add-an-entity / reorder-nav workflows, consistent with shipped behavior.
  • AC-3: The page is supplemental content — authored under site/supplemental/, declared in site.yaml, surviving a full regenerate + ownership sweep.
  • AC-4: T-9DOK-site-check-gate-hardening’s skill-update pass verifies the page against final M-0005 behavior (content parity check rides P8).

Out of scope

Section titled “Out of scope”
  • Documenting wiki-side artifacts (docs/index.md, glossary, references) beyond a pointer — the docs skill owns that.
  • Publishing/deployment docs.

Dependencies

Section titled “Dependencies”

Discovery context

Section titled “Discovery context”

Requested in-session 2026-06-07 during M-0005 P2: “we also need to document how the SDLC site documentation works… and ensure that it ends up in the site.”

Depends on

Section titled “Depends on”

T-9LZ4-site-supplemental-migration

← Back to Tasks