Build the documentation as a VitePress site

[suffro]

Turns docs/ into a VitePress documentation site. Hosting and deployment are deliberately out of scope: there is no base, no sitemap hostname and no workflow.

Structure

Section	Pages
Home	index.md (hero, install + condensed result, feature grid, command table)
Getting Started	introduction.md, installation.md, quickstart.md (new)
Core Concepts	decisions.md, datasets.md, gates.md (new)
Testing & Reliability	metrics.md, fuzzing.md (new); properties.md, regression.md (rewritten)
Production	production.md, policy.md (rewritten)
Backends	backends.md (overview + mock); systemone.md, http.md, custom-backends.md (new, split out of the old backends page)
Reference	cli.md (new); contracts.md, reports.md (rewritten)
CI and Architecture	ci.md, architecture.md (rewritten)

All nine existing pages keep their paths. Metric definitions moved from reports.md to metrics.md, and the fuzzing workflow (seeds, minimization, replay) moved from properties.md to fuzzing.md. Code comments and .context/ references to moved sections now point to the new pages. That is the only change under src/ and tests/.

How it was checked against the implementation

• The CLI reference was written from cli/__init__.py. The contract reference was written from the pydantic models, and every row of "Invalid combinations" was triggered against the real validator, with messages copied from its output.
• The quickstart was run end to end, including the PASS, WARN, FAIL and exit-2 paths, against decguard installed from PyPI (0.1.0, then re-checked against 0.1.1, where the output matches apart from the version string and timings). Other outputs (fuzz, replay, diff, check, run) were copied from real runs of examples/refund.
• All 31 YAML snippets were validated against the schema. 29 pass as written. The other two are expected: the {...} skeleton, and the plugin example, which needs the plugin installed. The plugin example was built as a real entry-point package and run with validate and test --all. The HTTP endpoint example was also run against decguard test.
• The production-record and dataset JSON examples load with check and validate.

Build and links

• npm ci && npm run docs:build succeeds. VitePress fails the build on dead links between pages; I confirmed that by adding a broken link once and removing it again.
• VitePress does not check #anchors, so a separate script checked the built HTML: 1004 internal links, 300 of them with anchors, and 0 problems. I also broke one anchor to confirm the script catches it.
• The dev server starts. The homepage and a docs page were checked visually in light and dark mode, and at 390px width.

Other changes

• README: shortened to a landing page (install, a short quickstart, capabilities, links into the docs). Links stay absolute GitHub URLs because the README is also the PyPI page (see Install from PyPI in the README; release 0.1.1 #7). PyPI will show the new README only after the next release.
• Version in the nav: read from pyproject.toml at build time. Version strings in page text are pinned to 0.1.1 and will need updating on each release.
• Node tooling (dev only): a root package.json with docs:dev, docs:build and docs:preview, and vitepress@1.6.4 pinned exactly, with a lockfile. npm audit reports three advisories in VitePress's dev-server dependency chain (esbuild/vite). They affect only the local dev server, and VitePress 1.x has no fix yet.
• CHANGELOG (Unreleased) and .context/ (architecture, conventions, state) are updated.

Checks

• ruff check, ruff format --check, mypy: pass. Ruff also formats Python blocks inside Markdown, so three doc snippets were reformatted.
• pytest: 313 passed, 8 opt-in real-backend skips.
• syngraphe check: no problems.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Failed ❌ View logs ↗		346fada	2026-09-25T01:02:35.403Z	View logs ↗