up

docs/ci/20_CI_RECIPES.md

@@ -241,7 +241,59 @@ jobs:
 
 ---
 
-## 4 · Troubleshooting cheat‑sheet
+## 4 · Docs CI (Gitea Actions & Offline Mirror)
+
+StellaOps ships a dedicated Docs workflow at `.gitea/workflows/docs.yml`. When mirroring the pipeline offline or running it locally, install the same toolchain so markdown linting, schema validation, and HTML preview stay deterministic.
+
+### 4.1 Toolchain bootstrap
+
+```bash
+# Node.js 20.x is required; install once per runner
+npm install --no-save \
+  markdown-link-check \
+  remark-cli \
+  remark-preset-lint-recommended \
+  ajv \
+  ajv-cli \
+  ajv-formats
+
+# Python 3.11+ powers the preview renderer
+python -m pip install --upgrade pip
+python -m pip install markdown pygments
+```
+
+**Offline tip.** Add the packages above to your artifact mirror (for example `ops/devops/offline-kit.json`) so runners can install them via `npm --offline` / `pip --no-index`.
+
+### 4.2 Schema validation step
+
+Ajv compiles every event schema to guard against syntax or format regressions. The workflow uses `ajv-formats` for UUID/date-time support.
+
+```bash
+for schema in docs/events/*.json; do
+  npx ajv compile -c ajv-formats -s "$schema"
+done
+```
+
+Run this loop before committing schema changes. For new references, append `-r additional-file.json` so CI and local runs stay aligned.
+
+### 4.3 Preview build
+
+```bash
+python scripts/render_docs.py --source docs --output artifacts/docs-preview --clean
+```
+
+Host the resulting bundle via any static file server for review (for example `python -m http.server`).
+
+### 4.4 Publishing checklist
+
+- [ ] Toolchain installs succeed without hitting the public internet (mirror or cached tarballs).
+- [ ] Ajv validation passes for `scanner.report.ready@1`, `scheduler.rescan.delta@1`, `attestor.logged@1`.
+- [ ] Markdown link check (`npx markdown-link-check`) reports no broken references.
+- [ ] Preview bundle archived (or attached) for stakeholders.
+
+---
+
+## 5 · Troubleshooting cheat‑sheet
 
 | Symptom                               | Root cause                  | First things to try                                             |
 | ------------------------------------- | --------------------------- | --------------------------------------------------------------- |
@@ -253,6 +305,7 @@ jobs:
 
 ---
 
-### Change log
-
-* **2025‑08‑04** – Variable clean‑up, removed Docker‑socket & cache mounts, added Jenkins / CircleCI / Gitea examples, clarified Option B comment.
+### Change log
+
+* **2025‑10‑18** – Documented Docs CI toolchain (Ajv validation, static preview) and offline checklist.
+* **2025‑08‑04** – Variable clean‑up, removed Docker‑socket & cache mounts, added Jenkins / CircleCI / Gitea examples, clarified Option B comment.