@cairnkeep/cli 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [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 +336,8 @@ 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.12.0...HEAD
+[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,8 +9,25 @@
 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
 
@@ -27,8 +44,8 @@ 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.
 
 ## Compatibility
 
@@ -43,7 +60,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 +77,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 +157,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 +197,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

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

@@ -13,13 +13,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 +202,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.12.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 |
@@ -35,7 +36,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 +59,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 +79,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 |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.11.0
+**Baseline:** Cairnkeep 2.12.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,10 @@ 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.
 
 ## The three-layer model
 
@@ -52,7 +54,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
 
@@ -88,6 +91,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 |

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.12.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.12.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.12.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.12.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.12.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.12.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.12.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).

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.12.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.12.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.12.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.12.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.12.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.12.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.12.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/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