@cairnkeep/cli 2.8.0 → 2.11.0

package/CHANGELOG.md

@@ -5,6 +5,71 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [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
+
+- Publish complete, centralized MCP tool annotations and add project-scoped
+  `full`, derived `read-only`, and exact custom tool profiles with strict
+  environment precedence and canonical provenance digests.
+- Add immutable context-pack manifests, local and commit-pinned Git installs,
+  atomic project enablement and confirmed updates, retained object storage,
+  integrity diagnostics, and explicit uninstall purge consent.
+- Add read-only context-pack list/search/read tools behind separate local and
+  authenticated-HTTP consent gates. Documents include full provenance; skills
+  remain invisible until their exact project/pack/path/file digest is approved.
+- Add deterministic Markdown chunking, optional embedding-ranked retrieval with
+  offline substring fallback, shell completion, lifecycle tests, operator docs,
+  and learning-path exercises.
+
+Context packs add no runtime dependency, telemetry, background synchronization,
+publisher-authenticity claim, ACL system, automatic skill activation, or
+  provider-specific runtime integration.
+
 ## [2.8.0] - 2026-08-03
 
 ### Added
@@ -252,7 +317,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.8.0...HEAD
+[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.11.0...HEAD
+[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
 [2.6.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.5.0...v2.6.0

package/README.md

@@ -14,19 +14,22 @@ Qwen Code, Pi, and other MCP clients).
 
 ## Status
 
-Shipped: the memory server, the `cairn` CLI (`bootstrap`, `memory-server`, `sync`, `sync-pi`, `sync-kimi`,
-`doctor`, `trajectory`, `artifact`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
+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.11 adds guided `cairn setup`, the maintained Pi local stdio memory
+extension, and the native Windows operating layer.
+
 ## Compatibility
 
 Node.js 22, 24, and 26 are supported. Cairnkeep 2.x requires Node.js 22 or
@@ -39,18 +42,22 @@ 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 |
+| 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 |
-| Other MCP clients | Memory and optional domain-knowledge MCP tools |
-| Native Windows | Not supported by the Bash-based installer; use WSL (not yet CI-verified) |
+| 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 |
+| 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.
@@ -78,10 +85,14 @@ 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
+  profiles; `cairn pack` validates, installs, pins, updates, and approves
+  immutable external context;
   `cairn eval validate|run|ablate|report|prune|delete` coordinates explicit
   local two-pass and one-capability-at-a-time measurements;
   `cairn skill harvest|list|show|review|propose|evaluate|apply|rollback`
@@ -96,7 +107,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
@@ -125,9 +136,11 @@ 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 **[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.
@@ -144,8 +157,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)
@@ -182,18 +195,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 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.
+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
+```
+
+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:
@@ -262,6 +293,11 @@ search):
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
 | `CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
 | `CAIRN_AGENTFS_BASE_DIR` | Base dir for global memory scopes (default `~/.cairnkeep`) |
+| `CAIRN_MCP_TOOL_PROFILE` | Process override for MCP exposure: `full`, `read-only`, or `custom` |
+| `CAIRN_MCP_ALLOWED_TOOLS` | Comma-separated exact allowlist required by a custom process profile |
+| `CAIRN_CONTEXT_PACKS` | Opt in to local context-pack list/search/read tools (default off) |
+| `CAIRN_CONTEXT_PACK_HTTP` | Separately consent to context-pack tools over authenticated HTTP (default off) |
+| `CAIRN_PACK_BASE_DIR` | Immutable pack objects, source records, pointers, and retrieval cache (default `~/.cairnkeep/packs`) |
 | `CAIRN_TRAJECTORY_CAPTURE` | Opt in to local structured session capture (`1`, `true`, `yes`, or `on`; default off) |
 | `CAIRN_TRAJECTORY_SESSION_MAX_BYTES` | Maximum serialized bytes per captured session (default `5242880`, 5 MiB) |
 | `CAIRN_TRAJECTORY_STORE_MAX_BYTES` | Maximum logical bytes across local trajectories (default `268435456`, 256 MiB) |
@@ -295,6 +331,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) |
@@ -308,6 +345,22 @@ remote memory, and delegated exploration can send content to endpoints you
 configure. Review [Privacy and data flow](docs/privacy-and-data-flow.md) before
 enabling them.
 
+### MCP authority and context packs
+
+Every tool publishes a stable title and all four MCP annotation hints. Use
+`cairn mcp-tools set read-only` for observation-only clients, or an exact custom
+allowlist when a workflow needs fewer tools. Process settings override the
+strict project file; the default remains `full`. Profiles only remove tools and
+cannot bypass capability or feature gates. See
+[MCP tool profiles](docs/mcp-tool-profiles.md).
+
+Context packs are immutable, digest-addressed local document/skill bundles.
+They are installed and project-pinned manually; no background Git sync occurs.
+With `CAIRN_CONTEXT_PACKS=1`, enabled documents are searchable through three
+read-only MCP tools. Skills remain invisible until their exact file digest is
+approved, and are never copied or executed. See
+[Immutable context packs](docs/context-packs.md).
+
 ### Managed capability contract (opt-in)
 
 `CAIRN_CAPABILITY_CONTRACT=1` enables one versioned, typed boundary around the
@@ -388,8 +441,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).
@@ -482,6 +535,8 @@ exposes trajectory data. See the [operating guide](docs/operating.md#compaction-
 - **Memory storage and deployment** — [docs/storage.md](docs/storage.md)
 - **Podman and OCI containers** — [docs/containers.md](docs/containers.md)
 - **Privacy and data flow** — [docs/privacy-and-data-flow.md](docs/privacy-and-data-flow.md)
+- **MCP tool profiles** — [docs/mcp-tool-profiles.md](docs/mcp-tool-profiles.md)
+- **Immutable context packs** — [docs/context-packs.md](docs/context-packs.md)
 - **Validated skill improvement** — [docs/skill-improvement.md](docs/skill-improvement.md)
 - **Git providers** — [docs/git-providers.md](docs/git-providers.md)
 - **Support** — [SUPPORT.md](SUPPORT.md)

package/bin/cairn

@@ -1,155 +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 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] [--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" "$@"
-    ;;
-  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

@@ -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

package/docs/context-packs.md

@@ -0,0 +1,94 @@
+# Immutable context packs
+
+Context packs provide project-approved reference documents and skills without
+copying them into a harness or promoting them into durable memory. They are
+local, immutable, disabled by default, and never execute instructions.
+
+## Format and identity
+
+The root `context-pack.json` follows
+[`schemas/context-pack.schema.json`](../schemas/context-pack.schema.json). It
+declares a kebab-case ID, semantic version, descriptive metadata, license, and
+an ordered list of UTF-8 `document` or `skill` files with SHA-256 digests.
+
+Validation rejects unknown manifest fields, absolute or traversing paths,
+symlinks, devices, duplicate, missing or undeclared files, invalid UTF-8, and
+digest mismatches. Limits are 1 MiB per file, 1,024 entries, and 64 MiB total.
+The authoritative pack digest covers the exact manifest bytes plus sorted
+path/content bytes. The version label is informative; the digest is identity.
+
+```bash
+cairn pack init ./my-pack --id my-pack --version 1.0.0 \
+  --title "My pack" --description "Reviewed local guidance" --license Apache-2.0
+# Edit metadata/kinds if needed, then refresh file hashes.
+cairn pack lock ./my-pack
+cairn pack validate ./my-pack
+```
+
+## Installation and project pinning
+
+```bash
+cairn pack install ./my-pack
+cairn pack install https://example.invalid/repository.git --ref v1.0.0
+cairn pack list
+cairn pack show PACK-DIGEST
+cairn pack enable PACK-DIGEST --project ./project
+cairn pack disable my-pack --project ./project
+cairn pack remove PACK-DIGEST
+```
+
+Local installation performs no network operation. Git installation requires
+`--ref`, invokes the system `git` executable with an argument array, records
+the exact resolved commit, rejects credentials embedded in URLs, and stores no
+checkout metadata. Immutable objects live under `CAIRN_PACK_BASE_DIR` (default
+`~/.cairnkeep/packs`). Project pointers are atomic and digest-pinned. Remote
+administration may use a validated `--project-id` instead of a local path.
+
+Objects are retained until explicitly removed. Removal is refused while any
+project points to the digest. Ordinary uninstall retains them; use
+`cairn uninstall --purge-packs` only after reviewing the dry run and backup.
+
+Updates never synchronize in the background:
+
+```bash
+cairn pack update my-pack --check --project ./project
+cairn pack update my-pack --apply --confirm CANDIDATE-DIGEST --project ./project
+```
+
+`--check` does not install or switch a project. `--apply` re-inspects the source,
+requires the candidate digest, installs an immutable object, and atomically
+switches only the named project.
+
+## Retrieval and skill approval
+
+Set `CAIRN_CONTEXT_PACKS=1` and restart the memory server to register the three
+read-only, closed-world tools: `context_pack_list`, `context_pack_search`, and
+`context_pack_read`. Every file or search result includes pack ID, version,
+pack digest, path, kind, and file digest. Search uses the existing optional
+embedding configuration and falls back to deterministic substring matching if
+configuration or the endpoint is unavailable. Embedding cache data is stored
+outside immutable objects.
+
+Markdown is split deterministically at headings and paragraphs, with chunks
+bounded to 8 KiB and 512-byte overlap. Only packs enabled for the current
+project are searched.
+
+Skills remain invisible until their exact file digest is approved:
+
+```bash
+cairn pack skills --project ./project
+cairn pack approve-skill PACK-DIGEST path/to/SKILL.md \
+  --confirm FILE-DIGEST --project ./project
+cairn pack revoke-skill PACK-DIGEST path/to/SKILL.md --project ./project
+```
+
+Approval binds the project identity, pack digest, path, and file digest. A pack
+update invalidates approval. Approved skills are only discoverable/readable
+through the context-pack tools; Cairnkeep does not copy, activate, or execute
+them.
+
+Authenticated HTTP deployments need the separate
+`CAIRN_CONTEXT_PACK_HTTP=1` consent flag in addition to
+`CAIRN_CONTEXT_PACKS=1`, the existing bearer token, Host/CORS guards, and a
+project header. Pack digests prove integrity, not publisher authenticity.
+Publisher signatures remain future work.