@cairnkeep/cli 2.2.0 → 2.3.0

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

@@ -0,0 +1,116 @@
+# L03 - Bootstrap the first project
+
+**Status:** Ready
+**Track:** Quickstart
+**Time:** 25 minutes
+**Tested with:** Cairnkeep 2.3.0
+
+## Outcome
+
+You can bootstrap a disposable project, verify its wiring, store one accepted
+fact, and recall it from a new harness session.
+
+## Prerequisites
+
+- Completed [L02](L02-installation.md).
+- Git and a supported harness.
+- A disposable directory that contains no real project or confidential data.
+
+## Exercise
+
+1. Create a disposable repository:
+
+   ```bash
+   mkdir -p "$HOME/cairnkeep-course/first-project"
+   cd "$HOME/cairnkeep-course/first-project"
+   git init
+   printf '# Cairnkeep course project\n' > README.md
+   ```
+
+2. Bootstrap the project:
+
+   ```bash
+   cairn bootstrap "$PWD"
+   cp .ai/env.example .ai/.env
+   ```
+
+3. Keep optional endpoint and model values unset for this local exercise. Run
+   diagnostics:
+
+   ```bash
+   cairn doctor
+   ```
+
+4. Launch Claude Code through the generated project launcher:
+
+   ```bash
+   ./.ai/start-claude.sh
+   ```
+
+5. In the harness, store a deliberately synthetic convention:
+
+   ```text
+   /remember Course convention: examples use UTC timestamps.
+   ```
+
+6. Retrieve it:
+
+   ```text
+   /recall UTC timestamps
+   ```
+
+7. Exit the harness, start it again with the same launcher, and repeat the
+   recall. This second session is the persistence proof.
+
+## Verify
+
+The lesson is complete only if:
+
+- `cairn doctor` reports no configured dependency failures;
+- `/remember` confirms a durable key;
+- `/recall` finds the fact after the first session has exited;
+- `cairn memory path` points to local storage on this machine.
+
+## Common failures
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| Launcher is missing | A different directory was bootstrapped | Run `pwd`, then bootstrap that exact path |
+| `.ai/.env` is missing | Only the example is generated | Copy `.ai/env.example` to `.ai/.env` |
+| `cairn-memory` is unavailable | L02 MCP registration is absent or stale | Run `claude mcp get cairn-memory`, repair it, then restart Claude Code |
+| Slash commands are unknown | Operating assets were not loaded | Run `cairn sync --check`, apply if needed, then restart the harness |
+| Recall works only in the first session | Sessions used different storage routing | Compare launchers and environment, then inspect `cairn memory path` |
+
+## Privacy and trust boundary
+
+Use synthetic memory in the course. The local stdio server writes to local
+AgentFS/SQLite storage. Project wiki and planning files are derived artifacts;
+the repository remains canonical.
+
+## Clean up
+
+Exit the harness before removing the disposable project:
+
+```bash
+rm -rf "$HOME/cairnkeep-course/first-project"
+```
+
+This removes project scaffolding but not the global memory store. Remove the
+synthetic memory through the normal memory review/delete workflow if required.
+
+## Optional challenge
+
+Repeat bootstrap with `--untracked` in another disposable Git repository, then
+inspect `.git/info/exclude` to see how contributor mode avoids shared changes.
+
+## Recap
+
+- Bootstrap is project-specific and follows machine setup.
+- The generated launcher establishes a repeatable project environment.
+- 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

@@ -0,0 +1,44 @@
+# L04 - Memory fundamentals
+
+**Status:** Brief
+**Track:** Practitioner
+**Planned time:** 35 minutes
+
+## Outcome
+
+Choose an appropriate scope and key, search by meaning, inspect history, and
+review extracted candidates before they become durable memory.
+
+## Planned lesson
+
+- Identity, project, and global scopes.
+- Key families: `decisions/`, `pitfalls/`, `patterns/`, `bugs/`,
+  `constraints/`, and `conventions/`.
+- Exact read versus semantic search and substring fallback.
+- Superseding a fact without losing history.
+- Session-end candidate extraction and `/memory-review` as the acceptance gate.
+- Deleting synthetic course memory safely.
+
+## Hands-on lab
+
+Store three synthetic facts in different categories, retrieve them by an
+imprecise query, supersede one, inspect its history, and reject one staged
+candidate.
+
+## Acceptance criteria
+
+- The learner can justify the scope and category for each fact.
+- Search finds a fact without requiring its exact key.
+- Superseding preserves the prior value in history.
+- No extracted candidate becomes durable without an explicit review action.
+
+## 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)
+- [Storage and deployment](../../storage.md)

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

@@ -0,0 +1,43 @@
+# L05 - The daily workflow
+
+**Status:** Brief
+**Track:** Practitioner
+**Planned time:** 40 minutes
+
+## Outcome
+
+Use memory, the cited wiki, alignment artifacts, and automatic hooks without
+confusing derived knowledge with canonical project sources.
+
+## Planned lesson
+
+- SessionStart recall, pre-edit recall, and SessionEnd candidate staging.
+- `/wiki-ingest`, `/wiki-query`, and `/wiki-lint`.
+- Sparse, citation-heavy wiki pages rather than copied documentation.
+- Alignment gaps, contradictions, and project planning artifacts.
+- `/memory-sync` for configured git-provider state.
+- A start-of-task and end-of-task checklist.
+
+## Hands-on lab
+
+Ingest one synthetic ADR, query it with citations, change the canonical ADR,
+observe staleness, refresh the derived page, and review the session candidate
+queue before exiting.
+
+## Acceptance criteria
+
+- Every derived claim links to a canonical source.
+- A stale or contradictory page is detected rather than silently trusted.
+- Automatic hooks are observable and do not bypass human memory review.
+- 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)
+- [Git provider configuration](../../git-providers.md)

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

@@ -0,0 +1,45 @@
+# L06 - Repository review and security
+
+**Status:** Brief
+**Track:** Practitioner
+**Planned time:** 45 minutes
+
+## Outcome
+
+Run `/repo-review` and `/security-audit` against a bounded target, validate
+findings, and keep generated reports separate from automatic code changes.
+
+## Planned lesson
+
+- When to use repository review versus a security audit.
+- Target selection, repository boundaries, and safe local-only policy.
+- Investigator and validator roles.
+- Severity, evidence, reproduction, false positives, and remediation ordering.
+- Reviewing `REVIEW.md` and `.planning/security/` before acting.
+- Why a report is not permission to modify unrelated code.
+
+## Hands-on lab
+
+Use a deliberately vulnerable toy service containing a correctness defect, an
+authorization defect, and one tempting false positive. Run both workflows,
+reproduce valid findings, reject the false positive, and apply fixes on a
+solution branch.
+
+## Acceptance criteria
+
+- The learner finds both real defects and does not report the planted false
+  positive as confirmed.
+- Every accepted finding contains evidence and a reproduction path.
+- 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)
+- Course-labs repository to be created in Wave 2

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

@@ -0,0 +1,42 @@
+# L07 - Privacy and storage
+
+**Status:** Brief
+**Track:** Practitioner
+**Planned time:** 30 minutes
+
+## Outcome
+
+Predict where memory, project artifacts, credentials, and optional model data
+will go before starting a session.
+
+## Planned lesson
+
+- The placement rule: the server process owns the store it opens.
+- Local stdio versus explicitly configured remote HTTP.
+- AgentFS/SQLite data at rest and project-derived artifacts.
+- Credential boundaries and environment-variable precedence.
+- Embedding/extraction endpoints and what content they receive.
+- `cairn memory path` and a preflight data-flow checklist.
+
+## Hands-on lab
+
+Draw the data flow for a default local setup and for a disposable loopback HTTP
+setup. Verify the local store path, inspect only file permissions and database
+names, and prove that no remote destination was discovered.
+
+## Acceptance criteria
+
+- The learner predicts the correct storage host for both topologies.
+- Secrets are never printed, committed, or included in screenshots.
+- Optional model and RAG flows are identified separately from memory storage.
+- The learner can stop when an effective destination is ambiguous.
+
+## 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)
+- [Storage and deployment](../../storage.md)

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

@@ -0,0 +1,41 @@
+# L08 - Multiple machines
+
+**Status:** Brief
+**Track:** Practitioner
+**Planned time:** 40 minutes
+
+## Outcome
+
+Choose between independent local stores, export/import migration, and a trusted
+remote service, then execute a backup-first migration without data loss.
+
+## Planned lesson
+
+- Independent local memory versus intentional centralization.
+- WAL-safe `cairn memory export` and backup-first import.
+- Trusted-client automation with private configuration.
+- Authenticated HTTP routing and one-server/one-trust-domain limitations.
+- Migration ordering, rollback, and old-client compatibility.
+- Verifying source and destination before decommissioning anything.
+
+## Hands-on lab
+
+Create a disposable store, write two synthetic facts, export it, import into a
+second isolated base directory, verify both facts, and demonstrate rollback to
+the pre-import backup.
+
+## Acceptance criteria
+
+- Source data remains intact throughout the exercise.
+- The destination is backed up automatically before import.
+- 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

@@ -0,0 +1,42 @@
+# L09 - Domain knowledge with RAG
+
+**Status:** Brief
+**Track:** Operator
+**Planned time:** 35 minutes
+
+## Outcome
+
+Connect an optional document-RAG workspace, query it, and disable it again
+without affecting core Cairnkeep memory.
+
+## Planned lesson
+
+- Memory versus document RAG responsibilities.
+- Workspace selection and project configuration.
+- Query-only setup before document synchronization.
+- Incremental, full, and replacement synchronization boundaries.
+- Endpoint, credential, and document-selection safety.
+- Diagnosing an unavailable RAG service with `cairn doctor`.
+
+## Hands-on lab
+
+Index a synthetic three-document corpus into a disposable workspace, ask a
+question requiring citations to two documents, update one document, resync, and
+verify the new answer. Then unset the integration and prove memory still works.
+
+## Acceptance criteria
+
+- Only allowlisted synthetic documents are uploaded.
+- The learner can identify the selected workspace and endpoint without printing
+  its credential.
+- 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

@@ -0,0 +1,42 @@
+# L10 - Faster context exploration
+
+**Status:** Brief
+**Track:** Operator
+**Planned time:** 30 minutes
+
+## Outcome
+
+Use optional token-miser/FastContext exploration with compact citations and
+understand caching, routing, and fallback behavior.
+
+## Planned lesson
+
+- `context_explore` as a thin delegate rather than a second memory store.
+- Repository root, query, citations, and cache keys.
+- Cross-referencing citations with memory and the wiki.
+- Optional pre-task invocation and its privacy implication.
+- `route_check` health versus model-selection policy.
+- Failure behavior when the optional subprocess is absent.
+
+## Hands-on lab
+
+Explore a synthetic repository, verify every returned path and line range,
+repeat the query to observe caching, modify the repository, and confirm cache
+invalidation. Disable the binary and verify standalone Cairnkeep remains usable.
+
+## Acceptance criteria
+
+- Every reported citation resolves to current repository content.
+- Dirty-state or HEAD changes prevent stale cache reuse.
+- 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)
+- [token-miser](https://github.com/cairnkeep/token-miser)

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

@@ -0,0 +1,42 @@
+# L11 - Containers and isolation
+
+**Status:** Brief
+**Track:** Operator
+**Planned time:** 40 minutes
+
+## Outcome
+
+Select and operate local stdio, authenticated HTTP, persistent service, or
+isolated workspace container modes while preserving data deliberately.
+
+## Planned lesson
+
+- Minimal server image versus workspace base image.
+- Rootless execution, read-only filesystems, volumes, and secret mounts.
+- Loopback HTTP, TLS/rebinding boundaries, and trust domains.
+- Podman Compose and Quadlet persistence.
+- Sandbox-copy versus shared-host workspace modes.
+- Backup and rollback before image replacement.
+
+## Hands-on lab
+
+Start a loopback authenticated server with a disposable token file and volume,
+probe health and memory persistence across container replacement, then remove
+only the course resources.
+
+## Acceptance criteria
+
+- No credential appears in the image, command line, or repository.
+- The service binds only to the documented interface.
+- Memory survives container replacement and disappears only when the course
+  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

@@ -0,0 +1,43 @@
+# L12 - Managed overlays
+
+**Status:** Brief
+**Track:** Operator
+**Planned time:** 45 minutes
+
+## Outcome
+
+Design a private managed distribution that pins the public core, injects policy
+through supported seams, delivers no secrets, and upgrades fleets safely.
+
+## Planned lesson
+
+- Why an overlay is a distribution, not a fork of core behavior.
+- Manifest, core pin, launcher seams, and project profile lock.
+- Private registry and derived container image options.
+- Machine-private configuration versus distributable defaults.
+- Bootstrap, diagnostics, fleet status/update, release gates, and rollback.
+- Compatibility guarantees for existing clients and stored memory.
+
+## Hands-on lab
+
+Build a generic example overlay that adds a harmless pre-launch environment
+marker, packages it to a local registry, bootstraps two disposable projects,
+upgrades the pin, verifies fleet status, and rolls one project back.
+
+## Acceptance criteria
+
+- The public core remains provider-neutral and unmodified.
+- The package and image contain no credential or machine-private configuration.
+- 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)
+- [Managed distributions](../../overlay-distributions.md)

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

@@ -0,0 +1,61 @@
+# LXX - Lesson title
+
+**Status:** Draft
+**Track:** Quickstart | Practitioner | Operator
+**Time:** NN minutes
+**Tested with:** Cairnkeep X.Y.Z
+
+## Outcome
+
+State one observable capability the learner will have at the end.
+
+## Why this matters
+
+Describe the practical problem in no more than three paragraphs.
+
+## Prerequisites
+
+- Required prior lesson.
+- Required software and supported versions.
+- Starting repository and state.
+
+## Mental model
+
+Explain only the concepts required for this exercise.
+
+## Exercise
+
+Number each action. Put commands in copyable code blocks and explain the effect
+before the command.
+
+## Verify
+
+Provide a command or observation that distinguishes complete, partial, and
+failed setup.
+
+## Common failures
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| Example | Explain without guessing | Exact safe recovery |
+
+## Privacy and trust boundary
+
+State where data and credentials go, what leaves the machine, and what remains
+derived rather than canonical.
+
+## Clean up
+
+Provide reversible cleanup for every resource created by the lesson.
+
+## Optional challenge
+
+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.

package/docs/learning/templates/video-script-template.md

@@ -0,0 +1,50 @@
+# 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/tracks/operator.md

@@ -0,0 +1,14 @@
+# Operator Track
+
+**Audience:** advanced users and platform maintainers
+**Prerequisite:** Practitioner track
+**Total time:** about 3 hours
+
+1. [L09 - Domain knowledge with RAG](../lessons/L09-domain-knowledge.md)
+2. [L10 - Faster context exploration](../lessons/L10-context-exploration.md)
+3. [L11 - Containers and isolation](../lessons/L11-containers.md)
+4. [L12 - Managed overlays](../lessons/L12-managed-overlays.md)
+
+All modules are optional. The track is complete when the operator can add and
+remove each integration without breaking the standalone local workflow and can
+explain its storage, network, credential, and rollback boundaries.

package/docs/learning/tracks/practitioner.md

@@ -0,0 +1,15 @@
+# Practitioner Track
+
+**Audience:** developers adopting Cairnkeep in daily work
+**Prerequisite:** Quickstart track
+**Total time:** about 3.5 hours
+
+1. [L04 - Memory fundamentals](../lessons/L04-memory-fundamentals.md)
+2. [L05 - The daily workflow](../lessons/L05-daily-workflow.md)
+3. [L06 - Repository review and security](../lessons/L06-repository-quality.md)
+4. [L07 - Privacy and storage](../lessons/L07-privacy-and-storage.md)
+5. [L08 - Multiple machines](../lessons/L08-multiple-machines.md)
+
+The track is complete when the learner can decide what should become memory,
+review derived knowledge, run governed repository checks, locate the store, and
+perform a reversible backup or migration.

package/docs/learning/tracks/quickstart.md

@@ -0,0 +1,14 @@
+# Quickstart Track
+
+**Audience:** developers evaluating Cairnkeep
+**Total time:** about 75 minutes
+**Infrastructure:** local machine; Podman is optional
+
+1. [L00 - Why Cairnkeep?](../lessons/L00-why-cairnkeep.md)
+2. [L01 - Try it safely](../lessons/L01-safe-trial.md)
+3. [L02 - Install the local workflow](../lessons/L02-installation.md)
+4. [L03 - Bootstrap the first project](../lessons/L03-first-project.md)
+
+The track is complete when a learner can start a new harness session, retrieve
+a previously accepted fact, and explain that default stdio memory is stored on
+the local machine rather than a discovered remote service.