squad-kit 0.2.1 → 0.3.0

package/dist/cli.js

@@ -172,7 +172,7 @@ function renderError(err) {
 // src/commands/init.ts
 import fs14 from "fs";
 import path6 from "path";
-import { input as input3, select as select3, checkbox, confirm as confirm5, password as password3 } from "@inquirer/prompts";
+import { input as input2, select as select3, checkbox, confirm as confirm5, password as password3 } from "@inquirer/prompts";
 
 // src/core/paths.ts
 import path from "path";
@@ -212,8 +212,8 @@ function requireSquadRoot(startDir = process.cwd()) {
   }
   return root;
 }
-function slugify(input6) {
-  return input6.toLowerCase().trim().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+function slugify(input5) {
+  return input5.toLowerCase().trim().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "").slice(0, 80);
 }
 
 // src/core/gitignore.ts
@@ -222,42 +222,38 @@ import path2 from "path";
 var SQUAD_SECRETS_PATTERN = ".squad/secrets.yaml";
 var SQUAD_ATTACHMENTS_PATTERN = ".squad/stories/**/attachments/";
 var SQUAD_TRASH_PATTERN = ".squad/.trash/";
+var SQUAD_LAST_RUN_PATTERN = ".squad/.last-run.json";
+var SQUAD_LAST_COPY_PROMPT_PATTERN = ".squad/.last-copy-prompt.md";
 var MANAGED_BLOCK_HEADER = "# Managed by squad-kit \u2014 do not edit this block";
 var MANAGED_BLOCK_FOOTER = "# End squad-kit block";
 function ensureGitignore(repoRoot) {
   const file = path2.join(repoRoot, ".gitignore");
   const text = fs2.existsSync(file) ? fs2.readFileSync(file, "utf8") : "";
-  if (text.includes(SQUAD_SECRETS_PATTERN) && text.includes(SQUAD_TRASH_PATTERN)) {
-    return false;
-  }
-  if (text.includes(SQUAD_SECRETS_PATTERN) && !text.includes(SQUAD_TRASH_PATTERN)) {
-    let next = text;
-    if (next.includes(SQUAD_ATTACHMENTS_PATTERN + "\n")) {
-      next = next.replace(
-        SQUAD_ATTACHMENTS_PATTERN + "\n",
-        SQUAD_ATTACHMENTS_PATTERN + "\n" + SQUAD_TRASH_PATTERN + "\n"
-      );
-    } else if (next.includes(MANAGED_BLOCK_FOOTER)) {
-      next = next.replace(MANAGED_BLOCK_FOOTER, SQUAD_TRASH_PATTERN + "\n" + MANAGED_BLOCK_FOOTER);
+  const requiredPatterns = [
+    SQUAD_SECRETS_PATTERN,
+    SQUAD_ATTACHMENTS_PATTERN,
+    SQUAD_TRASH_PATTERN,
+    SQUAD_LAST_RUN_PATTERN,
+    SQUAD_LAST_COPY_PROMPT_PATTERN
+  ];
+  const allPresent = requiredPatterns.every((p) => text.includes(p));
+  if (allPresent) return false;
+  if (!text.includes(SQUAD_SECRETS_PATTERN)) {
+    const block = ["", MANAGED_BLOCK_HEADER, ...requiredPatterns, MANAGED_BLOCK_FOOTER, ""].join("\n");
+    const next2 = text.length === 0 ? block.trimStart() : text.endsWith("\n") ? text + block : text + "\n" + block;
+    fs2.writeFileSync(file, next2, "utf8");
+    return true;
+  }
+  let next = text;
+  for (const pattern of requiredPatterns) {
+    if (next.includes(pattern)) continue;
+    if (next.includes(MANAGED_BLOCK_FOOTER)) {
+      next = next.replace(MANAGED_BLOCK_FOOTER, pattern + "\n" + MANAGED_BLOCK_FOOTER);
     } else {
-      next = next.replace(/\n?$/, (m) => m + SQUAD_TRASH_PATTERN + "\n");
-    }
-    if (next !== text) {
-      fs2.writeFileSync(file, next, "utf8");
-      return true;
+      next = next.replace(/\n?$/, (m) => m + pattern + "\n");
     }
   }
-  if (!text.includes(SQUAD_SECRETS_PATTERN)) {
-    const block = [
-      "",
-      MANAGED_BLOCK_HEADER,
-      SQUAD_SECRETS_PATTERN,
-      SQUAD_ATTACHMENTS_PATTERN,
-      SQUAD_TRASH_PATTERN,
-      MANAGED_BLOCK_FOOTER,
-      ""
-    ].join("\n");
-    const next = text.length === 0 ? block.trimStart() : text.endsWith("\n") ? text + block : text + "\n" + block;
+  if (next !== text) {
     fs2.writeFileSync(file, next, "utf8");
     return true;
   }
@@ -280,15 +276,15 @@ var DEFAULT_CONFIG = {
   planner: void 0
 };
 var FORBIDDEN_KEYS = ["apikey", "api_key", "token", "secret", "credential", "credentials"];
-function rejectSecretsInYaml(node, configFile, path25 = []) {
+function rejectSecretsInYaml(node, configFile, path26 = []) {
   if (node === null || typeof node !== "object") return;
   for (const [key, value] of Object.entries(node)) {
     if (FORBIDDEN_KEYS.includes(key.toLowerCase())) {
       throw new Error(
-        `Refusing to load ${configFile}: key "${[...path25, key].join(".")}" looks like a secret. Run \`squad config set planner\` or \`squad config set tracker\` to save it to .squad/secrets.yaml, then remove the key from config.yaml. Provider keys also work via ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY.`
+        `Refusing to load ${configFile}: key "${[...path26, key].join(".")}" looks like a secret. Run \`squad config set planner\` or \`squad config set tracker\` to save it to .squad/secrets.yaml, then remove the key from config.yaml. Provider keys also work via ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY.`
       );
     }
-    if (typeof value === "object") rejectSecretsInYaml(value, configFile, [...path25, key]);
+    if (typeof value === "object") rejectSecretsInYaml(value, configFile, [...path26, key]);
   }
 }
 function mergePlanner(base, override) {
@@ -306,6 +302,9 @@ function mergePlanner(base, override) {
     modelOverride: {
       ...base?.modelOverride ?? {},
       ...override.modelOverride ?? {}
+    },
+    cache: {
+      enabled: override.cache?.enabled ?? base?.cache?.enabled ?? true
     }
   };
   if (merged.modelOverride) {
@@ -350,6 +349,20 @@ function loadConfig(configFile) {
   rejectSecretsInYaml(parsed, configFile);
   const merged = mergeConfig(DEFAULT_CONFIG, parsed);
   validateModelOverride(merged.planner?.modelOverride, configFile);
+  if (merged.planner?.cache !== void 0) {
+    const c = merged.planner.cache;
+    if (typeof c !== "object" || c === null || Array.isArray(c)) {
+      throw new Error(
+        `planner.cache in ${configFile} must be an object with \`enabled: true\` or \`false\`. Run \`squad config set planner\` to set prompt caching.`
+      );
+    }
+    const ce = c.enabled;
+    if (typeof ce !== "boolean") {
+      throw new Error(
+        `planner.cache.enabled in ${configFile} must be a boolean (not a quoted string). Run \`squad config set planner\` to set prompt caching, or use \`true\` or \`false\` unquoted in YAML.`
+      );
+    }
+  }
   if (merged.planner?.enabled) {
     if (!["anthropic", "openai", "google"].includes(merged.planner.provider)) {
       throw new Error(
@@ -696,7 +709,7 @@ async function runConfigShow(opts) {
 
 // src/commands/config/set-planner.ts
 import fs9 from "fs";
-import { confirm as confirm2, input as input2, password as password2, select } from "@inquirer/prompts";
+import { confirm as confirm2, password as password2, select } from "@inquirer/prompts";
 
 // src/tracker/env-overlay.ts
 function overlayTrackerEnv(base) {
@@ -842,7 +855,8 @@ function newPlannerBlock(provider) {
       maxFileReads: 25,
       maxContextBytes: 5e4,
       maxDurationSeconds: 180
-    }
+    },
+    cache: { enabled: true }
   };
 }
 function mergePlannerKeyIntoSecrets(base, provider, key) {
@@ -993,22 +1007,11 @@ async function runConfigSetPlanner(opts = {}) {
       success("Planner key saved to .squad/secrets.yaml");
       info(".squad/secrets.yaml updated (chmod 0600 on POSIX)");
     }
-    const wantOverride = await confirm2({
-      message: "Set a custom plan-phase model id (planner.modelOverride)?",
-      default: false
+    const cacheEnabled = await confirm2({
+      message: "Enable prompt caching? (Recommended \u2014 reduces billed tokens by ~70% on most providers.)",
+      default: nextPlanner.cache?.enabled ?? true
     });
-    if (wantOverride) {
-      const modelId = await input2({
-        message: "Plan model id (leave empty to use the default for this provider):",
-        default: ""
-      });
-      if (modelId.trim().length > 0 && nextPlanner) {
-        nextPlanner = {
-          ...nextPlanner,
-          modelOverride: { ...nextPlanner.modelOverride ?? {}, [provider]: modelId.trim() }
-        };
-      }
-    }
+    nextPlanner = { ...nextPlanner, cache: { enabled: cacheEnabled } };
   }
   const next = { ...config2, planner: nextPlanner };
   saveConfig(paths.configFile, next);
@@ -1029,6 +1032,7 @@ async function runConfigSetPlanner(opts = {}) {
     kv("credential", `${cred.source} (${sourceText})`, 10);
   }
   if (process.env.CI === "true" || !cred) {
+    printPlannerNextSteps(Boolean(cred));
     return;
   }
   const listed = await fetchProviderModelIds(provider, cred.value);
@@ -1042,6 +1046,23 @@ async function runConfigSetPlanner(opts = {}) {
   } else {
     info("Credential check: models API responded OK for this key.");
   }
+  printPlannerNextSteps(true);
+}
+function printPlannerNextSteps(credentialReady) {
+  blank();
+  step("Next:");
+  if (!credentialReady) {
+    info("1) Save a planner key: re-run `squad config set planner` and paste the key when prompted.");
+    info("2) Verify with `squad doctor` \u2014 all planner checks should turn green.");
+    info("3) Then run `squad new-story <slug>` and `squad new-plan --api` to generate your first plan.");
+    return;
+  }
+  info("1) Verify with `squad doctor` \u2014 every planner check should be green.");
+  info("2) Create a story:  squad new-story <feature-slug>  (or --no-tracker for a manual story).");
+  info("3) Fill the generated intake.md, then run `squad new-plan --api` to generate the plan.");
+  info(
+    "4) To change provider, key, or disable caching later: re-run `squad config set planner`. Model overrides are edited directly in .squad/config.yaml (planner.modelOverride)."
+  );
 }
 
 // src/commands/config/set-tracker.ts
@@ -1526,6 +1547,7 @@ async function runConfigSetTracker(opts = {}) {
     kv("project", next.tracker.project, 10);
   }
   if (process.env.CI === "true") {
+    printTrackerNextSteps(next.tracker.type);
     return;
   }
   const reloaded = loadConfig(paths.configFile);
@@ -1549,6 +1571,20 @@ async function runConfigSetTracker(opts = {}) {
       );
     }
   }
+  printTrackerNextSteps(next.tracker.type);
+}
+function printTrackerNextSteps(type) {
+  blank();
+  step("Next:");
+  if (type === "none") {
+    info("1) Tracker is off. Create stories manually with `squad new-story <slug> --no-tracker`.");
+    info("2) Re-enable any time with `squad config set tracker`.");
+    return;
+  }
+  info("1) Verify with `squad doctor` \u2014 tracker checks should be green.");
+  info(`2) Create a story: squad new-story <feature-slug> --id <${type === "jira" ? "JIRA-123" : "azure-work-item-id"}>`);
+  info("   squad-kit auto-fetches the title, description, and attachments into the intake.");
+  info("3) Review the generated intake.md, then run `squad new-plan --api` to generate the plan.");
 }
 
 // src/commands/config/unset-tracker.ts
@@ -1671,8 +1707,8 @@ async function runInit(opts) {
     agents: parseAgentsFlag(opts.agents)
   };
   const answers = opts.yes ? defaults : {
-    name: await input3({ message: "Project name", default: defaults.name }),
-    language: await input3({ message: "Primary language", default: defaults.language }),
+    name: await input2({ message: "Project name", default: defaults.name }),
+    language: await input2({ message: "Primary language", default: defaults.language }),
     tracker: await select3({
       message: "Issue tracker",
       choices: [
@@ -1893,7 +1929,7 @@ Plan meta-prompts (\`generate-plan.md\`, \`story-skeleton.md\`) ship inside the
 // src/commands/new-story.ts
 import fs16 from "fs";
 import path8 from "path";
-import { input as input4, select as select4 } from "@inquirer/prompts";
+import { input as input3, select as select4 } from "@inquirer/prompts";
 
 // src/core/stories.ts
 import fs15 from "fs";
@@ -2024,7 +2060,7 @@ async function runNewStory(featureSlug, opts) {
       }
     }
     if (!featureSlugInput) {
-      featureSlugInput = (await input4({
+      featureSlugInput = (await input3({
         message: "New feature slug (kebab-case):",
         validate: validateFeatureSlugForPrompt
       })).trim();
@@ -2063,7 +2099,7 @@ async function runNewStory(featureSlug, opts) {
       noTracker = true;
       trackerNeedsId = false;
     } else {
-      id = (await input4({
+      id = (await input3({
         message: `${config2.tracker.type} work-item id:`,
         validate: (v) => validateTrackerId(config2.tracker.type, v.trim()) ? true : `Invalid ${config2.tracker.type} id format.`
       })).trim();
@@ -2082,12 +2118,12 @@ async function runNewStory(featureSlug, opts) {
         );
       }
     } else {
-      title = (await input4({ message: "Short story title:" })).trim();
+      title = (await input3({ message: "Short story title:" })).trim();
       if (!title) throw new Error("Title cannot be empty. Run `squad new-story` again and enter a short title, or add `--yes` to fail fast in scripts.");
     }
   }
   if (interactive && !title) {
-    const maybe = (await input4({ message: "Short title (optional, press Enter to skip):", default: "" })).trim();
+    const maybe = (await input3({ message: "Short title (optional, press Enter to skip):", default: "" })).trim();
     if (maybe) title = maybe;
   }
   const storyFolderName = id ? trackerIdForFilename(config2.tracker.type, id) : slugify(title ?? "");
@@ -2279,29 +2315,96 @@ function ensureFeatureOverview(featurePlanDir, slug) {
 }
 
 // src/commands/new-plan.ts
-import fs21 from "fs";
-import path14 from "path";
+import fs22 from "fs";
+import path15 from "path";
 import { confirm as confirm6, select as select5 } from "@inquirer/prompts";
 
 // src/utils/clipboard.ts
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 async function copyToClipboard(text) {
-  const cmd = clipboardCommand();
-  if (!cmd) return false;
+  const candidates = clipboardCandidates();
+  if (candidates.length === 0) {
+    return { ok: false, reason: noCandidateReason() };
+  }
+  let lastReason;
+  for (const cmd of candidates) {
+    const reason = cmd.unavailableReason?.();
+    if (reason) {
+      lastReason = reason;
+      continue;
+    }
+    const res = await tryCopy(cmd, text);
+    if (res.ok) return res;
+    lastReason = res.reason;
+  }
+  return { ok: false, reason: lastReason ?? "no working clipboard tool found" };
+}
+function tryCopy(cmd, text) {
   return new Promise((resolve) => {
-    const child = spawn(cmd.command, cmd.args, { stdio: ["pipe", "ignore", "ignore"] });
-    child.on("error", () => resolve(false));
-    child.on("close", (code) => resolve(code === 0));
-    child.stdin.write(text);
-    child.stdin.end();
+    let child;
+    try {
+      child = spawn(cmd.command, cmd.args, { stdio: ["pipe", "ignore", "pipe"] });
+    } catch (err) {
+      resolve({ ok: false, reason: `${cmd.command} failed to spawn: ${err.message}` });
+      return;
+    }
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (err) => {
+      resolve({ ok: false, reason: `${cmd.command} spawn error: ${err.message}` });
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ ok: true, tool: cmd.command });
+      } else {
+        resolve({
+          ok: false,
+          reason: `${cmd.command} exited with code ${code}${stderr ? `: ${stderr.trim().slice(0, 200)}` : ""}`
+        });
+      }
+    });
+    child.stdin?.write(text);
+    child.stdin?.end();
   });
 }
-function clipboardCommand() {
-  if (process.platform === "darwin") return { command: "pbcopy", args: [] };
-  if (process.platform === "win32") return { command: "clip", args: [] };
-  if (process.env.WAYLAND_DISPLAY) return { command: "wl-copy", args: [] };
-  if (process.env.DISPLAY) return { command: "xclip", args: ["-selection", "clipboard"] };
-  return null;
+function clipboardCandidates() {
+  if (process.platform === "darwin") {
+    return [{ command: "pbcopy", args: [] }];
+  }
+  if (process.platform === "win32") {
+    return [{ command: "clip", args: [] }];
+  }
+  const out = [];
+  if (process.env.WAYLAND_DISPLAY) {
+    out.push({ command: "wl-copy", args: [], unavailableReason: hasBinary("wl-copy") });
+  }
+  if (process.env.DISPLAY) {
+    out.push({ command: "xclip", args: ["-selection", "clipboard"], unavailableReason: hasBinary("xclip") });
+    out.push({ command: "xsel", args: ["--clipboard", "--input"], unavailableReason: hasBinary("xsel") });
+  }
+  if (process.env.TERMUX_VERSION) {
+    out.push({ command: "termux-clipboard-set", args: [], unavailableReason: hasBinary("termux-clipboard-set") });
+  }
+  return out;
+}
+function hasBinary(bin) {
+  return () => {
+    const which = process.platform === "win32" ? "where" : "which";
+    const res = spawnSync(which, [bin], { stdio: "ignore" });
+    if (res.status === 0) return void 0;
+    return `${bin} not found on PATH`;
+  };
+}
+function noCandidateReason() {
+  if (process.platform === "linux") {
+    if (!process.env.DISPLAY && !process.env.WAYLAND_DISPLAY && !process.env.TERMUX_VERSION) {
+      return "no display server detected (headless / SSH) \u2014 install xclip or xsel, or use the saved file";
+    }
+    return "no clipboard tool detected \u2014 install xclip, xsel, or wl-copy";
+  }
+  return `no clipboard tool detected on ${process.platform}`;
 }
 
 // src/planner/loop.ts
@@ -2323,8 +2426,8 @@ var READ_FILE_TOOL = {
   }
 };
 var MAX_BYTES_PER_READ = 32e3;
-function readFileTool(root, budget, input6) {
-  const raw = input6?.path;
+function readFileTool(root, budget, input5) {
+  const raw = input5?.path;
   if (typeof raw !== "string" || raw.length === 0) {
     return error('read_file: missing or invalid "path" argument.');
   }
@@ -2437,7 +2540,8 @@ function rateLimitMessage(err) {
     google: "https://aistudio.google.com/app/plan_information"
   };
   const headline = err.retryAfterSec ? `${err.provider} rate limit hit \u2014 provider asked us to wait ${err.retryAfterSec}s before retrying.` : `${err.provider} rate limit hit.`;
-  const retried = err.retryAlreadyAttempted ? "squad-kit already retried once automatically and was throttled again \u2014 your org is firmly over its per-minute quota." : "squad-kit aborted before retrying.";
+  const cap = err.maxRetrySec ?? 90;
+  const retried = err.retrySkippedReason === "retry_after_too_long" ? `squad-kit did not auto-retry: the provider's ${err.retryAfterSec}s wait is longer than our ${cap}s cap, so retrying would just burn another request inside the same throttle window.` : err.retryAlreadyAttempted ? "squad-kit already retried once automatically and was throttled again \u2014 your org is firmly over its per-minute quota." : "squad-kit aborted before retrying.";
   return [
     headline,
     retried,
@@ -2454,109 +2558,16 @@ function rateLimitMessage(err) {
   ].join("\n");
 }
 
-// src/planner/loop.ts
-var MAX_RATE_LIMIT_RETRY_SEC = 30;
-var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-async function runPlanner(input6) {
-  const maxIter = input6.maxIterations ?? 40;
-  const turns = [{ role: "user", text: input6.userPrompt }];
-  let accumulatedText = "";
-  let iterations = 0;
-  let budgetExhausted = false;
-  let finishedNormally = false;
-  while (iterations < maxIter) {
-    iterations += 1;
-    if (input6.budget.timedOut()) {
-      return { planText: accumulatedText, budgetExhausted, timedOut: true, finishedNormally: false, iterations };
-    }
-    if (input6.budget.overCost()) {
-      return { planText: accumulatedText, budgetExhausted: true, timedOut: false, finishedNormally: false, iterations };
-    }
-    const request = {
-      systemPrompt: input6.systemPrompt,
-      model: input6.model,
-      tools: [READ_FILE_TOOL],
-      turns,
-      apiKey: input6.apiKey,
-      maxOutputTokens: 8192
-    };
-    let response = await input6.provider.send(request);
-    if (response.usage) {
-      input6.budget.recordUsage(response.usage);
-      input6.onUsage?.(response.usage);
-    }
-    let retriedRateLimit = false;
-    if (response.stopReason === "error" && response.errorKind === "rate_limit") {
-      const waitSec = Math.min(response.retryAfterSec ?? 10, MAX_RATE_LIMIT_RETRY_SEC);
-      input6.onRateLimit?.(waitSec);
-      await (input6.sleep ?? defaultSleep)(waitSec * 1e3);
-      response = await input6.provider.send(request);
-      if (response.usage) {
-        input6.budget.recordUsage(response.usage);
-        input6.onUsage?.(response.usage);
-      }
-      retriedRateLimit = true;
-    }
-    if (response.stopReason === "error") {
-      throw composePlannerError(input6.provider.name, response, retriedRateLimit);
-    }
-    if (response.text) {
-      accumulatedText += response.text;
-      input6.onAssistantText?.(response.text);
-    }
-    if (response.stopReason === "max_tokens" && !response.toolCalls?.length) {
-      return { planText: accumulatedText, budgetExhausted, timedOut: false, finishedNormally: false, iterations };
-    }
-    if (response.stopReason === "end_turn" || !response.toolCalls?.length) {
-      finishedNormally = true;
-      return { planText: accumulatedText, budgetExhausted, timedOut: false, finishedNormally, iterations };
-    }
-    turns.push({
-      role: "assistant",
-      text: response.text,
-      toolCalls: response.toolCalls
-    });
-    const toolResults = [];
-    for (const tc of response.toolCalls) {
-      if (tc.name !== READ_FILE_TOOL.name) {
-        toolResults.push({ toolCallId: tc.id, content: `unknown tool "${tc.name}"`, isError: true });
-        continue;
-      }
-      const before = input6.budget.snapshot().bytes;
-      const result = readFileTool(input6.root, input6.budget, tc.input);
-      const after = input6.budget.snapshot().bytes;
-      input6.onToolCall?.(tc, after - before, after);
-      if (result.isError && (/budget/i.test(result.content) || /max file reads/i.test(result.content))) {
-        budgetExhausted = true;
-      }
-      toolResults.push({ toolCallId: tc.id, content: result.content, isError: result.isError });
-    }
-    turns.push({ role: "user", toolResults });
-    if (budgetExhausted) {
-      turns.push({
-        role: "user",
-        text: "Budget is exhausted. Finalise the plan with the information you already have. Do not call any more tools. Output the complete plan markdown now."
-      });
-    }
-  }
-  return { planText: accumulatedText, budgetExhausted, timedOut: false, finishedNormally: false, iterations };
-}
-function composePlannerError(providerName, response, retriedRateLimit) {
-  if (response.errorKind === "rate_limit") {
-    return new Error(
-      rateLimitMessage({
-        provider: providerName,
-        retryAfterSec: response.retryAfterSec,
-        rawBody: response.rawError ?? "",
-        retryAlreadyAttempted: retriedRateLimit
-      })
-    );
-  }
-  if (response.errorKind === "model_not_found") {
-    return new Error(response.rawError ?? "planner: model not found");
+// src/planner/stable-json.ts
+function sortRecordKeys(v) {
+  if (v === null || typeof v !== "object") return v;
+  if (Array.isArray(v)) return v.map((x) => sortRecordKeys(x));
+  const o = v;
+  const out = {};
+  for (const k of Object.keys(o).sort()) {
+    out[k] = sortRecordKeys(o[k]);
   }
-  const base = response.rawError ?? "planner: provider error";
-  return new Error(`${base} Run \`squad doctor\` to diagnose, or retry \u2014 most 5xx errors are transient.`);
+  return out;
 }
 
 // src/planner/providers/anthropic.ts
@@ -2568,14 +2579,39 @@ var anthropicProvider = {
     return callAnthropic(req);
   }
 };
-async function callAnthropic(req) {
-  const body = {
+function buildAnthropicBody(req) {
+  if (req.cacheEnabled === false) {
+    const base2 = {
+      model: req.model,
+      max_tokens: req.maxOutputTokens ?? 4096,
+      system: req.systemPrompt,
+      tools: req.tools.map(toAnthropicTool)
+    };
+    if (req.turns.length === 0) {
+      return base2;
+    }
+    return { ...base2, messages: req.turns.map((t) => toAnthropicMessage(t)) };
+  }
+  const base = {
     model: req.model,
     max_tokens: req.maxOutputTokens ?? 4096,
-    system: req.systemPrompt,
-    tools: req.tools.map(toAnthropicTool),
-    messages: req.turns.map(toAnthropicMessage)
+    system: [
+      {
+        type: "text",
+        text: req.systemPrompt,
+        cache_control: { type: "ephemeral" }
+      }
+    ],
+    tools: req.tools.map(toAnthropicTool)
   };
+  if (req.turns.length === 0) {
+    return base;
+  }
+  return { ...base, messages: toMessagesWithCacheMarkers(req.turns) };
+}
+async function callAnthropic(req) {
+  const built = buildAnthropicBody(req);
+  const body = { ...built, messages: built.messages ?? [] };
   const res = await fetch(API_URL, {
     method: "POST",
     headers: {
@@ -2615,26 +2651,73 @@ async function callAnthropic(req) {
     stopReason: mapStop(json.stop_reason),
     usage: {
       inputTokens: json.usage?.input_tokens ?? 0,
-      outputTokens: json.usage?.output_tokens ?? 0
+      outputTokens: json.usage?.output_tokens ?? 0,
+      cacheCreationTokens: json.usage?.cache_creation_input_tokens ?? 0,
+      cacheReadTokens: json.usage?.cache_read_input_tokens ?? 0
     }
   };
 }
+function toMessagesWithCacheMarkers(turns) {
+  let lastUserWithToolResultIdx = -1;
+  for (let i = turns.length - 1; i >= 0; i -= 1) {
+    const t = turns[i];
+    if (t.role === "user" && hasToolResultBlock(t)) {
+      lastUserWithToolResultIdx = i;
+      break;
+    }
+  }
+  return turns.map((turn, idx) => {
+    const message = toAnthropicMessage(turn);
+    if (idx === lastUserWithToolResultIdx) {
+      return attachCacheControlToLastToolResult(message);
+    }
+    return message;
+  });
+}
+function hasToolResultBlock(turn) {
+  return (turn.toolResults?.length ?? 0) > 0;
+}
+function attachCacheControlToLastToolResult(msg) {
+  const content = [...msg.content];
+  for (let i = content.length - 1; i >= 0; i -= 1) {
+    const block = content[i];
+    if (block.type === "tool_result") {
+      content[i] = { ...block, cache_control: { type: "ephemeral" } };
+      break;
+    }
+  }
+  return { ...msg, content };
+}
 function toAnthropicTool(t) {
-  return { name: t.name, description: t.description, input_schema: t.inputSchema };
+  return {
+    name: t.name,
+    description: t.description,
+    input_schema: sortRecordKeys(t.inputSchema)
+  };
 }
 function toAnthropicMessage(turn) {
   const blocks = [];
   if (turn.text) blocks.push({ type: "text", text: turn.text });
-  if (turn.toolCalls)
-    for (const tc of turn.toolCalls) blocks.push({ type: "tool_use", id: tc.id, name: tc.name, input: tc.input });
-  if (turn.toolResults)
-    for (const tr of turn.toolResults)
+  if (turn.toolCalls) {
+    for (const tc of turn.toolCalls) {
+      blocks.push({
+        type: "tool_use",
+        id: tc.id,
+        name: tc.name,
+        input: sortRecordKeys(tc.input)
+      });
+    }
+  }
+  if (turn.toolResults) {
+    for (const tr of turn.toolResults) {
       blocks.push({
         type: "tool_result",
         tool_use_id: tr.toolCallId,
         content: tr.content,
         is_error: tr.isError ?? false
       });
+    }
+  }
   return { role: turn.role === "assistant" ? "assistant" : "user", content: blocks };
 }
 function mapStop(r) {
@@ -2651,15 +2734,23 @@ var openaiProvider = {
     return callOpenAI(req);
   }
 };
-async function callOpenAI(req) {
-  const messages = [{ role: "system", content: req.systemPrompt }];
-  for (const turn of req.turns) messages.push(...toOpenAIMessages(turn));
-  const body = {
+function buildOpenAIBody(req) {
+  const base = {
     model: req.model,
-    messages,
-    tools: req.tools.map(toOpenAITool),
-    max_completion_tokens: req.maxOutputTokens ?? 4096
+    max_completion_tokens: req.maxOutputTokens ?? 4096,
+    tools: req.tools.map(toOpenAITool)
   };
+  if (req.turns.length === 0) {
+    return base;
+  }
+  const messages = [{ role: "system", content: req.systemPrompt }];
+  for (const turn of req.turns) messages.push(...toOpenAIMessages(turn));
+  return { ...base, messages };
+}
+async function callOpenAI(req) {
+  const built = buildOpenAIBody(req);
+  const messages = built.messages && built.messages.length > 0 ? built.messages : [{ role: "system", content: req.systemPrompt }];
+  const body = { ...built, messages };
   const res = await fetch(API_URL2, {
     method: "POST",
     headers: {
@@ -2709,7 +2800,14 @@ async function callOpenAI(req) {
   };
 }
 function toOpenAITool(t) {
-  return { type: "function", function: { name: t.name, description: t.description, parameters: t.inputSchema } };
+  return {
+    type: "function",
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: sortRecordKeys(t.inputSchema)
+    }
+  };
 }
 function toOpenAIMessages(turn) {
   const out = [];
@@ -2720,7 +2818,10 @@ function toOpenAIMessages(turn) {
       tool_calls: turn.toolCalls?.map((tc) => ({
         id: tc.id,
         type: "function",
-        function: { name: tc.name, arguments: JSON.stringify(tc.input) }
+        function: {
+          name: tc.name,
+          arguments: JSON.stringify(sortRecordKeys(tc.input))
+        }
       }))
     });
   } else {
@@ -2740,7 +2841,7 @@ function mapStop2(r) {
 }
 function safeJson(raw) {
   try {
-    return JSON.parse(raw);
+    return sortRecordKeys(JSON.parse(raw));
   } catch {
     return {};
   }
@@ -2754,14 +2855,23 @@ var googleProvider = {
     return callGoogle(req);
   }
 };
-async function callGoogle(req) {
-  const url = `${API_BASE}/${encodeURIComponent(req.model)}:generateContent?key=${encodeURIComponent(req.apiKey)}`;
-  const body = {
+function buildGoogleBody(req) {
+  const base = {
     system_instruction: { parts: [{ text: req.systemPrompt }] },
-    contents: req.turns.map(toGoogleContent),
-    tools: req.tools.length ? [{ functionDeclarations: req.tools.map(toGoogleTool) }] : void 0,
     generationConfig: { maxOutputTokens: req.maxOutputTokens ?? 4096 }
   };
+  if (req.tools.length) {
+    base.tools = [{ functionDeclarations: req.tools.map(toGoogleTool) }];
+  }
+  if (req.turns.length === 0) {
+    return base;
+  }
+  return { ...base, contents: req.turns.map(toGoogleContent) };
+}
+async function callGoogle(req) {
+  const url = `${API_BASE}/${encodeURIComponent(req.model)}:generateContent?key=${encodeURIComponent(req.apiKey)}`;
+  const built = buildGoogleBody(req);
+  const body = { ...built, contents: built.contents ?? [] };
   const res = await fetch(url, {
     method: "POST",
     headers: { "content-type": "application/json" },
@@ -2796,7 +2906,7 @@ async function callGoogle(req) {
   const toolCalls = parts.filter((p) => "functionCall" in p && !!p.functionCall).map((p, i) => ({
     id: `gcall_${i}_${p.functionCall.name}`,
     name: p.functionCall.name,
-    input: p.functionCall.args ?? {}
+    input: p.functionCall.args ? sortRecordKeys(p.functionCall.args) : {}
   }));
   return {
     text: textOut || void 0,
@@ -2809,14 +2919,17 @@ async function callGoogle(req) {
   };
 }
 function toGoogleTool(t) {
-  return { name: t.name, description: t.description, parameters: t.inputSchema };
+  return { name: t.name, description: t.description, parameters: sortRecordKeys(t.inputSchema) };
 }
 function toGoogleContent(turn) {
   const role = turn.role === "assistant" ? "model" : "user";
   const parts = [];
   if (turn.text) parts.push({ text: turn.text });
-  if (turn.toolCalls)
-    for (const tc of turn.toolCalls) parts.push({ functionCall: { name: tc.name, args: tc.input } });
+  if (turn.toolCalls) {
+    for (const tc of turn.toolCalls) {
+      parts.push({ functionCall: { name: tc.name, args: sortRecordKeys(tc.input) } });
+    }
+  }
   if (turn.toolResults) {
     for (const tr of turn.toolResults) {
       parts.push({
@@ -2836,6 +2949,208 @@ function mapStop3(r) {
   return "tool_use";
 }
 
+// src/planner/providers/prefix.ts
+function prefixOf(provider, req) {
+  const trimmed = { ...req, turns: req.turns.slice(0, -1) };
+  const s = (() => {
+    switch (provider) {
+      case "anthropic":
+        return JSON.stringify(buildAnthropicBody(trimmed));
+      case "openai":
+        return JSON.stringify(buildOpenAIBody(trimmed));
+      case "google":
+        return JSON.stringify(buildGoogleBody(trimmed));
+    }
+  })();
+  return s.length > 0 ? s.slice(0, -1) : s;
+}
+
+// src/planner/loop.ts
+var MAX_RATE_LIMIT_RETRY_SEC = 90;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function buildPlannerRunStats(budget, turns, runStartedAt) {
+  const u = budget.snapshot().usage;
+  const cacheRead = u.cacheReadTokens ?? 0;
+  const cacheCreate = u.cacheCreationTokens ?? 0;
+  const inTok = u.inputTokens;
+  const outTok = u.outputTokens;
+  const totalInput = inTok + cacheRead;
+  const cacheHitRatio = totalInput === 0 ? 0 : Math.round(cacheRead / totalInput * 100) / 100;
+  return {
+    turns,
+    inputTokens: inTok,
+    outputTokens: outTok,
+    cacheCreationTokens: cacheCreate,
+    cacheReadTokens: cacheRead,
+    cacheHitRatio,
+    durationMs: Date.now() - runStartedAt
+  };
+}
+async function runPlanner(input5) {
+  const runStartedAt = Date.now();
+  const maxIter = input5.maxIterations ?? 40;
+  const turns = [{ role: "user", text: input5.userPrompt }];
+  let accumulatedText = "";
+  let iterations = 0;
+  let budgetExhausted = false;
+  let finishedNormally = false;
+  let prevRequestPrefix;
+  while (iterations < maxIter) {
+    iterations += 1;
+    if (input5.budget.timedOut()) {
+      return {
+        planText: accumulatedText,
+        budgetExhausted,
+        timedOut: true,
+        finishedNormally: false,
+        iterations,
+        stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
+      };
+    }
+    if (input5.budget.overCost()) {
+      return {
+        planText: accumulatedText,
+        budgetExhausted: true,
+        timedOut: false,
+        finishedNormally: false,
+        iterations,
+        stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
+      };
+    }
+    const request = {
+      systemPrompt: input5.systemPrompt,
+      model: input5.model,
+      tools: [READ_FILE_TOOL],
+      turns,
+      apiKey: input5.apiKey,
+      maxOutputTokens: 8192,
+      cacheEnabled: input5.cacheEnabled ?? true
+    };
+    if (process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test" && prevRequestPrefix !== void 0) {
+      const currentPrefix = prefixOf(input5.provider.name, request);
+      if (!currentPrefix.startsWith(prevRequestPrefix)) {
+        const byte = firstByteDiff(prevRequestPrefix, currentPrefix);
+        warning(
+          `planner: prefix mutation at turn ${iterations}, byte ${byte} \u2014 caching will not hit.`
+        );
+      }
+    }
+    let response = await input5.provider.send(request);
+    if (response.usage) {
+      input5.budget.recordUsage(response.usage);
+      input5.onUsage?.(response.usage);
+    }
+    let retriedRateLimit = false;
+    let retrySkippedReason;
+    if (response.stopReason === "error" && response.errorKind === "rate_limit") {
+      const asked = response.retryAfterSec;
+      if (asked !== void 0 && asked > MAX_RATE_LIMIT_RETRY_SEC) {
+        retrySkippedReason = "retry_after_too_long";
+      } else {
+        const waitSec = Math.min(asked ?? 10, MAX_RATE_LIMIT_RETRY_SEC);
+        input5.onRateLimit?.(waitSec);
+        await (input5.sleep ?? defaultSleep)(waitSec * 1e3);
+        response = await input5.provider.send(request);
+        if (response.usage) {
+          input5.budget.recordUsage(response.usage);
+          input5.onUsage?.(response.usage);
+        }
+        retriedRateLimit = true;
+      }
+    }
+    if (response.stopReason === "error") {
+      throw composePlannerError(input5.provider.name, response, retriedRateLimit, retrySkippedReason);
+    }
+    prevRequestPrefix = prefixOf(input5.provider.name, request);
+    if (response.text) {
+      accumulatedText += response.text;
+      input5.onAssistantText?.(response.text);
+    }
+    if (response.stopReason === "max_tokens" && !response.toolCalls?.length) {
+      return {
+        planText: accumulatedText,
+        budgetExhausted,
+        timedOut: false,
+        finishedNormally: false,
+        iterations,
+        stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
+      };
+    }
+    if (response.stopReason === "end_turn" || !response.toolCalls?.length) {
+      finishedNormally = true;
+      return {
+        planText: accumulatedText,
+        budgetExhausted,
+        timedOut: false,
+        finishedNormally,
+        iterations,
+        stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
+      };
+    }
+    turns.push({
+      role: "assistant",
+      text: response.text,
+      toolCalls: response.toolCalls
+    });
+    const toolResults = [];
+    for (const tc of response.toolCalls) {
+      if (tc.name !== READ_FILE_TOOL.name) {
+        toolResults.push({ toolCallId: tc.id, content: `unknown tool "${tc.name}"`, isError: true });
+        continue;
+      }
+      const before = input5.budget.snapshot().bytes;
+      const result = readFileTool(input5.root, input5.budget, tc.input);
+      const after = input5.budget.snapshot().bytes;
+      input5.onToolCall?.(tc, after - before, after);
+      if (result.isError && (/budget/i.test(result.content) || /max file reads/i.test(result.content))) {
+        budgetExhausted = true;
+      }
+      toolResults.push({ toolCallId: tc.id, content: result.content, isError: result.isError });
+    }
+    turns.push({ role: "user", toolResults });
+    if (budgetExhausted) {
+      turns.push({
+        role: "user",
+        text: "Budget is exhausted. Finalise the plan with the information you already have. Do not call any more tools. Output the complete plan markdown now."
+      });
+    }
+  }
+  return {
+    planText: accumulatedText,
+    budgetExhausted,
+    timedOut: false,
+    finishedNormally: false,
+    iterations,
+    stats: buildPlannerRunStats(input5.budget, iterations, runStartedAt)
+  };
+}
+function firstByteDiff(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i += 1) {
+    if (a.charCodeAt(i) !== b.charCodeAt(i)) return i;
+  }
+  return n;
+}
+function composePlannerError(providerName, response, retriedRateLimit, retrySkippedReason) {
+  if (response.errorKind === "rate_limit") {
+    return new Error(
+      rateLimitMessage({
+        provider: providerName,
+        retryAfterSec: response.retryAfterSec,
+        rawBody: response.rawError ?? "",
+        retryAlreadyAttempted: retriedRateLimit,
+        retrySkippedReason,
+        maxRetrySec: MAX_RATE_LIMIT_RETRY_SEC
+      })
+    );
+  }
+  if (response.errorKind === "model_not_found") {
+    return new Error(response.rawError ?? "planner: model not found");
+  }
+  const base = response.rawError ?? "planner: provider error";
+  return new Error(`${base} Run \`squad doctor\` to diagnose, or retry \u2014 most 5xx errors are transient.`);
+}
+
 // src/planner/providers/index.ts
 function providerFor(name) {
   switch (name) {
@@ -2857,7 +3172,7 @@ var Budget = class {
   reads = 0;
   bytes = 0;
   startedAt = Date.now();
-  totalUsage = { inputTokens: 0, outputTokens: 0 };
+  totalUsage = { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
   canRead(nextFileBytes) {
     if (this.reads >= this.cfg.maxFileReads) {
       return { ok: false, reason: `max file reads (${this.cfg.maxFileReads}) reached` };
@@ -2875,6 +3190,8 @@ var Budget = class {
     this.totalUsage.inputTokens += u.inputTokens;
     this.totalUsage.outputTokens += u.outputTokens;
     if (u.costUsd !== void 0) this.totalUsage.costUsd = (this.totalUsage.costUsd ?? 0) + u.costUsd;
+    this.totalUsage.cacheCreationTokens = (this.totalUsage.cacheCreationTokens ?? 0) + (u.cacheCreationTokens ?? 0);
+    this.totalUsage.cacheReadTokens = (this.totalUsage.cacheReadTokens ?? 0) + (u.cacheReadTokens ?? 0);
   }
   timedOut() {
     return (Date.now() - this.startedAt) / 1e3 > this.cfg.maxDurationSeconds;
@@ -3020,8 +3337,8 @@ function formatSequence(n) {
 }
 
 // src/planner/writer.ts
-function writePlanFile(input6) {
-  const { paths, config: config2, story } = input6;
+function writePlanFile(input5) {
+  const { paths, config: config2, story } = input5;
   const featurePlanDir = path13.join(paths.plansDir, story.feature);
   fs20.mkdirSync(featurePlanDir, { recursive: true });
   const existing = findExistingPlan(featurePlanDir, story.id);
@@ -3040,9 +3357,9 @@ function writePlanFile(input6) {
     const trackerPart = trackerId && trackerId !== baseSlug ? `-${trackerId}` : "";
     targetPath = path13.join(featurePlanDir, `${formatSequence(nn)}-story-${baseSlug}${trackerPart}.md`);
   }
-  const body = `${input6.metadataHeader.trimEnd()}
+  const body = `${input5.metadataHeader.trimEnd()}
 
-${input6.planBodyMarkdown.trimStart()}
+${input5.planBodyMarkdown.trimStart()}
 `;
   fs20.writeFileSync(targetPath, body, "utf8");
   upsertOverviewRow(featurePlanDir, story.feature, nn, path13.basename(targetPath), story);
@@ -3109,6 +3426,45 @@ function buildMetadataHeader(args) {
   return `<!-- squad-kit: ${parts.join(", ")} -->`;
 }
 
+// src/core/last-run.ts
+import fs21 from "fs/promises";
+import path14 from "path";
+async function writeLastRun(paths, rec) {
+  const file = path14.join(paths.squadDir, ".last-run.json");
+  await fs21.writeFile(file, JSON.stringify({ ...rec, version: 1 }, null, 2) + "\n", "utf8");
+}
+async function readLastRun(paths) {
+  const file = path14.join(paths.squadDir, ".last-run.json");
+  try {
+    const raw = await fs21.readFile(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/ui/planner-cache-summary.ts
+function formatTokenK(n) {
+  return `${(n / 1e3).toFixed(1)}k`;
+}
+function formatPlannerCacheLine(opts) {
+  if (!opts.cacheEnabled) {
+    return "cache disabled";
+  }
+  const { stats } = opts;
+  if (stats.cacheReadTokens > 0) {
+    const pct = Math.round(stats.cacheHitRatio * 100);
+    const total = stats.inputTokens + stats.cacheReadTokens;
+    const read = formatTokenK(stats.cacheReadTokens);
+    const tot = formatTokenK(total);
+    const written = stats.cacheCreationTokens > 0 ? ` \xB7 ${formatTokenK(stats.cacheCreationTokens)} written` : "";
+    return `cache hit ${pct}% (${read} read / ${tot} total${written})`;
+  }
+  return "cache miss 0% \u2014 run `squad doctor` to diagnose";
+}
+
 // src/commands/new-plan.ts
 function decideMode(opts, config2) {
   if (opts.api && opts.copy) {
@@ -3140,8 +3496,8 @@ async function runNewPlan(intakePath, opts) {
   }
 }
 function resolveFromPath(intakePath, stories, root) {
-  const resolved = path14.resolve(intakePath.trim());
-  if (!fs21.existsSync(resolved)) {
+  const resolved = path15.resolve(intakePath.trim());
+  if (!fs22.existsSync(resolved)) {
     throw new Error(
       `Intake not found: ${resolved}. Run \`squad list\` to see intakes, or \`squad new-story\` to create one first.`
     );
@@ -3153,7 +3509,7 @@ function resolveFromPath(intakePath, stories, root) {
   );
 }
 function relativeStoriesDir(root) {
-  return path14.relative(root, path14.join(root, ".squad", "stories"));
+  return path15.relative(root, path15.join(root, ".squad", "stories"));
 }
 async function pickStory(stories, opts) {
   const candidates = opts.all ? stories : stories.filter((s) => !s.planFile);
@@ -3184,7 +3540,7 @@ async function pickStory(stories, opts) {
       value: s.intakePath
     }))
   });
-  return candidates.find((s) => path14.resolve(s.intakePath) === path14.resolve(pick));
+  return candidates.find((s) => path15.resolve(s.intakePath) === path15.resolve(pick));
 }
 function formatLabel(s) {
   const head = `${s.feature} / ${s.id}`;
@@ -3245,6 +3601,7 @@ async function emitViaApi(story, paths, config2, _opts) {
   const userPrompt = composeUserPrompt({ intakeContent: readFile(story.intakePath) });
   const sessionSpinner = { current: null };
   const startedAt = Date.now();
+  const cacheEnabled = planner.cache?.enabled ?? true;
   const result = await runPlanner({
     root: paths.root,
     provider,
@@ -3253,6 +3610,7 @@ async function emitViaApi(story, paths, config2, _opts) {
     systemPrompt,
     userPrompt,
     budget,
+    cacheEnabled,
     onToolCall: (tc, bytes, total) => {
       const p = tc.input.path ?? "<unknown>";
       sessionSpinner.current?.succeed(
@@ -3295,9 +3653,18 @@ async function emitViaApi(story, paths, config2, _opts) {
     planBodyMarkdown: result.planText,
     metadataHeader: header
   });
+  try {
+    await writeLastRun(paths, {
+      stats: result.stats,
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      provider: planner.provider,
+      model
+    });
+  } catch {
+  }
   blank();
   summaryBox(" plan generated ", [
-    { key: "file", value: path14.relative(paths.root, planFile) },
+    { key: "file", value: path15.relative(paths.root, planFile) },
     { key: "nn", value: String(sequenceNumber).padStart(2, "0") },
     { key: "model", value: `${planner.provider}/${model}` },
     { key: "reads", value: `${snap.reads} files \xB7 ${(snap.bytes / 1024).toFixed(1)} KB` },
@@ -3305,6 +3672,7 @@ async function emitViaApi(story, paths, config2, _opts) {
       key: "tokens",
       value: `${snap.usage.inputTokens} in \xB7 ${snap.usage.outputTokens} out${snap.usage.costUsd !== void 0 ? `  \u2248 $${snap.usage.costUsd.toFixed(2)}` : ""}`
     },
+    { key: "cache", value: formatPlannerCacheLine({ cacheEnabled, stats: result.stats }) },
     { key: "time", value: `${Math.round(elapsedMs / 1e3)}s` },
     { key: "action", value: overwrote ? "overwrote existing plan" : "new plan" }
   ]);
@@ -3314,9 +3682,9 @@ async function emitViaApi(story, paths, config2, _opts) {
     warning("Planner did not reach end_turn. Inspect the plan carefully.");
   }
   blank();
-  info(`next  \u2192  open a new agent chat and attach only ${path14.basename(planFile)}`);
+  info(`next  \u2192  open a new agent chat and attach only ${path15.basename(planFile)}`);
 }
-async function emitCopyPrompt(story, _paths, config2, clipboard) {
+async function emitCopyPrompt(story, paths, config2, clipboard) {
   const intakeContent = readFile(story.intakePath);
   const metaPromptTemplate = readBundledPrompt("generate-plan.md");
   const composed = render(metaPromptTemplate, {
@@ -3325,13 +3693,44 @@ async function emitCopyPrompt(story, _paths, config2, clipboard) {
     trackerType: config2.tracker.type,
     intakeContent
   });
+  const promptFile = path15.join(paths.squadDir, ".last-copy-prompt.md");
+  fs22.writeFileSync(promptFile, composed, "utf8");
+  const relPromptFile = path15.relative(paths.root, promptFile);
+  const bytes = Buffer.byteLength(composed, "utf8");
+  const estTokens = Math.round(bytes / 4);
+  const clipResult = clipboard ? await copyToClipboard(composed) : { ok: false, reason: "clipboard disabled (--no-clipboard)" };
+  blank();
+  divider("planner prompt ready");
+  kv("mode", "copy-paste", 10);
+  kv("story", `${story.feature} / ${story.id}`, 10);
+  kv("prompt", relPromptFile, 10);
+  kv("size", `${formatKB(bytes)} \xB7 ~${formatCount(estTokens)} tokens (est)`, 10);
+  if (clipResult.ok) {
+    kv("clipboard", `\u2713 copied via ${clipResult.tool}`, 10);
+  } else {
+    kv("clipboard", `! ${clipResult.reason}`, 10);
+  }
   printModelBanner(config2);
-  process.stdout.write(composed);
-  if (!composed.endsWith("\n")) process.stdout.write("\n");
-  if (clipboard) {
-    const ok = await copyToClipboard(composed);
-    if (ok) info("copied to clipboard");
+  blank();
+  step("Next:");
+  info("1) Open your agent chat (Cursor / Claude Code / Copilot / Gemini).");
+  info("2) Switch to a strong plan model (Opus 4.x / GPT-5.3 Codex thinking / Gemini deep-think).");
+  if (clipResult.ok) {
+    info("3) Paste from clipboard and let the agent work. It will read files and write the plan itself.");
+  } else {
+    info(`3) Open ${relPromptFile}, paste its contents into the agent chat, and let it work.`);
   }
+  info(
+    `4) The agent writes the plan to .squad/plans/${story.feature}/<nn>-story-${story.id}.md. Review it, then open a fresh chat to implement (attach only the plan file).`
+  );
+}
+function formatKB(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+function formatCount(n) {
+  if (n < 1e3) return String(n);
+  return `${(n / 1e3).toFixed(1)}k`;
 }
 function printModelBanner(config2) {
   if (!isInteractive()) return;
@@ -3354,7 +3753,7 @@ function printModelBanner(config2) {
 }
 
 // src/commands/status.ts
-import fs22 from "fs";
+import fs23 from "fs";
 var kw = 28;
 function probeTrackerCredential(config2, overlay) {
   const { client, error: error2 } = clientFor(config2, overlay);
@@ -3380,7 +3779,7 @@ async function runStatus() {
   const scan = scanPlans(paths.plansDir);
   const storyCount = listStories(paths).length;
   const planCount = scan.usedNumbers.length;
-  const secrets = fs22.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
+  const secrets = fs23.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
   const overlay = overlayTrackerEnv(secrets);
   banner();
   step("squad-kit status");
@@ -3434,13 +3833,13 @@ function buildTrackerLine(config2, overlay) {
 }
 
 // src/commands/list.ts
-import path15 from "path";
+import path16 from "path";
 async function runList(opts) {
   const root = requireSquadRoot();
   const paths = buildPaths(root);
   const records = listStories(paths, { feature: opts.feature });
   const rows = records.map((r) => {
-    const planAbs = r.planFile ? path15.join(paths.plansDir, r.feature, r.planFile) : void 0;
+    const planAbs = r.planFile ? path16.join(paths.plansDir, r.feature, r.planFile) : void 0;
     const meta = planAbs ? readPlanMetadata(planAbs) : void 0;
     return {
       feature: r.feature,
@@ -3479,9 +3878,9 @@ function stripAnsi(s) {
 }
 
 // src/commands/tracker-link.ts
-import fs23 from "fs";
-import path16 from "path";
-import { input as input5, select as select6 } from "@inquirer/prompts";
+import fs24 from "fs";
+import path17 from "path";
+import { input as input4, select as select6 } from "@inquirer/prompts";
 async function runTrackerLink(storyPath, trackerId, opts = {}) {
   const root = requireSquadRoot();
   const paths = buildPaths(root);
@@ -3513,7 +3912,7 @@ async function runTrackerLink(storyPath, trackerId, opts = {}) {
         "Usage: squad tracker link [story-path] [tracker-id]. Run `squad tracker link` without arguments in a TTY to pick from a list, or pass `--yes` to opt out of prompts."
       );
     }
-    resolvedTrackerId = (await input5({
+    resolvedTrackerId = (await input4({
       message: `${config2.tracker.type} work-item id:`,
       validate: (v) => {
         const trimmed = v.trim();
@@ -3527,17 +3926,21 @@ async function runTrackerLink(storyPath, trackerId, opts = {}) {
       `Invalid tracker id "${resolvedTrackerId}" for tracker type "${config2.tracker.type}". Run \`squad config show\` to review the expected format, or \`squad config set tracker\` if the type is wrong.`
     );
   }
-  const resolved = path16.resolve(resolvedStoryPath);
-  const intakeFile = resolved.endsWith("intake.md") ? resolved : path16.join(resolved, "intake.md");
-  if (!fs23.existsSync(intakeFile)) {
+  const resolved = path17.resolve(resolvedStoryPath);
+  const intakeFile = resolved.endsWith("intake.md") ? resolved : path17.join(resolved, "intake.md");
+  if (!fs24.existsSync(intakeFile)) {
     throw new Error(
       `intake.md not found at ${intakeFile}. Run \`squad list\` to see valid paths, or \`squad new-story\` to create a story first.`
     );
   }
-  const content = fs23.readFileSync(intakeFile, "utf8");
+  const content = fs24.readFileSync(intakeFile, "utf8");
   const updated = upsertTrackerId(content, resolvedTrackerId);
-  fs23.writeFileSync(intakeFile, updated, "utf8");
-  success(`Linked tracker id ${resolvedTrackerId} \u2192 ${path16.relative(root, intakeFile)}`);
+  fs24.writeFileSync(intakeFile, updated, "utf8");
+  success(`Linked tracker id ${resolvedTrackerId} \u2192 ${path17.relative(root, intakeFile)}`);
+  blank();
+  step("Next:");
+  info("1) Review the intake \u2014 the Source block at the top now carries the tracker id.");
+  info("2) Run `squad new-plan --api` (or `--copy`) to generate the plan for this story.");
 }
 function upsertTrackerId(content, id) {
   const pattern = /(-\s*\*\*Work item id:\*\*)[^\n]*/;
@@ -3551,8 +3954,8 @@ function upsertTrackerId(content, id) {
 }
 
 // src/commands/doctor.ts
-import fs24 from "fs";
-import path17 from "path";
+import fs25 from "fs";
+import path18 from "path";
 async function gatherContext(paths) {
   const ctx = { hasLegacyPromptsDir: false };
   try {
@@ -3561,29 +3964,29 @@ async function gatherContext(paths) {
     ctx.configError = err;
   }
   try {
-    ctx.secrets = fs24.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
+    ctx.secrets = fs25.existsSync(paths.secretsFile) ? loadSecrets(paths.secretsFile) : {};
   } catch (err) {
     ctx.secretsError = err;
   }
-  ctx.hasLegacyPromptsDir = fs24.existsSync(paths.promptsDir);
+  ctx.hasLegacyPromptsDir = fs25.existsSync(paths.promptsDir);
   return ctx;
 }
 function gitignoreHasManagedBlock(repoRoot) {
-  const gitignore = path17.join(repoRoot, ".gitignore");
-  return fs24.existsSync(gitignore) && fs24.readFileSync(gitignore, "utf8").includes(".squad/secrets.yaml");
+  const gitignore = path18.join(repoRoot, ".gitignore");
+  return fs25.existsSync(gitignore) && fs25.readFileSync(gitignore, "utf8").includes(".squad/secrets.yaml");
 }
 function gitignoreHasTrashPattern(repoRoot) {
-  const gitignore = path17.join(repoRoot, ".gitignore");
-  return fs24.existsSync(gitignore) && fs24.readFileSync(gitignore, "utf8").includes(SQUAD_TRASH_PATTERN);
+  const gitignore = path18.join(repoRoot, ".gitignore");
+  return fs25.existsSync(gitignore) && fs25.readFileSync(gitignore, "utf8").includes(SQUAD_TRASH_PATTERN);
 }
 async function checkDirStructure(paths, _ctx, fix) {
-  const need = [paths.squadDir, paths.storiesDir, paths.plansDir].filter((p) => !fs24.existsSync(p));
+  const need = [paths.squadDir, paths.storiesDir, paths.plansDir].filter((p) => !fs25.existsSync(p));
   if (need.length === 0) {
     return { id: "dirs", name: ".squad/ directory structure", status: "ok" };
   }
   if (fix) {
     for (const p of need) {
-      fs24.mkdirSync(p, { recursive: true });
+      fs25.mkdirSync(p, { recursive: true });
     }
     return { id: "dirs", name: ".squad/ directory structure", status: "ok", detail: "repaired" };
   }
@@ -3591,7 +3994,7 @@ async function checkDirStructure(paths, _ctx, fix) {
     id: "dirs",
     name: ".squad/ directory structure",
     status: "warn",
-    detail: `missing: ${need.map((p) => path17.relative(paths.root, p)).join(", ")}`,
+    detail: `missing: ${need.map((p) => path18.relative(paths.root, p)).join(", ")}`,
     fixable: true,
     fixHint: "squad doctor --fix"
   };
@@ -3646,15 +4049,15 @@ async function checkSecretsPermissions(paths, _ctx, fix) {
   if (process.platform === "win32") {
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "skip", detail: "Windows" };
   }
-  if (!fs24.existsSync(paths.secretsFile)) {
+  if (!fs25.existsSync(paths.secretsFile)) {
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "ok", detail: "not present" };
   }
-  const mode = fs24.statSync(paths.secretsFile).mode & 511;
+  const mode = fs25.statSync(paths.secretsFile).mode & 511;
   if (mode === 384) {
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "ok" };
   }
   if (fix) {
-    fs24.chmodSync(paths.secretsFile, 384);
+    fs25.chmodSync(paths.secretsFile, 384);
     return { id: "secrets-perms", name: ".squad/secrets.yaml permissions", status: "ok", detail: "repaired" };
   }
   return {
@@ -3675,7 +4078,7 @@ async function checkSecretsParseable(_paths, ctx) {
       detail: ctx.secretsError.message
     };
   }
-  if (!fs24.existsSync(_paths.secretsFile)) {
+  if (!fs25.existsSync(_paths.secretsFile)) {
     return { id: "secrets-yaml", name: ".squad/secrets.yaml parseable", status: "ok", detail: "not present" };
   }
   return { id: "secrets-yaml", name: ".squad/secrets.yaml parseable", status: "ok" };
@@ -3826,6 +4229,101 @@ async function checkPlannerModel(_paths, ctx) {
     };
   }
 }
+async function checkPlannerTierAwareness(_paths, ctx) {
+  const id = "planner-tier";
+  const name = "planner tier vs. model";
+  if (!ctx.config || ctx.config.planner?.enabled !== true) {
+    return { id, name, status: "skip", detail: "planner disabled" };
+  }
+  const provider = ctx.config.planner.provider;
+  if (provider !== "anthropic") {
+    return { id, name, status: "skip", detail: `not applicable for ${provider}` };
+  }
+  const planModel = modelFor(provider, "plan", ctx.config.planner.modelOverride);
+  if (!/opus/i.test(planModel)) {
+    return { id, name, status: "ok", detail: `${planModel} is comfortably under Tier 1` };
+  }
+  const cacheOn = ctx.config.planner?.cache?.enabled !== false;
+  if (cacheOn) {
+    return {
+      id,
+      name,
+      status: "warn",
+      detail: "Anthropic Tier 1 with Opus \u2014 tight but viable with prompt caching on",
+      fixHint: [
+        "Caching saves ~70% on billed input tokens. Keep `planner.cache.enabled: true` in config.",
+        "If you still hit 429s on long runs, reduce `planner.budget.maxContextBytes` or use Haiku for plan phase."
+      ].join("\n")
+    };
+  }
+  return {
+    id,
+    name,
+    status: "warn",
+    detail: `${planModel} on Anthropic Tier 1 (10k input tokens/min) is throttle-prone for plans over ~3 file reads`,
+    fixHint: "Run `squad config set planner` and pick a Sonnet or Haiku id for planner.modelOverride.anthropic, or upgrade tier at https://console.anthropic.com/settings/limits. squad-kit will auto-retry a 429 once (waiting up to 90s), but repeated throttling means the plan model is simply too big for your quota."
+  };
+}
+async function checkPlannerCache(paths, ctx) {
+  const id = "planner-cache";
+  const name = "planner cache effectiveness";
+  const config2 = ctx.config;
+  const cacheCfg = config2?.planner?.cache;
+  if (config2?.planner?.enabled !== true) {
+    return { id, name, status: "skip", detail: "planner disabled \u2014 cache check not applicable" };
+  }
+  if (cacheCfg?.enabled === false) {
+    return {
+      id,
+      name,
+      status: "warn",
+      detail: "prompt caching is disabled in .squad/config.yaml",
+      fixHint: "Cache saves ~70% on billed tokens. Re-enable with `squad config set planner`."
+    };
+  }
+  const lastRun = await readLastRun(paths);
+  if (!lastRun) {
+    return {
+      id,
+      name,
+      status: "skip",
+      detail: "no planner runs logged yet",
+      fixHint: "Run `squad new-plan --api` once, then re-run `squad doctor` to see cache telemetry."
+    };
+  }
+  const { stats } = lastRun;
+  const hitPct = Math.round(stats.cacheHitRatio * 100);
+  if (stats.cacheReadTokens === 0 && stats.turns > 1) {
+    return {
+      id,
+      name,
+      status: "fail",
+      detail: `caching configured but last run saw 0% hits across ${stats.turns} turns`,
+      fixHint: [
+        "Possible causes:",
+        "  \u2022 Planner provider is not Anthropic and the prefix is below 1024 tokens (OpenAI / Google need larger prefixes).",
+        "  \u2022 System prompt is mutating between turns \u2014 check recent changes.",
+        "  \u2022 Using an older model that doesn't support caching.",
+        `Provider: ${lastRun.provider}/${lastRun.model}. Run \`NODE_ENV=development squad new-plan --api\` to surface prefix-mismatch warnings.`
+      ].join("\n")
+    };
+  }
+  if (hitPct < 30 && stats.turns > 3) {
+    return {
+      id,
+      name,
+      status: "warn",
+      detail: `low cache hit rate: ${hitPct}% (last run, ${stats.turns} turns)`,
+      fixHint: "Expected \u226560% for Anthropic, \u226540% for OpenAI, \u226550% for Google after 3+ turns. Prefix may be unstable."
+    };
+  }
+  return {
+    id,
+    name,
+    status: "ok",
+    detail: `caching active \u2014 last run ${hitPct}% hit (${formatTokenK(stats.cacheReadTokens)} read, ${lastRun.provider}/${lastRun.model})`
+  };
+}
 async function checkTrackerConfig(_paths, ctx) {
   if (!ctx.config) {
     return { id: "tracker-config", name: "tracker configuration", status: "skip", detail: "config unavailable" };
@@ -3947,6 +4445,8 @@ async function runAllChecks(paths, ctx, fix) {
   await add("planner configuration", () => checkPlannerConfig(paths, ctx));
   await add("planner credential resolves", () => checkPlannerCredential(paths, ctx));
   await add("planner model resolves at provider", () => checkPlannerModel(paths, ctx));
+  await add("planner tier vs. model", () => checkPlannerTierAwareness(paths, ctx));
+  await add("planner cache effectiveness", () => checkPlannerCache(paths, ctx));
   await add("tracker configuration", () => checkTrackerConfig(paths, ctx));
   await add("tracker credential resolves", () => checkTrackerCredential(paths, ctx));
   await add("tracker connectivity", () => checkTrackerConnectivity(paths, ctx));
@@ -4052,23 +4552,23 @@ async function runDoctor(opts) {
 }
 
 // src/commands/migrate.ts
-import fs25 from "fs";
-import path18 from "path";
+import fs26 from "fs";
+import path19 from "path";
 import { confirm as confirm7 } from "@inquirer/prompts";
 var LEGACY_PROMPTS_MIGRATION = {
   id: "legacy-prompts",
   name: "Remove legacy .squad/prompts/",
-  isApplied: (paths) => !fs25.existsSync(paths.promptsDir),
-  describe: (paths) => `delete ${path18.relative(paths.root, paths.promptsDir)} (prompts are now bundled in squad-kit)`,
+  isApplied: (paths) => !fs26.existsSync(paths.promptsDir),
+  describe: (paths) => `delete ${path19.relative(paths.root, paths.promptsDir)} (prompts are now bundled in squad-kit)`,
   apply: (paths) => {
     const target = paths.promptsDir;
-    if (!target.includes(path18.sep + ".squad" + path18.sep + "prompts")) {
+    if (!target.includes(path19.sep + ".squad" + path19.sep + "prompts")) {
       throw new Error(
         `Refusing to delete suspicious path: ${target}. This is a safety check \u2014 run \`squad doctor\` if .squad/ paths look wrong.`
       );
     }
-    if (fs25.existsSync(target)) {
-      fs25.rmSync(target, { recursive: true, force: true });
+    if (fs26.existsSync(target)) {
+      fs26.rmSync(target, { recursive: true, force: true });
     }
   }
 };
@@ -4076,8 +4576,8 @@ var GITIGNORE_MIGRATION = {
   id: "gitignore",
   name: "Ensure .gitignore managed block",
   isApplied: (paths) => {
-    const f = path18.join(paths.root, ".gitignore");
-    return fs25.existsSync(f) && fs25.readFileSync(f, "utf8").includes(".squad/secrets.yaml");
+    const f = path19.join(paths.root, ".gitignore");
+    return fs26.existsSync(f) && fs26.readFileSync(f, "utf8").includes(".squad/secrets.yaml");
   },
   describe: () => "add squad-kit managed block to .gitignore",
   apply: (paths) => {
@@ -4089,23 +4589,23 @@ var SECRETS_PERMS_MIGRATION = {
   name: "Tighten .squad/secrets.yaml permissions",
   isApplied: (paths) => {
     if (process.platform === "win32") return true;
-    if (!fs25.existsSync(paths.secretsFile)) return true;
-    const st = fs25.statSync(paths.secretsFile);
+    if (!fs26.existsSync(paths.secretsFile)) return true;
+    const st = fs26.statSync(paths.secretsFile);
     return (st.mode & 511) === 384;
   },
-  describe: (paths) => `chmod 0600 ${path18.relative(paths.root, paths.secretsFile)}`,
+  describe: (paths) => `chmod 0600 ${path19.relative(paths.root, paths.secretsFile)}`,
   apply: (paths) => {
     if (process.platform === "win32") return;
-    if (fs25.existsSync(paths.secretsFile)) fs25.chmodSync(paths.secretsFile, 384);
+    if (fs26.existsSync(paths.secretsFile)) fs26.chmodSync(paths.secretsFile, 384);
   }
 };
 var PLANNER_BUDGET_DEFAULTS_MIGRATION = {
   id: "planner-budget-defaults",
   name: "Backfill planner.budget defaults in config.yaml",
   isApplied: (paths) => {
-    if (!fs25.existsSync(paths.configFile)) return true;
+    if (!fs26.existsSync(paths.configFile)) return true;
     try {
-      const raw = fs25.readFileSync(paths.configFile, "utf8");
+      const raw = fs26.readFileSync(paths.configFile, "utf8");
       if (!/^\s*planner:/m.test(raw)) return true;
       if (/^\s*budget:/m.test(raw)) return true;
       const cfg = loadConfig(paths.configFile);
@@ -4124,9 +4624,9 @@ var CONFIG_NORMALIZE_MIGRATION = {
   id: "config-normalize",
   name: "Normalise .squad/config.yaml formatting",
   isApplied: (paths) => {
-    if (!fs25.existsSync(paths.configFile)) return true;
+    if (!fs26.existsSync(paths.configFile)) return true;
     try {
-      const raw = fs25.readFileSync(paths.configFile, "utf8");
+      const raw = fs26.readFileSync(paths.configFile, "utf8");
       const cfg = loadConfig(paths.configFile);
       return raw.trim() === serializeConfig(cfg).trim();
     } catch {
@@ -4135,7 +4635,7 @@ var CONFIG_NORMALIZE_MIGRATION = {
   },
   describe: () => "rewrite config.yaml with canonical YAML formatting (drops comments)",
   apply: (paths) => {
-    if (!fs25.existsSync(paths.configFile)) return;
+    if (!fs26.existsSync(paths.configFile)) return;
     const cfg = loadConfig(paths.configFile);
     saveConfig(paths.configFile, cfg);
   }
@@ -4203,7 +4703,11 @@ async function runMigrate(opts) {
   }
   info("");
   success(`Applied ${applied}/${pending.length} migration(s).`);
-  info("Run `squad doctor` to verify.");
+  blank();
+  step("Next:");
+  info("1) Run `squad doctor` to verify every check is green.");
+  info("2) If you were upgrading from 0.1.x, review .squad/config.yaml \u2014 new defaults (planner, cache) may have been added.");
+  info("3) Continue your usual workflow: `squad new-story` \u2192 fill intake \u2192 `squad new-plan`.");
 }
 
 // src/commands/upgrade.ts
@@ -4212,8 +4716,8 @@ import process3 from "process";
 import { confirm as confirm8 } from "@inquirer/prompts";
 
 // src/core/package-info.ts
-import fs26 from "fs";
-import path19 from "path";
+import fs27 from "fs";
+import path20 from "path";
 function changelogBlobUrl(repositoryUrl, version) {
   let base = repositoryUrl;
   if (!base) base = "https://github.com/AzmSquad/squad-kit";
@@ -4224,9 +4728,9 @@ function changelogBlobUrl(repositoryUrl, version) {
 }
 function readInstalledPackage() {
   const root = packageRoot();
-  const pkgFile = path19.join(root, "package.json");
-  const pkg = JSON.parse(fs26.readFileSync(pkgFile, "utf8"));
-  const isDevInstall = fs26.existsSync(path19.join(root, "src"));
+  const pkgFile = path20.join(root, "package.json");
+  const pkg = JSON.parse(fs27.readFileSync(pkgFile, "utf8"));
+  const isDevInstall = fs27.existsSync(path20.join(root, "src"));
   return {
     name: pkg.name,
     version: pkg.version,
@@ -4266,7 +4770,7 @@ function isNewer(a, b) {
 }
 
 // src/core/package-manager.ts
-import path20 from "path";
+import path21 from "path";
 import process2 from "process";
 function detectPackageManager(installRoot) {
   const ua = process2.env.npm_config_user_agent;
@@ -4277,11 +4781,11 @@ function detectPackageManager(installRoot) {
     if (ua.startsWith("npm/")) return { pm: "npm", reason: "npm_config_user_agent" };
   }
   const root = installRoot.toLowerCase();
-  if (root.includes(`${path20.sep}pnpm${path20.sep}`) || root.includes(`${path20.sep}.pnpm${path20.sep}`))
+  if (root.includes(`${path21.sep}pnpm${path21.sep}`) || root.includes(`${path21.sep}.pnpm${path21.sep}`))
     return { pm: "pnpm", reason: `install path contains pnpm` };
-  if (root.includes(`${path20.sep}.yarn${path20.sep}`) || root.includes(`${path20.sep}yarn${path20.sep}`))
+  if (root.includes(`${path21.sep}.yarn${path21.sep}`) || root.includes(`${path21.sep}yarn${path21.sep}`))
     return { pm: "yarn", reason: `install path contains yarn` };
-  if (root.includes(`${path20.sep}.bun${path20.sep}`) || root.includes(`${path20.sep}bun${path20.sep}`))
+  if (root.includes(`${path21.sep}.bun${path21.sep}`) || root.includes(`${path21.sep}bun${path21.sep}`))
     return { pm: "bun", reason: `install path contains bun` };
   return { pm: "npm", reason: "default fallback" };
 }
@@ -4382,8 +4886,8 @@ function spawnInherit(cmd, args) {
 }
 
 // src/commands/rm/shared.ts
-import fs27 from "fs";
-import path21 from "path";
+import fs28 from "fs";
+import path22 from "path";
 import { select as select7 } from "@inquirer/prompts";
 var STORY_PLAN = /^(\d{2,})-story-.+\.md$/;
 function canPromptForRm(opts) {
@@ -4391,9 +4895,9 @@ function canPromptForRm(opts) {
   return isInteractive() && Boolean(process.stdin.isTTY);
 }
 function removeOverviewRow(featurePlanDir, storyId) {
-  const overview = path21.join(featurePlanDir, "00-overview.md");
-  if (!fs27.existsSync(overview)) return;
-  const src = fs27.readFileSync(overview, "utf8");
+  const overview = path22.join(featurePlanDir, "00-overview.md");
+  if (!fs28.existsSync(overview)) return;
+  const src = fs28.readFileSync(overview, "utf8");
   const lines = src.split("\n");
   const filtered = lines.filter((line2) => {
     if (!line2.startsWith("|")) return true;
@@ -4401,12 +4905,12 @@ function removeOverviewRow(featurePlanDir, storyId) {
     if (/^\|\s*-+/.test(line2)) return true;
     return !line2.includes(storyId);
   });
-  fs27.writeFileSync(overview, filtered.join("\n"), "utf8");
+  fs28.writeFileSync(overview, filtered.join("\n"), "utf8");
 }
 function removeOverviewRowForPlanFile(featurePlanDir, planBasename) {
-  const overview = path21.join(featurePlanDir, "00-overview.md");
-  if (!fs27.existsSync(overview)) return;
-  const src = fs27.readFileSync(overview, "utf8");
+  const overview = path22.join(featurePlanDir, "00-overview.md");
+  if (!fs28.existsSync(overview)) return;
+  const src = fs28.readFileSync(overview, "utf8");
   const token = `\`${planBasename}\``;
   const lines = src.split("\n");
   const filtered = lines.filter((line2) => {
@@ -4415,25 +4919,25 @@ function removeOverviewRowForPlanFile(featurePlanDir, planBasename) {
     if (/^\|\s*-+/.test(line2)) return true;
     return !line2.includes(token);
   });
-  fs27.writeFileSync(overview, filtered.join("\n"), "utf8");
+  fs28.writeFileSync(overview, filtered.join("\n"), "utf8");
 }
 function trashOrDelete(absPaths, trashRoot, useTrash) {
   if (!useTrash) {
-    for (const p of absPaths) fs27.rmSync(p, { recursive: true, force: true });
+    for (const p of absPaths) fs28.rmSync(p, { recursive: true, force: true });
     return { removed: absPaths };
   }
   const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const bucket = path21.join(trashRoot, ts);
-  fs27.mkdirSync(bucket, { recursive: true });
+  const bucket = path22.join(trashRoot, ts);
+  fs28.mkdirSync(bucket, { recursive: true });
   for (const src of absPaths) {
-    const rel = path21.basename(src);
-    let dst = path21.join(bucket, rel);
+    const rel = path22.basename(src);
+    let dst = path22.join(bucket, rel);
     let n = 0;
-    while (fs27.existsSync(dst)) {
+    while (fs28.existsSync(dst)) {
       n += 1;
-      dst = path21.join(bucket, `${n}_${rel}`);
+      dst = path22.join(bucket, `${n}_${rel}`);
     }
-    fs27.renameSync(src, dst);
+    fs28.renameSync(src, dst);
   }
   return { removed: absPaths, trashed: bucket };
 }
@@ -4444,21 +4948,21 @@ function renderPreview(kind, targets, opts) {
     kv(t.kind, t.label, 6);
   }
   if (opts.trash) {
-    info(`Items will move to ${path21.relative(process.cwd(), opts.trashRoot)}/<timestamp>/`);
+    info(`Items will move to ${path22.relative(process.cwd(), opts.trashRoot)}/<timestamp>/`);
   } else if (!opts.dryRun) {
     warning("This is a permanent delete. Pass --trash to move to .squad/.trash/ instead.");
   }
 }
 function listAllPlanListEntries(paths, featureFilter) {
-  if (!fs27.existsSync(paths.plansDir)) return [];
+  if (!fs28.existsSync(paths.plansDir)) return [];
   const out = [];
-  for (const ent of fs27.readdirSync(paths.plansDir, { withFileTypes: true })) {
+  for (const ent of fs28.readdirSync(paths.plansDir, { withFileTypes: true })) {
     if (!ent.isDirectory()) continue;
     if (featureFilter && ent.name !== featureFilter) continue;
-    const featureDir = path21.join(paths.plansDir, ent.name);
-    for (const name of fs27.readdirSync(featureDir)) {
+    const featureDir = path22.join(paths.plansDir, ent.name);
+    for (const name of fs28.readdirSync(featureDir)) {
       if (!STORY_PLAN.test(name)) continue;
-      out.push({ feature: ent.name, file: name, abs: path21.join(featureDir, name) });
+      out.push({ feature: ent.name, file: name, abs: path22.join(featureDir, name) });
     }
   }
   return out.sort((a, b) => (a.feature + a.file).localeCompare(b.feature + b.file));
@@ -4509,34 +5013,34 @@ function resolveStoryFromArg(arg, stories, root) {
     if (s.id === t) return s;
     if (`${s.feature}/${s.id}` === t) return s;
   }
-  const abs = path21.isAbsolute(t) ? t : path21.resolve(root, t);
-  const withIntake = t.endsWith("intake.md") ? abs : path21.join(abs, "intake.md");
+  const abs = path22.isAbsolute(t) ? t : path22.resolve(root, t);
+  const withIntake = t.endsWith("intake.md") ? abs : path22.join(abs, "intake.md");
   return findStoryByIntake(stories, withIntake) ?? findStoryByIntake(stories, abs);
 }
 function isSequenceToken(s) {
   return /^\d{1,4}$/.test(s) && s.length > 0;
 }
 function tryParsePlanFilePath(absPath, paths, featureFilter) {
-  if (!fs27.existsSync(absPath) || !STORY_PLAN.test(path21.basename(absPath))) return void 0;
-  const planRoot = fs27.realpathSync(path21.resolve(paths.plansDir));
-  const fileReal = fs27.realpathSync(path21.resolve(absPath));
-  const rel = path21.relative(planRoot, fileReal);
-  if (rel.startsWith("..") || path21.isAbsolute(rel)) return void 0;
-  const segs = rel.split(path21.sep);
+  if (!fs28.existsSync(absPath) || !STORY_PLAN.test(path22.basename(absPath))) return void 0;
+  const planRoot = fs28.realpathSync(path22.resolve(paths.plansDir));
+  const fileReal = fs28.realpathSync(path22.resolve(absPath));
+  const rel = path22.relative(planRoot, fileReal);
+  if (rel.startsWith("..") || path22.isAbsolute(rel)) return void 0;
+  const segs = rel.split(path22.sep);
   if (segs.length < 2) return void 0;
   const feature = segs[0];
-  const file = segs.slice(1).join(path21.sep);
+  const file = segs.slice(1).join(path22.sep);
   if (featureFilter && feature !== featureFilter) return void 0;
-  return { feature, file, abs: path21.resolve(absPath) };
+  return { feature, file, abs: path22.resolve(absPath) };
 }
 function resolvePlanFromArg(arg, paths, featureFilter) {
   const t = arg.trim();
   if (!t) return void 0;
-  const asPath = path21.isAbsolute(t) ? t : path21.resolve(process.cwd(), t);
+  const asPath = path22.isAbsolute(t) ? t : path22.resolve(process.cwd(), t);
   const a = tryParsePlanFilePath(asPath, paths, featureFilter);
   if (a) return a;
-  if (!path21.isAbsolute(t)) {
-    const under = tryParsePlanFilePath(path21.join(paths.plansDir, t), paths, featureFilter);
+  if (!path22.isAbsolute(t)) {
+    const under = tryParsePlanFilePath(path22.join(paths.plansDir, t), paths, featureFilter);
     if (under) return under;
   }
   if (isSequenceToken(t)) {
@@ -4566,24 +5070,24 @@ function countOverviewDataRows(overviewContent) {
   return n;
 }
 function featureStoriesDirEmpty(paths, feature) {
-  const d = path21.join(paths.storiesDir, feature);
-  if (!fs27.existsSync(d)) return true;
-  return fs27.readdirSync(d).length === 0;
+  const d = path22.join(paths.storiesDir, feature);
+  if (!fs28.existsSync(d)) return true;
+  return fs28.readdirSync(d).length === 0;
 }
 
 // src/commands/rm/story.ts
-import fs29 from "fs";
-import path23 from "path";
+import fs30 from "fs";
+import path24 from "path";
 import { confirm as confirm10 } from "@inquirer/prompts";
 
 // src/commands/rm/feature.ts
-import fs28 from "fs";
-import path22 from "path";
+import fs29 from "fs";
+import path23 from "path";
 import { confirm as confirm9 } from "@inquirer/prompts";
 function countStoryDirs(storiesDir, feature) {
-  const d = path22.join(storiesDir, feature);
-  if (!fs28.existsSync(d)) return 0;
-  return fs28.readdirSync(d, { withFileTypes: true }).filter((x) => x.isDirectory()).length;
+  const d = path23.join(storiesDir, feature);
+  if (!fs29.existsSync(d)) return 0;
+  return fs29.readdirSync(d, { withFileTypes: true }).filter((x) => x.isDirectory()).length;
 }
 async function runRmFeature(featureSlug, opts = {}) {
   const root = requireSquadRoot();
@@ -4617,17 +5121,17 @@ async function runRmFeature(featureSlug, opts = {}) {
       feature = await pickFeatureInteractive(paths);
     }
   }
-  const storyDir = path22.join(paths.storiesDir, feature);
-  const planDir = path22.join(paths.plansDir, feature);
+  const storyDir = path23.join(paths.storiesDir, feature);
+  const planDir = path23.join(paths.plansDir, feature);
   const nStories = countStoryDirs(paths.storiesDir, feature);
   const nPlans = listAllPlanListEntries(paths, feature).length;
-  const hasOverview = fs28.existsSync(path22.join(planDir, "00-overview.md")) ? 1 : 0;
+  const hasOverview = fs29.existsSync(path23.join(planDir, "00-overview.md")) ? 1 : 0;
   const targets = [];
-  if (fs28.existsSync(storyDir)) {
-    targets.push({ label: path22.relative(root, storyDir), absPath: storyDir, kind: "dir" });
+  if (fs29.existsSync(storyDir)) {
+    targets.push({ label: path23.relative(root, storyDir), absPath: storyDir, kind: "dir" });
   }
-  if (fs28.existsSync(planDir)) {
-    targets.push({ label: path22.relative(root, planDir), absPath: planDir, kind: "dir" });
+  if (fs29.existsSync(planDir)) {
+    targets.push({ label: path23.relative(root, planDir), absPath: planDir, kind: "dir" });
   }
   divider("squad rm feature");
   info(`Feature:  ${feature}`);
@@ -4642,7 +5146,7 @@ async function runRmFeature(featureSlug, opts = {}) {
     kv(t.kind, t.label, 6);
   }
   if (useTrash) {
-    info(`Items will move to ${path22.relative(process.cwd(), paths.trashDir)}/<timestamp>/`);
+    info(`Items will move to ${path23.relative(process.cwd(), paths.trashDir)}/<timestamp>/`);
   } else if (!dryRun) {
     warning("This is a permanent delete. Pass --trash to move to .squad/.trash/ instead.");
   }
@@ -4675,7 +5179,7 @@ async function runRmFeature(featureSlug, opts = {}) {
     useTrash
   );
   if (result.trashed) {
-    success(`Feature removed. Items moved to ${path22.relative(root, result.trashed)}.`);
+    success(`Feature removed. Items moved to ${path23.relative(root, result.trashed)}.`);
   } else {
     success("Feature removed (stories and plans directories).");
   }
@@ -4716,11 +5220,11 @@ async function runRmStory(storyPathOrId, opts = {}) {
     }
   }
   const targets = [
-    { label: path23.relative(root, story.storyDir), absPath: story.storyDir, kind: "dir" }
+    { label: path24.relative(root, story.storyDir), absPath: story.storyDir, kind: "dir" }
   ];
   if (story.planFile) {
-    const planAbs = path23.join(paths.plansDir, story.feature, story.planFile);
-    targets.push({ label: path23.relative(root, planAbs), absPath: planAbs, kind: "file" });
+    const planAbs = path24.join(paths.plansDir, story.feature, story.planFile);
+    targets.push({ label: path24.relative(root, planAbs), absPath: planAbs, kind: "file" });
   }
   renderPreview("story", targets, {
     dryRun,
@@ -4745,16 +5249,16 @@ async function runRmStory(storyPathOrId, opts = {}) {
   }
   const absPaths = targets.map((t) => t.absPath);
   const result = trashOrDelete(absPaths, paths.trashDir, useTrash);
-  removeOverviewRow(path23.join(paths.plansDir, story.feature), story.id);
+  removeOverviewRow(path24.join(paths.plansDir, story.feature), story.id);
   if (result.trashed) {
-    success(`Removed (moved to ${path23.relative(root, result.trashed)}).`);
+    success(`Removed (moved to ${path24.relative(root, result.trashed)}).`);
   } else {
     success("Removed story folder, plan file (if any), and overview row.");
   }
-  const featurePlanDir = path23.join(paths.plansDir, story.feature);
-  const overviewPath = path23.join(featurePlanDir, "00-overview.md");
-  if (fs29.existsSync(overviewPath)) {
-    const body = fs29.readFileSync(overviewPath, "utf8");
+  const featurePlanDir = path24.join(paths.plansDir, story.feature);
+  const overviewPath = path24.join(featurePlanDir, "00-overview.md");
+  if (fs30.existsSync(overviewPath)) {
+    const body = fs30.readFileSync(overviewPath, "utf8");
     const onlyShell = countOverviewDataRows(body) === 0;
     if (onlyShell && featureStoriesDirEmpty(paths, story.feature)) {
       if (canPrompt) {
@@ -4774,7 +5278,7 @@ async function runRmStory(storyPathOrId, opts = {}) {
 }
 
 // src/commands/rm/plan.ts
-import path24 from "path";
+import path25 from "path";
 import { confirm as confirm11 } from "@inquirer/prompts";
 async function runRmPlan(planPathOrSequence, opts = {}) {
   const root = requireSquadRoot();
@@ -4810,7 +5314,7 @@ async function runRmPlan(planPathOrSequence, opts = {}) {
   }
   const storyRows = listStories(paths, { feature: plan.feature });
   const linked = storyRows.find((s) => s.planFile === plan.file);
-  const targets = [{ label: path24.relative(root, plan.abs), absPath: plan.abs, kind: "file" }];
+  const targets = [{ label: path25.relative(root, plan.abs), absPath: plan.abs, kind: "file" }];
   renderPreview("plan", targets, {
     dryRun,
     trash: useTrash,
@@ -4833,14 +5337,14 @@ async function runRmPlan(planPathOrSequence, opts = {}) {
     }
   }
   trashOrDelete([plan.abs], paths.trashDir, useTrash);
-  removeOverviewRowForPlanFile(path24.join(paths.plansDir, plan.feature), plan.file);
-  const intakeHint = linked ? path24.relative(root, linked.intakePath) : `under .squad/stories/${plan.feature}/`;
+  removeOverviewRowForPlanFile(path25.join(paths.plansDir, plan.feature), plan.file);
+  const intakeHint = linked ? path25.relative(root, linked.intakePath) : `under .squad/stories/${plan.feature}/`;
   success(`Plan removed. Run \`squad new-plan ${intakeHint}\` to regenerate.`);
 }
 
 // src/cli.ts
 var program = new Command();
-program.name("squad").description("Plan once, execute cheap. A 3-step SDD workflow CLI.").version("0.2.1");
+program.name("squad").description("Plan once, execute cheap. A 3-step SDD workflow CLI.").version("0.3.0");
 program.command("init").description("Bootstrap .squad/ in the current directory").option("--agents <list>", "Comma-separated agent list: claude-code,cursor,copilot,gemini").option("--tracker <type>", "Tracker type: none|github|linear|jira|azure").option(
   "--tracker-workspace <hostOrOrg>",
   "Jira host or Azure org (non-interactive default; also written to config for jira/azure)"