@cairnkeep/cli 2.8.0 → 2.9.0

package/scripts/completion.sh

@@ -11,7 +11,7 @@ _cairn_complete() {
   COMPREPLY=()
   current=${COMP_WORDS[COMP_CWORD]}
   previous=${COMP_WORDS[COMP_CWORD-1]:-}
-  commands="bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities notes eval skill graph memory audit-timer uninstall completion version help"
+  commands="bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help"
   if (( COMP_CWORD == 1 )); then
     COMPREPLY=( $(compgen -W "$commands" -- "$current") )
     return
@@ -51,6 +51,8 @@ _cairn_complete() {
         *) COMPREPLY=( $(compgen -W "list status enable disable reset logging" -- "$current") ) ;;
       esac
       ;;
+    mcp-tools) COMPREPLY=( $(compgen -W "list status set reset full read-only custom --tool --project --json" -- "$current") ) ;;
+    pack) COMPREPLY=( $(compgen -W "init lock validate install list show remove enable disable update skills approve-skill revoke-skill --id --version --title --description --license --ref --project --project-id --check --apply --confirm --json" -- "$current") ) ;;
     notes) COMPREPLY=( $(compgen -W "distill search-error promote doctor --project --session --all-projects --para-root --text --component --with --confirm --repair --json" -- "$current") ) ;;
     eval)
       case "${COMP_WORDS[2]:-}" in
@@ -67,7 +69,7 @@ _cairn_complete() {
     graph) COMPREPLY=( $(compgen -W "build query status diff explain path --force" -- "$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 --pi-live-root --kimi-live-root" -- "$current") ) ;;
+    uninstall) COMPREPLY=( $(compgen -W "--dry-run --yes --purge-memory --purge-packs --live-root --pi-live-root --kimi-live-root" -- "$current") ) ;;
     completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "$current") ) ;;
   esac
 }
@@ -89,6 +91,8 @@ _cairn() {
     'trajectory:inspect and prune local session trajectories'
     'artifact:inspect, delete, and prune local artifacts'
     'capabilities:inspect and manage project capability state'
+    'mcp-tools:inspect and restrict MCP tool exposure'
+    'pack:manage immutable context packs and skill approvals'
     'notes:distill and search local hindsight notes'
     'eval:run and inspect default-off local evaluations'
     'skill:review and evaluate evidence-backed skill improvements'
@@ -120,6 +124,8 @@ _cairn() {
         *) _values 'artifact command' list show delete prune ;;
       esac
       ;;
+    mcp-tools) _values 'MCP tool profile command' list status set reset full read-only custom '--tool[allow an exact tool]:tool:' '--project[project root]:directory:_files -/' '--json[emit JSON]' ;;
+    pack) _values 'context pack command' init lock validate install list show remove enable disable update skills approve-skill revoke-skill '--ref[pinned Git ref]:ref:' '--project[project root]:directory:_files -/' '--project-id[remote project ID]:project ID:' '--check[inspect update]' '--apply[apply update]' '--confirm[confirm digest]:digest:' '--json[emit JSON]' ;;
     capabilities)
       case $words[3] in
         list|status) _arguments '--json[emit JSON]' ;;
@@ -157,7 +163,7 @@ _cairn() {
     graph) _values 'graph command' build query status diff explain path '--force[allow a smaller graph after code deletion]' ;;
     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 -/' '--pi-live-root[Pi agent root]:directory:_files -/' '--kimi-live-root[Kimi Code root]:directory:_files -/' '*:project directory:_files -/' ;;
+    uninstall) _arguments '--dry-run[show changes]' '--yes[skip confirmation]' '--purge-memory[delete memory]' '--purge-packs[delete context packs]' '--live-root[project Claude root]:directory:_files -/' '--pi-live-root[Pi agent root]:directory:_files -/' '--kimi-live-root[Kimi Code root]:directory:_files -/' '*:project directory:_files -/' ;;
     completion) _values 'shell' bash zsh fish ;;
     *) _arguments '*:argument:_files' ;;
   esac
@@ -168,8 +174,8 @@ EOF
   fish)
     cat <<'EOF'
 complete -c cairn -f
-for command in bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities notes eval skill graph memory audit-timer uninstall completion version help
-    complete -c cairn -n "not __fish_seen_subcommand_from bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities notes eval skill graph memory audit-timer uninstall completion version help" -a $command
+for command in bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help
+    complete -c cairn -n "not __fish_seen_subcommand_from bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help" -a $command
 end
 complete -c cairn -n "__fish_seen_subcommand_from sync" -l apply
 complete -c cairn -n "__fish_seen_subcommand_from sync" -l live-root -r
@@ -193,6 +199,17 @@ complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from reset" -l all
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from logging; and not __fish_seen_subcommand_from enable disable reset" -a "enable disable reset"
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from list status enable disable reset logging" -l json
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -a "list status set reset"
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools; and __fish_seen_subcommand_from set" -a "full read-only custom"
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -l project -r
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -l tool -r
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -l json
+complete -c cairn -n "__fish_seen_subcommand_from pack" -a "init lock validate install list show remove enable disable update skills approve-skill revoke-skill"
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l project -r
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l project-id -r
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l ref -r
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l confirm -r
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l json
 complete -c cairn -n "__fish_seen_subcommand_from notes" -a "distill search-error promote doctor"
 complete -c cairn -n "__fish_seen_subcommand_from eval; and not __fish_seen_subcommand_from validate run ablate report prune delete" -a "validate run ablate report prune delete"
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from validate run ablate" -l task-set -r
@@ -234,6 +251,8 @@ complete -c cairn -n "__fish_seen_subcommand_from graph; and __fish_seen_subcomm
 complete -c cairn -n "__fish_seen_subcommand_from completion" -a "bash zsh fish"
 complete -c cairn -n "__fish_seen_subcommand_from uninstall" -l pi-live-root -r
 complete -c cairn -n "__fish_seen_subcommand_from uninstall" -l kimi-live-root -r
+complete -c cairn -n "__fish_seen_subcommand_from uninstall" -l purge-memory
+complete -c cairn -n "__fish_seen_subcommand_from uninstall" -l purge-packs
 EOF
     ;;
   *)

package/scripts/doctor.sh

@@ -400,6 +400,45 @@ case "$eval_state" in
   unsafe) warn "evaluation report storage is unsafe" ;;
 esac
 
+# 12. MCP least-authority profile. Invalid or unknown custom tool names are a
+# startup failure, so doctor treats them as an actionable configuration error.
+mcp_profile_cli="$CAIRN_ROOT/mcp-memory-server/dist/mcp-tool-cli.js"
+if [[ ! -f "$mcp_profile_cli" ]]; then
+  fail "MCP tool profile checker is missing from the installed package"
+elif mcp_profile_json=$(node "$mcp_profile_cli" status --project "$PWD" --json 2>/dev/null); then
+  if mcp_profile_summary=$(node - "$mcp_profile_json" <<'NODE'
+try {
+  const value = JSON.parse(process.argv[2]);
+  if (value.schema_version !== 1 || !["full", "read-only", "custom"].includes(value.mode)
+      || !/^[a-f0-9]{64}$/.test(value.profile_digest) || !Array.isArray(value.allowed_tools)) process.exit(1);
+  process.stdout.write(`${value.mode}\t${value.profile_digest}`);
+} catch { process.exit(1); }
+NODE
+  ); then
+    pass "MCP tool profile $(printf '%s' "$mcp_profile_summary" | cut -f1) ($(printf '%s' "$mcp_profile_summary" | cut -f2))"
+  else
+    fail "MCP tool profile status returned invalid data"
+  fi
+else
+  fail "MCP tool profile is invalid (check .ai/mcp-tools.json and CAIRN_MCP_TOOL_PROFILE)"
+fi
+
+# 13. Context-pack objects and project pointers are verified even when MCP pack
+# retrieval is disabled. The feature gate controls reads, not integrity checks.
+pack_cli="$CAIRN_ROOT/mcp-memory-server/dist/context-pack-cli.js"
+pack_base="${CAIRN_PACK_BASE_DIR:-$HOME/.cairnkeep/packs}"
+pack_base="${pack_base/#\~/$HOME}"
+if [[ ! -e "$pack_base" ]]; then
+  skip "context packs (not installed)"
+elif [[ ! -f "$pack_cli" ]]; then
+  fail "context-pack checker is missing from the installed package"
+elif pack_json=$(node "$pack_cli" doctor --json 2>/dev/null) && node -e 'const v=JSON.parse(process.argv[1]); if(v.ok!==true)process.exit(1)' "$pack_json"; then
+  pack_counts=$(node -e 'const v=JSON.parse(process.argv[1]); process.stdout.write(`${v.objects} object(s), ${v.projects} project pointer(s)`)' "$pack_json")
+  pass "context packs healthy ($pack_counts)"
+else
+  fail "context-pack objects or project pointers failed integrity checks"
+fi
+
 echo
 if [[ "$fails" -gt 0 ]]; then
   echo "cairn doctor: $fails configured dependency check(s) failed."

package/scripts/test-cli-dispatch.sh

@@ -16,6 +16,8 @@ tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 "$cairn" help | grep -q "cairn notes" || fail "help missing notes"
 "$cairn" help | grep -q "cairn artifact <list|show|delete|prune>" || fail "help missing artifact"
 "$cairn" help | grep -q "cairn capabilities <list|status|enable|disable|reset|logging>" || fail "help missing capabilities"
+"$cairn" help | grep -q "cairn mcp-tools <list|status|set|reset>" || fail "help missing mcp-tools"
+"$cairn" help | grep -q "cairn pack <init|lock|validate|install|list|show|remove|enable|disable|update|skills|approve-skill|revoke-skill>" || fail "help missing pack"
 "$cairn" help | grep -q "cairn graph <build|query|status|diff|explain|path>" || fail "help missing graph"
 "$cairn" sync --help >/dev/null 2>&1 || fail "cairn sync dispatch"
 "$cairn" sync-pi --help >/dev/null 2>&1 || fail "cairn sync-pi dispatch"
@@ -23,6 +25,10 @@ tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 env -u CAIRN_NOTE_DISTILLATION "$cairn" notes --help >/dev/null 2>&1 || fail "cairn notes dispatch"
 "$cairn" artifact --help | grep -q "cairn artifact list" || fail "cairn artifact dispatch"
 "$cairn" capabilities --help >"$tmp/capabilities-help" 2>/dev/null || fail "cairn capabilities dispatch"
+"$cairn" mcp-tools list --json >"$tmp/mcp-tools.json" || fail "cairn mcp-tools dispatch"
+CAIRN_PACK_BASE_DIR="$tmp/pack-store" "$cairn" pack list --json >"$tmp/packs.json" || fail "cairn pack dispatch"
+node -e 'const v=require(process.argv[1]);if(v.schema_version!==1||!Array.isArray(v.tools))process.exit(1)' "$tmp/mcp-tools.json" || fail "mcp-tools JSON contract"
+node -e 'const v=require(process.argv[1]);if(v.schema_version!==1||!Array.isArray(v.packs))process.exit(1)' "$tmp/packs.json" || fail "pack JSON contract"
 "$cairn" graph --help | grep -q "cairn graph explain <symbol>" || fail "cairn graph dispatch"
 grep -qxF 'MCP capability changes require a memory-server restart. Operating capability' "$tmp/capabilities-help" || fail "capability help missing exact restart wording"
 grep -qxF 'changes apply on the next invocation.' "$tmp/capabilities-help" || fail "capability help missing exact invocation wording"

package/scripts/test-completion.sh

@@ -43,6 +43,11 @@ for shell in bash zsh fish; do
   for skill_flag in --candidate --exploration-task-set --confirmation-task-set --evaluation --application --confirm; do
     grep -q -- "$skill_flag\|-l ${skill_flag#--}" "$tmp/$shell"
   done
+  grep -q 'mcp-tools' "$tmp/$shell"
+  grep -q 'full.*read-only.*custom\|full read-only custom' "$tmp/$shell"
+  grep -q 'pack' "$tmp/$shell"
+  grep -q 'init.*lock.*validate.*install.*list.*show.*remove.*enable.*disable.*update.*skills.*approve-skill.*revoke-skill\|init lock validate install list show remove enable disable update skills approve-skill revoke-skill' "$tmp/$shell"
+  grep -q -- '--purge-packs\|-l purge-packs' "$tmp/$shell"
 done
 
 "$ROOT/bin/cairn" help >"$tmp/root-help"

package/scripts/test-learning-docs.sh

@@ -15,13 +15,14 @@ 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
+  course-04-operation course-05-evidence course-06-governance course-07-evaluation \
+  course-08-graph course-09-skill course-10-trust-context; do
   grep -qF "\`$checkpoint\`" "$coverage"
 done
 
 ready=0
 brief=0
-for number in $(seq -w 0 19); do
+for number in $(seq -w 0 21); 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
@@ -52,7 +53,7 @@ grep -qF '`cairn sync-kimi --apply`' "$graph_lesson"
 grep -qF '`cairn sync-pi --apply`' "$graph_lesson"
 grep -qF '`graphify-out/`' "$graph_lesson"
 
-[[ $ready -eq 4 && $brief -eq 16 ]] || {
+[[ $ready -eq 7 && $brief -eq 15 ]] || {
   echo "unexpected learning status totals: ready=$ready brief=$brief" >&2
   exit 1
 }

package/scripts/test-package-install.sh

@@ -86,6 +86,23 @@ do
   [[ -f "$installed_root/$required" ]] || fail "npm tarball omitted $required"
 done
 
+for required in \
+  schemas/context-pack.schema.json \
+  mcp-memory-server/dist/mcp-tool-catalog.js \
+  mcp-memory-server/dist/mcp-tool-profile.js \
+  mcp-memory-server/dist/mcp-tool-cli.js \
+  mcp-memory-server/dist/context-pack.js \
+  mcp-memory-server/dist/context-pack-cli.js \
+  docs/mcp-tool-profiles.md \
+  docs/context-packs.md
+do
+  [[ -f "$installed_root/$required" ]] || fail "npm tarball omitted $required"
+done
+CAIRN_PACK_BASE_DIR="$tmp/installed-packs" cairn pack list --json >"$tmp/installed-pack-list.json" || \
+  fail "installed package pack CLI failed"
+cairn mcp-tools list --json >"$tmp/installed-mcp-tools.json" || \
+  fail "installed package mcp-tools CLI failed"
+
 for required in \
   schemas/skill-adapter.schema.json \
   schemas/skill-proposal-protocol.schema.json \

package/scripts/test-uninstall.sh

@@ -303,6 +303,27 @@ check "memory store restored"     "$(cat "$SB/home/.cairnkeep/db" 2>/dev/null)"
 check "note store restored exactly" "$(sha256sum "$SB/home/.cairnkeep/notes/projects/example/hindsight/failure.md" | cut -d' ' -f1)" "$purge_note_before"
 check "typed and journal state restored exactly" "$(tree_hash "$SB/home/.cairnkeep")" "$purge_store_before"
 
+# --- context-pack data requires its own explicit purge consent ---------------
+PACK_HOME="$SB/pack-home"
+PACK_STORE="$PACK_HOME/.cairnkeep/packs"
+mkdir -p "$PACK_STORE/objects/example" "$PACK_HOME/.cairnkeep/memory"
+printf 'immutable pack\n' >"$PACK_STORE/objects/example/marker"
+printf 'memory\n' >"$PACK_HOME/.cairnkeep/memory/marker"
+pack_output=$(HOME="$PACK_HOME" XDG_CONFIG_HOME="$PACK_HOME/.config" \
+  CAIRN_AGENTFS_BASE_DIR="$PACK_HOME/.cairnkeep" CAIRN_PACK_BASE_DIR="$PACK_STORE" \
+  "$ROOT_DIR/scripts/uninstall.sh" --yes --live-root "$SB/pack-live" --pi-live-root "$SB/pack-pi" --kimi-live-root "$SB/pack-kimi" 2>&1)
+check "ordinary uninstall reports retained context packs" "$(grep -q 'kept context packs' <<<"$pack_output" && echo yes || echo no)" "yes"
+check "ordinary uninstall retains context packs" "$([[ -f "$PACK_STORE/objects/example/marker" ]] && echo yes || echo no)" "yes"
+HOME="$PACK_HOME" XDG_CONFIG_HOME="$PACK_HOME/.config" \
+  CAIRN_AGENTFS_BASE_DIR="$PACK_HOME/.cairnkeep" CAIRN_PACK_BASE_DIR="$PACK_STORE" \
+  "$ROOT_DIR/scripts/uninstall.sh" --yes --purge-memory --live-root "$SB/pack-live" --pi-live-root "$SB/pack-pi" --kimi-live-root "$SB/pack-kimi" >/dev/null 2>&1
+check "memory purge retains context packs" "$([[ -f "$PACK_STORE/objects/example/marker" ]] && echo yes || echo no)" "yes"
+check "memory purge removes non-pack memory" "$([[ -e "$PACK_HOME/.cairnkeep/memory" ]] && echo no || echo yes)" "yes"
+HOME="$PACK_HOME" XDG_CONFIG_HOME="$PACK_HOME/.config" \
+  CAIRN_AGENTFS_BASE_DIR="$PACK_HOME/.cairnkeep" CAIRN_PACK_BASE_DIR="$PACK_STORE" \
+  "$ROOT_DIR/scripts/uninstall.sh" --yes --purge-packs --live-root "$SB/pack-live" --pi-live-root "$SB/pack-pi" --kimi-live-root "$SB/pack-kimi" >/dev/null 2>&1
+check "explicit pack purge removes context packs" "$([[ -e "$PACK_STORE" ]] && echo no || echo yes)" "yes"
+
 echo
 if [[ "$fails" -gt 0 ]]; then echo "test-uninstall: $fails check(s) failed."; exit 1; fi
 echo "test-uninstall: OK"

package/scripts/uninstall.sh

@@ -25,9 +25,12 @@ PI_LIVE_ROOT="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
 KIMI_LIVE_ROOT="${KIMI_CODE_HOME:-$HOME/.kimi-code}"
 STORE_DIR="${CAIRN_AGENTFS_BASE_DIR:-$HOME/.cairnkeep}"
 STORE_DIR="${STORE_DIR/#\~/$HOME}"
+PACK_DIR="${CAIRN_PACK_BASE_DIR:-$HOME/.cairnkeep/packs}"
+PACK_DIR="${PACK_DIR/#\~/$HOME}"
 DRY_RUN=0
 ASSUME_YES=0
 PURGE_MEMORY=0
+PURGE_PACKS=0
 PROJECTS=()
 
 # The hooks cairnkeep registers (basename is the settings.json match token).
@@ -49,7 +52,7 @@ PROJECT_AI_FILES=(
 
 usage() {
   cat <<'EOF'
-Usage: uninstall.sh [--dry-run] [--yes] [--purge-memory] [--live-root PATH]
+Usage: uninstall.sh [--dry-run] [--yes] [--purge-memory] [--purge-packs] [--live-root PATH]
                     [--pi-live-root PATH] [--kimi-live-root PATH] [PROJECT ...]
 
 Reverse cairnkeep's install. Everything removed/edited is backed up into
@@ -59,6 +62,8 @@ $HOME/.cairnkeep-uninstall-<ts>/ with a revert.sh before any change.
   --yes            Do not prompt for confirmation.
   --purge-memory   Also remove the global memory store and .agentfs/ memory and
                    trajectories in each PROJECT. Backed up first; off by default.
+  --purge-packs    Also remove immutable context-pack objects and project
+                   pointers. Backed up first; off by default.
   --live-root PATH Claude root to clean (default: $CLAUDE_CONFIG_DIR or ~/.claude).
   --pi-live-root PATH Pi agent root to clean (default: $PI_CODING_AGENT_DIR or ~/.pi/agent).
   --kimi-live-root PATH Kimi Code root to clean (default: $KIMI_CODE_HOME or ~/.kimi-code).
@@ -73,6 +78,7 @@ while [[ $# -gt 0 ]]; do
     --dry-run) DRY_RUN=1; shift ;;
     --yes) ASSUME_YES=1; shift ;;
     --purge-memory) PURGE_MEMORY=1; shift ;;
+    --purge-packs) PURGE_PACKS=1; shift ;;
     --live-root) LIVE_ROOT="$2"; shift 2 ;;
     --pi-live-root) PI_LIVE_ROOT="$2"; shift 2 ;;
     --kimi-live-root) KIMI_LIVE_ROOT="$2"; shift 2 ;;
@@ -142,6 +148,7 @@ echo "  live root:    $LIVE_ROOT"
 echo "  Pi live root: $PI_LIVE_ROOT"
 echo "  Kimi root:    $KIMI_LIVE_ROOT"
 echo "  memory store: $STORE_DIR ($([[ $PURGE_MEMORY -eq 1 ]] && echo 'WILL be purged' || echo 'kept'))"
+echo "  context packs: $PACK_DIR ($([[ $PURGE_PACKS -eq 1 ]] && echo 'WILL be purged' || echo 'kept'))"
 [[ ${#PROJECTS[@]} -gt 0 ]] && echo "  projects:     ${PROJECTS[*]}"
 
 if [[ $DRY_RUN -eq 0 && $ASSUME_YES -eq 0 ]]; then
@@ -231,6 +238,24 @@ fi
 if [[ $PURGE_MEMORY -eq 1 ]]; then
   echo "Memory store:"
   remove_path "$STORE_DIR"
+  if [[ $PURGE_PACKS -eq 0 && "$PACK_DIR" == "$STORE_DIR"/* && $DRY_RUN -eq 0 ]]; then
+    pack_backup="$BACKUP_DIR/files/${PACK_DIR#/}"
+    if [[ -d "$pack_backup" ]]; then
+      mkdir -p "$(dirname "$PACK_DIR")"
+      cp -a "$pack_backup" "$PACK_DIR"
+      echo "  retained context packs: $PACK_DIR"
+    fi
+  fi
+fi
+
+if [[ $PURGE_MEMORY -eq 0 && $PURGE_PACKS -eq 0 && -d "$PACK_DIR" ]]; then
+  echo "Context packs:"
+  echo "  kept context packs: $PACK_DIR (use --purge-packs to remove)"
+fi
+
+if [[ $PURGE_PACKS -eq 1 && ! ( $PURGE_MEMORY -eq 1 && "$PACK_DIR" == "$STORE_DIR"/* ) ]]; then
+  echo "Context packs:"
+  remove_path "$PACK_DIR"
 fi
 
 # 6. Per-project bootstrap scaffold.

package/templates/env.example.template

@@ -17,6 +17,17 @@
 # scopes default to ~/.cairnkeep; project scope uses <server-cwd>/.agentfs/.
 # CAIRN_AGENTFS_BASE_DIR=~/.cairnkeep
 #
+# Least-authority MCP profiles only restrict currently available tools. Project
+# state is managed with `cairn mcp-tools`; these are process overrides.
+# CAIRN_MCP_TOOL_PROFILE=read-only
+# CAIRN_MCP_ALLOWED_TOOLS=memory_read,memory_search
+#
+# Immutable context packs are local and OFF by default. HTTP access requires
+# the separate pack HTTP flag plus the existing authenticated HTTP settings.
+# CAIRN_CONTEXT_PACKS=1
+# CAIRN_CONTEXT_PACK_HTTP=1
+# CAIRN_PACK_BASE_DIR=~/.cairnkeep/packs
+#
 # Typed metadata, filters, logical note address spaces, and memory_import are
 # OFF by default. Restart the memory server after changing this construction-
 # time tool-schema flag. No model, API key, or network endpoint is required.