@cairnkeep/cli 2.11.0 → 2.13.0

package/docs/learning/lessons/L13-session-evidence.md

@@ -2,7 +2,7 @@
 
 **Status:** Brief
 **Track:** Practitioner; Evidence and Evaluation
-**Planned time:** 45 minutes
+**Planned time:** 60 minutes
 
 ## Outcome
 
@@ -16,12 +16,14 @@ confusing it with reviewed durable memory.
   hindsight note, explicit shared promotion, and reviewed memory.
 - Independent consent flags for trajectory capture, note distillation, note
   enrichment, compaction capture, artifact tools, and artifact HTTP access.
+- Launcher-owned Git work evidence, its local-only read surface, its separate
+  patch consent boundary, and why interval evidence is not authorship proof.
 - Claude Code and OpenCode hooks versus Pi's native `session_shutdown` adapter.
 - Pre-write redaction, reasoning omission, size limits, 30-day defaults, and
   fail-open capture behavior.
 - Compaction summaries as harness-produced continuity evidence, never trusted
   instructions and never automatic fresh-session context.
-- `cairn trajectory`, `cairn notes`, `cairn artifact`, and `cairn doctor
+- `cairn trajectory`, `cairn notes`, `cairn artifact`, `cairn evidence`, and `cairn doctor
   --repair` inspection and recovery paths.
 
 ## Hands-on lab
@@ -62,4 +64,48 @@ cairn artifact list --json
 - [Operating guide: structured trajectories](../../operating.md#structured-session-trajectories-opt-in)
 - [Operating guide: hindsight notes](../../operating.md#hindsight-notes-opt-in)
 - [Privacy and data flow](../../privacy-and-data-flow.md#structured-trajectory-capture)
+- [Git-linked work evidence](../../work-evidence.md)
 - [Storage and deployment](../../storage.md)
+
+## Git-linked work evidence lab
+
+Use a disposable Git repository and a generated launcher. Add this to
+`.ai/.env` without enabling patch capture:
+
+```sh
+CAIRN_WORK_EVIDENCE=1
+```
+
+Launch the selected harness, edit one tracked file and create one untracked
+file, then exit normally. Inspect the result:
+
+```sh
+cairn evidence list --json
+cairn evidence show EVIDENCE-ID --json
+cairn evidence doctor --json
+cairn evidence prune --dry-run --json
+```
+
+The learner should be able to identify the start/end Git state, touched path
+labels, exit status and overall digest; explain why the record does not prove
+authorship; and confirm that no prompt, keystroke, command history or reasoning
+was retained. Repeat with the feature unset and verify that no work-evidence
+directory is created.
+
+For the optional patch exercise, use only synthetic content and set both
+`CAIRN_WORK_EVIDENCE_PATCH=1` and `CAIRN_ARTIFACT_STORE=1`. Begin with an
+already-dirty tracked file, make another edit, then verify that the artifact can
+include both because its scope is the start commit to the end worktree. Confirm
+that an untracked file body is absent and that Cairnkeep exposes no apply or
+restore command.
+
+## Recording outline
+
+1. Show the default-off launcher and empty evidence list.
+2. Enable metadata-only capture, run a short session and inspect its digests.
+3. Follow one exact trajectory or artifact link without copying its body.
+4. Demonstrate missing-Git fail-open behavior and the preserved harness exit.
+5. Enable the two patch prerequisites with synthetic data and explain the
+   pre-existing-dirty and untracked-body boundaries.
+6. Finish with dry-run deletion/pruning, local-only MCP exposure and uninstall
+   retention.

package/docs/learning/lessons/L19-validated-skill-improvement.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Evidence and Evaluation
 **Time:** 50 minutes
-**Tested with:** Cairnkeep 2.11.0
+**Tested with:** Cairnkeep 2.13.0
 
 ## Outcome
 

package/docs/learning/lessons/L20-mcp-tool-profiles.md

@@ -1,7 +1,7 @@
 # L20 - Least-authority MCP tool profiles
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.11.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.13.0 and Node.js 22 or newer
 **Time:** 25 minutes
 
 ## Outcome

package/docs/learning/lessons/L21-context-packs.md

@@ -1,7 +1,7 @@
 # L21 - Immutable context packs and skill approval
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.11.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.13.0 and Node.js 22 or newer
 **Time:** 40 minutes
 
 ## Outcome

package/docs/learning/lessons/L22-native-windows.md

@@ -3,25 +3,25 @@
 **Status:** Ready
 **Track:** Operator
 **Time:** 30 minutes
-**Tested with:** Cairnkeep 2.11.0, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.13.0, Windows x64, and Node.js 22 or newer
 
 ## Outcome
 
-You can prove that Cairnkeep is running natively from PowerShell, bootstrap a
-path containing spaces, inspect its security boundary, and perform a reversible
-uninstall without relying on WSL or Git Bash.
+You can prove that Cairnkeep is running natively from PowerShell, run guided
+setup on an empty path containing spaces, inspect its security boundary, and
+perform a reversible uninstall without relying on WSL or Git Bash.
 
 ## Exercise
 
 From PowerShell:
 
 ```powershell
-npm install --global @cairnkeep/cli@2.11.0
+npm install --global @cairnkeep/cli@2.13.0
 cairn version
 
 $Lab = Join-Path $env:TEMP 'Cairnkeep Windows Lab'
 New-Item -ItemType Directory -Force -Path $Lab | Out-Null
-cairn bootstrap $Lab
+cairn setup $Lab --git init --harness claude --memory local --yes
 cairn sync --apply --live-root (Join-Path $Lab '.claude-test')
 cairn sync --check --live-root (Join-Path $Lab '.claude-test')
 Push-Location $Lab
@@ -29,9 +29,9 @@ cairn doctor
 Pop-Location
 ```
 
-Verify that `.ai/start-claude.cmd`, `.ai/start-harness.ps1`, and the managed
-Claude assets exist. `cairn doctor` must identify native Windows x64 and complete
-an MCP stdio handshake.
+Verify that `.git`, `.ai/cairnkeep.json`, `.ai/start-claude.cmd`,
+`.ai/start-harness.ps1`, and the managed Claude assets exist. `cairn doctor`
+must identify native Windows x64 and complete an MCP stdio handshake.
 
 ## Permission check
 

package/docs/learning/lessons/L23-guided-setup.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart and Operator
 **Time:** 35 minutes
-**Tested with:** Cairnkeep 2.11.0; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.13.0; Pi 0.84.1; Node.js 22, 24, and 26
 
 ## Outcome
 
@@ -11,6 +11,10 @@ You can classify a missing or empty target, replay setup without a TTY, explain
 the limitations of Git-less mode, verify Pi's local stdio memory bridge, and
 recover or uninstall every managed asset without hidden machine changes.
 
+The selected harnesses come from Cairnkeep's declarative registry. Codex is a
+supported selection: it receives `.codex/config.toml` and a launcher, while Pi
+continues to require its separate explicit machine sync.
+
 ## Prerequisites
 
 - Node.js 22 or newer, npm, and Git for the main exercise.
@@ -130,7 +134,7 @@ prompts, approve skills, create an autonomous loop, or add remote access.
 
 ## Release boundary
 
-Ready means this lesson and its deterministic contracts pass against v2.11.0.
+Ready means this lesson and its deterministic contracts pass against v2.13.0.
 Release readiness requires a non-skipping acceptance run
 against separate Pi 0.84.1 minimum and explicitly versioned registry-current
 installations, plus the documented Node.js, Bash 3.2, and native Windows matrix.

package/docs/learning/tracks/evidence-and-evaluation.md

@@ -13,7 +13,8 @@
 6. [L19 - Validated skill improvement](../lessons/L19-validated-skill-improvement.md)
 
 The track is complete when the learner can explain each consent boundary,
-inspect and manage every local evidence store, compare baseline and ablation
+inspect and manage every local evidence store, including Git-linked work
+evidence, compare baseline and ablation
 reports without making unsupported claims, apply or roll back an exact eligible
 skill proposal, and distinguish that narrow runtime from the design-only
 general meta-agent contract.

package/docs/learning/tracks/quickstart.md

@@ -7,14 +7,15 @@
 1. [L00 - Why Cairnkeep?](../lessons/L00-why-cairnkeep.md)
 2. [L01 - Try it safely](../lessons/L01-safe-trial.md)
 3. [L02 - Install the local workflow](../lessons/L02-installation.md)
-4. [L03 - Bootstrap the first project](../lessons/L03-first-project.md)
+4. [L03 - Set up the first project](../lessons/L03-first-project.md)
 5. [L23 - Guided setup and Pi memory](../lessons/L23-guided-setup.md)
 
 The track is complete when a learner can start a new harness session, retrieve
 a previously accepted fact, and explain that default stdio memory is stored on
-the local machine rather than a discovered remote service. L23 then shows how
-the recommended guided entry point preserves deterministic automation and keeps
-Pi machine sync explicit. This guided surface ships in v2.11.
+the local machine rather than a discovered remote service. L03 uses the
+recommended guided entry point and offers Codex's project-scoped path without a
+separate machine sync; L23 extends that contract to Pi's maintained local stdio
+bridge while keeping its machine sync explicit.
 
 Hands-on spine: `course-00-app` through `course-01-bootstrap`, followed by
 `course-12-guided-setup`, in the public

package/docs/native-windows.md

@@ -32,6 +32,20 @@ recovery contract as POSIX. It writes a restricted `.ai/cairnkeep.json` setup
 record and never syncs machine assets automatically. `cairn bootstrap` remains
 the deterministic compatibility primitive for existing scripts.
 
+For Codex memory without a harness-wide sync, select only Codex:
+
+```powershell
+cairn setup $Project --git init --harness codex --memory local --yes
+Set-Location $Project
+cairn doctor
+.\.ai\start-codex.cmd
+```
+
+Review `.codex\config.toml` and accept Codex's project-trust prompt. Setup does
+not edit the user-wide Codex configuration or grant trust. It preserves a
+different existing project configuration and doctor verifies a manually merged
+`mcp_servers.cairn-memory` table.
+
 Setup and bootstrap write both the established Unix launchers and native Windows
 launchers. Each `.cmd` file enters `start-harness.ps1`, loads `.ai/.env`, changes
 to the project root, and forwards arguments without shell interpolation.
@@ -39,6 +53,15 @@ Optional `.ai/pre-launch.ps1` and `.ai/post-exit.ps1` seams run in the same
 PowerShell process, so exported environment changes reach the harness. The post
 hook receives `$env:CAIRN_EXIT_STATUS`.
 
+With `CAIRN_WORK_EVIDENCE=1`, the native PowerShell launcher routes all selected
+harnesses through `cairn evidence run`. It uses the system `git.exe`, writes the
+same private project-local format as POSIX systems, and preserves the harness
+exit status. Missing Git, a non-repository directory or capture failure warns
+and launches the harness directly. Optional patch capture additionally requires
+`CAIRN_WORK_EVIDENCE_PATCH=1` and `CAIRN_ARTIFACT_STORE=1`; Windows atomic
+replacement uses the platform file-replace primitive rather than POSIX rename
+semantics.
+
 ## MCP and operating assets
 
 Register the stdio server exactly as on other platforms:

package/docs/operating.md

@@ -70,7 +70,7 @@ cairn setup /path/to/project --git init --harness claude,pi --memory local --yes
 ```
 
 The deterministic form accepts `--git init|existing|none`, a comma-separated
-subset of `claude,opencode,pi,kimi,qwen`, and `--memory local|none`. `--git
+subset of `claude,opencode,pi,kimi,qwen,codex`, and `--memory local|none`. `--git
 existing` requires the target to be in an existing work tree. `--git init`
 requires Git and is the only non-interactive authorization to initialize a
 repository. `--git none` is an explicit limited mode: repository-aware features
@@ -91,8 +91,10 @@ assets. It contains no credentials, endpoints, or absolute paths.
 
 Setup never installs or refreshes machine-level harness assets. Its
 `machine_sync.automatic` field is always false, and the human output labels the
-reported command as not run automatically. Apply the relevant machine command
-explicitly, check it, then diagnose and launch:
+reported command as not run automatically. For selections such as Codex and
+Qwen that need no machine sync, `machine_sync.command` is `null` and the human
+output says that sync is not required. Apply any reported command explicitly,
+check it, then diagnose and launch:
 
 ```bash
 cairn sync --apply                    # Claude Code operating assets
@@ -105,6 +107,25 @@ cd /path/to/project && cairn doctor
 `cairn bootstrap [--untracked] PATH` remains available for scripts that depend
 on its original scaffold and Git-exclusion contract.
 
+## Setup order (Codex CLI)
+
+Codex uses project-scoped configuration, so setup owns the complete local MCP
+wiring without editing user-wide state:
+
+```bash
+npm install -g @cairnkeep/cli
+cairn setup /path/to/project --git init --harness codex --memory local --yes
+cd /path/to/project
+cairn doctor
+./.ai/start-codex.sh                    # native Windows: .\.ai\start-codex.cmd
+```
+
+Review `.codex/config.toml` and accept Codex's project-trust prompt before use.
+An existing different file is preserved and reported as skipped; merge the
+generated `mcp_servers.cairn-memory` table into it, then run `cairn doctor`.
+Uninstall leaves that operator-owned file intact. Selecting
+`--memory none` creates the launcher but deliberately omits the MCP entry.
+
 ## Setup order (Claude Code)
 
 The commands below install the default local topology: `cairn-memory` runs as a
@@ -445,6 +466,12 @@ vendor or host.
 | `CAIRN_TRAJECTORY_RETENTION_DAYS` | Age retention applied on capture/prune (default `30`; `0` removes sessions once they are older than the current instant) |
 | `CAIRN_TRAJECTORY_REDACTION_FILE` | Optional redaction JSON path contained by the project (default `.ai/trajectory-redaction.json` when that file exists) |
 | `CAIRN_REDACTION_FILE` | Optional project-contained redaction JSON shared by trajectories and artifacts; takes precedence over `CAIRN_TRAJECTORY_REDACTION_FILE` |
+| `CAIRN_WORK_EVIDENCE` | Capture bounded Git state around generated harness launches (off by default) |
+| `CAIRN_WORK_EVIDENCE_PATCH` | Request an optional redacted patch artifact (off by default; requires `CAIRN_ARTIFACT_STORE`) |
+| `CAIRN_WORK_EVIDENCE_RETENTION_DAYS` | Work-evidence retention (default `30`; `0` disables age pruning) |
+| `CAIRN_WORK_EVIDENCE_STORE_MAX_BYTES` | Project-local metadata budget (default `67108864`, 64 MiB) |
+| `CAIRN_WORK_EVIDENCE_MAX_TOUCHED_PATHS` | Maximum touched-path labels per record (default and hard maximum `4096`) |
+| `CAIRN_WORK_EVIDENCE_PATCH_MAX_BYTES` | Optional patch cap (default `1048576`, 1 MiB; the artifact cap can lower it) |
 | `CAIRN_COMPACTION_CAPTURE` | Opt in to supported local compaction capture and automatic structured recovery (off by default; unset means zero new work) |
 | `CAIRN_ARTIFACT_STORE` | Expose the four local stdio artifact tools (off by default; independent of compaction capture) |
 | `CAIRN_ARTIFACT_HTTP` | Separately expose artifact tools over authenticated HTTP (off by default; also requires `CAIRN_ARTIFACT_STORE`) |
@@ -865,13 +892,13 @@ maintain a running install — without forking the core. All are opt-in.
 ### Launcher seams
 
 The generic launchers (`.ai/start-claude.sh`, `.ai/start-opencode.sh`,
-`.ai/start-kimi.sh`, `.ai/start-qwen.sh`, and `.ai/start-pi.sh`) run optional hooks around the
+`.ai/start-kimi.sh`, `.ai/start-qwen.sh`, `.ai/start-codex.sh`, and `.ai/start-pi.sh`) run optional hooks around the
 harness, each a no-op when absent:
 
 | Seam | When | Purpose |
 |---|---|---|
 | `.ai/pre-launch.sh` | sourced after `.env`, before launch | export env (e.g. a provider base URL / auth), refresh credentials, or abort by returning non-zero |
-| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered on Claude Code (`--settings`) or OpenCode (`OPENCODE_CONFIG`); Kimi, Qwen, and Pi leave the variable available to hooks but do not interpret it |
+| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered on Claude Code (`--settings`) or OpenCode (`OPENCODE_CONFIG`); Kimi, Qwen, Codex, and Pi leave the variable available to hooks but do not interpret it |
 | `.ai/post-exit.sh` | sourced after the harness exits | teardown; `CAIRN_EXIT_STATUS` holds the exit code |
 
 A wrapper that needs a non-default provider drops a `pre-launch.sh` that renders
@@ -1021,6 +1048,43 @@ eligible for exact-digest application. See
 [Validated skill improvement](skill-improvement.md) for the command sequence,
 adapter contract, task constraints, and rollback procedure.
 
+### Git-linked work evidence (opt-in)
+
+Set `CAIRN_WORK_EVIDENCE=1` in `.ai/.env` and use a generated harness launcher.
+The launcher opens a local evidence interval before Claude Code, OpenCode, Pi,
+Kimi, Qwen or Codex and settles it after exit. A missing Git executable, a
+non-repository directory or a capture error produces a warning and never blocks
+the harness. Direct harness launches do not create launcher-owned evidence.
+The launcher reserves `CAIRN_WORK_EVIDENCE_ID` and `CAIRN_WORK_EVIDENCE_ROOT`
+for child-process correlation; operators must not set either variable directly.
+
+```bash
+cairn evidence list --json
+cairn evidence show EVIDENCE-ID --json
+cairn evidence delete EVIDENCE-ID --dry-run --json
+cairn evidence prune --dry-run --json
+cairn evidence doctor --json
+```
+
+The start/end record includes commits, branch/detached/unborn state, dirty
+state, canonical status/workspace digests, touched path labels, timestamps and
+exit status. It can append exact trajectory, artifact and reviewed-memory
+identifiers produced by descendant processes. It captures no prompts,
+keystrokes, command history or reasoning. Concurrent writers are not
+attributed, and a path changed then restored to its starting state is invisible.
+
+Patch capture is a separate consent boundary: both
+`CAIRN_WORK_EVIDENCE_PATCH=1` and `CAIRN_ARTIFACT_STORE=1` are required. The
+redacted, bounded diff is computed from the starting commit to the ending
+worktree, so it can include tracked changes that predated the session; untracked
+bodies are omitted. Cairnkeep has no apply, restore or replay operation.
+
+When enabled, local stdio exposes only `work_evidence_list` and
+`work_evidence_read`; they are read-only, non-destructive, idempotent and
+closed-world. HTTP never exposes them. See [Git-linked work evidence](work-evidence.md),
+[storage](storage.md#git-linked-work-evidence) and
+[privacy](privacy-and-data-flow.md#git-linked-work-evidence).
+
 ### Structured session trajectories (opt-in)
 
 Trajectory capture is disabled by default. To enable it for a launched Claude

package/docs/privacy-and-data-flow.md

@@ -23,6 +23,8 @@ request unless the corresponding endpoint and credential are configured.
 | Remote HTTP memory | MCP requests and responses, including memory content | The explicitly registered Cairnkeep HTTP server |
 | Opt-in trajectory capture | None | Local `<project>/.agentfs/trajectory.db` only; no model or HTTP path exists |
 | Opt-in capability callback records | None | Payload-free final metadata in local `<project>/.agentfs/trajectory.db`; HTTP transport is always skipped |
+| Opt-in Git-linked work evidence | Repository-relative Git state and exact local object identifiers | Local `<Git root>/.agentfs/work-evidence/v1/`; HTTP transport is always skipped |
+| Separately enabled work-evidence patch | Redacted tracked diff from the starting commit to the ending worktree | Local artifact store only; requires both work-evidence patch and artifact-store consent |
 | Opt-in deterministic note distillation | None | Reads redacted closed trajectories; writes local Markdown + manifest under `${CAIRN_AGENTFS_BASE_DIR:-~/.cairnkeep}/notes/` |
 | Separately opted-in note enrichment | `CAIRN_LLM_API_KEY` | Sends bounded redacted note evidence to the explicit `CAIRN_LLM_API_URL` chat endpoint |
 | Typed lifecycle and inline `memory_import` over local stdio | None | Values, metadata, digests, replay bindings, and history remain in the selected local store |
@@ -37,6 +39,7 @@ request unless the corresponding endpoint and credential are configured.
 | Explicit artifact read/show | The redacted body only when HTTP is separately enabled and the operator/client explicitly reads it | Local terminal/stdio, or the explicitly registered authenticated server |
 | Opt-in evaluation coordinator | Adapter-defined inference may leave the machine only according to the explicit operator-owned adapter and inherited environment | Local adapter subprocess; Cairnkeep supplies no provider, endpoint, credential, model, or network default |
 | Guided project setup | None | Selected scaffold assets and private `.ai/cairnkeep.json` state in the target; machine sync is never automatic |
+| Codex project setup and launcher | None | Local `.codex/config.toml` starts `cairn memory-server` over stdio only after the operator trusts the project |
 | Pi memory extension | None | Local `cairn memory-server` stdio child; no HTTP transport is inherited |
 
 Model endpoints may be local or remote. Cairnkeep cannot determine a provider's
@@ -93,7 +96,7 @@ and its generated `revert.sh` restores exact bytes, modes, and layout. Explicit
 `cairn eval delete` and `prune` remove selected contained experiment trees with
 no hidden tombstone.
 
-## Guided setup and Pi bridge
+## Guided setup, Codex, and Pi bridge
 
 Guided setup performs a read-only target and Git preflight before project
 writes. Its schema-v1 `.ai/cairnkeep.json` record contains the package version,
@@ -103,6 +106,12 @@ endpoints, absolute paths, prompts, or memory values. The file is mode `0600`
 on POSIX and receives the private managed-file ACL on native Windows. Setup
 never invokes machine sync, and it does not start a harness or server child.
 
+Selecting Codex with local memory adds a non-secret project MCP table that
+invokes `cairn memory-server`. Setup never edits user-wide Codex configuration,
+grants project trust, or overwrites a different `.codex/config.toml`. Doctor can
+validate a manually merged Cairnkeep table without claiming ownership of the
+surrounding operator configuration, and uninstall leaves that file intact.
+
 When the explicitly installed Pi memory extension starts a session, it spawns
 `cairn memory-server` as a child in the project directory over local stdio. The
 bridge removes `MCP_HTTP_PORT` from the child environment, retains only the
@@ -324,6 +333,40 @@ compaction hooks, or a generic filesystem. With HTTP consent absent, remote
 clients cannot observe artifact schemas or content. Artifacts have no default egress.
 Artifacts have no telemetry; local capture/recovery never uses the HTTP route.
 
+## Git-linked work evidence
+
+Work evidence is disabled unless `CAIRN_WORK_EVIDENCE=1` is present in the
+launcher environment. Generated launchers observe Git immediately before and
+after the harness process and store commit, branch/detached/unborn and dirty
+state, canonical status/workspace digests, bounded touched-path labels,
+timestamps and exit status. Descendant processes may append exact identifiers
+for trajectories, artifacts and reviewed-memory writes. They do not copy those
+bodies into the evidence record.
+
+Workspace digests are derived from Git object state and can include the hashes
+of observed untracked content. Bodies are not retained, but hashing is not
+redaction: an observer can test guesses for low-entropy content. Keep secrets
+out of project worktrees and do not enable this feature when path labels or
+content-derived digests exceed the project's retention policy.
+
+No prompt, keystroke, shell history, environment value or model reasoning is
+captured. Repository-relative path labels are retained because they are needed
+to explain the observed worktree transition. Concurrent processes are not
+distinguishable, and a path restored to its starting state is not reported as
+touched. The record is evidence of an interval and integrity relationships, not
+proof of authorship.
+
+Optional patch capture requires both `CAIRN_WORK_EVIDENCE_PATCH=1` and
+`CAIRN_ARTIFACT_STORE=1`. The diff is computed from the start commit to the end
+worktree, so it can contain tracked edits that existed before launch. Untracked
+bodies are omitted. Existing recursive redaction and the lower configured byte
+cap apply before the artifact is persisted. Cairnkeep never applies, restores
+or sends the patch.
+
+`work_evidence_list` and `work_evidence_read` are local-stdio-only observation
+tools. They are absent when the feature is off and absent from authenticated
+HTTP even when it is on. No work-evidence path performs a network request.
+
 ## Structured trajectory capture
 
 `CAIRN_TRAJECTORY_CAPTURE` is unset and off by default. When explicitly set to

package/docs/quickstart.md

@@ -0,0 +1,91 @@
+# Cairnkeep quickstart
+
+This is the shortest supported route from an empty directory or existing Git
+repository to durable, local agent memory. The default transport is stdio and
+the default store stays on this computer.
+
+## Codex CLI
+
+Install Cairnkeep, then let guided setup initialize an empty project and write
+Codex's project-scoped MCP entry:
+
+```bash
+npm install --global @cairnkeep/cli
+cairn setup /path/to/project --git init --harness codex --memory local --yes
+cd /path/to/project
+cairn doctor
+./.ai/start-codex.sh
+```
+
+Use `--git existing` instead when the target is already a Git work tree. On
+native Windows, launch with `.\.ai\start-codex.cmd`.
+
+Before the first session, review `.codex/config.toml` and accept Codex's project
+trust prompt. The generated entry runs `cairn memory-server` locally. Setup
+does not edit the user-wide Codex configuration and does not enable networking,
+telemetry, embeddings, session capture, or context packs.
+
+If `.codex/config.toml` already exists and differs, setup reports it as
+`skipped` and preserves it byte-for-byte. Merge this table into the existing
+file, then run `cairn doctor`:
+
+```toml
+[mcp_servers.cairn-memory]
+command = "cairn"
+args = ["memory-server"]
+```
+
+## Claude Code
+
+Claude Code has the full Cairnkeep operating layer, so it needs one explicit
+machine-level sync in addition to project setup:
+
+```bash
+npm install --global @cairnkeep/cli
+claude mcp add cairn-memory -s user -- cairn memory-server
+cairn sync --apply
+cairn setup /path/to/project --git init --harness claude --memory local --yes
+cd /path/to/project
+cairn doctor
+./.ai/start-claude.sh
+```
+
+Setup reports machine-level commands but never executes them. This keeps
+project scaffolding separate from harness-wide changes.
+
+## First memory cycle
+
+In a harness with Cairnkeep commands, remember one durable fact and recall it:
+
+```text
+> /remember Use transactional migrations for schema changes
+> /recall transactional migrations
+```
+
+In Codex or another MCP client, ask the client to call `memory_write`, then
+`memory_search`. Close the session, start a new one, and repeat the search. The
+result should survive the restart.
+
+## What setup owns
+
+`cairn setup` creates only the selected harness assets plus the common `.ai`,
+`.planning`, and `.agentfs` scaffold. It initializes Git only with explicit
+`--git init`, preserves unrelated files, does not overwrite modified files it
+does not own, and records managed digests in private `.ai/cairnkeep.json`.
+
+Useful follow-ups:
+
+```bash
+cairn setup . --git existing --harness codex --memory local --yes  # reconcile
+cairn doctor                                                       # diagnose
+cairn uninstall --dry-run .                                       # preview removal
+```
+
+For all harnesses, remote HTTP, storage, profiles, context packs, overlays, and
+recovery details, continue with [Operating Cairnkeep](operating.md) or the
+[learning path](learning/README.md).
+
+To add bounded Git state around future generated-launcher sessions, set
+`CAIRN_WORK_EVIDENCE=1` in `.ai/.env`; inspect it with `cairn evidence list`.
+It is local and off by default. Patch capture remains a separate double-consent
+feature. See [Git-linked work evidence](work-evidence.md).

package/docs/storage.md

@@ -20,6 +20,7 @@ registration, memory remains on that computer.
 | `project` | `<server working directory>/.agentfs/project.db` |
 | Opt-in session trajectories and capability callback state | `<harness project root>/.agentfs/trajectory.db` |
 | Opt-in local artifacts and compaction revisions | `<project root>/.agentfs/artifacts.db` |
+| Opt-in Git-linked work evidence | `<Git root>/.agentfs/work-evidence/v1/` |
 | Opt-in evaluation reports and note snapshots | `<project root>/.agentfs/eval/experiments/<experiment-id>/` |
 | Immutable context-pack objects and source records | `${CAIRN_PACK_BASE_DIR:-~/.cairnkeep/packs}/objects/` and `sources/` |
 | Digest-pinned context-pack project pointers and approvals | `${CAIRN_PACK_BASE_DIR:-~/.cairnkeep/packs}/projects/` |
@@ -128,6 +129,31 @@ the processed-session ledger at 4096 digests per project. Note bodies do not
 expire automatically: inspect/delete them according to your own retention
 policy. Trajectory pruning does not delete already-derived notes.
 
+## Git-linked work evidence
+
+`CAIRN_WORK_EVIDENCE=1` stores private, atomic JSON records below
+`<Git root>/.agentfs/work-evidence/v1/records/` and append-only link sets below
+`links/`. The root is resolved with the system Git executable; ancestor
+symlinks, non-regular records and malformed data fail closed. Files and
+directories are hardened with the same platform-specific private-permission
+boundary used by other local stores.
+
+Each record is immutable after it moves from pending to complete. Completion
+captures the final Git observation and an overall digest; it never rewrites the
+start observation. A crash can leave a pending record, which `cairn evidence
+doctor` reports. Doctor may report permissions, corruption and temporary
+remnants, but does not infer or manufacture a missing end state.
+
+Defaults are 30 days, 64 MiB of local metadata, 4,096 touched path labels and a
+1 MiB optional patch cap. Capture and `cairn evidence prune` apply the age and
+budget policy. `delete` and `prune` support dry runs. Patch bodies, when doubly
+enabled, are ordinary redacted artifacts in `.agentfs/artifacts.db`; the
+evidence record keeps only the artifact identifier and digest relationship.
+
+Default uninstall retains the project `.agentfs` tree. Explicit
+`--purge-memory` follows the existing backup-first project-store boundary and
+therefore includes work evidence. Memory export does not include it.
+
 ## Artifact storage
 
 Artifacts are deliberately separate from memory and trajectories. Local

package/docs/work-evidence.md

@@ -0,0 +1,80 @@
+# Git-linked work evidence
+
+Cairnkeep can record a bounded, local account of the Git state surrounding a
+harness session. The feature is off by default. Enable it in the project's
+`.ai/.env`:
+
+```sh
+CAIRN_WORK_EVIDENCE=1
+```
+
+Generated Claude Code, OpenCode, Pi, Kimi, Qwen and Codex launchers then start
+an evidence record before the harness and settle it after the harness exits.
+The harness still launches when Git is unavailable, the directory is not a Git
+worktree, or evidence capture fails; Cairnkeep prints a warning instead of
+turning optional evidence into an availability dependency.
+
+## Recorded metadata
+
+Each completed record contains the harness, start/end timestamps, exit status,
+repository-relative identity, and the start/end commit, branch, detached or
+unborn state, dirty state, status digest and workspace digest. It also contains
+a bounded list of paths whose observed state changed during the session and an
+overall evidence digest.
+
+Workspace digests are content-derived, including for observed untracked files.
+They do not retain file bodies, but low-entropy candidate content can sometimes
+be tested against a known digest; do not treat hashing as redaction.
+
+Records may link to exact trajectories, artifacts and reviewed-memory writes
+created while that launcher-owned session is active. Links are append-only and
+carry identifiers, not copied content. Cairnkeep does not capture keystrokes,
+prompts, shell history or model reasoning.
+
+The record describes a time interval, not authorship. Concurrent processes can
+change the same worktree, and a file changed and restored to its starting state
+will not appear as touched. Treat the evidence as integrity-linked operational
+context, not proof that a particular person or model made a change.
+
+## Optional patch artifact
+
+Patch capture requires two independent feature flags:
+
+```sh
+CAIRN_WORK_EVIDENCE_PATCH=1
+CAIRN_ARTIFACT_STORE=1
+```
+
+The patch is produced at session end from the starting commit to the ending
+worktree. It can therefore include tracked changes that already existed when
+the session started. Untracked file names can appear in metadata, but their
+bodies are not included. The patch is redacted, bounded by the lower of the
+work-evidence and artifact limits, and stored in the existing artifact store.
+Cairnkeep provides no patch apply, restore or replay command.
+
+## Inspect and maintain
+
+```sh
+cairn evidence list [--status pending|complete] [--json]
+cairn evidence show <evidence-id-or-prefix> [--json]
+cairn evidence delete <evidence-id-or-prefix> [--dry-run] [--json]
+cairn evidence prune [--dry-run] [--json]
+cairn evidence doctor [--repair] [--json]
+```
+
+Metadata and links live below
+`<repository>/.agentfs/work-evidence/v1/`. Records default to 30-day retention,
+1 MiB per optional patch, 4,096 touched paths and a 64 MiB metadata budget.
+Interrupted sessions remain visibly pending rather than being fabricated as
+complete. `doctor` reports malformed records, broken links, permission drift,
+temporary remnants and stale pending sessions. `--repair` can remove temporary
+remnants, but it does not change records or invent an ending Git state.
+
+With the feature enabled, local stdio MCP registers `work_evidence_list` and
+`work_evidence_read`. Both are read-only, non-destructive, idempotent and
+closed-world. They are never exposed by the HTTP transport. MCP profiles can
+further restrict them, but cannot enable the feature.
+
+Ordinary uninstall retains the project `.agentfs` boundary. As with other
+project evidence stores, `cairn uninstall --purge-memory` backs up and removes
+it only after explicit confirmation.