@cairnkeep/cli 2.3.1 → 2.5.0

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.3.1
+**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.
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.3.1
+**Tested with:** Cairnkeep 2.5.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.3.1
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.5.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.3.1 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.5.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.3.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.5.0 and Node.js 22 or newer
 
 ## Outcome
 
@@ -13,8 +13,9 @@ layer, and distinguish a complete installation from a partial one.
 ## Prerequisites
 
 - Node.js 22 or newer and npm.
-- Claude Code installed for the commands below. OpenCode users should follow
-  the equivalent setup in [the operating guide](../../operating.md).
+- Claude Code installed for the commands below. OpenCode and Kimi Code users
+  should follow the equivalent setup in
+  [the operating guide](../../operating.md).
 - Permission to install an npm package globally for your user.
 
 ## Mental model
@@ -40,7 +41,7 @@ machine-level steps.
 2. Install Cairnkeep:
 
    ```bash
-   npm install --global @cairnkeep/cli@2.3.1
+   npm install --global @cairnkeep/cli@2.5.0
    cairn --version
    ```
 
@@ -62,6 +63,15 @@ machine-level steps.
    cairn sync --check
    ```
 
+6. Optionally enable completion in the current Bash shell:
+
+   ```bash
+   source <(cairn completion bash)
+   ```
+
+   Use `cairn completion zsh` or `cairn completion fish` for those shells.
+   Completion is a convenience and is not another runtime component.
+
 ## Verify
 
 Run both checks:
@@ -88,7 +98,15 @@ installation.
 
 This registration starts `cairn memory-server` locally as a stdio child. It
 does not discover a server, send memory to a remote host, configure embeddings,
-or enable an optional document-RAG integration.
+enable session capture, or enable an optional document-RAG integration. Pi uses
+the separate `cairn sync-pi` trajectory adapter and still needs a user-selected
+bridge if Pi should expose MCP memory tools.
+
+Kimi Code can use the same memory server through its generated
+`.ai/start-kimi.sh` launcher, but its HTTP MCP configuration requires a literal
+URL rather than `${CAIRN_MEMORY_REMOTE_URL}`. Keep the resolved URL in a private
+`.kimi-code/mcp.json` and keep the bearer token in the environment. See
+[Harness compatibility](../../harness-compatibility.md#kimi-code).
 
 ## Clean up if you stop the evaluation