Docs Governance

What It Is

The docs platform is a docs-as-code system with schema-validated frontmatter, required section headings for internal system docs, generated manifests, and CI checks for the phase-one platforms.

How It Works

Every page lives in Websites/docs and uses the same metadata contract. Public and internal builds are generated from the same source. CI validates content shape and requires paired docs changes for selected system directories.

Interfaces

• content schema: Websites/docs/src/content/config.ts
• manifest generator: Websites/docs/scripts/write-manifest.mjs
• validation rules: Websites/docs/scripts/validate-docs.mjs
• coverage gate: Websites/docs/scripts/check-doc-coverage.mjs
• workflow: .github/workflows/docs-platform.yml

Data Flow

1. Contributors update implementation and docs together.
2. Validation checks metadata and required headings.
3. Public and internal builds are generated separately.
4. A machine-readable manifest is written for the built target.

Failure Modes

• doc metadata is missing or invalid
• system IDs in frontmatter do not exist in the registry
• internal system docs omit required sections
• code changes land in phase-one repos without docs changes

Debugging

• run npm run validate from Websites/docs
• run npm run build:public and npm run build:internal
• inspect dist/public/manifest.json and dist/internal/manifest.json
• confirm the changed file list passed to the coverage gate matches the current branch diff

Change Log / Verification

• Initial governance rules established on 2026-03-29
• Scope is intentionally narrow to the phase-one systems until wider migration lands