@cairnkeep/cli 2.6.0 → 2.8.0

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.6.0
+**Baseline:** Cairnkeep 2.8.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
@@ -32,8 +32,9 @@ Run setup in that order, then confirm `cairn doctor`, `cairn sync --check`, and
 | 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 |
+| 8 | Validated skill improvement | Repeated resolved hindsight warrants a measured skill change |
 
-Every stage is independently useful. Stages 4-7 are opt-in and are not
+Every stage is independently useful. Stages 4-8 are opt-in and are not
 prerequisites for ordinary memory.
 
 ## Core and derived knowledge
@@ -43,7 +44,7 @@ prerequisites for ordinary memory.
 | 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` |
+| Local code graph | `cairn graph build|query|status|diff|explain|path`; `/graphify` delegates | Default off; optional isolated `graphify` executable; incremental work under `graphify-out/`, published view under `.planning/graphs/` | Ignore both derived locations; check status and source before trusting a result; use `--force` only after intentional deletion; uninstall adapters separately | `course-08-graph` |
 | Repository quality | `/repo-review`, `/security-audit` | On-demand workflow; findings are hypotheses until reproduced | Require file/line evidence and regression tests | `course-03-quality` |
 
 ## Storage and optional topology
@@ -70,13 +71,15 @@ prerequisites for ordinary memory.
 | Typed nodes/import | `CAIRN_TYPED_MEMORY_NODES=1` | Restart MCP server; tool schema changes | Hard-filter search; dry-run, replay-safe import; `cairn doctor --repair` only for derived state | `course-05-evidence` |
 | Capability contract | `CAIRN_CAPABILITY_CONTRACT=1` | MCP changes require restart; operating changes apply next invocation | `cairn capabilities list|status|enable|disable|reset|logging`; digest identifies state only | `course-06-governance` |
 | Evaluation | `CAIRN_EVAL=1` for the coordinator process | No harness chosen by Cairnkeep | `validate` before `run`; inspect report, missingness and evidence scope; dry-run prune/delete | `course-07-evaluation` |
-| Meta-agent loop | Not shipped | Not applicable | Design contract only; never advertise as an available command | `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` |
+| General meta-agent loop | Not shipped | Not applicable | Skill-file lifecycle only; no generic configuration loop or scheduler | `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.
+- Run `cairn sync-pi --check` when the optional Pi capture/graph adapter is installed.
+- Run `cairn sync-kimi --check` when the optional Kimi graph Skill is installed.
 - Use `cairn doctor --repair` only after preserving the affected store and only
   for repairable derived indexes/metadata.
 - Use `cairn uninstall --dry-run` before uninstall; durable memory is retained

package/docs/learning/README.md

@@ -1,8 +1,8 @@
 # Learn Cairnkeep
 
-This learning path teaches Cairnkeep through small, verifiable outcomes. The
-canonical lesson is written once and can be reused as a guide, blog post,
-workshop handout, or video script.
+This public learning path teaches Cairnkeep through small, verifiable outcomes.
+It is the technical source for guides, workshops, and independently reviewed
+publication material.
 
 ## Start here
 
@@ -22,9 +22,9 @@ 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).
+Lessons marked **Ready** include a complete, release-verified exercise. Lessons
+marked **Brief** define public outcomes and acceptance criteria and will be
+expanded only after their labs are executable.
 
 ## Curriculum
 
@@ -48,6 +48,8 @@ expanded according to the [production plan](PRODUCTION-PLAN.md).
 | 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 |
+| 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 |
 
 The [curriculum coverage map](CURRICULUM-MAP.md) records where every public
 feature is introduced, practised, and operated. It also marks design-only work
@@ -62,16 +64,16 @@ Every complete lesson contains:
 3. A hands-on exercise using non-sensitive sample data.
 4. Verification and recovery steps.
 5. A privacy or security boundary.
-6. A presenter-ready video script.
+6. Release compatibility metadata for completed exercises.
 
 The learner should never need optional infrastructure to complete L00-L06.
-Remote memory, RAG, routing, containers, structured capture, typed nodes,
-capability governance, and evaluation are separate opt-in modules.
+Remote memory, RAG, routing, containers, graph indexing, structured capture,
+typed nodes, capability governance, and evaluation are separate opt-in modules.
 
 ## For contributors
 
-Use [the lesson template](templates/lesson-template.md) and
-[the video template](templates/video-script-template.md). The
-[instructor guide](instructor-guide.md) defines rehearsal, recording, and
-publication checks. Commands in finished lessons must be tested against the
-current release before publication.
+Use [the lesson template](templates/lesson-template.md). Commands in finished
+lessons must be tested against the current release before publication.
+Unpublished editorial plans and recording scripts are intentionally maintained
+outside the public product repository; stable video links or transcripts can
+be added here after publication.

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.6.0
+**Tested with:** Cairnkeep 2.8.0
 
 ## Outcome
 
@@ -93,7 +93,3 @@ configuration and are taught later.
 - Optional services are not prerequisites.
 
 Next: [L01 - Try it safely](L01-safe-trial.md).
-
-## Video
-
-Use [the L00 presenter script](../video-scripts/L00-why-cairnkeep.md).

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.6.0
+**Tested with:** Cairnkeep 2.8.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.6.0
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.8.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.6.0 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.8.0 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it
@@ -90,7 +90,3 @@ podman volume rm cairnkeep-course-data
 - Persistence belongs to an explicitly named volume.
 
 Next: [L02 - Install the local workflow](L02-installation.md).
-
-## Video
-
-Use [the L01 presenter script](../video-scripts/L01-safe-trial.md).

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.6.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.8.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.6.0
+   npm install --global @cairnkeep/cli@2.8.0
    cairn --version
    ```
 
@@ -99,14 +99,16 @@ 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,
 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.
+the separate `cairn sync-pi` trajectory and graph-prompt 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).
+Its optional `cairn sync-kimi` Skill adds only the local `/graphify` delegate;
+it does not change memory transport or send graph data to a new destination.
 
 Qwen Code can use the generated `.ai/start-qwen.sh` launcher. Its project
 `.qwen/settings.json` supports environment references for both the remote URL
@@ -135,7 +137,3 @@ Do not delete memory stores as part of a course cleanup.
 - Default stdio memory is local.
 
 Next: [L03 - Bootstrap the first project](L03-first-project.md).
-
-## Video
-
-Use [the L02 presenter script](../video-scripts/L02-installation.md).

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.6.0
+**Tested with:** Cairnkeep 2.8.0
 
 ## Outcome
 
@@ -115,7 +115,3 @@ inspect `.git/info/exclude` to see how contributor mode avoids shared changes.
 - Persistence is proven only after a new session recalls the accepted fact.
 
 Next: [L04 - Memory fundamentals](L04-memory-fundamentals.md).
-
-## Video
-
-Use [the L03 presenter script](../video-scripts/L03-first-project.md).

package/docs/learning/lessons/L04-memory-fundamentals.md

@@ -35,12 +35,6 @@ candidate.
 - No extracted candidate becomes durable without an explicit review action.
 - Enabling typed nodes changes discovery structure, not the authority of a fact.
 
-## Planned video
-
-Open with two contradictory memories, demonstrate search and superseding, then
-finish with the review queue. Target 12-15 minutes. Write the complete script in
-Wave 2 after the lab fixture is executable.
-
 ## Source material
 
 - [Operating guide](../../operating.md#the-workflow)

package/docs/learning/lessons/L05-daily-workflow.md

@@ -35,11 +35,6 @@ queue before exiting.
 - The learner can describe what to do at session start, before editing, and at
   session end.
 
-## Planned video
-
-Follow one small feature from session start to reviewed handoff. Target 15
-minutes and split wiki maintenance into a second video if rehearsal runs long.
-
 ## Source material
 
 - [Operating guide](../../operating.md#the-workflow)

package/docs/learning/lessons/L06-repository-quality.md

@@ -33,12 +33,6 @@ solution branch.
 - No scan reaches outside the disposable repository or its local processes.
 - The lab passes after remediation and fails in its tagged starter state.
 
-## Planned video
-
-This is the flagship value demonstration. Show one serious synthetic defect
-from discovery through validation and fix. Target 15 minutes; publish the full
-45-minute exercise as a workshop.
-
 ## Source material
 
 - [Operating guide](../../operating.md#the-workflow)

package/docs/learning/lessons/L07-privacy-and-storage.md

@@ -34,11 +34,6 @@ names, and prove that no remote destination was discovered.
 - The learner can stop when an effective destination is ambiguous.
 - Independent feature flags are not treated as one blanket consent switch.
 
-## Planned video
-
-Use two simple diagrams and one terminal preflight. Target 10 minutes. Do not
-demonstrate real endpoints or credentials.
-
 ## Source material
 
 - [Privacy and data flow](../../privacy-and-data-flow.md)

package/docs/learning/lessons/L08-multiple-machines.md

@@ -31,11 +31,6 @@ the pre-import backup.
 - The learner verifies counts and exact synthetic values on both sides.
 - No remote service is introduced merely to complete the migration lab.
 
-## Planned video
-
-Record the backup, migration, verification, and rollback without cuts that hide
-state transitions. Target 12 minutes.
-
 ## Source material
 
 - [Storage and deployment](../../storage.md#inspecting-and-moving-memory)

package/docs/learning/lessons/L09-domain-knowledge.md

@@ -32,11 +32,6 @@ verify the new answer. Then unset the integration and prove memory still works.
 - Updated content replaces stale retrieval results.
 - Disabling RAG leaves `/remember` and `/recall` healthy.
 
-## Planned video
-
-Lead with “optional, not required”, show query then sync, and finish by disabling
-the integration. Target 12 minutes.
-
 ## Source material
 
 - [Domain knowledge](../../domain-knowledge.md)

package/docs/learning/lessons/L10-context-exploration.md

@@ -33,11 +33,6 @@ invalidation. Disable the binary and verify standalone Cairnkeep remains usable.
 - The learner distinguishes exploration output from durable memory.
 - An unavailable explorer fails locally without breaking memory operations.
 
-## Planned video
-
-Compare a broad manual search with one cited exploration result. Target 10
-minutes and keep routing as a separate optional chapter.
-
 ## Source material
 
 - [Operating guide](../../operating.md#exploration-cache-context_explore-on-by-default)

package/docs/learning/lessons/L11-containers.md

@@ -32,11 +32,6 @@ only the course resources.
   volume is deliberately removed.
 - The learner can enumerate every mount and network boundary.
 
-## Planned video
-
-Use a diagram first, then replace a running container while retaining its
-volume. Target 15 minutes.
-
 ## Source material
 
 - [Containers](../../containers.md)

package/docs/learning/lessons/L12-managed-overlays.md

@@ -33,12 +33,6 @@ upgrades the pin, verifies fleet status, and rolls one project back.
 - Effective storage and service destinations are explainable before launch.
 - Upgrade and rollback preserve the disposable memory store.
 
-## Planned video
-
-Show the same project under public core and a generic managed overlay, then
-explain the small delta. Target 15 minutes; keep registry administration in the
-written operator lab.
-
 ## Source material
 
 - [Building a private overlay](../../building-an-overlay.md)

package/docs/learning/lessons/L13-session-evidence.md

@@ -57,12 +57,6 @@ cairn artifact list --json
   memory by purpose, store, lifecycle, and trust level.
 - Cleanup targets only the disposable course evidence.
 
-## Planned video
-
-Draw the evidence lifecycle, capture one synthetic session, inspect the redacted
-record, and find the resulting failure note. Target 14 minutes. Treat compaction
-and Pi as short boundary chapters rather than requiring three harness demos.
-
 ## Source material
 
 - [Operating guide: structured trajectories](../../operating.md#structured-session-trajectories-opt-in)

package/docs/learning/lessons/L14-typed-memory.md

@@ -38,12 +38,6 @@ import.
 - Imported values never appear in command diagnostics or course screenshots.
 - The learner does not present a logical note address as a host path.
 
-## Planned video
-
-Use a small type-and-tag diagram, then demonstrate filtered discovery and the
-dry-run/replay sequence. Target 12 minutes. Keep the full import limits in the
-written lesson rather than narrating a table of numbers.
-
 ## Source material
 
 - [Operating guide: typed memory nodes](../../operating.md#typed-memory-nodes-and-note-address-spaces-opt-in)

package/docs/learning/lessons/L15-capability-governance.md

@@ -43,12 +43,6 @@ CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities logging enable
 - No callback record contains prompts, tool arguments, results, or memory values.
 - Disabling an optional capability does not break standalone memory.
 
-## Planned video
-
-Show precedence as three stacked layers, then perform one disable/reset cycle.
-Target 11 minutes. Use JSON status for evidence and avoid presenting a digest as
-a security signature or performance result.
-
 ## Source material
 
 - [Operating guide: managed capability contract](../../operating.md#managed-capability-contract-opt-in)

package/docs/learning/lessons/L16-evaluation.md

@@ -52,13 +52,6 @@ after the lab is rehearsed from the packaged CLI rather than a source clone.
   without claiming causality, significance, or product improvement.
 - Course cleanup is limited to its temporary contained experiment root.
 
-## Planned video
-
-Start with the claim boundary, validate before running, inspect one two-pass
-report, and close by marking the fixture `offline-framework`. Target 16 minutes.
-Publish ablation as a second short video if the complete schedule obscures the
-measurement concepts.
-
 ## Source material
 
 - [Operating guide: evaluation harness](../../operating.md#evaluation-harness-opt-in)

package/docs/learning/lessons/L17-agent-boundary.md

@@ -6,23 +6,25 @@
 
 ## Outcome
 
-Separate Cairnkeep's shipped evidence and evaluation substrates from the
-design-only bounded meta-agent proposal, and identify which authority always
-remains with the operator and external harness.
+Separate Cairnkeep's shipped evidence, evaluation, and narrow skill-file
+lifecycle from the design-only general meta-agent proposal, and identify which
+authority always remains with the operator and external harness.
 
 ## Planned lesson
 
 - Current facts: typed capability state, local evidence, immutable evaluation
   inputs, isolated schedules, independent verification, and canonical reports.
-- Design only: natural-language form compilation, candidate generation,
-  candidate injection, comparison, proposal bundles, patch application, and
-  rollback ledgers.
+- Shipped in 2.8.0: reviewed hindsight candidates, bounded edits to one existing
+  `SKILL.md`, isolated baseline/candidate comparison, held-out confirmation,
+  exact-digest application, and rollback ledgers.
+- Design only: general natural-language configuration compilation, arbitrary
+  target types, autonomous scheduling, and an owner inference loop.
 - Cairnkeep coordinates evidence; it does not own a harness inference loop.
 - Natural language is untrusted proposal data, not executable authorization.
 - Separate human gates for form, evaluation, application, confirmation, and
   rollback.
-- Why no CLI command, schema, runtime default, or quality claim ships for the
-  proposed meta-agent loop.
+- Why the shipped `cairn skill` command does not authorize or imply the broader
+  proposed meta-agent loop or a product quality claim.
 
 ## Hands-on lab
 
@@ -36,6 +38,8 @@ be required before any future implementation could act.
 
 - No learner attempts to invoke a meta-agent command or treats an illustrative
   block as a supported schema.
+- The learner can distinguish supported `cairn skill` operations from the
+  broader design-only proposal.
 - Every inference execution remains owned by an operator-configured adapter.
 - A capability digest is not treated as approval, identity proof, or evidence
   of improvement.
@@ -43,12 +47,6 @@ be required before any future implementation could act.
 - The learner can name at least one explicit future prerequisite and one
   unconditional human stop point.
 
-## Planned video
-
-Use one ownership diagram and one fictional proposal. Target 9 minutes. Put a
-persistent `DESIGN ONLY` label on every future component and end on the exact
-current-versus-future boundary.
-
 ## Source material
 
 - [Meta-agent design contract](../../design/meta-agent.md)

package/docs/learning/lessons/L18-local-code-graph.md

@@ -0,0 +1,97 @@
+# L18 - Local code graph
+
+**Status:** Brief
+**Track:** Practitioner
+**Planned time:** 35 minutes
+**Introduced in:** Cairnkeep 2.7.0
+
+## Outcome
+
+Build and inspect an optional local structural graph without confusing derived
+graph data with canonical source code or granting an external tool ownership of
+the Cairnkeep operating layer.
+
+## Planned lesson
+
+- When a structural graph answers a code-navigation question better than
+  durable memory, the wiki, or broad text search.
+- Why the graph capability is disabled unless the managed capability contract
+  enables `graph` or the compatibility setting `graphify.enabled` is true.
+- How to install only the isolated `graphify` executable with `uv tool install
+  graphifyy` or `pipx install graphifyy`. Do not run `graphify install` because
+  Cairnkeep owns the harness commands, policies, and lifecycle.
+- How `cairn graph build`, `cairn graph status`, `cairn graph query`,
+  `cairn graph explain`, `cairn graph path`, and `cairn graph diff` share one
+  portable owner across harnesses and the shell.
+- Why builds index local code only, use a reduced subprocess environment, avoid
+  provider credentials and semantic document extraction, and publish validated
+  artifacts atomically under `.planning/graphs/` while Graphify maintains its
+  separate incremental work directory under `graphify-out/`.
+- How the previous successful graph snapshot supports `diff`, and why `--force`
+  is appropriate only when an intentional code deletion reduces the graph.
+- Why exact symbols and narrow terms are more reliable than broad prose, and
+  why every graph result must be checked against canonical source files.
+- How Claude Code and OpenCode receive managed `/graphify` wrappers while
+  `cairn sync-kimi --apply` and `cairn sync-pi --apply` install thin delegates
+  that call only `cairn graph`.
+
+## Hands-on lab
+
+Use the synthetic course repository at checkpoint `course-08-graph` in a
+disposable clone. Confirm that a disabled graph fails before Graphify or graph
+artifacts are accessed. Install only the isolated executable, enable the graph
+through one documented capability path, and then run:
+
+```bash
+cairn graph build
+cairn graph status
+cairn graph query addItem
+cairn graph explain addItem
+cairn graph path addItem writeLedger
+```
+
+Make one reversible change to the synthetic ledger, rebuild, and inspect
+`cairn graph diff`. Revert the source change, rebuild again, and verify the
+status. Inspect `.planning/graphs/` and `graphify-out/` without adding either
+derived location to Git.
+
+## Acceptance criteria
+
+- The disabled-path check creates or changes no graph artifact.
+- `status` identifies whether the published graph is present and current.
+- `query`, `explain`, and `path` return structural discovery evidence that the
+  learner verifies against `src/trail-ledger.mjs`.
+- A second successful build produces a snapshot-backed diff.
+- The learner can explain why `--force` is not a generic retry flag.
+- The repository contains no Graphify-owned harness assets and neither
+  `graphify-out/` nor a published graph artifact is staged for commit.
+- The learner can distinguish graph storage and subprocess data flow from
+  Cairnkeep memory storage and optional embedding traffic.
+
+## Common failures
+
+- If `graphify` is missing, install the isolated CLI and verify it is on
+  `PATH`; do not run its harness installer.
+- If the capability is disabled, enable it through the managed contract or the
+  compatibility setting rather than bypassing the owner.
+- If no previous snapshot exists, make a successful build after a real code
+  change before requesting `diff`.
+- If a path or explanation is empty, retry with exact symbol names and verify
+  the source directly instead of treating a broad query as proof.
+
+## Privacy and trust boundary
+
+The managed build passes the repository path to a local Graphify subprocess and
+publishes a validated view locally. Its reduced environment excludes provider
+credentials, and the managed workflow does not perform semantic document
+extraction. Graphify's incremental `graphify-out/` workspace and Cairnkeep's
+published `.planning/graphs/` view can both contain sensitive structural data.
+Keep both local by default, review ignore rules, and never present the graph as
+canonical evidence.
+
+## Source material
+
+- [Operating guide](../../operating.md#optional-graphify-workflow)
+- [Harness compatibility](../../harness-compatibility.md)
+- [Privacy and data flow](../../privacy-and-data-flow.md)
+- [L15 - Capability governance](L15-capability-governance.md)

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

@@ -0,0 +1,87 @@
+# L19 - Validated skill improvement
+
+**Status:** Brief
+**Track:** Evidence and Evaluation
+**Planned time:** 50 minutes
+**Introduced in:** Cairnkeep 2.8.0
+
+## Outcome
+
+Turn repeated failure and demonstrated resolution evidence into one reviewed
+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
+
+- Why harvest requires failures from at least two sessions and at least one
+  recorded resolution.
+- How `harvest`, `show`, and `review --approve` keep evidence local until the
+  learner consents to proposal-adapter egress.
+- How the strict proposal adapter receives a bounded request, a private process
+  environment, and an edit budget for one existing `SKILL.md`.
+- Why proposal generation and evaluation never modify the live target.
+- How separate committed sets with at least two disjoint task IDs and
+  definitions each, one immutable source revision, fresh Git worktrees, exact
+  adapter digests, and an independent verifier protect the gate.
+- Why improvements count distinct tasks, any regressed task rejects the
+  candidate, and small passing fixtures are not universal quality proof.
+- How full proposal-digest confirmation, backup-first atomic replacement, and
+  concurrent-edit-safe rollback limit application authority.
+
+## 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:
+
+```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
+
+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 \
+  --confirm FULL_PROPOSAL_DIGEST --json
+cairn skill rollback --application APPLICATION_ID --confirm --json
+```
+
+The lesson remains a Brief until that checkpoint is public and every command is
+rehearsed against the release package.
+
+## Acceptance criteria
+
+- No candidate exists for repeated failure without resolution evidence.
+- Proposal execution cannot inherit unapproved credentials or isolation-owned
+  environment variables.
+- The live `SKILL.md` is byte-identical before and after propose/evaluate.
+- Overlapping task IDs, changed adapters, unknown verifier results, and any
+  regression fail closed.
+- Apply rejects a wrong digest or changed target.
+- Rollback restores the original bytes and refuses to overwrite a later edit.
+- The learner can explain why an eligible small task set supports one local
+  decision but not a universal performance claim.
+
+## Privacy and trust boundary
+
+Hindsight excerpts and skill content remain local until candidate approval.
+Approval permits those exact fields to enter the explicitly configured proposal
+adapter. Evaluation adapters receive isolated worktrees with baseline or
+candidate skill bytes, not the hindsight evidence. Candidate, proposal,
+evaluation, application, backup, and report artifacts remain sensitive local
+project state under `.agentfs/`.
+
+## Source material
+
+- [Validated skill improvement](../../skill-improvement.md)
+- [Evaluation and ablation](L16-evaluation.md)
+- [The agent boundary](L17-agent-boundary.md)
+- [Storage](../../storage.md#validated-skill-storage)
+- [Privacy and data flow](../../privacy-and-data-flow.md#validated-skill-improvement-flow)

package/docs/learning/templates/lesson-template.md

@@ -58,7 +58,3 @@ Offer one bounded extension that is not required for the next lesson.
 ## Recap
 
 List three facts and link the next lesson.
-
-## Video
-
-Link to `../video-scripts/LXX-title.md` only after the script is verified.