@cairnkeep/cli 2.6.0 → 2.8.0

package/docs/learning/PRODUCTION-PLAN.md

@@ -1,153 +0,0 @@
-# Learning Path Production Plan
-
-This plan grows the course in small publishable waves. Each wave produces a
-useful learner outcome on its own and leaves the public material in a coherent
-state.
-
-## Guiding principles
-
-- Demonstrate value before architecture.
-- Keep public lessons provider-neutral and free of private configuration.
-- Teach local storage first; remote storage must always be an explicit choice.
-- Write the canonical lesson before recording the video.
-- 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-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-L17.
-- A release-reviewed feature-to-lesson coverage map.
-
-**Exit gate**
-
-- A new learner can follow L00-L03 on a clean machine or stop safely after the
-  container trial.
-- Every command is current and no optional service is presented as mandatory.
-
-## Wave 1 - Pilot the quickstart
-
-1. Rehearse L00-L03 without recording and log confusing steps.
-2. Run the lessons on one clean Linux environment and one macOS environment.
-3. Record the four short videos from the supplied scripts.
-4. Ask two learners to complete the track without live assistance.
-5. Fix every repeated point of confusion before public promotion.
-
-**Artifacts:** four videos, four blog-ready lessons, one learner feedback form.
-
-**Exit gate:** both pilot learners reach a successful `/remember` and `/recall`
-round trip and can explain where their memory is stored.
-
-## Wave 2 - Daily practitioner value
-
-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.
-
-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.
-
-## Wave 3 - Safe operation
-
-Expand L07-L08 and add a backup/restore lab:
-
-- Draw the local stdio and explicit remote HTTP data flows.
-- Demonstrate `cairn memory path`, export, import, and rollback.
-- Explain identity, project, and global routing without using real credentials.
-- Test the multiple-machine procedure with disposable stores before recording.
-
-**Exit gate:** the learner can predict the storage destination before starting
-a session and can restore a snapshot without losing the pre-existing store.
-
-## Wave 4 - Optional accelerators
-
-Expand L09-L10 as independent modules:
-
-- Optional document RAG, workspace selection, query, and sync.
-- token-miser/FastContext exploration, citations, caching, and failure modes.
-
-Each lesson begins and ends with the reminder that Cairnkeep works without the
-optional component.
-
-**Exit gate:** disabling either integration returns the learner to a healthy
-standalone Cairnkeep workflow.
-
-## 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:
-
-- Rootless containers, persistent volumes, authenticated HTTP, and isolation.
-- Overlay manifests, private package delivery, bootstrap policy, fleet updates,
-  rollback, and release gates.
-
-**Exit gate:** the operator can explain every host mount, network boundary,
-credential source, storage destination, and rollback action.
-
-## Wave 7 - Publication and maintenance
-
-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. 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
-
-For each lesson, follow this loop:
-
-1. **Select:** choose the next lesson from the current wave.
-2. **Discover:** collect real learner questions and one convincing use case.
-3. **Draft:** complete the lesson using the template.
-4. **Verify:** execute every command from a clean starting state.
-5. **Script:** derive the video script from the verified lesson.
-6. **Rehearse:** read it aloud while performing the demo once without recording.
-7. **Record:** capture the short lesson in sections, not one continuous take.
-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 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/instructor-guide.md

@@ -1,66 +0,0 @@
-# Instructor Guide
-
-## Before each lesson
-
-- Confirm the lesson is marked **Ready**, not **Brief**.
-- Run every command against the current Cairnkeep release.
-- Use a disposable repository and synthetic names, URLs, tokens, and data.
-- Hide notifications, shell history, credentials, bookmarks, and unrelated
-  repositories before screen recording.
-- 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
-
-Record each video as independent segments:
-
-1. **Hook:** the concrete problem in 20-40 seconds.
-2. **Outcome:** what the learner will be able to verify.
-3. **Concept:** only the mental model required for the exercise.
-4. **Demo:** commands and observable results.
-5. **Boundary:** storage, privacy, or trust implication.
-6. **Recap:** result and next lesson.
-
-Aim for 8-15 minutes. If a script exceeds 15 minutes, split the lesson rather
-than speaking faster.
-
-## Recording conventions
-
-- Say command intent before typing the command.
-- Pause after important output so it can be read.
-- Never paste a real token, cookie, endpoint, email, or repository name.
-- Describe output rather than claiming every learner will see identical text.
-- Keep mistakes that teach a recovery step; remove unrelated typing mistakes.
-- Refer to lessons by stable ID, for example “L02”, so links survive title edits.
-
-## Pilot feedback
-
-Ask each pilot learner:
-
-1. Where did you first become uncertain?
-2. Which command did you run without understanding its effect?
-3. Where do you believe memory is stored?
-4. What would prevent you from using this in a real project tomorrow?
-5. Which result made the value clear?
-
-Record observations without collecting project content, prompts, credentials,
-or memory values.
-
-## Definition of done
-
-A lesson is **Ready** only when:
-
-- prerequisites and cleanup are explicit;
-- all commands were executed from the documented starting state;
-- verification distinguishes success from partial installation;
-- common failures have actionable recovery steps;
-- 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/templates/video-script-template.md

@@ -1,50 +0,0 @@
-# LXX Video Script - Title
-
-**Target duration:** NN minutes
-**Companion lesson:** link
-
-## Recording setup
-
-- Screen and terminal state.
-- Files or browser tabs prepared in advance.
-- Sensitive information that must be hidden.
-
-## 00:00 - Hook
-
-**Say:** Presenter wording.
-
-**Show:** Exact visual or terminal state.
-
-## 00:30 - Outcome
-
-**Say:** What the learner will prove.
-
-**Show:** Final result briefly, without teaching it yet.
-
-## 01:00 - Mental model
-
-**Say:** Minimum required explanation.
-
-**Show:** Diagram, slide, or command help.
-
-## 02:00 - Demonstration
-
-For every step include:
-
-- **Say:** intent before action;
-- **Do:** command or interaction;
-- **Point out:** the one important result.
-
-## NN:NN - Boundary and recovery
-
-Explain storage/privacy implications and demonstrate one common recovery.
-
-## NN:NN - Recap
-
-Restate the verified outcome and name the next lesson by ID.
-
-## Editing notes
-
-- Chapters and on-screen captions.
-- Sections safe to re-record independently.
-- Links for the description.

package/docs/learning/video-scripts/L00-why-cairnkeep.md

@@ -1,80 +0,0 @@
-# L00 Video Script - Why Cairnkeep?
-
-**Target duration:** 7 minutes
-**Companion lesson:** [L00](../lessons/L00-why-cairnkeep.md)
-
-## Recording setup
-
-- Show only the trust-ladder table from the lesson.
-- Prepare one slide containing the question: “What should survive this session?”
-- No terminal or private project is required.
-
-## 00:00 - Hook
-
-**Say:** “A coding agent can solve a difficult problem today and make the same
-mistake tomorrow. The missing piece is often not more context. It is a small,
-reviewed record of what the project already learned.”
-
-**Show:** The question slide.
-
-## 00:35 - Outcome
-
-**Say:** “In this lesson you will learn where Cairnkeep fits, what it should
-remember, and what must remain in the repository or another canonical system.”
-
-**Show:** The lesson outcome.
-
-## 01:00 - Trust ladder
-
-**Say:** “Follow information through a trust ladder. The current conversation is
-working context. Optional captured evidence and hindsight notes preserve bounded
-local observations, but they are not automatically trusted memory. Cairnkeep
-memory holds concise operational facts. The project wiki is derived, cited
-knowledge. Code, tests, specifications, policies, and issue trackers remain
-canonical.”
-
-**Show:** Reveal one table row at a time.
-
-**Say:** “If these disagree, the canonical source wins. Cairnkeep helps the
-agent find and apply knowledge; it does not redefine truth.”
-
-## 02:40 - Memory versus RAG
-
-**Say:** “Document RAG and codebase exploration answer a different question:
-which source material is relevant right now? Cairnkeep can integrate with those
-retrieval paths, but it does not require them. A decision such as ‘use
-transactional migrations’ is a memory. The complete migration policy remains a
-document.”
-
-**Show:** Memory on the left, document retrieval on the right.
-
-## 03:40 - Classification exercise
-
-**Say:** “Consider four statements. A confirmed API behavior can become memory
-and should still be traceable to code or a specification. A complete API
-specification remains canonical. A debugging hypothesis stays in the session
-until confirmed. A verified operational prohibition is a durable constraint.”
-
-**Show:** The four L00 exercise statements and reveal answers after a pause.
-
-## 05:10 - Boundary
-
-**Say:** “Cairnkeep does not store every sentence from a session. The default
-stdio setup stores memory on this computer. Structured capture, notes,
-artifacts, evaluation, remote storage, model extraction, embeddings, and
-document RAG are separate explicit choices.”
-
-**Show:** “Local by default. Optional means opt-in.”
-
-## 06:10 - Recap
-
-**Say:** “Remember three things: durable memory is selective, evidence is not
-automatically trusted memory, and canonical sources still win. Optional layers
-are not prerequisites. In L01 we will inspect the published container without
-installing the complete workflow.”
-
-## Editing notes
-
-- Chapters: Problem, Trust ladder, Memory vs retrieval, Exercise, Boundary.
-- Link L00 and L01 in the description.
-- Re-record the version-independent slide only if the conceptual model changes.

package/docs/learning/video-scripts/L01-safe-trial.md

@@ -1,78 +0,0 @@
-# L01 Video Script - Try it safely
-
-**Target duration:** 8 minutes
-**Companion lesson:** [L01](../lessons/L01-safe-trial.md)
-
-## Recording setup
-
-- Use a terminal with no registry credentials or unrelated containers visible.
-- Remove any prior `cairnkeep-course-data` volume before recording.
-- Put the complete Podman command in a prepared text file to avoid typing errors.
-
-## 00:00 - Hook
-
-**Say:** “Before installing commands or changing a coding harness, we can inspect
-how the Cairnkeep server is packaged and what it is allowed to persist.”
-
-**Show:** An empty terminal and `podman --version`.
-
-## 00:30 - Outcome
-
-**Say:** “We will run the server as an unprivileged, read-only container, expose
-no network port, and identify the single named volume that would hold memory.”
-
-## 01:00 - Pull the image
-
-**Say:** “I am pinning the course version rather than using `latest`, so this
-recording and the written instructions refer to the same artifact.”
-
-**Do:** Run the L01 `podman pull` command.
-
-**Point out:** The exact image name and version, without dwelling on layer output.
-
-## 02:00 - Explain the isolation flags
-
-**Say:** “The root filesystem is read-only, Linux capabilities are dropped,
-new privileges are disabled, and only a constrained temporary directory plus a
-named data volume are writable. No home directory or project is mounted.”
-
-**Show:** Highlight the command in sections before running it.
-
-## 03:15 - Start and stop
-
-**Do:** Run the direct Podman stdio command.
-
-**Say:** “The quiet process is expected. It is waiting for MCP messages on
-standard input; it is not a web application.”
-
-**Do:** Pause for two seconds, then press `Ctrl-C`.
-
-## 04:30 - Inspect persistence
-
-**Do:** Run `podman volume inspect cairnkeep-course-data`.
-
-**Say:** “The container was disposable. The named volume is separate and would
-survive replacement of the container. Removing that volume would remove its
-stored databases.”
-
-## 05:40 - Boundary and recovery
-
-**Say:** “This test exposed no port and contacted no remote Cairnkeep server.
-If your environment blocks GHCR or Podman, skip this optional trial and use the
-npm installation in L02.”
-
-**Do:** Run `podman volume exists cairnkeep-course-data` and show status `0`.
-
-## 06:50 - Cleanup and recap
-
-**Do:** Run `podman volume rm cairnkeep-course-data`.
-
-**Say:** “Never run that cleanup against a real memory volume. We proved three
-things: the server runs unprivileged, stdio exposes no listener, and persistence
-is explicit. In L02 we install the complete local workflow.”
-
-## Editing notes
-
-- Blur unrelated image and volume names if they appear.
-- Add a warning caption before volume removal.
-- Link the Containers documentation and L02.

package/docs/learning/video-scripts/L02-installation.md

@@ -1,97 +0,0 @@
-# L02 Video Script - Install the local workflow
-
-**Target duration:** 12 minutes
-**Companion lesson:** [L02](../lessons/L02-installation.md)
-
-## Recording setup
-
-- Use a clean user profile or disposable VM with Node.js 22 or newer.
-- Install Claude Code but remove any existing `cairn-memory` registration.
-- Ensure no private MCP servers, provider URLs, or environment variables appear.
-- Prepare a snapshot before installation for a repeatable retake.
-
-## 00:00 - Hook
-
-**Say:** “The most common incomplete installation has a running memory server
-but no Cairnkeep commands or hooks. We will install and verify all three parts
-of the local workflow.”
-
-**Show:** A three-part diagram: CLI, MCP registration, operating layer.
-
-## 00:40 - Outcome
-
-**Say:** “At the end, Claude Code can start the local `cairn-memory` server and
-the managed command assets pass a non-writing drift check.”
-
-## 01:10 - Runtime preflight
-
-**Do:** Run `node --version` and `npm --version`.
-
-**Say:** “Cairnkeep requires Node.js 22 or newer. I verify that before changing
-the machine.”
-
-## 02:00 - Install the CLI
-
-**Do:** Run the pinned npm install and `cairn --version` from L02.
-
-**Say:** “For a course recording I pin the version. Users can follow the current
-release instructions when the lesson is updated.”
-
-## 03:30 - Register MCP
-
-**Say:** “The stable server name is `cairn-memory`. This command tells Claude
-Code to launch a local stdio child process. It does not configure a remote URL.”
-
-**Do:** Run the `claude mcp add` command, followed by `claude mcp get cairn-memory`.
-
-**Point out:** The command is `cairn memory-server`.
-
-## 05:15 - Install the operating layer
-
-**Say:** “MCP tools alone do not install `/remember`, `/recall`, wiki commands,
-review workflows, agents, or hooks. That is the job of `cairn sync`.”
-
-**Do:** Run `cairn sync --apply`.
-
-**Pause:** Allow the learner to see the asset summary.
-
-## 07:00 - Verify without writing
-
-**Do:** Run `cairn sync --check`.
-
-**Say:** “This is the repeatable drift check. A healthy result means the
-operating layer matches the installed distribution. MCP registration plus this
-check distinguishes a complete setup from a partial one.”
-
-## 08:30 - Common failure demonstration
-
-**Say:** “If slash commands are missing, do not reinstall everything blindly.
-First check the MCP registration, then check operating-layer drift, and restart
-the harness after applying assets.”
-
-**Show:** The two verification commands together.
-
-## 09:30 - Optional shell completion
-
-**Do:** Run `source <(cairn completion bash)` and complete `cairn tra`.
-
-**Say:** “Completion is optional convenience. It does not start another server
-or enable any feature.”
-
-## 10:00 - Boundary
-
-**Say:** “This default server is local. We did not configure embeddings,
-document RAG, or remote HTTP memory. Those choices have separate lessons
-because they change data flow.”
-
-## 11:00 - Recap
-
-**Say:** “The machine setup has three pieces: CLI, MCP registration, and the
-operating layer. In L03 we add the fourth piece, a bootstrapped project, and
-prove memory survives a new session.”
-
-## Editing notes
-
-- Chapter markers: Preflight, CLI, MCP, Operating layer, Verify, Boundary.
-- Do not show the general MCP list if it contains unrelated server names.
-- Link L02, the operating guide, and L03.

package/docs/learning/video-scripts/L03-first-project.md

@@ -1,99 +0,0 @@
-# L03 Video Script - Bootstrap the first project
-
-**Target duration:** 13 minutes
-**Companion lesson:** [L03](../lessons/L03-first-project.md)
-
-## Recording setup
-
-- Start from the completed L02 VM snapshot.
-- Confirm `$HOME/cairnkeep-course/first-project` does not exist.
-- Use only the synthetic UTC convention from the lesson.
-- Prepare to stop and restart the harness during the recording.
-
-## 00:00 - Hook
-
-**Say:** “An installation is not proven by files on disk. The useful proof is a
-fact accepted in one session and recalled in a new session.”
-
-## 00:30 - Outcome
-
-**Say:** “We will bootstrap a disposable Git repository, run diagnostics, store
-one synthetic convention, restart Claude Code, and retrieve it again.”
-
-## 01:00 - Create the project
-
-**Do:** Run the directory, `git init`, and README commands from L03.
-
-**Say:** “I use a disposable repository so no course artifact can reach a real
-project.”
-
-## 02:00 - Bootstrap
-
-**Say:** “Bootstrap adds project launchers and derived-knowledge scaffolding. It
-does not reinstall the machine-level MCP server or operating assets.”
-
-**Do:** Run `cairn bootstrap "$PWD"` and copy `.ai/env.example` to `.ai/.env`.
-
-**Point out:** The generated next steps without reading every created filename.
-
-## 03:45 - Diagnose
-
-**Do:** Run `cairn doctor`.
-
-**Say:** “Optional unconfigured integrations may be skipped. A configured but
-unreachable dependency is a failure and should be fixed before relying on it.”
-
-**Point out:** Session capture, notes, compaction, artifacts, typed memory,
-capability governance, and evaluation remain off for the core-memory proof.
-
-## 05:00 - Launch and remember
-
-**Do:** Start `./.ai/start-claude.sh`.
-
-**Say:** “I launch through the project script so every session loads the same
-project environment.”
-
-**Do in Claude:** `/remember Course convention: examples use UTC timestamps.`
-
-**Point out:** The durable key returned by the workflow.
-
-## 07:00 - Recall
-
-**Do in Claude:** `/recall UTC timestamps`
-
-**Say:** “This confirms retrieval inside the first session, but not yet
-persistence across sessions.”
-
-## 08:00 - Persistence proof
-
-**Do:** Exit Claude Code, run the launcher again, and repeat `/recall UTC timestamps`.
-
-**Pause:** Keep the retrieved result visible.
-
-**Say:** “This is the important proof. The second harness process recovered the
-accepted fact from durable local storage.”
-
-## 10:00 - Locate storage
-
-**Do:** Exit the harness and run `cairn memory path`.
-
-**Say:** “The command reports the local store location. Nothing in bootstrap
-silently selected a remote server.”
-
-## 11:00 - Recovery and boundary
-
-**Say:** “If recall fails after restart, compare the launcher and environment,
-check the MCP registration, and verify the storage path. Do not solve routing
-problems by copying database files while the server is running.”
-
-## 12:00 - Recap
-
-**Say:** “We bootstrapped one project, used its launcher, and proved persistence
-across a new session. The quickstart is complete. L04 will teach how to choose
-keys, scopes, search, history, and the memory review gate.”
-
-## Editing notes
-
-- Do not cut away the harness exit/restart; it is the central proof.
-- Add captions for “first session” and “second session”.
-- Link L03 and L04 in the description.