CX Documentation

When you extract bundle contents, treat intact and copied outputs as the ordinary safe path.

If extraction reports degraded, stop and decide whether you need approximate human review or deterministic machine-safe recovery:

Why this protects you: degraded extraction means the recovered packed content no longer matches the manifest contract, so line coordinates and file identity may no longer be trustworthy enough for safe automation.

For the full failure model, recovery statuses, and detailed examples, see Extraction Safety.

cx bundle --force and cx bundle --ci are audited overrides. They allow a bundle to be materialized from tracked-file drift only when the operator has chosen that provenance explicitly, and the manifest records forced_dirty or ci_dirty for downstream review. --force also keeps the command running after note-validation errors, so the operator can inspect the resulting artifact and the emitted diagnostics together. Scanner findings remain fatal.

See Audited Overrides before using either flag in release or CI workflows.

Use the repository-local make targets for day-to-day development:

make certify runs everything make verify does, then performs a clean double-build reproducibility check: the dist/ tree is hashed, wiped, rebuilt, and hashed again. The two hash sets must match exactly. This mirrors the CI reproducibility job so the release gate is exercisable locally without pushing.

Use cx commands for repository planning, bundle generation, verification, and live MCP work.

cx init now writes a generated workspace-aware Makefile, .editorconfig, cx-mcp.toml, cx.toml, .mcp.json, .vscode/mcp.json, and local agent settings in .claude/settings.json and .codex/settings.json in addition to notes/. The generated cx-mcp.toml is a minimal diff to cx.toml and serves as the MCP overlay for the workspace root. The Makefile selects a language-specific template when it sees common workspace markers for Rust, Go, JavaScript/TypeScript, Python, Java, Elixir, Julia, Crystal, or Zig, and otherwise falls back to the base template.

For the TypeScript template, the generated Makefile uses lockfile-first package-manager selection (bun.lock*, pnpm-lock.yaml, yarn.lock, then package-lock.json / npm-shrinkwrap.json) and keeps install separate from build. The normalized local targets are install, build, test, check, lint, verify, certify, clean, and notes. lint and check skip with a clear message when the corresponding package scripts are absent, and certify falls back to verify unless the workspace defines a stricter package-manager certify script. The generated cx-mcp.toml is the source-oriented authoring overlay and includes src/, package.json, tsconfig*.json, and README.md while excluding node_modules/, dist/**, and common cache or coverage directories. A companion cx-mcp-build.toml is generated for compiled-output inspection. Adjust the authoring and build overlays independently if your workspace uses a different layout.

The cross-template capability matrix, generated file contract, and support levels are documented in Init Template Contract.

cx init checks each generated target individually. It preserves existing files by default and creates any missing init artifacts; use --force to overwrite existing generated files.

Use --template to explicitly choose an init template by environment:

List supported templates with:

When --template is omitted, cx init autodetects the workspace environment from files like package.json, go.mod, pyproject.toml, pom.xml, and Cargo.toml.

cx mcp prefers a colocated cx-mcp.toml overlay. If that file is present, it is the default MCP config for the workspace; if it is missing, cx falls back to the baseline cx.toml configuration. The MCP surface now includes live bundle planning plus note reading, search, creation, update, rename, delete, and note-graph inspection tools in addition to workspace file browsing.

cx docs export writes deterministic markdown renderings of the Antora assemblies described by the active playbook so operators and downstream LLM workflows can inspect the final documentation content directly instead of inferring it from source AsciiDoc files alone. MultiMarkdown is the default export format for this command. The export rewrites Antora-style cross references into review-friendly links between the emitted markdown files and reports unresolved review-link destinations such as xref: links, module-qualified Antora HTML targets, or .adoc destinations. Use --playbook when the docs are driven by a playbook other than the default antora-playbook.yml at the source root, and use --root-level to switch between a single combined assembly (0) and one export per assembly or module (1, the default). JSON mode reports structured diagnostics when the export is blocked so CI and operators can see the exact assembly and unresolved destinations instead of only receiving a generic failure. Use --log-output <path> when you want Antora export logs written to a file instead of stderr. This overrides docs.log_output from cx.toml. Empty log files are deleted automatically after the export, so a log path only remains on disk when it captured actual output.

cx bundle --include-doc-exports reuses that same export path and stages the generated Antora assemblies under docs.target_dir/ inside the bundle. The default is {project}-docs-exports, and you can configure it the same way as assets.target_dir in cx.toml. The bundle manifest records those files as .mmd.txt artifacts in derivedReviewExports so they are discoverable, checksum-covered, and still clearly labeled as derived review material rather than proof-path section outputs. cx inspect --derived-review-exports --json and cx verify --json also summarize the derived review exports, including unresolved review-link diagnostics for already bundled artifacts. When bundled docs export logging is enabled, the log is written to antora-export.log.txt in the bundle root. Empty bundled log files are removed automatically and are not recorded as bundle content or handover inventory.

Use cx mcp catalog --json when you need only the machine-readable MCP tool contract. It exposes the registered tool set with stable name, capability, and stability fields plus summary counts, without mixing in profile resolution or audit state.

For concrete integration examples and per-IDE snippets (VS Code/Cline, Roo Code, Cursor, Claude Desktop), see the Agent Integration Guide.

Use this sequence when you are connecting an agent or IDE to a live workspace:

Keep the everyday operator rule simple:

If an agent cannot see the right files, verify these before debugging anything deeper:

Repository-local make shortcuts keep the developer loop compact:

The make targets are wrappers around the corresponding Bun scripts. Use them for local ergonomics; use cx when you are working with bundle planning, verification, extraction, or MCP sessions.

The native MCP server exposes file-based list, grep, and read tools over the workspace scope. It also exposes inspect, bundle, doctor_mcp, and doctor_workflow tools for live planning, plus note-native notes_read, notes_search, notes_new, notes_update, notes_rename, notes_delete, notes_list, notes_backlinks, notes_orphans, notes_code_links, and notes_links tools over the notes corpus. Use list to enumerate visible files, grep to search their contents, and read to inspect a specific file with optional line anchors without switching back to the packaging workflow.

Example note search:

CLI and MCP note commands side by side:

Use the CLI for direct on-disk note lifecycle operations. Use MCP when the agent needs live search, reads, updates, or graph inspection inside an active workspace session.

cx docs compile --profile architecture|manual|onboarding is the repository-owned promotion path from stable notes into generated Antora pages. Use note graph tools to validate and inspect note evidence before running docs compilation.