ADR 0130: The docs site renders the help tree through the shared discovery module

Amendments.

• ADR 0143 — ADRs on site: the ADRs-stay-off-site deferral is lifted — decision records render on the site as project history outside product guidance.
• ADR 0218 — command name: the shared manual tree now renders through discern docs; the /docs route and one-document-model decision stand.
• ADR 0314 — corpus boundary: /docs and the installed manual move from a filtered Map projection to a dedicated manual source. The shared discovery and rendering engine remains; the safely admitted Map publishes separately as a trust exhibit.

Status: accepted

The site (ADR 0129) needed a documentation section with the usability of a modern docs product: sidebar navigation, search, pagination, per-page contents. The content already existed twice over — the map/ tree documents the system, and BUNDLED_PUBLIC_DOC_DIRS already curates which of its subtrees ship inside every customer binary as discern help. The risk in adding a docs site was adding a third copy: a separate content tree, or a site-side list of what to publish, either of which would drift from what the binary actually serves.

Listings also needed per-page metadata (a one-line description for navigation, search, and index files) that no doc carried. Requiring authored metadata on every leaf would create a surface agents forget to maintain — the exact staleness the map discipline exists to prevent.

/docs renders the help tree. The site imports the engine's own discoverDocs and filters to BUNDLED_PUBLIC_DOC_DIRS: the allowlist that decides what ships in a customer binary is, unchanged, the boundary that decides what publishes on the web. There is no site-side content list.

Metadata is derived first, overridden second. Discovery now derives every doc's description from its lead paragraph (the derivation map-overview regions already used), and an optional frontmatter block (title, description, order, publish) can override a derived value when the derivation reads poorly. Parsing lives in the engine, so every discern project's map/help records carry descriptions, not just this site.

Routes strip the reading-order prefixes (/docs/quality-gate/the-receipt, not /docs/20-quality-gate/…) so renumbering a tier never breaks an inbound link. Every page negotiates like the rest of the site: text clients — or a .md suffix — receive the pristine Markdown bytes, the same bytes discern help <leaf> --raw prints. Relative links rewrite to routes when the target is published and to the repository on GitHub when it is not, so a reference to an internal tier or an ADR never dead-ends.

The ADRs themselves stay off the site for now — links point at GitHub — until the public-audience prose review recorded in TODO.md has happened.

• The site cannot drift from the binary: what discern help serves and what discern.sh/docs serves are one derivation apart from the same allowlist. A leaf added to the map appears in the nav, search index, llms.txt, and the test suite with no site change.
• The auto-enrolling suite (tests/site_docs_test.ts) now guards link integrity for the published tree — a cross-reference into an unpublished tier must rewrite cleanly or the build fails. This protects the bundled discern help reading experience too.
• Frontmatter is a new, optional engine surface. Its restricted grammar (scalar key: value lines only) is deliberate: anything richer passes through as document content rather than risking silent content loss.
• Descriptions being derived means a poorly-opening leaf gets a poor listing line — visible in /docs and discern map --json — which is pressure on the prose itself rather than on a metadata sidecar.