@cairnkeep/cli 2.9.0 → 2.11.0

package/scripts/setup.mjs

@@ -0,0 +1,306 @@
+import { spawnSync } from "node:child_process";
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as defaultInput, stdout as defaultOutput, stderr as defaultError } from "node:process";
+import {
+  buildSetupPlan,
+  classifySetupTarget,
+  parseSetupArgs,
+  readSetupPolicy,
+  resolveSetupChoices,
+} from "./setup-core.mjs";
+import { reconcileSetupPlan } from "./setup-reconcile.mjs";
+
+const HARNESSES = Object.freeze(["claude", "opencode", "pi", "kimi", "qwen"]);
+const GIT_MODES = Object.freeze(["init", "existing", "none"]);
+const MEMORY_MODES = Object.freeze(["local", "none"]);
+const STATE_KEYS = Object.freeze(["schema_version", "cairnkeep_version", "git", "memory", "harnesses", "assets"]);
+const ASSET_KEYS = Object.freeze(["digest", "mode", "template"]);
+const SAFE_ASSET = /^\.(?:ai|planning|agentfs)\/(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._/-]+$/;
+const COMMON_SETUP_ASSETS = Object.freeze([
+  ".ai/env.example",
+  ".ai/trajectory-redaction.json",
+  ".ai/capabilities.json",
+  ".agentfs/.gitignore",
+  ".planning/config.json",
+  ".planning/PROJECT-BRIEF.md",
+  ".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",
+]);
+
+function operational(kind, message) {
+  const error = new Error(message);
+  error.name = "SetupOperationalError";
+  error.kind = kind;
+  error.status = 1;
+  return error;
+}
+
+function writeLine(stream, value = "") {
+  stream.write(`${value}\n`);
+}
+
+function parseInteractiveHarnesses(value) {
+  const selected = value.split(",").map((item) => item.trim()).filter(Boolean);
+  if (selected.length === 0 || new Set(selected).size !== selected.length || selected.some((item) => !HARNESSES.includes(item))) {
+    throw operational("interactive-input", `Harnesses must be a comma-separated subset of ${HARNESSES.join(", ")}.`);
+  }
+  return HARNESSES.filter((name) => selected.includes(name));
+}
+
+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 });
+  try {
+    const target = parsed.target ?? (await terminal.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"
+      ? "Git mode (init recommended; choices: init, existing, none): "
+      : 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 };
+  } catch (error) {
+    terminal.close();
+    throw error;
+  }
+}
+
+function renderPlan(plan, stream) {
+  writeLine(stream, `Target: ${plan.target}`);
+  writeLine(stream, `Git mode: ${plan.git}`);
+  writeLine(stream, `Harnesses: ${plan.harnesses.join(", ")}`);
+  writeLine(stream, `Memory mode: ${plan.memory}`);
+  writeLine(stream, "Planned assets:");
+  for (const asset of plan.assets) writeLine(stream, `  ${asset.path}`);
+}
+
+function launchCommands(plan, platform) {
+  const suffix = platform === "win32" ? "cmd" : "sh";
+  return plan.harnesses.map((harness) => `.ai/start-${harness}.${suffix}`);
+}
+
+function setupRecovery(plan) {
+  return [`cairn setup . --git ${plan.git} --harness ${plan.harnesses.join(",")} --memory ${plan.memory} --yes`];
+}
+
+function resultFor(plan, reconciliation, platform) {
+  const machineCommand = plan.harnesses.includes("pi") ? "cairn sync-pi --apply" : "cairn sync --apply";
+  return Object.freeze({
+    schema_version: 1,
+    status: plan.limited ? "limited" : "complete",
+    target: plan.target,
+    git: plan.git,
+    memory: plan.memory,
+    harnesses: plan.harnesses,
+    counts: reconciliation.counts,
+    changes: reconciliation.changes,
+    verification: Object.freeze(["cairn doctor"]),
+    launch_commands: Object.freeze(launchCommands(plan, platform)),
+    recovery: Object.freeze(setupRecovery(plan)),
+    limitations: Object.freeze(plan.limited ? ["Git integration is disabled; repository-aware features are limited."] : []),
+    machine_sync: Object.freeze({ automatic: false, command: machineCommand }),
+  });
+}
+
+export function renderSetupResult(result, stream) {
+  writeLine(stream, `Setup status: ${result.status}`);
+  writeLine(stream, `Harnesses: ${result.harnesses.join(", ")}`);
+  writeLine(stream, `Git mode: ${result.git}`);
+  writeLine(stream, `Memory mode: ${result.memory}`);
+  writeLine(stream, `Created: ${result.counts.created}`);
+  writeLine(stream, `Updated: ${result.counts.updated}`);
+  writeLine(stream, `Unchanged: ${result.counts.unchanged}`);
+  writeLine(stream, `Skipped: ${result.counts.skipped}`);
+  writeLine(stream, `Verification: ${result.verification.join(", ")}`);
+  for (const command of result.launch_commands) writeLine(stream, `Launch: ${command}`);
+  for (const command of result.recovery) writeLine(stream, `Recovery: ${command}`);
+  for (const limitation of result.limitations) writeLine(stream, `Limitation: ${limitation}`);
+  writeLine(stream, `Machine sync: ${result.machine_sync.command} (not run automatically)`);
+}
+
+function createTarget(target) {
+  try {
+    if (!existsSync(target)) mkdirSync(target, { recursive: true, mode: 0o755 });
+    const info = lstatSync(target);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("target is not a regular directory");
+  } catch {
+    throw operational("target-denied", "Setup target could not be created safely.");
+  }
+}
+
+function initializeGit(target) {
+  const result = spawnSync("git", ["init", "-q", target], { encoding: "utf8", shell: false });
+  if (result.error?.code === "ENOENT") throw operational("missing-git", "Git executable is required for --git init.");
+  if (result.error || result.status !== 0) throw operational("git-init", "Git repository initialization failed.");
+}
+
+async function executeSetup(args, options) {
+  const isTTY = options.isTTY ?? Boolean(options.input.isTTY);
+  const parsed = parseSetupArgs(args, { isTTY });
+  const policy = parsed.policyPath ? readSetupPolicy(parsed.policyPath) : null;
+
+  let interactive = null;
+  let target = parsed.target;
+  let preflight = null;
+  if (isTTY && (!target || !parsed.git || !parsed.harnesses || !parsed.memory || !parsed.confirmed)) {
+    interactive = await promptSetupChoices(parsed, options);
+    target = interactive.target;
+    preflight = interactive.preflight;
+  }
+  preflight ??= classifySetupTarget(target);
+  const choices = resolveSetupChoices({
+    parsed,
+    preflight,
+    policy,
+    interactive: interactive ? { ...interactive, confirmed: true } : null,
+  });
+  let plan = buildSetupPlan({ target, preflight, choices });
+  if (options.augmentPlan) plan = await options.augmentPlan(plan);
+
+  if (interactive && !parsed.confirmed) {
+    renderPlan(plan, options.output);
+    const answer = (await interactive.terminal.question("Apply this setup plan? [y/N] ")).trim().toLowerCase();
+    interactive.terminal.close();
+    if (answer !== "y" && answer !== "yes") {
+      writeLine(options.output, "Setup cancelled; no files were changed.");
+      return null;
+    }
+  } else if (interactive) interactive.terminal.close();
+
+  createTarget(plan.target);
+  if (plan.git === "init") initializeGit(plan.target);
+  const reconciliation = await reconcileSetupPlan(plan);
+  return resultFor(plan, reconciliation, options.platform);
+}
+
+export async function runSetup(args, options = {}) {
+  const streams = {
+    input: options.input ?? defaultInput,
+    output: options.output ?? defaultOutput,
+    error: options.error ?? defaultError,
+    isTTY: options.isTTY,
+    platform: options.platform ?? process.platform,
+    augmentPlan: options.augmentPlan,
+    question: options.question,
+    closePrompt: options.closePrompt,
+  };
+  try {
+    const result = await executeSetup(args, streams);
+    if (!result) return 0;
+    if (args.includes("--json")) writeLine(streams.output, JSON.stringify(result));
+    else renderSetupResult(result, streams.output);
+    return 0;
+  } catch (error) {
+    writeLine(streams.error, error instanceof Error ? error.message : "Setup failed.");
+    return Number.isInteger(error?.status) ? error.status : 1;
+  }
+}
+
+function incompleteDiagnosis(recovery = "cairn setup . --git existing --harness claude --memory local --yes") {
+  return Object.freeze({ schema_version: 1, status: "incomplete", code: "setup-state", recovery: Object.freeze([recovery]) });
+}
+
+function exactKeys(value, expected) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).sort().join(",") === [...expected].sort().join(",");
+}
+
+function safeStateAsset(path, record) {
+  return typeof path === "string"
+    && path.length <= 512
+    && SAFE_ASSET.test(path)
+    && !path.includes("\\")
+    && !path.split("/").includes("..")
+    && exactKeys(record, ASSET_KEYS)
+    && typeof record.digest === "string"
+    && /^[a-f0-9]{64}$/.test(record.digest)
+    && Number.isInteger(record.mode)
+    && record.mode >= 0
+    && record.mode <= 0o777
+    && typeof record.template === "string"
+    && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(record.template);
+}
+
+function readPrivateState(path) {
+  const info = lstatSync(path);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) throw new Error("unsafe");
+  if (process.platform !== "win32" && (info.mode & 0o777) !== 0o600) throw new Error("unsafe");
+  let descriptor;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const opened = fstatSync(descriptor);
+    if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.size > 1024 * 1024) throw new Error("unsafe");
+    return JSON.parse(readFileSync(descriptor, "utf8"));
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+export function diagnoseSetup(target = ".") {
+  const project = resolve(target);
+  const statePath = join(project, ".ai", "cairnkeep.json");
+  if (!existsSync(statePath)) return Object.freeze({ schema_version: 1, status: "absent", code: "not-configured", recovery: Object.freeze([]) });
+  try {
+    const state = readPrivateState(statePath);
+    if (!exactKeys(state, STATE_KEYS)
+        || state.schema_version !== 1
+        || typeof state.cairnkeep_version !== "string"
+        || state.cairnkeep_version.length === 0
+        || state.cairnkeep_version.length > 128
+        || !GIT_MODES.includes(state.git)
+        || !MEMORY_MODES.includes(state.memory)
+        || !Array.isArray(state.harnesses)
+        || state.harnesses.length === 0
+        || new Set(state.harnesses).size !== state.harnesses.length
+        || state.harnesses.some((name) => !HARNESSES.includes(name))
+        || !state.assets
+        || typeof state.assets !== "object"
+        || Array.isArray(state.assets)
+        || Object.keys(state.assets).length === 0) return incompleteDiagnosis();
+
+    const recovery = `cairn setup . --git ${state.git} --harness ${state.harnesses.join(",")} --memory ${state.memory} --yes`;
+    for (const [path, record] of Object.entries(state.assets)) {
+      if (!safeStateAsset(path, record)) return incompleteDiagnosis(recovery);
+      const destination = join(project, ...path.split("/"));
+      if (!existsSync(destination)) return incompleteDiagnosis(recovery);
+      const info = lstatSync(destination);
+      if (!info.isFile() || info.isSymbolicLink()) return incompleteDiagnosis(recovery);
+      const digest = createHash("sha256").update(readFileSync(destination)).digest("hex");
+      if (digest !== record.digest || (process.platform !== "win32" && (info.mode & 0o777) !== record.mode)) return incompleteDiagnosis(recovery);
+    }
+    const requiredAssets = [...COMMON_SETUP_ASSETS, ...state.harnesses.map((harness) => `.ai/start-${harness}.sh`)];
+    if (requiredAssets.some((path) => !Object.hasOwn(state.assets, path))) return incompleteDiagnosis(recovery);
+    return Object.freeze({
+      schema_version: 1,
+      status: state.git === "none" ? "limited" : "complete",
+      code: state.git === "none" ? "git-disabled" : "configured",
+      recovery: Object.freeze([]),
+    });
+  } catch {
+    return incompleteDiagnosis();
+  }
+}

package/scripts/sync-pi-assets.sh

@@ -21,6 +21,7 @@ SOURCE_ROOT="$ROOT_DIR/pi"
 LIVE_ROOT="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
 MODE="check"
 ASSETS=(
+  "extensions/cairnkeep-memory.ts"
   "extensions/cairnkeep-trajectory.ts"
   "prompts/graphify.md"
 )
@@ -37,7 +38,7 @@ done
 
 render_asset() {
   local rel="$1"
-  if [[ "$rel" == "extensions/cairnkeep-trajectory.ts" ]]; then
+  if [[ "$rel" == extensions/*.ts ]]; then
     sed "s|@@INFRA_ROOT@@|$ROOT_DIR|g" "$SOURCE_ROOT/$rel"
   else
     cat "$SOURCE_ROOT/$rel"
@@ -74,20 +75,34 @@ ensure_sources
 if [[ "$MODE" == "apply" ]]; then
   updated=0
   unchanged=0
+  memory_updated=0
+  memory_unchanged=0
   for rel in "${ASSETS[@]}"; do
     mkdir -p "$(dirname "$LIVE_ROOT/$rel")"
     if [[ -f "$LIVE_ROOT/$rel" ]] && cmp -s <(render_asset "$rel") "$LIVE_ROOT/$rel"; then
-      unchanged=$((unchanged + 1))
+      if [[ "$rel" == "extensions/cairnkeep-memory.ts" ]]; then
+        memory_unchanged=1
+      else
+        unchanged=$((unchanged + 1))
+      fi
       continue
     fi
     rendered_tmp=$(mktemp)
     render_asset "$rel" > "$rendered_tmp"
     install -m 0644 "$rendered_tmp" "$LIVE_ROOT/$rel"
     rm -f "$rendered_tmp"
-    updated=$((updated + 1))
+    if [[ "$rel" == "extensions/cairnkeep-memory.ts" ]]; then
+      memory_updated=1
+    else
+      updated=$((updated + 1))
+    fi
   done
   printf 'Applied %s Pi asset(s); %s already matched.\n' "$updated" "$unchanged"
+  printf 'Pi memory extension: %s updated; %s already matched.\n' "$memory_updated" "$memory_unchanged"
 fi
 
-check_assets
+if ! check_assets; then
+  echo "Recovery: sync-pi-assets.sh --apply --live-root PATH" >&2
+  exit 1
+fi
 printf 'Pi extension and graph prompt are in sync under %s\n' "$LIVE_ROOT"

package/scripts/test-completion.sh

@@ -118,5 +118,44 @@ if "$ROOT/bin/cairn" completion unsupported >/dev/null 2>&1; then
   exit 1
 fi
 
+completion_surface_complete=true
+for shell in bash zsh fish; do
+  if ! grep -qw 'setup' "$tmp/$shell"; then
+    completion_surface_complete=false
+  fi
+done
+"$ROOT/bin/cairn" completion powershell >"$tmp/powershell"
+if ! grep -qE "['\"]setup['\"]" "$tmp/powershell"; then
+  completion_surface_complete=false
+fi
+
+if [[ "$completion_surface_complete" != true ]]; then
+  if [[ "${CAIRN_PHASE26_RED:-0}" == 1 ]]; then
+    echo "PHASE26_RED:SETUP_COMPLETION_MISSING"
+    exit 86
+  fi
+  echo "SKIP: guided setup completion surface is not complete"
+  git -C "$ROOT" diff --check
+  echo "PASS: shell completion generation"
+  exit 0
+fi
+
+setup_flags='--git --harness --memory --policy --yes --json'
+setup_values='init existing none claude opencode pi kimi qwen local'
+for shell in bash zsh fish powershell; do
+  for flag in $setup_flags; do
+    grep -q -- "$flag\|${flag#--}" "$tmp/$shell" || {
+      echo "setup completion omitted $flag for $shell" >&2
+      exit 1
+    }
+  done
+  for value in $setup_values; do
+    grep -qF "$value" "$tmp/$shell" || {
+      echo "setup completion omitted $value for $shell" >&2
+      exit 1
+    }
+  done
+done
+
 git -C "$ROOT" diff --check
 echo "PASS: shell completion generation"

package/scripts/test-doctor.sh

@@ -454,3 +454,69 @@ for sentinel in prompt-sentinel model-output-sentinel adapter-stderr-sentinel en
 done
 
 echo "PASS: cairn doctor (existing probes plus value-free capability/evaluation diagnostics)"
+
+phase26_doctor_complete=true
+for required in \
+  "$ROOT/scripts/setup.mjs" \
+  "$ROOT/schemas/cairnkeep-setup.schema.json" \
+  "$ROOT/pi/extensions/cairnkeep-memory.ts"; do
+  [[ -f "$required" ]] || phase26_doctor_complete=false
+done
+grep -qF 'cairnkeep.json' "$doctor" || phase26_doctor_complete=false
+grep -qF 'cairnkeep-memory.ts' "$doctor" || phase26_doctor_complete=false
+
+if [[ "$phase26_doctor_complete" != true ]]; then
+  if [[ "${CAIRN_PHASE26_RED:-0}" == 1 ]]; then
+    echo "PHASE26_RED:SETUP_DOCTOR_MISSING"
+    exit 86
+  fi
+  echo "SKIP: setup and Pi doctor diagnostics are not complete"
+  exit 0
+fi
+
+setup_home="$tmp/setup-home"
+setup_pi="$setup_home/.pi/agent"
+mkdir -p "$setup_home" "$setup_pi"
+HOME="$setup_home" "$ROOT/scripts/sync-pi-assets.sh" --apply --live-root "$setup_pi" >/dev/null
+
+complete_project="$tmp/setup-complete"
+HOME="$setup_home" "$ROOT/bin/cairn" setup "$complete_project" \
+  --git init --harness claude,pi --memory local --yes --json >/dev/null
+(cd "$complete_project" && HOME="$setup_home" PI_CODING_AGENT_DIR="$setup_pi" "$doctor") >"$tmp/setup-complete.out" 2>&1 \
+  || fail "doctor rejected complete guided setup"
+grep -Eq '\[PASS\].*(project )?setup.*complete' "$tmp/setup-complete.out" || fail "doctor omitted complete setup state"
+
+limited_project="$tmp/setup-limited"
+HOME="$setup_home" "$ROOT/bin/cairn" setup "$limited_project" \
+  --git none --harness claude --memory none --yes --json >/dev/null
+(cd "$limited_project" && HOME="$setup_home" PI_CODING_AGENT_DIR="$setup_pi" "$doctor") >"$tmp/setup-limited.out" 2>&1 \
+  || fail "doctor treated intentional Git-less setup as fatal"
+grep -Eq '\[WARN\].*(setup.*limited|Git-less)' "$tmp/setup-limited.out" || fail "doctor omitted Git-less limited state"
+
+incomplete_project="$tmp/setup-incomplete"
+mkdir -p "$incomplete_project/.ai"
+printf '%s\n' '{"schema_version":1,"git":"existing","memory":"local","harnesses":["pi"],"assets":{}}' >"$incomplete_project/.ai/cairnkeep.json"
+set +e
+(cd "$incomplete_project" && HOME="$setup_home" PI_CODING_AGENT_DIR="$setup_pi" "$doctor") >"$tmp/setup-incomplete.out" 2>&1
+incomplete_status=$?
+set -e
+[[ "$incomplete_status" -ne 0 ]] || fail "doctor accepted incomplete setup state"
+grep -Eq '\[FAIL\].*(setup.*incomplete|setup state)' "$tmp/setup-incomplete.out" || fail "doctor omitted incomplete setup diagnosis"
+grep -Eq 'cairn setup .*--git|cairn setup --git' "$tmp/setup-incomplete.out" || fail "incomplete setup lacks exact setup recovery"
+
+rm -f "$setup_pi/extensions/cairnkeep-memory.ts"
+set +e
+(cd "$complete_project" && HOME="$setup_home" PI_CODING_AGENT_DIR="$setup_pi" "$doctor") >"$tmp/setup-pi-drift.out" 2>&1
+pi_drift_status=$?
+set -e
+[[ "$pi_drift_status" -ne 0 ]] || fail "doctor accepted missing selected Pi memory extension"
+grep -Eq '\[FAIL\].*Pi.*memory extension|\[FAIL\].*cairnkeep-memory' "$tmp/setup-pi-drift.out" || fail "doctor omitted Pi drift diagnosis"
+grep -qF 'cairn sync-pi --apply' "$tmp/setup-pi-drift.out" || fail "Pi drift lacks exact sync recovery"
+
+for output in "$tmp/setup-complete.out" "$tmp/setup-limited.out" "$tmp/setup-incomplete.out" "$tmp/setup-pi-drift.out"; do
+  if grep -Eqi 'token[=:]|secret[=:]|credential[=:]|https?://' "$output"; then
+    fail "setup doctor exposed unbounded private values"
+  fi
+done
+
+echo "PASS: complete, limited, incomplete, Pi drift, and recovery doctor contract"

package/scripts/test-learning-docs.sh

@@ -16,13 +16,13 @@ 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 \
-  course-08-graph course-09-skill course-10-trust-context; do
+  course-08-graph course-09-skill course-10-trust-context course-11-windows; do
   grep -qF "\`$checkpoint\`" "$coverage"
 done
 
 ready=0
 brief=0
-for number in $(seq -w 0 21); do
+for number in $(seq -w 0 22); 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
@@ -53,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 7 && $brief -eq 15 ]] || {
+[[ $ready -eq 8 && $brief -eq 15 ]] || {
   echo "unexpected learning status totals: ready=$ready brief=$brief" >&2
   exit 1
 }
@@ -94,4 +94,53 @@ for (const file of markdownFiles("docs/learning")) {
 }
 NODE
 
+l23=docs/learning/lessons/L23-guided-setup.md
+quickstart=docs/learning/tracks/quickstart.md
+operator=docs/learning/tracks/operator.md
+phase26_learning_complete=true
+[[ -f "$l23" ]] || phase26_learning_complete=false
+grep -qF 'L23-guided-setup.md' "$quickstart" || phase26_learning_complete=false
+grep -qF 'L23-guided-setup.md' "$operator" || phase26_learning_complete=false
+
+if [[ "$phase26_learning_complete" != true ]]; then
+  if [[ "${CAIRN_PHASE26_RED:-0}" == 1 ]]; then
+    echo "PHASE26_RED:GUIDED_SETUP_LEARNING_MISSING"
+    exit 86
+  fi
+  echo "SKIP: Ready L23 guided-setup lesson and track routing are not complete"
+  echo "PASS: public learning path structure, readiness, links, and version alignment"
+  exit 0
+fi
+
+grep -q '^\*\*Status:\*\* Ready' "$l23"
+grep -qF "Tested with:** Cairnkeep $version" "$l23"
+for heading in '## Outcome' '## Exercise' '## Recovery exercise' '## Common failures' '## Privacy and trust boundary'; do
+  grep -qxF "$heading" "$l23" || {
+    echo "L23 missing required heading: $heading" >&2
+    exit 1
+  }
+done
+for command in \
+  'cairn setup' \
+  '--git init' \
+  '--git none' \
+  '--harness' \
+  '--memory' \
+  '--yes' \
+  'cairn sync-pi --apply' \
+  'cairn doctor' \
+  'cairn uninstall'; do
+  grep -qF -- "$command" "$l23" || {
+    echo "L23 missing guided setup command or mode: $command" >&2
+    exit 1
+  }
+done
+grep -Eqi 'missing|empty' "$l23"
+grep -Eqi 'deterministic|non-interactive|non-TTY' "$l23"
+grep -Eqi 'local.*stdio|stdio.*local' "$l23"
+grep -Eqi 'limited|Git-less' "$l23"
+grep -Eqi 'cancel|shutdown|child process' "$l23"
+grep -Eqi '0\.84\.1' "$l23"
+grep -Eqi 'credentials|secrets|private state' "$l23"
+
 echo "PASS: public learning path structure, readiness, links, and version alignment"

package/scripts/test-package-install.sh

@@ -331,4 +331,68 @@ fi
 [[ "$(sha256sum "$ROOT/package-lock.json" | cut -d' ' -f1)" == "$root_lock_before" ]] || fail "root lockfile changed during pack/install"
 [[ "$(sha256sum "$ROOT/mcp-memory-server/package-lock.json" | cut -d' ' -f1)" == "$server_lock_before" ]] || fail "server lockfile changed during pack/install"
 
+phase26_surface_complete=true
+for required in \
+  scripts/setup.mjs \
+  scripts/setup-core.mjs \
+  scripts/setup-reconcile.mjs \
+  schemas/cairnkeep-setup.schema.json \
+  schemas/cairnkeep-setup-policy.schema.json \
+  mcp-memory-server/dist/pi-mcp-bridge.js \
+  pi/extensions/cairnkeep-memory.ts \
+  docs/operating.md \
+  docs/harness-compatibility.md \
+  docs/native-windows.md \
+  docs/building-an-overlay.md
+do
+  [[ -f "$ROOT/$required" ]] || phase26_surface_complete=false
+done
+
+if [[ "$phase26_surface_complete" != true ]]; then
+  if [[ "${CAIRN_PHASE26_RED:-0}" == 1 ]]; then
+    echo "PHASE26_RED:SETUP_PACKAGE_MISSING"
+    exit 86
+  fi
+  echo "SKIP: packaged guided setup and Pi bridge surface is not complete"
+  echo "PASS: npm tarball installs a self-contained CLI and MCP server"
+  exit 0
+fi
+
+for required in \
+  scripts/setup.mjs \
+  scripts/setup-core.mjs \
+  scripts/setup-reconcile.mjs \
+  schemas/cairnkeep-setup.schema.json \
+  schemas/cairnkeep-setup-policy.schema.json \
+  mcp-memory-server/dist/pi-mcp-bridge.js \
+  pi/extensions/cairnkeep-memory.ts \
+  docs/operating.md \
+  docs/harness-compatibility.md \
+  docs/native-windows.md \
+  docs/building-an-overlay.md
+do
+  [[ -f "$installed_root/$required" ]] || fail "npm tarball omitted Phase 26 asset $required"
+done
+
+installed_setup_target="$tmp/Installed Setup – Unicode"
+(cd "$tmp" && cairn setup "$installed_setup_target" \
+  --git none --harness claude,pi --memory local --yes --json) >"$tmp/installed-setup.json" \
+  || fail "installed cairn setup failed outside the source checkout"
+node - "$tmp/installed-setup.json" "$installed_setup_target" <<'NODE'
+const fs = require("fs");
+const [resultPath, target] = process.argv.slice(2);
+const result = JSON.parse(fs.readFileSync(resultPath, "utf8"));
+if (result.schema_version !== 1 || result.status !== "limited") process.exit(1);
+if (result.git !== "none" || result.memory !== "local") process.exit(1);
+if (JSON.stringify(result.harnesses) !== JSON.stringify(["claude", "pi"])) process.exit(1);
+if (!fs.existsSync(`${target}/.ai/cairnkeep.json`)) process.exit(1);
+NODE
+
+if find "$installed_root" -type f \( \
+  -name '.env' -o -name '*.tmp' -o -name '*.bak' -o -name 'cairnkeep.json' \
+  -o -path '*/.planning/*' -o -path '*/.agentfs/*' \
+\) | grep -q .; then
+  fail "npm tarball included temporary or project-private setup state"
+fi
+
 echo "PASS: npm tarball installs a self-contained CLI and MCP server"

package/scripts/test-phase17-artifact-lifecycle.sh

@@ -48,7 +48,7 @@ run_shell_syntax_baseline() {
   local script
   while IFS= read -r script; do
     bash -n "$script" || return 1
-  done < <(find "$ROOT/bin" "$ROOT/scripts" -type f \( -name '*.sh' -o -name 'cairn' \) | sort)
+  done < <(find "$ROOT/bin" "$ROOT/scripts" -type f -name '*.sh' | sort)
 }
 
 run_baseline() {

package/scripts/test-phase18-capability-lifecycle.sh

@@ -142,7 +142,7 @@ run_baseline() {
   run_baseline_check "$ROOT/scripts/test-completion.sh"
   run_baseline_check "$ROOT/scripts/test-package-install.sh"
   run_baseline_check "$ROOT/scripts/test-uninstall.sh"
-  run_baseline_check bash -n "$ROOT/bin/cairn"
+  run_baseline_check node --check "$ROOT/bin/cairn"
   run_master_off_identity
   echo "PASS: Phase 18 master-off CLI/package/lifecycle identity baseline"
 }