@cairnkeep/cli 2.8.0 → 2.11.0

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

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

package/docs/learning/tracks/operator.md

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

package/docs/learning/tracks/quickstart.md

@@ -1,17 +1,21 @@
 # Quickstart Track
 
 **Audience:** developers evaluating Cairnkeep
-**Total time:** about 75 minutes
+**Total time:** about 110 minutes
 **Infrastructure:** local machine; Podman is optional
 
 1. [L00 - Why Cairnkeep?](../lessons/L00-why-cairnkeep.md)
 2. [L01 - Try it safely](../lessons/L01-safe-trial.md)
 3. [L02 - Install the local workflow](../lessons/L02-installation.md)
 4. [L03 - Bootstrap the first project](../lessons/L03-first-project.md)
+5. [L23 - Guided setup and Pi memory](../lessons/L23-guided-setup.md)
 
 The track is complete when a learner can start a new harness session, retrieve
 a previously accepted fact, and explain that default stdio memory is stored on
-the local machine rather than a discovered remote service.
+the local machine rather than a discovered remote service. L23 then shows how
+the recommended guided entry point preserves deterministic automation and keeps
+Pi machine sync explicit. This guided surface ships in v2.11.
 
-Hands-on spine: `course-00-app` through `course-01-bootstrap` in the public
+Hands-on spine: `course-00-app` through `course-01-bootstrap`, followed by
+`course-12-guided-setup`, in the public
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs).

package/docs/mcp-tool-profiles.md

@@ -0,0 +1,43 @@
+# MCP tool annotations and least-authority profiles
+
+Cairnkeep publishes a complete annotation contract for every MCP tool. Each
+tool has a stable title and explicit `readOnlyHint`, `destructiveHint`,
+`idempotentHint`, and `openWorldHint` values. Local observations are closed
+world. Tools that query configured services or delegated processes are open
+world. Any mutation that may replace or remove state is destructive; immutable
+artifact creation is additive.
+
+Use the profile CLI to reduce the tools visible to an MCP client:
+
+```bash
+cairn mcp-tools list
+cairn mcp-tools status --json
+cairn mcp-tools set read-only
+cairn mcp-tools set custom --tool memory_read --tool memory_search
+cairn mcp-tools reset
+```
+
+Project configuration is strict versioned JSON in `.ai/mcp-tools.json`, created
+only by `set` and written with mode `0600`. Do not hand-edit it. A process may
+override the project with `CAIRN_MCP_TOOL_PROFILE=full|read-only|custom`; custom
+process profiles also require a comma-separated `CAIRN_MCP_ALLOWED_TOOLS`.
+Precedence is process environment, project configuration, then `full`.
+
+`read-only` is derived from the central annotation catalog. `custom` is an
+exact allowlist. Unknown names fail server startup and `cairn doctor`. Profiles
+only remove authority: they cannot activate typed nodes, artifacts, context
+packs, HTTP exposure, or a disabled capability. Effective discovery is:
+
+```text
+available feature gates ∩ capability contract ∩ MCP tool profile
+```
+
+`status` includes a canonical profile digest. Evaluation reports record that
+same digest in their evidence provenance without changing the independent
+capability-configuration digest. Restart the memory server after changing an
+MCP profile.
+
+The default `full` profile preserves the same tool names, schemas, responses,
+feature gates, and ordering as an unconfigured server. The annotations help
+conservative clients distinguish observations from actions; they do not grant
+permission or replace the client's approval policy.

package/docs/native-windows.md

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

package/docs/operating.md

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