@cairnkeep/cli 2.9.0 → 2.12.0

package/CHANGELOG.md

@@ -5,6 +5,69 @@ 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
+
+- Replace the Bash npm entry point with a cross-platform Node CLI while keeping
+  the established Unix scripts as compatibility implementations.
+- Add native Windows x64 bootstrap and `.cmd`/PowerShell launchers, Claude/Pi/
+  Kimi asset synchronization, Node hook transports, diagnostics, PowerShell
+  completion, Task Scheduler registration, memory import/export plumbing, and
+  backup-first uninstall with a `revert.ps1` manifest.
+- Enforce private Windows ACLs for least-authority MCP profiles and context-pack
+  state, make pack objects read-only, retry Windows atomic replacements, and
+  terminate evaluation adapter descendant trees through `taskkill.exe /T`.
+- Add a PowerShell-only Windows CI matrix for Node 22/24/26, including native
+  lifecycle tests and a packed global npm installation under paths containing
+  spaces and Unicode.
+
+### Changed
+
+- Add PowerShell to shell completion and document Windows x64 as a supported
+  native platform. Windows ARM64 remains an x64-emulation target until the
+  storage dependency ships a native ARM64 binding.
+
+### Added
+
+- Add `cairn setup` as the recommended guided project entry point, with a fully
+  deterministic non-interactive form, explicit Git/harness/memory choices,
+  versioned private project state, selected-asset reconciliation, structured
+  output, doctor diagnostics, and recovery commands.
+- Add a strict provider-neutral setup-policy schema for private overlays, with
+  command-line choices taking precedence over policy defaults and constraints
+  enforced on every resolved plan.
+- Add the maintained Pi local stdio memory extension, dynamic MCP catalog
+  discovery, bounded child lifecycle, cancellation, exact response preservation,
+  and trusted annotation metadata. Pi 0.84.1 is the validated minimum.
+
+### Changed
+
+- Make project setup report machine sync without running it automatically;
+  `cairn sync-pi --apply|--check`, `cairn doctor`, and backup-first uninstall
+  remain explicit lifecycle operations.
+- Preserve `cairn bootstrap` and `--untracked` as backward-compatible scripted
+  primitives while recommending guided setup for new onboarding.
+
 ## [2.9.0] - 2026-08-06
 
 ### Added
@@ -273,7 +336,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.9.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
 [2.7.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.6.0...v2.7.0

package/README.md

@@ -9,24 +9,44 @@
 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 (`bootstrap`, `memory-server`, `sync`, `sync-pi`, `sync-kimi`,
+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
 `npm i -g @cairnkeep/cli`, and the
 operating layer (commands,
-agents, hooks) installed on Claude Code and OpenCode, plus a native Pi
+agents, hooks) installed on Claude Code and OpenCode, plus the native Pi
 trajectory extension and thin Pi/Kimi graph adapters. The generic launchers
-expose wrapper seams (`.ai/pre-launch.sh`, `CAIRN_EXTRA_SETTINGS`,
-`.ai/post-exit.sh`) so an enterprise wrapper can add provider/credential setup
+expose wrapper seams (`.ai/pre-launch.sh`/`.ai/pre-launch.ps1`,
+`CAIRN_EXTRA_SETTINGS`, `.ai/post-exit.sh`/`.ai/post-exit.ps1`) so an enterprise wrapper can add provider/credential setup
 without forking them. Also shipped: context exploration (`/context-explore`) and
 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.12 adds a declarative harness registry, first-class Codex project
+setup, and a shorter path from installation to verified recall.
+
 ## Compatibility
 
 Node.js 22, 24, and 26 are supported. Cairnkeep 2.x requires Node.js 22 or
@@ -39,21 +59,25 @@ and 20 are end-of-life upstream.
 | OpenCode on Linux/macOS | Memory server plus commands, plugins, hooks, and launchers |
 | 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 | Native opt-in trajectory extension, launcher, and `/graphify` prompt; no bundled MCP bridge |
-| Codex CLI | Memory MCP server; no Cairnkeep operating-layer assets |
+| 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 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 | Not supported by the Bash-based installer; use WSL (not yet CI-verified) |
+| 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 |
+| WSL | Uses the normal Linux workflow; distinct from native Windows and Git Bash |
 
 The `cairn graph` CLI is harness-independent and can be run from a project
 shell used by Kimi Code, Pi, Qwen Code, Codex, or another client. Claude Code,
 OpenCode, Pi, and Kimi can receive thin `/graphify` adapters; those adapters do
 not imply equivalent hooks, agents, or MCP support.
 
-Linux, macOS, Bash 3.2 portability, and clean Node 22/24/26 runtime checks
-are exercised in CI.
+Linux, macOS, Bash 3.2 portability, native PowerShell on Windows x64, global npm
+installation, and clean Node 22/24/26 runtime checks are exercised in CI. See
+[Native Windows operation](docs/native-windows.md) for platform-specific setup,
+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
 
@@ -78,8 +102,9 @@ storage paths, secrets, and private derived images, see
 - **`mcp-memory-server/`** — an MCP server exposing durable, scoped memory
   (`memory_write`, `memory_search`, …) backed by AgentFS, with optional
   embedding-ranked search against any OpenAI-compatible endpoint.
-- **`bin/cairn`** — the CLI. `cairn bootstrap [path]` scaffolds a project's
-  `.ai/` launchers + env; `cairn doctor` health-checks the configured pieces;
+- **`bin/cairn`** — the CLI. `cairn setup [path]` guides or deterministically
+  reconciles selected project assets; `cairn bootstrap [path]` preserves the
+  established scripted scaffold contract; `cairn doctor` health-checks the configured pieces;
   `cairn trajectory list|show|prune` manages opt-in local session trajectories;
   `cairn artifact list|show|delete|prune` manages opt-in local artifacts;
   `cairn mcp-tools list|status|set|reset` applies least-authority discovery
@@ -99,7 +124,7 @@ storage paths, secrets, and private derived images, see
   (`export` requires the optional `sqlite3` CLI);
   `cairn audit-timer` installs the scheduled memory+wiki audit;
   `cairn completion bash|zsh|fish` generates shell completion definitions; and
-  `cairn sync-pi` installs the native Pi trajectory extension and graph prompt;
+  `cairn sync-pi` installs the native Pi memory and trajectory extensions plus graph prompt;
   `cairn sync-kimi` installs the Kimi graph Skill;
   `cairn uninstall` reverses the install (backup-first, revertible).
 - **`templates/`** — project scaffolding (generic launchers, env) plus the
@@ -128,9 +153,12 @@ them. These are the accelerators the author pairs cairnkeep with; each is opt-in
 ## Setup
 
 A working workflow needs three things: the memory server registered, the
-operating layer (commands, agents, hooks) installed into your harness, and a
-bootstrapped project. `cairn bootstrap` does only the last of these — the full
-ordered walkthrough is in **[docs/operating.md](docs/operating.md)**.
+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
 the user's computer. Cairnkeep never discovers or selects a remote host.
@@ -147,8 +175,8 @@ claude mcp add cairn-memory -s user -- cairn memory-server
 # 2. Install the operating layer (commands, agents, hooks, scaffold templates)
 cairn sync --apply                       # add --live-root <proj>/.claude to scope it
 
-# 3. Scaffold a project and configure it
-cairn bootstrap /path/to/project
+# 3. Configure a project deterministically
+cairn setup /path/to/project --git init --harness claude --memory local --yes
 cp /path/to/project/.ai/env.example /path/to/project/.ai/.env   # then edit
 
 # 4. Launch (and, optionally, check the wiring first)
@@ -169,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
@@ -185,18 +220,36 @@ headers. Review and approve project MCP configuration with
 `qwen mcp approve cairn-memory`, then launch with `./.ai/start-qwen.sh`. See
 [Harness compatibility](docs/harness-compatibility.md#qwen-code).
 
-For Pi, install the local trajectory adapter and use the scaffolded launcher:
+For Pi, select Pi during project setup, explicitly install/check its machine
+assets, run doctor, and use the generated launcher:
 
 ```bash
 cairn sync-pi --apply
-cairn bootstrap /path/to/project
-cd /path/to/project && ./.ai/start-pi.sh
+cairn sync-pi --check
+cairn setup /path/to/project --git init --harness pi --memory local --yes
+cd /path/to/project && cairn doctor && ./.ai/start-pi.sh
+```
+
+This installs the maintained local stdio memory extension, trajectory capture,
+and the thin `/graphify` prompt. The memory extension discovers the effective
+server tool catalog and preserves annotations in trusted result details; Pi's
+public API has no native annotations field. It adds tools only—no prompt runs,
+skill activation, autonomous loop, or remote access. Pi 0.84.1 is the minimum
+validated version; v2.11 also passed the registry-current Pi release and the
+documented Node, Bash, and native Windows matrix.
+
+Preview removal before confirming it. Uninstall backs up every managed file it
+will change and prints the generated revert command; durable memory and context
+packs remain unless their explicit purge flags are supplied:
+
+```bash
+cairn uninstall --dry-run /path/to/project
+cairn uninstall --yes /path/to/project
 ```
 
-This installs trajectory capture plus the thin `/graphify` prompt. The prompt
-delegates exclusively to `cairn graph`. Cairnkeep does not bundle or select a
-Pi MCP bridge; configure a user-chosen bridge separately if you also want the
-MCP memory tools inside Pi.
+If setup-owned project assets drift, rerun the exact `cairn setup ... --yes`
+recovery command reported by `cairn doctor`. For Pi machine-asset drift, run
+`cairn sync-pi --apply`, then `cairn sync-pi --check` and `cairn doctor`.
 
 Closed trajectories can be compiled into local hindsight notes without a model
 or embedding service. Capture and distillation are separate opt-ins:
@@ -303,6 +356,7 @@ search):
 | `CAIRN_EVAL` | Opt in to the local evaluation coordinator (default off; does not select a harness, model, endpoint, credential, or network) |
 | `CAIRN_GIT_PROVIDER` | Git host for collaboration commands: `github`\|`gitlab`\|`codeberg`\|`forgejo`\|`none` ([docs/git-providers.md](docs/git-providers.md)) |
 | `CAIRN_ROUTE_ENDPOINT` | Base URL of an already-running token-miser routing/tiering proxy (unset → `route_check` is inert) |
+| `CAIRN_GRAPHIFY_BINARY` | Optional Graphify command/path override (default `graphify` from `PATH`; JavaScript helpers run through Node) |
 | `CAIRN_EXPLORE_BINARY` | Absolute path to the `token_miser` binary used by `context_explore` (unset → the tool throws) |
 | `CAIRN_EXPLORE_REPO_ROOT` | Default repo root for `context_explore` when no per-call `repo_root` is given |
 | `CAIRN_EXTRA_SETTINGS` | Optional settings/config file the launcher layers onto the harness (wrapper seam) |
@@ -412,8 +466,8 @@ is neither a Cairnkeep result nor an acceptance target.
 Reports and note snapshots stay under
 `.agentfs/eval/experiments/<experiment-id>/`; default uninstall retains them,
 while explicit purge is backup-first and revertible. Cancellation retains an
-inspectable partial report. POSIX process-group cleanup is tested; Windows
-descendant-process-tree termination is not guaranteed. See the
+inspectable partial report. POSIX process-group cleanup and Windows descendant-
+tree cleanup through `taskkill.exe /T` are tested by their platform contracts. See the
 [operating guide](docs/operating.md#evaluation-harness-opt-in),
 [storage contract](docs/storage.md#evaluation-report-and-note-snapshot-storage),
 and [privacy flow](docs/privacy-and-data-flow.md#evaluation-adapter-and-report-flow).

package/bin/cairn

@@ -1,167 +1,8 @@
-#!/usr/bin/env bash
-# cairn — Cairnkeep CLI. Thin dispatcher over the core scripts.
-set -euo pipefail
+#!/usr/bin/env node
 
-# Resolve through symlinks so this works when installed as an npm global bin
-# (which symlinks <prefix>/bin/cairn -> the packaged bin/cairn).
-SOURCE="${BASH_SOURCE[0]}"
-while [ -L "$SOURCE" ]; do
-  DIR=$(cd -P "$(dirname "$SOURCE")" && pwd)
-  SOURCE=$(readlink "$SOURCE")
-  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
-done
-CAIRN_ROOT=$(cd -P "$(dirname "$SOURCE")/.." && pwd)
+import { main } from "../scripts/cairn-cli.mjs";
 
-cmd="${1:-help}"
-[[ $# -gt 0 ]] && shift
-
-usage() {
-  cat <<'USAGE'
-cairn — Cairnkeep CLI
-
-Usage:
-  cairn bootstrap [--untracked] [path]
-                           Scaffold launchers, planning files, and the private
-                           project-memory ignore guard (default path: .).
-                           --untracked keeps the scaffold out of git via the repo's
-                           .git/info/exclude (contributor mode: nothing to commit,
-                           invisible to other contributors, local-only).
-  cairn memory-server      Run the memory MCP server (stdio). Register it with your
-                           harness, e.g. claude mcp add cairn-memory -s user -- cairn memory-server.
-  cairn sync [--apply] [--live-root DIR]
-                           Install/update the Claude Code operating layer (commands,
-                           agents, hooks) into ~/.claude, or into DIR for a single
-                           project (--live-root <project>/.claude).
-  cairn sync-pi [--apply] [--live-root DIR]
-                           Install/update the Pi trajectory extension and thin
-                           /graphify prompt into ~/.pi/agent or isolated DIR.
-  cairn sync-kimi [--apply] [--live-root DIR]
-                           Install/update the thin Kimi /graphify Skill into
-                           $KIMI_CODE_HOME, ~/.kimi-code, or isolated DIR.
-  cairn doctor             Health-check the memory server and configured LLM /
-                           embedding endpoints, git provider, and stores.
-                           Use --repair for derived trajectory/typed metadata,
-                           indexes, and interrupted note transactions.
-  cairn trajectory <list|show|prune>
-                           Inspect and prune opt-in local session trajectories.
-  cairn artifact <list|show|delete|prune>
-                           Inspect and delete opt-in local artifacts. List/show
-                           support --json; delete supports --dry-run; prune
-                           supports --dry-run and --include-protected.
-  cairn capabilities <list|status|enable|disable|reset|logging>
-                           Inspect and manage project capability state. MCP changes
-                           require a memory-server restart; operating changes apply
-                           on the next invocation.
-  cairn mcp-tools <list|status|set|reset>
-                           Inspect and restrict MCP tool exposure with full,
-                           read-only, or exact custom project profiles.
-  cairn pack <init|lock|validate|install|list|show|remove|enable|disable|update|skills|approve-skill|revoke-skill>
-                           Build, verify, install, pin, and retrieve immutable
-                           context packs. Packs stay local and disabled by default.
-  cairn notes <distill|search-error|promote|doctor>
-                           Compile closed trajectories into local hindsight notes,
-                           search exact failure signatures, promote corroborated
-                           notes, or validate the note store.
-  cairn eval <validate|run|ablate|report|prune|delete>
-                           Validate or run default-off local evaluations, inspect
-                           reports, and manage retained experiment results.
-  cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>
-                           Turn recurring hindsight evidence into reviewed,
-                           evaluated, reversible skill-file improvements.
-  cairn graph <build|query|status|diff|explain|path>
-                           Build the local code graph, inspect freshness and
-                           changes, or query exact symbols and paths.
-  cairn memory <path|export|import>
-                           Relocate global-scope memory. `path` prints its location;
-                           `export <file.tgz>` takes a WAL-safe snapshot (requires
-                           sqlite3); `import <file.tgz>` restores it.
-  cairn audit-timer [--on-calendar SPEC] [--para-root PATH] [--render-only DIR]
-                           Install (opt-in) a systemd user timer that runs the
-                           memory+wiki audit on a schedule; prints a cron alternative.
-  cairn uninstall [--dry-run] [--yes] [--purge-memory] [--purge-packs] [--live-root DIR]
-                  [--pi-live-root DIR] [--kimi-live-root DIR] [PROJECT ...]
-                           Reverse what cairnkeep installed/modified (operating
-                           layer, hook registrations, MCP registration, audit
-                           timer, and any given projects' bootstrap scaffold).
-                           Backs everything up first with a revert.sh; keeps the
-                           durable memory store unless --purge-memory is given.
-  cairn completion bash|zsh|fish
-                           Generate completion definitions for a major shell.
-  cairn version            Print version
-  cairn help               Show this help
-USAGE
-}
-
-case "$cmd" in
-  bootstrap)
-    exec "$CAIRN_ROOT/scripts/bootstrap.sh" "$@"
-    ;;
-  doctor)
-    exec "$CAIRN_ROOT/scripts/doctor.sh" "$@"
-    ;;
-  uninstall)
-    exec "$CAIRN_ROOT/scripts/uninstall.sh" "$@"
-    ;;
-  memory)
-    exec "$CAIRN_ROOT/scripts/memory-store.sh" "$@"
-    ;;
-  memory-server)
-    # Run the memory MCP server (stdio by default). Use with your harness, e.g.
-    #   claude mcp add cairn-memory -s user -- cairn memory-server
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/index.js" "$@"
-    ;;
-  trajectory)
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/trajectory-cli.js" "$@"
-    ;;
-  artifact)
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/artifact-cli.js" "$@"
-    ;;
-  capabilities)
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/capability-cli.js" "$@"
-    ;;
-  mcp-tools)
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/mcp-tool-cli.js" "$@"
-    ;;
-  pack)
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/context-pack-cli.js" "$@"
-    ;;
-  notes)
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/note-cli.js" "$@"
-    ;;
-  eval)
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/eval-cli.js" "$@"
-    ;;
-  skill)
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/skill-cli.js" "$@"
-    ;;
-  graph)
-    exec node "$CAIRN_ROOT/mcp-memory-server/dist/graph-cli.js" "$@"
-    ;;
-  sync)
-    exec "$CAIRN_ROOT/scripts/sync-claude-assets.sh" "$@"
-    ;;
-  sync-pi)
-    exec "$CAIRN_ROOT/scripts/sync-pi-assets.sh" "$@"
-    ;;
-  sync-kimi)
-    exec "$CAIRN_ROOT/scripts/sync-kimi-assets.sh" "$@"
-    ;;
-  audit-timer)
-    exec "$CAIRN_ROOT/scripts/install-audit-timer.sh" "$@"
-    ;;
-  completion)
-    exec "$CAIRN_ROOT/scripts/completion.sh" "$@"
-    ;;
-  version | --version | -v)
-    v=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$CAIRN_ROOT/package.json" 2>/dev/null | head -1)
-    echo "cairnkeep ${v:-unknown}"
-    ;;
-  help | --help | -h)
-    usage
-    ;;
-  *)
-    echo "Unknown command: $cmd" >&2
-    usage >&2
-    exit 2
-    ;;
-esac
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`cairn: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

package/bin/cairn-container

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from "../scripts/cairn-container-cli.mjs";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`cairn-container: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 2;
+});

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 |
@@ -54,19 +54,54 @@ export ANTHROPIC_BASE_URL="$MY_INTERNAL_GATEWAY"
 The user still runs the standard `./.ai/start-claude.sh`; the overlay's behaviour
 is injected by the file's presence.
 
+## Guided setup policy seam
+
+An overlay may provide a data-only JSON policy to `cairn setup --policy PATH`.
+The public schema is
+[`schemas/cairnkeep-setup-policy.schema.json`](../schemas/cairnkeep-setup-policy.schema.json).
+It is strict and provider-neutral: `schema_version` is `1`; `defaults` may set
+`git`, `harnesses`, and `memory`; and `constraints` may restrict those values
+and require selected harnesses. Unknown properties are rejected.
+
+Precedence is explicit command-line choices, then policy defaults, then
+interactive input. Constraints validate the resolved plan regardless of which
+source supplied a choice. Non-interactive use still requires an explicit
+target and `--yes`, and every unresolved Git, harness, or memory choice is an
+error. A policy is a regular non-symlink JSON file no larger than 1 MiB; on
+POSIX it must not be executable. Keep organization-specific endpoints,
+credentials, and launcher logic outside this file.
+
+For deterministic onboarding, pin a reviewed policy beside the overlay and
+invoke:
+
+```bash
+cairn setup /path/to/project --policy /path/to/setup-policy.json \
+  --git existing --harness claude,pi --memory local --yes
+cairn sync-pi --apply
+cairn sync-pi --check
+```
+
+Setup reconciles only the selected project assets and reports machine sync
+without running it. The overlay remains responsible for applying and checking
+machine assets explicitly. Preserve `.ai/cairnkeep.json`: it is the private,
+versioned project ownership record used by status, doctor, recovery, and
+backup-first uninstall.
+
 ## An overlay install script
 
 Make it one idempotent command from a fresh machine:
 
 ```bash
-# 1. Get cairnkeep at a pinned version (npm or a pinned clone)
-npm i -g @cairnkeep/cli@1.0.2      # or: git clone … && git checkout v1.0.2
+# 1. Get cairnkeep at a reviewed, pinned version (npm or a pinned clone)
+npm i -g @cairnkeep/cli@<version>
 
 # 2. Register the memory server with your harness
 claude mcp add cairn-memory -s user -- cairn memory-server
 
-# 3. Scaffold the target project (contributor mode if you don't own the repo)
-cairn bootstrap --untracked /path/to/project
+# 3. Reconcile the target project deterministically
+cairn setup /path/to/project --git existing --harness claude --memory local --yes
+# Existing bootstrap automation remains supported:
+# cairn bootstrap --untracked /path/to/project
 
 # 4. Install the operating layer — GLOBAL or PROJECT-SCOPED (below)
 sync-claude-assets.sh --apply                      # global ~/.claude
@@ -128,6 +163,8 @@ secret storage, not generated project files.
 - [ ] Operating layer scoped as intended (global vs `--live-root`)
 - [ ] Optional integrations wired only where wanted
 - [ ] A single documented command takes a fresh machine to a working setup
+- [ ] Setup policy is data-only, schema-valid, and contains no secrets or endpoints
+- [ ] Machine sync/check is explicit; project setup never runs it automatically
 - [ ] Managed machines resolve `cairn` to the overlay distribution, not raw core
 - [ ] `cairn config explain` reports memory and RAG destinations without secrets
 - [ ] A project profile lock prevents silent cross-overlay reconfiguration

package/docs/containers.md

@@ -38,6 +38,13 @@ podman run --rm -i \
 
 Pin a version instead of `latest` for managed installations.
 
+On native Windows, the installed `cairn-container.cmd` invokes the same
+argument-safe Node launcher and defaults to `podman.exe`; set
+`CONTAINER_ENGINE` to an explicit compatible engine path if needed. Podman
+Desktop must be configured for Linux containers. Named-volume modes preserve
+the container-side contract, while host paths are passed as single arguments
+so drive letters and spaces are not split by a shell.
+
 ## Authenticated HTTP
 
 Generate the bearer token into a private file and start a loopback-only
@@ -57,6 +64,9 @@ The launcher refuses token files that are symlinks or have a mode other than
 `0400` or `0600`. It mounts the token read-only instead of putting it in the
 container environment or image.
 
+On Windows, the equivalent check rejects symlinks and any token ACL granting
+access beyond the current SID, Local System, or built-in Administrators.
+
 The listener is deliberately published only on `127.0.0.1`. For access from
 other machines, keep it on loopback behind a TLS reverse proxy or encrypted
 private network. Add the externally visible `Host` header to the DNS-rebinding