@cairnkeep/cli 2.9.0 → 2.11.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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
@@ -273,7 +317,8 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
-[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.9.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

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`,
+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 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.
@@ -78,8 +85,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 +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
@@ -128,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.
@@ -147,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)
@@ -185,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 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 +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) |
@@ -412,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).

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

@@ -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/harness-compatibility.md

@@ -12,7 +12,7 @@ commands, hooks, plugins, or trajectory adapters.
 | OpenCode | Memory MCP, commands, workflows, plugins, launcher | Exercised by Cairnkeep tests |
 | Kimi Code | Memory MCP, `AGENTS.md`, launcher, opt-in graph Skill | Launcher tested; remote MCP tested with Kimi Code 0.30.0; graph Skill contract-tested |
 | Qwen Code | Memory MCP, launcher | Launcher tested; stdio and remote MCP tested with Qwen Code 0.21.1 |
-| Pi | Native opt-in trajectory extension, launcher, and graph prompt | Exercised by Cairnkeep tests; no bundled MCP bridge |
+| Pi | Memory MCP through maintained local stdio extension, native opt-in trajectory extension, launcher, and graph prompt | Pi 0.84.1 validated minimum; deterministic and real bridge/lifecycle tests |
 | Codex CLI | Memory MCP | Configuration supported; no Cairnkeep operating-layer assets or launcher |
 | Other MCP clients | Memory plus optional domain-knowledge and context-pack tools | Protocol-compatible; not automatically runtime-tested |
 
@@ -33,7 +33,35 @@ Pi, Qwen Code, Codex, and other shell-capable clients can invoke
 `graphify` executable are on `PATH`. `cairn sync-kimi --apply` registers a Kimi
 Skill as `/graphify` (or `/skill:graphify`), and `cairn sync-pi --apply`
 registers a Pi prompt template as `/graphify`; both delegate exclusively to
-that CLI. Neither adds an MCP bridge to Pi or expands the other support levels.
+that CLI. Pi sync separately installs the Cairnkeep-owned local stdio memory
+extension; it does not expand the other support levels.
+
+## Pi
+
+Run `cairn sync-pi --apply` explicitly to install
+`extensions/cairnkeep-memory.ts`, `extensions/cairnkeep-trajectory.ts`, and
+`prompts/graphify.md` under the Pi agent root. Use `--check` for drift and
+`cairn doctor` from a project that selected Pi for setup-aware diagnosis. Setup
+reports this machine command but never runs it automatically. Uninstall removes
+only those owned paths, backup-first.
+
+The memory extension supervises `cairn memory-server` as a local stdio child.
+It discovers the effective MCP catalog dynamically and preserves names,
+descriptions, input/output schemas, original content, `structuredContent`,
+`_meta`, failure behavior, and the exact tool annotations in trusted result
+`details`. Pi 0.84.1 exposes no native annotations field in its public tool API,
+so those annotations are not claimed as native model-facing metadata. Server
+feature gates, capability state, and least-authority profiles continue to
+decide which tools exist.
+
+Startup, calls, results, stderr retention, cancellation, and shutdown are
+bounded. The extension adds tools only: it does not run prompts, activate
+context-pack skills, create an autonomous loop, or add a remote transport.
+Pi 0.84.1 is the validated minimum. The v2.11 release matrix passed separate
+installations for that minimum and the explicitly versioned registry-current Pi
+release, together with Node.js 22/24/26, Bash 3.2, and native Windows. The
+executable paths were distinct; both reported 0.84.1 because that was also the
+registry-current release.
 
 ## Kimi Code
 

package/docs/learning/CURRICULUM-MAP.md

@@ -1,7 +1,7 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.9.0
-**Last reviewed:** 2026-08-06
+**Baseline:** Cairnkeep 2.11.0
+**Last reviewed:** 2026-08-12
 
 This map prevents the course from drifting behind the product. It assigns each
 user-facing surface to a lesson and records whether the lesson is complete or
@@ -34,6 +34,9 @@ been rehearsed.
 | Reviewed, evaluated, reversible skill-file improvement | L19 | L19 | Ready; explicit and default off |
 | Complete MCP annotations and least-authority tool profiles | L20 | L20 | Ready; default profile remains full |
 | Immutable context packs and exact-digest skill approval | L21 | L21 | Ready; default off |
+| Native Windows x64 CLI, hooks, ACLs, scheduling, and recovery | L22 | L22 | Ready; PowerShell-native |
+| Guided project setup, selected harness state, and Git-less limitations | L23 | L23 | Ready |
+| Pi local stdio memory bridge, trusted annotation details, and explicit lifecycle | L23 | L23 | Ready; Pi 0.84.1 validated minimum |
 
 ## Release Review
 
@@ -65,6 +68,8 @@ repository remains the canonical source for explanations and scripts.
 | `course-08-graph` | L18 | Optional local structural graph workflow |
 | `course-09-skill` | L19 | Validated skill improvement in a disposable project |
 | `course-10-trust-context` | L20-L21 | MCP authority profiles and offline context-pack lifecycle |
+| `course-11-windows` | L22 | Native PowerShell lifecycle, ACL inspection, and reversible uninstall |
+| `course-12-guided-setup` | L23 | Deterministic setup, Pi local stdio, recovery, and backup-first uninstall |
 
 ## Command Ownership
 
@@ -74,9 +79,10 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 | Command | Primary lesson |
 |---|---|
 | `cairn bootstrap` | L03 |
+| `cairn setup` | L23 |
 | `cairn memory-server` | L02 |
 | `cairn sync` | L02 |
-| `cairn sync-pi` | L13 |
+| `cairn sync-pi` | L13 and L23 |
 | `cairn sync-kimi` | L02 |
 | `cairn doctor` | L03; advanced repair in L13-L14 |
 | `cairn trajectory` | L13 |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.9.0
+**Baseline:** Cairnkeep 2.11.0
 
 This is the step-back map for choosing and operating Cairnkeep features. The
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs) provide one
@@ -8,13 +8,17 @@ synthetic Trail Ledger project with tagged states from a plain application to
 offline evaluation. Detailed contracts remain in the linked operating,
 storage, privacy, and lesson documents.
 
+Guided setup and the maintained Pi memory extension ship in v2.11. See
+[L23](lessons/L23-guided-setup.md) for the tested boundary.
+
 ## The three-layer model
 
 1. **Memory server:** an MCP process that owns scoped durable storage. The
    default stdio setup runs on the current machine; installation never
    discovers or selects a remote host.
 2. **Project scaffold:** launchers, private environment, and `.planning/`
-   policy/derived-knowledge files created by `cairn bootstrap`.
+   policy/derived-knowledge files reconciled by `cairn setup`; `cairn bootstrap`
+   remains the deterministic compatibility primitive.
 3. **Operating layer:** harness commands, agents, and hooks installed by
    `cairn sync --apply` or the harness-specific equivalent.
 
@@ -48,6 +52,7 @@ prerequisites for ordinary memory.
 | Wiki and alignment | `/wiki-ingest`, `/wiki-query`, `/wiki-lint`, alignment files | Written only when invoked; reviewable `.planning/` artifacts | Re-run lint, inspect source citations, revert tracked changes normally | `course-02-memory` |
 | Local code graph | `cairn graph build|query|status|diff|explain|path`; `/graphify` delegates | Default off; optional isolated `graphify` executable; incremental work under `graphify-out/`, published view under `.planning/graphs/` | Ignore both derived locations; check status and source before trusting a result; use `--force` only after intentional deletion; uninstall adapters separately | `course-08-graph` |
 | Repository quality | `/repo-review`, `/security-audit` | On-demand workflow; findings are hypotheses until reproduced | Require file/line evidence and regression tests | `course-03-quality` |
+| Guided project setup | `cairn setup PATH --git init\|existing\|none --harness LIST --memory local\|none --yes` | Reconciles only selected project assets; private `.ai/cairnkeep.json`; machine sync is never automatic | Repeat deterministically, run doctor, or replay its recovery command; Git-less mode remains limited | `course-12-guided-setup` |
 
 ## Storage and optional topology
 
@@ -62,6 +67,7 @@ prerequisites for ordinary memory.
 | Managed overlays | Separate distribution manifest, wrapper, profile lock, fleet and rollback gates | Policy and secrets belong in the private distribution/machine config, never core | `overlay info`, doctor, fleet dry run/current state, rollback | `course-04-operation` |
 | MCP tool profiles | `cairn mcp-tools set full|read-only|custom` | Strict mode-`0600` project config; process overrides take precedence; profile only removes tools | Inspect catalog/status digest; reset and restart MCP | `course-10-trust-context` |
 | Context packs | Manual local or commit-pinned Git install plus project enablement | Immutable objects and atomic pointers under `CAIRN_PACK_BASE_DIR`; no background sync | Validate, inspect digest, check/apply update, disable/remove | `course-10-trust-context` |
+| Pi local stdio memory | Select Pi during setup, then explicitly run `cairn sync-pi --apply` | Local memory-server child; dynamic effective tool catalog; annotations retained in trusted details, not a native Pi field | `cairn sync-pi --check`, `cairn doctor`, cancel one call, then observe awaited shutdown with no orphan | `course-12-guided-setup` |
 
 ## Evidence, governance, and measurement
 
@@ -83,7 +89,7 @@ prerequisites for ordinary memory.
 
 - Use a generated launcher so project environment and hooks are repeatable.
 - Run `cairn sync --check` after every core upgrade; apply only reported drift.
-- Run `cairn sync-pi --check` when the optional Pi capture/graph adapter is installed.
+- Run `cairn sync-pi --check` when the Pi memory/trajectory/graph assets are installed.
 - Run `cairn sync-kimi --check` when the optional Kimi graph Skill is installed.
 - Use `cairn doctor --repair` only after preserving the affected store and only
   for repairable derived indexes/metadata.