feat(docs): vitepress site for docs/, mermaid rendering, ci build workflow

Implementation of ADR-0022.

* `vitepress`, `vitepress-plugin-mermaid` and `mermaid` added to
  workspace devDependencies. Build settled at ~9 s for the full
  site, sub-second incremental in dev.
* `docs/.vitepress/config.mts`:
  * `srcExclude` drops `docs/README.md` (git/IDE-only index) and
    `docs/decisions/template.md` (authoring scaffold).
  * `rewrites` maps `decisions/README.md` → `decisions/index.md`
    so `/decisions/` resolves to the curated landing while the
    source stays git-friendly.
  * `ignoreDeadLinks` skips cross-repo refs (`../CLAUDE`,
    `../../apps/**`, `../../notes/**`), `localhost:*` dev URLs,
    and the deliberately-excluded `README`/`template` references —
    the source stays usable from a git/IDE reader without
    breaking the site build.
  * Auto-generated sub-sidebar for `/decisions` walks
    `00NN-*.md` so adding an ADR is one file.
  * Mermaid via `withMermaid` with `securityLevel: 'strict'`.
* `docs/index.md` — VitePress Hero landing with four feature
  cards (Architecture, Decisions, Development, Onboarding).
* `package.json` exposes `docs:dev`, `docs:build`, `docs:preview`.
* `docs/development.md` (line ~5): `[setup/](setup/)` → first
  page, since folder-style links don't resolve cleanly under
  `cleanUrls`. Line 330: wrap `${{ github.* }}` in
  `<code v-pre>…</code>` so VitePress's Vue template parser
  doesn't trip on the curly-brace interpolation.
* `.gitea/workflows/docs-site.yml` — builds on every PR (gate
  on parse errors + genuine dead links), uploads the dist as an
  artifact on push to main. The Mermaid plugin regression fence
  greps for `class="mermaid"` / `<svg>` in ADR-0009's rendered
  HTML.
* `.gitignore` excludes `docs/.vitepress/{cache,dist}/`.

Deployment target stays provisional per ADR-0022; the workflow
publishes a `docs-site` artifact for now. The rsync step lands
once the future infrastructure ADR locks the host.

.gitea/workflows/docs-site.yml

@@ -0,0 +1,73 @@
+# Per ADR-0022 (Documentation site — VitePress).
+# Builds the static docs site from `docs/`. On `pull_request` the
+# build is a syntax / dead-link gate; on `push` to `main` the same
+# build runs and the bundle is uploaded as an artifact so the
+# operator can drop it on the static host until the future
+# infrastructure ADR locks the rsync target.
+#
+# Path filter scopes the workflow to changes that can actually
+# affect the rendered site: documentation content, the VitePress
+# configuration itself, and dependency manifests (Vite/VitePress
+# upgrades).
+
+name: Docs site
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - '.gitea/workflows/docs-site.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - '.gitea/workflows/docs-site.yml'
+
+jobs:
+  build:
+    runs-on: [self-hosted, on-prem]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      # `pnpm docs:build` runs `vitepress build docs` per the script
+      # added in this chantier. Fails the workflow on:
+      #   - markdown / Vue-template parse errors,
+      #   - genuine dead in-site links (the config's
+      #     `ignoreDeadLinks` regex already covers the intentional
+      #     cross-repo + localhost references that must not break
+      #     the build).
+      - name: Build docs site
+        run: pnpm docs:build
+      # Sanity-check: the build must produce HTML where the Mermaid
+      # plugin has injected its diagram markers. Guards against a
+      # silent regression on the plugin upgrade path — `pnpm install`
+      # might happily resolve a new major that no longer hooks into
+      # markdown-it the same way, leaving fenced ```mermaid blocks
+      # as raw text. Per ADR-0022 §"Confirmation".
+      - name: Assert Mermaid renders into the build output
+        run: |
+          if ! grep -RIlq 'class="mermaid"\|<svg' docs/.vitepress/dist/decisions/0009-auth-flow-oidc-pkce-msal-node.html; then
+            echo "ADR-0009's Mermaid sequence diagram did not render — Mermaid plugin regression?" >&2
+            exit 1
+          fi
+      # On push only — upload the static bundle so the operator can
+      # rsync it to the host until the future infra ADR formalises
+      # the deployment target. The artifact lives 30 days in Gitea's
+      # storage by default.
+      - name: Upload docs bundle
+        if: github.event_name == 'push'
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs-site
+          path: docs/.vitepress/dist/
+          retention-days: 30