CX Documentation

The proof path now uses a native-only production engine:

This split is intentional. It lets the kernel own the production proof path without weakening extraction, verification, or manifest trust. Official repomix remains only as an optional reference oracle for parity/testing work; the older fork is historical. The reference-oracle lane now includes scripts/repomix-adapter-parity.js, which keeps adapter upgrades bound to a checked-in repomix 1.13.1 baseline for rendered XML bytes, per-file token counts, total token count, and security findings.

The planner resolves the source of truth for candidate files from version control, not from a broad filesystem walk. The priority order is:

That VCS-derived list is the master base for all later planning decisions.

The global [files] include array can extend the master base with extra paths that the VCS does not track, such as generated artefacts or build outputs. The global [files] exclude array is applied after all extensions to remove paths that should never be planned.

This shaping step changes membership in the master base, but it still does not let sections discover new files on their own.

Section include and exclude globs are classifiers, not discoverers. They operate only on the already-computed master base and can never add a file that is not already in it. This separates the question of what exists from the question of where it belongs.

At this stage the planner resolves:

This happens before rendering because the plan must be settled first.

After deriving the master list, the planner classifies the working tree into one of four states:

The unsafe_dirty guard exists because a bundle built from a dirty tracked file cannot be reliably reproduced or verified later. Two escape hatches are available: --force for local experimentation where a human is present, and --ci for automated pipelines. Both are recorded in the manifest under distinct state labels so audit tooling can distinguish human overrides from pipeline overrides.

Why this protects you: a tracked-file bundle built from a moving working tree cannot later prove what source state it represents. Refusing to proceed by default keeps the artifact contract anchored to reproducible input.

VCS state is not tracked for filesystem-fallback workspaces. Those always produce dirtyState = "clean" and vcsProvider = "none".

Sections are ordered by their priority value (descending) before overlap resolution begins. A file claimed by multiple sections is assigned to whichever section appears first in the resolved order. Sections without an explicit priority are treated as priority 0 and their relative order follows dedup.order (config position or lexical) as a stable tie-breaker.

A section may set catch_all = true instead of providing an include list. A catch-all section absorbs all files in the master list that were not claimed by any other section. It runs last in the planning pipeline, after all normal sections have consumed their files, and may still apply an exclude list to filter what it absorbs.

At most one catch-all section is permitted per configuration.

This same mechanism lets repository notes live in the normal planning model. The default docs section now includes notes/**, so durable human intent is bundled beside documentation and code-facing Markdown instead of being treated as a separate side channel.

Three overlap handling strategies are available via dedup.mode:

For rapidly evolving codebases where new files frequently match multiple sections, dedup.mode = "first-wins" with explicit priority values is preferable to accumulating static exclude paths in cx.toml. Static excludes become stale as files are renamed or moved, and they generate merge conflicts when multiple developers resolve overlaps concurrently on separate branches.

[[3-section-rendering]] === 3. Section rendering

Each section is rendered as one Repomix-compatible output file in the configured style:

cx also supplies a section-specific Repomix header through the documented output.headerText option so the file itself carries cx-oriented handover context without post-processing the generated output. That header is intentionally a presentation-layer prolog rather than part of the core format semantics: it explains what the artifact is, how to interpret logical paths, where edits belong, and which bundle contracts remain authoritative.

This yields more semantic fluency for humans and AI consumers without relaxing the deterministic contract:

The renderer also reports output token counts. If the adapter supports exact span capture, cx records absolute outputStartLine and outputEndLine values for each packed text file in XML, Markdown, and plain sections. Those spans are the primary lookup path for those text formats. JSON uses direct object lookup instead of span metadata, and JSON-only bundles may omit spans entirely.

[[4-shared-handover]] === 4. Shared handover

cx bundle writes a kernel-rendered shared handover file alongside the section outputs. The handover is meant to travel with the section files when multiple outputs are handed over together, so the shared context is externalized without breaking the self-contained section files.

For XML-style bundles, that handover intentionally stays mostly plain text. Rare tags such as <section_inventory> and <recent_repository_history> act as semantic anchors for LLMs and operators rather than as a full XML document contract.

[[5-manifest-build]] === 5. Manifest build

cx writes a canonical manifest that records:

The manifest is not just a report. It is the contract other commands operate against.

[[6-lock-file-and-checksums]] === 6. Lock file and checksums

cx bundle also writes:

[[7-post-build-consumers]] === 7. Post-build consumers

After bundling, other commands use the recorded state:

When merging two configurations (base and override), cx applies these rules:

Every merge operation returns a conflict list documenting:

This explicit logging lets operators audit configuration inheritance chains and detect unintended changes that silent merges would hide.

Configuration is not arbitrary application state. Changes to section definitions, file patterns, or dedup rules affect the reproducibility of a bundle. By making conflicts visible rather than silent, cx ensures that operational decisions about configuration are explicit and auditable.