Two fixes to the published site, both about not shipping something false.
exclude_docs held back prds/ but let ui-service-boundary.md through, because
architecture/migration-decisions.md links to it three times. That PRD in turn
links to service-decomposition.md and config-schema.md, so the exclusion was
still producing two dead links on the published site. Letting those two
through closes the chain: the build now reports no excluded-link references
at all.
generated-documentation.md's "Step 9: CI" said no workflow builds, checks or
publishes documentation. Adding .github/workflows/docs.yml made the first
clause false. Restated to say what that workflow does and, more importantly,
what it deliberately does not: it does not run docsgen, regenerate
contracts.json, or publish. Generated-artifact drift is still gated locally by
task check, which is the split that section exists to protect, since a CI job
that regenerated output could paper over uncommitted differences rather than
fail on them.
Adds an mkdocs.yml, a landing page, and `task docs:site` / `task docs:serve`.
Deliberately hosting-agnostic: MkDocs is the same input Backstage TechDocs
consumes, so choosing where this lands later costs nothing.
exclude_docs holds back four subtrees, since everything under docs/ would
otherwise be published. archive/ is superseded design and would compete with
the current architecture for a reader's attention; inspiration/ discusses
other products by name; prds/ are open decisions rather than settled design;
github-token.md is credential setup. One PRD is let back through because
architecture/migration-decisions.md links to it three times, and a page
excluded out from under a live link is just a 404 with extra steps.
No nav block. MkDocs derives it from the directory layout, so a new page
under docs/architecture/ publishes without a second edit, and there is no
hand-maintained tree to drift against the repository.
Builds --strict, so a dead internal link fails rather than ships.