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

.gitignore

@@ -10,6 +10,10 @@ tmp/
 .nx/cache/
 .nx/workspace-data/
 
+# VitePress (docs site per ADR-0022)
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
 # Test artifacts
 coverage/
 .test-output/

docs/.vitepress/config.mts

@@ -0,0 +1,164 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineConfig } from 'vitepress';
+import { withMermaid } from 'vitepress-plugin-mermaid';
+
+/**
+ * VitePress configuration for the APF Portal documentation site
+ * per ADR-0022.
+ *
+ * Source tree maps directly to URLs:
+ *   docs/index.md                → /
+ *   docs/development.md          → /development
+ *   docs/architecture.md         → /architecture
+ *   docs/decisions/README.md     → /decisions/
+ *   docs/decisions/00NN-…md      → /decisions/00NN-…   (auto-listed sidebar)
+ *   docs/setup/0N-…md            → /setup/0N-…
+ *
+ * `docs/README.md` stays as the git-side / IDE-preview index and is
+ * therefore excluded from the published site; `decisions/template.md`
+ * is an authoring scaffold, also excluded.
+ */
+
+const DECISIONS_DIR = join(__dirname, '..', 'decisions');
+const ADR_FILE_RE = /^\d{4}-[\w-]+\.md$/;
+
+/**
+ * Walks `docs/decisions/` and returns one sidebar entry per accepted
+ * ADR (`NNNN-kebab-title.md`), ordered by numeric prefix. Adding a
+ * new ADR is then a single-file change — no `config.ts` edit
+ * required (the convention spelled out in ADR-0022 §"Sidebar
+ * generation").
+ *
+ * The link text drops the numeric prefix's leading zeroes to read
+ * naturally ("ADR-0009 — …") while the underlying URL keeps the
+ * full filename for stable routing across renames.
+ */
+function adrSidebarItems(): { text: string; link: string }[] {
+  return readdirSync(DECISIONS_DIR)
+    .filter((name) => ADR_FILE_RE.test(name))
+    .sort()
+    .map((name) => {
+      const slug = name.replace(/\.md$/, '');
+      const num = slug.slice(0, 4);
+      const title = slug.slice(5).replace(/-/g, ' ');
+      return {
+        text: `ADR-${num} — ${title}`,
+        link: `/decisions/${slug}`,
+      };
+    });
+}
+
+export default withMermaid(
+  defineConfig({
+    title: 'APF Portal Documentation',
+    description:
+      "Architecture decisions, development guide, and onboarding material for APF France Handicap's web portal.",
+
+    // Root files (`README.md`) and authoring artefacts (`template.md`)
+    // never make it to the rendered site — see ADR-0022.
+    srcExclude: ['README.md', 'decisions/template.md'],
+
+    // The curated decisions index lives in `decisions/README.md`
+    // (git/IDE convention). VitePress expects `index.md` at a
+    // folder root for clean URLs, so we rewrite at build time —
+    // source layout stays git-friendly, the published URL resolves
+    // `/decisions/` to the curated landing.
+    rewrites: {
+      'decisions/README.md': 'decisions/index.md',
+    },
+
+    // ADRs and the development guide carry deliberate references to
+    // files that live OUTSIDE `docs/` (CLAUDE.md, apps/**, infra/**,
+    // notes/**), localhost URLs that only resolve in a dev session,
+    // and the authoring `template.md` we explicitly excluded. All of
+    // those are valid from a git/IDE reader's perspective; VitePress
+    // is told to skip them rather than fail the build.
+    ignoreDeadLinks: [
+      /^https?:\/\/localhost/,
+      /^\.{1,2}\//,
+      /\/template$/,
+      /\/README$/,
+    ],
+
+    // VitePress emits `.html` files by default; clean URLs hide the
+    // extension. Mirrors what readers will see in the browser address
+    // bar and what the inline ADR refs in `portal-admin` already use
+    // when they target Gitea source-view (forward-compatible the day
+    // we flip those refs to point at the docs site).
+    cleanUrls: true,
+
+    // The site is internal + read-only; we let crawlers in by
+    // default but won't ship a sitemap until the hostname is locked
+    // by the future infra ADR.
+    lastUpdated: true,
+
+    themeConfig: {
+      nav: [
+        { text: 'Development', link: '/development' },
+        { text: 'Architecture', link: '/architecture' },
+        { text: 'Decisions', link: '/decisions/' },
+        { text: 'Onboarding', link: '/setup/01-wsl-terminal-setup' },
+      ],
+
+      sidebar: {
+        '/development': [
+          {
+            text: 'Daily development',
+            items: [{ text: 'Repo layout & commands', link: '/development' }],
+          },
+        ],
+        '/architecture': [
+          {
+            text: 'Architecture',
+            items: [{ text: 'C4 + module boundaries', link: '/architecture' }],
+          },
+        ],
+        '/decisions/': [
+          {
+            text: 'Decisions',
+            items: [
+              { text: 'Index by theme', link: '/decisions/' },
+              ...adrSidebarItems(),
+            ],
+          },
+        ],
+        '/setup/': [
+          {
+            text: 'Onboarding',
+            items: [
+              { text: 'WSL terminal setup', link: '/setup/01-wsl-terminal-setup' },
+              { text: 'Dev web stack', link: '/setup/02-dev-web-stack' },
+              { text: 'Angular + Nx monorepo', link: '/setup/03-angular-nx-monorepo' },
+            ],
+          },
+        ],
+      },
+
+      socialLinks: [
+        { icon: 'git', link: 'https://git.unespace.com/julien/apf_portal' },
+      ],
+
+      search: {
+        provider: 'local',
+      },
+
+      outline: {
+        level: [2, 3],
+      },
+
+      footer: {
+        message: 'APF Portal — internal documentation',
+      },
+    },
+
+    // `vitepress-plugin-mermaid` passes its `mermaid` key through to
+    // the Mermaid runtime. Theme `default` follows VitePress's
+    // light/dark switcher automatically; explicit `securityLevel`
+    // tightens the renderer so diagrams can't inject arbitrary HTML
+    // from the source markdown.
+    mermaid: {
+      securityLevel: 'strict',
+    },
+  }),
+);

docs/development.md

@@ -2,7 +2,7 @@
 
 This document is the day-to-day reference for working on `apf_portal`. It covers the repo layout, the prerequisites, the initial setup from a fresh clone, and the commands you'll run during a typical development cycle. It is meant to grow — add sections as the team's workflow does.
 
-For decision rationale, see the [ADRs](decisions/). For onboarding the local environment (terminal, Node, pnpm), see [setup/](setup/).
+For decision rationale, see the [ADRs](decisions/). For onboarding the local environment (terminal, Node, pnpm), see [setup/01-wsl-terminal-setup.md](setup/01-wsl-terminal-setup.md).
 
 ---
 
@@ -327,7 +327,7 @@ Renovate authenticates as a dedicated bot user. Setup is manual on Gitea — don
 4. **Generate a PAT for the bot** (`RENOVATE_TOKEN`). Sign in as the bot, then User Settings → Applications → Generate New Token. Scopes needed: read/write `repository`, read/write `issue`, read `user`. Avoid `admin`.
 5. **Store the PAT as a repo secret.** Settings → Actions → Secrets → New Secret. Name: `RENOVATE_TOKEN`. Value: the token from step 4.
 6. **Generate a zero-scope GitHub.com PAT** (`GITHUBCOM_TOKEN`). On github.com (any account, e.g. yours): Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic). **Do not tick any scope** — anonymous-equivalent rights are enough; the token only buys Renovate the higher authenticated rate limit (5 000 req/h vs 60 req/h) for resolving GitHub-hosted Action versions and `containerbase/node-prebuild` binaries used during lockfile maintenance.
-7. **Store it as a repo secret named `GITHUBCOM_TOKEN`** (Gitea reserves the `GITHUB_*` secret namespace for the built-in `${{ github.* }}` context, so an underscore between `GITHUB` and `COM` is rejected).
+7. **Store it as a repo secret named `GITHUBCOM_TOKEN`** (Gitea reserves the `GITHUB_*` secret namespace for the built-in <code v-pre>${{ github.\* }}</code> context, so an underscore between `GITHUB` and `COM` is rejected).
 8. **Sign out and forget both tokens locally.** They are now only retrievable via the secret store.
 
 To **rotate** either token: regenerate at the matching step, update the secret. The schedule keeps running unattended.

docs/index.md

@@ -0,0 +1,33 @@
+---
+layout: home
+
+hero:
+  name: APF Portal
+  text: Documentation
+  tagline: Architecture decisions, development guide, and onboarding material for APF France Handicap's web portal.
+  actions:
+    - theme: brand
+      text: Read the architecture
+      link: /architecture
+    - theme: alt
+      text: Browse decisions
+      link: /decisions/
+
+features:
+  - title: Architecture
+    details: System context, container diagram, Nx module boundaries, CI/CD pipeline. Cross-cutting Mermaid diagrams that frame the whole platform.
+    link: /architecture
+    linkText: Open architecture
+  - title: Decisions (ADRs)
+    details: Every non-trivial choice — auth flow, sessions, audit trail, downstream-API access, accessibility, performance budgets, admin app — recorded as MADR 4.0.0 ADRs.
+    link: /decisions/
+    linkText: Open decisions
+  - title: Development guide
+    details: Repo layout, daily commands, observability dev-loop (Jaeger, log↔trace correlation), dependency updates, conventional commits.
+    link: /development
+    linkText: Open development guide
+  - title: Onboarding
+    details: WSL terminal setup, Node + pnpm + Docker, Angular + Nx monorepo bootstrap. Everything a new contributor needs to get a working environment.
+    link: /setup/01-wsl-terminal-setup
+    linkText: Start onboarding
+---

package.json

@@ -9,7 +9,10 @@
     "ci:audit": "pnpm audit --audit-level=moderate",
     "ci:commits": "pnpm exec commitlint --from ${COMMIT_LINT_FROM:-origin/main} --to HEAD --verbose",
     "ci:gzip-budgets": "node scripts/check-gzip-budgets.mjs",
-    "ci:perf": "pnpm exec nx build portal-shell --configuration=production && pnpm ci:gzip-budgets && pnpm exec lhci autorun --config=./lighthouserc.js"
+    "ci:perf": "pnpm exec nx build portal-shell --configuration=production && pnpm ci:gzip-budgets && pnpm exec lhci autorun --config=./lighthouserc.js",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "private": true,
   "lint-staged": {
@@ -101,6 +104,7 @@
     "jsdom": "^29.0.0",
     "jsonc-eslint-parser": "^2.1.0",
     "lint-staged": "^17.0.0",
+    "mermaid": "^11.15.0",
     "nx": "22.7.1",
     "pino-pretty": "^13.1.3",
     "postcss": "^8.5.12",
@@ -113,6 +117,8 @@
     "typescript": "~5.9.2",
     "typescript-eslint": "^8.40.0",
     "vite": "^8.0.0",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-mermaid": "^2.0.17",
     "vitest": "^4.0.8",
     "webpack-cli": "^5.1.4"
   },