@cairnkeep/cli 2.15.4 → 2.17.0

package/schemas/context-usage-receipt.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/context-usage-receipt.schema.json",
+  "title": "Cairnkeep context usage receipt v1",
+  "description": "A privacy-minimal link from existing work evidence to a retrieved result. Receipts contain identifiers, digests, outcome labels and a timestamp; never retrieved content, queries, prompts or model output.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "link_id",
+    "evidence_id",
+    "kind",
+    "created_at",
+    "receipt_id",
+    "task_digest",
+    "result_digest",
+    "outcome"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "link_id": {
+      "description": "Equal to receipt_id for context usage links.",
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "evidence_id": {
+      "type": "string",
+      "pattern": "^wev_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "kind": { "const": "context_usage" },
+    "created_at": { "type": "string", "format": "date-time" },
+    "receipt_id": {
+      "description": "SHA-256 of canonical evidence_id, task_digest and result_digest fields. The outcome is deliberately excluded so a changed outcome is a conflict, not a second receipt.",
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "task_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "result_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "outcome": { "enum": ["used", "unused", "unknown"] }
+  }
+}

package/schemas/memory-proposal.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/memory-proposal.schema.json",
+  "title": "Cairnkeep review-gated memory proposal",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "created_at", "project_root", "scope", "source", "extraction", "candidates", "digest"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "created_at": { "type": "string", "format": "date-time" },
+    "project_root": { "type": "string", "minLength": 1 },
+    "scope": { "type": "string", "pattern": "^(project|[a-z0-9][a-z0-9-]*)$" },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "session_id", "digest"],
+      "properties": {
+        "kind": { "const": "trajectory" },
+        "session_id": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "digest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "extraction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["model"],
+      "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 256 } }
+    },
+    "candidates": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 128,
+      "items": { "$ref": "#/$defs/candidate" }
+    },
+    "digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "candidate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "value", "operation", "base_hash", "value_hash"],
+      "$comment": "Runtime verification also requires value_hash to equal SHA-256(value), noop base_hash to equal value_hash, and update base_hash to differ from value_hash.",
+      "properties": {
+        "key": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "value": { "type": "string", "maxLength": 65536 },
+        "category": { "type": "string", "maxLength": 64 },
+        "importance": { "type": "number", "minimum": 0, "maximum": 1 },
+        "operation": { "enum": ["create", "update", "noop"] },
+        "base_hash": { "oneOf": [{ "$ref": "#/$defs/digest" }, { "type": "null" }] },
+        "value_hash": { "$ref": "#/$defs/digest" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "operation": { "const": "create" } }, "required": ["operation"] },
+          "then": { "properties": { "base_hash": { "type": "null" } } }
+        },
+        {
+          "if": { "properties": { "operation": { "enum": ["update", "noop"] } }, "required": ["operation"] },
+          "then": { "properties": { "base_hash": { "$ref": "#/$defs/digest" } } }
+        }
+      ]
+    }
+  }
+}

package/schemas/retrieval-benchmark.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cairnkeep.dev/schemas/retrieval-benchmark.schema.json",
+  "title": "Cairnkeep retrieval benchmark suite",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "description", "packs", "cases"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "description": { "type": "string", "minLength": 1 },
+    "packs": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "version", "title", "enabled", "files"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+          "version": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$" },
+          "title": { "type": "string", "minLength": 1 },
+          "enabled": { "type": "boolean" },
+          "files": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 1024,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["path", "kind", "title", "description", "keywords", "content"],
+              "properties": {
+                "path": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$" },
+                "kind": { "enum": ["document", "skill"] },
+                "title": { "type": "string", "minLength": 1 },
+                "description": { "type": "string" },
+                "keywords": { "type": "array", "items": { "type": "string" } },
+                "content": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "cases": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 1024,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "query", "relevant", "forbidden", "limit"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+          "query": { "type": "string", "minLength": 1 },
+          "relevant": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+          "forbidden": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+          "limit": { "type": "integer", "minimum": 1, "maximum": 100 }
+        }
+      }
+    }
+  }
+}

package/scripts/cairn-cli.mjs

@@ -9,6 +9,7 @@ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const NODE_COMMANDS = new Map([
   ["memory-server", "index.js"],
   ["trajectory", "trajectory-cli.js"],
+  ["proposals", "memory-proposal-cli.js"],
   ["artifact", "artifact-cli.js"],
   ["capabilities", "capability-cli.js"],
   ["mcp-tools", "mcp-tool-cli.js"],
@@ -37,6 +38,7 @@ export const USAGE = `cairn — Cairnkeep CLI
 
 Usage:
   cairn bootstrap [--untracked] [path]
+  cairn setup [PATH]  # interactive Git, harness, memory, and confirmation selectors
   cairn setup PATH --git init|existing|none --harness LIST --memory local|none [--policy PATH] --yes [--json]
   cairn memory-server
   cairn sync [--check|--apply] [--live-root DIR]
@@ -44,6 +46,7 @@ Usage:
   cairn sync-kimi [--check|--apply] [--live-root DIR]
   cairn doctor [--repair]
   cairn trajectory <list|show|prune>
+  cairn proposals <create|list|show|apply|doctor>
   cairn artifact <list|show|delete|prune>
   cairn capabilities <list|status|enable|disable|reset|logging>
   cairn mcp-tools <list|status|set|reset>

package/scripts/completion.sh

@@ -13,7 +13,7 @@ _cairn_complete() {
   COMPREPLY=()
   current=${COMP_WORDS[COMP_CWORD]}
   previous=${COMP_WORDS[COMP_CWORD-1]:-}
-  commands="bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help"
+  commands="bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack proposals notes eval skill graph memory audit-timer uninstall completion version help"
   if (( COMP_CWORD == 1 )); then
     COMPREPLY=( $(compgen -W "$commands" -- "$current") )
     return
@@ -57,7 +57,8 @@ _cairn_complete() {
       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 import-okf validate-okf export-okf list show remove enable disable update skills approve-skill revoke-skill --id --version --title --description --license --ref --project --project-id --output --file --note --check --apply --confirm --json" -- "$current") ) ;;
+    pack) COMPREPLY=( $(compgen -W "init lock validate install import-okf validate-okf export-okf list show remove enable disable update skills approve-skill revoke-skill doctor --id --version --title --description --license --ref --project --project-id --output --file --note --check --apply --confirm --repair --json" -- "$current") ) ;;
+    proposals) COMPREPLY=( $(compgen -W "create list show apply doctor --session --scope --model --category --project --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
@@ -101,6 +102,7 @@ _cairn() {
     'capabilities:inspect and manage project capability state'
     'mcp-tools:inspect and restrict MCP tool exposure'
     'pack:manage immutable context packs and skill approvals'
+    'proposals:review and apply session memory proposals'
     'notes:distill and search local hindsight notes'
     'eval:run and inspect default-off local evaluations'
     'skill:review and evaluate evidence-backed skill improvements'
@@ -136,7 +138,8 @@ _cairn() {
     evidence) _values 'work evidence command' list show delete prune doctor '--status[filter records]:status:(pending complete)' '--dry-run[report without mutation]' '--repair[remove safe temporary remnants]' '--json[emit JSON]' ;;
     playbook) _values 'playbook command' list status init set enable disable reset check record receipts instructions doctor minimal balanced strict must should may off start finish install remove context.recall context.explore work.plan verify.tests review.repository review.security docs.update learning.capture '--project[project root]:directory:_files -/' '--json[emit JSON]' '--enforce[fail when must evidence is missing]' '--changed[changed project path]:file:_files' '--change-type[change type]:type:(code tests docs config dependencies security)' '--complexity[task complexity]:level:(trivial standard complex)' '--familiarity[context familiarity]:level:(known mixed unfamiliar)' '--risk[task risk]:level:(low normal high security)' '--public-change[public behavior changed]' '--completed[completed action]:action:' '--skipped[skipped action and reason]:evidence:' '--failed[failed action and reason]:evidence:' '--actor[local actor label]:actor:' '--actor-kind[local actor kind]:kind:(user agent service)' '--session[session label]:session:' '--policy[policy digest]:digest:' '--decision[decision digest]:digest:' '--event[lifecycle event]:event:(start check finish)' '--action[canonical action]:action:(context.recall context.explore work.plan verify.tests review.repository review.security docs.update learning.capture)' '--outcome[outcome]:outcome:(completed skipped failed)' '--reason[bounded reason]:reason:' ;;
     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 import-okf validate-okf export-okf 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:' '--output[export output directory]:directory:_files -/' '--file[explicit project Markdown file]:file:_files' '--note[promoted shared note ID]:note ID:' '--check[inspect update or export]' '--apply[apply update or export]' '--confirm[confirm digest]:digest:' '--json[emit JSON]' ;;
+    pack) _values 'context pack command' init lock validate install import-okf validate-okf export-okf list show remove enable disable update skills approve-skill revoke-skill doctor '--ref[pinned Git ref]:ref:' '--project[project root]:directory:_files -/' '--project-id[remote project ID]:project ID:' '--output[export output directory]:directory:_files -/' '--file[explicit project Markdown file]:file:_files' '--note[promoted shared note ID]:note ID:' '--check[inspect update or export]' '--apply[apply update or export]' '--confirm[confirm digest]:digest:' '--repair[remove only invalid derived context cache state]' '--json[emit JSON]' ;;
+    proposals) _values 'memory proposal command' create list show apply doctor '--session[trajectory session ID]:session:' '--scope[memory scope]:scope:' '--model[extraction model]:model:' '--category[extraction category]:category:' '--project[project root]:directory:_files -/' '--json[emit JSON]' ;;
     capabilities)
       case $words[3] in
         list|status) _arguments '--json[emit JSON]' ;;
@@ -185,8 +188,8 @@ EOF
   fish)
     sed "s/__CAIRN_HARNESSES__/$harnesses/g" <<'EOF'
 complete -c cairn -f
-for command in bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook 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 setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help" -a $command
+for command in bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack proposals notes eval skill graph memory audit-timer uninstall completion version help
+complete -c cairn -n "not __fish_seen_subcommand_from bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack proposals 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
@@ -243,12 +246,20 @@ complete -c cairn -n "__fish_seen_subcommand_from mcp-tools; and __fish_seen_sub
 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 import-okf validate-okf export-okf list show remove enable disable update skills approve-skill revoke-skill"
+complete -c cairn -n "__fish_seen_subcommand_from pack" -a "init lock validate install import-okf validate-okf export-okf list show remove enable disable update skills approve-skill revoke-skill doctor"
 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 pack; and __fish_seen_subcommand_from doctor" -l repair
+complete -c cairn -n "__fish_seen_subcommand_from proposals" -a "create list show apply doctor"
+complete -c cairn -n "__fish_seen_subcommand_from proposals" -l session -r
+complete -c cairn -n "__fish_seen_subcommand_from proposals" -l scope -r
+complete -c cairn -n "__fish_seen_subcommand_from proposals" -l model -r
+complete -c cairn -n "__fish_seen_subcommand_from proposals" -l category -r
+complete -c cairn -n "__fish_seen_subcommand_from proposals" -l project -r
+complete -c cairn -n "__fish_seen_subcommand_from proposals" -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

package/scripts/doctor.sh

@@ -13,7 +13,7 @@ REPAIR_STORES=0
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --repair) REPAIR_STORES=1; shift ;;
-    -h|--help) echo "Usage: cairn doctor [--repair]  # repair derived trajectory/artifact/typed metadata, indexes, and interrupted note transactions"; exit 0 ;;
+    -h|--help) echo "Usage: cairn doctor [--repair]  # repair safe derived pack caches, typed metadata/indexes, and interrupted note transactions"; exit 0 ;;
     *) echo "Unknown doctor option: $1" >&2; echo "Usage: cairn doctor [--repair]" >&2; exit 2 ;;
   esac
 done
@@ -470,11 +470,13 @@ fi
 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}"
+pack_args=(doctor --json)
+if [[ "$REPAIR_STORES" == 1 ]]; then pack_args+=(--repair); fi
 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
+elif pack_json=$(node "$pack_cli" "${pack_args[@]}" 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

package/scripts/setup.mjs

@@ -21,8 +21,9 @@ import {
   resolveSetupChoices,
 } from "./setup-core.mjs";
 import { reconcileSetupPlan } from "./setup-reconcile.mjs";
-import { HARNESS_IDS, machineSyncCommand, requiredHarnessAssetPaths } from "./harness-registry.mjs";
+import { HARNESS_IDS, HARNESS_REGISTRY, machineSyncCommand, requiredHarnessAssetPaths } from "./harness-registry.mjs";
 import { reconcilePlaybookInstructions } from "./playbook-instructions.mjs";
+import { selectManyPrompt, selectOnePrompt, supportsTerminalPrompts } from "./terminal-prompts.mjs";
 
 const HARNESSES = HARNESS_IDS;
 const GIT_MODES = Object.freeze(["init", "existing", "none"]);
@@ -70,11 +71,36 @@ function parseInteractiveHarnesses(value) {
 }
 
 export async function promptSetupChoices(parsed, streams) {
-  const terminal = typeof streams.question === "function"
-    ? { question: streams.question, close: streams.closePrompt ?? (() => {}) }
-    : createInterface({ input: streams.input, output: streams.output });
+  let linePrompt = null;
+  let externallyClosed = false;
+  const question = typeof streams.question === "function"
+    ? streams.question
+    : async (message) => {
+      linePrompt ??= createInterface({ input: streams.input, output: streams.output });
+      return linePrompt.question(message);
+    };
+  const closeLinePrompt = () => {
+    if (linePrompt) linePrompt.close();
+    linePrompt = null;
+    if (!externallyClosed) {
+      streams.closePrompt?.();
+      externallyClosed = true;
+    }
+  };
+  const structured = Boolean(streams.selectOne && streams.selectMany)
+    || supportsTerminalPrompts(streams.input, streams.output);
+  const selectOne = streams.selectOne ?? ((options) => selectOnePrompt({
+    ...options,
+    input: streams.input,
+    output: streams.output,
+  }));
+  const selectMany = streams.selectMany ?? ((options) => selectManyPrompt({
+    ...options,
+    input: streams.input,
+    output: streams.output,
+  }));
   try {
-    const target = parsed.target ?? (await terminal.question("Target path: ")).trim();
+    const target = parsed.target ?? (await question("Target path: ")).trim();
     if (!target) throw operational("interactive-input", "A setup target path is required.");
     const preflight = classifySetupTarget(target);
     const gitQuestion = preflight.targetState === "missing" || preflight.targetState === "empty"
@@ -82,12 +108,63 @@ export async function promptSetupChoices(parsed, streams) {
       : preflight.repository === "work-tree"
         ? "Git mode (existing recommended; choices: init, existing, none): "
         : "Git mode (init requires explicit choice for existing non-Git target; choices: init, existing, none): ";
-    const git = parsed.git ?? (await terminal.question(gitQuestion)).trim();
-    const harnesses = parsed.harnesses ?? parseInteractiveHarnesses(await terminal.question(`Harnesses (${HARNESSES.join(", ")}): `));
-    const memory = parsed.memory ?? (await terminal.question("Memory mode (local, none): ")).trim();
-    return { target, git, harnesses, memory, preflight, terminal };
+    if (structured) closeLinePrompt();
+    const gitChoices = preflight.gitExecutable === "missing"
+      ? [{ value: "none", label: "Continue without Git", hint: "Git executable not found; repository features will be limited" }]
+      : preflight.repository === "work-tree"
+        ? [
+          { value: "existing", label: "Use the existing Git repository", hint: "recommended" },
+          { value: "none", label: "Continue without Git integration", hint: "limited" },
+        ]
+        : [
+          { value: "init", label: "Initialize a Git repository", hint: preflight.targetState === "non-empty" ? "review the existing directory first" : "recommended" },
+          { value: "none", label: "Continue without Git integration", hint: "limited" },
+        ];
+    const git = parsed.git ?? (structured
+      ? await selectOne({ message: "Git integration", choices: gitChoices, initialValue: gitChoices[0].value })
+      : (await question(gitQuestion)).trim());
+    const harnesses = parsed.harnesses ?? (structured
+      ? await selectMany({
+        message: "Coding harnesses",
+        choices: HARNESS_REGISTRY.map(({ id, title }) => ({ value: id, label: `${title} (${id})` })),
+      })
+      : parseInteractiveHarnesses(await question(`Harnesses (${HARNESSES.join(", ")}): `)));
+    const memory = parsed.memory ?? (structured
+      ? await selectOne({
+        message: "Memory mode",
+        choices: [
+          { value: "local", label: "Local Cairnkeep memory", hint: "recommended" },
+          { value: "none", label: "No memory server" },
+        ],
+        initialValue: "local",
+      })
+      : (await question("Memory mode (local, none): ")).trim());
+    return {
+      target,
+      git,
+      harnesses,
+      memory,
+      preflight,
+      terminal: {
+        question,
+        close: closeLinePrompt,
+        confirm: structured
+          ? async () => (await selectOne({
+            message: "Apply this setup plan?",
+            choices: [
+              { value: "no", label: "No, cancel" },
+              { value: "yes", label: "Yes, apply the plan" },
+            ],
+            initialValue: "no",
+          })) === "yes"
+          : async () => {
+            const answer = (await question("Apply this setup plan? [y/N] ")).trim().toLowerCase();
+            return answer === "y" || answer === "yes";
+          },
+      },
+    };
   } catch (error) {
-    terminal.close();
+    closeLinePrompt();
     throw error;
   }
 }
@@ -167,7 +244,7 @@ function initializeGit(target) {
 }
 
 async function executeSetup(args, options) {
-  const isTTY = options.isTTY ?? Boolean(options.input.isTTY);
+  const isTTY = options.isTTY ?? Boolean(options.input.isTTY && options.output.isTTY);
   const parsed = parseSetupArgs(args, { isTTY });
   const policy = parsed.policyPath ? readSetupPolicy(parsed.policyPath) : null;
 
@@ -196,9 +273,9 @@ async function executeSetup(args, options) {
 
   if (interactive && !parsed.confirmed) {
     renderPlan(plan, options.output);
-    const answer = (await interactive.terminal.question("Apply this setup plan? [y/N] ")).trim().toLowerCase();
+    const accepted = await interactive.terminal.confirm();
     interactive.terminal.close();
-    if (answer !== "y" && answer !== "yes") {
+    if (!accepted) {
       writeLine(options.output, "Setup cancelled; no files were changed.");
       return null;
     }
@@ -221,6 +298,8 @@ export async function runSetup(args, options = {}) {
     augmentPlan: options.augmentPlan,
     question: options.question,
     closePrompt: options.closePrompt,
+    selectOne: options.selectOne,
+    selectMany: options.selectMany,
   };
   try {
     const result = await executeSetup(args, streams);

package/scripts/terminal-prompts.mjs

@@ -0,0 +1,172 @@
+import { emitKeypressEvents } from "node:readline";
+
+function promptError(message, status = 1) {
+  const error = new Error(message);
+  error.name = "TerminalPromptError";
+  error.status = status;
+  return error;
+}
+
+function normalizedChoices(choices) {
+  if (!Array.isArray(choices) || choices.length === 0) throw promptError("A terminal prompt requires at least one choice.");
+  const normalized = choices.map((choice) => Object.freeze({
+    value: String(choice.value),
+    label: String(choice.label),
+    hint: choice.hint ? String(choice.hint) : "",
+  }));
+  if (new Set(normalized.map(({ value }) => value)).size !== normalized.length) {
+    throw promptError("Terminal prompt choices must have unique values.");
+  }
+  return Object.freeze(normalized);
+}
+
+export function supportsTerminalPrompts(input, output, env = process.env) {
+  return Boolean(
+    input?.isTTY
+      && output?.isTTY
+      && typeof input.setRawMode === "function"
+      && env.TERM !== "dumb",
+  );
+}
+
+async function runKeypressPrompt({ input, output, draw, accept }) {
+  emitKeypressEvents(input);
+  const wasRaw = Boolean(input.isRaw);
+  const wasPaused = typeof input.isPaused === "function" ? input.isPaused() : false;
+  let renderedLines = 0;
+  let settled = false;
+  let keypressHandler = null;
+  let rawChanged = false;
+  let resumed = false;
+  let cursorHidden = false;
+
+  const render = () => {
+    const lines = draw();
+    if (renderedLines > 0) output.write(`\x1b[${renderedLines}A\r\x1b[0J`);
+    output.write(`${lines.join("\n")}\n`);
+    renderedLines = lines.length;
+  };
+
+  const clear = () => {
+    if (renderedLines > 0) output.write(`\x1b[${renderedLines}A\r\x1b[0J`);
+    renderedLines = 0;
+  };
+
+  try {
+    if (!wasRaw) {
+      input.setRawMode(true);
+      rawChanged = true;
+    }
+    if (wasPaused && typeof input.resume === "function") {
+      input.resume();
+      resumed = true;
+    }
+    output.write("\x1b[?25l");
+    cursorHidden = true;
+    render();
+    return await new Promise((resolve, reject) => {
+      const finish = (callback, value) => {
+        if (settled) return;
+        settled = true;
+        input.removeListener("keypress", onKeypress);
+        callback(value);
+      };
+      const onKeypress = (text, key = {}) => {
+        try {
+          if ((key.ctrl && key.name === "c") || key.name === "escape") {
+            finish(reject, promptError("Setup cancelled.", 130));
+            return;
+          }
+          const result = accept(text, key);
+          if (result?.done) finish(resolve, result.value);
+          else render();
+        } catch (error) {
+          finish(reject, error);
+        }
+      };
+      keypressHandler = onKeypress;
+      input.on("keypress", onKeypress);
+    });
+  } finally {
+    if (keypressHandler) input.removeListener("keypress", keypressHandler);
+    clear();
+    if (cursorHidden) output.write("\x1b[?25h");
+    if (rawChanged) input.setRawMode(false);
+    if (resumed && typeof input.pause === "function") input.pause();
+  }
+}
+
+function movement(key, cursor, length) {
+  if (key.name === "up" || key.name === "k") return (cursor - 1 + length) % length;
+  if (key.name === "down" || key.name === "j") return (cursor + 1) % length;
+  if (key.name === "home") return 0;
+  if (key.name === "end") return length - 1;
+  return cursor;
+}
+
+export async function selectOnePrompt({ message, choices, initialValue, input, output }) {
+  const options = normalizedChoices(choices);
+  let cursor = Math.max(0, options.findIndex(({ value }) => value === initialValue));
+  const selected = await runKeypressPrompt({
+    input,
+    output,
+    draw: () => [
+      `? ${message} (Up/Down to move, Enter to select)`,
+      ...options.map((choice, index) => `${index === cursor ? ">" : " "} ${choice.label}${choice.hint ? ` - ${choice.hint}` : ""}`),
+    ],
+    accept: (text, key) => {
+      cursor = movement(key, cursor, options.length);
+      if (key.name === "return" || key.name === "enter") return { done: true, value: options[cursor].value };
+      const number = Number.parseInt(text, 10);
+      if (Number.isInteger(number) && number >= 1 && number <= options.length) {
+        cursor = number - 1;
+        return { done: true, value: options[cursor].value };
+      }
+      return null;
+    },
+  });
+  const label = options.find(({ value }) => value === selected)?.label ?? selected;
+  output.write(`> ${message}: ${label}\n`);
+  return selected;
+}
+
+export async function selectManyPrompt({ message, choices, selectedValues = [], input, output, minimum = 1 }) {
+  const options = normalizedChoices(choices);
+  const allowed = new Set(options.map(({ value }) => value));
+  const selected = new Set(selectedValues.filter((value) => allowed.has(value)));
+  let cursor = 0;
+  let validation = "";
+  const values = await runKeypressPrompt({
+    input,
+    output,
+    draw: () => [
+      `? ${message} (Up/Down to move, Space to toggle, A to toggle all, Enter to continue)`,
+      ...options.map((choice, index) => `${index === cursor ? ">" : " "} [${selected.has(choice.value) ? "x" : " "}] ${choice.label}${choice.hint ? ` - ${choice.hint}` : ""}`),
+      validation,
+    ],
+    accept: (text, key) => {
+      cursor = movement(key, cursor, options.length);
+      if (key.name === "space" || text === " ") {
+        const value = options[cursor].value;
+        if (selected.has(value)) selected.delete(value);
+        else selected.add(value);
+        validation = "";
+      } else if (text?.toLowerCase() === "a") {
+        if (selected.size === options.length) selected.clear();
+        else for (const { value } of options) selected.add(value);
+        validation = "";
+      } else if (key.name === "return" || key.name === "enter") {
+        if (selected.size < minimum) {
+          validation = `  Select at least ${minimum} option${minimum === 1 ? "" : "s"}.`;
+          output.write("\x07");
+        } else {
+          return { done: true, value: options.filter(({ value }) => selected.has(value)).map(({ value }) => value) };
+        }
+      }
+      return null;
+    },
+  });
+  const labels = options.filter(({ value }) => values.includes(value)).map(({ label }) => label);
+  output.write(`> ${message}: ${labels.join(", ")}\n`);
+  return values;
+}

package/scripts/test-completion.sh

@@ -46,7 +46,13 @@ for shell in bash zsh fish; do
   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 'init.*lock.*validate.*install.*list.*show.*remove.*enable.*disable.*update.*skills.*approve-skill.*revoke-skill.*doctor\|init lock validate install list show remove enable disable update skills approve-skill revoke-skill doctor' "$tmp/$shell"
+  grep -q -- '--repair\|-l repair' "$tmp/$shell"
+  grep -q 'proposals' "$tmp/$shell"
+  grep -q 'create.*list.*show.*apply.*doctor\|create list show apply doctor' "$tmp/$shell"
+  for proposal_flag in --session --scope --model --category --project --json; do
+    grep -q -- "$proposal_flag\|-l ${proposal_flag#--}" "$tmp/$shell"
+  done
   grep -q -- '--purge-packs\|-l purge-packs' "$tmp/$shell"
   grep -q 'evidence' "$tmp/$shell"
   grep -q 'list.*show.*delete.*prune.*doctor\|list show delete prune doctor' "$tmp/$shell"
@@ -77,6 +83,7 @@ fi
 grep -qF 'cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>' "$tmp/root-help"
 grep -qF 'cairn evidence <list|show|delete|prune|doctor>' "$tmp/root-help"
 grep -qF 'cairn playbook <list|status|init|set|enable|disable|reset|check|record|receipts|instructions|doctor>' "$tmp/root-help"
+grep -qF 'cairn proposals <create|list|show|apply|doctor>' "$tmp/root-help"
 node "$ROOT/mcp-memory-server/dist/skill-cli.js" --help >"$tmp/skill-help"
 for command in $skill_commands; do
   grep -q "cairn skill $command" "$tmp/skill-help"