Documentation guide

Status and authority

The documentation site presents this experimental proof of concept; it does not turn the repository into a mature or production-ready product. Constructive criticism, independent reproduction, counterexamples, and corrections are expected.

The site publishes the repository's canonical Markdown directly. It is not an authority for experimental behavior. poc/contract.md is the normative human-readable boundary; the executable definition, query, and independent finite oracles encode its acceptance obligations. They must agree. A discrepancy is a defect, and the contract remains authoritative until an explicit design decision changes it. Explanatory documents and VitePress presentation are lower authority and cannot reinterpret that boundary.

Local workflow

Documentation tooling requires Node.js >=22.12 <23. It is not required to run the POC. From the repository root:

npm ci --ignore-scripts
npm run docs:check
npm run docs:dev

docs:check validates machine-owned facts and selected US-English terminology, builds the static site with dead-link failures enabled, and inspects the publishable output. docs:dev starts the local authoring server after those reproducibility checks have established the dependency tree.

The exact VitePress 2.0.0-alpha.19 prerelease is intentional. At adoption on 2026-08-15, the official guide targeted the preview line and the locked dependency tree passed npm audit. Its risk is isolated to the static documentation boundary. Exact pinning and the complete site build prevent silent minor or prerelease upgrades.

Source ownership

Subject	Canonical source
Supported claim and nonclaims	poc/contract.md
Modes, scales, limits, and exact source inventory	poc/definition.json
Static, runtime, and fusion expectations	poc/oracles/*.json
Read-only query behavior	poc/query/query-v1.json
Component and trust boundaries	ARCHITECTURE.md
Host and runtime compatibility	COMPATIBILITY.md
Retained files and schemas	poc/ARTIFACTS.md
Public-command diagnosis	TROUBLESHOOTING.md
Site navigation and metadata	.vitepress/config.mts
Site-only presentation	.vitepress/theme/
Documentation validation	docs/scripts/

Do not maintain a second prose copy of a canonical claim. Navigation should link to its source, and explanatory text should name the owning machine source when a value can drift.

Review rules

• Keep the experimental status and nonclaims visible.
• Publish poc.sh as the only supported execution path.
• Write all authored content, labels, alternative text, comments, and commit messages in US English.
• Preserve working relative links in both GitHub and VitePress.
• Review Markdown HTML and Vue components as executable build input.
• Keep generated output, caches, dependencies, and local preview files out of Git.
• Keep Node, npm, VitePress, Vue, PlantUML, and site output outside the Docker context and every POC inventory.
• Add no analytics, remote fonts, remote scripts, hosted search, or remote diagram renderer without an explicit need and trust review.

Architecture diagrams

Editable PlantUML sources live in docs/diagrams/source/; reviewed SVG output lives in docs/diagrams/rendered/. The committed .plantuml.yml records the authoring boundary: PlantUML 1.2026.6, SVG output, Graphviz dot, the allowlist security profile, disabled remote includes, and disabled embedded source metadata. Diagram rendering is an authoring operation. PlantUML, Java, and Graphviz are not part of the POC image, VitePress runtime, or GitHub Pages deployment.

Every diagram change must preserve these properties:

• validate the changed source under the allowlist profile before rendering;
• render locally with the pinned PlantUML version and commit the source and SVG together;
• keep one bounded question per diagram and use explicit aliases for long labels;
• use an ordinary semantic figure, nonempty image alternative text, and a meaningful caption in the canonical Markdown; and
• run npm run docs:check, which verifies diagram membership, retained hashes, SVG safety, viewer geometry, and the generated site.

The published site progressively adds a same-origin, dependency-free full-screen viewer. The canonical image, alternative text, and caption remain usable on GitHub and when JavaScript is unavailable. The viewer displays the committed SVG through an image element; it does not parse SVG markup, contact a remote renderer, or execute PlantUML in the browser.

Publication boundary

Pull requests and pushes to main run the locked documentation checks and build. Only a push to main uploads .vitepress/dist/ as the GitHub Pages artifact. The deployment waits for both the complete POC gate and the documentation gate, then runs in a serialized job that refuses to deploy if its revision is no longer the head of main. That job can read the current repository reference; its only write permissions are Pages and the identity token. It does not check out source, install dependencies, or execute project build or runtime code. The site verifier rejects unexpected routes, altered diagram bytes, symbolic links, and sensitive or source-only file types before upload. The build job has only read access to repository contents. Pages configuration and metadata access remain inside the main-only deployment boundary.

Repository settings remain external evidence. The owner must select GitHub Actions as the Pages source, restrict the github-pages environment to main, require HTTPS, and preserve the repository's review policy before relying on the published URL. If the repository is private at activation time, the owner must also confirm an eligible GitHub plan and the intended site visibility. A Pages site can be public even when its source repository is private.