mdBook Docsite — Projected Documentation as the Standard Surface for ontoref-Managed Projects
Accepted
Context
The project already had `generate-mdbook` (generator.nu): it composed identity, ontology, ADRs, modes and scenarios and emitted a bare mdBook (raw markdown, the default theme, no served target). It answered "render the graph to markdown" but not "what is the standard, served, on-brand documentation surface for a project that manages itself with ontoref".
Two external references fixed the missing shape. The cdci-dao mdBook (/Users/Akasha/Development/mdbook/cdci-dao) separates CHROME from CONTENT: a ds-theme + a book.toml with preprocessors (tera, admonish, toc, codeblocks) is the container; globaldefs.md + a tera context is how content enters, with a dev↔dist swap that bakes a base-URL. docserver (/Users/Akasha/Development/docserver/code) serves PRE-BUILT static HTML registered by a [[serv_paths]] entry (src_path → url_path, is_restricted); it does not build or watch — "on demand" means rebuild, not serve-time.
The seam where ontoref plugs in is exactly cdci-dao's chrome/content split: keep the chrome fixed and shipped; feed the content from .ontoref/ on every build. The question is whether to make this the standard documentation surface for every ontoref project, and on what terms.
Decision
Adopt the cdci-dao mdBook model as the standard documentation surface, projected from the ontology and served by docserver, shipped as a protocol template.
- CHROME (shippable, fixed): reflection/templates/mdbook/ carries the ds-theme, a parameterized book.toml (tera/admonish/toc/codeblocks/variables/ extended-markdown-table), assets/css, globaldefs and brand images. It ships with the reflection tree (installed by `just install-daemon`), so consumers reach it at $ONTOREF_ROOT/reflection/templates/mdbook/ without the source repo.
- MATERIALISE: `docsite init` (reflection/modules/docsite.nu) copies the chrome into the project's .ontoref/docsite/ — idempotent, skipped if a book.toml already exists. `docsite generate` auto-runs it on first use.
- PROJECT (hybrid): on every build, docsite.nu reuses generator.nu's composed `docs data`, writes a Tera context (identity read from card.ncl, not the filesystem basename) for the static chrome pages, and pre-renders one page per ADR, one per mode, and the architecture facets into docsite/src/, assembling SUMMARY. Static Tera chrome + pre-rendered dynamic pages = the cdci-dao pattern. Re-generating re-projects; the docs cannot drift from the state they describe.
- SERVE: a dev build emits relative links for `mdbook serve`; `docsite generate --serve-path /<mount>` bakes site-url to the docserver url_path (a surgical one-line swap, save/ backup-restore) and emits the [[serv_paths]] registration.
- The generate-docsite mode declares the procedure (materialize-template → project-and-build → dist-and-register); `just docsite [serve-path]` is the shortcut. The model was proven spine-local on ontoref itself before promotion; migration 0039 carries it to consumers. Adoption is opt-in.
Constraints
- Hard The mdBook chrome (ds-theme + book.toml preprocessors + assets) MUST ship as the protocol template under reflection/templates/mdbook/. The per-ADR, per-mode and architecture pages MUST be regenerated from .ontoref/ on every build, never hand-authored into the materialised docsite/src/.
- Hard Project identity (name, description) in the docsite MUST be read from card.ncl, the ontological beacon, NOT derived from the directory basename. This keeps the model correct for any project regardless of where its ontology sits.
- Soft Serving SHOULD go through a dist build with site-url baked to the docserver mount, emitting a [[serv_paths]] registration entry. The mode MUST NOT mutate a foreign docserver config; it emits the entry and the copy hint for the operator to apply.
- Soft Building a docsite SHOULD remain opt-in: no project is required to materialise or generate one, and the absence of .ontoref/docsite/ is never an error. The capability ships; adoption is voluntary and reports direction of motion, not a gate.
Alternatives considered
- Keep generate-mdbook (the bare renderer) as the only doc surface — rejected: It emits raw markdown on the default theme with no served target and no chrome/content split. It answers 'render the graph to markdown' but is not an on-brand, docserver-servable, standard surface. Kept as a quick dump; not the standard.
- Pure-Tera: every page a {{ }} template, mdbook-tera renders all content at build — rejected: Maximises 'on demand' but forces per-ADR/per-mode loops into a single tera context while mdbook still needs one .md file per page — rigid for the per-item pages with no benefit over pre-rendering them. The hybrid keeps tera for the chrome where it helps.
- Ship to install/resources/templates/ and copy via install.nu — rejected: install.nu does not copy install/resources/templates/ wholesale, while the reflection tree IS copied verbatim to the data dir and is already how forms templates ship ($ONTOREF_ROOT/reflection/templates/). Placing the chrome under reflection/templates/mdbook/ reuses the wired path with no install.nu change.
- Promote straight to the protocol template without proving it spine-local first — rejected: Standardises an unverified surface for every consumer in one step — the premature-formalization anti-pattern (adr-029). Proving the slice on ontoref itself, then promoting with a migration, keeps the realised instance ahead of the protocol claim (sufficient-verification).
Anti-patterns
- Hand-Authoring the Projected Documentation — The architecture / decisions / modes pages are written as static markdown rather than projected from .ontoref/ on each build. The docs drift from the ontology they claim to present.
- Naming the Project from the Directory — The docsite title/identity is derived from the directory basename instead of card.ncl, producing wrong names (e.g. '.ontoref') and a model that breaks when the ontology does not sit at the project root.
- Making the Docsite a Gate — Treating the absence of a docsite as an error, or requiring every project to build one. Collapses the formalization-vs-adoption Spiral by imposing the surface rather than offering it.