@cairnkeep/cli 2.8.0 → 2.11.0

package/docs/harness-compatibility.md

@@ -12,22 +12,56 @@ 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 and optional domain-knowledge tools | Protocol-compatible; not automatically runtime-tested |
+| Other MCP clients | Memory plus optional domain-knowledge and context-pack tools | Protocol-compatible; not automatically runtime-tested |
 
 Only Claude Code and OpenCode currently receive the complete operating layer.
 Kimi receives one narrow graph Skill, while Pi receives one narrow graph prompt;
 neither is equivalent to the full commands, agents, hooks, and plugins surface.
 Qwen skills and hooks still require harness-specific adaptation and validation.
 
+Every MCP client receives complete tool annotations and may use a Cairnkeep
+least-authority profile independent of harness assets. Context-pack tools are
+ordinary read-only MCP tools and require the pack feature gate; authenticated
+HTTP additionally requires separate pack-HTTP consent. Approved pack skills
+remain context documents, not native harness Skills or automatic instructions.
+
 `cairn graph` is a separate, harness-independent project-shell CLI. Kimi Code,
 Pi, Qwen Code, Codex, and other shell-capable clients can invoke
 `cairn graph build|query|status|diff|explain|path` when `cairn` and the isolated
 `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.8.0
-**Last reviewed:** 2026-08-03
+**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
@@ -31,7 +31,12 @@ been rehearsed.
 | Deterministic two-pass evaluation and one-capability ablation | L16 | L16 | Brief; default off |
 | Shell completion | L02 | L02 | Ready; optional convenience |
 | Bounded meta-agent configuration loop | L17 | None | Design-only; not shipped |
-| Reviewed, evaluated, reversible skill-file improvement | L19 | L19 | Brief; explicit and default off |
+| 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
 
@@ -61,7 +66,10 @@ repository remains the canonical source for explanations and scripts.
 | `course-06-governance` | L15 | Capability precedence and restart boundaries |
 | `course-07-evaluation` | L16-L17 | Package-owned offline fixture and design boundary |
 | `course-08-graph` | L18 | Optional local structural graph workflow |
-| Planned: `course-09-skill` | L19 | Validated skill improvement after a disposable lab exists |
+| `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
 
@@ -71,14 +79,17 @@ 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 |
 | `cairn artifact` | L13 |
 | `cairn capabilities` | L15 |
+| `cairn mcp-tools` | L20 |
+| `cairn pack` | L21 |
 | `cairn notes` | L13 |
 | `cairn eval` | L16 |
 | `cairn skill` | L19 |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.8.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.
 
@@ -33,6 +37,8 @@ Run setup in that order, then confirm `cairn doctor`, `cairn sync --check`, and
 | 6 | Typed nodes and capability governance | Filtering and centrally inspectable feature state are needed |
 | 7 | Evaluation and ablation | A concrete change needs bounded measurement |
 | 8 | Validated skill improvement | Repeated resolved hindsight warrants a measured skill change |
+| 9 | Least-authority MCP profiles | A client should receive fewer tools than the default catalog |
+| 10 | Immutable context packs | Reviewed external context should be pinned without becoming memory |
 
 Every stage is independently useful. Stages 4-8 are opt-in and are not
 prerequisites for ordinary memory.
@@ -46,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
 
@@ -58,6 +65,9 @@ prerequisites for ordinary memory.
 | Context exploration | Configure an operator-owned exploration binary or route endpoint | Source/context goes only to the selected local or remote component | Check citations/cache; remove variables and relaunch | `course-04-operation` |
 | Containers | Rootless memory or workspace launcher | Named volumes persist; shared checkout mode is read/write, sandbox mode copies into a volume | Inspect mounts/volumes; remove only explicitly named disposable resources | `course-04-operation` |
 | 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
 
@@ -71,14 +81,15 @@ prerequisites for ordinary memory.
 | Typed nodes/import | `CAIRN_TYPED_MEMORY_NODES=1` | Restart MCP server; tool schema changes | Hard-filter search; dry-run, replay-safe import; `cairn doctor --repair` only for derived state | `course-05-evidence` |
 | Capability contract | `CAIRN_CAPABILITY_CONTRACT=1` | MCP changes require restart; operating changes apply next invocation | `cairn capabilities list|status|enable|disable|reset|logging`; digest identifies state only | `course-06-governance` |
 | Evaluation | `CAIRN_EVAL=1` for the coordinator process | No harness chosen by Cairnkeep | `validate` before `run`; inspect report, missingness and evidence scope; dry-run prune/delete | `course-07-evaluation` |
-| Validated skill improvement | Reviewed recurring hindsight; proposal adapter; `CAIRN_EVAL=1` for evaluation | No server restart; explicit subprocesses only | `cairn skill list|show`; exact-digest apply; concurrent-edit-safe rollback | Planned: `course-09-skill` |
+| Validated skill improvement | Reviewed recurring hindsight; proposal adapter; `CAIRN_EVAL=1` for evaluation | No server restart; explicit subprocesses only | `cairn skill list|show`; exact-digest apply; concurrent-edit-safe rollback | `course-09-skill` |
 | General meta-agent loop | Not shipped | Not applicable | Skill-file lifecycle only; no generic configuration loop or scheduler | `course-07-evaluation` |
+| Pack retrieval and skills | `CAIRN_CONTEXT_PACKS=1`; HTTP needs separate consent; skills need exact-digest approval | Restart MCP server | `cairn pack skills`; revoke approval or disable pack; no automatic execution | `course-10-trust-context` |
 
 ## Harness and maintenance checks
 
 - 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.

package/docs/learning/README.md

@@ -49,7 +49,11 @@ expanded only after their labs are executable.
 | L16 | [Evaluation and ablation](lessons/L16-evaluation.md) | Brief | 50 min |
 | L17 | [The agent boundary](lessons/L17-agent-boundary.md) | Brief | 25 min |
 | L18 | [Local code graph](lessons/L18-local-code-graph.md) | Brief | 35 min |
-| L19 | [Validated skill improvement](lessons/L19-validated-skill-improvement.md) | Brief | 50 min |
+| L19 | [Validated skill improvement](lessons/L19-validated-skill-improvement.md) | Ready | 50 min |
+| L20 | [Least-authority MCP tool profiles](lessons/L20-mcp-tool-profiles.md) | Ready | 25 min |
+| L21 | [Immutable context packs and skill approval](lessons/L21-context-packs.md) | Ready | 40 min |
+| L22 | [Operate Cairnkeep on native Windows](lessons/L22-native-windows.md) | Ready | 30 min |
+| L23 | [Guided setup and Pi memory](lessons/L23-guided-setup.md) | Ready | 35 min |
 
 The [curriculum coverage map](CURRICULUM-MAP.md) records where every public
 feature is introduced, practised, and operated. It also marks design-only work
@@ -68,7 +72,9 @@ Every complete lesson contains:
 
 The learner should never need optional infrastructure to complete L00-L06.
 Remote memory, RAG, routing, containers, graph indexing, structured capture,
-typed nodes, capability governance, and evaluation are separate opt-in modules.
+typed nodes, capability governance, evaluation, and context packs are separate
+opt-in modules. MCP profiles are restrictive and never activate an optional
+feature.
 
 ## For contributors
 

package/docs/learning/lessons/L00-why-cairnkeep.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.8.0
+**Tested with:** Cairnkeep 2.11.0
 
 ## Outcome
 

package/docs/learning/lessons/L01-safe-trial.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.8.0
+**Tested with:** Cairnkeep 2.11.0
 
 ## Outcome
 
@@ -26,7 +26,7 @@ ephemeral; the named course volume is persistent.
 1. Pull the public image:
 
    ```bash
-   podman pull ghcr.io/cairnkeep/cairnkeep:2.8.0
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.11.0
    ```
 
 2. Start the stdio server with a read-only root filesystem and no Linux
@@ -38,7 +38,7 @@ ephemeral; the named course volume is persistent.
      --read-only --cap-drop=all --security-opt=no-new-privileges \
      --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
      --volume cairnkeep-course-data:/data:Z,U \
-     ghcr.io/cairnkeep/cairnkeep:2.8.0 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.11.0 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it

package/docs/learning/lessons/L02-installation.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.8.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.11.0 and Node.js 22 or newer
 
 ## Outcome
 
@@ -41,7 +41,7 @@ machine-level steps.
 2. Install Cairnkeep:
 
    ```bash
-   npm install --global @cairnkeep/cli@2.8.0
+   npm install --global @cairnkeep/cli@2.11.0
    cairn --version
    ```
 
@@ -72,6 +72,15 @@ machine-level steps.
    Use `cairn completion zsh` or `cairn completion fish` for those shells.
    Completion is a convenience and is not another runtime component.
 
+   On native Windows PowerShell, use:
+
+   ```powershell
+   Invoke-Expression (& cairn completion powershell | Out-String)
+   ```
+
+   Bootstrap emits `.cmd` launchers on Windows; use
+   `.\.ai\start-claude.cmd` instead of the Unix `.sh` launcher.
+
 ## Verify
 
 Run both checks:

package/docs/learning/lessons/L03-first-project.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.8.0
+**Tested with:** Cairnkeep 2.11.0
 
 ## Outcome
 

package/docs/learning/lessons/L19-validated-skill-improvement.md

@@ -1,9 +1,9 @@
 # L19 - Validated skill improvement
 
-**Status:** Brief
+**Status:** Ready
 **Track:** Evidence and Evaluation
-**Planned time:** 50 minutes
-**Introduced in:** Cairnkeep 2.8.0
+**Time:** 50 minutes
+**Tested with:** Cairnkeep 2.11.0
 
 ## Outcome
 
@@ -12,7 +12,7 @@ skill proposal, measure it on separate exploration and confirmation tasks,
 apply only the exact eligible digest, and prove rollback without risking a real
 project.
 
-## Planned lesson
+## Lesson
 
 - Why harvest requires failures from at least two sessions and at least one
   recorded resolution.
@@ -31,30 +31,45 @@ project.
 
 ## Hands-on lab
 
-Use a future disposable `course-09-skill` checkpoint containing synthetic
-hindsight evidence, a small `SKILL.md`, deterministic proposal and evaluation
-adapters, and separate committed task sets. The lab will run:
+Use the disposable `course-09-skill` checkpoint from the synthetic course
+repository. It contains bounded hindsight evidence, one existing `SKILL.md`,
+deterministic proposal and evaluation adapters, and separate committed task
+sets. Keep every generated artifact under `.course-state/`:
 
 ```bash
-cairn skill harvest --project . --json
-cairn skill show --kind candidate --id CANDIDATE_ID
-cairn skill review --candidate CANDIDATE_ID --approve --json
-cairn skill propose --candidate CANDIDATE_ID --target skills/demo/SKILL.md \
-  --adapter fixtures/proposal-adapter.json --json
+git switch --detach course-09-skill
+scripts/reset-course-state.sh --yes
+node scripts/setup-skill-lab.mjs
+core=$(node scripts/locate-cairnkeep-core.mjs)
+lab="$PWD/.course-state/skill-project"
+export CAIRN_AGENTFS_BASE_DIR="$PWD/.course-state/agentfs"
+
+"$core/bin/cairn" skill harvest --project "$lab" --json
+"$core/bin/cairn" skill show --project "$lab" \
+  --kind candidate --id CANDIDATE_ID
+"$core/bin/cairn" skill review --project "$lab" \
+  --candidate CANDIDATE_ID --approve --json
+"$core/bin/cairn" skill propose --project "$lab" \
+  --candidate CANDIDATE_ID --target skills/course-review/SKILL.md \
+  --adapter "$lab/fixtures/proposal-adapter.json" --json
 
 export CAIRN_EVAL=1
-cairn skill evaluate --proposal PROPOSAL_ID \
-  --exploration-task-set eval/exploration.json \
-  --confirmation-task-set eval/confirmation.json \
-  --adapter eval/adapter.json --repetitions 2 --yes --json
-
-cairn skill apply --proposal PROPOSAL_ID --evaluation EVALUATION_ID \
+"$core/bin/cairn" skill evaluate --project "$lab" \
+  --proposal PROPOSAL_ID \
+  --exploration-task-set "$lab/eval/exploration.json" \
+  --confirmation-task-set "$lab/eval/confirmation.json" \
+  --adapter "$lab/eval/eval-adapter.json" \
+  --repetitions 1 --minimum-improvement 1 --yes --json
+
+"$core/bin/cairn" skill apply --project "$lab" \
+  --proposal PROPOSAL_ID --evaluation EVALUATION_ID \
   --confirm FULL_PROPOSAL_DIGEST --json
-cairn skill rollback --application APPLICATION_ID --confirm --json
+"$core/bin/cairn" skill rollback --project "$lab" \
+  --application APPLICATION_ID --confirm --json
 ```
 
-The lesson remains a Brief until that checkpoint is public and every command is
-rehearsed against the release package.
+Before applying, deliberately try an incorrect digest and verify it is rejected.
+After rollback, compare the target with `fixtures/skill/SKILL.md` byte for byte.
 
 ## Acceptance criteria
 
@@ -69,6 +84,22 @@ rehearsed against the release package.
 - The learner can explain why an eligible small task set supports one local
   decision but not a universal performance claim.
 
+## Common failures
+
+- If harvest returns no candidate, confirm the evidence contains the same
+  failure family in at least two distinct sessions and a recorded resolution.
+- If proposal validation rejects the adapter program, regenerate the lab and
+  verify its configuration resolves to the reviewed executable by absolute
+  path.
+- If evaluation is disabled, set `CAIRN_EVAL=1` only for this disposable lab
+  and retain the explicit `--yes` confirmation.
+- If task validation reports overlap or a mutable revision, use the committed
+  exploration and confirmation fixtures from `course-09-skill` unchanged.
+- If apply rejects the confirmation, copy the full `proposal_digest` from the
+  reviewed proposal rather than an ID, prefix, or candidate-content digest.
+- If rollback reports a concurrent target change, stop and inspect that edit;
+  do not overwrite it by copying the backup manually.
+
 ## Privacy and trust boundary
 
 Hindsight excerpts and skill content remain local until candidate approval.

package/docs/learning/lessons/L20-mcp-tool-profiles.md

@@ -0,0 +1,67 @@
+# L20 - Least-authority MCP tool profiles
+
+**Status:** Ready
+**Tested with:** Cairnkeep 2.11.0 and Node.js 22 or newer
+**Time:** 25 minutes
+
+## Outcome
+
+Classify every MCP tool as an observation or mutation, apply a read-only project
+profile, replace it with an exact allowlist, and prove that invalid authority is
+rejected before server startup.
+
+## Exercise
+
+Use a disposable directory so no real project policy changes:
+
+```bash
+lab=$(mktemp -d)
+cairn mcp-tools list --json >"$lab/catalog.json"
+cairn mcp-tools status --project "$lab" --json
+cairn mcp-tools set read-only --project "$lab"
+cairn mcp-tools status --project "$lab" --json >"$lab/read-only.json"
+test "$(stat -c '%a' "$lab/.ai/mcp-tools.json" 2>/dev/null || stat -f '%Lp' "$lab/.ai/mcp-tools.json")" = 600
+cairn mcp-tools set custom --tool memory_read --tool memory_search --project "$lab"
+cairn mcp-tools status --project "$lab" --json >"$lab/custom.json"
+```
+
+Inspect the catalog. Every entry must contain a title and four Boolean hints.
+The read-only profile must contain only tools whose `readOnlyHint` is true. The
+custom profile contains exactly the two named tools in canonical discovery
+order.
+
+Confirm environment precedence without changing the project file:
+
+```bash
+CAIRN_MCP_TOOL_PROFILE=full cairn mcp-tools status --project "$lab" --json
+```
+
+The source is `environment`; the project remains custom when the override is
+removed. A profile cannot enable a feature-gated tool, and a disabled capability
+still removes its tool. Restart the memory server after profile changes.
+
+## Common failures
+
+- `custom` without `--tool` is invalid because an empty accidental server is
+  more likely to be a configuration mistake than useful least authority.
+- Unknown names and a group/world-readable project config fail closed.
+- A running MCP session keeps its discovery snapshot until restarted.
+
+## Privacy and trust boundary
+
+Profiles do not read tool payloads or add telemetry. The digest identifies the
+allowlist, not the user's identity or the independent capability state. Client
+approval remains necessary for mutations even when a profile exposes them.
+
+## Recovery and acceptance
+
+```bash
+cairn mcp-tools reset --project "$lab"
+test ! -e "$lab/.ai/mcp-tools.json"
+rm -rf "$lab"
+```
+
+- Unknown custom tool names fail `set`, server startup, and `cairn doctor`.
+- Profile and capability digests are independent.
+- Conservative clients may execute read-only observations; mutations still
+  require their approval policy.

package/docs/learning/lessons/L21-context-packs.md

@@ -0,0 +1,79 @@
+# L21 - Immutable context packs and skill approval
+
+**Status:** Ready
+**Tested with:** Cairnkeep 2.11.0 and Node.js 22 or newer
+**Time:** 40 minutes
+
+## Outcome
+
+Build a local offline context pack, verify its immutable identity, pin it to a
+disposable project, and explain why document enablement and skill approval are
+different trust decisions.
+
+## Exercise
+
+```bash
+lab=$(mktemp -d)
+mkdir -p "$lab/pack" "$lab/project"
+printf '# Local guide\n\nSynthetic offline guidance.\n' >"$lab/pack/guide.md"
+export CAIRN_PACK_BASE_DIR="$lab/store"
+cairn pack init "$lab/pack" --id course-guide --version 1.0.0 \
+  --title "Course guide" --description "Synthetic local reference" \
+  --license Apache-2.0
+cairn pack lock "$lab/pack"
+cairn pack validate "$lab/pack"
+cairn pack install "$lab/pack" --json >"$lab/install.json"
+digest=$(node -e 'process.stdout.write(require(process.argv[1]).digest)' "$lab/install.json")
+cairn pack enable "$digest" --project "$lab/project"
+cairn pack show "$digest" --json
+cairn pack skills --project "$lab/project" --json
+```
+
+The local lifecycle makes no network request. The pack digest covers exact
+manifest and content bytes; `version` is a label, not identity. Objects remain
+under `$CAIRN_PACK_BASE_DIR` after disablement and ordinary uninstall.
+
+Add a file with `kind: skill`, refresh it with `cairn pack lock`, install the new
+digest, and enable it. `cairn pack skills` shows the skill but the MCP list/read
+surface does not expose it until:
+
+```bash
+cairn pack approve-skill NEW-PACK-DIGEST path/to/SKILL.md \
+  --confirm FILE-DIGEST --project "$lab/project"
+```
+
+Approval binds the project, pack, path, and file bytes. A later pack update
+invalidates it. Approval makes instructions readable only; it never executes or
+copies them into a harness.
+
+## Common failures
+
+- Adding a file after `init` requires declaring it in the manifest before
+  `lock`; undeclared content is rejected.
+- Git installation without `--ref`, a stale update confirmation, and removal of
+  an enabled digest all fail closed.
+- Enabling the pack does not expose a skill until its current file digest is
+  approved.
+
+## Privacy and trust boundary
+
+Local pack operations are offline. Configured semantic search can send enabled
+chunks and a query to the explicit embedding endpoint; failure falls back to
+substring search. A digest detects changed bytes but does not authenticate the
+publisher. Approved instructions remain untrusted readable context, not code.
+
+## Recovery and acceptance
+
+```bash
+cairn pack disable course-guide --project "$lab/project"
+cairn pack remove "$digest"
+unset CAIRN_PACK_BASE_DIR
+rm -rf "$lab"
+```
+
+- Traversal, symlinks, undeclared files, invalid UTF-8, and digest tampering fail
+  validation.
+- `update --check` never switches a project; apply requires the inspected digest.
+- `CAIRN_CONTEXT_PACKS=1` enables local read-only tools only after restart.
+- HTTP additionally requires `CAIRN_CONTEXT_PACK_HTTP=1` and existing auth.
+- A digest proves integrity, not publisher authenticity.

package/docs/learning/lessons/L22-native-windows.md

@@ -0,0 +1,83 @@
+# L22 - Operate Cairnkeep on native Windows
+
+**Status:** Ready
+**Track:** Operator
+**Time:** 30 minutes
+**Tested with:** Cairnkeep 2.11.0, Windows x64, and Node.js 22 or newer
+
+## Outcome
+
+You can prove that Cairnkeep is running natively from PowerShell, bootstrap a
+path containing spaces, inspect its security boundary, and perform a reversible
+uninstall without relying on WSL or Git Bash.
+
+## Exercise
+
+From PowerShell:
+
+```powershell
+npm install --global @cairnkeep/cli@2.11.0
+cairn version
+
+$Lab = Join-Path $env:TEMP 'Cairnkeep Windows Lab'
+New-Item -ItemType Directory -Force -Path $Lab | Out-Null
+cairn bootstrap $Lab
+cairn sync --apply --live-root (Join-Path $Lab '.claude-test')
+cairn sync --check --live-root (Join-Path $Lab '.claude-test')
+Push-Location $Lab
+cairn doctor
+Pop-Location
+```
+
+Verify that `.ai/start-claude.cmd`, `.ai/start-harness.ps1`, and the managed
+Claude assets exist. `cairn doctor` must identify native Windows x64 and complete
+an MCP stdio handshake.
+
+## Permission check
+
+```powershell
+Get-Acl (Join-Path $Lab '.ai\capabilities.json') | Format-List
+```
+
+Managed private files remove inherited broad access and retain only the current
+identity, Local System, and Administrators. Do not replace this with a Unix-mode
+check; Windows authorization is an ACL contract.
+
+## Recovery exercise
+
+```powershell
+cairn uninstall --dry-run --live-root (Join-Path $Lab '.claude-test') $Lab
+cairn uninstall --yes --live-root (Join-Path $Lab '.claude-test') $Lab
+```
+
+The command prints the timestamped backup location. Inspect `manifest.json` and
+`revert.ps1`; run the revert script only if you intentionally want to restore
+the removed managed assets.
+
+## Common failures
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `cairn.cmd` is not found | npm's global directory is not on `PATH` | Run `npm prefix -g`, add the resulting directory to the user `PATH`, then open a new PowerShell session |
+| Hook registration reports drift | Managed `.cmd` hook or settings entry is absent | Run `cairn sync --apply`, then repeat `cairn sync --check` |
+| Memory export fails | `sqlite3.exe` is absent | Install SQLite and confirm `Get-Command sqlite3.exe`; runtime and import remain available |
+| A private-state check fails | The file inherited a broader ACL | Preserve the file, inspect it with `Get-Acl`, and recreate it through the owning Cairnkeep command |
+
+## Privacy and trust boundary
+
+Native support changes process, path, and permission mechanics; it does not
+enable a network, model, capture, artifact, context-pack, or capability flag.
+The Windows ACL is a local-host access boundary, while pack digests establish
+content integrity rather than publisher authenticity. Task Scheduler and purge
+operations remain separate explicit actions.
+
+## Boundaries
+
+- Windows x64 is native; Windows ARM64 is currently x64 emulation.
+- `sqlite3.exe` is optional for runtime and import, but required for a WAL-safe
+  memory export.
+- WSL is a separate Linux topology. Git Bash is not native-Windows evidence.
+- Task Scheduler changes remain opt-in through `cairn audit-timer`.
+
+See [Native Windows operation](../../native-windows.md) for the complete
+platform contract.