slidemind 0.1.6 → 0.1.8

package/bin/slidemind.mjs

@@ -3,7 +3,7 @@
 //
 // Subcommands:
 //   slidemind init [--for <target>]   set up slidemind in a coding harness
-//                                       (register the MCP server + skill);
+//                                       (deploy the skill);
 //                                       targets: claude | codex | opencode | all
 //                                       (`install` is a back-compat alias)
 //   slidemind new <name>              scaffold ./decks/<name>/{plan.md,slides/}
@@ -22,6 +22,7 @@
 
 import { spawn } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -44,11 +45,24 @@ function printHelp() {
     `slidemind ${pkg.version} — drive the slidemind PowerPoint add-in to build native, on-brand decks\n` +
       `\n` +
       `Usage:\n` +
-      `  slidemind new <name>             Scaffold ./decks/<name>/\n` +
+      `  slidemind ready [deck]           One-command session setup — run this FIRST each session.\n` +
+      `                                     Verifies pairing/connection/CLI version, resolves the open\n` +
+      `                                     design, materializes its bundle, and (with a deck) binds it.\n` +
+      `                                     Exit 0 = ready; non-zero prints one actionable blocker.\n` +
+      `                                     --to <presId>   bind to a specific open window\n` +
+      `                                     --force         re-download the bundle even if current\n` +
+      `                                     --connect-only  check the connection only (no design/bundle)\n` +
+      `                                     --json          machine-readable readiness payload\n` +
+      `  slidemind new <name>             Scaffold ./decks/<name>/ (auto-binds to the open design)\n` +
+      `                                     --to <presId>   bind to a specific open window\n` +
+      `                                     --no-bind       skip the auto-bind\n` +
+      `  slidemind plan <deck>            Plan sign-off gate on <deck>/plan.md: opens it in the browser\n` +
+      `                                     as a markdown editor + live preview + overall feedback box,\n` +
+      `                                     blocks until the user decides, prints DECISION: approved | comments\n` +
+      `                                     --port <n>          bind a fixed port (default: ephemeral)\n` +
       `  slidemind build <deck>           Build self-contained HTML\n` +
       `  slidemind review <deck>          Open a spatial preview review; blocks until the user\n` +
       `                                     approves or leaves comments (host-free)\n` +
-      `                                     --no-open       don't auto-open the browser\n` +
       `                                     --port <n>      bind a fixed port (default: ephemeral)\n` +
       `  slidemind build-pptx <deck>      Export native .pptx via the add-in (requires an open host)\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
@@ -65,9 +79,16 @@ function printHelp() {
       `                                     --top <N>       max results\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --json          print the raw result payload\n` +
-      `  slidemind ls engines             List the live engine catalog for the active corporate design\n` +
+      `  slidemind view-slide [opts]      Fetch a slide search result's preview image to a file (requires a host)\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `                                     --pick <n>      1-based selection number to view\n` +
+      `                                     --to <presId>   the window the search ran on (required if >1 open)\n` +
+      `                                     --out <dir>     output dir (default: a slidemind temp dir)\n` +
+      `  slidemind ls engines             List the live engine catalog for an active pane\n` +
       `                                     --type <t>      collection | search\n` +
       `                                     --subtype <s>   image | slide | template | content\n` +
+      `                                     --to <presId>   target a specific window/backend\n` +
+      `                                     --all          include every paired backend\n` +
       `                                     --json          print the raw engine list\n` +
       `  slidemind insert-slide [opts]    Insert reused slide search results live into a window (requires a host)\n` +
       `                                     --search <id>   searchId from 'slidemind search'\n` +
@@ -80,10 +101,17 @@ function printHelp() {
       `                                     --deck <deck>   deck to add the slides to\n` +
       `                                     --to <presId>   target the window the search ran on (required if >1 open)\n` +
       `                                     --at <N>        numeric prefix to start at (default: append)\n` +
+      `  slidemind download-result [opts] Download image/icon search result(s) into a deck's assets/ (requires a host)\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `                                     --pick <n,..>   1-based selection number(s)\n` +
+      `                                     --deck <deck>   deck to write the asset(s) into\n` +
+      `                                     --to <presId>   the window the search ran on (required if >1 open)\n` +
+      `                                     --icon-color <hex[,hex,..]>  bake a colour into SVG result(s) (one for all, or one per --pick)\n` +
       `  slidemind download-bundle [deck] Materialize the active corporate design's bundle locally\n` +
       `                                     --to <presId>   target a specific window\n` +
       `                                     --force         re-download even if the cached bundle is current\n` +
-      `  slidemind presentations          List PowerPoint windows registered with the add-in\n` +
+      `  slidemind presentations          List active PowerPoint panes registered with the add-in\n` +
+      `                                     --all          include retained suspended entries\n` +
       `  slidemind doctor                 Diagnose CLI/add-in pairing, backend, and pane readiness\n` +
       `                                     --json          print machine-readable status\n` +
       `  slidemind read [presId]          Pull the current content of an open presentation (requires a host)\n` +
@@ -101,7 +129,7 @@ function printHelp() {
       `  slidemind whoami                 Show every paired environment (* = default)\n` +
       `  slidemind use <url|env>          Set the default environment\n` +
       `  slidemind logout [url|env]       Unpair one environment (--all to unpair every one)\n` +
-      `  slidemind init --for <t>         Set up slidemind in a harness (registers the MCP server + skill; clears the bundle cache)\n` +
+      `  slidemind init --for <t>         Set up slidemind in a harness (deploys the skill; clears the bundle cache)\n` +
       `  slidemind uninstall --for <t>    Remove a previously-installed skill (clears the bundle cache)\n` +
       `  slidemind update [--for <t>]     Fetch the latest release and redeploy\n` +
       `                                     --for <t>     harness to redeploy into (default: all)\n` +
@@ -140,6 +168,31 @@ function resolveDeckArg(arg) {
   return path.join(decksDir, arg);
 }
 
+// Best-effort human name of a materialized design: the first `# ` heading in
+// the bundle's design.md, with the add-in's trailing " — design rules" suffix
+// stripped. Returns null on any failure (missing file, no heading) so callers
+// fall back to the raw presFP. Shared by `ready` and `new`'s auto-bind.
+function readDesignName(bundleDir) {
+  if (!bundleDir) return null;
+  try {
+    const md = fs.readFileSync(path.join(bundleDir, "design.md"), "utf8");
+    for (const raw of md.split("\n")) {
+      const line = raw.trim();
+      if (line.startsWith("# ")) {
+        const name = line
+          .slice(2)
+          .trim()
+          .replace(/\s+[—-]\s+design rules\s*$/i, "")
+          .trim();
+        return name || null;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 function runNode(script, args) {
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [script, ...args], {
@@ -180,6 +233,15 @@ async function cmdBuild(rest) {
   ]);
 }
 
+async function cmdPlan(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "plan");
+  await runNode(path.join(BUILDERS_DIR, "plan.mjs"), [
+    "--deck",
+    resolveDeckArg(deck),
+    ...passthrough,
+  ]);
+}
+
 async function cmdReview(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "review");
   await runNode(path.join(BUILDERS_DIR, "review.mjs"), [
@@ -238,8 +300,9 @@ async function cmdBuildPptx(rest) {
   if (!fs.existsSync(path.join(deckDir, "slides"))) {
     fail(`expected 'slides/' folder in ${deckDir}`);
   }
-  // The .pptx is rendered server-side by the add-in (one exporter, one truth);
-  // this requires an open PowerPoint host with an active corporate design.
+  // The .pptx is rendered server-side by the add-in (one exporter, one truth).
+  // A bound deck renders pane-free over the brand routes — no PowerPoint
+  // window needed; unbound decks (or --to) resolve through the pane registry.
   const mod = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "build-and-push.mjs")).href
   );
@@ -250,7 +313,8 @@ async function cmdBuildPptx(rest) {
     onProgress: renderProgressPrinter(),
   });
   process.stdout.write(
-    `Wrote ${result.outPath} (${result.slideCount ?? "?"} slides) via the slidemind add-in\n`,
+    `Wrote ${result.outPath} (${result.slideCount ?? "?"} slides) via the slidemind add-in` +
+      `${result.windowless ? " (no PowerPoint window needed)" : ""}\n`,
   );
   for (const w of result.warnings ?? []) {
     process.stderr.write(`  warning: ${w}\n`);
@@ -496,8 +560,11 @@ async function cmdSearch(rest) {
         `  slidemind add-slide --search ${res.searchId} --pick <n> --deck <deck> --to ${ranPresId}\n`,
     );
   } else {
+    // The searchId is bound to the window the search ran on — download must
+    // target that same window, so spell out its presId in the next-step command.
     process.stdout.write(
-      `Download an image result for a deck via the agent (slidemind_download_result, search_id ${res.searchId}).\n`,
+      `searchId ${res.searchId} ran on window ${ranPresId}${envTag} — download image result(s) into a deck:\n` +
+        `  slidemind download-result --search ${res.searchId} --pick <n[,n,...]> --deck <deck> --to ${ranPresId} [--icon-color <hex>]\n`,
     );
   }
 }
@@ -510,6 +577,7 @@ async function cmdLs(rest) {
   let type = null;
   let subtype = null;
   let to = null;
+  let all = false;
   let asJson = false;
   for (let i = 0; i < subRest.length; i++) {
     const a = subRest[i];
@@ -526,10 +594,10 @@ async function cmdLs(rest) {
         fail(`--subtype expects image|slide|template|content, got '${subtype}'`);
       }
     } else if (a === "--to") {
-      // Accepted for symmetry with other commands; engines are backend-scoped,
-      // not presId-scoped, so it does not change the catalog.
       to = subRest[++i];
       if (!to) fail("--to expects a presId");
+    } else if (a === "--all") {
+      all = true;
     } else if (a === "--json") {
       asJson = true;
     } else if (a.startsWith("-")) {
@@ -538,11 +606,17 @@ async function cmdLs(rest) {
       fail(`unexpected argument: ${a}`);
     }
   }
-  void to;
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
-  const { engines } = await client.listEngines({ type, subtype });
+  if (all && to) fail("--all cannot be combined with --to");
+  let backendURL = null;
+  if (!all) {
+    const registry = await client.requirePaneHost();
+    const entry = client.pickAnyPresentationEntry(registry, to);
+    backendURL = entry.backendURL ?? null;
+  }
+  const { engines } = await client.listEngines({ type, subtype, backendURL });
   if (asJson) {
     process.stdout.write(`${JSON.stringify(engines, null, 2)}\n`);
     return;
@@ -686,8 +760,8 @@ async function cmdAddSlide(rest) {
 
   // Extract each picked slide's bytes over the bridge, then let the shared
   // helper compute the play-order filenames (NN-reused-<shortid>.pptx). The
-  // prefix math is the single shared unit (src/lib/reused-slides.mjs) so the
-  // CLI and the MCP tool never diverge. Existing files are not renumbered.
+  // prefix math lives in one shared unit (src/lib/reused-slides.mjs). Existing
+  // files are not renumbered.
   const reused = await import(
     pathToFileURL(path.join(SRC_DIR, "lib", "reused-slides.mjs")).href
   );
@@ -721,6 +795,186 @@ async function cmdAddSlide(rest) {
   );
 }
 
+// Map a `--icon-color` value onto the `--pick` list. Accepts either one colour
+// (applied to every pick) or exactly one per pick (positional); an empty
+// segment means "no colour for this pick". Returns an array aligned to picks.
+function parseIconColors(raw, pickCount) {
+  if (!raw) return new Array(pickCount).fill(null);
+  const colors = raw
+    .split(",")
+    .map((s) => s.trim())
+    .map((s) => (s.length ? s : null));
+  for (const c of colors) {
+    if (c !== null && !/^#[0-9a-fA-F]{3,8}$/.test(c)) {
+      fail(`--icon-color expects hex colours like #0A7E8C, got '${c}'`);
+    }
+  }
+  if (colors.length === 1) return new Array(pickCount).fill(colors[0]);
+  if (colors.length !== pickCount) {
+    fail(
+      `--icon-color takes one colour (applied to all) or exactly ${pickCount} (one per --pick); got ${colors.length}`,
+    );
+  }
+  return colors;
+}
+
+async function cmdViewSlide(rest) {
+  let searchId = null;
+  let pick = null;
+  let to = null;
+  let outDir = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--search") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n)) fail(`--search expects a searchId, got '${next}'`);
+      searchId = n;
+    } else if (a === "--pick") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--pick expects a positive selection number, got '${next}'`);
+      }
+      pick = n;
+    } else if (a === "--to") {
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--out" || a === "-o") {
+      outDir = rest[++i];
+      if (!outDir) fail("--out expects a directory");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (searchId === null || pick === null) {
+    fail("usage: slidemind view-slide --search <id> --pick <n> --to <presId> [--out <dir>]");
+  }
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  const { extFromMime } = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
+  );
+  const registry = await client.requirePaneHost();
+  // The searchId is presentation-scoped, so --to targets the window the search
+  // ran on. Without it, a registry with >1 open window is a dead-end.
+  const entry = client.pickPresentationEntry(registry, to);
+  const res = await client.viewSlide({
+    presId: entry.presId,
+    searchId,
+    selection: pick,
+    backendURL: entry.backendURL ?? null,
+  });
+  if (!res?.ok || !res.dataUri) {
+    fail(`view-slide failed: ${res?.error ?? "no image returned"}`);
+  }
+  const m = /^data:([^;]+);base64,(.+)$/.exec(res.dataUri);
+  if (!m) fail("view-slide returned an unparseable data URI");
+  const dir = outDir
+    ? path.resolve(process.cwd(), outDir)
+    : fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-view-"));
+  fs.mkdirSync(dir, { recursive: true });
+  const target = path.join(dir, `slide-${searchId}-${pick}.${extFromMime(m[1])}`);
+  fs.writeFileSync(target, Buffer.from(m[2], "base64"));
+  process.stdout.write(
+    `Wrote preview of result ${pick} (searchId ${searchId}) to ${target}\n`,
+  );
+}
+
+async function cmdDownloadResult(rest) {
+  let searchId = null;
+  let picks = null;
+  let deck = null;
+  let to = null;
+  let iconColorsRaw = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--search") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n)) fail(`--search expects a searchId, got '${next}'`);
+      searchId = n;
+    } else if (a === "--pick") {
+      picks = parsePicks(rest[++i]);
+    } else if (a === "--deck") {
+      deck = rest[++i];
+      if (!deck) fail("--deck expects a deck name or path");
+    } else if (a === "--to") {
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--icon-color" || a === "--icon-colour") {
+      iconColorsRaw = rest[++i];
+      if (!iconColorsRaw) fail("--icon-color expects a hex colour (or comma-separated list aligned to --pick)");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (searchId === null || !picks || !deck) {
+    fail(
+      "usage: slidemind download-result --search <id> --pick <n[,n,...]> --deck <deck> --to <presId> [--icon-color <hex[,hex,...]>]",
+    );
+  }
+  const iconColors = parseIconColors(iconColorsRaw, picks.length);
+  const deckDir = resolveDeckArg(deck);
+  const assetsDir = path.join(deckDir, "assets");
+  fs.mkdirSync(assetsDir, { recursive: true });
+
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  // Shared image/icon download logic (src/bridge/engine-download.mjs).
+  const { downloadOneResult } = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
+  );
+  const registry = await client.requirePaneHost();
+  // The searchId is presentation-scoped, so --to targets the window the search
+  // ran on. Without it, a registry with >1 open window is a dead-end.
+  const entry = client.pickPresentationEntry(registry, to);
+
+  // Concurrent — each download is its own bridge round-trip; allSettled so one
+  // bad selection doesn't sink the rest of the batch.
+  const settled = await Promise.allSettled(
+    picks.map((selection, i) =>
+      downloadOneResult({
+        client,
+        presId: entry.presId,
+        backendURL: entry.backendURL ?? null,
+        searchId,
+        assetsDir,
+        selection,
+        iconColor: iconColors[i],
+      }),
+    ),
+  );
+  const results = settled.map((r, i) =>
+    r.status === "fulfilled"
+      ? r.value
+      : { selection: picks[i], error: r.reason?.message ?? String(r.reason) },
+  );
+  let ok = 0;
+  const lines = [];
+  for (const r of results) {
+    if (r.error) {
+      lines.push(`  ✗ selection ${r.selection}: ${r.error}`);
+      continue;
+    }
+    ok++;
+    const note = r.recolor?.note ? ` — ${r.recolor.note}` : "";
+    lines.push(`  ${r.reference}  (${r.recolor?.mode ?? "?"})${note}`);
+  }
+  process.stdout.write(
+    `Downloaded ${ok}/${results.length} result(s) into ${path.relative(process.cwd(), assetsDir)}:\n` +
+      lines.join("\n") +
+      `\nReference each from slide JSX as <img src="./assets/...">.\n`,
+  );
+  if (ok === 0) process.exit(1);
+}
+
 async function cmdDownloadBundle(rest) {
   let to = null;
   let force = false;
@@ -789,23 +1043,38 @@ async function cmdDownloadBundle(rest) {
 
 async function cmdPresentations(rest) {
   const asJson = rest.includes("--json");
+  const showAll = rest.includes("--all");
   const mod = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
-  const list = await mod.listOpenPresentations();
+  // `--all` is a raw immediate inspection snapshot (no wait). Otherwise wait out
+  // the brief re-registration window after a pane reload / PowerPoint wake so a
+  // freshly-suspended pane doesn't read as an empty list. Either way we LIST
+  // every entry with its status — suspended panes are honest render/push targets
+  // and hiding them made the CLI say "nothing" during the flaky window.
+  const list = showAll
+    ? await mod.listOpenPresentations()
+    : (await mod.listReadyPresentationsWithWait()).all;
+  // Connected/pane-ready panes first, then suspended/stale ones (stable sort
+  // keeps each group's incoming order).
+  const sorted = [...list].sort(
+    (a, b) =>
+      (mod.isPaneReadyPresentation(b) ? 1 : 0) -
+      (mod.isPaneReadyPresentation(a) ? 1 : 0),
+  );
   if (asJson) {
     process.stdout.write(
-      JSON.stringify(list.map(mod.toPublicPresentation), null, 2) + "\n",
+      JSON.stringify(sorted.map(mod.toPublicPresentation), null, 2) + "\n",
     );
     return;
   }
-  if (list.length === 0) {
+  if (sorted.length === 0) {
     process.stderr.write(
-      "No PowerPoint windows registered with the slidemind add-in.\n",
+      "No active PowerPoint panes registered with the slidemind add-in.\n",
     );
     return;
   }
-  for (const p of list) {
+  for (const p of sorted) {
     const label = p.title || p.fileName || "(untitled)";
     const env = p.env ? `[${p.env}]\t` : "";
     const state =
@@ -813,6 +1082,16 @@ async function cmdPresentations(rest) {
       (p.connected === false || p.suspendedAt ? "suspended" : "connected");
     const design = p.designState ? `\tcd:${p.designState}` : "";
     process.stdout.write(`${p.presId}\t${env}${label}\t${state}${design}\n`);
+    // A pane that can't take live ops yet (suspended/stale/hydrating) is still
+    // listed — with the one actionable line to wake it — so the reader sees an
+    // honest state instead of an empty registry.
+    if (!mod.isPaneReadyPresentation(p)) {
+      const hint =
+        p.nextAction && typeof p.nextAction.message === "string"
+          ? p.nextAction.message
+          : "bring PowerPoint forward and click the slidemind pane";
+      process.stdout.write(`\t${hint}\n`);
+    }
   }
 }
 
@@ -825,6 +1104,8 @@ function publicConnectionStatus(status, client) {
       ok: b.ok,
       readinessV1: b.readinessV1 === true,
       capabilities: b.capabilities ?? null,
+      minCliVersion: b.minCliVersion ?? null,
+      cliUpdateRequired: b.cliUpdateRequired === true,
       error: b.error,
       summary: b.summary ?? null,
       presentations: (b.presentations ?? []).map(client.toPublicPresentation),
@@ -833,15 +1114,52 @@ function publicConnectionStatus(status, client) {
   };
 }
 
-function connectionNextAction(pub) {
+// The ordered connection-readiness ladder as a STRUCTURED blocker: the first
+// unmet precondition, or null when the connection is fully ready. `code` is the
+// machine-copeable reason an agent switches on; `actor` says who can clear it —
+// only `cli_update_required` is the AGENT's to fix (it can run `slidemind
+// update`), every other rung needs a human at the add-in. The `message` strings
+// are BYTE-IDENTICAL to the old connectionNextAction ladder so doctor's printed
+// output never churns (connectionNextAction is now a thin projection over this).
+// `slidemind ready` layers `ambiguous_design` on top and treats `pane_suspended`
+// as non-blocking (a render-ready-but-suspended window is still a design source).
+function connectionBlocker(pub) {
   if (!pub.paired) {
-    return 'Not paired. In the add-in open Settings → General → Connect CLI, press Pair, then run the shown `slidemind pair <code>`.';
+    return {
+      code: "not_paired",
+      actor: "user",
+      message:
+        "Not paired. In the add-in open Settings → General → Connect CLI, press Pair, then run the shown `slidemind pair <code>`.",
+    };
   }
   if ((pub.backends ?? []).every((b) => !b.ok)) {
-    return "Every paired backend is unreachable. Check network/VPN/backend status, or re-pair if the environment moved.";
+    return {
+      code: "all_unreachable",
+      actor: "user",
+      message:
+        "Every paired backend is unreachable. Check network/VPN/backend status, or re-pair if the environment moved.",
+    };
+  }
+  // Version skew explains most downstream failures — surface it before pane
+  // readiness so the user fixes the right thing first.
+  const outdated = (pub.backends ?? []).find((b) => b.cliUpdateRequired);
+  if (outdated) {
+    return {
+      code: "cli_update_required",
+      actor: "agent",
+      message:
+        `This CLI is older than the minimum the '${outdated.env}' add-in supports` +
+        `${outdated.minCliVersion ? ` (${outdated.minCliVersion})` : ""}. ` +
+        "Run `slidemind update` (or `npm install -g slidemind@latest`), then retry.",
+    };
   }
   if ((pub.presentations ?? []).length === 0) {
-    return "No PowerPoint window is registered. Open PowerPoint, load the slidemind add-in, and activate or create a corporate design.";
+    return {
+      code: "no_window",
+      actor: "user",
+      message:
+        "No PowerPoint window is registered. If PowerPoint is already open with the slidemind pane, bring it to the foreground (click the pane) and re-run. Otherwise open PowerPoint, load the slidemind add-in, and activate or create a corporate design.",
+    };
   }
   const renderReady = pub.presentations.some(
     (p) =>
@@ -850,7 +1168,12 @@ function connectionNextAction(pub) {
       p.designState === "ready",
   );
   if (!renderReady) {
-    return "PowerPoint is connected, but no window is render-ready. Wait for corporate design matching or activate/create a corporate design.";
+    return {
+      code: "not_render_ready",
+      actor: "user",
+      message:
+        "PowerPoint is connected, but no window is render-ready. Wait for corporate design matching or activate/create a corporate design.",
+    };
   }
   const paneReady = pub.presentations.some(
     (p) =>
@@ -860,9 +1183,418 @@ function connectionNextAction(pub) {
         !p.suspendedAt),
   );
   if (!paneReady) {
-    return "Rendering is available, but pane operations are suspended. Bring PowerPoint forward and click/reopen the slidemind pane before push/search/read.";
+    return {
+      code: "pane_suspended",
+      actor: "user",
+      message:
+        "Rendering is available, but pane operations are suspended. Bring PowerPoint forward and click/reopen the slidemind pane before push/search/read.",
+    };
+  }
+  return null;
+}
+
+// Back-compat projection for doctor: just the blocker's message, or "Ready."
+// when the ladder is clear. Keeps the ladder authored in ONE place.
+function connectionNextAction(pub) {
+  return connectionBlocker(pub)?.message ?? "Ready.";
+}
+
+// The one-command agent preflight. Collapses the old 4-call session start
+// (presentations → pick → download-bundle → download-bundle-to-bind) into a
+// single verb: check pairing/reachability/CLI-version/windows, resolve the OPEN
+// design (the add-in is the source of truth), materialize its bundle, bind the
+// deck, and print exactly one actionable blocker when it can't. Exit 0 iff
+// ready; every blocker → exit 1 with a machine-copeable code. Never prints a
+// backendURL (env label only).
+async function cmdReady(rest) {
+  // --- Local arg parse: unknown flags fail BEFORE any network (cli-dispatch
+  // convention). ---
+  let to = null;
+  let asJson = false;
+  let force = false;
+  let connectOnly = false;
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--to") {
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--json") {
+      asJson = true;
+    } else if (a === "--force") {
+      force = true;
+    } else if (a === "--connect-only") {
+      connectOnly = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      positional.push(a);
+    }
+  }
+
+  // --- Local: resolve the deck dir (never create it) and read its existing
+  // bundle ref. deckPresFP feeds ONLY the mirror tie-break + `suggested`; it
+  // never auto-picks a design. ---
+  const deckArg = positional[0] ?? null;
+  const bundle = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  let deckDir = null;
+  let deckSlug = null;
+  let deckPresFP = null;
+  if (deckArg) {
+    deckDir = resolveDeckArg(deckArg);
+    if (!fs.existsSync(deckDir)) {
+      fail(
+        `deck '${deckArg}' not found — run \`slidemind ready\` (no deck) to set up, then \`slidemind new ${deckArg}\``,
+      );
+    }
+    deckSlug = path.basename(deckDir);
+    deckPresFP = bundle.readDeckBundleRef(deckDir)?.presFP ?? null;
+  }
+
+  // Emit a structured blocker (JSON to stdout / human to stderr) and exit 1.
+  // `humanLines` overrides the default `slidemind: <message>` for the richer
+  // ambiguous / unknown-window shapes. Mirrors doctor's stream conventions:
+  // machine JSON on stdout, human prose on stderr.
+  const finishBlocker = ({ blocker, extras = {}, humanLines = null }) => {
+    if (asJson) {
+      process.stdout.write(
+        JSON.stringify(
+          { ready: false, blocker, nextAction: blocker.message, ...extras },
+          null,
+          2,
+        ) + "\n",
+      );
+      process.exit(1);
+    }
+    if (humanLines) {
+      process.stderr.write(
+        humanLines.endsWith("\n") ? humanLines : `${humanLines}\n`,
+      );
+      process.exit(1);
+    }
+    fail(blocker.message);
+  };
+
+  // --- Local: not paired short-circuits before any network. ---
+  const cfg = await loadBridgeModule("config");
+  if (cfg.readSessions().length === 0) {
+    finishBlocker({ blocker: connectionBlocker({ paired: false }) });
+    return;
+  }
+
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+
+  // --- Network (one parallel round): readiness ladder + the merged registry. ---
+  const [statusRaw, detailed] = await Promise.all([
+    client.connectionStatus(),
+    client.listOpenPresentationsDetailed(),
+  ]);
+  const pub = publicConnectionStatus(statusRaw, client);
+  let registry = detailed.presentations;
+
+  // Terminal blockers: waiting can't fix an unreachable backend or a stale CLI.
+  const terminal = connectionBlocker(pub);
+  if (
+    terminal &&
+    (terminal.code === "all_unreachable" || terminal.code === "cli_update_required")
+  ) {
+    finishBlocker({ blocker: terminal });
+    return;
+  }
+
+  // --- Bounded hydration wait when nothing is render-ready yet: covers the
+  // just-clicked / just-woke pane still hydrating brand metadata. Polls even on
+  // an empty registry (that's the flaky window this papers over). ---
+  const isRR = client.isRenderReadyPresentation;
+  if (!registry.some(isRR)) {
+    const waitMs =
+      parseInt(process.env.SLIDEMIND_BRIDGE_PRESENTATIONS_WAIT_MS || "6000", 10) ||
+      6000;
+    const pollMs =
+      parseInt(process.env.SLIDEMIND_BRIDGE_READY_POLL_MS || "1500", 10) || 1500;
+    const deadline = Date.now() + waitMs;
+    while (!registry.some(isRR) && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, pollMs));
+      registry = (await client.listOpenPresentationsDetailed()).presentations;
+    }
+  }
+  if (!registry.some(isRR)) {
+    // --- Pane-free rung: a BOUND deck readies over the brand routes with no
+    // window at all — the design identity (presFP == brandId) lives in the
+    // deck's .bundle-ref.json, and the render half never needed the pane.
+    // Degraded: build-pptx/build/review/view-draft work; push/search/read
+    // still need a pane. Skipped for --connect-only (search needs a pane) and
+    // --to (an explicit window must resolve through the registry). Any miss
+    // (old add-in, legacy ref, revoked grant) falls through to the ladder.
+    if (deckDir && deckPresFP && !to && !connectOnly) {
+      let result = null;
+      try {
+        result = await bundle.materializeBundle(null, {
+          force,
+          brandId: deckPresFP,
+        });
+      } catch {
+        /* fall through to the standard no_window / not_render_ready blocker */
+      }
+      if (result) {
+        bundle.writeDeckBundleRef(deckDir, {
+          presFP: result.presFP,
+          etag: result.etag,
+        });
+        const designName = readDesignName(result.dir);
+        const env = result.backendURL
+          ? cfg.deriveEnvLabel(result.backendURL)
+          : null;
+        const nextAction =
+          "Ready (no PowerPoint window — build-pptx/build/review/view-draft work; push/search/read need a pane).";
+        if (asJson) {
+          process.stdout.write(
+            JSON.stringify(
+              {
+                ready: true,
+                windowless: true,
+                deck: deckSlug,
+                bound: true,
+                env,
+                presId: null,
+                presFP: result.presFP,
+                designName,
+                bundleDir: result.dir,
+                bundleEtag: result.etag ?? null,
+                paneSuspended: true,
+                warnings: result.warnings ?? [],
+                nextAction,
+              },
+              null,
+              2,
+            ) + "\n",
+          );
+          return;
+        }
+        const designLabel = designName
+          ? `${designName} (${result.presFP})`
+          : result.presFP;
+        process.stdout.write(
+          `Ready — design ${designLabel}${env ? ` [${env}]` : ""} (no PowerPoint window)\n`,
+        );
+        process.stdout.write(
+          `  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`,
+        );
+        process.stdout.write(`  deck ${deckSlug} bound\n`);
+        process.stdout.write(
+          "  Note: build-pptx/build/review/view-draft work without a window; push/search/read need a pane.\n",
+        );
+        for (const w of result.warnings ?? []) {
+          process.stderr.write(`  warning: ${w}\n`);
+        }
+        return;
+      }
+    }
+    // Only the no-window / not-render-ready rungs are reachable here (terminal
+    // blockers already returned; a render-ready window would have exited the
+    // poll). Reuse the ladder's exact strings over the freshly-polled registry.
+    const latePub = {
+      paired: true,
+      backendCount: pub.backendCount,
+      backends: pub.backends,
+      presentations: registry.map(client.toPublicPresentation),
+    };
+    const b =
+      connectionBlocker(latePub) ?? {
+        code: "not_render_ready",
+        actor: "user",
+        message:
+          "PowerPoint is connected, but no window is render-ready. Wait for corporate design matching or activate/create a corporate design.",
+      };
+    finishBlocker({ blocker: b });
+    return;
+  }
+
+  // --- --connect-only: the connection is up with ≥1 render-ready window; the
+  // search skill needs nothing more (no design resolution, no bundle). ---
+  if (connectOnly) {
+    if (asJson) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            ready: true,
+            connectOnly: true,
+            nextAction: "Ready.",
+            backends: (pub.backends ?? []).map((b) => ({ env: b.env, ok: b.ok })),
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+    } else {
+      const windows = registry.filter(isRR).length;
+      process.stdout.write(
+        `Connected. ${pub.backendCount} backend(s), ${windows} window(s) registered.\n`,
+      );
+    }
+    return;
+  }
+
+  // --- Local: resolve WHICH design to bind against. ---
+  const resolution = client.resolveDesignSource(registry, {
+    explicitPresId: to,
+    deckPresFP,
+  });
+
+  if (resolution.status === "none") {
+    // Defensive: a render-ready window exists (poll passed) so this is rare.
+    finishBlocker({
+      blocker: {
+        code: "not_render_ready",
+        actor: "user",
+        message:
+          "PowerPoint is connected, but no window is render-ready. Wait for corporate design matching or activate/create a corporate design.",
+      },
+    });
+    return;
+  }
+
+  if (resolution.status === "unknown_presid") {
+    const windows = registry.filter(isRR).map(client.toPublicPresentation);
+    const candidates = windows.map((p) => ({
+      presId: p.presId,
+      env: p.env ?? null,
+      title: p.title ?? null,
+      fileName: p.fileName ?? null,
+    }));
+    const blocker = {
+      code: "unknown_presid",
+      actor: "user",
+      message: `No render-ready PowerPoint window has presId='${to}'. Re-run 'slidemind ready --to <presId>' with one of the open windows.`,
+    };
+    const rows = windows.map(
+      (p) =>
+        `  ${p.presId}  ${p.env ? `[${p.env}]  ` : ""}${p.title || p.fileName || "(untitled)"}`,
+    );
+    finishBlocker({
+      blocker,
+      extras: { candidates },
+      humanLines:
+        `slidemind: ${blocker.message}\n` +
+        `${rows.join("\n")}`,
+    });
+    return;
+  }
+
+  if (resolution.status === "ambiguous") {
+    const cand = resolution.candidates;
+    const blocker = {
+      code: "ambiguous_design",
+      actor: "user",
+      message:
+        "Multiple corporate designs are open — ask the user which to build against, then re-run: slidemind ready --to <presId>.",
+    };
+    const rows = cand.map((c) => {
+      const env = c.env ? `  [${c.env}]` : "";
+      const label = c.title || c.fileName || "(untitled)";
+      return `  ${c.presId}${env}  ${label}    (design ${c.brandId ?? "?"})`;
+    });
+    let human =
+      "slidemind: multiple corporate designs are open — ask the user which to build against:\n" +
+      `${rows.join("\n")}\n`;
+    if (resolution.suggested) {
+      const s = cand.find((c) => c.presId === resolution.suggested);
+      const sLabel = s?.title || s?.fileName || "(untitled)";
+      human += `(this deck was last built against ${s?.brandId ?? deckPresFP} — ${sLabel})\n`;
+    }
+    human += "Then re-run: slidemind ready --to <presId>";
+    finishBlocker({
+      blocker,
+      extras: {
+        candidates: cand.map((c) => ({
+          presId: c.presId,
+          env: c.env ?? null,
+          title: c.title ?? null,
+          fileName: c.fileName ?? null,
+          presFP: c.brandId ?? null,
+        })),
+        suggested: resolution.suggested,
+      },
+      humanLines: human,
+    });
+    return;
+  }
+
+  // --- Network: materialize the resolved design's bundle. Always called —
+  // incremental etag-gated download makes an unchanged bundle near-free and a
+  // changed one refreshes. ---
+  const entry = resolution.entry;
+  const result = await bundle.materializeBundle(entry.presId, {
+    force,
+    backendURL: entry.backendURL ?? null,
+    preferBrandId: entry.brandId ?? null,
+  });
+
+  // --- Local: bind the deck (kills the second download-bundle). ---
+  let bound = false;
+  if (deckDir) {
+    bundle.writeDeckBundleRef(deckDir, {
+      presFP: result.presFP,
+      etag: result.etag,
+    });
+    bound = true;
+  }
+
+  const designName = readDesignName(result.dir);
+  const paneSuspended = !client.isPaneReadyPresentation(entry);
+
+  if (asJson) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          ready: true,
+          deck: deckSlug,
+          bound,
+          env: entry.env ?? null,
+          presId: entry.presId,
+          presFP: result.presFP,
+          designName,
+          bundleDir: result.dir,
+          bundleEtag: result.etag ?? null,
+          presentation: {
+            title: entry.title ?? null,
+            fileName: entry.fileName ?? null,
+          },
+          paneSuspended,
+          warnings: result.warnings ?? [],
+          nextAction: "Ready.",
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  // --- Human success: compact multi-line summary on stdout. ---
+  const envTag = entry.env ? ` [${entry.env}]` : "";
+  const presLabel = entry.title || entry.fileName || "(untitled)";
+  const designLabel = designName
+    ? `${designName} (${result.presFP})`
+    : result.presFP;
+  process.stdout.write(`Ready — design ${designLabel}\n`);
+  process.stdout.write(`  presentation: ${presLabel}${envTag}\n`);
+  process.stdout.write(
+    `  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`,
+  );
+  if (bound) process.stdout.write(`  deck ${deckSlug} bound\n`);
+  if (paneSuspended) {
+    process.stdout.write(
+      "  Note: pane operations (push/search/read) will wait for a pane click.\n",
+    );
+  }
+  for (const w of result.warnings ?? []) {
+    process.stderr.write(`  warning: ${w}\n`);
   }
-  return "Ready.";
 }
 
 async function cmdDoctor(rest) {
@@ -1228,8 +1960,8 @@ async function cmdPush(rest) {
   }
   if (result.paneSuspended) {
     process.stdout.write(
-      `PowerPoint is backgrounded — the deck rendered but couldn't be pushed.\n` +
-        `Click the slidemind task pane once to bring PowerPoint to the foreground, ` +
+      `The deck rendered, but no PowerPoint window was ready to receive it.\n` +
+        `Open PowerPoint with the slidemind pane (or click the pane once to wake it), ` +
         `then re-run: slidemind push ${deck}\n` +
         `The rendered deck was saved to ${path.relative(process.cwd(), result.fallbackFile)} in the meantime.\n`,
     );
@@ -1241,7 +1973,22 @@ async function cmdPush(rest) {
 }
 
 async function cmdNew(rest) {
-  const positional = rest.filter((a) => !a.startsWith("--"));
+  let to = null;
+  let noBind = false;
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--to") {
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--no-bind") {
+      noBind = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      positional.push(a);
+    }
+  }
   const name = positional[0];
   if (!name) fail("usage: slidemind new <name>");
   if (!/^[a-z0-9][a-z0-9-]*$/i.test(name)) {
@@ -1264,6 +2011,48 @@ async function cmdNew(rest) {
   process.stdout.write(
     `Next: ask your agent to author "${name}", then \`slidemind build ${name}\`\n`,
   );
+
+  // Stateless auto-bind: bind the fresh deck to whatever design is OPEN so the
+  // agent skips a follow-up `download-bundle`. Best-effort — a bind miss (no
+  // host, ambiguous designs, bundle not yet materialized, any network error)
+  // NEVER fails the scaffold; it just drops a soft hint. Fully offline when
+  // unpaired: no network attempted, no hint. `--no-bind` opts out entirely.
+  if (noBind) return;
+  const cfg = await loadBridgeModule("config");
+  if (cfg.readSessions().length === 0) return;
+  let boundMsg = null;
+  try {
+    const client = await import(
+      pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+    );
+    const bundle = await import(
+      pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+    );
+    const { presentations } = await client.listOpenPresentationsDetailed();
+    const resolution = client.resolveDesignSource(presentations, {
+      explicitPresId: to,
+    });
+    if (resolution.status === "resolved") {
+      const entry = resolution.entry;
+      const meta = bundle.readMaterializedBundleMeta(entry.brandId);
+      if (meta?.presFP) {
+        bundle.writeDeckBundleRef(deckDir, {
+          presFP: meta.presFP,
+          etag: meta.etag ?? null,
+        });
+        const label =
+          readDesignName(bundle.bundleDirForPresFP(meta.presFP)) ?? meta.presFP;
+        boundMsg = `bound to design ${label}`;
+      }
+    }
+  } catch {
+    /* best-effort — fall through to the soft hint */
+  }
+  process.stdout.write(
+    boundMsg
+      ? `${boundMsg}\n`
+      : `not bound to a design yet — run \`slidemind ready ${name}\` when a window is open\n`,
+  );
 }
 
 function parseTargetFlag(rest) {
@@ -1384,9 +2173,9 @@ function spawnInherit(file, args) {
 // ---------- distribution (public npm) ----------
 //
 // slidemind is published to public npm as `slidemind`. First install is
-// `npm install -g slidemind` (then `slidemind init` to register the MCP
-// server + skill; `install` stays as a back-compat alias); `slidemind update`
-// is a thin wrapper over `npm install -g slidemind@latest`.
+// `npm install -g slidemind` (then `slidemind init` to deploy the skill;
+// `install` stays as a back-compat alias); `slidemind update` is a thin
+// wrapper over `npm install -g slidemind@latest`.
 
 // Resolve the `npm` that sits next to the node running this process, so an
 // update lands the global into the same prefix slidemind was launched from.
@@ -1480,6 +2269,9 @@ async function main(rawArgv) {
     case "build":
       await cmdBuild(rest);
       return 0;
+    case "plan":
+      await cmdPlan(rest);
+      return 0;
     case "review":
       await cmdReview(rest);
       return 0;
@@ -1495,15 +2287,24 @@ async function main(rawArgv) {
     case "ls":
       await cmdLs(rest);
       return 0;
+    case "view-slide":
+      await cmdViewSlide(rest);
+      return 0;
     case "insert-slide":
       await cmdInsertSlide(rest);
       return 0;
     case "add-slide":
       await cmdAddSlide(rest);
       return 0;
+    case "download-result":
+      await cmdDownloadResult(rest);
+      return 0;
     case "download-bundle":
       await cmdDownloadBundle(rest);
       return 0;
+    case "ready":
+      await cmdReady(rest);
+      return 0;
     case "new":
       await cmdNew(rest);
       return 0;
@@ -1535,7 +2336,7 @@ async function main(rawArgv) {
       return 0;
     case "init":
     case "install":
-      // Set slidemind up in a coding harness (register the MCP server + skill).
+      // Set slidemind up in a coding harness (deploy the skill).
       // `install` stays as a back-compat alias for the documented `init`.
       await cmdInstall(rest);
       return 0;