@cairnkeep/cli 2.2.1 → 2.3.1

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable user-facing changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [2.3.1] - 2026-07-25
+
+### Fixed
+
+- Refresh locked runtime dependencies to include the `fast-uri` host-confusion
+  fix and the `body-parser` request-limit fix used by the memory server build.
+- Reject high-severity runtime advisories in the public, CI, and release gates.
+
+## [2.3.0] - 2026-07-25
+
+### Added
+
+- Add `cairn completion bash|zsh|fish` for generating completion definitions
+  that distributions or users can install through each shell's standard
+  mechanism.
+- Exercise every generated definition and reject unsupported shell names in
+  the repository test suite.
+
 ## [2.2.1] - 2026-07-20
 
 ### Fixed
@@ -111,6 +129,9 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
+[2.3.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.3.0...v2.3.1
+[2.3.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.2.1...v2.3.0
+[2.2.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.2.0...v2.2.1
 [2.2.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.3...v2.0.0

package/README.md

@@ -14,7 +14,8 @@ across sessions, projects, and harnesses (Claude Code, OpenCode, …).
 ## Status
 
 Shipped: the memory server, the `cairn` CLI (`bootstrap`, `memory-server`, `sync`,
-`doctor`, `memory`, `audit-timer`, `uninstall`) installable via `npm i -g @cairnkeep/cli`, and the
+`doctor`, `memory`, `audit-timer`, `completion`, `uninstall`) installable via
+`npm i -g @cairnkeep/cli`, and the
 operating layer (commands,
 agents, hooks) installed on both Claude Code and OpenCode. The generic launchers
 expose wrapper seams (`.ai/pre-launch.sh`, `CAIRN_EXTRA_SETTINGS`,
@@ -68,8 +69,9 @@ storage paths, secrets, and private derived images, see
   `.ai/` launchers + env; `cairn doctor` health-checks the configured pieces;
   `cairn memory export|import` relocates the durable store between machines
   (`export` requires the optional `sqlite3` CLI);
-  `cairn audit-timer` installs the scheduled memory+wiki audit; `cairn uninstall`
-  reverses the install (backup-first, revertible).
+  `cairn audit-timer` installs the scheduled memory+wiki audit;
+  `cairn completion bash|zsh|fish` generates shell completion definitions; and
+  `cairn uninstall` reverses the install (backup-first, revertible).
 - **`templates/`** — project scaffolding (generic launchers, env) plus the
   derived-knowledge layer (wiki, alignment, graph, security, planning).
 - **`scripts/`** — asset-sync and maintenance utilities.
@@ -203,6 +205,7 @@ enabling them.
 
 ## More
 
+- **Guided learning paths and video scripts** — [docs/learning/README.md](docs/learning/README.md)
 - **Optional document RAG** (`domain_knowledge_*` via AnythingLLM) — [docs/domain-knowledge.md](docs/domain-knowledge.md)
 - **Building a private overlay** (wrap cairnkeep for your org/provider) — [docs/building-an-overlay.md](docs/building-an-overlay.md)
 - **Managed overlay distributions** (wrapper CLI, policy lock, private registry, rollback) — [docs/overlay-distributions.md](docs/overlay-distributions.md)

package/bin/cairn

@@ -47,6 +47,8 @@ Usage:
                            timer, and any given projects' bootstrap scaffold).
                            Backs everything up first with a revert.sh; keeps the
                            durable memory store unless --purge-memory is given.
+  cairn completion bash|zsh|fish
+                           Generate completion definitions for a major shell.
   cairn version            Print version
   cairn help               Show this help
 USAGE
@@ -76,6 +78,9 @@ case "$cmd" in
   audit-timer)
     exec "$CAIRN_ROOT/scripts/install-audit-timer.sh" "$@"
     ;;
+  completion)
+    exec "$CAIRN_ROOT/scripts/completion.sh" "$@"
+    ;;
   version | --version | -v)
     v=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$CAIRN_ROOT/package.json" 2>/dev/null | head -1)
     echo "cairnkeep ${v:-unknown}"

package/docs/learning/PRODUCTION-PLAN.md

@@ -0,0 +1,122 @@
+# 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.
+
+## Wave 0 - Course foundation
+
+**Deliverables**
+
+- Stable lesson IDs L00-L12.
+- Quickstart, practitioner, and operator tracks.
+- Lesson, video, and instructor templates.
+- Complete L00-L03 lesson and recording scripts.
+- Briefs and acceptance criteria for L04-L12.
+
+**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 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.
+
+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.
+
+**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 - 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 6 - Publication and maintenance
+
+1. Publish a landing article linking to the three 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.
+
+## 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 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.

package/docs/learning/README.md

@@ -0,0 +1,58 @@
+# 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.
+
+## Start here
+
+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.
+- [Operator](tracks/operator.md) - storage, optional services, containers, and
+  managed distributions.
+
+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).
+
+## Curriculum
+
+| ID | Lesson | Status | Typical time |
+|---|---|---|---:|
+| L00 | [Why Cairnkeep?](lessons/L00-why-cairnkeep.md) | Ready | 10 min |
+| L01 | [Try it safely](lessons/L01-safe-trial.md) | Ready | 15 min |
+| L02 | [Install the local workflow](lessons/L02-installation.md) | Ready | 25 min |
+| L03 | [Bootstrap the first project](lessons/L03-first-project.md) | Ready | 25 min |
+| L04 | [Memory fundamentals](lessons/L04-memory-fundamentals.md) | Brief | 35 min |
+| L05 | [The daily workflow](lessons/L05-daily-workflow.md) | Brief | 40 min |
+| L06 | [Repository review and security](lessons/L06-repository-quality.md) | Brief | 45 min |
+| L07 | [Privacy and storage](lessons/L07-privacy-and-storage.md) | Brief | 30 min |
+| L08 | [Multiple machines](lessons/L08-multiple-machines.md) | Brief | 40 min |
+| L09 | [Domain knowledge with RAG](lessons/L09-domain-knowledge.md) | Brief | 35 min |
+| 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 |
+
+## Teaching contract
+
+Every complete lesson contains:
+
+1. A practical problem and observable outcome.
+2. Prerequisites and a clean starting state.
+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.
+
+The learner should never need optional infrastructure to complete L00-L06.
+Remote memory, RAG, routing, and containers 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.

package/docs/learning/instructor-guide.md

@@ -0,0 +1,60 @@
+# 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.
+
+## 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.

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

@@ -0,0 +1,87 @@
+# L00 - Why Cairnkeep?
+
+**Status:** Ready
+**Track:** Quickstart
+**Time:** 10 minutes
+**Tested with:** Cairnkeep 2.3.1
+
+## Outcome
+
+You can explain what Cairnkeep remembers, what remains canonical in the
+repository, and how it differs from chat history and document retrieval.
+
+## Why this matters
+
+Coding harnesses are effective inside one session but important decisions,
+pitfalls, and conventions are easily lost between sessions or tools. Copying an
+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.
+
+## Mental model
+
+Keep four layers distinct:
+
+| Layer | Example | Role |
+|---|---|---|
+| Harness history | The current conversation | Temporary working context |
+| 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.
+
+## Exercise
+
+For each statement, choose the appropriate destination:
+
+1. “The payment API retries only idempotent operations.”
+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.”
+
+Suggested answer:
+
+- 1 can become memory after validation and should cite the canonical code or
+  specification in derived knowledge.
+- 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.
+
+## Verify
+
+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.**
+
+## Common failures
+
+| Misconception | Correction |
+|---|---|
+| 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 |
+| 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.
+
+## Recap
+
+- Memory is selective and durable.
+- Derived knowledge remains subordinate to canonical sources.
+- 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

@@ -0,0 +1,96 @@
+# L01 - Try it safely
+
+**Status:** Ready
+**Track:** Quickstart
+**Time:** 15 minutes
+**Tested with:** Cairnkeep 2.3.1
+
+## Outcome
+
+You can launch the published memory-server image as an unprivileged,
+read-only container and identify the only persistent resource it creates.
+
+## Prerequisites
+
+- Podman installed and able to run rootless containers.
+- No Cairnkeep installation or coding harness is required.
+
+## Mental model
+
+This is a packaging and isolation trial, not the complete harness workflow.
+The server communicates over stdio and waits for an MCP client. The container is
+ephemeral; the named course volume is persistent.
+
+## Exercise
+
+1. Pull the public image:
+
+   ```bash
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.3.1
+   ```
+
+2. Start the stdio server with a read-only root filesystem and no Linux
+   capabilities:
+
+   ```bash
+   podman run --rm -i \
+     --userns=keep-id:uid=10001,gid=10001 \
+     --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
+   ```
+
+3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it
+   remains running.
+
+4. Inspect the persistent resource:
+
+   ```bash
+   podman volume inspect cairnkeep-course-data
+   ```
+
+## Verify
+
+```bash
+podman volume exists cairnkeep-course-data
+echo $?
+```
+
+Exit status `0` confirms that the named volume exists. No listener was exposed
+on the network by this lesson.
+
+## Common failures
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `podman: command not found` | Podman is not installed | Skip L01 and continue with host installation in L02 |
+| Image pull is denied | Registry or network policy blocks GHCR | Use the npm installation in L02 |
+| SELinux mount error | Unsupported volume labelling mode | Confirm the documented Podman/SELinux setup before changing flags |
+
+## Privacy and trust boundary
+
+The command publishes no port and mounts no project directory, home directory,
+or credential. Only the named volume is persistent. Do not infer that a
+container automatically provides remote memory or a containerized harness.
+
+## Clean up
+
+This deletes only the empty course volume. Do not reuse this command for a
+volume containing real memory.
+
+```bash
+podman volume rm cairnkeep-course-data
+```
+
+## Recap
+
+- The server image runs unprivileged and read-only.
+- Stdio does not expose a network listener.
+- 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

@@ -0,0 +1,115 @@
+# L02 - Install the local workflow
+
+**Status:** Ready
+**Track:** Quickstart
+**Time:** 25 minutes
+**Tested with:** Cairnkeep 2.3.1 and Node.js 22 or newer
+
+## Outcome
+
+You can install the CLI, register the local memory server, install the operating
+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).
+- Permission to install an npm package globally for your user.
+
+## Mental model
+
+A complete setup has three independent parts:
+
+1. the `cairn` CLI and memory server;
+2. the MCP registration used by the harness;
+3. the operating layer containing commands, agents, hooks, and templates.
+
+`cairn bootstrap` configures a project later; it does not perform the first two
+machine-level steps.
+
+## Exercise
+
+1. Confirm the runtime:
+
+   ```bash
+   node --version
+   npm --version
+   ```
+
+2. Install Cairnkeep:
+
+   ```bash
+   npm install --global @cairnkeep/cli@2.3.1
+   cairn --version
+   ```
+
+3. Register the local stdio server under the stable name `cairn-memory`:
+
+   ```bash
+   claude mcp add cairn-memory -s user -- cairn memory-server
+   ```
+
+4. Install the operating layer:
+
+   ```bash
+   cairn sync --apply
+   ```
+
+5. Check for drift without modifying anything:
+
+   ```bash
+   cairn sync --check
+   ```
+
+## Verify
+
+Run both checks:
+
+```bash
+claude mcp get cairn-memory
+cairn sync --check
+```
+
+The MCP entry must invoke `cairn memory-server`, and the sync check must report
+no operating-layer drift. Having only one of these results is a partial
+installation.
+
+## Common failures
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `cairn` is not found | npm global bin directory is absent from `PATH` | Run `npm prefix -g`, locate its bin directory, and update `PATH` |
+| MCP exists but slash commands do not | Operating layer was not applied | Run `cairn sync --apply`, then restart the harness |
+| MCP starts but stores somewhere unexpected | A memory environment override is active | Inspect the effective environment and read L07 before continuing |
+| Existing managed files differ | Local customization conflicts with sync | Run `cairn sync --check`, review the diff, and back up before applying |
+
+## Privacy and trust boundary
+
+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.
+
+## Clean up if you stop the evaluation
+
+Continue directly to L03 if you are completing the quickstart. If you stop here,
+remove the MCP registration and review the non-writing uninstall plan:
+
+```bash
+claude mcp remove -s user cairn-memory
+cairn uninstall --dry-run
+```
+
+Do not delete memory stores as part of a course cleanup.
+
+## Recap
+
+- CLI installation, MCP registration, and operating-layer sync are distinct.
+- `sync --check` is the non-writing drift check.
+- 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).