Docs Web Source-Of-Truth Policy

This policy defines how the Docusaurus website consumes repository documentation without creating a second committed documentation truth.

Ownership Model

.docs is the canonical authored source for:

• architecture decisions and platform specs
• package guides
• developer happy paths
• verification and release governance
• security and supply-chain rules
• agent-native capability documentation
• Cloudflare Pages and Storybook deployment runbooks

apps/docs is the canonical source for:

• Docusaurus configuration
• homepage and website chrome
• sidebar and navbar presentation
• generated content preparation scripts
• static headers and assets
• API reference placeholder and future generator contract

Root files such as README.md, SECURITY.md, CHANGELOG.md, and .github/CODEOWNERS remain root-owned repository operation files. The docs site may link to them, but it must not copy them as a second canonical source.

Generated View

The v0 website uses a deterministic generated view:

1. authored Markdown remains in .docs
2. apps/docs/scripts/prepare-content.mjs copies selected .docs files into apps/docs/.generated/docs
3. Docusaurus reads apps/docs/.generated/docs
4. apps/docs/.generated is ignored and never committed

This keeps the Docusaurus app self-contained at build time while preserving .docs as the source of truth.

Publish Classification

Documentation inputs are classified as:

• publish: public v0 docs rendered by Docusaurus
• link: external/root repository files linked from the site
• generate-later: future generated outputs such as API reference pages
• omit: internal evidence or raw capture material that should not appear in navigation

Current v0 classification:

Source	Classification	Website treatment
.docs/README.md	publish	Docs index at /
.docs/architecture/docs-web-decisions.md	publish	Architecture section
.docs/architecture/docs-web-ia.md	publish	Docs web section
.docs/architecture/docs-web-source-policy.md	publish	Architecture section
.docs/architecture/docs-web-api-reference-runway.md	publish	Docs web section
.docs/architecture/workspace-composition.md	publish	Architecture section
.docs/architecture/workspace-composition-decisions.md	publish	Architecture section
.docs/architecture/workspace-composition-kernel.md	publish	Architecture section
.docs/architecture/workspace-composition-module-authoring.md	publish	Architecture section
.docs/architecture/workspace-composition-namespace-diagnostics-versioning.md	publish	Architecture section
.docs/architecture/workspace-composition-react-render-runtime.md	publish	Architecture section
.docs/architecture/workspace-composition-security-trust.md	publish	Architecture section
.docs/architecture/workspace-composition-surface-migration-map.md	publish	Architecture section
.docs/architecture/workspace-composition-v0-roadmap.md	publish	Architecture section
.docs/architecture/workspace-composition-linear-backlog.md	omit	Linear planning source stays out of public navigation
.docs/guides/*.md	publish	Guides section
.docs/packages/*.md	publish	Packages section
.docs/security/*.md	publish	Security section
.docs/ops/*.md	publish	Operations section
.docs/agent-native/*.md	publish	Agent-native section
.docs/verification.md	publish	Verification section
.docs/release-governance.md	publish	Release section
README.md	link	Linked as repository overview
SECURITY.md	link	Linked as vulnerability reporting policy
CHANGELOG.md	link	Linked as repository changelog
.github/CODEOWNERS	link	Linked as ownership routing
projects/*/protocol-captures/**	omit	Raw evidence stays out of docs navigation
package dist/**/*.d.ts	generate-later	Future API reference input
package exports maps	generate-later	Future API reference input

Editing Rule

When changing package, architecture, release, verification, or security content, edit .docs first. The generated Docusaurus view is rebuilt by the docs app and must not be hand-edited.

When changing website presentation, edit apps/docs.

When changing Cloudflare Pages or Storybook deployment runbooks, edit .docs/ops.

When changing root repository operations, edit the root file and link to it from docs if needed.

Duplication Rules

Allowed:

• short summaries on landing pages
• links from apps/docs pages to canonical docs
• generated copies under ignored apps/docs/.generated
• website-specific deployment runbooks in .docs/ops

Forbidden:

• committed hand-maintained copies of any .docs authored content under apps/docs
• manually maintained package API pages before the API generator exists
• duplicated release checklists that compete with .docs/release-governance.md
• duplicated security policy content that competes with SECURITY.md or .docs/security/supply-chain.md

Migration Path

v0 keeps .docs canonical and adds the Docusaurus website as a generated presentation layer.

A later move to apps/docs as the authored source is allowed only if the same change:

• updates this policy
• reopens DOCS-ADR-006 and DOCS-ADR-008 through the decision-register reopen process
• removes or redirects the replaced .docs files
• updates verification scripts
• updates package and root docs links

Verification

Implementation must verify:

• generated docs can be rebuilt from .docs
• apps/docs/.generated is ignored
• Docusaurus build succeeds from generated content
• docs navigation does not include raw protocol capture evidence
• Storybook and API reference are linked as separate or future surfaces, not copied content