@cairnkeep/cli 2.2.0 → 2.3.0

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

@@ -0,0 +1,76 @@
+# L00 Video Script - Why Cairnkeep?
+
+**Target duration:** 7 minutes
+**Companion lesson:** [L00](../lessons/L00-why-cairnkeep.md)
+
+## Recording setup
+
+- Show only the four-layer 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 - Four layers
+
+**Say:** “Start with four different layers. The current conversation is working
+context. Cairnkeep memory is a set of 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 answers a different question: which parts of a larger
+document are relevant right now? Cairnkeep can integrate with a RAG system, but
+it does not require one. 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. Remote storage, model extraction,
+embeddings, and document RAG are all explicit, optional choices.”
+
+**Show:** “Local by default. Optional means opt-in.”
+
+## 06:10 - Recap
+
+**Say:** “Remember three things: durable memory is selective, derived knowledge
+does not overrule canonical sources, and optional services are not prerequisites.
+In L01 we will inspect the published container without installing the complete
+workflow.”
+
+## Editing notes
+
+- Chapters: Problem, Four layers, Memory vs RAG, 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

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

@@ -0,0 +1,90 @@
+# 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:40 - 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.”
+
+## 10:30 - 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

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

package/docs/operating.md

@@ -26,6 +26,20 @@ installs. This guide covers all three in order.
 - Optional: rootless Podman for the containerized memory server and isolated
   workspace base described in [Containers](containers.md).
 
+## Shell completion
+
+Generate completion definitions directly from the CLI:
+
+```bash
+cairn completion bash
+cairn completion zsh
+cairn completion fish
+```
+
+Distributions can install these outputs into the platform's normal completion
+directories. They can also be loaded for the current shell, for example with
+`source <(cairn completion bash)`.
+
 ## Setup order (Claude Code)
 
 The commands below install the default local topology: `cairn-memory` runs as a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",

package/scripts/cairn-container

@@ -171,7 +171,8 @@ run_workspace() {
   repo=$(absolute_dir "$repo")
   case "$mode" in sandbox | shared) ;; *) fail "--mode must be sandbox or shared" ;; esac
   if [ -z "$workspace_volume" ]; then
-    workspace_volume="cairnkeep-workspace-$(safe_name "$(basename "$repo")")"
+    repo_id=$(printf '%s' "$repo" | cksum | awk '{print $1}')
+    workspace_volume="cairnkeep-workspace-$(safe_name "$(basename "$repo")")-$repo_id"
   fi
 
   require_engine

package/scripts/completion.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+shell=${1:-}
+
+case "$shell" in
+  bash)
+    cat <<'EOF'
+_cairn_complete() {
+  local current previous commands
+  COMPREPLY=()
+  current=${COMP_WORDS[COMP_CWORD]}
+  previous=${COMP_WORDS[COMP_CWORD-1]:-}
+  commands="bootstrap memory-server sync doctor memory audit-timer uninstall completion version help"
+  if (( COMP_CWORD == 1 )); then
+    COMPREPLY=( $(compgen -W "$commands" -- "$current") )
+    return
+  fi
+  case "${COMP_WORDS[1]}" in
+    bootstrap) COMPREPLY=( $(compgen -W "--untracked" -- "$current") ) ;;
+    sync) COMPREPLY=( $(compgen -W "--apply --live-root" -- "$current") ) ;;
+    memory) COMPREPLY=( $(compgen -W "path export import" -- "$current") ) ;;
+    audit-timer) COMPREPLY=( $(compgen -W "--on-calendar --para-root --render-only" -- "$current") ) ;;
+    uninstall) COMPREPLY=( $(compgen -W "--dry-run --yes --purge-memory --live-root" -- "$current") ) ;;
+    completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "$current") ) ;;
+  esac
+}
+complete -F _cairn_complete cairn
+EOF
+    ;;
+  zsh)
+    cat <<'EOF'
+#compdef cairn
+_cairn() {
+  local -a commands
+  commands=(
+    'bootstrap:scaffold a project'
+    'memory-server:run the memory MCP server'
+    'sync:install the Claude operating layer'
+    'doctor:check runtime dependencies and endpoints'
+    'memory:manage the durable memory store'
+    'audit-timer:install a memory and wiki audit timer'
+    'uninstall:remove installed Cairnkeep components safely'
+    'completion:generate shell completion'
+    'version:show the installed version'
+    'help:show help'
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+  case $words[2] in
+    bootstrap) _arguments '--untracked[keep scaffold out of Git]' '*:project directory:_files -/' ;;
+    sync) _arguments '--apply[apply changes]' '--live-root[project Claude root]:directory:_files -/' ;;
+    memory) _values 'memory command' path export import ;;
+    audit-timer) _arguments '--on-calendar[systemd calendar]:calendar:' '--para-root[PARA root]:directory:_files -/' '--render-only[render directory]:directory:_files -/' ;;
+    uninstall) _arguments '--dry-run[show changes]' '--yes[skip confirmation]' '--purge-memory[delete memory]' '--live-root[project Claude root]:directory:_files -/' '*:project directory:_files -/' ;;
+    completion) _values 'shell' bash zsh fish ;;
+    *) _arguments '*:argument:_files' ;;
+  esac
+}
+_cairn "$@"
+EOF
+    ;;
+  fish)
+    cat <<'EOF'
+complete -c cairn -f
+for command in bootstrap memory-server sync doctor memory audit-timer uninstall completion version help
+    complete -c cairn -n "not __fish_seen_subcommand_from bootstrap memory-server sync doctor memory audit-timer uninstall completion version help" -a $command
+end
+complete -c cairn -n "__fish_seen_subcommand_from bootstrap" -l untracked
+complete -c cairn -n "__fish_seen_subcommand_from memory" -a "path export import"
+complete -c cairn -n "__fish_seen_subcommand_from completion" -a "bash zsh fish"
+EOF
+    ;;
+  *)
+    printf 'usage: cairn completion bash|zsh|fish\n' >&2
+    exit 2
+    ;;
+esac

package/scripts/test-completion.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+for shell in bash zsh fish; do
+  "$ROOT/bin/cairn" completion "$shell" > "$tmp/$shell"
+  [[ -s $tmp/$shell ]]
+  grep -q 'completion' "$tmp/$shell"
+done
+
+grep -q 'complete -F _cairn_complete cairn' "$tmp/bash"
+grep -q '#compdef cairn' "$tmp/zsh"
+grep -q 'complete -c cairn' "$tmp/fish"
+
+if "$ROOT/bin/cairn" completion unsupported >/dev/null 2>&1; then
+  echo "completion accepted an unsupported shell" >&2
+  exit 1
+fi
+
+git -C "$ROOT" diff --check
+echo "PASS: shell completion generation"

package/scripts/test-container-runner.sh

@@ -80,4 +80,8 @@ has_arg CAIRN_WORKSPACE_MODE=shared
 lacks_arg "$repo:/source:ro,Z"
 has_arg bash
 
+repo_id=$(printf '%s' "$repo" | cksum | awk '{print $1}')
+run_launcher workspace --repo "$repo" --image example/workspace:1
+has_arg "cairnkeep-workspace-repository-$repo_id:/workspace:Z,U"
+
 echo "PASS: container launcher security and workspace contracts"

package/scripts/test-container.sh

@@ -21,12 +21,13 @@ server_image="localhost/cairnkeep-test-server:$suffix"
 workspace_image="localhost/cairnkeep-test-workspace:$suffix"
 volume="cairnkeep-test-data-$suffix"
 sandbox_volume="cairnkeep-test-workspace-$suffix"
+conflict_volume="cairnkeep-test-conflict-$suffix"
 name="cairnkeep-test-$suffix"
 tmp=$(mktemp -d)
 
 cleanup() {
   "$ENGINE" rm -f "$name" >/dev/null 2>&1 || true
-  "$ENGINE" volume rm -f "$volume" "$sandbox_volume" >/dev/null 2>&1 || true
+  "$ENGINE" volume rm -f "$volume" "$sandbox_volume" "$conflict_volume" >/dev/null 2>&1 || true
   "$ENGINE" image rm -f "$server_image" "$workspace_image" >/dev/null 2>&1 || true
   rm -rf "$tmp"
 }
@@ -180,4 +181,34 @@ else
     "$workspace_image" sh -c 'test "$(cat sandbox.txt)" = sandbox'
 fi
 
+# A pre-populated, unmarked volume must not be merged with repository content.
+"$ENGINE" volume create "$conflict_volume" >/dev/null
+if [[ "$ENGINE" == podman ]]; then
+  "$ENGINE" run --rm --userns=keep-id:uid=10001,gid=10001 \
+    --volume "$conflict_volume:/workspace:Z,U" \
+    --env CAIRN_WORKSPACE_MODE=shared \
+    "$workspace_image" sh -c 'printf unrelated > unrelated.txt'
+else
+  "$ENGINE" run --rm --user root --entrypoint sh \
+    --volume "$conflict_volume:/workspace" "$workspace_image" \
+    -c 'printf unrelated > /workspace/unrelated.txt; chown -R 10001:10001 /workspace'
+fi
+if [[ "$ENGINE" == podman ]]; then
+  conflict_mounts=(
+    --userns=keep-id:uid=10001,gid=10001
+    --volume "$tmp/repo:/source:ro,Z"
+    --volume "$conflict_volume:/workspace:Z,U"
+  )
+else
+  conflict_mounts=(
+    --volume "$tmp/repo:/source:ro"
+    --volume "$conflict_volume:/workspace"
+  )
+fi
+if "$ENGINE" run --rm "${conflict_mounts[@]}" \
+  --env CAIRN_WORKSPACE_MODE=sandbox "$workspace_image" true >/dev/null 2>&1; then
+  echo "FAIL: sandbox merged into a non-empty unmarked volume" >&2
+  exit 1
+fi
+
 echo "PASS: container stdio, guarded HTTP, persistence, shared, and sandbox modes"

package/scripts/test-learning-docs.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$ROOT"
+
+version=$(node -p "require('./package.json').version")
+landing=docs/learning/README.md
+production=docs/learning/PRODUCTION-PLAN.md
+
+[[ -f "$landing" && -f "$production" ]]
+grep -qF 'docs/learning/README.md' README.md
+
+ready=0
+brief=0
+for number in $(seq -w 0 12); do
+  matches=(docs/learning/lessons/L"$number"-*.md)
+  [[ ${#matches[@]} -eq 1 && -f ${matches[0]} ]] || {
+    echo "learning path must contain exactly one L$number lesson" >&2
+    exit 1
+  }
+  lesson=${matches[0]}
+  grep -q '^## Outcome$' "$lesson"
+  if grep -q '^\*\*Status:\*\* Ready' "$lesson"; then
+    ready=$((ready + 1))
+    grep -qF "Tested with:** Cairnkeep $version" "$lesson"
+    script=$(sed -n 's|.*(\.\./video-scripts/\([^)]*\)).*|docs/learning/video-scripts/\1|p' "$lesson")
+    [[ -n "$script" && -f "$script" ]] || {
+      echo "ready lesson has no presenter script: $lesson" >&2
+      exit 1
+    }
+    grep -q '^## Common failures$' "$lesson"
+    grep -q '^## Privacy and trust boundary$' "$lesson"
+  elif grep -q '^\*\*Status:\*\* Brief' "$lesson"; then
+    brief=$((brief + 1))
+    grep -q '^## Acceptance criteria$' "$lesson"
+    grep -q '^## Planned video$' "$lesson"
+  else
+    echo "lesson has an unsupported status: $lesson" >&2
+    exit 1
+  fi
+done
+
+[[ $ready -eq 4 && $brief -eq 9 ]] || {
+  echo "unexpected learning status totals: ready=$ready brief=$brief" >&2
+  exit 1
+}
+
+for track in quickstart practitioner operator; do
+  file=docs/learning/tracks/$track.md
+  [[ -f "$file" ]]
+  grep -q '^# ' "$file"
+done
+
+node <<'NODE'
+const { existsSync, readdirSync, readFileSync } = require("node:fs");
+const { dirname, resolve } = require("node:path");
+
+function markdownFiles(root) {
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const path = `${root}/${entry.name}`;
+    return entry.isDirectory() ? markdownFiles(path) : path.endsWith(".md") ? [path] : [];
+  });
+}
+
+for (const file of markdownFiles("docs/learning")) {
+  const text = readFileSync(file, "utf8");
+  for (const match of text.matchAll(/\]\(([^)]+)\)/g)) {
+    const target = match[1].split("#", 1)[0];
+    if (!target || /^[a-z]+:/i.test(target)) continue;
+    if (!existsSync(resolve(dirname(file), target))) {
+      throw new Error(`broken learning link in ${file}: ${match[1]}`);
+    }
+  }
+}
+NODE
+
+echo "PASS: learning path structure, readiness, scripts, and version alignment"