docs(nav): publish every ADR and runbook, gated by a nav check (closes #169) (#172)

## What & why

`docs/` is the source of truth (CLAUDE.md §12), but only pages listed in `mkdocs.yml`'s nav
are published — and mkdocs' own `validation.nav.omitted_files: warn` keeps the build green
while dropping the rest. So the site had quietly stopped at **ADR-0010** and
**`runbooks/ci.md`**: 31 pages, including every ADR from 0011 to 0034, six of the seven
runbooks, and `synthetic-data.md`, existed in the repo and nowhere else.

- `infra/check-docs-nav.py` fails when a page under `docs/` is not in the nav. It runs in
  `make lint`, so the existing CI job gates it — python3 only, no new tooling, and no
  mkdocs install needed to check it.
- The nav now lists all 34 ADRs, all 7 runbooks and `synthetic-data.md`.
- ADR-0033's `Slice:` header said "none yet"; #25 closed it.
- The landing page gained a pointer to the Talos runbook.

Closes #169

## Definition of Done

- [x] Linked Gitea issue (above).
- [x] Failing test committed before the fix — the red commit lists all 31 missing pages.
- [x] Implementation makes the test pass.
- [x] Conventional Commits referencing the issue (`refs #169`).
- [ ] CI green — awaiting the run on this PR (`python3 infra/check-docs-nav.py` passes locally;
      `make lint` also needs the .NET SDK, which CI has).
- [x] `docker compose up` unaffected — docs and `mkdocs.yml` only, plus one `make lint` line.
- [x] Docs updated — that is the change.
- [x] No ADR needed: no dependency, no boundary, no §8 rule touched.
- [x] Not user-visible, so no demo note.

## Notes for reviewers

- The check is a **substring test**, not a YAML parse (there's a `ponytail:` note in the
  script): a page's path either appears in `mkdocs.yml` or it doesn't. That keeps it
  dependency-free — `mkdocs.yml` can't be read by `yaml.safe_load` anyway, it carries a
  `!!python/name:` tag for the mermaid fence. It does not check that an entry *points at a
  file that exists*; mkdocs' `not_found: warn` covers that direction.
- ADR labels in the nav are shortened by hand (`"ADR-0013: Behandel-portal wiring"`), since
  several H1s are a full sentence.

**Known gap, not fixed here:** CLAUDE.md §12 says the site is "published via a Gitea Actions
workflow to Gitea Pages", and no such workflow exists — `mkdocs build` is never run, by CI or
by any make target. Gitea has no built-in Pages, so publishing needs a decision (a
`gitea-pages` server, an artifact, or a static host) rather than a patch. Worth its own issue
if the published site is actually wanted; until then this PR makes the nav correct for whoever
runs `mkdocs serve`.Reviewed-on: #172

Makefile

@@ -64,6 +64,9 @@ frontend:
 ## lint: verify formatting (no changes)
 lint:
 	dotnet format $(SLN) --verify-no-changes
+	# Only pages in mkdocs.yml's nav are published, and mkdocs keeps a build green
+	# when one is missing — so the nav is checked here rather than not at all.
+	python3 infra/check-docs-nav.py
 
 ## build: release build
 build:

docs/architecture/adr-0033-kubernetes-via-one-helm-chart.md

@@ -3,8 +3,8 @@
 - **Status:** Accepted
 - **Date:** 2026-09-04
 - **Deciders:** Respellion engineering
-- **Slice:** _(none yet — raised directly as a deployment-target request; see
-  "Process note" at the end)_
+- **Slice:** #25 (S-24) — raised directly as a deployment-target request and matched to
+  that issue afterwards; see the "Process note" at the end
 
 ## Context
 

docs/index.md

@@ -14,6 +14,8 @@ should teach.
   In Dutch; the strategic framing lives in `Respellion/innovation-lab`.
 - **[Working in Gitea](gitea-workflow.md)** — issues, milestones, branches, PRs.
 - **[CI runbook](runbooks/ci.md)** — the pipeline and the `make ci` local gate.
+- **[Kubernetes on Talos](runbooks/kubernetes-talos.md)** — the second deployment target:
+  one Helm chart, a single-node cluster, and the parts that bite (ADR-0033).
 
 ## Quickstart
 

infra/check-docs-nav.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Fail when a page under docs/ is missing from mkdocs.yml's nav.
+
+docs/ is the source of truth (CLAUDE.md §12), but only the pages listed in the nav
+are published — and mkdocs' own `omitted_files: warn` keeps a build green while
+silently dropping them, which is how every ADR after 0010 and every runbook but
+ci.md fell off the site.
+
+ponytail: a substring test, not a YAML parse — a page's path either appears in
+mkdocs.yml or it doesn't, and that needs no dependency.
+"""
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+nav = (ROOT / "mkdocs.yml").read_text()
+
+missing = sorted(
+    str(page.relative_to(ROOT / "docs"))
+    for page in (ROOT / "docs").rglob("*.md")
+    if str(page.relative_to(ROOT / "docs")) not in nav
+)
+
+if missing:
+    print(f"{len(missing)} page(s) under docs/ are not in mkdocs.yml's nav:")
+    print("\n".join(f"  {m}" for m in missing))
+    sys.exit(1)
+
+print("docs nav complete: every page under docs/ is published")

mkdocs.yml

@@ -32,6 +32,30 @@ nav:
       - "ADR-0008: Read projection store": architecture/adr-0008-read-projection-store.md
       - "ADR-0009: External-task job worker": architecture/adr-0009-external-task-job-worker.md
       - "ADR-0010: BFF OIDC validation": architecture/adr-0010-bff-oidc.md
+      - "ADR-0011: Approval status flow": architecture/adr-0011-approval-status-flow.md
+      - "ADR-0012: Citizen reference correlation": architecture/adr-0012-citizen-reference-correlation.md
+      - "ADR-0013: Behandel-portal wiring": architecture/adr-0013-behandel-portal-wiring.md
+      - "ADR-0014: Withdrawal cancels the process": architecture/adr-0014-withdrawal-cancels-the-process.md
+      - "ADR-0015: Beoordeling escalation": architecture/adr-0015-beoordeling-escalation.md
+      - "ADR-0016: Diploma eligibility DMN": architecture/adr-0016-diploma-eligibility-dmn.md
+      - "ADR-0017: Document-wait timeout": architecture/adr-0017-document-wait-timeout-cancellation.md
+      - "ADR-0018: Diploma upload via the ACL": architecture/adr-0018-diploma-upload-via-acl-documenten.md
+      - "ADR-0019: Zaak cancellation on timeout": architecture/adr-0019-zaak-cancellation-on-timeout.md
+      - "ADR-0020: Local stack self-seeds": architecture/adr-0020-local-stack-self-seeds.md
+      - "ADR-0021: Zaaktype by identificatie": architecture/adr-0021-acl-resolves-zaaktype-by-identificatie.md
+      - "ADR-0022: Quartz scheduler": architecture/adr-0022-quartz-scheduler.md
+      - "ADR-0023: Observability stack": architecture/adr-0023-observability-stack.md
+      - "ADR-0024: Prometheus AspNetCore exporter": architecture/adr-0024-prometheus-aspnetcore-exporter.md
+      - "ADR-0025: BFF reads catalogus via the ACL": architecture/adr-0025-bff-reads-catalogus-via-acl.md
+      - "ADR-0026: Mutable default-fill store": architecture/adr-0026-mutable-default-fill-store.md
+      - "ADR-0027: RegisterRecord objecttype": architecture/adr-0027-registerrecord-objecttype-schema.md
+      - "ADR-0028: Objecten holds the register": architecture/adr-0028-objecten-holds-the-register.md
+      - "ADR-0029: Objecten publishes to NRC": architecture/adr-0029-objecten-publishes-to-nrc.md
+      - "ADR-0030: Projection sourced from the register": architecture/adr-0030-projection-sourced-from-the-register.md
+      - "ADR-0031: MFA on the medewerker realm": architecture/adr-0031-mfa-on-the-medewerker-realm.md
+      - "ADR-0032: Werkbak live refresh": architecture/adr-0032-werkbak-live-refresh.md
+      - "ADR-0033: Kubernetes via one Helm chart": architecture/adr-0033-kubernetes-via-one-helm-chart.md
+      - "ADR-0034: Caddy serves the portals": architecture/adr-0034-caddy-serves-the-portals.md
   - FDS-architectuur:
       - Overzicht: architecture/fds/README.md
       - Componentview (L3): architecture/fds/c4-component-view.md
@@ -46,8 +70,15 @@ nav:
   - Working in Gitea: gitea-workflow.md
   - Frontend decisions: frontend-decisions.md
   - Demo script: demo-script.md
+  - Synthetic data: synthetic-data.md
   - Runbooks:
       - CI: runbooks/ci.md
+      - OpenZaak: runbooks/openzaak.md
+      - Open Notificaties (NRC): runbooks/opennotificaties.md
+      - Keycloak: runbooks/keycloak.md
+      - Flowable: runbooks/flowable.md
+      - Kubernetes on Talos: runbooks/kubernetes-talos.md
+      - Gitea Actions gotchas: runbooks/gitea-actions-gotchas.md
 
 markdown_extensions:
   - admonition