@cairnkeep/cli 2.4.0 → 2.5.0

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

@@ -5,7 +5,7 @@
 
 ## Recording setup
 
-- Show only the four-layer table from the lesson.
+- 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.
 
@@ -24,12 +24,14 @@ remember, and what must remain in the repository or another canonical system.”
 
 **Show:** The lesson outcome.
 
-## 01:00 - Four layers
+## 01:00 - Trust ladder
 
-**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.”
+**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.
 
@@ -38,10 +40,11 @@ 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.”
+**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.
 
@@ -57,20 +60,21 @@ until confirmed. A verified operational prohibition is a durable constraint.”
 ## 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.”
+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, 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.”
+**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, Four layers, Memory vs RAG, Exercise, Boundary.
+- 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/L02-installation.md

@@ -71,13 +71,20 @@ the harness after applying assets.”
 
 **Show:** The two verification commands together.
 
-## 09:40 - Boundary
+## 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.”
 
-## 10:30 - Recap
+## 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

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

@@ -43,6 +43,9 @@ does not reinstall the machine-level MCP server or operating assets.”
 **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`.

package/docs/operating.md

@@ -16,8 +16,9 @@ installs. This guide covers all three in order.
 
 ## Prerequisites
 
-- Node.js 22 or newer (for the memory server) and a supported harness: Claude
-  Code, OpenCode, or Pi.
+- Node.js 22 or newer (for the memory server) and a supported harness. Claude
+  Code and OpenCode receive the full operating layer. Kimi Code receives the
+  memory MCP and launcher. Pi receives its native trajectory adapter.
 - Optional: the `sqlite3` CLI for `cairn memory export`. Runtime memory and
   `cairn memory import` do not require it.
 - Optional: an OpenAI-compatible LLM endpoint for memory extraction and
@@ -157,6 +158,37 @@ Model selection stays operator-env-driven through the existing
 variables (see "Configuration" below) — the harness commits no default model
 and carries no known-good allowlist.
 
+## Setup order (Kimi Code)
+
+Kimi Code can use the Cairnkeep memory MCP and the generated project launcher.
+It does not yet receive Cairnkeep-specific skills, commands, or hooks.
+
+For local stdio memory, create `.kimi-code/mcp.json` in the project:
+
+```json
+{
+  "mcpServers": {
+    "cairn-memory": {
+      "command": "cairn",
+      "args": ["memory-server"]
+    }
+  }
+}
+```
+
+Then launch from the project root with `./.ai/start-kimi.sh`. The launcher
+loads `.ai/.env`, runs the optional pre-launch and post-exit hooks, and forwards
+all arguments to `kimi`.
+
+Remote HTTP configuration needs one extra precaution: Kimi validates `url` as
+a literal URL and does not expand `${CAIRN_MEMORY_REMOTE_URL}` there. Put the
+resolved URL in a private `.kimi-code/mcp.json` and use
+`bearerTokenEnvVar: "CAIRN_MEMORY_HTTP_TOKEN"` so the token value remains in
+the environment. A repository-root `.mcp.json` must also be valid because Kimi
+parses it before applying its private override. See
+[Harness compatibility](harness-compatibility.md#kimi-code) for the complete
+configuration and trust-boundary guidance.
+
 ## Setup order (Pi)
 
 Pi trajectory capture uses the same project scaffold and store, but its source
@@ -630,13 +662,14 @@ maintain a running install — without forking the core. All are opt-in.
 
 ### Launcher seams
 
-The generic launchers (`.ai/start-claude.sh`, `.ai/start-opencode.sh`) run three
-optional hooks around the harness, each a no-op when absent:
+The generic launchers (`.ai/start-claude.sh`, `.ai/start-opencode.sh`,
+`.ai/start-kimi.sh`, and `.ai/start-pi.sh`) run optional hooks around the
+harness, each a no-op when absent:
 
 | Seam | When | Purpose |
 |---|---|---|
 | `.ai/pre-launch.sh` | sourced after `.env`, before launch | export env (e.g. a provider base URL / auth), refresh credentials, or abort by returning non-zero |
-| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered on the harness (`--settings` / `OPENCODE_CONFIG`); process env still wins over it |
+| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered on Claude Code (`--settings`) or OpenCode (`OPENCODE_CONFIG`); Kimi and Pi leave the variable available to hooks but do not interpret it |
 | `.ai/post-exit.sh` | sourced after the harness exits | teardown; `CAIRN_EXIT_STATUS` holds the exit code |
 
 A wrapper that needs a non-default provider drops a `pre-launch.sh` that renders

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.4.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}
+{"identifier":"cairn-offline-fake-v1","package_version":"2.5.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

package/package.json

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

package/scripts/bootstrap.sh

@@ -56,6 +56,7 @@ install_file() {
 install_file "$TPL/start-claude.sh.template"   "$target/.ai/start-claude.sh"   0755
 install_file "$TPL/start-opencode.sh.template" "$target/.ai/start-opencode.sh" 0755
 install_file "$TPL/start-pi.sh.template"       "$target/.ai/start-pi.sh"       0755
+install_file "$TPL/start-kimi.sh.template"     "$target/.ai/start-kimi.sh"     0755
 install_file "$TPL/env.example.template"       "$target/.ai/env.example"       0644
 install_file "$TPL/trajectory-redaction.json.template" "$target/.ai/trajectory-redaction.json" 0644
 install_file "$TPL/capabilities.json.template" "$target/.ai/capabilities.json" 0600
@@ -105,3 +106,4 @@ echo "  3. Install the operating layer (commands/agents/hooks): cairn sync --app
 echo "     For Pi trajectory capture, also run: cairn sync-pi --apply"
 echo "     From a source clone, use bin/cairn in place of cairn."
 echo "  4. Launch: $target/.ai/start-claude.sh"
+echo "     Kimi memory-client launch: $target/.ai/start-kimi.sh"

package/scripts/test-bootstrap-untracked.sh

@@ -53,6 +53,7 @@ mkdir "$tmp/repo"
 git -C "$tmp/repo" init -q
 "$ROOT/scripts/bootstrap.sh" --untracked "$tmp/repo" >/dev/null
 [[ -f "$tmp/repo/.ai/start-claude.sh" ]] || fail "scaffold missing"
+[[ -x "$tmp/repo/.ai/start-kimi.sh" ]] || fail "Kimi launcher missing"
 [[ -f "$tmp/repo/.planning/config.json" ]] || fail "planning layer missing"
 [[ -f "$tmp/repo/.agentfs/.gitignore" ]] || fail "project-memory ignore guard missing"
 [[ -z "$(git -C "$tmp/repo" status --porcelain)" ]] || fail "scaffold visible to git"
@@ -66,7 +67,7 @@ grep -qxF "/.agentfs/" "$tmp/repo/.git/info/exclude" || fail "missing /.agentfs/
 printf '%s\n' '{"schema_version":1,"capabilities":{"wiki":false},"logging":{"callbacks":true}}' >"$tmp/repo/.ai/capabilities.json"
 chmod 600 "$tmp/repo/.ai/capabilities.json"
 printf '%s\n' '# operator-owned environment' >"$tmp/repo/.ai/env.example"
-asset_paths='.ai/start-claude.sh .ai/start-opencode.sh .ai/start-pi.sh .ai/env.example .ai/trajectory-redaction.json .ai/capabilities.json .agentfs/.gitignore .planning/config.json .planning/wiki/index.md .planning/wiki/policy.md .planning/wiki/CONTRADICTIONS.md .planning/wiki/LOG.md .planning/alignment/policy.md .planning/alignment/gap-register.yaml .planning/graphs/policy.md .planning/graphs/.gitignore .planning/security/policy.md'
+asset_paths='.ai/start-claude.sh .ai/start-opencode.sh .ai/start-pi.sh .ai/start-kimi.sh .ai/env.example .ai/trajectory-redaction.json .ai/capabilities.json .agentfs/.gitignore .planning/config.json .planning/wiki/index.md .planning/wiki/policy.md .planning/wiki/CONTRADICTIONS.md .planning/wiki/LOG.md .planning/alignment/policy.md .planning/alignment/gap-register.yaml .planning/graphs/policy.md .planning/graphs/.gitignore .planning/security/policy.md'
 mkdir -p "$tmp/assets-before"
 for path in $asset_paths; do
   cp "$tmp/repo/$path" "$tmp/assets-before/${path//\//__}"

package/scripts/test-launcher-hooks.sh

@@ -423,6 +423,8 @@ launcher="$repo/.ai/start-claude.sh"
 [[ -x "$launcher" ]] || fail "launcher not scaffolded"
 pi_launcher="$repo/.ai/start-pi.sh"
 [[ -x "$pi_launcher" ]] || fail "Pi launcher not scaffolded"
+kimi_launcher="$repo/.ai/start-kimi.sh"
+[[ -x "$kimi_launcher" ]] || fail "Kimi launcher not scaffolded"
 
 # OpenCode's run mode ends a turn after content-only output. Commands that need
 # owner I/O must therefore make their first response action a tool call rather
@@ -464,11 +466,17 @@ cat > "$tmp/bin/opencode" <<'FAKE'
 } > "$OPENCODE_LOG"
 exit "${FAKE_EXIT:-0}"
 FAKE
-chmod +x "$tmp/bin/claude" "$tmp/bin/opencode"
+cat > "$tmp/bin/kimi" <<'FAKE'
+#!/usr/bin/env bash
+{ echo "args:$*"; echo "prelaunch:${PRELAUNCH_RAN:-0}"; echo "extra:${CAIRN_EXTRA_SETTINGS:-}"; } > "$KIMI_LOG"
+exit "${FAKE_EXIT:-0}"
+FAKE
+chmod +x "$tmp/bin/claude" "$tmp/bin/opencode" "$tmp/bin/kimi"
 ln -s "$ROOT/bin/cairn" "$tmp/bin/cairn"
 export PATH="$tmp/bin:$PATH"
 export CLAUDE_LOG="$tmp/claude.log"
 export OPENCODE_LOG="$tmp/opencode.log"
+export KIMI_LOG="$tmp/kimi.log"
 
 # Claude sync has three exact installation states. Normal sync and an explicit
 # overlay request with the master off must contain no capability hook bytes or
@@ -528,6 +536,10 @@ grep -qx "args:--foo bar" "$OPENCODE_LOG" || fail "OpenCode baseline did not pas
 grep -qx "config:" "$OPENCODE_LOG" || fail "OpenCode baseline selected a config root"
 grep -qx "capability-registration:0" "$OPENCODE_LOG" || fail "OpenCode baseline registered a capability plugin"
 
+"$kimi_launcher" --foo bar >/dev/null 2>&1 || fail "Kimi baseline launch failed"
+grep -qx "args:--foo bar" "$KIMI_LOG" || fail "Kimi baseline did not pass args through"
+grep -qx "prelaunch:0" "$KIMI_LOG" || fail "Kimi prelaunch marker leaked without a hook"
+
 # Invalid/off master values stay on the legacy direct-exec path: one harness
 # process, unchanged argv/config environment, and no isolated assets or store.
 legacy_claude="$tmp/legacy-claude"
@@ -618,6 +630,12 @@ grep -qx "prelaunch:1" "$OPENCODE_LOG" || fail "OpenCode pre-launch env not visi
 grep -qx "args:--settings-probe" "$OPENCODE_LOG" || fail "OpenCode extra config changed harness argv"
 grep -qx "explicit-config:$tmp/settings.json" "$OPENCODE_LOG" || fail "CAIRN_EXTRA_SETTINGS not exported as OPENCODE_CONFIG"
 
+rm -f "$KIMI_LOG"
+"$kimi_launcher" --plan >/dev/null 2>&1 || fail "Kimi launch with pre-launch failed"
+grep -qx "args:--plan" "$KIMI_LOG" || fail "Kimi pre-launch changed harness argv"
+grep -qx "prelaunch:1" "$KIMI_LOG" || fail "Kimi pre-launch env not visible to harness"
+grep -qx "extra:$tmp/settings.json" "$KIMI_LOG" || fail "Kimi pre-launch environment was not preserved"
+
 # 3. pre-launch.sh non-zero aborts the launch before the harness runs.
 rm -f "$CLAUDE_LOG"
 cat > "$repo/.ai/pre-launch.sh" <<'EOF'
@@ -626,6 +644,9 @@ return 1
 EOF
 if "$launcher" >/dev/null 2>&1; then fail "non-zero pre-launch should abort the launch"; fi
 [[ ! -f "$CLAUDE_LOG" ]] || fail "harness ran despite pre-launch abort"
+rm -f "$KIMI_LOG"
+if "$kimi_launcher" >/dev/null 2>&1; then fail "non-zero pre-launch should abort Kimi"; fi
+[[ ! -f "$KIMI_LOG" ]] || fail "Kimi ran despite pre-launch abort"
 rm -f "$repo/.ai/pre-launch.sh"
 
 # 4. post-exit.sh runs after the harness with $CAIRN_EXIT_STATUS.
@@ -638,6 +659,13 @@ status=$?
 [[ "$status" -eq 7 ]] || fail "expected exit 7 from launcher, got $status"
 grep -qx "post:7" "$tmp/post.log" || fail "post-exit hook did not see CAIRN_EXIT_STATUS"
 
+rm -f "$tmp/post.log" "$KIMI_LOG"
+FAKE_EXIT=8 "$kimi_launcher" --auto >/dev/null 2>&1 && fail "Kimi launcher should propagate harness exit code"
+status=$?
+[[ "$status" -eq 8 ]] || fail "expected exit 8 from Kimi launcher, got $status"
+grep -qx "args:--auto" "$KIMI_LOG" || fail "Kimi launcher changed arguments"
+grep -qx "post:8" "$tmp/post.log" || fail "Kimi launcher post-exit status missing"
+
 # 5. Pi launcher preserves the same env/pre/post seams and passes arguments
 # unchanged; Pi has no generic settings-file flag so CAIRN_EXTRA_SETTINGS is ignored.
 rm -f "$repo/.ai/pre-launch.sh" "$repo/.ai/post-exit.sh"

package/scripts/test-learning-docs.sh

@@ -7,13 +7,22 @@ cd "$ROOT"
 version=$(node -p "require('./package.json').version")
 landing=docs/learning/README.md
 production=docs/learning/PRODUCTION-PLAN.md
+coverage=docs/learning/CURRICULUM-MAP.md
+feature_guide=docs/learning/FEATURE-GUIDE.md
 
-[[ -f "$landing" && -f "$production" ]]
+[[ -f "$landing" && -f "$production" && -f "$coverage" && -f "$feature_guide" ]]
 grep -qF 'docs/learning/README.md' README.md
+grep -qF "**Baseline:** Cairnkeep $version" "$coverage"
+grep -qF "**Baseline:** Cairnkeep $version" "$feature_guide"
+grep -qF 'https://github.com/cairnkeep/cairnkeep-course-labs' "$landing"
+for checkpoint in course-00-app course-01-bootstrap course-02-memory course-03-quality \
+  course-04-operation course-05-evidence course-06-governance course-07-evaluation; do
+  grep -qF "\`$checkpoint\`" "$coverage"
+done
 
 ready=0
 brief=0
-for number in $(seq -w 0 12); do
+for number in $(seq -w 0 17); 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
@@ -41,17 +50,24 @@ for number in $(seq -w 0 12); do
   fi
 done
 
-[[ $ready -eq 4 && $brief -eq 9 ]] || {
+[[ $ready -eq 4 && $brief -eq 14 ]] || {
   echo "unexpected learning status totals: ready=$ready brief=$brief" >&2
   exit 1
 }
 
-for track in quickstart practitioner operator; do
+for track in quickstart practitioner evidence-and-evaluation operator; do
   file=docs/learning/tracks/$track.md
   [[ -f "$file" ]]
   grep -q '^# ' "$file"
 done
 
+while read -r command; do
+  grep -qF "\`cairn $command\`" "$coverage" || {
+    echo "top-level command has no curriculum owner: cairn $command" >&2
+    exit 1
+  }
+done < <(bin/cairn help | sed -n 's/^  cairn \([a-z-]*\).*/\1/p' | sort -u)
+
 node <<'NODE'
 const { existsSync, readdirSync, readFileSync } = require("node:fs");
 const { dirname, resolve } = require("node:path");

package/scripts/test-package-install.sh

@@ -43,6 +43,7 @@ bootstrap_output=$(cairn bootstrap "$tmp/project")
 [[ "$bootstrap_output" == *"cairn sync --apply"* ]] || fail "bootstrap printed invalid operating-layer setup instructions"
 [[ -x "$tmp/project/.ai/start-claude.sh" ]] || fail "bootstrap did not install an executable Claude launcher"
 [[ -x "$tmp/project/.ai/start-pi.sh" ]] || fail "bootstrap did not install an executable Pi launcher"
+[[ -x "$tmp/project/.ai/start-kimi.sh" ]] || fail "bootstrap did not install an executable Kimi launcher"
 [[ -f "$tmp/project/.planning/config.json" ]] || fail "bootstrap did not install the planning scaffold"
 
 (cd "$tmp/project" && cairn doctor) >/dev/null || fail "installed package failed cairn doctor"
@@ -220,6 +221,8 @@ NODE
   fail "npm tarball omitted the Pi sync command"
 [[ -f "$installed_root/templates/start-pi.sh.template" ]] || \
   fail "npm tarball omitted the Pi launcher template"
+[[ -f "$installed_root/templates/start-kimi.sh.template" ]] || \
+  fail "npm tarball omitted the Kimi launcher template"
 [[ -f "$installed_root/schemas/note.schema.json" ]] || \
   fail "npm tarball omitted the note schema"
 [[ -f "$installed_root/schemas/memory-node.schema.json" ]] || \

package/scripts/uninstall.sh

@@ -39,6 +39,7 @@ PROJECT_AI_FILES=(
   start-claude.sh
   start-opencode.sh
   start-pi.sh
+  start-kimi.sh
   env.example
   trajectory-redaction.json
   capabilities.json

package/templates/start-kimi.sh.template

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Cairnkeep launcher for Kimi Code. Loads this repo's .ai/.env (if present),
+# then launches Kimi from the repo root. Kimi reads a valid project .mcp.json
+# and an optional .kimi-code/mcp.json override; it does not expand environment
+# references in an HTTP URL, so remote URLs must be materialized by private
+# machine configuration rather than committed to a shared project file.
+#
+# Wrapper seams (both optional, both no-ops when absent):
+#   .ai/pre-launch.sh        sourced after .env, before launch. May export env
+#                            or abort the launch by returning/exiting non-zero.
+#   .ai/post-exit.sh         sourced after Kimi exits, with
+#                            $CAIRN_EXIT_STATUS set to the exit code.
+set -euo pipefail
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+if [[ -f "$ROOT_DIR/.ai/.env" ]]; then
+  set -a
+  # shellcheck disable=SC1091
+  . "$ROOT_DIR/.ai/.env"
+  set +a
+fi
+if [[ -f "$ROOT_DIR/.ai/pre-launch.sh" ]]; then
+  # shellcheck disable=SC1091
+  . "$ROOT_DIR/.ai/pre-launch.sh"
+fi
+
+cd "$ROOT_DIR"
+
+if [[ -f "$ROOT_DIR/.ai/post-exit.sh" ]]; then
+  set +e
+  kimi "$@"
+  CAIRN_EXIT_STATUS=$?
+  set -e
+  export CAIRN_EXIT_STATUS
+  # shellcheck disable=SC1091
+  . "$ROOT_DIR/.ai/post-exit.sh" || true
+  exit "$CAIRN_EXIT_STATUS"
+fi
+exec kimi "$@"