intentdocs 0.10.0 → 0.11.0

package/dist/index.js

@@ -1,22 +1,18 @@
 #!/usr/bin/env node
+import {
+  appendToNotes
+} from "./chunk-GFKZ5CRL.js";
 import {
   UPGRADE_MESSAGE_PLAIN,
   isPlanGated
-} from "./chunk-UR73WX5I.js";
+} from "./chunk-UQDMUKLP.js";
 import {
   ci
-} from "./chunk-IDNUBI2P.js";
+} from "./chunk-65EDM7QH.js";
 import {
   setup,
   sync
-} from "./chunk-EEKEF2FD.js";
-import {
-  captureCli,
-  shutdownCliAnalytics
-} from "./chunk-HEHHSSUM.js";
-import {
-  scope
-} from "./chunk-5USVG4DW.js";
+} from "./chunk-IORMKLAQ.js";
 import {
   criterionPriority,
   criterionStatusLabel,
@@ -24,11 +20,22 @@ import {
   formatDesignRefLine,
   storyContextPath,
   writeStoryContext
-} from "./chunk-NFIXRIHM.js";
+} from "./chunk-BNEU6TLJ.js";
 import {
   matchesStoryRef,
   storyRef
 } from "./chunk-LQTPZL2Y.js";
+import {
+  captureCli,
+  shutdownCliAnalytics
+} from "./chunk-KPQ42YE6.js";
+import {
+  scope
+} from "./chunk-ID4B5RZ2.js";
+import {
+  login,
+  logout
+} from "./chunk-64I7RLP3.js";
 import {
   amendDecision,
   apiFetch,
@@ -43,13 +50,14 @@ import {
   syncHeaders,
   updateStories,
   uploadScreenshot
-} from "./chunk-YUW3W43S.js";
+} from "./chunk-KTGQO3AE.js";
 import {
+  checkoutConfig,
   hasConfig,
   readConfig,
   requireConfig,
   writeConfig
-} from "./chunk-UF535HZL.js";
+} from "./chunk-K5SNF6CG.js";
 import {
   ask,
   closePrompt,
@@ -59,13 +67,9 @@ import {
 } from "./chunk-WRRUCCVZ.js";
 import {
   authenticatedFetch,
-  bindingLabel,
-  clearAuth,
   getAuth,
-  requireValidAuth,
-  saveAuth,
-  validateAuth
-} from "./chunk-LXQXJULN.js";
+  requireValidAuth
+} from "./chunk-XZE2XP6O.js";
 import {
   API_BASE
 } from "./chunk-UYTVTYNB.js";
@@ -75,168 +79,96 @@ import { Command } from "commander";
 import { createRequire as createRequire2 } from "module";
 
 // src/commands/init.ts
-import { writeFileSync, existsSync, readFileSync, appendFileSync, statSync } from "fs";
-import { join } from "path";
+import { writeFileSync as writeFileSync2, existsSync as existsSync2, readFileSync as readFileSync2, appendFileSync, statSync } from "fs";
+import { join as join2 } from "path";
 import { createInterface } from "readline";
 
-// src/commands/login.ts
-import { exec } from "child_process";
-function finishLogin(data) {
-  saveAuth({
-    token: data.token,
-    apiBase: API_BASE,
-    ...data.userId && { userId: data.userId },
-    binding: data.binding ?? null,
-    ...data.posthogKey && { posthogKey: data.posthogKey },
-    ...data.posthogHost && { posthogHost: data.posthogHost }
-  });
-  console.log(`
-
-\u2705 Logged in as ${data.userId ?? "unknown user"} \u2014 token ${bindingLabel(data.binding)}
-`);
-  if (data.binding?.approvalStatus === "pending") {
-    console.log("An admin has been asked to approve it. Until they do, this token reads your personal projects only.\n");
+// src/lib/agent-permissions.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var READ_TOOLS = [
+  "list_projects",
+  "get_context",
+  "get_session_context",
+  "list_stories",
+  "get_story",
+  "get_status",
+  "get_build_order",
+  "get_vision",
+  "get_design",
+  "get_run"
+];
+var BUILD_LOOP_TOOLS = [
+  "next_in_run",
+  "update_run",
+  "start_story",
+  "report_criteria",
+  "save_tests",
+  "complete_story",
+  "link_pr",
+  "add_note"
+];
+var STILL_ASKS = ["replace_criteria", "update_stories", "create_stories", "cancel_story"];
+var ALLOWED_TOOLS = [...READ_TOOLS, ...BUILD_LOOP_TOOLS];
+var DEFAULT_SERVER_NAME = "intentdocs";
+function readJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
   }
-  console.log("You can now run: intentdocs init");
-  console.log(
-    "Optional: add your Anthropic API key to unlock AI features on any plan \u2014 intentdocs keys set"
-  );
 }
-function openBrowser(url) {
-  const cmd = process.platform === "darwin" ? `open "${url}"` : process.platform === "win32" ? `start "${url}"` : `xdg-open "${url}"`;
-  exec(cmd);
+function intentdocsServers(servers) {
+  if (!servers || typeof servers !== "object") return [];
+  return Object.entries(servers).filter(([, s]) => (s?.url ?? "").includes("intentdocs.com/api/mcp") || (s?.args ?? []).includes("intentdocs")).map(([name]) => name);
 }
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
+function detectServerNames(cwd = process.cwd(), home = homedir()) {
+  const names = /* @__PURE__ */ new Set();
+  for (const n of intentdocsServers(readJson(join(cwd, ".mcp.json"))?.mcpServers)) names.add(n);
+  const user = readJson(join(home, ".claude.json"));
+  for (const n of intentdocsServers(user?.mcpServers)) names.add(n);
+  const projects = user?.projects ?? {};
+  for (const n of intentdocsServers(projects[cwd]?.mcpServers)) names.add(n);
+  return names.size > 0 ? [...names] : [DEFAULT_SERVER_NAME];
 }
-async function login() {
-  const existing = getAuth();
-  if (existing) {
-    const result = await validateAuth();
-    if (result.valid) {
-      console.log(`Already logged in (user: ${result.userId}). Run \`intentdocs logout\` to switch accounts.`);
-      return;
-    }
-    switch (result.reason) {
-      case "revoked":
-        console.log("Your stored token has been revoked. Starting a fresh login...\n");
-        break;
-      case "not_found":
-        console.log("Your stored token is no longer valid. Starting a fresh login...\n");
-        break;
-      case "network_error":
-        console.error("Could not reach intentdocs.com to verify your token. Check your internet connection and try again.");
-        process.exit(1);
-        break;
-    }
-    clearAuth();
-  }
-  console.log("Logging in to intentdocs...\n");
-  const res = await fetch(`${API_BASE}/api/cli/auth`, { method: "POST" });
-  if (!res.ok) {
-    console.error("Failed to start login flow. Try again.");
-    process.exit(1);
-  }
-  const { code } = await res.json();
-  const authUrl = `${API_BASE}/cli/auth?code=${code}`;
-  console.log("Opening browser to authorize...");
-  console.log(`If it doesn't open, visit: ${authUrl}
-`);
-  openBrowser(authUrl);
-  const POLL_INTERVAL_MS = 3e3;
-  const INITIAL_TIMEOUT_S = 300;
-  const EXTEND_TIMEOUT_S = 120;
-  let totalWaitedS = 0;
-  let phase = "initial";
-  let timeoutS = INITIAL_TIMEOUT_S;
-  while (totalWaitedS < timeoutS) {
-    const elapsed = totalWaitedS;
-    const minutesLeft = Math.ceil((timeoutS - elapsed) / 60);
-    if (elapsed === 0) {
-      process.stdout.write("Waiting for browser approval...");
-    } else if (elapsed % 30 === 0) {
-      process.stdout.write(`
-  Still waiting for approval (${minutesLeft}m remaining)...`);
-    } else {
-      process.stdout.write(".");
-    }
-    await sleep(POLL_INTERVAL_MS);
-    totalWaitedS += POLL_INTERVAL_MS / 1e3;
-    try {
-      const checkRes = await fetch(`${API_BASE}/api/cli/auth?code=${code}`);
-      if (!checkRes.ok) continue;
-      const data = await checkRes.json();
-      if (data.status === "approved" && data.token) {
-        finishLogin(data);
-        return;
-      }
-      if (data.status === "expired") {
-        console.error("\n\nThe server-side login request expired. Run `intentdocs login` to start a new one.");
-        process.exit(1);
-      }
-    } catch {
-    }
-  }
-  if (phase === "initial") {
-    console.log("\n\nThe initial wait has ended. The browser approval hasn't come through yet.");
-    console.log("This can happen if you needed to create an account or got distracted.\n");
-    const rl = await import("readline");
-    const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await new Promise(
-      (resolve) => iface.question("Keep waiting? (y/n): ", resolve)
-    );
-    iface.close();
-    if (answer.trim().toLowerCase().startsWith("y")) {
-      phase = "extended";
-      timeoutS = totalWaitedS + EXTEND_TIMEOUT_S;
-      console.log(`
-Waiting ${EXTEND_TIMEOUT_S / 60} more minutes...`);
-      while (totalWaitedS < timeoutS) {
-        const minutesLeft = Math.ceil((timeoutS - totalWaitedS) / 60);
-        if (Math.floor(totalWaitedS) % 30 === 0 && totalWaitedS > INITIAL_TIMEOUT_S) {
-          process.stdout.write(`
-  Still waiting (${minutesLeft}m remaining)...`);
-        } else {
-          process.stdout.write(".");
-        }
-        await sleep(POLL_INTERVAL_MS);
-        totalWaitedS += POLL_INTERVAL_MS / 1e3;
-        try {
-          const checkRes = await fetch(`${API_BASE}/api/cli/auth?code=${code}`);
-          if (!checkRes.ok) continue;
-          const data = await checkRes.json();
-          if (data.status === "approved" && data.token) {
-            finishLogin(data);
-            return;
-          }
-          if (data.status === "expired") {
-            console.error("\n\nThe server-side login request expired. Run `intentdocs login` to start a new one.");
-            process.exit(1);
-          }
-        } catch {
-        }
-      }
-    }
-  }
-  console.error("\n\nLogin timed out. Run `intentdocs login` to try again.");
-  console.error("If the browser page is still open, complete it and re-run the command \u2014 your approval will still work within 10 minutes.\n");
-  process.exit(1);
+function allowRules(serverNames, tools = ALLOWED_TOOLS) {
+  return serverNames.flatMap((server) => tools.map((tool) => `mcp__${server}__${tool}`));
 }
-async function logout() {
-  const { existsSync: existsSync5, unlinkSync } = await import("fs");
-  const { join: join5 } = await import("path");
-  const { homedir } = await import("os");
-  const authFile = join5(homedir(), ".intent", "auth.json");
-  if (existsSync5(authFile)) {
-    unlinkSync(authFile);
-    console.log("Logged out.");
-  } else {
-    console.log("Not logged in.");
-  }
+function withAllowRules(settings, rules) {
+  const permissions = { ...settings.permissions ?? {} };
+  const allow = Array.isArray(permissions.allow) ? permissions.allow : [];
+  permissions.allow = [...allow, ...rules.filter((r) => !allow.includes(r))];
+  return { ...settings, permissions };
+}
+function writeProjectAllowList(cwd, rules) {
+  const path = join(cwd, ".claude", "settings.json");
+  const before = readJson(path) ?? {};
+  const existing = new Set(before.permissions?.allow ?? []);
+  const next2 = withAllowRules(before, rules);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(next2, null, 2) + "\n");
+  return { path, added: rules.filter((r) => !existing.has(r)).length };
+}
+function describeAllowList(serverNames) {
+  return [
+    `  Allow these IntentDocs tools without asking, in .claude/settings.json (server: ${serverNames.join(", ")})?`,
+    "",
+    `    Reads:       ${READ_TOOLS.join(", ")}`,
+    `    Build loop:  ${BUILD_LOOP_TOOLS.join(", ")}`,
+    "",
+    `  Still asks:   ${STILL_ASKS.join(", ")} \u2014 anything that changes the spec or cancels work.`
+  ].join("\n");
 }
+var CURSOR_ALLOW_NOTE = [
+  "  Cursor: in its settings, find the agent's auto-run options and allow these",
+  `  intentdocs MCP tools: ${ALLOWED_TOOLS.join(", ")}.`,
+  `  Leave ${STILL_ASKS.join(", ")} asking.`
+].join("\n");
 
 // src/commands/init.ts
-var INTENTDOCS_CLAUDE_BLOCK = "\n\n# intentdocs\nRead INTENT.md for the product story map, personas, and backlog.\nWhen you call `save_tests`, pass the `file` and the `full_name` (the full test name, describe blocks included) for every test, so CI can report each test's result back to its story.\nWhen you open a pull request for a story, pass its URL to `intent done` or `complete_story`; intentdocs stamps the PR with a 'Spec \u2192 Code via intentdocs.com' footer linking back to the story when GitHub is connected. If it is not, end the PR body with:\n---\nSpec \u2192 Code via [intentdocs.com](https://intentdocs.com?utm_source=github&utm_medium=pr-footer) \xB7 [story <story-id>](<story-url>)\n";
+var INTENTDOCS_CLAUDE_BLOCK = "\n\n# intentdocs\nRead INTENT.md for the product story map, personas, and backlog.\nSave every test you write for a story with `save_tests`, linked to the acceptance criteria it proves, and pass the `file` and the `full_name` (the full test name, describe blocks included) for each, so CI can report each test's result back to its story.\nWhen you open a pull request for a story, pass its URL to `npx intentdocs done <story> --pr <url>` or to `complete_story` (or `link_pr`); intentdocs stamps the PR with a 'Spec \u2192 Code via intentdocs.com' footer linking back to the story when GitHub is connected. Add the footer yourself only when that reply asks you to (it says nothing when the project turned the line off); it will look like:\n---\nSpec \u2192 Code via [intentdocs.com](https://intentdocs.com?utm_source=github&utm_medium=pr-footer) \xB7 [story <story-id>](<story-url>)\n";
 function ask2(rl, question) {
   return new Promise((resolve) => rl.question(question, resolve));
 }
@@ -254,8 +186,8 @@ ${prompt} [1-${items.length}]: `);
 }
 function detectStack(cwd) {
   try {
-    if (existsSync(join(cwd, "package.json"))) {
-      const raw = readFileSync(join(cwd, "package.json"), "utf-8");
+    if (existsSync2(join2(cwd, "package.json"))) {
+      const raw = readFileSync2(join2(cwd, "package.json"), "utf-8");
       const pkg = JSON.parse(raw);
       const deps = { ...pkg.dependencies, ...pkg.devDependencies };
       if (deps["next"]) return "Next.js (React, TypeScript)";
@@ -267,24 +199,24 @@ function detectStack(cwd) {
       if (deps["express"]) return "Node.js (Express, TypeScript)";
       return "Node.js (TypeScript)";
     }
-    if (existsSync(join(cwd, "pyproject.toml")) || existsSync(join(cwd, "requirements.txt"))) {
-      const hasFastapi = existsSync(join(cwd, "pyproject.toml")) && readFileSync(join(cwd, "pyproject.toml"), "utf-8").includes("fastapi");
+    if (existsSync2(join2(cwd, "pyproject.toml")) || existsSync2(join2(cwd, "requirements.txt"))) {
+      const hasFastapi = existsSync2(join2(cwd, "pyproject.toml")) && readFileSync2(join2(cwd, "pyproject.toml"), "utf-8").includes("fastapi");
       return hasFastapi ? "Python (FastAPI)" : "Python";
     }
-    if (existsSync(join(cwd, "Cargo.toml"))) return "Rust";
-    if (existsSync(join(cwd, "go.mod"))) return "Go";
-    if (existsSync(join(cwd, "pubspec.yaml"))) return "Flutter (Dart)";
+    if (existsSync2(join2(cwd, "Cargo.toml"))) return "Rust";
+    if (existsSync2(join2(cwd, "go.mod"))) return "Go";
+    if (existsSync2(join2(cwd, "pubspec.yaml"))) return "Flutter (Dart)";
   } catch {
   }
   return "";
 }
 async function init(tokenArg) {
   if (hasConfig()) {
-    console.log("Already initialized. Run `intentdocs sync` to refresh.");
+    console.log("Already initialized. Run `npx intentdocs sync` to refresh.");
     return;
   }
   if (tokenArg) {
-    console.error("Sync tokens have been retired \u2014 `intentdocs init` no longer takes one. Run `intentdocs login`, then `intentdocs init` and pick the project and map.");
+    console.error("Sync tokens have been retired \u2014 `npx intentdocs init` no longer takes one. Run `npx intentdocs login`, then `npx intentdocs init` and pick the project and map.");
     process.exit(1);
   }
   let auth = getAuth();
@@ -332,14 +264,7 @@ ${whereIAm}`);
 Story maps in "${project.name}":
 `);
     const map2 = await pickFromList(rl, maps, (m) => m.title, "Select story map");
-    const config = {
-      apiBase: auth.apiBase,
-      mapTitle: map2.title,
-      projectId: project.id,
-      mapId: map2.id,
-      workspace: project.workspace ? { orgId: project.workspace.orgId, name: project.workspace.name } : { orgId: null, name: null },
-      ...appUrl && { appUrl }
-    };
+    const config = checkoutConfig({ apiBase: auth.apiBase, project, map: map2, appUrl });
     console.log(`
 Connecting to "${map2.title}"${project.workspace ? ` in ${project.workspace.name ?? "its workspace"}` : ""}...`);
     try {
@@ -356,8 +281,8 @@ Connecting to "${map2.title}"${project.workspace ? ` in ${project.workspace.name
     writeConfig(config);
     await setupFiles(config);
     await setupStack(rl);
-    const specPath = join(process.cwd(), "INTENT.md");
-    const claudeMdBytes = existsSync(specPath) ? statSync(specPath).size : 0;
+    const specPath = join2(process.cwd(), "INTENT.md");
+    const claudeMdBytes = existsSync2(specPath) ? statSync(specPath).size : 0;
     captureCli(
       "harness_initialized",
       {
@@ -370,28 +295,48 @@ Connecting to "${map2.title}"${project.workspace ? ` in ${project.workspace.name
     console.log(`
   \u2705 Ready! Next steps:
 
-    intent status         \u2014 see your story map
-    intent next           \u2014 pick up the first story
-    intent setup          \u2014 configure Claude Code / Cursor slash commands
-    intent ci             \u2014 report your tests' results from CI to each story
-    intent propose        \u2014 plan a new feature from the terminal
+    npx intentdocs status         \u2014 see your story map
+    npx intentdocs next           \u2014 pick up the first story
+    npx intentdocs setup          \u2014 configure Claude Code / Cursor slash commands
+    npx intentdocs ci             \u2014 report your tests' results from CI to each story
+    npx intentdocs propose        \u2014 plan a new feature from the terminal
     `);
+    await offerAllowList((q) => ask2(rl, q));
     const setUpCi = await ask2(rl, "  Set up CI test reporting now? It creates a key and adds the workflow. (y/N): ");
     if (/^y(es)?$/i.test(setUpCi.trim())) {
-      const { ci: ci2 } = await import("./ci-LBOCMRKZ.js");
+      const { ci: ci2 } = await import("./ci-NOCV3XUV.js");
       await ci2();
     } else {
-      console.log("  You can run `intent ci` any time to turn it on.\n");
+      console.log("  You can run `npx intentdocs ci` any time to turn it on.\n");
     }
   } finally {
     rl.close();
     await shutdownCliAnalytics();
   }
 }
+async function offerAllowList(askFn, cwd = process.cwd(), home) {
+  const servers = detectServerNames(cwd, home);
+  console.log(`
+${describeAllowList(servers)}
+`);
+  const answer = await askFn("  Add them? (y/N): ");
+  if (!/^y(es)?$/i.test(answer.trim())) {
+    console.log("  Left as is \u2014 Claude Code will keep asking before each call.\n");
+    console.log(`${CURSOR_ALLOW_NOTE}
+`);
+    return false;
+  }
+  const { path, added } = writeProjectAllowList(cwd, allowRules(servers));
+  console.log(`  \u2713 Allowed ${added} ${added === 1 ? "tool" : "tools"} in ${path.replace(cwd + "/", "")}
+`);
+  console.log(`${CURSOR_ALLOW_NOTE}
+`);
+  return true;
+}
 async function setupStack(rl) {
   const cwd = process.cwd();
-  const archPath = join(cwd, "ARCHITECTURE.md");
-  if (existsSync(archPath)) return;
+  const archPath = join2(cwd, "ARCHITECTURE.md");
+  if (existsSync2(archPath)) return;
   const detected = detectStack(cwd);
   let stack;
   if (detected) {
@@ -432,38 +377,38 @@ _Record trade-offs and why._
 
 _Add important files and what they do as you build._
 `;
-  writeFileSync(archPath, archContent);
+  writeFileSync2(archPath, archContent);
   console.log(`  \u2713 Created ARCHITECTURE.md with your stack (edit it as you build)`);
 }
 async function setupFiles(config) {
   try {
     const md = await getContext(config);
-    writeFileSync(join(process.cwd(), "INTENT.md"), md);
+    writeFileSync2(join2(process.cwd(), "INTENT.md"), md);
     console.log("\u2713 Downloaded INTENT.md");
   } catch {
     console.warn("\u26A0 Could not download INTENT.md");
   }
-  const gitignore = join(process.cwd(), ".gitignore");
-  if (existsSync(gitignore)) {
-    const content = readFileSync(gitignore, "utf-8");
+  const gitignore = join2(process.cwd(), ".gitignore");
+  if (existsSync2(gitignore)) {
+    const content = readFileSync2(gitignore, "utf-8");
     if (!content.includes(".intent/")) {
       appendFileSync(gitignore, "\n# intentdocs\n.intent/\n");
       console.log("\u2713 Added .intent/ to .gitignore");
     }
   }
   const cwd = process.cwd();
-  if (existsSync(join(cwd, "CLAUDE.md"))) {
-    const claudeMd = readFileSync(join(cwd, "CLAUDE.md"), "utf-8");
+  if (existsSync2(join2(cwd, "CLAUDE.md"))) {
+    const claudeMd = readFileSync2(join2(cwd, "CLAUDE.md"), "utf-8");
     if (!claudeMd.includes("INTENT.md")) {
-      appendFileSync(join(cwd, "CLAUDE.md"), INTENTDOCS_CLAUDE_BLOCK);
+      appendFileSync(join2(cwd, "CLAUDE.md"), INTENTDOCS_CLAUDE_BLOCK);
       console.log("\u2713 Added INTENT.md reference to CLAUDE.md");
     }
   }
-  if (existsSync(join(cwd, ".cursorrules"))) {
-    const rules = readFileSync(join(cwd, ".cursorrules"), "utf-8");
+  if (existsSync2(join2(cwd, ".cursorrules"))) {
+    const rules = readFileSync2(join2(cwd, ".cursorrules"), "utf-8");
     if (!rules.includes("INTENT.md")) {
       appendFileSync(
-        join(cwd, ".cursorrules"),
+        join2(cwd, ".cursorrules"),
         "\n\nRead INTENT.md for the product story map, personas, and backlog.\n"
       );
       console.log("\u2713 Added INTENT.md reference to .cursorrules");
@@ -646,8 +591,8 @@ function kanbanView(stories2) {
 
 // src/commands/next.ts
 import { execSync } from "child_process";
-import { writeFileSync as writeFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { writeFileSync as writeFileSync3 } from "fs";
+import { join as join3 } from "path";
 
 // src/lib/verification-suggestions.ts
 function needsVerificationSuggestion(ac) {
@@ -692,13 +637,11 @@ function parseVerificationSuggestions(raw) {
 // src/commands/next.ts
 var PRIORITY_ORDER = { must: 0, should: 1, could: 2 };
 var EFFORT_ORDER = { S: 0, M: 1, L: 2, XL: 3 };
-function unsequencedRefusal(story, apiBase, mapId) {
+function unsequencedNote(story, apiBase, mapId) {
   const planUrl = `${apiBase}/storymapper/${mapId}?phase=plan&story=${story.id}`;
   return `
-  \u{1F512} "${story.title}" is unsequenced \u2014 it hasn't been ordered on the Plan view yet.
-
-  Agents only build stories you've deliberately sequenced. Drag it into the
-  plan (or set its build order) here, then retry:
+  \u2139\uFE0F  "${story.title}" isn't in the build order yet. Starting it adds it to the end;
+     reorder it on the Plan view if it belongs elsewhere:
   \u2192 ${planUrl}
 `;
 }
@@ -714,10 +657,7 @@ async function next(opts = {}) {
 `);
       return;
     }
-    if (match.build_sequence == null) {
-      console.log(unsequencedRefusal(match, config.apiBase, data.map.id));
-      return;
-    }
+    if (match.build_sequence == null) console.log(unsequencedNote(match, config.apiBase, data.map.id));
     s = match;
   } else {
     if (!opts.skipWip) {
@@ -728,10 +668,10 @@ async function next(opts = {}) {
 `);
         for (const ip of inProgress) {
           console.log(`    \u{1F528} ${ip.title}`);
-          console.log(`       ID: ${ip.id.slice(0, 8)} | Mark done: intent done ${ip.id.slice(0, 8)}`);
+          console.log(`       ID: ${ip.id.slice(0, 8)} | Mark done: npx intentdocs done ${ip.id.slice(0, 8)}`);
         }
         console.log(`
-  Finish those first, or run \`intentdocs next --skip-wip\` to pick the next todo anyway.
+  Finish those first, or run \`npx intentdocs next --skip-wip\` to pick the next todo anyway.
 `);
         return;
       }
@@ -759,12 +699,12 @@ async function next(opts = {}) {
       if (unsequencedCount > 0) {
         console.log(`
   \u{1F512} ${unsequencedCount} stor${unsequencedCount === 1 ? "y is" : "ies are"} unsequenced \u2014 agents only build stories you've deliberately ordered.`);
-        console.log(`  Sequence ${unsequencedCount === 1 ? "it" : "them"} on the Plan view, then run \`intentdocs next\` again.
+        console.log(`  Sequence ${unsequencedCount === 1 ? "it" : "them"} on the Plan view, then run \`npx intentdocs next\` again.
 `);
       } else if (blockedCount > 0) {
         console.log(`
   \u{1F512} ${blockedCount} stories remain but all have unfinished dependencies.`);
-        console.log(`  Finish in-progress stories first, then run \`intentdocs next\` again.
+        console.log(`  Finish in-progress stories first, then run \`npx intentdocs next\` again.
 `);
       } else {
         console.log("\n  \u{1F389} All stories are done! Ship it.\n");
@@ -794,14 +734,14 @@ async function next(opts = {}) {
     console.log(`  Plan: \u2705 Implementation plan available`);
   }
   console.log(`
-  Start building: intent implement ${s.id.slice(0, 8)}
+  Start building: npx intentdocs implement ${storyRef(s)}
 `);
   if (opts.open) {
-    openBrowser2(specUrl);
+    openBrowser(specUrl);
   }
   await shutdownCliAnalytics();
 }
-async function generateVerificationSuggestions(story, contextPath) {
+async function generateVerificationSuggestions(story, contextPath, config) {
   const acs = story.acceptance_criteria;
   const candidates = acs.filter(needsVerificationSuggestion);
   if (acs.length === 0) {
@@ -814,13 +754,84 @@ async function generateVerificationSuggestions(story, contextPath) {
 `);
     return;
   }
-  const apiKey = process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    console.log(`  \u26A0\uFE0F  ANTHROPIC_API_KEY not set \u2014 skipping verification suggestions.
+  console.log(`  Suggesting verification commands for ${candidates.length} criteri${candidates.length !== 1 ? "a" : "on"}\u2026`);
+  let found = null;
+  let serverRefusal = null;
+  if (config?.mapId) {
+    try {
+      const res = await fetch(apiUrl(config, "/verification-suggestions"), {
+        method: "POST",
+        headers: syncHeaders({ "Content-Type": "application/json" }),
+        body: JSON.stringify({ story_id: story.id })
+      });
+      if (res.ok) {
+        const json = await res.json();
+        const byId = new Map(acs.map((ac) => [ac.id, ac]));
+        found = {
+          criteria: json.criteria.map((c) => byId.get(c.id) ?? { id: c.id, text: c.text, done: false }),
+          suggestions: json.suggestions
+        };
+      } else if (isPlanGated(res.status)) {
+        serverRefusal = "plan";
+      } else if (res.status === 404 || res.status === 405) {
+        serverRefusal = "unsupported";
+      } else {
+        console.log(`  \u26A0\uFE0F  intentdocs couldn't suggest commands (${res.status}) \u2014 suggestion generation skipped.
+`);
+        return;
+      }
+    } catch {
+      console.log(`  \u26A0\uFE0F  Network error \u2014 suggestion generation skipped.
+`);
+      return;
+    }
+  } else {
+    serverRefusal = "unsupported";
+  }
+  if (!found) {
+    const envKey = process.env.ANTHROPIC_API_KEY;
+    if (!envKey) {
+      if (serverRefusal === "plan") {
+        console.log(`  \u26A0\uFE0F  Verification suggestions need a paid plan or your own Anthropic key \u2014 run \`npx intentdocs keys set\`. Skipped.
+`);
+      } else {
+        console.log(`  \u26A0\uFE0F  No saved Anthropic key reached the server and ANTHROPIC_API_KEY is not set \u2014 skipping verification suggestions.
+`);
+      }
+      return;
+    }
+    const suggestions = await suggestWithKey(envKey, story, candidates);
+    if (!suggestions) return;
+    found = { criteria: candidates, suggestions };
+  }
+  if (found.suggestions.length === 0) {
+    console.log(`  \u26A0\uFE0F  Couldn't parse a usable response from Anthropic \u2014 suggestion generation skipped.
 `);
     return;
   }
-  console.log(`  Suggesting verification commands for ${candidates.length} criteri${candidates.length !== 1 ? "a" : "on"}\u2026`);
+  const lines = [`# Suggested verification commands: ${story.title}`, ``, `_Generated by \`npx intentdocs implement --stub\` \u2014 copy into the criterion's command field, or run \`npx intentdocs check\` once wired up._`, ``];
+  console.log();
+  for (const suggestion of found.suggestions) {
+    const ac = found.criteria[suggestion.index - 1];
+    if (!ac) continue;
+    if (suggestion.executable && suggestion.command) {
+      console.log(`  \u2192 ${ac.text}`);
+      console.log(`    command: ${suggestion.command}${suggestion.expected ? `  (expect: ${suggestion.expected})` : ""}`);
+      lines.push(`- **${ac.text}**`, `  - command: \`${suggestion.command}\``, ...suggestion.expected ? [`  - expected: ${suggestion.expected}`] : [], ``);
+    } else {
+      console.log(`  \u2192 ${ac.text}`);
+      console.log(`    not executable${suggestion.reason ? `: ${suggestion.reason}` : ""}`);
+      lines.push(`- **${ac.text}**`, `  - not executable${suggestion.reason ? `: ${suggestion.reason}` : ""}`, ``);
+    }
+  }
+  const suggestionsPath = contextPath.replace(/\.md$/, ".checks.md");
+  writeFileSync3(suggestionsPath, lines.join("\n"));
+  const relPath = suggestionsPath.replace(join3(process.cwd(), "/"), "");
+  console.log(`
+  \u2713 Suggestions written: ${relPath}
+`);
+}
+async function suggestWithKey(apiKey, story, candidates) {
   const prompt = buildVerificationSuggestionPrompt(story.title, story.user_story, candidates);
   let raw;
   try {
@@ -840,44 +851,18 @@ async function generateVerificationSuggestions(story, contextPath) {
     if (!res.ok) {
       console.log(`  \u26A0\uFE0F  Anthropic API error (${res.status}) \u2014 suggestion generation skipped.
 `);
-      return;
+      return null;
     }
     const json = await res.json();
     raw = json.content.find((c) => c.type === "text")?.text ?? "";
   } catch {
     console.log(`  \u26A0\uFE0F  Network error \u2014 suggestion generation skipped.
 `);
-    return;
-  }
-  const suggestions = parseVerificationSuggestions(raw);
-  if (suggestions.length === 0) {
-    console.log(`  \u26A0\uFE0F  Couldn't parse a usable response from Anthropic \u2014 suggestion generation skipped.
-`);
-    return;
-  }
-  const lines = [`# Suggested verification commands: ${story.title}`, ``, `_Generated by \`intentdocs next --stub\` \u2014 copy into the criterion's command field, or run \`intentdocs check\` once wired up._`, ``];
-  console.log();
-  for (const suggestion of suggestions) {
-    const ac = candidates[suggestion.index - 1];
-    if (!ac) continue;
-    if (suggestion.executable && suggestion.command) {
-      console.log(`  \u2192 ${ac.text}`);
-      console.log(`    command: ${suggestion.command}${suggestion.expected ? `  (expect: ${suggestion.expected})` : ""}`);
-      lines.push(`- **${ac.text}**`, `  - command: \`${suggestion.command}\``, ...suggestion.expected ? [`  - expected: ${suggestion.expected}`] : [], ``);
-    } else {
-      console.log(`  \u2192 ${ac.text}`);
-      console.log(`    not executable${suggestion.reason ? `: ${suggestion.reason}` : ""}`);
-      lines.push(`- **${ac.text}**`, `  - not executable${suggestion.reason ? `: ${suggestion.reason}` : ""}`, ``);
-    }
+    return null;
   }
-  const suggestionsPath = contextPath.replace(/\.md$/, ".checks.md");
-  writeFileSync2(suggestionsPath, lines.join("\n"));
-  const relPath = suggestionsPath.replace(join2(process.cwd(), "/"), "");
-  console.log(`
-  \u2713 Suggestions written: ${relPath}
-`);
+  return parseVerificationSuggestions(raw);
 }
-function openBrowser2(url) {
+function openBrowser(url) {
   try {
     const platform = process.platform;
     const cmd = platform === "darwin" ? `open "${url}"` : platform === "win32" ? `start "" "${url}"` : `xdg-open "${url}"`;
@@ -890,13 +875,12 @@ function openBrowser2(url) {
 async function implement(storyId, opts = {}) {
   const config = requireConfig();
   const data = await listStories(config);
-  const match = data.stories.find(
-    (st) => st.id === storyId || st.id.startsWith(storyId)
-  );
+  const match = data.stories.find((st) => matchesStoryRef(st, storyId));
   if (!match) {
     console.log(`
-  \u274C No story found matching ID: ${storyId}
+  \u274C No story found matching "${storyId}"
 `);
+    process.exitCode = 1;
     return;
   }
   const s = match;
@@ -910,14 +894,11 @@ async function implement(storyId, opts = {}) {
   if (s.status === "in_progress") {
     console.log(`
   \u{1F528} "${s.title}" is already in progress.`);
-    console.log(`     Mark done: intent done ${s.id.slice(0, 8)}
+    console.log(`     Mark done: npx intentdocs done ${storyRef(s)}
 `);
     return;
   }
-  if (s.build_sequence == null) {
-    console.log(unsequencedRefusal(s, config.apiBase, data.map.id));
-    return;
-  }
+  if (s.build_sequence == null) console.log(unsequencedNote(s, config.apiBase, data.map.id));
   const doneIds = new Set(
     data.stories.filter((st) => st.status === "done").map((st) => st.id)
   );
@@ -952,7 +933,7 @@ async function implement(storyId, opts = {}) {
     }
     console.log(`  \u2502                                                       \u2502`);
     console.log(`  \u2502  Consider:                                            \u2502`);
-    console.log(`  \u2502    intent sync --context   refresh CLAUDE.md first      \u2502`);
+    console.log(`  \u2502    npx intentdocs sync --context  (refresh CLAUDE.md) \u2502`);
     console.log(`  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
 `);
     const proceed = isInteractive() ? await confirm("  Assign this story and mark in progress?") : false;
@@ -976,8 +957,18 @@ async function implement(storyId, opts = {}) {
 `);
   }
   try {
-    await updateStories(config, [{ id: s.id, status: "in_progress", cancelled_at: null }]);
-  } catch {
+    const result = await updateStories(config, [{ id: s.id, status: "in_progress", cancelled_at: null }]);
+    if (result.missing?.includes(s.id)) {
+      throw new Error("the server reports the story matched no row \u2014 run `npx intentdocs stories` and try again");
+    }
+  } catch (err) {
+    console.error(`
+  \u2717 Not picked up: "${s.title}"`);
+    console.error(`    ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exitCode = 1;
+    await shutdownCliAnalytics();
+    return;
   }
   const contextPath = writeStoryContext(s);
   const relPath = contextPath.replace(process.cwd() + "/", "");
@@ -999,22 +990,22 @@ async function implement(storyId, opts = {}) {
   console.log(`  Priority: ${s.priority} | Effort: ${s.effort} | Release: ${s.release}${s.build_sequence ? ` | Build step: ${s.build_sequence}` : ""}`);
   console.log(`  Context: ${relPath}`);
   console.log(`  Spec:    ${specUrl}`);
-  console.log(`  Mark done: intent done ${s.id.slice(0, 8)}
+  console.log(`  Mark done: npx intentdocs done ${storyRef(s)}
 `);
   if (opts.stub) {
-    await generateVerificationSuggestions(s, contextPath);
+    await generateVerificationSuggestions(s, contextPath, config);
   }
   await shutdownCliAnalytics();
 }
 
 // src/commands/done.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 
 // src/lib/screenshot.ts
 import { createRequire } from "module";
 import { pathToFileURL } from "url";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { extname, join as join3 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { extname, join as join4 } from "path";
 var MAX_BYTES = 5 * 1024 * 1024;
 var EXT_MIME = {
   ".png": "image/png",
@@ -1024,7 +1015,7 @@ var EXT_MIME = {
 };
 async function loadPlaywright() {
   try {
-    const req = createRequire(join3(process.cwd(), "package.json"));
+    const req = createRequire(join4(process.cwd(), "package.json"));
     const resolved = req.resolve("playwright");
     return await import(pathToFileURL(resolved).href);
   } catch {
@@ -1032,7 +1023,7 @@ async function loadPlaywright() {
   }
 }
 function readScreenshotFile(path) {
-  if (!existsSync2(path)) {
+  if (!existsSync3(path)) {
     console.error(`  Screenshot file not found: ${path}`);
     return null;
   }
@@ -1042,7 +1033,7 @@ function readScreenshotFile(path) {
     console.error(`  Unsupported screenshot type "${ext}" \u2014 use .png, .jpg, or .webp`);
     return null;
   }
-  const buffer = readFileSync2(path);
+  const buffer = readFileSync3(path);
   if (buffer.length > MAX_BYTES) {
     console.error(`  Screenshot too large (${(buffer.length / 1024 / 1024).toFixed(1)}MB, max 5MB)`);
     return null;
@@ -1080,8 +1071,8 @@ async function captureScreenshot(appUrl) {
 // src/commands/done.ts
 function extractImplementationContext(storyId) {
   const path = storyContextPath(storyId);
-  if (!existsSync3(path)) return { summary: null, files: [] };
-  const content = readFileSync3(path, "utf-8");
+  if (!existsSync4(path)) return { summary: null, files: [] };
+  const content = readFileSync4(path, "utf-8");
   const lines = content.split("\n");
   const notesStart = lines.findIndex((l) => l.trim() === "## Implementation notes");
   const decisionsStart = lines.findIndex((l) => l.trim() === "## Decisions");
@@ -1121,8 +1112,25 @@ async function passesCriteriaGuard(story) {
   const proceed = await confirm("  Mark done anyway?");
   return { proceed, forced: proceed, blockedNonInteractive: false };
 }
+function prNumberFromUrl(url) {
+  const m = url.match(/\/pull\/(\d+)\/?(?:[?#].*)?$/);
+  return m ? Number(m[1]) : null;
+}
 async function done(idPrefix, opts = {}) {
   const config = requireConfig();
+  const prUrl = opts.pr?.trim();
+  if (prUrl !== void 0) {
+    let valid = false;
+    try {
+      valid = /^https?:$/.test(new URL(prUrl).protocol);
+    } catch {
+      valid = false;
+    }
+    if (!valid) {
+      console.error(`  \u2717 --pr needs the pull request's URL, e.g. https://github.com/acme/app/pull/12 (got "${opts.pr}").`);
+      process.exit(1);
+    }
+  }
   const data = await listStories(config);
   const match = data.stories.find((s) => matchesStoryRef(s, idPrefix));
   if (!match) {
@@ -1140,7 +1148,7 @@ async function done(idPrefix, opts = {}) {
       console.error(
         `  \u2717 Not marked done: "${match.title}" has unresolved 'must' criteria and no TTY is available to confirm an override.`
       );
-      console.error(`    Report the criteria (intent check / report_criteria) or re-run interactively to force it.`);
+      console.error(`    Report the criteria (npx intentdocs check / report_criteria) or re-run interactively to force it.`);
       process.exit(1);
     }
     return;
@@ -1161,6 +1169,11 @@ async function done(idPrefix, opts = {}) {
   if (summary) update.implementation_summary = summary;
   if (files.length > 0) update.implemented_files = files;
   if (screenshotUrl) update.screenshot_url = screenshotUrl;
+  if (prUrl) {
+    update.pr_url = prUrl;
+    const prNumber = prNumberFromUrl(prUrl);
+    if (prNumber) update.pr_number = prNumber;
+  }
   const result = await updateStories(config, [update]);
   const verify = await listStories(config);
   const persisted = verify.stories.find((s) => s.id === match.id);
@@ -1168,7 +1181,7 @@ async function done(idPrefix, opts = {}) {
     console.error(
       `  \u2717 Done-mark did not persist: server reports status="${persisted?.status ?? "not found"}" for "${match.title}" after the update.`
     );
-    console.error(`    Not treating this run as successful \u2014 re-run \`intent done ${idPrefix}\` or check the sync API.`);
+    console.error(`    Not treating this run as successful \u2014 re-run \`npx intentdocs done ${idPrefix}\` or check the sync API.`);
     await shutdownCliAnalytics();
     closePrompt();
     process.exit(1);
@@ -1190,6 +1203,11 @@ async function done(idPrefix, opts = {}) {
   if (summary) console.log(`   \u21B3 Implementation summary posted to story map`);
   if (files.length > 0) console.log(`   \u21B3 ${files.length} file(s) recorded`);
   if (screenshotUrl) console.log(`   \u21B3 Screenshot attached`);
+  if (prUrl) {
+    console.log(`   \u21B3 PR linked: ${prUrl}`);
+    const stamp = result.pr_stamps?.find((p) => p.id === match.id);
+    if (stamp?.message) console.log(`   ${stamp.message.replace(/\n/g, "\n   ")}`);
+  }
   for (const release of result.readyReleases ?? []) {
     console.log();
     console.log(`\u{1F3C1} ${release.label} is ready to close (${release.storyCount} stories done) \u2014 close it on Validate \u203A Release`);
@@ -1247,13 +1265,12 @@ async function done(idPrefix, opts = {}) {
 async function stop(storyId) {
   const config = requireConfig();
   const data = await listStories(config);
-  const match = data.stories.find(
-    (st) => st.id === storyId || st.id.startsWith(storyId)
-  );
+  const match = data.stories.find((st) => matchesStoryRef(st, storyId));
   if (!match) {
     console.log(`
-  \u274C No story found matching ID: ${storyId}
+  \u274C No story found matching "${storyId}"
 `);
+    process.exitCode = 1;
     return;
   }
   if (match.status !== "in_progress") {
@@ -1320,7 +1337,7 @@ function resolveStory(stories2, idPrefix) {
   const inProgress = stories2.filter((s) => s.status === "in_progress");
   if (inProgress.length === 1) return { story: inProgress[0] };
   return {
-    error: inProgress.length === 0 ? "No story in progress. Specify one: intent check <idPrefix>" : `${inProgress.length} stories in progress \u2014 specify one: intent check <idPrefix>`
+    error: inProgress.length === 0 ? "No story in progress. Specify one: npx intentdocs check <idPrefix>" : `${inProgress.length} stories in progress \u2014 specify one: npx intentdocs check <idPrefix>`
   };
 }
 async function check(idPrefix, opts = {}) {
@@ -1466,7 +1483,7 @@ async function start() {
   } catch (err) {
     spinner.fail("  Failed to connect");
     console.error(`  ${err.message}`);
-    console.error("  Make sure you're logged in: intentdocs login");
+    console.error("  Make sure you're logged in: npx intentdocs login");
     closePrompt();
     return;
   }
@@ -1538,14 +1555,14 @@ async function start() {
   Failed to create project: ${data.error ?? "unknown error"}`);
       }
     } else {
-      console.error("\n  Failed to create project. Try logging in again: intentdocs login");
+      console.error("\n  Failed to create project. Try logging in again: npx intentdocs login");
     }
     closePrompt();
     return;
   }
   const createContentType = createRes.headers.get("content-type") ?? "";
   if (!createContentType.includes("application/json")) {
-    console.error("\n  Unexpected response from server. Try logging in again: intentdocs login");
+    console.error("\n  Unexpected response from server. Try logging in again: npx intentdocs login");
     closePrompt();
     return;
   }
@@ -1609,7 +1626,7 @@ async function start() {
   if (!readyToScope) {
     console.log(`
   No worries! When you're ready:
-    \u2022 Run: intent scope ${projectId}
+    \u2022 Run: npx intentdocs scope ${projectId}
     \u2022 Or visit: ${API_BASE}
 
   Your project is saved and waiting for you.
@@ -1617,17 +1634,28 @@ async function start() {
     closePrompt();
     return;
   }
-  const { scope: scope2 } = await import("./scope-S3LZZ3KB.js");
+  const { scope: scope2 } = await import("./scope-RRGJHS2G.js");
   await scope2(projectId);
 }
 
 // src/commands/propose.ts
-import { mkdirSync, writeFileSync as writeFileSync3, readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
-import { join as join4 } from "path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4, readFileSync as readFileSync5, existsSync as existsSync5, appendFileSync as appendFileSync2 } from "fs";
+import { join as join5 } from "path";
+function ensureChangesIgnored(cwd = process.cwd()) {
+  const gitignorePath = join5(cwd, ".gitignore");
+  if (!existsSync5(gitignorePath)) return;
+  const covered = readFileSync5(gitignorePath, "utf-8").split(/\r?\n/).some((line) => /^\/?intent-changes\/?(\*\*?)?$/.test(line.trim()));
+  if (covered) return;
+  const gi = readFileSync5(gitignorePath, "utf-8");
+  appendFileSync2(gitignorePath, `${gi.endsWith("\n") || gi === "" ? "" : "\n"}
+# intentdocs local change proposals
+intent-changes/
+`);
+}
 async function propose(changeName, opts = {}) {
   await requireValidAuth();
   if (!hasConfig()) {
-    console.log("  Not connected to a project. Run `intentdocs init` first.");
+    console.log("  Not connected to a project. Run `npx intentdocs init` first.");
     closePrompt();
     return;
   }
@@ -1716,8 +1744,8 @@ async function propose(changeName, opts = {}) {
   \u2717 Failed to create stories: ${err instanceof Error ? err.message : String(err)}`);
     console.log("  Saving proposal locally anyway...");
   }
-  const changesDir = join4(process.cwd(), "intent-changes", slug);
-  if (!existsSync4(changesDir)) mkdirSync(changesDir, { recursive: true });
+  const changesDir = join5(process.cwd(), "intent-changes", slug);
+  if (!existsSync5(changesDir)) mkdirSync2(changesDir, { recursive: true });
   const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const proposalMd = [
     `# Proposal: ${changeName}`,
@@ -1752,16 +1780,9 @@ async function propose(changeName, opts = {}) {
     `_Add notes here as you build._`,
     ``
   ].join("\n");
-  writeFileSync3(join4(changesDir, "proposal.md"), proposalMd);
+  writeFileSync4(join5(changesDir, "proposal.md"), proposalMd);
   console.log(`  \u2713 Saved intent-changes/${slug}/proposal.md`);
-  const gitignorePath = join4(process.cwd(), ".gitignore");
-  if (existsSync4(gitignorePath)) {
-    const { readFileSync: readFileSync5, appendFileSync: appendFileSync2 } = await import("fs");
-    const gi = readFileSync5(gitignorePath, "utf-8");
-    if (!gi.includes("intent-changes")) {
-      appendFileSync2(gitignorePath, "\n# intentdocs local change proposals\nstc-changes/\n");
-    }
-  }
+  ensureChangesIgnored();
   console.log(`
   \u2705 Proposal "${changeName}" ready!
 
@@ -1769,14 +1790,14 @@ async function propose(changeName, opts = {}) {
   Local spec saved at: intent-changes/${slug}/proposal.md
 
   Next:
-    intent next           \u2014 pick up the first story
-    intent status         \u2014 see full progress
-    intent sync           \u2014 refresh INTENT.md
+    npx intentdocs next           \u2014 pick up the first story
+    npx intentdocs status         \u2014 see full progress
+    npx intentdocs sync           \u2014 refresh INTENT.md
   `);
   closePrompt();
 }
 function parseProposalFile(filePath) {
-  const raw = readFileSync4(filePath, "utf-8");
+  const raw = readFileSync5(filePath, "utf-8");
   const lines = raw.split("\n");
   let changeName = "";
   let problem = "";
@@ -1850,7 +1871,7 @@ function parseProposalFile(filePath) {
   return { changeName, problem, solution, activity, priority, stories: stories2 };
 }
 async function proposeFromFile(filePath, config, nameOverride) {
-  if (!existsSync4(filePath)) {
+  if (!existsSync5(filePath)) {
     console.error(`
   File not found: ${filePath}
 `);
@@ -1886,8 +1907,8 @@ async function proposeFromFile(filePath, config, nameOverride) {
   \u2717 Failed to create stories: ${err instanceof Error ? err.message : String(err)}`);
     console.log("  Saving proposal locally anyway...");
   }
-  const changesDir = join4(process.cwd(), "intent-changes", slug);
-  if (!existsSync4(changesDir)) mkdirSync(changesDir, { recursive: true });
+  const changesDir = join5(process.cwd(), "intent-changes", slug);
+  if (!existsSync5(changesDir)) mkdirSync2(changesDir, { recursive: true });
   const proposalMd = [
     `# Proposal: ${changeName}`,
     ``,
@@ -1918,10 +1939,11 @@ async function proposeFromFile(filePath, config, nameOverride) {
       ].join("\n");
     })
   ].join("\n");
-  writeFileSync3(join4(changesDir, "proposal.md"), proposalMd);
+  writeFileSync4(join5(changesDir, "proposal.md"), proposalMd);
   console.log(`  \u2713 Saved intent-changes/${slug}/proposal.md`);
+  ensureChangesIgnored();
   console.log(`
-  \u2705 Done! Run \`intentdocs next\` to start building.
+  \u2705 Done! Run \`npx intentdocs next\` to start building.
 `);
 }
 
@@ -1938,7 +1960,7 @@ async function show(idPrefix) {
   if (!story) {
     console.error(`
   No story found matching "${idPrefix}"
-  Run \`intentdocs stories\` to list IDs.
+  Run \`npx intentdocs stories\` to list IDs.
 `);
     process.exit(1);
   }
@@ -1992,7 +2014,7 @@ async function show(idPrefix) {
   const relPath = contextPath.replace(process.cwd() + "/", "");
   console.log(`
   Context  : ${relPath}`);
-  console.log(`  Mark done: intent done ${storyRef(story)}
+  console.log(`  Mark done: npx intentdocs done ${storyRef(story)}
 `);
 }
 
@@ -2041,7 +2063,7 @@ async function example() {
     console.log(`
   \u2713 Example saved: "${data.title}"
 `);
-    console.log("  Run `intentdocs sync --context` to regenerate your CLAUDE.md with this pattern.\n");
+    console.log("  Run `npx intentdocs sync --context` to regenerate your CLAUDE.md with this pattern.\n");
   } catch {
     rl.close();
     throw new Error("Aborted");
@@ -2291,7 +2313,7 @@ var TOOLS = [
   },
   {
     name: "add_note",
-    description: "Add implementation notes to a story. Use this to record how something was built, gotchas, or context for future developers.",
+    description: "Add an implementation note to a story \u2014 appended to its existing notes, never replacing them. Use this to record how something was built, gotchas, or context for future developers.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2467,16 +2489,6 @@ async function handleToolCall(name, args, config) {
       const data = await listStories(config);
       const match = data.stories.find((s) => matchesStoryRef(s, storyId));
       if (!match) return { content: [{ type: "text", text: `No story found matching "${storyId}"` }] };
-      if (match.build_sequence == null) {
-        return {
-          content: [{
-            type: "text",
-            text: `\u{1F512} "${match.title}" is unsequenced \u2014 it hasn't been ordered on the Plan view yet.
-
-Agents only build stories that have been deliberately sequenced. Sequence it on the Plan view (drag it into the plan or set its build order), then retry.`
-          }]
-        };
-      }
       const result = await updateStories(config, [{ id: match.id, status: "in_progress" }]);
       if (result.missing?.includes(match.id)) {
         return {
@@ -2486,8 +2498,11 @@ Agents only build stories that have been deliberately sequenced. Sequence it on
           }]
         };
       }
+      const placed = result.sequenced?.find((x) => x.id === match.id);
+      const note = placed ? `
+It wasn't in the build order, so it's been placed at the end of the build order.` : "";
       return {
-        content: [{ type: "text", text: `\u2713 ${match.title} \u2192 in_progress` }]
+        content: [{ type: "text", text: `\u2713 ${match.title} \u2192 in_progress${note}` }]
       };
     }
     case "mark_done": {
@@ -2687,7 +2702,7 @@ Decision needed: ${decisionNeeded}`
       await apiFetch(config, "/stories", {
         method: "PATCH",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ stories: [{ id: match.id, notes: note }] })
+        body: JSON.stringify({ stories: [{ id: match.id, notes: appendToNotes(match.notes, note) }] })
       });
       return { content: [{ type: "text", text: `\u2713 Note added to: ${match.title}` }] };
     }
@@ -2919,7 +2934,7 @@ async function startMcpServer(mode = "all") {
 import { execSync as execSync3 } from "child_process";
 async function openclawRegister() {
   if (!hasConfig()) {
-    console.error("Not initialised. Run: intent init");
+    console.error("Not initialised. Run: npx intentdocs init");
     process.exit(1);
   }
   const config = readConfig();
@@ -2961,15 +2976,15 @@ var program = new Command();
 program.name("intentdocs").description("Write specs, map stories, ship with AI \u2014 from your terminal").version(version);
 program.command("login").description("Log in to intentdocs (opens browser)").action(() => void login());
 program.command("logout").description("Log out of intentdocs").action(() => void logout());
-var keys = program.command("keys").description("Manage your Anthropic API key \u2014 unlock AI features on any plan");
-keys.command("set [key]").description("Save your Anthropic API key (prompts if omitted)").action((key) => {
-  import("./keys-5PA3D6CX.js").then((m) => void m.keysSet(key));
+var keys = program.command("keys").description("Manage your Anthropic (sk-ant-), xAI (xai-), or OpenAI (sk- / sk-proj-) API key \u2014 unlock AI features on any plan");
+keys.command("set [key]").description("Save an Anthropic (sk-ant-), xAI (xai-), or OpenAI (sk- / sk-proj-) API key (prompts if omitted)").action((key) => {
+  import("./keys-2W5V56FS.js").then((m) => void m.keysSet(key));
 });
 keys.command("status").description("Show whether a key is set (masked)").action(() => {
-  import("./keys-5PA3D6CX.js").then((m) => void m.keysStatus());
+  import("./keys-2W5V56FS.js").then((m) => void m.keysStatus());
 });
 keys.command("remove").description("Remove your stored key").action(() => {
-  import("./keys-5PA3D6CX.js").then((m) => void m.keysRemove());
+  import("./keys-2W5V56FS.js").then((m) => void m.keysRemove());
 });
 program.command("start").description("Start a new project \u2014 guided flow from problem to pitch").action(() => void start());
 program.command("scope [projectId]").description("Scope a project \u2014 generate blueprint, story map, and mockup").action((id) => void scope(id));
@@ -3001,7 +3016,10 @@ program.command("templates [name]").description("Browse story map templates").ac
   }
 });
 program.command("projects").description("List the projects your token can reach \u2014 the whole workspace it is bound to").action(() => {
-  import("./projects-F7GMH66U.js").then((m) => void m.projects());
+  import("./projects-AYAYVFKL.js").then((m) => void m.projects());
+});
+program.command("push").description("Upload this repo's nikOS intent/ folder: log in, create the project, and link the repo").action(() => {
+  import("./push-33V7ANJW.js").then((m) => m.push());
 });
 program.command("init [token]").description("Connect this project to a intentdocs story map").action((token) => void init(token));
 program.command("sync").description("Refresh INTENT.md from the live story map").option("--context", "Refresh only the CLAUDE.md/AGENTS.md context file (not stories)").action((opts) => void sync(opts));
@@ -3009,46 +3027,46 @@ program.command("ci").description("Set up CI test reporting \u2014 create a key,
 program.command("status").description("Show story map progress").action(() => void status());
 program.command("stories").description("List all stories").option("-f, --filter <filter>", "Filter by status (todo/in-progress/done) or search term").option("-s, --status <status>", "Filter by exact status: todo, in-progress, wip, done").option("-k, --kanban", "View stories as a kanban board (todo | in-progress | done)").action((opts) => void stories(opts));
 program.command("next").description("Show the next highest-priority story to work on").option("-o, --open", "Open the spec page in your browser").option("--skip-wip", "Show next todo even if stories are in progress").option("--story-id <id>", "Show a specific story by ID").action((opts) => void next(opts));
-program.command("implement <id>").description("Pick up a story and mark it in-progress").option("--stub", "Suggest verification commands for acceptance criteria (requires ANTHROPIC_API_KEY)").action((id, opts) => void implement(id, opts));
+program.command("implement <id>").description("Pick up a story and mark it in-progress (accepts its key or an ID prefix)").option("--stub", "Suggest verification commands for acceptance criteria (uses your saved key or plan; ANTHROPIC_API_KEY as a fallback)").action((id, opts) => void implement(id, opts));
 program.command("check [idPrefix]").description("Run executable acceptance criteria locally and print pass/fail (defaults to the in-progress story)").option("--report", "Report results back to the story map (reported_by: human)").action((idPrefix, opts) => void check(idPrefix, opts));
 program.command("show <id>").description("Show the full spec for a story (accepts ID prefix)").action((id) => void show(id));
-program.command("done <id>").description("Mark a story as done (accepts ID prefix)").option("--screenshot <path>", "Attach a screenshot of the product from an image file").action((id, opts) => void done(id, opts));
-program.command("stop <id>").description("Stop development of an in-progress story (resets to todo, signals agents to stop)").action((id) => void stop(id));
+program.command("done <id>").description("Mark a story as done (accepts its key or an ID prefix)").option("--screenshot <path>", "Attach a screenshot of the product from an image file").option("--pr <url>", "Link the story's pull request (stamped with the intentdocs footer when GitHub is connected)").action((id, opts) => void done(id, opts));
+program.command("stop <id>").description("Stop development of an in-progress story (resets to todo, signals agents to stop; accepts its key or an ID prefix)").action((id) => void stop(id));
 program.command("add <title>").description("Create a new story").option("-a, --activity <activity>", "Activity to add the story under").option("-p, --priority <priority>", "Priority: must, should, could", "should").option("-e, --effort <effort>", "Effort: S, M, L, XL", "M").action((title, opts) => void add(title, opts));
-var decide = program.command("decide [title]").description("Log an architectural or product decision").option("-d, --description <desc>", "Decision description").option("-c, --category <cat>", "Category: architecture, product, technical, trade-off", "technical").option("-s, --story <id>", "Link to a story ID").action((title, opts) => {
-  import("./log-EVLWM64C.js").then((m) => void m.logDecision(title, opts));
+var decide = program.command("decide [title]").description("Log an architectural or product decision").option("-d, --description <desc>", "Decision description").option("-c, --category <cat>", "Category: architecture, product, technical, trade-off", "technical").option("-s, --story <id>", "Link to a story (its key like PB-42, or an ID prefix)").action((title, opts) => {
+  import("./log-DFCCAAJN.js").then((m) => void m.logDecision(title, opts));
 });
 decide.command("list").description("List logged decisions (id, category, title)").action(() => {
-  import("./log-EVLWM64C.js").then((m) => void m.listLoggedDecisions());
+  import("./log-DFCCAAJN.js").then((m) => void m.listLoggedDecisions());
 });
 decide.command("amend <id>").description("Amend a logged decision's title, description, or category (accepts an ID prefix)").option("-t, --title <title>", "New title").option("-d, --description <desc>", "New description").option("-c, --category <cat>", "New category: architecture, product, technical, trade-off").action((id, opts) => {
-  import("./log-EVLWM64C.js").then((m) => void m.amendDecision(id, opts));
+  import("./log-DFCCAAJN.js").then((m) => void m.amendDecision(id, opts));
 });
 decide.command("delete <id>").alias("retract").description("Retract a logged decision \u2014 soft-deleted and audited, not removed (accepts an ID prefix)").option("-r, --reason <reason>", "Why this decision is being retracted").option("-y, --yes", "Skip the confirmation prompt (required when there's no TTY)").action((id, opts) => {
-  import("./log-EVLWM64C.js").then((m) => void m.deleteDecision(id, opts));
+  import("./log-DFCCAAJN.js").then((m) => void m.deleteDecision(id, opts));
 });
-program.command("note <storyId> [note]").description("Add implementation notes to a story").action((storyId, note) => {
-  import("./log-EVLWM64C.js").then((m) => void m.logNote(storyId, note));
+program.command("note <storyId> [note]").description("Add an implementation note to a story (appended to its notes)").action((storyId, note) => {
+  import("./log-DFCCAAJN.js").then((m) => void m.logNote(storyId, note));
 });
 program.command("example").description("Add a few-shot reference pattern (before/after code) to the project").action(() => void example());
 program.command("complexity [storyId]").description("Analyze story complexity with AI \u2014 scores, risks, effort estimates").action((id) => {
-  import("./complexity-ZOB3BPVD.js").then((m) => void m.complexity(id));
+  import("./complexity-OJVM37NF.js").then((m) => void m.complexity(id));
 });
 program.command("research [query]").description("Research a topic with AI using your project context").action((query) => {
-  import("./research-4ASCZSZN.js").then((m) => void m.research(query));
+  import("./research-SHO5SXVQ.js").then((m) => void m.research(query));
 });
-program.command("import [file]").description("Import a PRD or spec into your story map as stories").action((file) => {
-  import("./import-prd-MJUCIMHX.js").then((m) => void m.importPrd(file));
+program.command("import [file]").description("Import a PRD or spec into your story map as stories (reads standard input when no file is given; needs --yes then)").option("-y, --yes", "Import without asking for confirmation (required when reading from standard input)").action((file, opts) => {
+  import("./import-prd-5FCVXCYO.js").then((m) => void m.importPrd(file, opts));
 });
 var map = program.command("map").description("Import or extract story maps from codebases");
 map.command("extract").description("Output a prompt for your coding agent to extract a story map from an existing codebase").action(() => {
-  import("./map-extract-W6WJLVOF.js").then((m) => void m.mapExtract());
+  import("./map-extract-YUCFLGJS.js").then((m) => void m.mapExtract());
 });
 map.command("import <file>").description("Import a storymap.json file generated by your coding agent").option("--yes", "Skip confirmation prompt").action((file, opts) => {
-  import("./map-import-LL4AIAQE.js").then((m) => void m.mapImport(file, opts));
+  import("./map-import-7RN2NEUZ.js").then((m) => void m.mapImport(file, opts));
 });
 map.command("schema").description("Print the JSON Schema for storymap.json").action(() => {
-  import("./map-schema-6GL2UKZQ.js").then((m) => void m.mapSchema());
+  import("./map-schema-5BEIJM2J.js").then((m) => void m.mapSchema());
 });
 program.command("mcp").description("Start MCP server for Claude Code / Cursor integration").option("-m, --mode <mode>", "Tool mode: core, standard, all", "all").action((opts) => void startMcpServer(opts.mode));
 program.command("openclaw-register").description("Register this project with OpenClaw MCP \u2014 gives spawned coding agents access to your story map").action(() => void openclawRegister());