The Living Vault: Eliminating Split-Brain Documentation Drift with SSoT CMS#

In traditional software companies, documentation is a static artifact that lives in disconnected tools (Notion, Confluence, Google Docs). Within weeks of launch, engineering reality accelerates while written architecture becomes obsolete.

This creates "Split-Brain Drift": developers read stale documents, marketing makes inaccurate claims, and AI coding agents hallucinate deprecated APIs because their grounding documentation contradicts production code.

flowchart LR
    subgraph VaultSSoT ["1. Living Vault SSoT (gsi/vault/public)"]
        Handbook["Handbook Essays (*.md)"]
        Dispatches["Research Dispatches (*.md)"]
        Architecture["System Architecture Specs"]
    end

    subgraph Compiler ["2. nomos-vault-cms Compiler Engine"]
        Banner["SSoT Provenance Banner Injection"]
        Audit["SHA-256 Byte Parity Auditor"]
        SearchGen["Compile-Time Search Indexer (Cmd+K)"]
    end

    subgraph Membranes ["3. Multi-Portal Production Mirrors"]
        SophiaWeb["sophialabs.ca (/handbook, /dispatches)"]
        GantlettWeb["gantlett.io (/handbook, /advisory)"]
        DocsHub["sophialabs.ca/docs/nomos/ (VitePress)"]
    end

    VaultSSoT -->|"Single Source of Truth"| Compiler
    Compiler -->|"100% SHA-256 Byte Parity"| Membranes

🏛️ Documentation as Compiled Code#

The Living Vault replaces ad-hoc wikis by elevating documentation to first-class, machine-compiled software assets:

1. Pure Markdown SSoT (vault/public/)#

Every handbook chapter, benchmark dispatch, and architectural invariant is authored in clean, human-readable Markdown with standard YAML frontmatter in `vault-intent/public`.

2. Compiled Mirroring (nomos intent)#

During nomos intent compile (and automatically enforced in Gate 1 of nomos release ship):

• Source markdown files are parsed at the AST level.
• Immutable provenance banners (<!-- ⚠️ DO NOT EDIT DIRECTLY. MIRRORED FROM VAULT SSoT... -->) are injected without breaking frontmatter parsers.
• Files are mirrored atomically to portal content stores (src/lib/handbook/content/ and src/lib/dispatches/content/).

3. Machine-Enforced SHA-256 Byte Parity#

The SSoT Parity Gate (nomos intent check / npm run check:intent-parity) calculates clean SHA-256 checksums across every file. If a developer or rogue script edits a mirrored portal file directly without updating the Living Vault, the build is immediately halted.

⚡ Zero-Config Continuous Publishing#

Because the public web membrane uses Vite dynamic glob imports (import.meta.glob('./content/*.md')):

• Dropping a new .md file into vault/public/handbook/ auto-generates its SSR route (/handbook/[slug]).
• The article is immediately indexed into the client-side Cmd+K Command Palette.
• The route is automatically exposed to search engine crawlers via sitemap.xml.
• Documentation drift is mathematically impossible.