@cairnkeep/cli 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-07-29
+
+### Added
+
+- Add Kimi Code as a supported memory client with a generated project launcher,
+  local stdio guidance, and tested authenticated remote HTTP configuration.
+- Add an explicit harness compatibility matrix and a documented validation
+  process for future MCP clients.
+
+### Fixed
+
+- Document that Kimi requires a literal MCP URL and a token reference through
+  `bearerTokenEnvVar`, preventing invalid `${VAR}` URL configurations without
+  writing bearer-token values to project files.
+
 ## [2.4.0] - 2026-07-29
 
 ### Added
@@ -196,7 +211,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.4.0...HEAD
+[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.5.0...HEAD
+[2.5.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.3.1...v2.4.0
 [2.3.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.3.0...v2.3.1
 [2.3.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.2.1...v2.3.0

package/README.md

@@ -9,7 +9,8 @@
 A *cairn* is a stack of stones left as a trail marker for whoever follows; a
 *keep* is where you store what matters. **Cairnkeep** is where coding agents
 stack durable memory — decisions, pitfalls, patterns — and follow the trail
-across sessions, projects, and harnesses (Claude Code, OpenCode, Pi, …).
+across sessions, projects, and harnesses (Claude Code, OpenCode, Kimi Code,
+Pi, and other MCP clients).
 
 ## Status
 
@@ -36,6 +37,7 @@ and 20 are end-of-life upstream.
 |---|---|
 | Claude Code on Linux/macOS | Memory server plus commands, agents, hooks, and launchers |
 | OpenCode on Linux/macOS | Memory server plus commands, plugins, hooks, and launchers |
+| Kimi 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 and launcher; no bundled MCP bridge |
 | Codex CLI | Memory MCP server; no Cairnkeep operating-layer assets |
 | Other MCP clients | Memory and optional domain-knowledge MCP tools |
@@ -44,6 +46,9 @@ and 20 are end-of-life upstream.
 Linux, macOS, Bash 3.2 portability, and clean Node 22/24/26 runtime checks
 are exercised in CI.
 
+See [Harness compatibility](docs/harness-compatibility.md) for exact support
+levels, Kimi configuration, and candidates that are not yet runtime-tested.
+
 ## Try with Podman
 
 The minimal OCI image runs the memory server as an unprivileged user and keeps
@@ -148,6 +153,12 @@ patterns/transactional-migrations: Use transactional migrations for schema chang
 The exact command rendering depends on the client. Any MCP client can call
 `memory_write` and `memory_search` directly.
 
+For Kimi Code, bootstrap supplies a launcher and Kimi reads the repository's
+MCP configuration. A local stdio entry uses `cairn memory-server`. Remote Kimi
+configuration requires a literal URL and supports a token reference through
+`bearerTokenEnvVar`; it does not expand `${VAR}` in the URL. See
+[Harness compatibility](docs/harness-compatibility.md#kimi-code).
+
 For Pi, install the local trajectory adapter and use the scaffolded launcher:
 
 ```bash

package/docs/building-an-overlay.md

@@ -27,13 +27,14 @@ manifest, profile-lock, private-registry, and rollback contract.
 
 ## The launcher seams
 
-The generic launchers (`.ai/start-claude.sh`, `.ai/start-opencode.sh`, scaffolded
-by `cairn bootstrap`) run three optional hooks, each a no-op when absent:
+The generic launchers (`.ai/start-claude.sh`, `.ai/start-opencode.sh`,
+`.ai/start-kimi.sh`, and `.ai/start-pi.sh`, scaffolded by `cairn bootstrap`) run
+optional hooks, each a no-op when absent:
 
 | Seam | When | Use it for |
 |---|---|---|
 | `.ai/pre-launch.sh` | sourced after `.env`, before launch | export a provider base URL / credentials, refresh a token, run a connectivity check, or **abort** the launch by returning non-zero |
-| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered onto the harness (`--settings` for Claude Code, `OPENCODE_CONFIG` for OpenCode); process env still wins, so an inline value beats the file |
+| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered onto Claude Code (`--settings`) or OpenCode (`OPENCODE_CONFIG`); Kimi and Pi leave it available to hooks but do not interpret it |
 | `.ai/post-exit.sh` | sourced after the harness exits | teardown; `CAIRN_EXIT_STATUS` holds the exit code |
 
 **Typical overlay launcher** — a corporate wrapper needs a non-default provider

package/docs/harness-compatibility.md

@@ -0,0 +1,117 @@
+# Harness compatibility
+
+Cairnkeep separates memory transport from harness-specific operating assets.
+An MCP client can use the memory tools without also supporting Cairnkeep's
+commands, hooks, plugins, or trajectory adapters.
+
+## Support levels
+
+| Harness | Supported surface | Runtime status |
+|---|---|---|
+| Claude Code | Memory MCP, commands, agents, hooks, launcher | Exercised by Cairnkeep tests |
+| OpenCode | Memory MCP, commands, workflows, plugins, launcher | Exercised by Cairnkeep tests |
+| Kimi Code | Memory MCP, `AGENTS.md`, launcher | Launcher tested; remote MCP tested with Kimi Code 0.30.0 |
+| Pi | Native opt-in trajectory extension and launcher | 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 |
+
+Only Claude Code and OpenCode currently receive the complete operating layer.
+Kimi skills and hooks require harness-specific adaptation and validation before
+they can be presented as equivalent. In Kimi, call MCP tools directly or use
+ordinary prompts until that work is complete.
+
+## Kimi Code
+
+Kimi Code reads three MCP files, in increasing precedence:
+
+1. `~/.kimi-code/mcp.json`;
+2. the repository-root `.mcp.json`, for Claude compatibility;
+3. `.kimi-code/mcp.json` in the working directory.
+
+Each file must be valid before entries are merged. A later Kimi-specific entry
+does not rescue an invalid repository-root entry.
+
+### Local stdio
+
+Create `.kimi-code/mcp.json` in a trusted project:
+
+```json
+{
+  "mcpServers": {
+    "cairn-memory": {
+      "command": "cairn",
+      "args": ["memory-server"]
+    }
+  }
+}
+```
+
+Then launch through the generated project launcher:
+
+```bash
+./.ai/start-kimi.sh
+```
+
+The server is a local child process and writes to the storage selected by the
+launcher's `.ai/.env`. Kimi warns that project MCP commands execute when a
+session starts, so use this only in a repository you trust.
+
+### Remote HTTP
+
+Kimi validates `url` as a literal URL and does not expand `${VAR}` there. Keep
+the resolved URL in a private `.kimi-code/mcp.json`, reference the bearer token
+by environment-variable name, and keep non-secret routing headers explicit:
+
+```json
+{
+  "mcpServers": {
+    "cairn-memory": {
+      "url": "https://memory.example.com/mcp",
+      "bearerTokenEnvVar": "CAIRN_MEMORY_HTTP_TOKEN",
+      "headers": {
+        "X-Cairn-Project": "example-project",
+        "X-Cairn-Scopes": "identity,personal,project",
+        "X-Cairn-AnythingLLM-Workspaces": "example-workspace"
+      }
+    }
+  }
+}
+```
+
+Do not commit the private file when the endpoint or routing metadata is private.
+Add it to `.git/info/exclude` or generate it through an overlay. The token value
+stays in `.ai/.env` and is read at connection time.
+
+If the repository-root `.mcp.json` contains
+`"url": "${CAIRN_MEMORY_REMOTE_URL}"`, Kimi fails before launch with
+`Invalid URL`. Replace that private file's URL with a resolved value, or remove
+the entry when Kimi's private override is the intended owner. Do not place the
+token value in either file.
+
+Kimi MCP configuration is documented at
+[Kimi Code MCP](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/mcp.html).
+
+## Candidate memory clients
+
+The following clients have documented MCP support and are reasonable adapter
+candidates, but Cairnkeep does not yet ship their launchers, configuration
+writers, operating assets, or runtime CI:
+
+| Client | Documented MCP surface | Cairnkeep status |
+|---|---|---|
+| Gemini CLI | `mcpServers` in `settings.json` | Candidate for stdio and HTTP memory tests |
+| GitHub Copilot CLI | `copilot mcp` and `.mcp.json` | Candidate for memory plus shared skills |
+| Qwen Code | `qwen mcp` and MCP configuration | Candidate for stdio and HTTP memory tests |
+| goose | MCP extensions and CLI session extension loading | Candidate for memory and recipe integration |
+
+Primary references:
+
+- [Gemini CLI MCP](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)
+- [GitHub Copilot CLI MCP](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)
+- [Qwen Code MCP](https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/)
+- [goose](https://github.com/aaif-goose/goose)
+
+Support should be added one client at a time with a clean install, a local
+stdio handshake, an authenticated HTTP handshake, a real write/recall canary,
+storage-path verification, and removal instructions. Documented MCP support by
+itself is not enough to claim Cairnkeep support.

package/docs/learning/CURRICULUM-MAP.md

@@ -0,0 +1,91 @@
+# Curriculum Coverage Map
+
+**Baseline:** Cairnkeep 2.5.0
+**Last reviewed:** 2026-07-29
+
+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
+still a production brief. A feature may be shipped while its lesson is still a
+brief; the status must remain visible rather than implying that the exercise has
+been rehearsed.
+
+## Coverage
+
+| Product surface | Introduced | Practised or operated | Learning status |
+|---|---|---|---|
+| Local stdio memory and MCP registration | L00-L02 | L03-L04 | L00-L03 Ready; L04 Brief |
+| Project bootstrap, launchers, and contributor mode | L02-L03 | L05 | L02-L03 Ready; L05 Brief |
+| Memory scopes, keys, search, supersession, and history | L04 | L04-L05 | Brief |
+| Wiki, alignment, graph, and repository quality workflows | L05-L06 | L05-L06 | Brief |
+| Storage placement, export/import, and authenticated remote memory | L07 | L07-L08 | Brief |
+| Document RAG | L00 | L09 | Brief; optional |
+| token-miser exploration and routing | L00 | L10 | Brief; optional |
+| Rootless containers and persistent service operation | L01 | L11 | L01 Ready; L11 Brief |
+| Private managed distributions | L12 | L12 | Brief; optional |
+| Structured trajectories and Pi capture adapter | L13 | L13 | Brief; default off |
+| Hindsight-note distillation, lookup, enrichment, and promotion | L13 | L13-L14 | Brief; default off |
+| Compaction continuity and immutable artifacts | L13 | L13 | Brief; default off |
+| Typed memory nodes, filters, address spaces, and structured import | L14 | L14 | Brief; default off |
+| Managed eight-capability contract and payload-free callbacks | L15 | L15-L16 | Brief; default off |
+| 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 |
+
+## Release Review
+
+For every minor release:
+
+1. Compare the changelog and `cairn help` with this table.
+2. Assign every new command, store, network flow, or runtime default to a
+   lesson before release.
+3. Re-run commands in every Ready lesson against the release candidate.
+4. Update `Tested with` only after those commands pass.
+5. Keep untested additions as Brief, even when the underlying feature ships.
+6. Re-record only scripts whose observable behavior or mental model changed.
+
+## Course Spine
+
+The public `cairnkeep-course-labs` repository is the executable spine; this
+repository remains the canonical source for explanations and scripts.
+
+| Checkpoint | Lessons | Purpose |
+|---|---|---|
+| `course-00-app` | L00-L02 | Plain synthetic application before Cairnkeep |
+| `course-01-bootstrap` | L03 | Neutral bootstrap and isolated environment |
+| `course-02-memory` | L04-L05 | Memory lifecycle and derived knowledge |
+| `course-03-quality` | L06 | Repository review and deliberately vulnerable fixture |
+| `course-04-operation` | L07-L12 | Storage, routing, integrations, containers, overlays |
+| `course-05-evidence` | L13-L14 | Evidence lifecycle and typed memory |
+| `course-06-governance` | L15 | Capability precedence and restart boundaries |
+| `course-07-evaluation` | L16-L17 | Package-owned offline fixture and design boundary |
+
+## Command Ownership
+
+Every top-level CLI command has a teaching destination. This table is checked
+against `cairn help` so a new command cannot bypass a curriculum decision.
+
+| Command | Primary lesson |
+|---|---|
+| `cairn bootstrap` | L03 |
+| `cairn memory-server` | L02 |
+| `cairn sync` | L02 |
+| `cairn sync-pi` | L13 |
+| `cairn doctor` | L03; advanced repair in L13-L14 |
+| `cairn trajectory` | L13 |
+| `cairn artifact` | L13 |
+| `cairn capabilities` | L15 |
+| `cairn notes` | L13 |
+| `cairn eval` | L16 |
+| `cairn memory` | L07-L08 |
+| `cairn audit-timer` | L05 and L13 |
+| `cairn uninstall` | L02 and L11-L12 |
+| `cairn completion` | L02 |
+| `cairn version` | L02 |
+| `cairn help` | L02 |
+
+## Claim Boundary
+
+The bundled evaluation fixtures prove framework mechanics only. They do not
+show that Cairnkeep improves quality, efficiency, cost, or latency. Course
+material may teach how to design and inspect an experiment, but it must not make
+a product-performance claim without separately validated live evidence.

package/docs/learning/FEATURE-GUIDE.md

@@ -0,0 +1,86 @@
+# Cairnkeep feature guide
+
+**Baseline:** Cairnkeep 2.5.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
+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.
+
+## 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`.
+3. **Operating layer:** harness commands, agents, and hooks installed by
+   `cairn sync --apply` or the harness-specific equivalent.
+
+Run setup in that order, then confirm `cairn doctor`, `cairn sync --check`, and
+`cairn memory path` before trusting the installation.
+
+## Recommended adoption sequence
+
+| Stage | Add | Stop here when |
+|---|---|---|
+| 1 | Local memory, review, recall, history | Durable project context is the only goal |
+| 2 | Wiki, alignment, graph, repository/security review | Tracked derived knowledge and quality workflows are sufficient |
+| 3 | Backup, migration, multiple-machine routing | Storage placement and recovery are predictable |
+| 4 | Document RAG or context exploration | An optional external corpus or faster repository exploration is justified |
+| 5 | Trajectories, notes, compaction, artifacts | Local session evidence has an explicit retention purpose |
+| 6 | Typed nodes and capability governance | Filtering and centrally inspectable feature state are needed |
+| 7 | Evaluation and ablation | A concrete change needs bounded measurement |
+
+Every stage is independently useful. Stages 4-7 are opt-in and are not
+prerequisites for ordinary memory.
+
+## Core and derived knowledge
+
+| Surface | Interface | Default and storage | Verify or reverse | Course checkpoint |
+|---|---|---|---|---|
+| Scoped memory | `/remember`, `/recall`, MCP memory tools | Available after MCP registration; named/global DBs under `CAIRN_AGENTFS_BASE_DIR`, project DB under `<server-cwd>/.agentfs/` | Recall in a new session; use reviewed delete/supersession rather than filesystem removal | `course-02-memory` |
+| Memory lifecycle | `/memory-review`, `memory_supersede`, `memory_history`, reviewed apply/invalidate tools | Durable history; no automatic promotion | Inspect key history and provenance | `course-02-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` |
+| Knowledge graph | `/graphify` and graph tools | Disabled until configured/invoked; derived graph files | Rebuild from canonical sources; never treat the graph as canonical | `course-02-memory` |
+| Repository quality | `/repo-review`, `/security-audit` | On-demand workflow; findings are hypotheses until reproduced | Require file/line evidence and regression tests | `course-03-quality` |
+
+## Storage and optional topology
+
+| Surface | Enable | Data/network boundary | Verify or reverse | Course checkpoint |
+|---|---|---|---|---|
+| Backup/restore | `cairn memory path|export|import` | Export is WAL-safe for named/global DBs and requires `sqlite3`; import backs up replaced DBs and is not a merge | Restore first into a disposable store, then run doctor/recall | `course-04-operation` |
+| Remote memory | Explicit authenticated HTTP server plus explicit client URL/token | Storage belongs to the server host; project headers route but are not authorization | Inspect effective routing and run legacy/project canaries; revert client registration to stdio | `course-04-operation` |
+| Multiple machines | Deliberate local-per-machine or shared-server policy | No automatic account, host, or endpoint discovery | Predict the server process and DB path from each launcher before use | `course-04-operation` |
+| Document RAG | Configure the optional RAG endpoint/key and workspace | Selected documents may leave the repository for the configured service | Verify citations and sync status; unset configuration to return to standalone memory | `course-04-operation` |
+| 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` |
+
+## Evidence, governance, and measurement
+
+| Surface | Explicit opt-in | Restart | Inspect and clean up | Course checkpoint |
+|---|---|---|---|---|
+| Trajectories | `CAIRN_TRAJECTORY_CAPTURE=1` | Relaunch harness | `cairn trajectory list|show|prune`; local, redacted, bounded, reasoning omitted | `course-05-evidence` |
+| Hindsight notes | `CAIRN_NOTE_DISTILLATION=1` | No online callback; run job separately | `cairn notes distill|search-error|doctor|promote`; promotion requires corroboration/confirmation | `course-05-evidence` |
+| Note enrichment | Distillation plus separate enrichment flag, endpoint, key, and model | No server restart for the offline job | Failure leaves deterministic note usable; unset enrichment flag | `course-05-evidence` |
+| Compaction continuity | `CAIRN_COMPACTION_CAPTURE=1` | Sync assets and relaunch harness | Inspect provenance/age; remove retained local artifacts explicitly | `course-05-evidence` |
+| Artifact tools | `CAIRN_ARTIFACT_STORE=1`; HTTP needs a second flag and existing HTTP auth | Restart MCP server when tool exposure changes | `cairn artifact list|show|delete|prune` with dry runs | `course-05-evidence` |
+| 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` |
+| Meta-agent loop | Not shipped | Not applicable | Design contract only; never advertise as an available command | `course-07-evaluation` |
+
+## 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 adapter is installed.
+- Use `cairn doctor --repair` only after preserving the affected store and only
+  for repairable derived indexes/metadata.
+- Use `cairn uninstall --dry-run` before uninstall; durable memory is retained
+  unless purge is explicitly requested.
+- Revisit the [storage guide](../storage.md) and
+  [privacy/data-flow guide](../privacy-and-data-flow.md) before enabling a new
+  network or retention path.

package/docs/learning/PRODUCTION-PLAN.md

@@ -13,16 +13,19 @@ state.
 - Use short videos that can be replaced independently after product changes.
 - Treat commands, expected output, and recovery instructions as tested product
   surfaces rather than informal prose.
+- Keep default-off evidence and evaluation features out of the quickstart.
+- Never convert framework-fixture results into product-performance claims.
 
 ## Wave 0 - Course foundation
 
 **Deliverables**
 
-- Stable lesson IDs L00-L12.
-- Quickstart, practitioner, and operator tracks.
+- Stable lesson IDs L00-L17.
+- Quickstart, practitioner, evidence-and-evaluation, and operator tracks.
 - Lesson, video, and instructor templates.
 - Complete L00-L03 lesson and recording scripts.
-- Briefs and acceptance criteria for L04-L12.
+- Briefs and acceptance criteria for L04-L17.
+- A release-reviewed feature-to-lesson coverage map.
 
 **Exit gate**
 
@@ -45,16 +48,21 @@ round trip and can explain where their memory is stored.
 
 ## Wave 2 - Daily practitioner value
 
-Expand L04-L06 in this order:
+Expand L04-L06 and L13 in this order:
 
 1. L04 memory keys, scopes, search, history, and review.
 2. L05 wiki, alignment, session hooks, and derived-knowledge boundaries.
 3. L06 `/repo-review` and `/security-audit` against a deliberately vulnerable
    toy repository.
+4. L13 structured evidence, redaction, deterministic hindsight, compaction,
+   artifact inspection, and cleanup against synthetic sessions.
 
-Create the public `cairnkeep-course-labs` repository during this wave, not
-before. It must contain synthetic code only, prominent safety warnings, tagged
-starter states, and solution branches.
+Use the public `cairnkeep-course-labs` repository created for this wave. Its
+synthetic Trail Ledger project, prominent safety boundary, eight tagged
+checkpoints, executable verification, offline evaluation route, and
+`solutions/review-target` branch are the shared demo source. Expand lesson prose
+and presenter scripts against those immutable starts rather than copying the
+demo into this repository.
 
 **Exit gate:** a learner can complete all labs from a fresh clone, and CI resets
 and verifies every starter state.
@@ -84,7 +92,26 @@ optional component.
 **Exit gate:** disabling either integration returns the learner to a healthy
 standalone Cairnkeep workflow.
 
-## Wave 5 - Operators and platform teams
+## Wave 5 - Evidence governance and measurement
+
+Expand L14-L17 in dependency order:
+
+1. L14 typed nodes, hard filters, logical note addresses, and import replay.
+2. L15 capability precedence, omission, restart boundaries, and value-free
+   callbacks.
+3. L16 offline two-pass fixtures, one-capability ablation, report reading,
+   missingness, uncertainty, retention, and claim boundaries.
+4. L17 current-versus-design-only ownership and approval boundaries.
+
+The first L16 lab must use only the committed deterministic fixture. A separate
+live-evaluation course artifact may be introduced only after its provenance and
+claim anchors pass the repository's runtime-evidence verifier.
+
+**Exit gate:** the learner can inspect effective state and retained evidence,
+execute the fixture safely, and state exactly why it does not prove a quality or
+efficiency gain.
+
+## Wave 6 - Operators and platform teams
 
 Expand L11-L12:
 
@@ -95,13 +122,15 @@ Expand L11-L12:
 **Exit gate:** the operator can explain every host mount, network boundary,
 credential source, storage destination, and rollback action.
 
-## Wave 6 - Publication and maintenance
+## Wave 7 - Publication and maintenance
 
-1. Publish a landing article linking to the three tracks.
+1. Publish a landing article linking to the four tracks.
 2. Publish videos as a playlist with lesson IDs in every title.
 3. Add release compatibility metadata to each completed lesson.
 4. Run a command-verification pass for every Cairnkeep minor release.
-5. Review learner feedback monthly during the pilot, then quarterly.
+5. Reconcile `cairn help`, the changelog, and the curriculum coverage map for
+   every minor release.
+6. Review learner feedback monthly during the pilot, then quarterly.
 
 ## How we will work together
 
@@ -117,6 +146,8 @@ For each lesson, follow this loop:
 8. **Pilot:** give the written lesson to a learner before publishing the video.
 9. **Improve:** incorporate observed failures and publish both formats together.
 
-The immediate next step after merging Wave 0 is the unrecorded L00-L03
-rehearsal. Use the checklist in the [instructor guide](instructor-guide.md) and
-record questions rather than polishing video production prematurely.
+The immediate next step is an unrecorded L00-L03 rehearsal using
+`course-00-app` and `course-01-bootstrap`. Then expand L04-L06 and L13 against
+`course-02-memory`, `course-03-quality`, and `course-05-evidence`. Use the
+checklist in the [instructor guide](instructor-guide.md) and record questions
+rather than polishing video production prematurely.

package/docs/learning/README.md

@@ -10,9 +10,18 @@ Choose the shortest track that matches your goal:
 
 - [Quickstart](tracks/quickstart.md) - prove the core value in about 75 minutes.
 - [Practitioner](tracks/practitioner.md) - adopt Cairnkeep in daily project work.
+- [Evidence and evaluation](tracks/evidence-and-evaluation.md) - inspect optional
+  session evidence, govern capabilities, and measure changes without overstating
+  results.
 - [Operator](tracks/operator.md) - storage, optional services, containers, and
   managed distributions.
 
+For a single view of every released surface, its default, storage boundary,
+restart requirement, and rollback path, use the [feature guide](FEATURE-GUIDE.md).
+The public [course labs](https://github.com/cairnkeep/cairnkeep-course-labs)
+provide one synthetic project with tagged checkpoints shared by lessons,
+articles, workshops, and videos.
+
 Lessons marked **Ready** include a complete exercise and presenter script.
 Lessons marked **Brief** define outcomes and acceptance criteria and will be
 expanded according to the [production plan](PRODUCTION-PLAN.md).
@@ -34,6 +43,15 @@ expanded according to the [production plan](PRODUCTION-PLAN.md).
 | L10 | [Faster context exploration](lessons/L10-context-exploration.md) | Brief | 30 min |
 | L11 | [Containers and isolation](lessons/L11-containers.md) | Brief | 40 min |
 | L12 | [Managed overlays](lessons/L12-managed-overlays.md) | Brief | 45 min |
+| L13 | [Session evidence and hindsight](lessons/L13-session-evidence.md) | Brief | 45 min |
+| L14 | [Typed memory and controlled import](lessons/L14-typed-memory.md) | Brief | 40 min |
+| L15 | [Capability governance](lessons/L15-capability-governance.md) | Brief | 35 min |
+| L16 | [Evaluation and ablation](lessons/L16-evaluation.md) | Brief | 50 min |
+| L17 | [The agent boundary](lessons/L17-agent-boundary.md) | Brief | 25 min |
+
+The [curriculum coverage map](CURRICULUM-MAP.md) records where every public
+feature is introduced, practised, and operated. It also marks design-only work
+that must not be taught as a released capability.
 
 ## Teaching contract
 
@@ -47,7 +65,8 @@ Every complete lesson contains:
 6. A presenter-ready video script.
 
 The learner should never need optional infrastructure to complete L00-L06.
-Remote memory, RAG, routing, and containers are separate opt-in modules.
+Remote memory, RAG, routing, containers, structured capture, typed nodes,
+capability governance, and evaluation are separate opt-in modules.
 
 ## For contributors
 

package/docs/learning/instructor-guide.md

@@ -10,6 +10,10 @@
 - Increase terminal font size and keep one command per visible line.
 - Prepare a clean start snapshot and a known-good completed snapshot.
 - Rehearse the failure-recovery section, not only the happy path.
+- For L13-L16, prove every optional flag starts disabled and clean up only the
+  disposable evidence or experiment root created by the lesson.
+- Label deterministic evaluation fixtures as framework evidence, never product
+  quality or efficiency evidence.
 
 ## Recommended recording format
 
@@ -58,3 +62,5 @@ A lesson is **Ready** only when:
 - storage and privacy implications are stated;
 - the video script matches the verified lesson;
 - a learner other than the author completed it without hidden instructions.
+- the command surface and lesson assignment agree with the
+  [curriculum coverage map](CURRICULUM-MAP.md).

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.4.0
+**Tested with:** Cairnkeep 2.5.0
 
 ## Outcome
 
@@ -18,22 +18,27 @@ entire transcript into the next prompt is expensive and preserves noise along
 with useful facts.
 
 Cairnkeep stores small, reviewed operational facts and retrieves them when they
-are relevant. It also provides a derived wiki and governed review workflows,
-without replacing source code, tests, issue trackers, or canonical documents.
+are relevant. It also provides a derived wiki and governed review workflows.
+Optional local evidence features can retain redacted session structure,
+artifacts, and deterministic hindsight notes, but they remain distinct from
+reviewed memory and are disabled by default. None of these layers replaces
+source code, tests, issue trackers, or canonical documents.
 
 ## Mental model
 
-Keep four layers distinct:
+Follow information through a trust ladder:
 
 | Layer | Example | Role |
 |---|---|---|
 | Harness history | The current conversation | Temporary working context |
+| Captured evidence (optional) | A redacted tool result or compaction summary | Bounded local evidence, not trusted instruction |
+| Hindsight note (optional) | A repeated failure signature and resolution | Deterministic derived knowledge, not automatically shared |
 | Cairnkeep memory | “Use transactional migrations” | Durable operational fact |
 | Project wiki | A cited architecture summary | Derived, reviewable knowledge |
 | Canonical source | Code, tests, ADR, issue | Authority when layers disagree |
 
-Document RAG is an optional fifth layer for retrieving larger documents. It is
-not required for Cairnkeep memory.
+Document RAG and token-miser context exploration are optional retrieval paths,
+not additional authorities. Neither is required for Cairnkeep memory.
 
 ## Exercise
 
@@ -43,6 +48,7 @@ For each statement, choose the appropriate destination:
 2. “Here is the complete API specification.”
 3. “The current debugging hypothesis is a race in the cache.”
 4. “Never run the production migration from a developer laptop.”
+5. “This synthetic stack trace appeared and was resolved twice.”
 
 Suggested answer:
 
@@ -51,6 +57,8 @@ Suggested answer:
 - 2 stays a canonical document and may optionally be indexed for RAG.
 - 3 remains session context until confirmed.
 - 4 is a durable constraint after it is verified against policy.
+- 5 may become local session evidence and a hindsight note. It becomes reviewed
+  memory only through a separate explicit workflow.
 
 ## Verify
 
@@ -59,6 +67,7 @@ You are ready for L01 if you can answer these questions:
 - Does Cairnkeep replace the repository or its documentation? **No.**
 - Does the default installation discover a remote memory server? **No.**
 - Should every sentence in a session become durable memory? **No.**
+- Does enabling one optional evidence feature enable the others? **No.**
 
 ## Common failures
 
@@ -66,17 +75,20 @@ You are ready for L01 if you can answer these questions:
 |---|---|
 | Memory is another transcript store | Store concise, durable facts rather than complete prompts |
 | RAG and memory are the same | RAG retrieves documents; memory preserves reviewed operational facts |
+| Captured evidence is trusted memory | Evidence and notes remain derived until explicitly reviewed or promoted |
 | Derived knowledge is authoritative | Code, tests, policies, and canonical documents win conflicts |
 
 ## Privacy and trust boundary
 
 The default stdio topology stores memory on the local machine. Remote storage,
-model-backed extraction, embeddings, and document RAG require explicit
-configuration and are taught separately.
+structured capture, note distillation/enrichment, artifacts, evaluation,
+model-backed extraction, embeddings, and document RAG require separate explicit
+configuration and are taught later.
 
 ## Recap
 
 - Memory is selective and durable.
+- Optional evidence and notes are distinct from reviewed memory.
 - Derived knowledge remains subordinate to canonical sources.
 - Optional services are not prerequisites.