Build the documentation as a VitePress site

.context/decisions/backend-plugins-via-entry-points.md

@@ -17,7 +17,7 @@ are untrusted input, and the plan forbids executing arbitrary code from contract
   `DecisionResult` semantics.
 - Python code can also be used directly through `CallableBackend` in the Python API.
 - The generic HTTP backend speaks a small documented JSON protocol, `decguard.http/0.1`
-  (docs/backends.md), with `label_map` for differing label names. Credentials come only
+  (docs/http.md), with `label_map` for differing label names. Credentials come only
   from environment variables.
 - No real Open-Jev/Kev adapter ships in Step 1: their APIs were not available to design
   against, and CI must not need model downloads or GPUs. The opt-in external test

.context/decisions/core-dependencies-and-internal-metrics.md

@@ -37,5 +37,5 @@ Build backend: `hatchling`. Tooling: `uv` (lockfile `uv.lock` committed), `ruff`
 ## Consequences
 
 - `pip install decguard` stays light and pure-Python.
-- Metric definitions are ours to keep correct; `docs/reports.md` documents every formula
+- Metric definitions are ours to keep correct; `docs/metrics.md` documents every formula
   and the tests pin them. Any change to a metric definition is a report-format change.

.context/decisions/systemone-builtin-backend.md

@@ -64,4 +64,4 @@ github.com/jaredpalmer/kev.
   and downloads about 1.8 GB of weights, which are cached by pinned revision. That is why
   the workflow is manual.
 - Changing the pinned Kev commit, checkpoint or Jev model means updating the workflow env,
-  `docs/backends.md` and the real contracts together.
+  `docs/systemone.md` and the real contracts together.

.context/state/current.md

@@ -2,10 +2,14 @@
 
 ## Current focus
 
-`0.1.0` is released: tag `v0.1.0` on `ca2373a`, published to PyPI by `release.yml`
-(Trusted Publishing, attestations) with the same wheel and sdist on the GitHub Release.
-The repository is public. `0.1.1` (on `main`, not yet tagged) only fixes the README, which
-is the PyPI project page: install with `pip install decguard`, absolute GitHub links.
+Documentation site (branch `docs/vitepress`): `docs/` is now a VitePress site with
+getting started, concepts, testing, production, backends, reference, CI and architecture
+sections; the README is a short landing page (absolute GitHub links, since it is the PyPI
+project page). Hosting/deployment of the site is deliberately not configured yet.
+
+Released: `0.1.0` (tag `v0.1.0` on `ca2373a`) and `0.1.1` (tag `v0.1.1` on `20b6b02`,
+README fix only), both published to PyPI by `release.yml` (Trusted Publishing,
+attestations) with the same files on the GitHub Releases. The repository is public.
 
 ## Recent relevant changes
 
@@ -38,15 +42,21 @@ is the PyPI project page: install with `pip install decguard`, absolute GitHub l
   metadata contains only compatible permissive licenses plus Certifi's MPL-2.0; `uv.lock`
   is current and every registry artifact is hash-pinned. No runtime dependency was added
   for the real backends.
+- Documentation: VitePress site in `docs/` (`npm run docs:build` fails on dead links);
+  existing page paths kept, backends split into `docs/systemone.md`, `docs/http.md` and
+  `docs/custom-backends.md`, metrics moved to `docs/metrics.md`, the fuzzing workflow to
+  `docs/fuzzing.md`.
+  Quickstart output was produced by the PyPI package.
 - Release workflow: pushing a `vX.Y.Z` tag validates the tag against `pyproject.toml` and
   CHANGELOG, builds and checks the distributions once, publishes them to PyPI with Trusted
   Publishing (environment `pypi`, no stored token), then creates the GitHub Release with
   the same files. Procedure in CONTRIBUTING.md#releasing.
 
 ## Next
 
-- Release `0.1.1` (push `v0.1.1` on the `main` commit with the README fix) so PyPI shows the
-  corrected page; a released version's PyPI description cannot be edited.
+- Merge the documentation PR, then choose and configure hosting for the VitePress site
+  (separate task; the site has no `base` or deployment workflow). Once a public docs URL
+  exists, point `project.urls.Documentation` in `pyproject.toml` and the README at it.
 
 ## Blockers
 

.context/truth/architecture.md

@@ -50,6 +50,9 @@ explicit policies and SDK) are implemented.
   records, summaries, property checks, `rejudge`, load-time `verify_run`), `render.py`
   (terminal).
 - `engine.py`: `run_test(mode="test"|"fuzz"|"all")` orchestration shared by CLI and API.
+- `docs/`: the user documentation as a VitePress site (`docs/.vitepress/config.mts`, a
+  small theme extension in `docs/.vitepress/theme/`); Node tooling is dev-only
+  (`package.json`, `package-lock.json` at the root). Not part of the Python package.
 - `cli/`: typer app with `validate`, `test` (`--all`), `fuzz`, `report`, `diff`, `replay`,
   offline `check`, and policy `run`.
 
@@ -69,8 +72,8 @@ policy → action directive (fallback is not invoked automatically).
 
 ## External systems
 
-- Decision backends over HTTP (`decguard.http/0.1` or System One, docs/backends.md) or
-  installed plugins. None is needed for the default test suite; a local stdlib HTTP server
+- Decision backends over HTTP (`decguard.http/0.1`, docs/http.md; System One,
+  docs/systemone.md) or installed plugins. None is needed for the default test suite; a local stdlib HTTP server
   backs the integration tests.
 - Real backends, opt-in only: a self-hosted Kev server (upstream `jaredpalmer/kev`, Kev-0.8B
   at a pinned revision) and Jev via OpenRouter (`typesafe/jev-1.13`, `OPENROUTER_API_KEY`),

.context/truth/conventions.md

@@ -15,7 +15,13 @@
   test` and `decguard test --all` (`test_examples_pass`, `test_examples_pass_all_checks`).
 - Deterministic outputs that users may store (mock hash distribution, fuzz RNG stream)
   are pinned by tests; changing them is a CHANGELOG-worthy format change.
-- Docs for users in `docs/`; user-visible changes go in `CHANGELOG.md` under Unreleased.
+- Docs for users in `docs/`, a VitePress site: every page is listed in the sidebar in
+  `docs/.vitepress/config.mts`; links between pages are relative `.md` links so they work
+  on GitHub too. The implementation is authoritative: command output shown in the docs is
+  copied from real runs. User-visible changes go in `CHANGELOG.md` under Unreleased.
+- Hosting/deployment of the docs is not configured (no `base`, no workflow).
+- `README.md` is also the PyPI project page: link with absolute GitHub URLs, not
+  repository-relative paths.
 
 ## Development workflow
 
@@ -26,10 +32,18 @@ uv run mypy
 uv run pytest
 ```
 
+Documentation (Node.js 18+, dev-only):
+
+```bash
+npm ci
+npm run docs:dev      # local preview
+npm run docs:build    # production build; fails on dead links between pages
+```
+
 CI (`.github/workflows/ci.yml`) runs these on Ubuntu and macOS for Python 3.11–3.13 and
 installs the built wheel in a clean environment.
 
-Real-backend checks are opt-in and never part of the default run (docs/backends.md):
+Real-backend checks are opt-in and never part of the default run (docs/systemone.md):
 `uv run pytest -m real_kev` (a Kev server on 127.0.0.1:8009) and
 `uv run pytest -m real_jev` (`OPENROUTER_API_KEY`). Once selected, a missing prerequisite
 is a failure, not a skip. In CI they run only in `.github/workflows/real-backends.yml`.

CHANGELOG.md

@@ -8,6 +8,15 @@ versioned separately.
 
 ## [Unreleased]
 
+### Added
+
+- Documentation site built with VitePress in `docs/` (`npm run docs:dev`,
+  `npm run docs:build`): getting started, core concepts, testing, production, backends,
+  CLI/contract/report reference, CI and architecture. New pages include a verified
+  quickstart, a CLI reference and a complete contract reference; the backends guide is
+  split into System One, HTTP and custom-backend pages. The README is now a short landing
+  page that links into these docs.
+
 ## [0.1.1] - 2026-09-25
 
 ### Fixed

CONTRIBUTING.md

@@ -87,6 +87,7 @@ does not run the paid real-backend tests.
 
 ## Adding a backend
 
-See [docs/backends.md](docs/backends.md). Built-in adapters live in
+See [docs/custom-backends.md](docs/custom-backends.md) and
+[docs/backends.md](docs/backends.md). Built-in adapters live in
 `src/decguard/backends/`; third-party ones should be separate packages registered under the
 `decguard.backends` entry-point group.