@cairnkeep/cli 2.8.0 → 2.9.0

package/CHANGELOG.md

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

package/README.md

@@ -15,7 +15,7 @@ Qwen Code, Pi, and other MCP clients).
 ## Status
 
 Shipped: the memory server, the `cairn` CLI (`bootstrap`, `memory-server`, `sync`, `sync-pi`, `sync-kimi`,
-`doctor`, `trajectory`, `artifact`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
+`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
@@ -41,7 +41,7 @@ and 20 are end-of-life upstream.
 | Qwen Code on Linux/macOS | Memory MCP server plus project launcher; no Cairnkeep operating-layer assets yet |
 | Pi on Linux/macOS | Native opt-in trajectory extension, launcher, and `/graphify` prompt; no bundled MCP bridge |
 | Codex CLI | Memory MCP server; no Cairnkeep operating-layer assets |
-| Other MCP clients | Memory and optional domain-knowledge MCP tools |
+| 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) |
 
 The `cairn graph` CLI is harness-independent and can be run from a project
@@ -82,6 +82,9 @@ storage paths, secrets, and private derived images, see
   `.ai/` launchers + env; `cairn doctor` health-checks the configured pieces;
   `cairn trajectory list|show|prune` manages opt-in local session trajectories;
   `cairn artifact list|show|delete|prune` manages opt-in local artifacts;
+  `cairn mcp-tools list|status|set|reset` applies least-authority discovery
+  profiles; `cairn pack` validates, installs, pins, updates, and approves
+  immutable external context;
   `cairn eval validate|run|ablate|report|prune|delete` coordinates explicit
   local two-pass and one-capability-at-a-time measurements;
   `cairn skill harvest|list|show|review|propose|evaluate|apply|rollback`
@@ -262,6 +265,11 @@ search):
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
 | `CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
 | `CAIRN_AGENTFS_BASE_DIR` | Base dir for global memory scopes (default `~/.cairnkeep`) |
+| `CAIRN_MCP_TOOL_PROFILE` | Process override for MCP exposure: `full`, `read-only`, or `custom` |
+| `CAIRN_MCP_ALLOWED_TOOLS` | Comma-separated exact allowlist required by a custom process profile |
+| `CAIRN_CONTEXT_PACKS` | Opt in to local context-pack list/search/read tools (default off) |
+| `CAIRN_CONTEXT_PACK_HTTP` | Separately consent to context-pack tools over authenticated HTTP (default off) |
+| `CAIRN_PACK_BASE_DIR` | Immutable pack objects, source records, pointers, and retrieval cache (default `~/.cairnkeep/packs`) |
 | `CAIRN_TRAJECTORY_CAPTURE` | Opt in to local structured session capture (`1`, `true`, `yes`, or `on`; default off) |
 | `CAIRN_TRAJECTORY_SESSION_MAX_BYTES` | Maximum serialized bytes per captured session (default `5242880`, 5 MiB) |
 | `CAIRN_TRAJECTORY_STORE_MAX_BYTES` | Maximum logical bytes across local trajectories (default `268435456`, 256 MiB) |
@@ -308,6 +316,22 @@ remote memory, and delegated exploration can send content to endpoints you
 configure. Review [Privacy and data flow](docs/privacy-and-data-flow.md) before
 enabling them.
 
+### MCP authority and context packs
+
+Every tool publishes a stable title and all four MCP annotation hints. Use
+`cairn mcp-tools set read-only` for observation-only clients, or an exact custom
+allowlist when a workflow needs fewer tools. Process settings override the
+strict project file; the default remains `full`. Profiles only remove tools and
+cannot bypass capability or feature gates. See
+[MCP tool profiles](docs/mcp-tool-profiles.md).
+
+Context packs are immutable, digest-addressed local document/skill bundles.
+They are installed and project-pinned manually; no background Git sync occurs.
+With `CAIRN_CONTEXT_PACKS=1`, enabled documents are searchable through three
+read-only MCP tools. Skills remain invisible until their exact file digest is
+approved, and are never copied or executed. See
+[Immutable context packs](docs/context-packs.md).
+
 ### Managed capability contract (opt-in)
 
 `CAIRN_CAPABILITY_CONTRACT=1` enables one versioned, typed boundary around the
@@ -482,6 +506,8 @@ exposes trajectory data. See the [operating guide](docs/operating.md#compaction-
 - **Memory storage and deployment** — [docs/storage.md](docs/storage.md)
 - **Podman and OCI containers** — [docs/containers.md](docs/containers.md)
 - **Privacy and data flow** — [docs/privacy-and-data-flow.md](docs/privacy-and-data-flow.md)
+- **MCP tool profiles** — [docs/mcp-tool-profiles.md](docs/mcp-tool-profiles.md)
+- **Immutable context packs** — [docs/context-packs.md](docs/context-packs.md)
 - **Validated skill improvement** — [docs/skill-improvement.md](docs/skill-improvement.md)
 - **Git providers** — [docs/git-providers.md](docs/git-providers.md)
 - **Support** — [SUPPORT.md](SUPPORT.md)

package/bin/cairn

@@ -52,6 +52,12 @@ Usage:
                            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
@@ -72,7 +78,7 @@ Usage:
   cairn audit-timer [--on-calendar SPEC] [--para-root PATH] [--render-only DIR]
                            Install (opt-in) a systemd user timer that runs the
                            memory+wiki audit on a schedule; prints a cron alternative.
-  cairn uninstall [--dry-run] [--yes] [--purge-memory] [--live-root DIR]
+  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
@@ -113,6 +119,12 @@ case "$cmd" in
   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" "$@"
     ;;

package/docs/context-packs.md

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

package/docs/harness-compatibility.md

@@ -14,13 +14,19 @@ commands, hooks, plugins, or trajectory adapters.
 | 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 |
 | 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

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.9.0
+**Last reviewed:** 2026-08-06
 
 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,9 @@ 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 |
 
 ## Release Review
 
@@ -61,7 +63,8 @@ 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 |
 
 ## Command Ownership
 
@@ -79,6 +82,8 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 | `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.9.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
@@ -33,6 +33,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.
@@ -58,6 +60,8 @@ 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` |
 
 ## Evidence, governance, and measurement
 
@@ -71,8 +75,9 @@ 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
 

package/docs/learning/README.md

@@ -49,7 +49,9 @@ 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 |
 
 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 +70,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.9.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.9.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.9.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.9.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.9.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.9.0
    cairn --version
    ```
 

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.9.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.9.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.9.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.