@cairnkeep/cli 2.9.0 → 2.12.0

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

@@ -0,0 +1,142 @@
+# L23 - Guided setup and Pi memory
+
+**Status:** Ready
+**Track:** Quickstart and Operator
+**Time:** 35 minutes
+**Tested with:** Cairnkeep 2.12.0; Pi 0.84.1; Node.js 22, 24, and 26
+
+## Outcome
+
+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.
+- Pi 0.84.1 or newer.
+- A disposable parent directory containing no credentials, secrets, private
+  state, or identifying project data.
+
+## Exercise
+
+Start with a missing target. The explicit flags make this deterministic and
+safe to replay from a non-interactive or non-TTY process:
+
+```bash
+lab=/tmp/cairnkeep-guided-setup-lab
+cairn setup "$lab" --git init --harness pi --memory local --yes
+cd "$lab"
+cairn doctor
+```
+
+Setup performs its classification before it creates `.ai`, `.planning`, or
+`.agentfs`. It initializes Git only because `--git init` authorizes that action,
+records the selected Pi harness in private `.ai/cairnkeep.json`, and reports
+created, updated, unchanged, and skipped assets. Repeating the same `cairn
+setup` command should report the managed files as unchanged.
+
+Project setup never changes the Pi installation. Apply and check machine assets
+explicitly, then diagnose the project again:
+
+```bash
+cairn sync-pi --apply
+cairn sync-pi --check
+cairn doctor
+./.ai/start-pi.sh
+```
+
+In the disposable Pi session, list the registered Cairnkeep tools and make one
+harmless read-only memory call. The extension starts `cairn memory-server` as a
+local stdio child in this project; it does not select HTTP or a remote server.
+Cancel one in-flight call and confirm a later read still works. Exit Pi normally
+and confirm shutdown completes rather than leaving a memory-server child
+running. Cancellation is per call and an awaited session shutdown owns child
+termination.
+
+The bridge discovers the effective server catalog. Full, read-only, and custom
+MCP profiles therefore expose only the tools allowed by the server. It preserves
+tool names, stable order, input and output schemas, original content,
+`structuredContent`, `_meta`, and the exact Phase 21 annotations in trusted
+bridge metadata and result `details`. Pi 0.84.1 has no native annotations field
+in its public tool API: do not interpret this preservation as native
+model-facing annotation propagation and do not invent such a field.
+
+To see the intentional Git-less boundary in another empty disposable target:
+
+```bash
+limited=/tmp/cairnkeep-guided-setup-limited
+cairn setup "$limited" --git none --harness pi --memory local --yes
+cd "$limited"
+cairn doctor
+```
+
+The result is `limited`, not `complete`. Launchers and local stdio memory remain
+available, but repository-identity and Git-dependent features do not. An
+existing non-Git tree is never initialized without explicit `--git init`.
+
+## Recovery exercise
+
+Delete one setup-owned launcher only in the disposable project, diagnose it,
+then replay the exact recovery command:
+
+```bash
+cd /tmp/cairnkeep-guided-setup-lab
+rm .ai/start-pi.sh
+cairn doctor
+cairn setup . --git init --harness pi --memory local --yes
+cairn sync-pi --apply
+cairn sync-pi --check
+cairn doctor
+```
+
+Doctor reports project-state drift separately from missing or drifted Pi
+machine assets. Setup repairs only recorded project assets; `cairn sync-pi
+--apply` repairs only the package-owned Pi extension and prompt paths.
+
+Preview backup-first removal before confirming it:
+
+```bash
+cairn uninstall --dry-run /tmp/cairnkeep-guided-setup-lab
+cairn uninstall --yes /tmp/cairnkeep-guided-setup-lab
+```
+
+Inspect the printed backup bundle and generated revert script. Durable memory
+and context packs remain unless their separate purge flags are supplied.
+
+## Common failures
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| Setup refuses a missing target | The non-interactive command omitted an explicit choice or `--yes` | Supply the target, `--git`, `--harness`, `--memory`, and `--yes` together |
+| Setup refuses `--git existing` | The target is not inside a Git work tree | Choose an existing repository, or explicitly authorize `--git init`; use `--git none` only when limited mode is intended |
+| Doctor reports missing or drifted Pi assets | Project setup selected Pi but machine sync is incomplete | Run `cairn sync-pi --apply`, then `cairn sync-pi --check` and `cairn doctor` |
+| A cancelled call ends the session | The Pi/bridge version does not satisfy the per-call cancellation contract | Preserve sanitized diagnostics, close the session, and do not claim release readiness |
+| Pi exits but a child process remains | Shutdown did not complete or the tested extension drifted | Preserve process-state evidence, run the sync check, and treat the release gate as failed |
+| A client expects native annotation hints | Pi's public tool API has no annotations field | Inspect trusted bridge metadata/result `details`; never claim native propagation |
+
+## Privacy and trust boundary
+
+`.ai/cairnkeep.json` is private setup state. It records selected modes,
+harnesses, and setup-owned asset digests—not credentials, secrets, endpoints, or
+absolute paths. The Pi bridge is a local child-process boundary: it inherits the
+operator environment needed by the local server, retains only bounded stderr
+for failure diagnostics, and does not log tool arguments or results.
+
+Use only synthetic values in exercises and evidence. Do not publish executable
+paths, usernames, hostnames, repository names, environment values, child output,
+memory content, or private state. The bridge adds tools only; it does not run
+prompts, approve skills, create an autonomous loop, or add remote access.
+
+## Release boundary
+
+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.
+Those executable paths must differ, but both may report 0.84.1 while that is the
+current release; a future registry advance requires its new exact version.

package/docs/learning/tracks/operator.md

@@ -2,7 +2,7 @@
 
 **Audience:** advanced users and platform maintainers
 **Prerequisite:** Practitioner track; L13 before operating captured evidence
-**Total time:** about 5 hours
+**Total time:** about 5 hours 35 minutes
 
 1. [L09 - Domain knowledge with RAG](../lessons/L09-domain-knowledge.md)
 2. [L10 - Faster context exploration](../lessons/L10-context-exploration.md)
@@ -12,11 +12,16 @@
 6. [L16 - Evaluation and ablation](../lessons/L16-evaluation.md)
 7. [L20 - Least-authority MCP tool profiles](../lessons/L20-mcp-tool-profiles.md)
 8. [L21 - Immutable context packs and skill approval](../lessons/L21-context-packs.md)
+9. [L22 - Operate Cairnkeep on native Windows](../lessons/L22-native-windows.md)
+10. [L23 - Guided setup and Pi memory](../lessons/L23-guided-setup.md)
 
 All modules are optional. The track is complete when the operator can add and
 remove each integration without breaking the standalone local workflow and can
-explain its storage, network, credential, and rollback boundaries.
+explain its storage, network, credential, and rollback boundaries. L23 adds the
+v2.11 setup/Pi lifecycle only after the earlier storage, governance, trust, and
+native-platform boundaries.
 
 Hands-on spine: `course-04-operation`, `course-06-governance`, and
-`course-07-evaluation`, and `course-10-trust-context` in the public
+`course-07-evaluation`, `course-10-trust-context`, and
+`course-12-guided-setup` in the public
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs).

package/docs/learning/tracks/quickstart.md

@@ -1,17 +1,22 @@
 # Quickstart Track
 
 **Audience:** developers evaluating Cairnkeep
-**Total time:** about 75 minutes
+**Total time:** about 110 minutes
 **Infrastructure:** local machine; Podman is optional
 
 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.
+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` in the public
+Hands-on spine: `course-00-app` through `course-01-bootstrap`, followed by
+`course-12-guided-setup`, in the public
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs).

package/docs/native-windows.md

@@ -0,0 +1,136 @@
+# Native Windows operation
+
+Cairnkeep supports Windows x64 directly from PowerShell and Command Prompt.
+The supported path does not invoke WSL, Git Bash, or a POSIX shell. Windows
+ARM64 may use Windows x64 emulation, but it is not a native ARM64 support claim
+until the database dependency publishes and passes an ARM64 Windows binding.
+
+## Install and guided setup
+
+Prerequisites are Node.js 22 or newer, npm, and the harness you intend to use.
+Git is required for `--git init`, `--git existing`, Git-backed context packs,
+and `--untracked` bootstrap. Explicit `--git none` provides the same documented
+limited mode as POSIX setup.
+The optional `sqlite3.exe` command enables WAL-safe `cairn memory export`.
+
+```powershell
+npm install --global @cairnkeep/cli
+cairn version
+$Project = 'C:\src\my-project'
+cairn setup $Project --git init --harness claude,pi --memory local --yes
+cairn sync --apply
+cairn sync-pi --apply
+cairn sync-pi --check
+Set-Location $Project
+cairn doctor
+.\.ai\start-claude.cmd
+```
+
+Guided setup exposes the same target classification, confirmation, Git,
+harness, memory, reconciliation, counts, JSON result, diagnostics, launch, and
+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.
+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`.
+
+## MCP and operating assets
+
+Register the stdio server exactly as on other platforms:
+
+```powershell
+claude mcp add cairn-memory -s user -- cairn memory-server
+cairn sync --check
+```
+
+`cairn sync --apply` installs native `.cmd` hook transports and registers them
+in the harness settings. The hook logic itself is Node and remains fail-open
+except for capability admission, which preserves its fail-closed contract.
+`cairn sync-pi` and `cairn sync-kimi` use native filesystem operations. Pi sync
+installs the maintained local stdio memory extension explicitly; setup does not
+start it or add remote access. Pi 0.84.1 is the validated minimum; the v2.11
+release matrix also exercised a separate installation of the exact
+registry-current Pi release. The two executable paths were distinct, while
+both reported 0.84.1 because that was also the current release.
+
+## PowerShell completion
+
+Load completion for the current session:
+
+```powershell
+Invoke-Expression (& cairn completion powershell | Out-String)
+```
+
+Place the same expression in `$PROFILE` to load it in future sessions.
+
+## Storage and permissions
+
+Cairnkeep retains the same storage paths and formats. `~` resolves to the
+Windows user profile. Sensitive managed JSON files do not rely on meaningless
+Unix mode bits: Cairnkeep removes inherited ACLs and grants access only to the
+current SID, Local System, and built-in Administrators. Context-pack content is
+digest-verified before receiving restricted ACLs and a read-only attribute.
+The guided setup state uses this same private ACL and contains no credentials,
+endpoints, or absolute paths.
+
+The embedded AgentFS database driver retains Windows file handles until its
+Node process exits. Cairnkeep therefore runs artifact-store operations in
+short-lived local Node helpers on Windows. Hard deletion and pruning build a
+compacted replacement, release all handles when the helper exits, and only then
+atomically replace the live database. This does not add a daemon, network
+access, or background synchronization.
+
+`cairn memory import` uses an internal path-validating tar/gzip reader. Export
+uses `sqlite3.exe` `.backup` for a consistent snapshot of each live WAL database
+and then writes the same portable `.tgz` format used on Unix.
+
+## Scheduling and process cleanup
+
+`cairn audit-timer` registers the opt-in `Cairnkeep Memory Audit` task through
+Windows Task Scheduler. `--render-only DIR` writes the command without changing
+the scheduler. Evaluation cancellation targets the exact child PID and its
+descendant tree through `taskkill.exe /T`, then escalates through `/F` after the
+configured grace period.
+
+## Uninstall and recovery
+
+Preview first, then confirm explicitly:
+
+```powershell
+cairn uninstall --dry-run C:\src\my-project
+cairn uninstall --yes C:\src\my-project
+```
+
+Uninstall removes only managed assets and their hook registrations. Before
+mutation it creates a timestamped bundle under
+`~/cairnkeep-uninstall-backups/` containing exact files, a strict manifest, and
+`revert.ps1`. Durable memory and context packs remain unless their separate
+purge flags are supplied.
+
+## Verification boundary
+
+The release gate runs from `windows-latest` using PowerShell for Node 22, 24,
+and 26. It builds the TypeScript server, runs its Node tests, exercises guided
+setup and bootstrap, sync/check (including Pi), native hooks, safe archive
+import, backup-first uninstall, spaces and Unicode paths, packs the npm artifact,
+installs it globally, invokes `cairn.cmd`, and runs `cairn doctor`. Git Bash is
+never selected as the job shell.

package/docs/operating.md

@@ -7,20 +7,23 @@ Cairnkeep has three moving parts:
 
 1. **The memory server** (`cairn-memory`) — an MCP server your harness talks to.
 2. **The project scaffold** — `.ai/` launchers and the `.planning/` knowledge
-   layer, written by `cairn bootstrap`.
+   layer, written by `cairn setup` or the compatibility-oriented
+   `cairn bootstrap` primitive.
 3. **The operating layer** — the commands, agents, and hooks that live in your
    harness config and drive the workflow.
 
-`cairn bootstrap` only does step 2. Steps 1 and 3 are one-time-per-machine
-installs. This guide covers all three in order.
+`cairn setup` is the recommended project entry point. `cairn bootstrap`
+retains its established deterministic behavior for existing automation. Steps
+1 and 3 are one-time-per-machine installs; project setup reports the explicit
+sync command but never runs it automatically. This guide covers all three.
 
 ## Prerequisites
 
 - Node.js 22 or newer (for the memory server) and a supported harness. Claude
   Code and OpenCode receive the full operating layer. Kimi Code receives the
   memory MCP, launcher, and opt-in graph Skill; Qwen Code receives the memory
-  MCP and launcher. Pi receives its native trajectory adapter, graph prompt,
-  and launcher.
+  MCP and launcher. Pi receives a maintained local stdio MCP extension, native
+  trajectory adapter, graph prompt, and launcher after explicit machine sync.
 - Optional: the `sqlite3` CLI for `cairn memory export`. Runtime memory and
   `cairn memory import` do not require it.
 - Optional: an OpenAI-compatible LLM endpoint for memory extraction and
@@ -29,6 +32,12 @@ installs. This guide covers all three in order.
 - Optional: rootless Podman for the containerized memory server and isolated
   workspace base described in [Containers](containers.md).
 
+Native Windows x64 is supported directly from PowerShell or Command Prompt;
+WSL and Git Bash are not required. The npm package installs a Node entry point,
+and bootstrap emits `.cmd` plus PowerShell launchers. See
+[Native Windows operation](native-windows.md) for the exact setup and recovery
+contract. Windows ARM64 currently uses x64 emulation.
+
 ## Shell completion
 
 Generate completion definitions directly from the CLI:
@@ -37,12 +46,86 @@ Generate completion definitions directly from the CLI:
 cairn completion bash
 cairn completion zsh
 cairn completion fish
+cairn completion powershell
 ```
 
 Distributions can install these outputs into the platform's normal completion
 directories. They can also be loaded for the current shell, for example with
 `source <(cairn completion bash)`.
 
+In PowerShell, load completion for the current session with:
+
+```powershell
+Invoke-Expression (& cairn completion powershell | Out-String)
+```
+
+## Guided project setup
+
+Interactive terminals may run `cairn setup` and answer the target, Git,
+harness, memory, and confirmation questions. Automation must make every choice
+explicit:
+
+```bash
+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,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
+remain unavailable, and both setup output and `cairn doctor` say so. A missing
+or empty interactive target recommends initialization and asks before writing;
+an existing non-Git tree is never initialized silently.
+
+Setup first classifies the target and Git state without writing, then creates or
+reconciles only the selected project launchers and common scaffold assets.
+Identical managed files remain unchanged, changed managed files are updated,
+and unrelated files are preserved. The result reports created, updated,
+unchanged, and skipped counts; `cairn doctor`; an exact launcher per selected
+harness; and the deterministic setup command to use for recovery. `--json`
+returns the same schema-v1 result. The private mode-`0600`
+`.ai/cairnkeep.json` record stores the package version, Git and memory modes,
+selected harnesses, and digests/modes/template identifiers for setup-owned
+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. 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
+cairn sync-pi --apply                 # Pi extension and prompt
+cairn sync-pi --check
+cd /path/to/project && cairn doctor
+./.ai/start-pi.sh
+```
+
+`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
@@ -206,8 +289,9 @@ cairn graph diff
 ```
 
 The same direct CLI works with Qwen Code, Codex, and other shell-capable
-clients. This does not add a Pi MCP bridge or imply that those harnesses receive
-the rest of Cairnkeep's operating layer.
+clients. Pi sync separately installs Cairnkeep's maintained local stdio MCP
+extension; the graph prompt remains a thin adapter and does not expand the rest
+of Pi's operating surface.
 
 All six modes delegate to `cairn graph`. Managed builds run Graphify's local
 code-only `update` path with provider credentials removed from the subprocess
@@ -217,6 +301,9 @@ so Graphify cannot re-index its own generated HTML/report/JSON. Managed builds
 do not perform Graphify's optional semantic document extraction. Prefer exact
 function, class, or file names; broad natural-language graph queries are less
 precise. Cairnkeep does not install or update Graphify automatically.
+Set `CAIRN_GRAPHIFY_BINARY` to override the `graphify` command when Graphify is
+installed at a specific path. Native executables run directly; `.js`, `.mjs`,
+and `.cjs` helpers run through the active Node runtime on every platform.
 
 Graphify also maintains an incremental `graphify-out/` work directory at the
 repository root. It is separate from Cairnkeep's published
@@ -299,26 +386,52 @@ configuration, approval behavior, and overlay guidance.
 
 ## Setup order (Pi)
 
-Pi trajectory capture uses the same project scaffold and store. Its sync also
-installs a thin `/graphify` prompt into Pi's agent root:
+Pi uses the same project scaffold and local memory store. Its explicit sync
+installs the maintained memory extension, native trajectory extension, and thin
+`/graphify` prompt into Pi's agent root:
 
 ```bash
 npm install -g @cairnkeep/cli
 cairn sync-pi --apply                    # default: ~/.pi/agent
-cairn bootstrap /path/to/project
+cairn setup /path/to/project --git init --harness pi --memory local --yes
 cp /path/to/project/.ai/env.example /path/to/project/.ai/.env
 cd /path/to/project && cairn doctor && ./.ai/start-pi.sh
 ```
 
-This command does not install an MCP bridge. Cairnkeep does not own or select a
-Pi bridge; if you want `cairn memory-server` tools inside Pi as well, configure
-a user-chosen Pi extension/bridge separately.
+The memory extension starts `cairn memory-server` as a local stdio child from
+the project root. It dynamically discovers the effective server catalog, so
+feature gates, capability state, and the current MCP tool profile remain
+authoritative. It does not contain a second hard-coded catalog. Startup is
+bounded to 10 seconds, calls to 30 seconds, results to 4 MiB, and retained child
+stderr to the newest 16 KiB. Cancellation is propagated, child or protocol
+failure is surfaced, and session shutdown closes the child.
+
+Tool names, descriptions, input and output schemas, content,
+`structuredContent`, `_meta`, and failure behavior cross the bridge without
+semantic rewriting. The exact MCP annotations are preserved in the trusted Pi
+result `details`, together with the discovered tool metadata and original
+content. Pi 0.84.1 has no native annotations field in its public tool API, so
+Cairnkeep does not claim native model-facing annotation propagation or invent a
+substitute field.
+
+The bridge is tools-only: it does not run prompts, activate context-pack skills,
+create an autonomous loop, add remote access, or bypass server-side tool
+restrictions. Removing `MCP_HTTP_PORT` from the child environment deliberately
+keeps this integration on local stdio.
 
 Use `cairn sync-pi --check` to report drift without writing, or
 `--live-root DIR` to target an isolated Pi agent root. The command owns exactly
-`extensions/cairnkeep-trajectory.ts` and `prompts/graphify.md`; `cairn
-uninstall --pi-live-root DIR` removes those files backup-first and leaves every
-other Pi asset untouched.
+`extensions/cairnkeep-memory.ts`, `extensions/cairnkeep-trajectory.ts`, and
+`prompts/graphify.md`; `cairn doctor` reports a selected Pi extension that is
+missing or drifted and points to `cairn sync-pi --apply`. `cairn uninstall
+--pi-live-root DIR` removes those files backup-first and leaves every other Pi
+asset untouched.
+
+Pi 0.84.1 is the validated minimum supported version for this extension. The
+v2.11 release passed the complete setup and bridge matrix on separate Pi 0.84.1
+minimum and registry-current installations, Node.js 22, 24, and 26, Bash 3.2,
+and native Windows. The two Pi executable paths differed, while both reported
+0.84.1 because that was also the registry-current release.
 
 The extension listens for Pi's native `session_shutdown` event and reads only
 the active branch from the read-only session manager. It returns before doing
@@ -381,6 +494,7 @@ vendor or host.
 | `CAIRN_HARNESS_STATE_DIR` | Optional absolute local root for recoverable native capability leases (default `${XDG_STATE_HOME:-~/.local/state}/cairn/harness`) |
 | `CAIRN_GIT_PROVIDER` | Git host for collaboration commands: `github`\|`gitlab`\|`codeberg`\|`forgejo`\|`none`. See [git-providers.md](git-providers.md) |
 | `CAIRN_ROUTE_ENDPOINT` | Base URL of an already-running token-miser routing/tiering proxy (unset → the `route_check` tool is inert) |
+| `CAIRN_GRAPHIFY_BINARY` | Optional Graphify command/path override; JavaScript helpers run through the active Node runtime (default `graphify` from `PATH`) |
 | `CAIRN_EXPLORE_BINARY` | Absolute path to the `token_miser` binary used by `context_explore` (unset → the tool throws at call time) |
 | `CAIRN_EXPLORE_REPO_ROOT` | Default repo root for `context_explore` when no per-call `repo_root` is given (unset + no param → the tool throws) |
 | `CAIRN_EXPLORE_CACHE` | Caches `context_explore` results keyed on query + repo HEAD + dirty-state; default ON, set to `0` to disable |
@@ -772,13 +886,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
@@ -809,6 +923,13 @@ rebuild only derived indexes/dedupe/pointers from valid authoritative records.
 Unsupported schema, SQLite failure, invalid full records, or digest corruption
 fails untouched with guidance to preserve the database before manual recovery.
 
+When `.ai/cairnkeep.json` exists, doctor also validates its private state,
+selected assets, digests, and modes. It reports `limited` for explicit
+`--git none`, fails an incomplete or drifted setup with the recorded
+deterministic `cairn setup` recovery command, and checks the Pi machine
+extension when Pi was selected. `cairn sync-pi --apply` repairs that
+machine-level drift; setup itself never performs the sync.
+
 ### Evaluation harness (opt-in)
 
 `cairn eval` is a local, serial experiment coordinator. It is disabled unless
@@ -897,8 +1018,9 @@ claims.
 SIGINT or SIGTERM stops schedule admission, terminates the active adapter,
 checkpoints a `cancelled` observation, waits for bounded cleanup, and retains
 an inspectable partial report. On POSIX systems the runner targets the child
-process group with TERM then bounded KILL escalation. Windows descendant-tree
-termination is not guaranteed and is not a supported evaluation claim.
+process group with TERM then bounded KILL escalation. Native Windows targets
+the adapter and its descendant tree with `taskkill.exe /T`, escalating to `/F`
+after the bounded grace period.
 
 See [storage](storage.md#evaluation-report-and-note-snapshot-storage) for local
 retention/removal and [privacy](privacy-and-data-flow.md#evaluation-adapter-and-report-flow)

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

@@ -36,6 +36,9 @@ request unless the corresponding endpoint and credential are configured.
 | Automatic compaction recovery | None | Structured categories are injected locally; raw summary and other bodies are excluded |
 | 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
 retention, training, or logging policy; verify it before sending confidential
@@ -91,6 +94,41 @@ 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, 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,
+Git and memory choices, selected harness names, and setup-owned asset paths,
+digests, modes, and template identifiers. It does not contain credentials,
+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
+newest 16 KiB of child stderr for bounded failure diagnostics, caps startup,
+calls, catalogs, and results, and closes the child at shutdown. The child still
+inherits the remaining operator environment needed by the normal local server,
+so those environment values and the project directory are a child-process trust
+boundary even though they are not persisted by the bridge.
+
+Catalog and call replay is allow-listed to MCP tool metadata and result fields.
+Names, schemas, annotations, content, `structuredContent`, `_meta`, and error
+state are preserved without sanitizing away protocol meaning; Pi receives the
+annotations in trusted result `details` because Pi 0.84.1 has no native
+annotations field. The bridge does not log requests or results, create a second
+catalog, activate prompts or skills, add remote access, or persist a transcript.
+Sanitized test replay uses synthetic tool arguments, results, stderr, and
+project paths only; release evidence must not include credentials, private
+endpoints, memory values, or identifying local paths.
+
 ## Evaluation adapter and report flow
 
 `CAIRN_EVAL` is unset/off by default. With it off, `cairn eval` returns a fixed
@@ -169,7 +207,9 @@ network-free, and permanently scoped as framework-only evidence.
 SIGINT/SIGTERM stops new schedule admission, terminates the active adapter,
 checkpoints cancellation, performs bounded cleanup, and retains a partial
 report. POSIX process groups receive TERM followed by bounded KILL escalation.
-There is no Windows descendant-process-tree termination guarantee.
+Native Windows uses `taskkill.exe /T` for the exact child tree and `/F` for
+bounded force escalation; it does not enumerate or terminate unrelated
+processes.
 
 Turns aggregate only under exact matching compatibility IDs. Missing token
 components/totals, unknown verifier outcomes, incompatible turn semantics, and