Curated Documentation Surface

CX Documentation

Kernel-owned proof path, live MCP workspace surface, and durable cognition notes.

cx is documented as four cooperating surfaces:

  • native proof path: bundle, validate, verify, extract

  • live workspace path: mcp

  • durable cognition path: notes

  • adapter/oracle path: diagnostics and parity only

Use this page for its local concern first. Return to Documentation Index when you need the broader map.

Track A produces proof-grade artifacts such as bundles, manifests, hashes, and verification results. Track B produces hypotheses, exploratory reasoning, and live workspace investigation state. Use the proof path when later humans or CI must trust the output. Use the live path when the work is still moving.

Trust remains asymmetric across the system:

  • source tree: trusted

  • notes: conditional

  • agent output: untrusted until verified

  • bundle: trusted

This page recaps only the local boundary. Use Cross-cutting Concepts when you need the full canonical model.

This is the curated front door for the cx documentation surface. The canonical docs live here in the Antora component across docs/modules/onboarding/pages/, docs/modules/manual/pages/, docs/modules/architecture/pages/, and the shared docs/modules/ROOT/pages/ reference surface.

Use the published Antora site for curated navigation, breadcrumbs, architecture structure, and workflow entrypoints. Use this directory when you need the repository-local Markdown companions.

Schema and coverage publishing policy lives in Release Checklist, which keeps the public GitHub Pages host and release mirror aligned with the checked-in schemas/ files and the successful main CI proof path. Developer command conventions for make test, make verify, and make release live in the repository notes and the operator manual. The MCP surface has a documented stable subset, but the broader integration layer still evolves conservatively. Use MCP Tool Stability Tiers for the stable subset and Agent Integration for client-facing setup guidance.

What Changed In 0.4.0

cx now explicitly operates as three primary cooperating surfaces:

  • immutable snapshots with cx bundle

  • live agent protocol with cx mcp

  • durable knowledge with cx notes

Track B generates hypotheses. Track A generates proofs. Notes preserve durable reasoning between them.

The adapter/oracle seam remains outside the shipped proof path. It exists for diagnostics, parity visibility, and reference-oracle comparison rather than ordinary operator workflows.

0.4.0 also makes three release-level changes explicit:

  • Vitest coverage is now the authoritative coverage-reporting lane for release assurance.

  • The MCP surface has a stable subset, but the broader integration layer still evolves conservatively.

  • Notes governance, cognition scoring, contradiction checks, and trust propagation are part of the operating contract rather than incidental implementation details.

See:

Start Here

Use the smallest core set first:

  • Run cx mcp first if you want the shortest onboarding path: see value now, learn the model later.

  • System Map - compressed front door plus contributor subsystem map

  • Operating Modes - choose between live MCP help, reproducible bundles, and durable notes

  • Mental Model - canonical semantics, Track A vs B, MCP policy tiers, and artifact lifecycle

  • System Contracts - cognition contract, boundary contract, and trust propagation model

  • Manual Overview - operator path, assurance ladder, and workflow map

Reference By Concern

Workflow Set

  • Friday to Monday - the primary end-to-end workflow from live investigation to verified handoff

  • Safe Note Mutation

    • the policy boundary plus operator and agent viewpoints for trusted local note mutation

Read the Friday-to-Monday workflow first. The note-mutation workflow is a narrower special case, not a parallel onboarding path.

Historical Material

Use these when upgrading or reviewing release history. They are not part of the core operator front door.

The allowed front-door docs are intentionally small. See GOVERNANCE.md for the docs surface budget and the reference-only rule for everything else.

Trust shorthand for the whole docs set:

  • Source tree: trusted

  • Notes: conditional

  • Agent output: untrusted until verified

  • Bundle: trusted

Hierarchy

  • Mental Model owns semantics.

  • Operating Modes maps those semantics to operator choices.

  • Workflows shows execution examples.

  • Agent documents the integration layer.

  • docs/ publishes the curated documentation site and arc42-based architecture spine.

Everything else should reference those layers instead of redefining them.