@cairnkeep/cli 1.0.2 → 1.0.4

package/README.md

@@ -10,7 +10,7 @@ across sessions, projects, and harnesses (Claude Code, OpenCode, …).
 ## Status
 
 Shipped: the memory server, the `cairn` CLI (`bootstrap`, `memory-server`, `sync`,
-`doctor`, `memory`, `audit-timer`) installable via `npm i -g @cairnkeep/cli`, and the
+`doctor`, `memory`, `audit-timer`, `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`,
@@ -28,7 +28,8 @@ cairnkeep-org sibling project.
 - **`bin/cairn`** — the CLI. `cairn bootstrap [path]` scaffolds a project's
   `.ai/` launchers + env; `cairn doctor` health-checks the configured pieces;
   `cairn memory export|import` relocates the durable store between machines;
-  `cairn audit-timer` installs the scheduled memory+wiki audit.
+  `cairn audit-timer` installs the scheduled memory+wiki audit; `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.

package/bin/cairn

@@ -22,6 +22,9 @@ case "$cmd" in
   doctor)
     exec "$CAIRN_ROOT/scripts/doctor.sh" "$@"
     ;;
+  uninstall)
+    exec "$CAIRN_ROOT/scripts/uninstall.sh" "$@"
+    ;;
   memory)
     exec "$CAIRN_ROOT/scripts/memory-store.sh" "$@"
     ;;
@@ -66,6 +69,12 @@ Usage:
   cairn audit-timer [--on-calendar SPEC] [--para-root PATH] [--render-only DIR]
                            Install (opt-in) a systemd user timer that runs the
                            memory+wiki audit on a schedule; prints a cron alternative.
+  cairn uninstall [--dry-run] [--yes] [--purge-memory] [--live-root DIR] [PROJECT ...]
+                           Reverse what cairnkeep installed/modified (operating
+                           layer, hook registrations, MCP registration, audit
+                           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 version            Print version
   cairn help               Show this help
 USAGE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",
@@ -32,6 +32,7 @@
     "zod": "^3.25.76"
   },
   "scripts": {
+    "prepack": "git ls-files -s | awk '$1==\"100755\"{print $4}' | xargs chmod 755",
     "test": "for test in scripts/test-*.sh; do \"$test\" || exit 1; done",
     "check:public": "scripts/verify-no-private-references.sh && scripts/verify-docs-parity.sh && npm test",
     "prepublishOnly": "npm run check:public && npm --prefix mcp-memory-server ci && npm --prefix mcp-memory-server test"

package/scripts/smoke-bash32.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# smoke-bash32.sh — run the sync scripts under macOS's default bash 3.2, in a
+# container, to prove they *execute* there (the static test-portable-sh.sh only
+# greps the source). This is the check that reproduces the real macOS failure:
+# bash 3.2 misparsing `declare -A` / missing `mapfile`.
+#
+# Uses docker or podman; SKIPS (exit 0) when neither exists, so it is safe to
+# run anywhere. Deliberately NOT named test-*.sh — `npm test` stays container-
+# free; run this by hand or via the CI shell-portability job.
+set -uo pipefail
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+RUNTIME=""
+for r in docker podman; do
+  command -v "$r" >/dev/null 2>&1 && { RUNTIME="$r"; break; }
+done
+if [[ -z "$RUNTIME" ]]; then
+  echo "smoke-bash32: SKIP (no docker/podman available)"
+  exit 0
+fi
+
+IMG="docker.io/library/bash:3.2"
+echo "smoke-bash32: $RUNTIME + $IMG"
+
+# --check exercises the failing code paths: the hook block in the claude script
+# (the declare -A site) and report_extra_live_assets in the opencode scripts
+# (the mapfile site), the latter only when the live root exists — so create it.
+SCRIPTS=(
+  scripts/sync-claude-assets.sh
+  scripts/sync-opencode-explore-assets.sh
+  scripts/sync-opencode-wiki-assets.sh
+)
+
+fails=0
+for s in "${SCRIPTS[@]}"; do
+  out=$("$RUNTIME" run --rm -v "$ROOT_DIR":/w:ro -w /w "$IMG" \
+    bash -c 'mkdir -p /tmp/live && exec bash "$0" --check --live-root /tmp/live' "$s" 2>&1) || true
+  # Exit status is ignored on purpose: --check returns non-zero for DRIFT
+  # (expected against an empty live root). We fail only on a bash-3.2 execution
+  # failure — an unbound-variable abort (declare -A misparse), a missing builtin
+  # (mapfile/readarray), or a syntax error — the exact 4-ism classes.
+  if grep -qiE 'unbound variable|command not found|mapfile:|readarray:|syntax error' <<<"$out"; then
+    echo "  [FAIL] $s"
+    tail -5 <<<"$out" | sed 's/^/      /'
+    fails=$((fails + 1))
+  else
+    echo "  [PASS] $s runs on bash 3.2"
+  fi
+done
+
+if [[ $fails -eq 0 ]]; then
+  echo "smoke-bash32: OK"
+  exit 0
+fi
+echo "smoke-bash32: $fails script(s) fail on bash 3.2"
+exit 1

package/scripts/smoke-mcp-boot.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# smoke-mcp-boot.sh — boot the memory server and run a real MCP `initialize`
+# handshake over stdio. Proves the built server actually starts and responds:
+# dist is present, deps resolve (esp. under a global install), and the MCP
+# transport works. This is the core product path, and nothing else tests it
+# after packaging/installation.
+#
+# Prefers `cairn memory-server` (a global install), else falls back to node on
+# the repo's dist build — so it works both post-install and from a clone.
+set -uo pipefail
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+if command -v cairn >/dev/null 2>&1; then
+  server=(cairn memory-server)
+elif [[ -f "$ROOT_DIR/mcp-memory-server/dist/index.js" ]]; then
+  server=(node "$ROOT_DIR/mcp-memory-server/dist/index.js")
+else
+  echo "smoke-mcp-boot: FAIL (no cairn on PATH and no dist build to run)"
+  exit 1
+fi
+
+req='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"ci","version":"0"}}}'
+
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+# HOME points at a throwaway dir so the server's default store (~/.cairnkeep)
+# lands there; `head -1` closes stdin after the first reply, so the server sees
+# EOF and exits cleanly.
+out=$(printf '%s\n' "$req" | HOME="$tmp" timeout 15 "${server[@]}" 2>/dev/null | head -1)
+
+if grep -q '"result"' <<<"$out" && grep -q '"tools"' <<<"$out"; then
+  echo "smoke-mcp-boot: OK (server booted, initialize returned tools capability)"
+  exit 0
+fi
+echo "smoke-mcp-boot: FAIL (no valid initialize response)"
+echo "  got: ${out:0:200}"
+exit 1

package/scripts/sync-claude-assets.sh

@@ -99,19 +99,27 @@ SETTINGS_FILE="$LIVE_ROOT/settings.json"
 # PreToolUse-style events; an optional trailing "@timeout" (seconds) threads
 # an explicit per-hook timeout into the settings.json registration entry so
 # Claude Code's kill budget is documented, not assumed (Pitfall 1).
-declare -A HOOK_EVENTS=(
-  ["memory-wakeup.sh"]="SessionStart"
-  ["memory-capture.sh"]="SessionEnd"
-  ["memory-recall.sh"]="PreToolUse:Edit|Write|MultiEdit"
-  ["context-explore-pretask.sh"]="UserPromptSubmit@25"
-)
+#
+# A case lookup, not `declare -A`: associative arrays are bash 4+, but macOS
+# still ships bash 3.2 as /bin/bash, where `declare -A HOOK_EVENTS=([k]=v)`
+# is parsed as a numeric-index assignment and dies under `set -u`
+# ("k: unbound variable"). Portable to 3.2; empty string = "not a hook".
+hook_event_for() {
+  case "$1" in
+    memory-wakeup.sh)           echo "SessionStart" ;;
+    memory-capture.sh)          echo "SessionEnd" ;;
+    memory-recall.sh)           echo "PreToolUse:Edit|Write|MultiEdit" ;;
+    context-explore-pretask.sh) echo "UserPromptSubmit@25" ;;
+    *)                          echo "" ;;
+  esac
+}
 
 for hook_src in "$CLAUDE_SOURCE"/hooks/*.sh; do
   [[ -f "$hook_src" ]] || continue
   hook_name="$(basename "$hook_src")"
   hook_dst="$HOOK_LIVE_DIR/$hook_name"
   hook_cmd="bash \"$hook_dst\""
-  event_spec="${HOOK_EVENTS[$hook_name]:-}"
+  event_spec="$(hook_event_for "$hook_name")"
   if [[ -z "$event_spec" ]]; then
     # Unknown hook: still render it, but do not auto-register (avoid stomping settings).
     if [[ "$MODE" == "apply" ]]; then

package/scripts/sync-opencode-explore-assets.sh

@@ -98,7 +98,11 @@ report_extra_live_assets() {
     return
   fi
 
-  mapfile -t extras < <(collect_extra_live_assets "$LIVE_ROOT")
+  # read loop, not `mapfile`: mapfile is bash 4+, absent from macOS bash 3.2.
+  local line
+  while IFS= read -r line; do
+    extras+=("$line")
+  done < <(collect_extra_live_assets "$LIVE_ROOT")
   if ((${#extras[@]} == 0)); then
     return
   fi

package/scripts/sync-opencode-wiki-assets.sh

@@ -133,7 +133,11 @@ report_extra_live_assets() {
     return
   fi
 
-  mapfile -t extras < <(collect_extra_live_assets "$LIVE_ROOT")
+  # read loop, not `mapfile`: mapfile is bash 4+, absent from macOS bash 3.2.
+  local line
+  while IFS= read -r line; do
+    extras+=("$line")
+  done < <(collect_extra_live_assets "$LIVE_ROOT")
   if ((${#extras[@]} == 0)); then
     return
   fi

package/scripts/test-portable-sh.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Guard: shipped shell scripts must run on macOS's default bash 3.2.
+#
+# macOS still ships bash 3.2 (2007) as /bin/bash, and `#!/usr/bin/env bash`
+# picks it up unless the user installed a newer bash on PATH. bash-4-only
+# features (associative arrays via `declare -A`, `mapfile`/`readarray`, the
+# `${var^^}`/`${var,,}` case operators) blow up there — e.g. `declare -A`
+# is misparsed as a numeric-index assignment and dies under `set -u` with a
+# bogus "unbound variable". CI runs on bash 5, so nothing else catches this.
+#
+# Grep-based, so it needs no bash 3.2 to run. Ceiling: it flags the common
+# 4-isms by pattern, not every one; the fresh-system smoke test should still
+# exercise the install under an actual bash 3.2 (docker run bash:3.2 ...).
+set -euo pipefail
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+# One ERE, alternated: assoc arrays | mapfile/readarray | ${v^^}/${v,,}.
+BASH4_PATTERN='declare[[:space:]]+-A|(mapfile|readarray)[[:space:]]|\$\{[A-Za-z_][A-Za-z0-9_]*(\^\^|,,)'
+
+failed=0
+while IFS= read -r f; do
+  [[ -n "$f" ]] || continue
+  # grep -n, then drop full-line comments (`^NN:  # ...`) so the pattern
+  # only trips on real usage, not prose that names the feature.
+  matches=$(grep -nE "$BASH4_PATTERN" "$f" | grep -vE '^[0-9]+:[[:space:]]*#' || true)
+  if [[ -n "$matches" ]]; then
+    if [[ $failed -eq 0 ]]; then
+      echo "FAIL: bash-4-only feature(s) in scripts that must run on macOS bash 3.2:" >&2
+      failed=1
+    fi
+    echo "  ${f#"$ROOT_DIR"/}" >&2
+    sed 's/^/    /' <<<"$matches" >&2
+  fi
+done < <(find "$ROOT_DIR/scripts" "$ROOT_DIR/bin" -type f \( -name '*.sh' -o -name '*.template' \) | sort)
+
+if [[ $failed -ne 0 ]]; then
+  echo "Rewrite portably (case lookup for maps, while-read for mapfile)." >&2
+  exit 1
+fi
+
+echo "test-portable-sh: OK (no bash-4-only features in shipped scripts)"

package/scripts/test-shipped-perms.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Regression guard for the 744-perms packaging bug. A root-owned `sudo npm i -g`
+# makes root the file owner, so a non-root user can only run cairn if "other"
+# has the execute bit. A publisher umask can strip it at pack time; the
+# `prepack` script re-applies git's tracked executable bit. This verifies
+# prepack heals a umask-mangled entrypoint back to 755 (world-executable).
+#
+# Deliberately does NOT run `npm pack`: this test runs inside `npm test`, which
+# runs inside `npm publish`'s prepublishOnly, and nesting npm that deep is not
+# portable. Running the prepack command directly tests the same guarantee.
+set -euo pipefail
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$ROOT"
+fail() { echo "FAIL: $1" >&2; exit 1; }
+
+prepack=$(node -e 'process.stdout.write(require("./package.json").scripts.prepack||"")')
+[[ -n "$prepack" ]] || fail "package.json has no prepack script (perms fix missing)"
+
+entry=bin/cairn
+trap 'chmod 755 "$entry" 2>/dev/null || true' EXIT
+chmod 744 "$entry"                                              # simulate a stripping umask
+sh -c "$prepack"                                               # run the real prepack command
+mode=$(stat -c '%a' "$entry" 2>/dev/null || stat -f '%Lp' "$entry")  # GNU || BSD/macOS
+[[ "$mode" == "755" ]] || fail "prepack did not restore $entry to 755 (got $mode) -- 744 packaging bug"
+echo "OK: prepack restores shipped executables to 755"

package/scripts/test-uninstall.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# test-uninstall.sh — install/uninstall/revert cycle for uninstall.sh.
+#
+# uninstall.sh removes and edits real user state (assets, settings.json hooks,
+# MCP registration, the memory store), so it is tested in a fully isolated HOME
+# with stubbed `claude`/`systemctl` — it never touches the real machine. Asserts
+# the three properties that matter: dry-run changes nothing, uninstall removes
+# what cairnkeep owns, and revert.sh restores it exactly.
+set -uo pipefail
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+SB=$(mktemp -d)
+trap 'rm -rf "$SB"' EXIT
+
+fails=0
+ok()   { printf '  [PASS] %s\n' "$1"; }
+bad()  { printf '  [FAIL] %s\n' "$1"; fails=$((fails + 1)); }
+check() { if [[ "$2" == "$3" ]]; then ok "$1 ($2)"; else bad "$1 (got '$2', want '$3')"; fi; }
+
+# Isolated environment: fake HOME + stubbed system commands.
+mkdir -p "$SB/home" "$SB/bin"
+printf '#!/usr/bin/env bash\ntrue\n' >"$SB/bin/claude"
+printf '#!/usr/bin/env bash\ntrue\n' >"$SB/bin/systemctl"
+chmod +x "$SB/bin/"*
+export HOME="$SB/home" XDG_CONFIG_HOME="$SB/home/.config" PATH="$SB/bin:$PATH"
+LIVE="$SB/live"
+
+echo "test-uninstall"
+
+# --- install the operating layer -------------------------------------------
+"$ROOT_DIR/scripts/sync-claude-assets.sh" --apply --live-root "$LIVE" >/dev/null 2>&1
+md_installed=$(find "$LIVE" -type f -name '*.md' | wc -l | tr -d ' ')
+check "assets installed" "$([[ $md_installed -gt 0 ]] && echo yes || echo no)" "yes"
+check "hooks registered" "$(grep -c 'hooks/' "$LIVE/settings.json")" "4"
+cp "$LIVE/settings.json" "$SB/settings.before.json"
+
+# --- dry-run must change nothing -------------------------------------------
+"$ROOT_DIR/scripts/uninstall.sh" --dry-run --live-root "$LIVE" >/dev/null 2>&1
+check "dry-run leaves assets" "$(find "$LIVE" -type f -name '*.md' | wc -l | tr -d ' ')" "$md_installed"
+check "dry-run makes no bundle" "$(ls -d "$SB/home/.cairnkeep-uninstall-"* 2>/dev/null | wc -l | tr -d ' ')" "0"
+
+# --- real uninstall ---------------------------------------------------------
+"$ROOT_DIR/scripts/uninstall.sh" --yes --live-root "$LIVE" >/dev/null 2>&1
+check "assets removed" "$(find "$LIVE" -type f -name '*.md' | wc -l | tr -d ' ')" "0"
+check "hooks de-registered" "$(grep -c 'hooks/' "$LIVE/settings.json" 2>/dev/null || true)" "0"
+BK=$(ls -d "$SB/home/.cairnkeep-uninstall-"* 2>/dev/null | head -1)
+check "revert.sh generated" "$([[ -n "$BK" && -f "$BK/revert.sh" ]] && echo yes || echo no)" "yes"
+
+# --- revert restores everything --------------------------------------------
+bash "$BK/revert.sh" >/dev/null 2>&1
+check "assets restored" "$(find "$LIVE" -type f -name '*.md' | wc -l | tr -d ' ')" "$md_installed"
+check "settings.json identical" "$(cmp -s "$SB/settings.before.json" "$LIVE/settings.json" && echo yes || echo no)" "yes"
+
+# --- project scaffold + memory purge round-trip ----------------------------
+PROJ="$SB/proj"; mkdir -p "$PROJ"; git -C "$PROJ" init -q
+"$ROOT_DIR/scripts/bootstrap.sh" --untracked "$PROJ" >/dev/null 2>&1
+EXCL="$PROJ/.git/info/exclude"
+mkdir -p "$SB/home/.cairnkeep"; echo data >"$SB/home/.cairnkeep/db"
+"$ROOT_DIR/scripts/uninstall.sh" --yes --purge-memory --live-root "$SB/home/.claude" "$PROJ" >/dev/null 2>&1
+check "project .ai removed"      "$([[ -e "$PROJ/.ai" ]] && echo no || echo yes)" "yes"
+check "exclude lines stripped"   "$(grep -cE '\.ai/|\.planning/' "$EXCL" 2>/dev/null || true)" "0"
+check "memory store purged"      "$([[ -e "$SB/home/.cairnkeep" ]] && echo no || echo yes)" "yes"
+BK2=$(ls -dt "$SB/home/.cairnkeep-uninstall-"* 2>/dev/null | head -1)
+bash "$BK2/revert.sh" >/dev/null 2>&1
+check "project scaffold restored" "$([[ -d "$PROJ/.ai" ]] && echo yes || echo no)" "yes"
+check "memory store restored"     "$(cat "$SB/home/.cairnkeep/db" 2>/dev/null)" "data"
+
+echo
+if [[ "$fails" -gt 0 ]]; then echo "test-uninstall: $fails check(s) failed."; exit 1; fi
+echo "test-uninstall: OK"

package/scripts/uninstall.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# cairn uninstall — reverse what cairnkeep installed/modified on this machine.
+#
+# Backup-first and revertible: every file it removes or edits is copied into a
+# timestamped bundle ($HOME/.cairnkeep-uninstall-<ts>/) with a generated
+# revert.sh, so `bash <bundle>/revert.sh` puts the machine back. Removes only
+# things cairnkeep owns; the durable memory store ($HOME/.cairnkeep) is DATA and
+# is left alone unless you pass --purge-memory (then it too is backed up first).
+#
+# Undoes: the operating layer (`cairn sync --apply` — commands, agents,
+# templates, hooks + their settings.json registrations), the MCP registration
+# (`claude mcp add cairn-memory`), the opt-in audit timer, and — for any project
+# paths you pass — the `cairn bootstrap` scaffold. The npm package itself is
+# npm's to remove; the final step is printed, not run (it would delete this
+# script mid-execution).
+set -uo pipefail
+
+CAIRN_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+CLAUDE_SOURCE="$CAIRN_ROOT/claude"
+TPL="$CAIRN_ROOT/templates"
+
+LIVE_ROOT="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+STORE_DIR="${CAIRN_AGENTFS_BASE_DIR:-$HOME/.cairnkeep}"
+STORE_DIR="${STORE_DIR/#\~/$HOME}"
+DRY_RUN=0
+ASSUME_YES=0
+PURGE_MEMORY=0
+PROJECTS=()
+
+# The hooks cairnkeep registers (basename is the settings.json match token).
+HOOK_NAMES=(memory-wakeup.sh memory-capture.sh memory-recall.sh context-explore-pretask.sh)
+
+usage() {
+  cat <<'EOF'
+Usage: uninstall.sh [--dry-run] [--yes] [--purge-memory] [--live-root PATH] [PROJECT ...]
+
+Reverse cairnkeep's install. Everything removed/edited is backed up into
+$HOME/.cairnkeep-uninstall-<ts>/ with a revert.sh before any change.
+
+  --dry-run        Print what would happen; touch nothing.
+  --yes            Do not prompt for confirmation.
+  --purge-memory   Also remove the durable memory store ($HOME/.cairnkeep or
+                   $CAIRN_AGENTFS_BASE_DIR). Backed up first, but this is your
+                   accumulated memory — off by default.
+  --live-root PATH Claude root to clean (default: $CLAUDE_CONFIG_DIR or ~/.claude).
+  PROJECT ...      Also revert `cairn bootstrap` in these project dirs
+                   (.ai/, .planning/, and any .git/info/exclude entries).
+  -h, --help       Show this help.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    --yes) ASSUME_YES=1; shift ;;
+    --purge-memory) PURGE_MEMORY=1; shift ;;
+    --live-root) LIVE_ROOT="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    -*) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
+    *) PROJECTS+=("$1"); shift ;;
+  esac
+done
+
+# ---- backup bundle -----------------------------------------------------------
+# Timestamp comes from the runtime clock on the user's machine.
+BACKUP_DIR="$HOME/.cairnkeep-uninstall-$(date +%Y%m%d-%H%M%S)"
+MANIFEST="$BACKUP_DIR/manifest.tsv"
+NOTES="$BACKUP_DIR/NOTES.txt"
+
+ensure_bundle() {
+  [[ $DRY_RUN -eq 1 ]] && return 0
+  [[ -d "$BACKUP_DIR" ]] && return 0
+  mkdir -p "$BACKUP_DIR/files"
+  : >"$MANIFEST"
+  : >"$NOTES"
+}
+
+# back_up ABS — copy an existing path into the bundle, mirrored by absolute path,
+# and record it in the manifest so revert.sh can restore it. Safe on dirs (cp -a).
+back_up() {
+  local abs="$1" rel
+  [[ -e "$abs" ]] || return 0
+  ensure_bundle
+  [[ $DRY_RUN -eq 1 ]] && return 0
+  rel="files/${abs#/}"
+  mkdir -p "$BACKUP_DIR/$(dirname "$rel")"
+  cp -a "$abs" "$BACKUP_DIR/$rel"
+  printf '%s\t%s\n' "$abs" "$rel" >>"$MANIFEST"
+}
+
+# remove_path ABS — back up then delete (file or dir).
+remove_path() {
+  local abs="$1"
+  [[ -e "$abs" ]] || return 0
+  if [[ $DRY_RUN -eq 1 ]]; then echo "  would remove: $abs"; return 0; fi
+  back_up "$abs"
+  rm -rf "$abs"
+  echo "  removed: $abs"
+}
+
+note() { [[ $DRY_RUN -eq 1 ]] || { ensure_bundle; printf '%s\n' "$1" >>"$NOTES"; }; }
+
+# ---- what will be removed ----------------------------------------------------
+# Asset dests: derived exactly as sync-claude-assets.sh installs them, so the two
+# never drift. claude/**/*.md -> <live>/..., security|wiki templates, hooks.
+asset_dests() {
+  local rel tpl h
+  while IFS= read -r rel; do echo "$LIVE_ROOT/$rel"; done \
+    < <(cd "$CLAUDE_SOURCE" 2>/dev/null && find . -type f -name '*.md' | sed 's|^\./||' | sort)
+  for tpl in "$TPL"/security-*.template "$TPL"/wiki-*.template; do
+    [[ -f "$tpl" ]] && echo "$LIVE_ROOT/templates/$(basename "$tpl")"
+  done
+  for h in "$CLAUDE_SOURCE"/hooks/*.sh; do
+    [[ -f "$h" ]] && echo "$LIVE_ROOT/hooks/$(basename "$h")"
+  done
+}
+
+echo "cairn uninstall"
+[[ $DRY_RUN -eq 1 ]] && echo "(dry run — nothing will change)"
+echo "  live root:    $LIVE_ROOT"
+echo "  memory store: $STORE_DIR ($([[ $PURGE_MEMORY -eq 1 ]] && echo 'WILL be purged' || echo 'kept'))"
+[[ ${#PROJECTS[@]} -gt 0 ]] && echo "  projects:     ${PROJECTS[*]}"
+
+if [[ $DRY_RUN -eq 0 && $ASSUME_YES -eq 0 ]]; then
+  printf 'Proceed? [y/N] '
+  read -r ans
+  [[ "$ans" == [yY] || "$ans" == [yY][eE][sS] ]] || { echo "aborted."; exit 0; }
+fi
+
+# 1. Operating-layer asset files.
+echo "Operating layer (assets):"
+while IFS= read -r dst; do remove_path "$dst"; done < <(asset_dests)
+
+# 2. settings.json hook registrations (back up whole file, then de-register).
+SETTINGS="$LIVE_ROOT/settings.json"
+if [[ -f "$SETTINGS" ]]; then
+  echo "Hook registrations (settings.json):"
+  if [[ $DRY_RUN -eq 1 ]]; then
+    echo "  would de-register: ${HOOK_NAMES[*]}"
+  elif command -v node >/dev/null 2>&1; then
+    back_up "$SETTINGS"
+    node -e '
+const fs = require("fs");
+const [p, ...names] = process.argv.slice(1);
+let s; try { s = JSON.parse(fs.readFileSync(p, "utf8")); }
+catch (e) { console.error("  settings.json parse failed, leaving untouched"); process.exit(1); }
+if (!s.hooks) process.exit(0);
+let removed = 0;
+for (const ev of Object.keys(s.hooks)) {
+  if (!Array.isArray(s.hooks[ev])) continue;
+  s.hooks[ev] = s.hooks[ev].filter((entry) => {
+    if (!Array.isArray(entry.hooks)) return true;
+    const before = entry.hooks.length;
+    entry.hooks = entry.hooks.filter((h) =>
+      !(typeof h.command === "string" && names.some((n) => h.command.includes(n))));
+    removed += before - entry.hooks.length;
+    return entry.hooks.length > 0;
+  });
+  if (s.hooks[ev].length === 0) delete s.hooks[ev];
+}
+if (Object.keys(s.hooks).length === 0) delete s.hooks;
+fs.writeFileSync(p, JSON.stringify(s, null, 2) + "\n");
+console.log("  de-registered " + removed + " hook(s)");
+' "$SETTINGS" "${HOOK_NAMES[@]}" || echo "  (settings.json left untouched)"
+  else
+    echo "  node not found — cannot edit settings.json; remove hook entries manually."
+  fi
+fi
+
+# 3. MCP registration (best-effort; a command, not a file — noted for revert).
+echo "MCP registration (cairn-memory):"
+if command -v claude >/dev/null 2>&1; then
+  if [[ $DRY_RUN -eq 1 ]]; then
+    echo "  would run: claude mcp remove cairn-memory -s user"
+  else
+    claude mcp remove cairn-memory -s user 2>/dev/null && echo "  removed cairn-memory" \
+      || echo "  cairn-memory not registered (or already gone)"
+    note "Re-add MCP server: claude mcp add cairn-memory -s user -- cairn memory-server"
+  fi
+else
+  echo "  claude CLI not found — if registered, run: claude mcp remove cairn-memory -s user"
+fi
+
+# 4. Audit timer (opt-in; disable + remove unit files).
+UNIT_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
+if [[ -f "$UNIT_DIR/memory-wiki-audit.timer" || -f "$UNIT_DIR/memory-wiki-audit.service" ]]; then
+  echo "Audit timer:"
+  if [[ $DRY_RUN -eq 1 ]]; then
+    echo "  would disable + remove memory-wiki-audit.{timer,service}"
+  else
+    command -v systemctl >/dev/null 2>&1 && systemctl --user disable --now memory-wiki-audit.timer 2>/dev/null || true
+    remove_path "$UNIT_DIR/memory-wiki-audit.timer"
+    remove_path "$UNIT_DIR/memory-wiki-audit.service"
+    command -v systemctl >/dev/null 2>&1 && systemctl --user daemon-reload 2>/dev/null || true
+    note "Re-enable timer: cairn audit-timer"
+  fi
+fi
+
+# 5. Memory store (DATA — only with --purge-memory).
+if [[ $PURGE_MEMORY -eq 1 ]]; then
+  echo "Memory store:"
+  remove_path "$STORE_DIR"
+fi
+
+# 6. Per-project bootstrap scaffold.
+for proj in "${PROJECTS[@]:-}"; do
+  [[ -n "$proj" && -d "$proj" ]] || continue
+  proj=$(cd "$proj" && pwd)
+  echo "Project scaffold: $proj"
+  remove_path "$proj/.ai"
+  remove_path "$proj/.planning"
+  # Strip the .git/info/exclude lines contributor-mode bootstrap added.
+  if excl=$(cd "$proj" && git rev-parse --git-path info/exclude 2>/dev/null); then
+    [[ "$excl" == /* ]] || excl="$proj/$excl"
+    prefix=$(cd "$proj" && git rev-parse --show-prefix 2>/dev/null)
+    if [[ -f "$excl" ]] && grep -qxF "/${prefix}.ai/" "$excl" 2>/dev/null; then
+      if [[ $DRY_RUN -eq 1 ]]; then
+        echo "  would strip .ai/ + .planning/ from ${excl}"
+      else
+        back_up "$excl"
+        grep -vxF -e "/${prefix}.ai/" -e "/${prefix}.planning/" "$excl" >"$excl.tmp" && mv "$excl.tmp" "$excl"
+        echo "  stripped exclude entries from ${excl}"
+      fi
+    fi
+  fi
+done
+
+# ---- generate revert.sh ------------------------------------------------------
+if [[ $DRY_RUN -eq 0 && -f "$MANIFEST" ]]; then
+  cat >"$BACKUP_DIR/revert.sh" <<'REVERT'
+#!/usr/bin/env bash
+# Restore everything cairn uninstall removed/edited from this bundle.
+set -euo pipefail
+here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+while IFS=$'\t' read -r abs rel; do
+  [[ -n "$abs" ]] || continue
+  mkdir -p "$(dirname "$abs")"
+  rm -rf "$abs"
+  cp -a "$here/$rel" "$abs"
+  echo "restored: $abs"
+done <"$here/manifest.tsv"
+echo
+echo "Files restored. Command-based steps (if they applied) — see NOTES.txt:"
+[[ -f "$here/NOTES.txt" ]] && cat "$here/NOTES.txt"
+REVERT
+  chmod +x "$BACKUP_DIR/revert.sh"
+fi
+
+echo
+if [[ $DRY_RUN -eq 1 ]]; then
+  echo "Dry run complete — no changes made."
+else
+  echo "Done. Backup + revert.sh: $BACKUP_DIR"
+  echo "  revert with: bash \"$BACKUP_DIR/revert.sh\""
+fi
+echo "Final step (npm's to do, not this script's): npm uninstall -g @cairnkeep/cli"