Curated Documentation Surface

CX Documentation

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

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.

Use this page when you need the canonical operator workflows in one place. These workflows are part of the manual surface rather than a separate doc class.

See Operating Modes for the mode chooser and Mental Model for the canonical semantics that sit underneath the workflows.

Friday To Monday Workflow

This is the canonical end-to-end workflow for a team that investigates with MCP on Friday night and trusts a promotable artifact on Monday morning.

Friday Night: Dirty Local Code, Fast AI Help

It is late on Friday. The developer has local tracked changes that are not ready to commit, but still needs fast AI help on the live code.

That is a Track B problem, not a clean promotion problem.

  1. Confirm the recommended mode:

    cx doctor workflow --task "understand the change, update notes, and prepare a handoff bundle"

  2. Start the live MCP server:

    cx mcp

  3. Typical MCP call sequence:

    doctor_mcp()
inspect()
notes_search(query="dirty state", limit=5)
notes_read(id="20260413153522")
read(path="src/cli/commands/bundle.ts", startLine=230, endLine=320)
bundle()

What happens here:

  • doctor_mcp confirms the live workspace boundary.

  • inspect and bundle() preview the plan without writing artifact files.

  • notes_search and notes_read reuse durable reasoning before the agent broad-scans the workspace.

  • read and search tools keep the work grounded in the current repository state.

If the developer intentionally enables note mutation in a trusted local session, that workflow belongs in Safe Note Mutation, not in the default Friday-night exploratory flow.

Why this protects you: the developer gets live reasoning help without pretending the current checkout is already a clean, promotable artifact.

Friday Night Closeout: Optional Local Review Bundle

Sometimes the developer still wants a temporary local snapshot for review, even though the checkout is dirty.

That is the exceptional case for a local override:

cx bundle --config cx.toml --force

This is acceptable only as a local review aid. The manifest records forced_dirty so nobody has to guess later whether the bundle came from a clean source state.

Why this protects you: the override does not erase the provenance problem. It records it. A local operator can still inspect the snapshot, but Monday automation does not have to mistake it for a clean promotion artifact.

Friday Closeout: Freeze The Real Handoff

Once the code is committed or the working tree is otherwise returned to a promotable state, switch to Track A and write the actual handoff:

cx inspect --config cx.toml --token-breakdown
cx bundle --config cx.toml
cx verify dist/demo-bundle --against . --config cx.toml

Why this protects you: Friday’s live workspace is still moving. The bundle is the moment where cx freezes that state into something Monday can verify instead of merely trust.

What Travels Across The Weekend

The handoff is the bundle directory, not the MCP session:

  • section outputs

  • manifest

  • lock file

  • checksum sidecar

  • copied assets

The notes you updated on Friday can also be included in the bundle plan, which keeps reasoning and artifact together.

Trust still stays asymmetric across the weekend:

  • source tree: trusted

  • notes: conditional

  • agent output: untrusted until verified

  • bundle: trusted

Monday Morning: CI Trusts Only The Clean Path

On Monday, CI should trust only the clean, promotable path. It should validate or verify the artifact built from committed source state, not a forced_dirty local convenience bundle.

Start with structure and integrity:

cx validate dist/demo-bundle
cx verify dist/demo-bundle --config cx.toml

If you have the expected source tree available, compare against it directly:

cx verify dist/demo-bundle --against /path/to/checkout --config cx.toml

If you need files back out for review or downstream work:

cx extract dist/demo-bundle --to /tmp/review --verify

Why this protects you: Monday’s runner should prove that the artifact still matches Friday’s bundle contract. Validation checks that the structure exists. Verification checks that the artifact set and, optionally, the source tree still agree. Extraction stays behind the same manifest and hash guardrails.

Failure Interpretation

  • Dirty-state refusal on Friday means the workspace was not stable enough to freeze as a promotable artifact.

  • forced_dirty on Friday means the bundle was only suitable for explicit local review, not for clean CI trust.

  • Checksum failure on Monday means the artifact set in hand is no longer provably the one written on Friday.

  • Degraded extraction means the bundle can no longer reconstruct text deterministically enough for safe automation.

Those failures are not friction for its own sake. They are the mechanisms that keep Friday intent queryable and safe on Monday.

Safe Note Mutation

This workflow explains how note mutation is intentionally denied by default and how a trusted local developer or agent session enables it safely. The generated cx.toml baseline now includes mcp.enable_mutation = true so the operational control is primarily the MCP policy setting.

See Agent Operating Model and Agent Integration Guide for the integration-layer view.

Step 1: Start In Default MCP Mode

The normal interactive starting point is an MCP session that can read, observe, and plan:

[mcp]
policy = "default"

In that mode, the agent can:

  • read source files

  • inspect bundle plans

  • search notes

  • read existing notes

In that mode, the agent cannot:

  • create notes

  • update notes

  • rename notes

  • delete notes

Why this stops you: a default MCP session is for live reasoning, not silent repository mutation. The denial protects the boundary between "the agent may inspect" and "the agent may change durable knowledge."

Step 2: See The Denial For What It Is

If the agent tries to call a note-mutation tool in default mode, that denial is expected:

notes_update(id="20260419090000", body="Refined conclusion.")

The correct response is not to weaken policy casually. First confirm whether this session is actually trusted to change the note graph.

Step 3: Intentionally Enable Mutation In A Trusted Local Session

When a local developer explicitly wants the agent to maintain notes, enable mutation in the MCP profile:

[mcp]
policy = "unrestricted"
enable_mutation = true

Then verify the effective profile:

cx doctor mcp --config cx.toml

Why this protects you: mutation authority becomes an explicit operator decision in versioned configuration instead of an accidental side effect of starting an MCP session.

Step 4: Mutate Notes Deliberately

Operator View

Once mutation is intentionally enabled, the operator can allow the agent to create or revise notes:

notes_new(title="Extraction Guardrail", body="Degraded extraction must stay opt-in because coordinate trust is part of the bundle contract.", tags=["safety", "workflow"])
notes_update(id="20260419090000", body="Expanded the note with Monday-morning verification guidance.", tags=["workflow", "handoff"])

Agent View

From the agent point of view, the safe sequence is:

cx mcp

Then inspect live context before writing durable knowledge:

doctor_mcp()
notes_search(query="dirty state", limit=5)
notes_read(id="20260413153522")
read(path="src/cli/commands/bundle.ts", startLine=220, endLine=280)
inspect()

Only after that review should the mutation happen:

notes_new(
  title="Dirty State Review Loop",
  body="Dirty-state refusal protects the proof path by stopping Track A from claiming artifact certainty while tracked code is still moving.\n\n## What\n\nTrack A must refuse a promotable bundle when tracked files are dirty.\n\n## Why\n\nReview and CI need proof-grade source identity, not a moving target.\n\n## How\n\nUse MCP for live reasoning first, then return to a clean tree before bundling.\n\n## Links\n\n- [[Friday Night Monday Morning Provenance]] - shows the time-separated handoff case.\n- src/cli/commands/bundle.ts - dirty-state enforcement path.",
  tags=["workflow", "provenance", "safety"]
)
notes_update(
  id="20260419153000",
  body="The repository cognition layer depends on summary-first routing, explicit what/why/how structure, and review after mutation.\n\n## What\n\nThe notes graph is durable reasoning for humans and agents.\n\n## Why\n\nLow-signal notes degrade routing quality and CI trust.\n\n## How\n\nRequire summaries, keep notes atomic, and run governance checks after mutation.\n\n## Links\n\n- [[Safe Note Mutation Workflow]] - policy boundary and audit loop.\n- src/notes/validate.ts - governance enforcement.",
  tags=["notes", "quality", "workflow"]
)

Why this protects you: the agent reads the current code, prior notes, and the bundle plan before proposing new durable reasoning.

Step 5: Review The Result With Graph And Audit Commands

After note mutation, review the graph instead of assuming the changes fit cleanly:

cx notes links
cx notes backlinks --id 20260419090000
cx notes graph --id 20260419090000 --depth 2
cx notes orphans

Use these commands to confirm:

  • the edited note still links to the right concepts

  • related notes point back where expected

  • no unexpected orphaning happened

  • the change fits the existing knowledge graph instead of fragmenting it

Trust still stays explicit after the edit:

  • source tree: trusted

  • notes: conditional

  • agent output: untrusted until verified

  • bundle: trusted

Why this protects you: safe mutation is not just "permission granted." It is permission plus review. The graph commands make durable knowledge auditable after the edit, not just editable during it.

Step 6: Reconfirm The Gate Locally And In CI

Once the mutation is complete, review it through the CLI instead of trusting the edit implicitly:

cx notes check
cx notes graph --id 20260419153000 --depth 2
cx notes backlinks --id 20260419153000

Use the check to verify:

  • every new or changed note still has a valid summary

  • no note exceeded the size limits

  • duplicate IDs did not enter the graph

  • broken links or orphaned concepts did not appear

The same review path has a dedicated CI lane:

bun run ci:notes:governance

That lane runs cx notes check directly so cognition-layer quality stays visible as its own gate instead of being buried inside a larger test job.

Why this protects you: note mutation is not finished when the write succeeds. It is finished when the updated cognition layer still passes governance and graph review locally and later in CI.