@cairnkeep/cli 2.11.0 → 2.13.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.13.0] - 2026-08-17
+
+### Added
+
+- Add opt-in, local Git-linked work evidence for all six generated harness
+  launchers and native Windows, with bounded start/end state, touched paths,
+  append-only trajectory/artifact/reviewed-memory links, lifecycle CLI and two
+  local read-only MCP observations.
+- Add separately consented, redacted patch artifacts and document their
+  start-commit scope, pre-existing-dirty limitation and omitted untracked bodies.
+
+## [2.12.0] - 2026-08-13
+
+### Added
+
+- Add one declarative harness registry for setup choices, project assets,
+  launcher generation, diagnostics, native Windows, and lifecycle tooling.
+- Add first-class Codex CLI setup with a project-scoped local stdio MCP entry,
+  POSIX and native Windows launchers, explicit project-trust guidance, and a
+  memory-off path that creates no MCP configuration.
+- Add a five-minute quickstart and Codex route to the public learning path.
+
+### Changed
+
+- Derive guided setup policy validation and required-asset diagnosis from the
+  shared harness catalog. Codex/Qwen-only setup now reports that no machine
+  sync is required instead of suggesting unrelated operating assets.
+- Extend bootstrap contributor mode, backup-first uninstall, schema validation,
+  package checks, and native Windows coverage to Codex-owned project files.
+
 ## [2.11.0] - 2026-08-12
 
 ### Added
@@ -317,7 +347,9 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
-[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.11.0...HEAD
+[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.13.0...HEAD
+[2.13.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.12.0...v2.13.0
+[2.12.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.11.0...v2.12.0
 [2.11.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.9.0...v2.11.0
 [2.9.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.8.0...v2.9.0
 [2.8.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.7.0...v2.8.0

package/README.md

@@ -9,13 +9,30 @@
 A *cairn* is a stack of stones left as a trail marker for whoever follows; a
 *keep* is where you store what matters. **Cairnkeep** is where coding agents
 stack durable memory — decisions, pitfalls, patterns — and follow the trail
-across sessions, projects, and harnesses (Claude Code, OpenCode, Kimi Code,
-Qwen Code, Pi, and other MCP clients).
+across sessions, projects, and harnesses (Claude Code, Codex CLI, OpenCode,
+Kimi Code, Qwen Code, Pi, and other MCP clients).
+
+## Five-minute start
+
+For Codex CLI, Cairnkeep can install the complete project-local memory wiring
+in one command:
+
+```bash
+npm install --global @cairnkeep/cli
+cairn setup /path/to/project --git init --harness codex --memory local --yes
+cd /path/to/project
+./.ai/start-codex.sh                 # Windows: .\.ai\start-codex.cmd
+```
+
+Review `.codex/config.toml` and accept Codex's project-trust prompt on first
+use. No separate MCP registration or machine-level asset sync is needed. See
+the **[quickstart](docs/quickstart.md)** for existing repositories, Claude Code,
+verification, and the first remember/recall cycle.
 
 ## Status
 
 Shipped: the memory server, the `cairn` CLI (`setup`, `bootstrap`, `memory-server`, `sync`, `sync-pi`, `sync-kimi`,
-`doctor`, `trajectory`, `artifact`, `mcp-tools`, `pack`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
+`doctor`, `trajectory`, `artifact`, `evidence`, `mcp-tools`, `pack`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
 `npm i -g @cairnkeep/cli`, and the
 operating layer (commands,
 agents, hooks) installed on Claude Code and OpenCode, plus the native Pi
@@ -27,8 +44,10 @@ a thin routing seam (`route_check`), both of which delegate to
 [token-miser](https://github.com/cairnkeep/token-miser), a public
 cairnkeep-org sibling project.
 
-Version 2.11 adds guided `cairn setup`, the maintained Pi local stdio memory
-extension, and the native Windows operating layer.
+Version 2.12 adds a declarative harness registry, first-class Codex project
+setup, and a shorter path from installation to verified recall.
+Version 2.13 adds opt-in local Git-linked work evidence around generated harness
+launchers, including native Windows, without capturing prompts or replacing Git.
 
 ## Compatibility
 
@@ -43,7 +62,7 @@ and 20 are end-of-life upstream.
 | Kimi Code on Linux/macOS | Memory MCP server, project launcher, and opt-in `/graphify` Skill |
 | Qwen Code on Linux/macOS | Memory MCP server plus project launcher; no Cairnkeep operating-layer assets yet |
 | Pi on Linux/macOS | Memory MCP through a maintained local stdio extension; native opt-in trajectory extension, launcher, and `/graphify` prompt; Pi 0.84.1 minimum for the bridge |
-| Codex CLI | Memory MCP server; no Cairnkeep operating-layer assets |
+| Codex CLI on Linux/macOS | Project-scoped memory MCP configuration and launcher; no Cairnkeep-specific commands or hooks |
 | Other MCP clients | Memory plus optional domain-knowledge and context-pack MCP tools |
 | Native Windows x64 | Node-native CLI, guided setup, memory server, bootstrap compatibility, PowerShell/Command Prompt launchers, sync, hooks, doctor, storage lifecycle, Task Scheduler, completion, and uninstall |
 | Windows ARM64 | Supported through Windows x64 emulation only; a native database binding is not currently shipped |
@@ -60,7 +79,7 @@ installation, and clean Node 22/24/26 runtime checks are exercised in CI. See
 ACL, scheduling, process-tree, and recovery details.
 
 See [Harness compatibility](docs/harness-compatibility.md) for exact support
-levels, Kimi and Qwen configuration, and candidates that are not yet runtime-tested.
+levels, trust boundaries, and candidates that are not yet runtime-tested.
 
 ## Try with Podman
 
@@ -140,6 +159,7 @@ operating layer installed into your harness, and a configured project. `cairn
 setup` is the recommended guided entry point; `cairn bootstrap` remains the
 deterministic compatibility primitive for established scripts. Project setup
 reports but never performs machine-level sync. The full ordered walkthrough is
+in **[the quickstart](docs/quickstart.md)**; the complete operator reference is
 in **[docs/operating.md](docs/operating.md)**.
 
 This setup is local by default: the registered stdio server stores memory on
@@ -179,6 +199,13 @@ patterns/transactional-migrations: Use transactional migrations for schema chang
 The exact command rendering depends on the client. Any MCP client can call
 `memory_write` and `memory_search` directly.
 
+For Codex CLI, `cairn setup --harness codex --memory local` writes the
+project-scoped `.codex/config.toml` entry and both POSIX and native Windows
+launchers. Review the configuration and trust the project before launching.
+Existing operator-owned `.codex/config.toml` files are never overwritten; a
+reported `skipped` file must be merged by the operator and checked with
+`cairn doctor`.
+
 For Kimi Code, bootstrap supplies a launcher and Kimi reads the repository's
 MCP configuration. A local stdio entry uses `cairn memory-server`. Remote Kimi
 configuration requires a literal URL and supports a token reference through
@@ -304,6 +331,12 @@ search):
 | `CAIRN_TRAJECTORY_RETENTION_DAYS` | Retain captured sessions for this many days (default `30`) |
 | `CAIRN_TRAJECTORY_REDACTION_FILE` | Optional project-contained redaction config (default `.ai/trajectory-redaction.json` when present) |
 | `CAIRN_REDACTION_FILE` | Optional project-contained redaction config shared by trajectories and artifacts (falls back to `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; also 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 work-evidence 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` | Maximum optional patch bytes (default `1048576`, 1 MiB; the artifact cap can lower it) |
 | `CAIRN_COMPACTION_CAPTURE` | Opt in to local harness-produced compaction capture and fresh-session recovery (off by default) |
 | `CAIRN_ARTIFACT_STORE` | Expose four local stdio artifact tools (off by default; independent of compaction capture) |
 | `CAIRN_ARTIFACT_HTTP` | Separately consent to artifact tools over authenticated HTTP (off by default; also requires `CAIRN_ARTIFACT_STORE`) |
@@ -492,6 +525,17 @@ reject policy cannot overwrite; explicit supersede preserves typed history.
 Note addresses require `scope: project` and logical keys, never filesystem
 paths. See the [operating guide](docs/operating.md#typed-memory-nodes-and-note-address-spaces-opt-in).
 
+### Git-linked work evidence (opt-in)
+
+`CAIRN_WORK_EVIDENCE=1` makes generated Claude Code, OpenCode, Pi, Kimi, Qwen
+and Codex launchers record bounded start/end Git state and links to exact local
+trajectories, artifacts and reviewed-memory writes. It records no prompts,
+keystrokes or reasoning, and harness launch remains fail-open when Git or
+capture is unavailable. Inspect it with `cairn evidence list|show|delete|prune|doctor`.
+Optional patch capture requires both `CAIRN_WORK_EVIDENCE_PATCH=1` and
+`CAIRN_ARTIFACT_STORE=1`; Cairnkeep never applies or restores a patch. See the
+[work-evidence guide](docs/work-evidence.md).
+
 ### Compaction continuity and artifacts (opt-in)
 
 `CAIRN_COMPACTION_CAPTURE=1` captures only harness-produced compaction summaries

package/docs/building-an-overlay.md

@@ -28,7 +28,7 @@ manifest, profile-lock, private-registry, and rollback contract.
 ## The 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`, scaffolded by `cairn bootstrap`) run
+`.ai/start-kimi.sh`, `.ai/start-qwen.sh`, `.ai/start-codex.sh`, and `.ai/start-pi.sh`, scaffolded by `cairn bootstrap`) run
 optional hooks, each a no-op when absent:
 
 | Seam | When | Use it for |

package/docs/harness-compatibility.md

@@ -4,6 +4,12 @@ Cairnkeep separates memory transport from harness-specific operating assets.
 An MCP client can use the memory tools without also supporting Cairnkeep's
 commands, hooks, plugins, or trajectory adapters.
 
+All six generated launchers—Claude Code, OpenCode, Kimi, Qwen, Pi and Codex—
+support the same opt-in Git-linked work-evidence wrapper. The wrapper is local,
+requires `CAIRN_WORK_EVIDENCE=1`, and fails open so optional capture cannot
+prevent a harness from launching. It does not imply that the harness supports
+Cairnkeep commands, hooks or native trajectory capture.
+
 ## Support levels
 
 | Harness | Supported surface | Runtime status |
@@ -13,13 +19,15 @@ commands, hooks, plugins, or trajectory adapters.
 | Kimi Code | Memory MCP, `AGENTS.md`, launcher, opt-in graph Skill | Launcher tested; remote MCP tested with Kimi Code 0.30.0; graph Skill contract-tested |
 | Qwen Code | Memory MCP, launcher | Launcher tested; stdio and remote MCP tested with Qwen Code 0.21.1 |
 | Pi | Memory MCP through maintained local stdio extension, native opt-in trajectory extension, launcher, and graph prompt | Pi 0.84.1 validated minimum; deterministic and real bridge/lifecycle tests |
-| Codex CLI | Memory MCP | Configuration supported; no Cairnkeep operating-layer assets or launcher |
+| Codex CLI | Project-scoped memory MCP and launcher | Setup and launcher contract-tested on POSIX and simulated native Windows; project trust remains operator-controlled |
 | Other MCP clients | Memory plus optional domain-knowledge and context-pack tools | Protocol-compatible; not automatically runtime-tested |
 
 Only Claude Code and OpenCode currently receive the complete operating layer.
 Kimi receives one narrow graph Skill, while Pi receives one narrow graph prompt;
 neither is equivalent to the full commands, agents, hooks, and plugins surface.
 Qwen skills and hooks still require harness-specific adaptation and validation.
+Codex receives a project-local MCP entry and launcher, but not Cairnkeep-specific
+commands, hooks, agents, or automatic skill activation.
 
 Every MCP client receives complete tool annotations and may use a Cairnkeep
 least-authority profile independent of harness assets. Context-pack tools are
@@ -200,6 +208,37 @@ Git, and leave secret values as environment references.
 Qwen MCP configuration is documented at
 [Qwen Code MCP](https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/).
 
+## Codex CLI
+
+Select Codex during setup to create a project-scoped local stdio entry and
+launcher:
+
+```bash
+cairn setup /path/to/project --git init --harness codex --memory local --yes
+cd /path/to/project
+./.ai/start-codex.sh
+```
+
+Native Windows uses `.\.ai\start-codex.cmd`. The generated
+`.codex/config.toml` contains only:
+
+```toml
+[mcp_servers.cairn-memory]
+command = "cairn"
+args = ["memory-server"]
+```
+
+Review this file before accepting Codex's project-trust prompt. Cairnkeep does
+not grant trust, edit the user-wide Codex configuration, or start Codex during
+setup. If an operator-owned `.codex/config.toml` already differs, setup reports
+`skipped` and leaves it unchanged; merge the table manually and run `cairn
+doctor` to verify the effective entry. Uninstall never removes an
+operator-owned configuration file.
+
+The launcher loads `.ai/.env`, runs optional pre/post hooks, changes to the
+project root, and passes all arguments to `codex`. It does not install native
+Codex Skills or instructions and does not activate approved context-pack skills.
+
 ## Candidate memory clients
 
 The following clients have documented MCP support and are reasonable adapter

package/docs/learning/CURRICULUM-MAP.md

@@ -1,7 +1,7 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.11.0
-**Last reviewed:** 2026-08-12
+**Baseline:** Cairnkeep 2.13.0
+**Last reviewed:** 2026-08-13
 
 This map prevents the course from drifting behind the product. It assigns each
 user-facing surface to a lesson and records whether the lesson is complete or
@@ -14,7 +14,8 @@ been rehearsed.
 | Product surface | Introduced | Practised or operated | Learning status |
 |---|---|---|---|
 | Local stdio memory and MCP registration | L00-L02 | L03-L04 | L00-L03 Ready; L04 Brief |
-| Project bootstrap, launchers, and contributor mode | L02-L03 | L05 | L02-L03 Ready; L05 Brief |
+| Guided project setup, launchers, and bootstrap compatibility/contributor mode | L02-L03 | L05 and L23 | L02-L03 and L23 Ready; L05 Brief |
+| Declarative harness registry and Codex project-scoped MCP setup | L03 | L03 and L23 | Ready; project trust remains explicit |
 | Memory scopes, keys, search, supersession, and history | L04 | L04-L05 | Brief |
 | Wiki, alignment, and repository quality workflows | L05-L06 | L05-L06 | Brief |
 | Optional local code graph, graph inspection, and harness delegates | L18 | L18 | Brief; default off |
@@ -26,6 +27,7 @@ been rehearsed.
 | Structured trajectories and Pi capture adapter | L13 | L13 | Brief; default off |
 | Hindsight-note distillation, lookup, enrichment, and promotion | L13 | L13-L14 | Brief; default off |
 | Compaction continuity and immutable artifacts | L13 | L13 | Brief; default off |
+| Git-linked work evidence | L13 | L13 | Lab + recording outline; default off |
 | Typed memory nodes, filters, address spaces, and structured import | L14 | L14 | Brief; default off |
 | Managed eight-capability contract and payload-free callbacks | L15 | L15-L16 | Brief; default off |
 | Deterministic two-pass evaluation and one-capability ablation | L16 | L16 | Brief; default off |
@@ -35,7 +37,7 @@ been rehearsed.
 | Complete MCP annotations and least-authority tool profiles | L20 | L20 | Ready; default profile remains full |
 | Immutable context packs and exact-digest skill approval | L21 | L21 | Ready; default off |
 | Native Windows x64 CLI, hooks, ACLs, scheduling, and recovery | L22 | L22 | Ready; PowerShell-native |
-| Guided project setup, selected harness state, and Git-less limitations | L23 | L23 | Ready |
+| Guided project setup, selected harness state, and Git-less limitations | L03 | L03 and L23 | Ready |
 | Pi local stdio memory bridge, trusted annotation details, and explicit lifecycle | L23 | L23 | Ready; Pi 0.84.1 validated minimum |
 
 ## Release Review
@@ -58,7 +60,7 @@ repository remains the canonical source for explanations and scripts.
 | Checkpoint | Lessons | Purpose |
 |---|---|---|
 | `course-00-app` | L00-L02 | Plain synthetic application before Cairnkeep |
-| `course-01-bootstrap` | L03 | Neutral bootstrap and isolated environment |
+| `course-01-bootstrap` | L03 | Guided local setup, Codex project configuration, and isolated environment |
 | `course-02-memory` | L04-L05 | Memory lifecycle and derived knowledge |
 | `course-03-quality` | L06 | Repository review and deliberately vulnerable fixture |
 | `course-04-operation` | L07-L12 | Storage, routing, integrations, containers, overlays |
@@ -78,8 +80,8 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 
 | Command | Primary lesson |
 |---|---|
-| `cairn bootstrap` | L03 |
-| `cairn setup` | L23 |
+| `cairn bootstrap` | L03 compatibility challenge |
+| `cairn setup` | L03 for Claude/Codex; advanced Pi lifecycle in L23 |
 | `cairn memory-server` | L02 |
 | `cairn sync` | L02 |
 | `cairn sync-pi` | L13 and L23 |
@@ -87,6 +89,7 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 | `cairn doctor` | L03; advanced repair in L13-L14 |
 | `cairn trajectory` | L13 |
 | `cairn artifact` | L13 |
+| `cairn evidence` | L13 |
 | `cairn capabilities` | L15 |
 | `cairn mcp-tools` | L20 |
 | `cairn pack` | L21 |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.11.0
+**Baseline:** Cairnkeep 2.13.0
 
 This is the step-back map for choosing and operating Cairnkeep features. The
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs) provide one
@@ -8,8 +8,13 @@ synthetic Trail Ledger project with tagged states from a plain application to
 offline evaluation. Detailed contracts remain in the linked operating,
 storage, privacy, and lesson documents.
 
-Guided setup and the maintained Pi memory extension ship in v2.11. See
-[L23](lessons/L23-guided-setup.md) for the tested boundary.
+Guided setup and the maintained Pi memory extension shipped in v2.11. The v2.12
+harness registry adds first-class Codex project setup without granting project
+trust. See [L03](lessons/L03-first-project.md) and
+[L23](lessons/L23-guided-setup.md) for the tested boundaries.
+Version 2.13 adds local Git-linked work evidence around all generated harness
+launchers; [L13](lessons/L13-session-evidence.md) covers its privacy and
+retention contract.
 
 ## The three-layer model
 
@@ -33,7 +38,7 @@ Run setup in that order, then confirm `cairn doctor`, `cairn sync --check`, and
 | 2 | Wiki, alignment, graph, repository/security review | Tracked derived knowledge and quality workflows are sufficient |
 | 3 | Backup, migration, multiple-machine routing | Storage placement and recovery are predictable |
 | 4 | Document RAG or context exploration | An optional external corpus or faster repository exploration is justified |
-| 5 | Trajectories, notes, compaction, artifacts | Local session evidence has an explicit retention purpose |
+| 5 | Trajectories, notes, compaction, artifacts, Git work evidence | Local session evidence has an explicit retention purpose |
 | 6 | Typed nodes and capability governance | Filtering and centrally inspectable feature state are needed |
 | 7 | Evaluation and ablation | A concrete change needs bounded measurement |
 | 8 | Validated skill improvement | Repeated resolved hindsight warrants a measured skill change |
@@ -52,7 +57,8 @@ prerequisites for ordinary memory.
 | Wiki and alignment | `/wiki-ingest`, `/wiki-query`, `/wiki-lint`, alignment files | Written only when invoked; reviewable `.planning/` artifacts | Re-run lint, inspect source citations, revert tracked changes normally | `course-02-memory` |
 | Local code graph | `cairn graph build|query|status|diff|explain|path`; `/graphify` delegates | Default off; optional isolated `graphify` executable; incremental work under `graphify-out/`, published view under `.planning/graphs/` | Ignore both derived locations; check status and source before trusting a result; use `--force` only after intentional deletion; uninstall adapters separately | `course-08-graph` |
 | Repository quality | `/repo-review`, `/security-audit` | On-demand workflow; findings are hypotheses until reproduced | Require file/line evidence and regression tests | `course-03-quality` |
-| Guided project setup | `cairn setup PATH --git init\|existing\|none --harness LIST --memory local\|none --yes` | Reconciles only selected project assets; private `.ai/cairnkeep.json`; machine sync is never automatic | Repeat deterministically, run doctor, or replay its recovery command; Git-less mode remains limited | `course-12-guided-setup` |
+| Guided project setup | `cairn setup PATH --git init\|existing\|none --harness LIST --memory local\|none --yes` | Reconciles only selected project assets from one harness registry; private `.ai/cairnkeep.json`; machine sync is never automatic | Repeat deterministically, run doctor, or replay its recovery command; Git-less mode remains limited | `course-12-guided-setup` |
+| Codex project memory | Select `--harness codex --memory local` | Writes `.codex/config.toml` plus POSIX/native Windows launchers; local stdio; user-wide configuration and trust remain untouched | Review the MCP table, accept Codex project trust, run doctor, and relaunch; uninstall is backup-first | `course-01-bootstrap` |
 
 ## Storage and optional topology
 
@@ -78,6 +84,7 @@ prerequisites for ordinary memory.
 | Note enrichment | Distillation plus separate enrichment flag, endpoint, key, and model | No server restart for the offline job | Failure leaves deterministic note usable; unset enrichment flag | `course-05-evidence` |
 | Compaction continuity | `CAIRN_COMPACTION_CAPTURE=1` | Sync assets and relaunch harness | Inspect provenance/age; remove retained local artifacts explicitly | `course-05-evidence` |
 | Artifact tools | `CAIRN_ARTIFACT_STORE=1`; HTTP needs a second flag and existing HTTP auth | Restart MCP server when tool exposure changes | `cairn artifact list|show|delete|prune` with dry runs | `course-05-evidence` |
+| Git-linked work evidence | `CAIRN_WORK_EVIDENCE=1`; optional patch also needs `CAIRN_WORK_EVIDENCE_PATCH=1` and the artifact store | Relaunch through a generated harness launcher | `cairn evidence list|show|delete|prune|doctor`; local only, no restore/apply | `course-05-evidence` |
 | Typed nodes/import | `CAIRN_TYPED_MEMORY_NODES=1` | Restart MCP server; tool schema changes | Hard-filter search; dry-run, replay-safe import; `cairn doctor --repair` only for derived state | `course-05-evidence` |
 | Capability contract | `CAIRN_CAPABILITY_CONTRACT=1` | MCP changes require restart; operating changes apply next invocation | `cairn capabilities list|status|enable|disable|reset|logging`; digest identifies state only | `course-06-governance` |
 | Evaluation | `CAIRN_EVAL=1` for the coordinator process | No harness chosen by Cairnkeep | `validate` before `run`; inspect report, missingness and evidence scope; dry-run prune/delete | `course-07-evaluation` |
@@ -88,6 +95,8 @@ prerequisites for ordinary memory.
 ## Harness and maintenance checks
 
 - Use a generated launcher so project environment and hooks are repeatable.
+- For Codex, review `.codex/config.toml` and accept project trust; no machine
+  sync is required for the memory-only integration.
 - Run `cairn sync --check` after every core upgrade; apply only reported drift.
 - Run `cairn sync-pi --check` when the Pi memory/trajectory/graph assets are installed.
 - Run `cairn sync-kimi --check` when the optional Kimi graph Skill is installed.

package/docs/learning/README.md

@@ -8,7 +8,8 @@ publication material.
 
 Choose the shortest track that matches your goal:
 
-- [Quickstart](tracks/quickstart.md) - prove the core value in about 75 minutes.
+- [Quickstart](tracks/quickstart.md) - prove the core value, including the
+  one-command Codex project path and the explicit Pi lifecycle, in about 110 minutes.
 - [Practitioner](tracks/practitioner.md) - adopt Cairnkeep in daily project work.
 - [Evidence and evaluation](tracks/evidence-and-evaluation.md) - inspect optional
   session evidence, govern capabilities, and measure changes without overstating
@@ -33,7 +34,7 @@ expanded only after their labs are executable.
 | L00 | [Why Cairnkeep?](lessons/L00-why-cairnkeep.md) | Ready | 10 min |
 | L01 | [Try it safely](lessons/L01-safe-trial.md) | Ready | 15 min |
 | L02 | [Install the local workflow](lessons/L02-installation.md) | Ready | 25 min |
-| L03 | [Bootstrap the first project](lessons/L03-first-project.md) | Ready | 25 min |
+| L03 | [Set up the first project](lessons/L03-first-project.md) | Ready | 25 min |
 | L04 | [Memory fundamentals](lessons/L04-memory-fundamentals.md) | Brief | 35 min |
 | L05 | [The daily workflow](lessons/L05-daily-workflow.md) | Brief | 40 min |
 | L06 | [Repository review and security](lessons/L06-repository-quality.md) | Brief | 45 min |
@@ -43,7 +44,7 @@ expanded only after their labs are executable.
 | L10 | [Faster context exploration](lessons/L10-context-exploration.md) | Brief | 30 min |
 | L11 | [Containers and isolation](lessons/L11-containers.md) | Brief | 40 min |
 | L12 | [Managed overlays](lessons/L12-managed-overlays.md) | Brief | 45 min |
-| L13 | [Session evidence and hindsight](lessons/L13-session-evidence.md) | Brief | 45 min |
+| L13 | [Session evidence and hindsight](lessons/L13-session-evidence.md) | Brief | 60 min |
 | L14 | [Typed memory and controlled import](lessons/L14-typed-memory.md) | Brief | 40 min |
 | L15 | [Capability governance](lessons/L15-capability-governance.md) | Brief | 35 min |
 | L16 | [Evaluation and ablation](lessons/L16-evaluation.md) | Brief | 50 min |

package/docs/learning/lessons/L00-why-cairnkeep.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.11.0
+**Tested with:** Cairnkeep 2.13.0
 
 ## Outcome
 

package/docs/learning/lessons/L01-safe-trial.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.11.0
+**Tested with:** Cairnkeep 2.13.0
 
 ## Outcome
 
@@ -26,7 +26,7 @@ ephemeral; the named course volume is persistent.
 1. Pull the public image:
 
    ```bash
-   podman pull ghcr.io/cairnkeep/cairnkeep:2.11.0
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.13.0
    ```
 
 2. Start the stdio server with a read-only root filesystem and no Linux
@@ -38,7 +38,7 @@ ephemeral; the named course volume is persistent.
      --read-only --cap-drop=all --security-opt=no-new-privileges \
      --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
      --volume cairnkeep-course-data:/data:Z,U \
-     ghcr.io/cairnkeep/cairnkeep:2.11.0 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.13.0 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it

package/docs/learning/lessons/L02-installation.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.11.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.13.0 and Node.js 22 or newer
 
 ## Outcome
 
@@ -13,7 +13,8 @@ layer, and distinguish a complete installation from a partial one.
 ## Prerequisites
 
 - Node.js 22 or newer and npm.
-- Claude Code installed for the commands below. OpenCode, Kimi Code, and Qwen Code users
+- Claude Code installed for the full operating-layer commands below. Codex CLI
+  users can take the project-scoped path in L03. OpenCode, Kimi Code, and Qwen Code users
   should follow the equivalent setup in
   [the operating guide](../../operating.md).
 - Permission to install an npm package globally for your user.
@@ -26,8 +27,13 @@ A complete setup has three independent parts:
 2. the MCP registration used by the harness;
 3. the operating layer containing commands, agents, hooks, and templates.
 
-`cairn bootstrap` configures a project later; it does not perform the first two
-machine-level steps.
+`cairn setup` configures a project later; it does not perform the first two
+machine-level steps. `cairn bootstrap` remains the compatibility primitive for
+scripts and overlays that already own their setup policy.
+
+Codex is the simpler memory-only exception: L03 writes its project-scoped MCP
+entry and launcher, so it needs no user-wide MCP registration or machine-level
+sync. Codex project trust remains an explicit operator decision.
 
 ## Exercise
 
@@ -41,7 +47,7 @@ machine-level steps.
 2. Install Cairnkeep:
 
    ```bash
-   npm install --global @cairnkeep/cli@2.11.0
+   npm install --global @cairnkeep/cli@2.13.0
    cairn --version
    ```
 
@@ -78,7 +84,7 @@ machine-level steps.
    Invoke-Expression (& cairn completion powershell | Out-String)
    ```
 
-   Bootstrap emits `.cmd` launchers on Windows; use
+   Project setup emits `.cmd` launchers on Windows; use
    `.\.ai\start-claude.cmd` instead of the Unix `.sh` launcher.
 
 ## Verify
@@ -108,8 +114,9 @@ installation.
 This registration starts `cairn memory-server` locally as a stdio child. It
 does not discover a server, send memory to a remote host, configure embeddings,
 enable session capture, or enable an optional document-RAG integration. Pi uses
-the separate `cairn sync-pi` trajectory and graph-prompt adapter and still needs
-a user-selected bridge if Pi should expose MCP memory tools.
+the separate, explicit `cairn sync-pi --apply` command to install Cairnkeep's
+maintained local stdio memory extension, trajectory extension, and graph prompt.
+Project setup records the Pi selection but never changes machine-level Pi assets.
 
 Kimi Code can use the same memory server through its generated
 `.ai/start-kimi.sh` launcher, but its HTTP MCP configuration requires a literal
@@ -145,4 +152,4 @@ Do not delete memory stores as part of a course cleanup.
 - `sync --check` is the non-writing drift check.
 - Default stdio memory is local.
 
-Next: [L03 - Bootstrap the first project](L03-first-project.md).
+Next: [L03 - Set up the first project](L03-first-project.md).

package/docs/learning/lessons/L03-first-project.md

@@ -1,14 +1,15 @@
-# L03 - Bootstrap the first project
+# L03 - Set up the first project
 
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.11.0
+**Tested with:** Cairnkeep 2.13.0
 
 ## Outcome
 
-You can bootstrap a disposable project, verify its wiring, store one accepted
-fact, and recall it from a new harness session.
+You can use the guided setup contract on an empty directory, choose Claude Code
+or Codex CLI, verify its Git and harness wiring, store one accepted fact, and
+recall it from a new session.
 
 ## Prerequisites
 
@@ -18,22 +19,32 @@ fact, and recall it from a new harness session.
 
 ## Exercise
 
-1. Create a disposable repository:
+1. Create an empty disposable project directory:
 
    ```bash
    mkdir -p "$HOME/cairnkeep-course/first-project"
    cd "$HOME/cairnkeep-course/first-project"
-   git init
-   printf '# Cairnkeep course project\n' > README.md
    ```
 
-2. Bootstrap the project:
+2. Choose one harness and run the deterministic form of guided setup. The
+   explicit flags make the
+   exercise reproducible while exercising the same preflight as interactive
+   `cairn setup`:
 
    ```bash
-   cairn bootstrap "$PWD"
+   # Full operating-layer route from L02:
+   cairn setup "$PWD" --git init --harness claude --memory local --yes
+
+   # Or the self-contained Codex memory route:
+   # cairn setup "$PWD" --git init --harness codex --memory local --yes
    cp .ai/env.example .ai/.env
    ```
 
+   Setup must create the Git repository, generate only the selected harness
+   assets, and write the private `.ai/cairnkeep.json` setup record. Codex also
+   receives `.codex/config.toml`; review it and accept Codex's project-trust
+   prompt before launching.
+
 3. Keep optional endpoint and model values unset for this local exercise. Run
    diagnostics:
 
@@ -45,10 +56,11 @@ fact, and recall it from a new harness session.
    and evaluation flags unset. The quickstart proves core memory without
    silently changing the amount of retained data.
 
-4. Launch Claude Code through the generated project launcher:
+4. Launch the selected harness through its generated project launcher:
 
    ```bash
    ./.ai/start-claude.sh
+   # Codex route: ./.ai/start-codex.sh
    ```
 
 5. In the harness, store a deliberately synthetic convention:
@@ -79,9 +91,11 @@ The lesson is complete only if:
 
 | Symptom | Cause | Recovery |
 |---|---|---|
-| Launcher is missing | A different directory was bootstrapped | Run `pwd`, then bootstrap that exact path |
+| Setup refuses the target | The directory is non-empty or its Git state conflicts with `--git init` | Preserve the directory, inspect it, then select `--git existing` or use a genuinely empty disposable path |
+| Launcher is missing | A different directory was configured or Claude was not selected | Run `pwd`, inspect `.ai/cairnkeep.json`, then replay the recovery command from `cairn doctor` |
 | `.ai/.env` is missing | Only the example is generated | Copy `.ai/env.example` to `.ai/.env` |
-| `cairn-memory` is unavailable | L02 MCP registration is absent or stale | Run `claude mcp get cairn-memory`, repair it, then restart Claude Code |
+| `cairn-memory` is unavailable in Claude | L02 MCP registration is absent or stale | Run `claude mcp get cairn-memory`, repair it, then restart Claude Code |
+| `cairn-memory` is unavailable in Codex | Project configuration was skipped or the project is not trusted | Review/merge `.codex/config.toml`, rerun setup, then accept project trust and relaunch |
 | Slash commands are unknown | Operating assets were not loaded | Run `cairn sync --check`, apply if needed, then restart the harness |
 | Recall works only in the first session | Sessions used different storage routing | Compare launchers and environment, then inspect `cairn memory path` |
 
@@ -105,13 +119,18 @@ synthetic memory through the normal memory review/delete workflow if required.
 
 ## Optional challenge
 
-Repeat bootstrap with `--untracked` in another disposable Git repository, then
-inspect `.git/info/exclude` to see how contributor mode avoids shared changes.
+Create another disposable Git repository and run `cairn bootstrap --untracked`
+there. Inspect `.git/info/exclude` to see how the compatibility primitive keeps
+contributor-mode scaffolding out of shared changes.
 
 ## Recap
 
-- Bootstrap is project-specific and follows machine setup.
+- Guided setup owns target preflight, Git choice, harness selection, and a
+  private reconciliation record.
+- Bootstrap remains available for compatibility and contributor workflows.
 - The generated launcher establishes a repeatable project environment.
+- Codex memory setup is project-scoped and does not silently grant trust or
+  modify the user-wide Codex configuration.
 - Persistence is proven only after a new session recalls the accepted fact.
 
 Next: [L04 - Memory fundamentals](L04-memory-fundamentals.md).