CX Documentation

cx 0.4.0 marks a transition from a Repomix-adapter system to a kernel-owned architecture.

Agent-driven note mutation is a full review loop, not a single write operation: inspect through MCP first, enable mutation intentionally, write durable notes, then run cx notes check and graph review before trusting the updated cognition…​

cx-cli provides three complementary workflows: Bundle (immutable snapshots), MCP (live interactive), and Notes (durable knowledge). Each serves a different use case and has distinct policy guarantees.

Antora and AsciiDoctor now define the curated documentation surface through a standard Antora component rooted at docs/, with docs/antora.yml, docs/modules/ROOT/pages/, and a separate local UI bundle under docs/ui/, not every text artifa…​

arc42 fits the architecture and contract layer of cx well, but it should be used as the spine of the curated architecture corpus rather than as the structure for the whole repository.

cx restoration ensures that files extracted from a bundle are exactly as they were captured during the planning phase, preventing degraded or corrupted files from entering a project.

The current term "bundle index" is now too narrow because the file already acts as a shared handover artifact for both humans and agents, not just a lookup-oriented section listing.

cx uses SHA-256 sidecars and manifest-level checksums to ensure the integrity of a bundle from the moment it is created until it is extracted or verified.

The bundle to verify to extract path is a contract, not just a convenient command sequence.

cx needs a single front-door explanation that tells operators which surface to use before they learn the deeper internals.

The CLI command lifecycle in cx is built on yargs and a centralized command dispatch model.

cx configuration follows a deterministic loading and inheritance pipeline that enables colocated overlays (like cx-mcp.toml) without repeating the entire cx.toml baseline.

Configuration files often inherit from parent configs: Organization-level defaults → Project-specific overrides System-wide settings → User-local tweaks Pipeline defaults → Job-specific exceptions

The CX Constitution defines the non-negotiable rules of the system.

cx must enforce a layered source-of-truth model instead of treating all repository text as equally authoritative.

Obsidian is a human navigation lens for the note graph, not the authority for repository semantics.

The CX architecture is built upon a triad specifically designed for operational bundling rather than just exploratory context generation. The triad consists of:

make test is the fast local feedback loop, make verify is the normal pre-merge gate, and make release VERSION=vX.Y.Z is the repository-local two-phase release wizard. Keeping those roles separate keeps the common command quick while maki…​

Provenance becomes convincing when shown across time instead of as a static label.

The Friday-to-Monday path is a workflow contract for turning live investigation into a trusted handoff.

The CI workflow runs on every branch push and on pull requests, but not on v* tag pushes. Tag finalization belongs to the release workflow instead of the main CI pipeline. Pages publishes the unified /schemas/ and /coverage/ site from su…​

The system must stabilize internal interfaces before adding plugins.

The system enforces a strict separation between kernel and extensions.

The layered truth model keeps repository cognition explicit: notes preserve intent truth, specs preserve executable rule truth, code preserves implementation truth, tests preserve behavioral truth, and docs preserve communication truth.

Vitest UI is unusually valuable for MCP performance investigation because the MCP stack is registration-heavy and spread across src/cli/commands/mcp.ts, src/mcp/server.ts, src/mcp/policy.ts, src/mcp/workspace.ts, and the tool-registratio…​

When reviewing repository notes, use manifest-first selection and live MCP note tools instead of opening every Markdown file.

The MCP read path must remain available as the primary live exploration workflow.

cx implements the Model Context Protocol (MCP) over a standard input/output (stdio) transport layer.

The MCP test and debug cockpit is a dedicated Vitest UI entrypoint for the MCP-heavy suite, not a generic replacement for the Bun lanes. It exists so operators can rerun MCP failures interactively, inspect coverage inside the UI, and tra…​

The MCP Vitest UI troubleshooting flow is intentionally small: use the broad MCP cockpit when you need coverage and import visibility across the MCP boundary, and switch to the adversarial cockpit when the failure is explicitly about sta…​

cx uses a unified deterministic identity model but bifurcates operation into two distinct paths: Track B generates hypotheses against live state, while Track A generates proof that can survive review, CI, and handoff.

Parallel rendering improves continuous integration throughput without changing deterministic output.

This plan outlines the steps to bring the notes/ directory into full alignment with the project’s complexity and current implementation.

cx enforces a strict repository boundary during bundle planning and live MCP sessions. This prevents sensitive files from leaking into the agent context or the final bundle.

cx-cli tools are organized into four stability tiers: STABLE, BETA, EXPERIMENTAL, and INTERNAL. This model lets operators understand which tools have locked APIs and which may evolve, and it now applies explicitly to the …​

The proof path is kernel-owned so render identity, verification, and extraction safety remain auditable even as helpers, plugins, and migration scaffolding evolve around the kernel.

The render kernel defines the proof-path behavior of cx.

cx strictly isolates its rendering backend using the Repomix Adapter Boundary. The system does not shell out to Repomix via the OS; instead, it uses a narrow in-process module boundary to maintain synchronous, deterministic control over …​

Repomix was a temporary compatibility layer during the render-kernel migration, and that decommissioning work is now closed for v0.4.

The notes graph is the repository cognition layer: durable reasoning that agents and humans can query safely only if the graph keeps strong signal-to-noise, summary-first routing, and bounded note size.

Safe note mutation is a two-part workflow: explicit authority first, graph review second.

Safe note mutation is a contract because cognition changes must stay reviewable and bounded.

cx uses a precise ownership model to distribute files from the master list into named sections. A conflict arises when two or more sections match the same file path.

The original render span computation relied on heuristic parsing of rendered output: Markers (XML tags, Markdown headings, plain-text delimiters) were parsed post-render Span calculations were indirect inference, not direct observati…​

cx stays trustworthy only if cognition quality, boundary rules, and trust labels remain explicit. A parseable note is not automatically reliable knowledge, Track B exploration is not automatically Track A proof, and agent output is not a…​

The suite had excellent real-world coverage but too much unit-level dependence on filesystem setup. That made core logic tests slower and more fragile than they needed to be.

cx models trust as a spectrum rather than a binary state.

cx-cli release management should separate preparation from publication. develop prepares the versioned candidate and absorbs release-fix commits until the full CI and release-assurance surface is green. The release tag then finalizes tha…​

Operator workflows should be treated as contracts when later automation depends on them.