/sdlc:docs

Generated from solutions/ontological/skills/docs/SKILL.md.

Description

Regenerate the generated-docs artifacts from the entities on disk: docs/index.md — SDLC’s single front-door — docs/glossary.md — the vocabulary roster assembled from term entities — and docs/references.md — the external-source roster assembled from reference entities. All are build artifacts: never hand-edited, always regenerated via sdlc docs generate [<artifact>…] (bare invocation = the three committed wiki artifacts; positional names scope the run — name site explicitly to build the Cloudflare-owned Astro site, which is otherwise gitignored and rebuilt at deploy time). Trigger when an entity is added/removed/renamed/re-kinded, a term or reference is added or edited, or a narrative section is added.

Allowed tools

• Read
• Glob
• Edit
• Write
• Bash

Source

docs

Regenerate the generated-docs artifacts. A bare sdlc docs generate regenerates the three committed wiki artifacts — index, glossary, references ([[D-B4CA-term-entity-and-generated-glossary]], [[D-0009-reference-entity-and-docs-appendix]]). The site artifact is selectable too but Cloudflare-owned — see “The site artifact” below.

docs/index.md — the front-door

Two parts:

• Narrative (fixed pointer) — a short fixed pointer block to the prose docs: [[vision]] (the why), [[PR-0001-sdlc]] (what it is and how it’s designed), [[D-VSLI-distributed-work-runner-architecture]] (the architecture). The prose lives in those docs; the index neither copies nor transcludes it.
• Reference (generated) — one ## section per entity type, read from docs/planning/. Each section splits its entities into an Active table and, when non-empty, a follow-up Emerging / obsoleted table carrying an explicit Status column. Summary cells transclude each entity’s ^summary block. A status value not covered by the bucket table is routed to the follow-up table with its status shown — never dropped.
• Appendix (generated) — the Glossary and References tables (the same data the standalone artifacts render — one pass, second projection) ahead of the fixed Conventions block.

Bucket	Status values
Active (in effect)	open/active, open/accepted, open/published, open/verified, open/validated
Emerging	open/draft, open/proposed, open/planned
Obsoleted	every closed/*

docs/glossary.md — the vocabulary roster

Assembled from the term entities under docs/planning/terms/ ([[D-B4CA-term-entity-and-generated-glossary]]). One table — Term | Definition | Source — alphabetical by title; the Definition cell transcludes the term’s ^summary block; the Source cell renders the term’s related: wikilinks. open/draft and closed/retired terms land in the follow-up Emerging / retired table.

To add vocabulary: sdlc term create --title <term>, fill the Definition section, regenerate. create derives the slug from the title; pass an explicit <slug> positional only to override it, or run sdlc term preview-id "<term>" first to see the would-be slug/id.

docs/references.md — the external-source roster

Assembled from the reference entities under docs/planning/references/ ([[D-0009-reference-entity-and-docs-appendix]]). One table — Reference | Summary | Link | Cited by — alphabetical by title; the Summary cell transcludes the reference’s ^summary block; the Link cell renders the optional url host-labelled; Cited-by renders related:. open/draft and closed/retired references land in the follow-up Emerging / retired table.

To catalog a source: sdlc reference create --title <name> [--url <url>], fill the Summary section, regenerate. create derives the slug from the title; pass an explicit <slug> positional only to override it, or run sdlc reference preview-id "<name>" first to see the would-be slug/id.

The site artifact — Cloudflare-owned, generated at deploy time

The Astro/Starlight site under the configured <docs_site> directory is published by Cloudflare, which runs sdlc docs generate site then astro build on every deploy (bun run build:doc-site). Its generated output — everything under <docs_site>/src/content/docs/ and the generated sidebar (<docs_site>/src/generated/sidebar.mjs) — is therefore gitignored and never committed: it was pure per-commit noise, and Cloudflare rebuilds it from source anyway. site is excluded from the default artifact set, so a bare sdlc docs generate and the drift gate never touch it; name it explicitly to regenerate the local content for preview.

The Astro app is plugin-provided. The build scaffold (astro.config.mjs, package.json, src/content.config.ts, src/routeData.ts, public/, …) is the plugin’s solutions/ontological/site-template/; the same sdlc docs generate site run materializes it into <docs_site>/ (overwriting — it is plugin-owned) so a consuming project “carries along” the build machinery and never hand-maintains it. The generic astro.config.mjs reads the site title/description/social/url from a generated src/generated/site-config.mjs (emitted from site.yaml’s site: block), so nothing project-specific is baked into the scaffold. A consumer’s <docs_site>/ therefore commits only site.yaml + supplemental/; the scaffold, content, node_modules, and dist are all gitignored.

Since [[D-0010-deterministic-site-assembly]] the site content is a pure build artifact: one sdlc docs generate site pass owns every file under <docs_site>/src/content/docs/ and the generated sidebar. The pass generates the reference pages (ops, entities, skills), the planning-corpus rosters + per-entity child pages, the glossary/references appendix, the data-model page, and the roadmap, and mirrors the hand-written pages in.

Source	What it generates
Plugin surface (skills, entity schemas, op registry)	the reference/ pages
Planning entities (docs/planning/<plural>/)	/planning/<plural>/ rosters + child pages (glossary/references re-platform as overrides)
Milestone entities	the generated roadmap.md
Supplemental pages (<docs_site>/supplemental/)	mirrored into the content root per the manifest

The supplemental model. Hand-written pages live OUTSIDE the content root under <docs_site>/supplemental/ and are declared in <docs_site>/site.yaml (the manifest: a landing: slot + an ordered nav: list). The pass mirrors each declared page into the content root with an injected AUTO-GENERATED banner. After placement the whole content root is swept: a file the pass did not place is deleted if bannered (stale generated page) or a hard error if unbannered (foreign hand-written content — the fix is mv to <docs_site>/supplemental/ + a manifest entry). There is no escape hatch for hand-written pages in the content root.

To add or edit a site page: edit the source — an entity for generated pages, or <docs_site>/supplemental/<path> (plus a site.yaml nav entry) for hand-written ones — then regenerate. The architecture is documented at /architecture/site-assembly/.

Regenerating

All artifacts are build artifacts. Regenerate with the registered op ([[S-0004-sdlc-cli-llm-head-deterministic-tail]]):

sdlc docs generate            # the committed wiki artifacts (index, glossary, references)
sdlc docs generate index      # scoped run
sdlc docs generate glossary
sdlc docs generate references
sdlc docs generate site       # build the Cloudflare-owned site (gitignored output)

The generator (solutions/ontological/lib/services/docs/generate.ts) reads the entities under docs/planning/, parses each through the remark/mdast extraction helpers, assembles plain data structures, and renders them through index_template.eta / glossary_template.eta / references_template.eta. The site artifact (solutions/ontological/lib/services/docs/site.ts) writes the docs site’s generated pages under <docs_site>/src/content/docs/.

--check — the drift gate

sdlc docs generate <…> --check regenerates the selected artifacts against the entities on disk WITHOUT writing and exits non-zero (NAMESPACE_CONFLICT / exit 7), naming the drifted pages, when regeneration would change anything; a clean tree exits 0.

sdlc docs generate site --check   # gate the site
sdlc docs generate --check        # gate every artifact

The gate is wired into quality_checks, so a PR that changes an entity without regenerating the site fails it ([[D-0010-deterministic-site-assembly]] §6, [[T-9DOK-site-check-gate-hardening]]). After editing an entity, run sdlc docs generate and commit the result.

Contract

• docs/index.md, docs/glossary.md, docs/references.md, and the whole <docs_site>/src/content/docs/ tree are generated. Do not hand-edit them; edit the source (entity, or <docs_site>/supplemental/ for a hand-written site page) and re-run the op.
• Idempotent: re-running against unchanged sources produces byte-identical files (no diff on the second run); --check proves it.
• The site’s assembly model (manifest, ownership sweep, collision semantics, supplemental workflow) is documented on the site itself at /architecture/site-assembly/ — source: <docs_site>/supplemental/architecture/site-assembly.md ([[D-0010-deterministic-site-assembly]]).