slidemind 0.2.2 → 0.2.4

package/bin/slidemind.mjs

@@ -2,6 +2,9 @@
 // slidemind — single CLI entry point for the slidemind npm package.
 //
 // Subcommands:
+//   slidemind setup <claim>           one-command onboarding from the add-in's
+//                                       "Connect CLI" button: connect + global
+//                                       install + skills + ready (run via npx)
 //   slidemind init [--for <target>]   set up slidemind in a coding harness
 //                                       (deploy the skill);
 //                                       targets: claude | codex | opencode | all
@@ -52,11 +55,22 @@ function printHelp() {
     `slidemind ${pkg.version} — drive the slidemind PowerPoint add-in to build native, on-brand decks\n` +
       `\n` +
       `Usage:\n` +
+      `  slidemind setup <claim>          One-command onboarding. Copy the command from PowerPoint →\n` +
+      `                                     slidemind → Settings → General → Connect CLI and paste it:\n` +
+      `                                     it connects this machine, installs slidemind globally, deploys\n` +
+      `                                     the skills, and runs 'ready'. Designed for 'npx slidemind@latest'.\n` +
+      `                                     --for <target>  harness to deploy skills into (default: auto — every\n` +
+      `                                                     coding agent found on this machine; none to skip)\n` +
+      `                                     --no-install    skip the global npm install (already installed)\n` +
+      `                                     --no-ready      skip the closing readiness check\n` +
+      `                                     --json          machine-readable result\n` +
       `  slidemind ready [deck]           One-command session setup — run this FIRST each session.\n` +
-      `                                     Verifies pairing/connection/CLI version, resolves the open\n` +
+      `                                     Verifies authorization/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` +
+      `                                     A deck already bound to a design readies with PowerPoint closed.\n` +
       `                                     --to <presId>   bind to a specific open window\n` +
+      `                                     --brand <id>    bind to a design by id (presFP) — no window needed\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` +
@@ -68,7 +82,8 @@ function printHelp() {
       `                                     blocks until the user decides, prints DECISION: approved | comments\n` +
       `                                     --port <n>          bind a fixed port (default: ephemeral)\n` +
       `  slidemind concepts <deck>        After plan sign-off, generate one concept mockup PNG per planned\n` +
-      `                                     slide into <deck>/concepts/concept-slide-NN.png (requires a host).\n` +
+      `                                     slide into <deck>/concepts/concept-slide-NN.png (bound deck,\n` +
+      `                                     pane-free — no PowerPoint window needed).\n` +
       `                                     Read each as a design target, then rebuild it as slide JSX.\n` +
       `                                     Optional aid — skips cleanly (exit 0) if unavailable.\n` +
       `  slidemind build <deck>           Build self-contained HTML\n` +
@@ -76,31 +91,46 @@ function printHelp() {
       `                                     approves or leaves comments (host-free)\n` +
       `                                     --port <n>      bind a fixed port (default: ephemeral)\n` +
       `  slidemind build-pptx <deck>      Export native .pptx — via the add-in for compose decks (host), LOCALLY for template packs (host-free)\n` +
+      `                                     --pack <dir>   explicit template-pack directory (plugin integrations)\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --out <path>    output path (default <deck>/<deck>.pptx)\n` +
+      `  slidemind inspect-template-deck <deck>  Inspect a template deck as JSON for pack-owned validation\n` +
+      `                                     --pack <dir>   explicit template-pack directory (required)\n` +
+      `                                     --allow-unrendered-freeform  include JSX inserts without .pptx artifacts\n` +
+      `                                     --json          print the normalized deck model\n` +
       `  slidemind view-draft <deck>      Render the deck's slides to per-slide PNGs (no push, no .pptx)\n` +
       `                                     so the agent can look before review; host-free once the\n` +
       `                                     bundle is materialized\n` +
       `                                     --to <presId>   window to fetch the bundle from (only if not cached)\n` +
       `                                     --out <dir>     output dir (default <deck>/.draft-preview/)\n` +
       `                                     --open          open each rendered PNG\n` +
-      `  slidemind search "<query>"       Search an engine or scope for images or slides (requires an open host)\n` +
+      `  slidemind search "<query>"       Search an engine or scope for images or slides (no window needed on\n` +
+      `                                     add-ins that serve the pane-free engine routes; older ones relay\n` +
+      `                                     through an open host)\n` +
       `                                     --engine <id>   engine, or scope:all | scope:sharepoint to search unfiltered\n` +
       `                                                     (default: first image engine; scope:all for slide intents)\n` +
       `                                     --result-type <t>  slide | image — required for a scope:* target\n` +
       `                                     --intent <i>    auto | content | visual (slide engines)\n` +
       `                                     --top <N>       max results\n` +
-      `                                     --to <presId>   target a specific window (required if >1 open)\n` +
-      `                                     --json          print the raw result payload\n` +
-      `  slidemind view-slide [opts]      Fetch a slide search result's preview image to a file (requires a host)\n` +
+      `                                     --deck <deck>   route by this deck's bound design (multi-environment)\n` +
+      `                                     --to <presId>   pin a window on the relayed path (ignored pane-free)\n` +
+      `                                     --json          print the raw result payload (carries the searchId)\n` +
+      `  slidemind view-slide [opts]      Fetch a slide search result's preview image to a file\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` +
+      `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
       `                                     --out <dir>     output dir (default: a slidemind temp dir)\n` +
-      `  slidemind ls engines             List the live engine catalog + search scopes for an active pane\n` +
+      `  slidemind read-source [opts]     Read the ORIGINAL deck a slide search result came from\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `                                     --pick <n>      1-based selection number\n` +
+      `                                     --from-slide <n>  first slide to read (1-based)\n` +
+      `                                     --to-slide <n>    last slide to read (1-based)\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
+      `                                     --out <file>    write the Markdown to a file instead of stdout\n` +
+      `  slidemind ls engines             List the live engine catalog + search scopes\n` +
       `                                     --type <t>      collection | search | scope\n` +
       `                                     --subtype <s>   image | slide | template | content\n` +
-      `                                     --to <presId>   target a specific window/backend\n` +
+      `                                     --to <presId>   target a specific window/backend (relayed path only)\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` +
@@ -109,17 +139,18 @@ function printHelp() {
       `                                     --to <presId>   target window (required if >1 open)\n` +
       `                                     --at <N>        insert after slide N (0-based); default = append\n` +
       `  slidemind add-slide [opts]       Fold reused slide(s) into a deck as native .pptx\n` +
-      `                                     --search <id>   searchId from 'slidemind search' (requires a host)\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
       `                                     --from <file.pptx>  fold slide(s) from a local .pptx instead (host-free)\n` +
       `                                     --pick <n,..>   1-based selection number(s)\n` +
       `                                     --deck <deck>   deck to add the slides to\n` +
-      `                                     --to <presId>   target the window the search ran on (required if >1 open; ignored with --from)\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only; ignored with --from)\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` +
+      `                                     --json          machine-readable result (carries the searchId)\n` +
+      `  slidemind download-result [opts] Download image/icon search result(s) into a deck's assets/\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` +
+      `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
       `                                     --icon-color <hex[,hex,..]>  bake a colour into SVG result(s) (one for all, or one per --pick)\n` +
       `  slidemind imagen "<prompt>"      Generate ONE image with the add-in's image model into a deck's assets/ (paired backend, pane-free)\n` +
       `                                     --deck <deck>   bound deck to write the image into (required)\n` +
@@ -132,7 +163,9 @@ function printHelp() {
       `                                     --force         re-download even if the cached bundle is current\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` +
+      `  slidemind doctor                 Diagnose two independent ladders: backend authoring readiness\n` +
+      `                                     (session, backend, CLI version, engine routes) and live\n` +
+      `                                     PowerPoint readiness (windows, pane)\n` +
       `                                     --json          print machine-readable status\n` +
       `  slidemind read [presId|file.pptx]  Pull the content of an open presentation (requires a host),\n` +
       `                                     or of a local .pptx path (read host-free from disk)\n` +
@@ -144,13 +177,12 @@ function printHelp() {
       `                                     --at <index>    insert after slide N (0-based); default = append\n` +
       `                                     --replace       delete existing slides first (destructive)\n` +
       `                                     --slides <ids>  comma-separated source slide ids to push\n` +
-      `  slidemind pair <code>            Pair with an add-in (copy the code from its "Connect CLI")\n` +
-      `                                     --label <name>  name this environment (default: derived from URL)\n` +
-      `                                   Pair once per environment; commands fan out across all of them.\n` +
-      `  slidemind whoami                 Show every paired environment (* = default)\n` +
+      `  slidemind whoami                 Show every connected 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 (deploys the skill; clears the bundle cache)\n` +
+      `                                     <t> = claude | codex | opencode | all | auto (every harness found here)\n` +
+      `                                     'setup' already does this — only needed after installing a new agent\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` +
@@ -418,15 +450,86 @@ async function cmdImagen(rest) {
   );
 }
 
+async function cmdInspectTemplateDeck(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "inspect-template-deck");
+  let packDir = null;
+  let json = false;
+  let allowUnrenderedFreeform = false;
+  for (let i = 0; i < passthrough.length; i++) {
+    const a = passthrough[i];
+    if (a === "--pack") {
+      packDir = passthrough[++i];
+      if (!packDir) fail("--pack expects a directory");
+    } else if (a === "--json") {
+      json = true;
+    } else if (a === "--allow-unrendered-freeform") {
+      allowUnrenderedFreeform = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (!packDir) fail("inspect-template-deck requires --pack <dir>");
+
+  const deckDir = resolveDeckArg(deck);
+  const resolveMod = await import(
+    pathToFileURL(path.join(SRC_DIR, "builders", "resolve-skill.mjs")).href
+  );
+  const skill = resolveMod.resolveSkillForDeck(deckDir, {
+    packDir: path.resolve(packDir),
+  });
+  if (skill.mode !== "fill-template") {
+    fail(`pack ${skill.skillDir} is mode ${skill.mode}, not fill-template`);
+  }
+  const engine = await import(
+    pathToFileURL(path.join(SRC_DIR, "pptx", "fill", "engine.mjs")).href
+  );
+  const result = engine.inspectFillTemplateDeck({
+    deckDir,
+    skill,
+    allowUnrenderedFreeform,
+  });
+  const payload = {
+    version: 1,
+    pack: {
+      name: skill.skillName,
+      mode: skill.mode,
+      directory: skill.skillDir,
+      template: result.templateKey,
+      locale: result.locale,
+    },
+    slides: result.sequence,
+    warnings: result.warnings,
+    problems: result.problems,
+  };
+  if (json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else {
+    for (const item of result.sequence) {
+      const suffix = item.kind === "master" ? ` → template ${item.no}` : "";
+      process.stdout.write(`${item.file}: ${item.kind}${suffix}\n`);
+    }
+    for (const warning of result.warnings) process.stderr.write(`  warning: ${warning}\n`);
+  }
+  if (result.problems.length) {
+    fail(`inspection failed:\n  - ${result.problems.join("\n  - ")}`);
+  }
+}
+
 async function cmdBuildPptx(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "build-pptx");
   let to = null;
   let outPath = null;
+  let packDir = null;
   for (let i = 0; i < passthrough.length; i++) {
     const a = passthrough[i];
     if (a === "--to") {
       to = passthrough[++i];
       if (!to) fail("--to expects a presId");
+    } else if (a === "--pack") {
+      packDir = passthrough[++i];
+      if (!packDir) fail("--pack expects a directory");
     } else if (a === "--out" || a === "-o") {
       outPath = passthrough[++i];
       if (!outPath) fail("--out expects a path");
@@ -449,8 +552,13 @@ async function cmdBuildPptx(rest) {
   const resolveMod = await import(
     pathToFileURL(path.join(SRC_DIR, "builders", "resolve-skill.mjs")).href
   );
-  if (resolveMod.resolveDeckMode(deckDir).mode === "fill-template") {
-    const skill = resolveMod.resolveSkillForDeck(deckDir);
+  const resolveOpts = packDir ? { packDir: path.resolve(packDir) } : {};
+  const deckMode = resolveMod.resolveDeckMode(deckDir, resolveOpts);
+  if (packDir && deckMode.mode !== "fill-template") {
+    fail(`explicit --pack ${path.resolve(packDir)} is mode ${deckMode.mode}, not fill-template`);
+  }
+  if (deckMode.mode === "fill-template") {
+    const skill = resolveMod.resolveSkillForDeck(deckDir, resolveOpts);
     if (to) {
       fail(
         "--to targets a PowerPoint window, but fill-template decks build " +
@@ -688,9 +796,169 @@ function writeSearchGrid(gridDataUri, searchId, resolveExt) {
   }
 }
 
+// Where an engine op runs. Newer add-ins serve the engine surface off the CLI
+// session itself (`/api/cli/engines`, `/api/cli/searches/*`), so discovery,
+// search, download and extraction need no PowerPoint window at all; older ones
+// relay every one of them through a task-pane webview, which is what
+// requirePaneHost gates. The DIRECT path is preferred whenever it exists and the
+// pane path stays as the compat fallback, so both add-in generations work.
+//
+// `--to <presId>` stops being a REQUIREMENT — the searchId is server-owned
+// rather than bound to a window, so nothing has to be targeted — but it is still
+// honoured, and naming a window means "relay through THAT pane". That is the
+// escape hatch for the two things the pane-free routes refuse (`asset_needs_host`
+// for SharePoint-hosted bytes, `recolor_needs_host` for an icon tint), both of
+// which the pane can do; ignoring --to made their own remediation unreachable.
+// `brandId` is the deck's bound design — the only thing that routes an engine op
+// in a multi-environment session when no window is involved.
+// No connected environment holds a server-owned search record. Authored once
+// because every consumer of an opaque searchId reaches the same dead end and
+// the same way out — the record's own environment is the only thing that can
+// serve it, so a re-search is the fix regardless of who asked.
+function expiredSearchMessage(searchId) {
+  return (
+    `search ${searchId} was not found on any connected environment — server-side ` +
+    "search records expire after ~2 hours. Re-run 'slidemind search' and pick again."
+  );
+}
+
+async function resolveEngineRouting(client, { to = null, brandId = null, pick = "one", searchId = null } = {}) {
+  // An opaque (server-minted) searchId pins the route by itself: the record
+  // lives on the environment that minted it, and the pane relay can never
+  // serve it — its handler only knows its own per-window numeric ids. So the
+  // record's origin outranks the deck's design AND --to, and when no connected
+  // environment holds the record the only honest answer is "search again",
+  // not a pane fallback that is guaranteed to 4xx.
+  if (client.isOpaqueSearchId?.(searchId)) {
+    if (to) {
+      fail(
+        `searchId ${searchId} is a pane-free search — it cannot be relayed through a window. ` +
+          `To go through the pane, re-run 'slidemind search "<query>" --to ${to}' and use ITS searchId.`,
+      );
+    }
+    let origin = null;
+    try {
+      origin = await client.resolveSearchBackend(searchId);
+    } catch (err) {
+      // The probe distinguishes "no environment holds this record" from the
+      // failures that only LOOK like it — a dead session, a stale snapshot —
+      // and hands the latter back for their own remediation.
+      await failOnEngineBlocker(client, err, { to });
+    }
+    if (origin) {
+      return { direct: true, backendURL: origin, presId: null, registry: null, entry: null };
+    }
+    fail(expiredSearchMessage(searchId));
+  }
+  let backendURL = null;
+  if (!to) {
+    backendURL = await client.resolveEngineBackend({ brandId });
+  }
+  if (backendURL) {
+    return { direct: true, backendURL, presId: null, registry: null, entry: null };
+  }
+  const registry = await client.requirePaneHost();
+  const entry =
+    pick === "any"
+      ? client.pickAnyPresentationEntry(registry, to)
+      : client.pickPresentationEntry(registry, to);
+  return {
+    direct: false,
+    backendURL: entry.backendURL ?? null,
+    presId: entry.presId,
+    registry,
+    entry,
+  };
+}
+
+// The design a deck is bound to (presFP == brandId), or null when it isn't bound
+// / isn't a deck. Routing state only — never printed.
+async function deckBrandId(deckDir) {
+  if (!deckDir) return null;
+  const bundleMod = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  return bundleMod.readDeckBundleRef(deckDir)?.presFP ?? null;
+}
+
+// A pane-ready window, or null — never a throw, and never a wait. Used by the
+// stale-snapshot paths below, where an open pane is an OPTION rather than a
+// precondition. `to` is honoured only when it names a window that is actually
+// registered; a stale --to must not cost the caller its fallback.
+async function openPaneEntry(client, to = null) {
+  const registry = (await client.paneReadyPresentations?.()) ?? [];
+  if (registry.length === 0) return null;
+  const explicit = registry.some((p) => p.presId === to) ? to : null;
+  try {
+    return { registry, entry: client.pickAnyPresentationEntry(registry, explicit) };
+  } catch {
+    // Several windows and no way to choose — no automatic fallback from here.
+    return null;
+  }
+}
+
+// The ONE rendering of a stale permission snapshot. The snapshot is the
+// backend's cached copy of the user's group memberships and it backs the
+// PANE-FREE path only: an open task pane signs every request with a live
+// browser token, which is strictly fresher than any snapshot. So when a
+// pane-ready window is already open, "open the slidemind add-in once" is wrong
+// twice over — it IS open, and that window can serve a fresh search right now.
+// Returns the message, or null when this isn't a stale-snapshot failure.
+async function staleSnapshotMessage(client, err, { to = null } = {}) {
+  const blocker = client.permissionsStaleBlocker?.(err);
+  if (!blocker) return null;
+  const pane = await openPaneEntry(client, to);
+  if (!pane) return blocker.message;
+  const env = pane.entry.env ? ` [${pane.entry.env}]` : "";
+  return (
+    `${blocker.message} A slidemind pane is already open${env} and signs each request live, so a fresh ` +
+    `search through that window works now: slidemind search "<query>" --to ${pane.entry.presId}.`
+  );
+}
+
+// Engine-route failures the USER has to clear get one actionable line instead of
+// a relay error. `permissions_stale` is the search permission snapshot having
+// aged out — the server hands back the exact remediation ("open the slidemind
+// add-in once…"), and only corpus search degrades; render and bundle don't.
+// Anything else is re-thrown for the top-level handler.
+async function failOnEngineBlocker(client, err, { to = null } = {}) {
+  const message = await staleSnapshotMessage(client, err, { to });
+  if (message) fail(message);
+  throw err;
+}
+
+// A stale snapshot that an OPEN PANE can simply route around. Only an operation
+// that can be replayed pane-side qualifies — creating a NEW search, whose id the
+// pane mints itself. A record-bound op on an opaque searchId cannot: the pane's
+// handler only understands its own per-window numeric ids, so those get
+// staleSnapshotMessage's extended blocker instead. Returns { registry, entry }
+// or null.
+async function paneRelayForStaleSnapshot(client, err, { to = null } = {}) {
+  if (!client.permissionsStaleBlocker?.(err)) return null;
+  return openPaneEntry(client, to);
+}
+
+// The pane-free routes refuse exactly two things outright: bytes that live in
+// SharePoint (`asset_needs_host`, which needs a delegated token only a browser
+// can mint) and an icon tint (`recolor_needs_host`, whose classifier is
+// DOM-based). An open pane does both, so the remediation is the RELAY — name it,
+// rather than echoing a 409 whose "retry" would take the identical route.
+// Returns null for anything else.
+function describeHostOnlyEngineFailure(err) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  if (code !== "asset_needs_host" && code !== "recolor_needs_host") return null;
+  const detail =
+    typeof err?.body?.error === "string" ? err.body.error : (err?.message ?? "");
+  return (
+    `${detail} Run 'slidemind search "<query>" --to <presId>' against an open window and ` +
+    "re-pick, then repeat this download with the same --to — that relays it through the pane."
+  );
+}
+
 async function cmdSearch(rest) {
   let asJson = false;
   let to = null;
+  let deck = null;
   let engineId = null;
   let resultType = null;
   let intent = null;
@@ -703,6 +971,9 @@ async function cmdSearch(rest) {
     } else if (a === "--to") {
       to = rest[++i];
       if (!to) fail("--to expects a presId");
+    } else if (a === "--deck") {
+      deck = rest[++i];
+      if (!deck) fail("--deck expects a deck name or path");
     } else if (a === "--engine" || a === "-e" || a === "--engineId") {
       engineId = rest[++i];
       if (!engineId) fail("--engine expects an engineId");
@@ -734,12 +1005,13 @@ async function cmdSearch(rest) {
   const query = queryParts.join(" ").trim();
   if (!query) {
     fail(
-      `usage: slidemind search "<query>" [--engine <id|scope:all|scope:sharepoint>] [--result-type slide|image] [--intent auto|content|visual] [--top <N>] [--to <presId>] [--json]`,
+      `usage: slidemind search "<query>" [--engine <id|scope:all|scope:sharepoint>] [--result-type slide|image] [--intent auto|content|visual] [--top <N>] [--deck <deck>] [--to <presId>] [--json]`,
     );
   }
 
-  // Engine search runs against the add-in's live engine over the bridge — an
-  // open host is required.
+  // Engine search runs against the add-in's live engine over the bridge —
+  // pane-free where the add-in serves the direct routes, relayed through an open
+  // window (host required) where it doesn't.
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
@@ -749,14 +1021,23 @@ async function cmdSearch(rest) {
   const { resolveAssetExt } = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
   );
-  const registry = await client.requirePaneHost();
-  // The engine is per-user, not window-bound — so search just attaches to any
-  // connected window (preferring a live one). No "which window?" prompt; pass
-  // --to only to pin a specific one. The chosen window is printed below so
-  // follow-up insert/add-slide can target the same pane the searchId lives on.
-  const entry = client.pickAnyPresentationEntry(registry, to);
-  const presId = entry.presId;
-  const backendURL = entry.backendURL ?? null;
+  // The engine catalog is per-user, not window-bound. On the pane path search
+  // attaches to any connected window (preferring a live one) and the chosen
+  // window is printed below, because the searchId lives on that pane; on the
+  // direct path the searchId is the backend's and no window is involved.
+  const routing = await resolveEngineRouting(client, {
+    to,
+    brandId: await deckBrandId(deck ? resolveDeckArg(deck) : null),
+    pick: "any",
+  });
+  const presId = routing.presId;
+  const backendURL = routing.backendURL;
+  // Mutable, because a stale permission snapshot can push a direct search onto
+  // the pane relay below — and once it does, the searchId belongs to a WINDOW
+  // and every next-step hint has to name it.
+  let direct = routing.direct;
+  let registry = routing.registry;
+  let entry = routing.entry;
 
   // An explicit content/visual intent means "search slides", not imagery.
   const slideIntent = intent === "content" || intent === "visual";
@@ -789,9 +1070,18 @@ async function cmdSearch(rest) {
         // Best-effort: a bundle that can't be materialized (e.g. an incomplete
         // one) must not replace the actionable "wire an image engine" message
         // below with a bundle error — the live catalog is the real answer here.
-        const mat = await bundle
-          .materializeBundle(presId, { backendURL })
-          .catch(() => null);
+        // Pane path: fetch by the window's presId. Direct path: there is no
+        // window, so only a bound deck (--deck) can name the design; without one
+        // there is nothing to fall back to and the live catalog's answer stands.
+        const brandId = presId
+          ? null
+          : await deckBrandId(deck ? resolveDeckArg(deck) : null);
+        const mat =
+          presId || brandId
+            ? await bundle
+                .materializeBundle(presId, { backendURL, brandId })
+                .catch(() => null)
+            : null;
         if (mat) pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
       }
       if (!pick) {
@@ -818,23 +1108,65 @@ async function cmdSearch(rest) {
     resultType = null;
   }
 
-  // Window-agnostic: tries the picked pane, then fails over to any other live
-  // window on the same backend if it's suspended/frozen. The answering window
-  // (res.presId) is what reuse must target — the searchId is bound to it.
-  const res = await client.engineSearchAnyPane({
-    registry,
-    explicitPresId: to,
-    engineId,
-    query,
-    subtype,
-    resultType,
-    intent: intent ?? null,
-    top: top ?? null,
-  });
-  const ranPresId = res?.presId ?? presId;
-  const ranEntry = registry.find((p) => p.presId === ranPresId) ?? entry;
+  // Direct: one pane-free call against the backend that owns the searchId.
+  // Pane: window-agnostic — tries the picked pane, then fails over to any other
+  // live window on the same backend if it's suspended/frozen. The answering
+  // window (res.presId) is what reuse must target there, since the searchId is
+  // bound to it.
+  const relaySearch = (reg) =>
+    client.engineSearchAnyPane({
+      registry: reg,
+      explicitPresId: to,
+      engineId,
+      query,
+      subtype,
+      resultType,
+      intent: intent ?? null,
+      top: top ?? null,
+    });
+  let res;
+  try {
+    res = direct
+      ? await client.engineSearch({
+          engineId,
+          query,
+          subtype,
+          resultType,
+          intent: intent ?? null,
+          top: top ?? null,
+          backendURL,
+        })
+      : await relaySearch(routing.registry);
+  } catch (err) {
+    // A stale permission snapshot degrades the PANE-FREE path only — an open
+    // pane signs each request live, which is strictly fresher than the
+    // snapshot. Creating a new search is exactly the operation the pane can
+    // replay (it mints its own searchId), so relay it rather than telling the
+    // user to open an add-in that is already open.
+    const relay = direct ? await paneRelayForStaleSnapshot(client, err, { to }) : null;
+    if (!relay) await failOnEngineBlocker(client, err, { to });
+    process.stderr.write(
+      `note: this environment's search permission snapshot has aged out, so the search ran through the open ` +
+        `slidemind pane${relay.entry.env ? ` [${relay.entry.env}]` : ""} instead (it signs each request live).\n`,
+    );
+    direct = false;
+    registry = relay.registry;
+    entry = relay.entry;
+    try {
+      res = await relaySearch(registry);
+    } catch (relayErr) {
+      await failOnEngineBlocker(client, relayErr, { to });
+    }
+  }
+  const ranPresId = res?.presId ?? entry?.presId ?? presId;
+  const ranEntry = direct
+    ? { env: res?.env ?? null }
+    : (registry.find((p) => p.presId === ranPresId) ?? entry);
   if (asJson) {
-    process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+    // The searchId rides the JSON so an interrupted agent can resume its picks
+    // without re-searching. The backendURL never does — env label only.
+    const { backendURL: _routingOnly, ...pub } = res ?? {};
+    process.stdout.write(`${JSON.stringify(pub, null, 2)}\n`);
     return;
   }
   if (!res?.ok) {
@@ -891,6 +1223,16 @@ async function cmdSearch(rest) {
         `Contact sheet of all ${count} result(s) — LOOK AT THIS FILE to choose, ` +
           `don't fetch previews one by one: ${gridPath}\n`,
       );
+    } else if (direct) {
+      // The pane composes the collage in a DOM; the pane-free route may not
+      // have one to hand back (`gridUnavailable`, or simply no grid field on an
+      // add-in that hasn't grown it yet). Say where previews come from instead
+      // — otherwise an agent that has learned to expect a contact sheet quietly
+      // issues N thumbnail fetches to rebuild it.
+      process.stdout.write(
+        `No contact sheet on this path — preview candidates one at a time instead: ` +
+          `slidemind view-slide --search ${res.searchId} --pick <n>\n`,
+      );
     }
   }
   // Tailor the next-step hint to the result kind: slide verbs (insert-slide /
@@ -899,8 +1241,24 @@ async function cmdSearch(rest) {
   // add-ins that don't echo a top-level subtype.
   const isSlideResults =
     res.subtype === "slide" || results.some((r) => r.kind === "slide");
-  const envTag = ranEntry.env ? ` [${ranEntry.env}]` : "";
-  if (isSlideResults) {
+  const envTag = ranEntry?.env ? ` [${ranEntry.env}]` : "";
+  if (direct) {
+    // The searchId belongs to the BACKEND here, not to a window: picks work with
+    // PowerPoint closed, so the follow-up commands carry no --to. Live insert is
+    // the one step that still names a window (it types into an open deck).
+    if (isSlideResults) {
+      process.stdout.write(
+        `searchId ${res.searchId}${envTag} is held by the add-in — reuse it with no PowerPoint window:\n` +
+          `  slidemind add-slide --search ${res.searchId} --pick <n> --deck <deck>\n` +
+          `  slidemind insert-slide --search ${res.searchId} --pick <n> --to <presId>   (live insert needs an open window)\n`,
+      );
+    } else {
+      process.stdout.write(
+        `searchId ${res.searchId}${envTag} is held by the add-in — download image result(s) into a deck (no window needed):\n` +
+          `  slidemind download-result --search ${res.searchId} --pick <n[,n,...]> --deck <deck> [--icon-color <hex>]\n`,
+      );
+    }
+  } else if (isSlideResults) {
     // The searchId is bound to the window the search ran on — reuse must target
     // that same window, so spell out its presId in the next-step commands.
     process.stdout.write(
@@ -962,16 +1320,58 @@ async function cmdLs(rest) {
   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;
+    // Pane-free where the add-in serves the direct routes; otherwise the catalog
+    // is relayed through a window, so a live pane is still the precondition.
+    try {
+      backendURL = (await resolveEngineRouting(client, { to, pick: "any" }))
+        .backendURL;
+    } catch (err) {
+      // Listing is the one engine op that can simply show EVERY environment
+      // (each engine is tagged with its env), so an ambiguous multi-environment
+      // session fans out here rather than demanding --backend.
+      if (err?.code !== "engine_backend_ambiguous") throw err;
+      backendURL = null;
+    }
+  }
+  let engines;
+  // The pane-free route's summary of the catalog BEFORE the type/subtype
+  // filter; null on older add-ins and on the pane-relay path.
+  let catalog = null;
+  // Which environments answered. The catalog is POOLED, and pooling dedupes the
+  // scopes every environment repeats — so a second environment can contribute
+  // no row of its own, and the surviving rows can no longer be counted to learn
+  // whether more than one answered.
+  let envs = [];
+  try {
+    ({ engines, catalog, envs = [] } = await client.listEngines({
+      type,
+      subtype,
+      backendURL,
+    }));
+  } catch (err) {
+    // No pane fallback here: `GET /api/cli/engines` is the catalog route on both
+    // add-in generations (newer ones answer it directly, older ones relay it
+    // themselves), so there is no second route to retry on. The message does
+    // name the open pane, because searching THROUGH it still works.
+    await failOnEngineBlocker(client, err, { to });
   }
-  const { engines } = await client.listEngines({ type, subtype, backendURL });
   if (asJson) {
-    process.stdout.write(`${JSON.stringify(engines, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({ engines, catalog, envs }, null, 2)}\n`);
     return;
   }
   if (engines.length === 0) {
+    // A filter that matched nothing is NOT an empty deployment — the summary is
+    // the only thing that tells the two apart, so say which one this is and the
+    // next move follows (drop the filter vs. search the corpus unfiltered).
+    const unfiltered = catalog ? catalog.totalEngines + catalog.totalScopes : 0;
+    if (catalog?.filtered && unfiltered > 0) {
+      process.stderr.write(
+        `No engine or scope matched this filter, but ${catalog.totalEngines} engine(s) ` +
+          `and ${catalog.totalScopes} scope(s) exist. Re-run 'slidemind ls engines' ` +
+          "without --type/--subtype to see them.\n",
+      );
+      return;
+    }
     // Deliberately not "nothing to search": an engine is a saved folder filter
     // over the add-in's shared corpus, so an empty catalog says only that nobody
     // saved a filter. An older add-in that predates scopes lands here too.
@@ -986,8 +1386,11 @@ async function cmdLs(rest) {
     );
     return;
   }
-  // Show the env tag only when more than one environment contributed engines.
-  const multiEnv = new Set(engines.map((e) => e.env)).size > 1;
+  // Show the env tag only when more than one environment contributed. Two
+  // environments can carry identically-named engines, and without the tag the
+  // pooled list gives no way to tell them apart. Deduped scope rows carry no env
+  // of their own (they exist on every environment), so they stay untagged.
+  const multiEnv = envs.length > 1 || new Set(engines.map((e) => e.env)).size > 1;
   for (const e of engines) {
     const kind = [e.type, e.subtype].filter(Boolean).join("/");
     const env = multiEnv && e.env ? `[${e.env}] ` : "";
@@ -998,12 +1401,28 @@ async function cmdLs(rest) {
       e.type === "scope"
         ? ` (needs --result-type ${(e.capabilities?.resultTypes ?? ["slide", "image"]).join("|")})`
         : "";
+    // An engine that exists but has nothing indexed yet returns zero hits for
+    // every query; say so here so an empty search isn't read as a bad engine id.
+    const state =
+      e.content?.state === "empty"
+        ? " (nothing indexed yet)"
+        : e.content?.state === "indexing"
+          ? " (indexing)"
+          : "";
     process.stdout.write(
-      `${env}${e.id} · ${e.label ?? e.id} · ${kind}${hint}${desc}\n`,
+      `${env}${e.id} · ${e.label ?? e.id} · ${kind}${hint}${state}${desc}\n`,
     );
   }
 }
 
+// A searchId is a number when the pane minted it (the relay path) and an opaque
+// server-minted id on the pane-free engine routes, where the search record lives
+// on the backend. Accept both so a pick round-trips whichever search produced it.
+function parseSearchIdArg(raw, flag = "--search") {
+  if (!raw || raw.startsWith("-")) fail(`${flag} expects a searchId, got '${raw}'`);
+  return /^\d+$/.test(raw) ? parseInt(raw, 10) : raw;
+}
+
 function parsePicks(raw, flag = "--pick") {
   if (!raw) fail(`${flag} expects a comma-separated list of selection numbers`);
   // Tolerate a trailing/empty segment ("1," or "1,,2") by dropping blank parts
@@ -1023,6 +1442,45 @@ function parsePicks(raw, flag = "--pick") {
   return picks;
 }
 
+/**
+ * Turn a live-insert failure into the action that actually fixes it. The client
+ * has already re-listed the registry and retried ONCE against the live window
+ * (a pane reconnect churns the presId), so a pane error that reaches here is one
+ * only the user can clear — and the way around it is the window-free fold.
+ *
+ * A stale permission snapshot is NOT among them: it is authored once, in
+ * staleSnapshotMessage, which the caller consults first.
+ */
+function describeInsertSlideFailure(err, searchId) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  if (code === "unknown_search") {
+    return `searchId ${searchId} is no longer available. Run 'slidemind search' again, then re-pick.`;
+  }
+  if (code === "searchId_required") {
+    // The pane was handed an id it cannot resolve — its search context is
+    // per-window and numeric, and a server-minted id was never in it.
+    return (
+      `searchId ${searchId} belongs to the add-in, not to that PowerPoint window. ` +
+      `Re-run 'slidemind search' (the CLI picks the reuse route from where the search ran), then re-pick.`
+    );
+  }
+  const paneAsleep =
+    code === "pane_suspended" ||
+    code === "pane_timeout" ||
+    // A relay 404 about the presId itself carries prose and no machine code,
+    // and bridgeFetch falls `code` back to that prose — so read the PARSED one.
+    (err?.status === 404 &&
+      (!err?.body?.code || err.body.code === "unknown_presentation"));
+  if (paneAsleep) {
+    return (
+      "the slidemind task pane in that PowerPoint window is not responding (already retried once). " +
+      "Foreground PowerPoint and click the slidemind pane to wake it, then re-run — or reuse the same " +
+      `result with no window at all: slidemind add-slide --search ${searchId} --pick <n> --deck <deck>.`
+    );
+  }
+  return `insert-slide failed: ${err?.message ?? "unknown error"}`;
+}
+
 async function cmdInsertSlide(rest) {
   let searchId = null;
   let picks = null;
@@ -1031,10 +1489,7 @@ async function cmdInsertSlide(rest) {
   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;
+      searchId = parseSearchIdArg(rest[++i]);
     } else if (a === "--pick") {
       picks = parsePicks(rest[++i]);
     } else if (a === "--to") {
@@ -1059,20 +1514,97 @@ async function cmdInsertSlide(rest) {
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
+  // Live insert types into an OPEN presentation, so it stays window- and
+  // pane-bound even where the rest of the engine surface has moved off the pane.
   const registry = await client.requirePaneHost();
   const entry = client.pickPresentationEntry(registry, to);
-  const res = await client.insertSlideLive({
-    presId: entry.presId,
-    searchId,
-    selections: picks,
-    at,
-    backendURL: entry.backendURL ?? null,
-  });
+  // Window identity for the client's single retry: a pane reconnect mints a NEW
+  // presId for the same window, and the design fingerprint re-matches it — but
+  // only against windows we did NOT already see next to the target, or a second
+  // deck on the same corporate design would take the insert.
+  const identity = {
+    fileName: entry.fileName ?? entry.title ?? null,
+    brandId: entry.brandId ?? null,
+    otherPresIds: registry
+      .map((p) => p.presId)
+      .filter((id) => id && id !== entry.presId),
+  };
+  // WHERE the searchId lives decides how the reuse runs. A number came from
+  // that window's own pane search and the pane resolves it; an opaque id is the
+  // backend's (the pane-free search) and the pane has never seen it — so those
+  // picks are extracted pane-free and inserted as bytes instead.
+  //
+  // Which backend extracts them is the RECORD's, not the window's. Those are
+  // different environments as soon as two are connected, and spending a
+  // server-owned id against the window's origin 404s as `unknown_search` — read
+  // as "the search expired", which sends the agent round a re-search loop that
+  // can never resolve. The window stays the INSERT target either way.
+  let engineBackendURL = null;
+  if (client.isOpaqueSearchId?.(searchId)) {
+    try {
+      engineBackendURL = await client.resolveSearchBackend(searchId);
+    } catch (err) {
+      await failOnEngineBlocker(client, err, { to: entry.presId });
+    }
+    if (!engineBackendURL) fail(expiredSearchMessage(searchId));
+  }
+  let res;
+  try {
+    res = engineBackendURL
+      ? await client.insertSlidesFromSearch({
+          presId: entry.presId,
+          searchId,
+          selections: picks,
+          at,
+          backendURL: entry.backendURL ?? null,
+          engineBackendURL,
+          ...identity,
+        })
+      : await client.insertSlideLive({
+          presId: entry.presId,
+          searchId,
+          selections: picks,
+          at,
+          backendURL: entry.backendURL ?? null,
+          ...identity,
+        });
+  } catch (err) {
+    fail(
+      (await staleSnapshotMessage(client, err, { to: entry.presId })) ??
+        describeInsertSlideFailure(err, searchId),
+    );
+  }
   if (!res?.ok) {
     fail(`insert-slide failed: ${res?.error ?? "unknown error"}`);
   }
   process.stdout.write(
-    `Inserted ${res.insertedCount ?? picks.length} slide(s) into presentation ${entry.presId}\n`,
+    `Inserted ${res.insertedCount ?? picks.length} slide(s) into presentation ${res.presId ?? entry.presId}\n`,
+  );
+}
+
+// One line per written slide, plus the machine-readable twin. The searchId is
+// echoed on purpose: an agent interrupted between picks can resume from the JSON
+// without re-running the search (the record lives on the backend now).
+function writeAddSlideResult({ asJson, searchId, deckDir, deck, written, slides }) {
+  if (asJson) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          searchId,
+          deck: path.relative(process.cwd(), deckDir),
+          slides,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+  process.stdout.write(
+    `Added ${written.length} reused slide(s) to ${path.relative(process.cwd(), deckDir)}:\n` +
+      written.map((w) => `  ${w}`).join("\n") +
+      `\nThey are native .pptx in slides/ — re-run 'slidemind build-pptx ${deck}' or 'slidemind push ${deck}' to render the deck with them spliced in.\n`,
   );
 }
 
@@ -1083,13 +1615,13 @@ async function cmdAddSlide(rest) {
   let at = null;
   let to = null;
   let from = null;
+  let asJson = false;
   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;
+    if (a === "--json") {
+      asJson = true;
+    } else if (a === "--search") {
+      searchId = parseSearchIdArg(rest[++i]);
     } else if (a === "--from") {
       from = rest[++i];
       if (!from) fail("--from expects a path to a .pptx file");
@@ -1162,21 +1694,30 @@ async function cmdAddSlide(rest) {
       .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"));
     const targets = reused.reusedSlideTargets(existing, results, at);
     const written = [];
+    const slides = [];
     results.forEach((r, i) => {
       const target = path.join(slidesDir, targets[i].filename);
       fs.writeFileSync(target, Buffer.from(r.bytes));
       written.push(path.relative(process.cwd(), target));
+      slides.push({
+        selection: picks[i] ?? null,
+        slideId: r.slideId ?? null,
+        file: path.relative(process.cwd(), target),
+      });
+    });
+    writeAddSlideResult({
+      asJson,
+      searchId: null,
+      deckDir,
+      deck,
+      written,
+      slides,
     });
-    process.stdout.write(
-      `Added ${written.length} reused slide(s) to ${path.relative(process.cwd(), deckDir)}:\n` +
-        written.map((w) => `  ${w}`).join("\n") +
-        `\nThey are native .pptx in slides/ — re-run 'slidemind build-pptx ${deck}' or 'slidemind push ${deck}' to render the deck with them spliced in.\n`,
-    );
     return;
   }
 
   if (searchId === null || !picks || !deck) {
-    fail("usage: slidemind add-slide (--search <id> | --from <file.pptx>) --pick <n[,n,...]> --deck <deck> [--to <presId>] [--at <N>]");
+    fail("usage: slidemind add-slide (--search <id> | --from <file.pptx>) --pick <n[,n,...]> --deck <deck> [--to <presId>] [--at <N>] [--json]");
   }
   const deckDir = resolveDeckArg(deck);
   const slidesDir = path.join(deckDir, "slides");
@@ -1185,12 +1726,17 @@ async function cmdAddSlide(rest) {
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.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 presId = entry.presId;
-  const backendURL = entry.backendURL ?? null;
+  // Direct path: an opaque searchId routes to the environment that minted the
+  // record; the deck's bound design only decides when the id can't. Pane path:
+  // 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 routing = await resolveEngineRouting(client, {
+    to,
+    brandId: await deckBrandId(deckDir),
+    searchId,
+  });
+  const presId = routing.presId;
+  const backendURL = routing.backendURL;
 
   // Extract each picked slide's bytes over the bridge, then let the shared
   // helper compute the play-order filenames (NN-reused-<shortid>.pptx). The
@@ -1211,9 +1757,12 @@ async function cmdAddSlide(rest) {
       if (s.tempPath) fs.rmSync(s.tempPath, { force: true });
     }
   };
+  // A searchId can be an opaque server id on the direct path — keep it usable as
+  // a file name component.
+  const searchKey = String(searchId).replace(/[^A-Za-z0-9._-]/g, "_");
   try {
     for (const pick of picks) {
-      const tempPath = path.join(slidesDir, `.reused-${searchId}-${pick}.part`);
+      const tempPath = path.join(slidesDir, `.reused-${searchKey}-${pick}.part`);
       if (typeof client.extractSlideToFile === "function") {
         try {
           const res = await client.extractSlideToFile({
@@ -1229,11 +1778,17 @@ async function cmdAddSlide(rest) {
           continue;
         } catch (err) {
           fs.rmSync(tempPath, { force: true });
+          const stale = await staleSnapshotMessage(client, err, { to });
+          if (stale) {
+            cleanupTemps();
+            fail(stale);
+          }
           // Route absent (bodyless 404 / 501) → this add-in predates the streaming
-          // route; fall through to the capped base64 ack path below.
+          // route; fall through to the capped base64 ack path below. On the
+          // pane-free path there is no ack path to fall back to.
           const routeMissing =
             (err?.status === 404 && !err?.code) || err?.status === 501;
-          if (!routeMissing) {
+          if (!routeMissing || !presId) {
             cleanupTemps();
             fail(`add-slide failed for selection ${pick}: ${err.message}`);
           }
@@ -1260,6 +1815,7 @@ async function cmdAddSlide(rest) {
     .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"));
   const targets = reused.reusedSlideTargets(existing, extracted, at);
   const written = [];
+  const slides = [];
   extracted.forEach((slide, i) => {
     const target = path.join(slidesDir, targets[i].filename);
     if (slide.tempPath) {
@@ -1268,12 +1824,13 @@ async function cmdAddSlide(rest) {
       fs.writeFileSync(target, Buffer.from(slide.base64, "base64"));
     }
     written.push(path.relative(process.cwd(), target));
+    slides.push({
+      selection: slide.selection,
+      slideId: slide.slideId ?? null,
+      file: path.relative(process.cwd(), target),
+    });
   });
-  process.stdout.write(
-    `Added ${written.length} reused slide(s) to ${path.relative(process.cwd(), deckDir)}:\n` +
-      written.map((w) => `  ${w}`).join("\n") +
-      `\nThey are native .pptx in slides/ — re-run 'slidemind build-pptx ${deck}' or 'slidemind push ${deck}' to render the deck with them spliced in.\n`,
-  );
+  writeAddSlideResult({ asJson, searchId, deckDir, deck, written, slides });
 }
 
 // Map a `--icon-color` value onto the `--pick` list. Accepts either one colour
@@ -1307,10 +1864,7 @@ async function cmdViewSlide(rest) {
   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;
+      searchId = parseSearchIdArg(rest[++i]);
     } else if (a === "--pick") {
       const next = rest[++i];
       const n = parseInt(next, 10);
@@ -1331,7 +1885,7 @@ async function cmdViewSlide(rest) {
     }
   }
   if (searchId === null || pick === null) {
-    fail("usage: slidemind view-slide --search <id> --pick <n> --to <presId> [--out <dir>]");
+    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
@@ -1339,16 +1893,18 @@ async function cmdViewSlide(rest) {
   const { resolveAssetExt } = 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,
-  });
+  const routing = await resolveEngineRouting(client, { to, searchId });
+  let res;
+  try {
+    res = await client.viewSlide({
+      presId: routing.presId,
+      searchId,
+      selection: pick,
+      backendURL: routing.backendURL,
+    });
+  } catch (err) {
+    await failOnEngineBlocker(client, err, { to });
+  }
   if (!res?.ok || !res.dataUri) {
     fail(`view-slide failed: ${res?.error ?? "no image returned"}`);
   }
@@ -1372,6 +1928,135 @@ async function cmdViewSlide(rest) {
   );
 }
 
+async function cmdReadSource(rest) {
+  let searchId = null;
+  let pick = null;
+  let fromSlide = null;
+  let toSlide = null;
+  let to = null;
+  let outFile = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--search") {
+      searchId = parseSearchIdArg(rest[++i]);
+    } 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 === "--from-slide") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--from-slide expects a positive slide number, got '${next}'`);
+      }
+      fromSlide = n;
+    } else if (a === "--to-slide") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--to-slide expects a positive slide number, got '${next}'`);
+      }
+      toSlide = n;
+    } else if (a === "--to") {
+      // Deliberately the WINDOW, matching every other search-scoped command.
+      // The slide window is --from-slide/--to-slide.
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--out" || a === "-o") {
+      outFile = rest[++i];
+      if (!outFile) fail("--out expects a file path");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (searchId === null || pick === null) {
+    fail(
+      "usage: slidemind read-source --search <id> --pick <n> [--from-slide <n>] [--to-slide <n>] [--to <presId>] [--out <file>]",
+    );
+  }
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  // Pane path: the searchId is presentation-scoped, so --to targets the window
+  // the search ran on — same rule as view-slide. Direct path: the record is the
+  // backend's, so no window is involved.
+  const routing = await resolveEngineRouting(client, { to, searchId });
+  let res;
+  try {
+    res = await client.readSourcePresentation({
+      presId: routing.presId,
+      searchId,
+      selection: pick,
+      fromSlide,
+      toSlide,
+      backendURL: routing.backendURL,
+    });
+  } catch (err) {
+    // The stale-snapshot line is authored once and knows about an open pane;
+    // everything else is this command's own vocabulary.
+    fail(
+      (await staleSnapshotMessage(client, err, { to })) ??
+        describeReadSourceFailure(err, searchId, pick),
+    );
+  }
+  if (!res?.markdown) {
+    fail("read-source returned no content. Try the search again, then re-pick.");
+  }
+  if (outFile) {
+    const target = path.resolve(process.cwd(), outFile);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, res.markdown, "utf8");
+    process.stdout.write(
+      `Wrote the source presentation of result ${pick} (searchId ${searchId}) to ${target}\n`,
+    );
+  } else {
+    process.stdout.write(res.markdown.endsWith("\n") ? res.markdown : `${res.markdown}\n`);
+  }
+  // Truncation is the one thing a reader must not miss: the body they just got
+  // is a slide map, not the deck.
+  if (res.truncated) {
+    process.stderr.write(
+      `note: this deck was too long to return in full — the output is its slide map. ` +
+        `Re-run with --from-slide/--to-slide to read a range.\n`,
+    );
+  } else if (res.totalSlideCount && res.slideCount < res.totalSlideCount) {
+    process.stderr.write(
+      `note: showing ${res.slideCount} of ${res.totalSlideCount} slides.\n`,
+    );
+  }
+}
+
+/**
+ * Turn a source-presentation failure into the action that actually fixes it.
+ * A stale permission snapshot is handled one level up, in staleSnapshotMessage
+ * — it is the one blocker only the USER can clear and it reads identically
+ * across every command.
+ */
+function describeReadSourceFailure(err, searchId, pick) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  switch (code) {
+    case "unknown_search":
+      return `searchId ${searchId} is no longer available on that window. Run 'slidemind search' again, then re-pick.`;
+    case "wrong_result_type":
+      return `result ${pick} has no source presentation — only slide search results come from a deck (image and collection results do not).`;
+    case "access_denied":
+      return "you do not have access to that result's source presentation.";
+    case "no_indexed_content":
+      return "that presentation has no indexed slides yet. It may still be syncing — try again later.";
+    case "invalid_source":
+      return `result ${pick} carries no source file reference. Re-run the search, or pick a different result.`;
+    case "source_presentation_unsupported":
+      return err.message;
+    default:
+      return `read-source failed: ${err?.message ?? "unknown error"}`;
+  }
+}
+
 async function cmdDownloadResult(rest) {
   let searchId = null;
   let picks = null;
@@ -1381,10 +2066,7 @@ async function cmdDownloadResult(rest) {
   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;
+      searchId = parseSearchIdArg(rest[++i]);
     } else if (a === "--pick") {
       picks = parsePicks(rest[++i]);
     } else if (a === "--deck") {
@@ -1404,7 +2086,7 @@ async function cmdDownloadResult(rest) {
   }
   if (searchId === null || !picks || !deck) {
     fail(
-      "usage: slidemind download-result --search <id> --pick <n[,n,...]> --deck <deck> --to <presId> [--icon-color <hex[,hex,...]>]",
+      "usage: slidemind download-result --search <id> --pick <n[,n,...]> --deck <deck> [--to <presId>] [--icon-color <hex[,hex,...]>]",
     );
   }
   const iconColors = parseIconColors(iconColorsRaw, picks.length);
@@ -1419,10 +2101,15 @@ async function cmdDownloadResult(rest) {
   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);
+  // Direct path: an opaque searchId routes to the record's own environment,
+  // else the deck's bound design decides; no window needed. Pane path: the
+  // searchId is presentation-scoped, so --to targets the window the search ran
+  // on (without it, >1 open window is a dead-end).
+  const routing = await resolveEngineRouting(client, {
+    to,
+    brandId: await deckBrandId(deckDir),
+    searchId,
+  });
 
   // Concurrent — each download is its own bridge round-trip; allSettled so one
   // bad selection doesn't sink the rest of the batch.
@@ -1430,8 +2117,8 @@ async function cmdDownloadResult(rest) {
     picks.map((selection, i) =>
       downloadOneResult({
         client,
-        presId: entry.presId,
-        backendURL: entry.backendURL ?? null,
+        presId: routing.presId,
+        backendURL: routing.backendURL,
         searchId,
         assetsDir,
         selection,
@@ -1439,10 +2126,22 @@ async function cmdDownloadResult(rest) {
       }),
     ),
   );
+  // One user-clearable blocker sinks the whole batch identically — every pick
+  // would fail the same way, and the fix is one action, not N error lines.
+  const stale = settled.find(
+    (r) => r.status === "rejected" && client.permissionsStaleBlocker?.(r.reason),
+  );
+  if (stale) fail(await staleSnapshotMessage(client, stale.reason, { to }));
   const results = settled.map((r, i) =>
     r.status === "fulfilled"
       ? r.value
-      : { selection: picks[i], error: r.reason?.message ?? String(r.reason) },
+      : {
+          selection: picks[i],
+          error:
+            describeHostOnlyEngineFailure(r.reason) ??
+            r.reason?.message ??
+            String(r.reason),
+        },
   );
   const { formatSize } = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "image-dimensions.mjs")).href
@@ -1787,26 +2486,28 @@ function publicConnectionStatus(status, client) {
   };
 }
 
-// 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 one exception is
-// a plugin-installed CLI: `/plugin` is the only updater that replaces the
-// binary on the session's PATH, and the agent cannot drive it, so that rung
-// hands back to the user (see src/install-channel.mjs). The `message` strings
-// are otherwise 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) {
+// The readiness ladder splits in two, because the two halves fail
+// independently: BACKEND AUTHORING readiness (a session, a reachable add-in
+// backend, a supported CLI — everything render, bundle and the pane-free engine
+// routes need) and LIVE POWERPOINT readiness (a registered window, render-ready
+// metadata, an awake pane — what push/insert-slide and reading an open deck
+// need). Keeping them apart is the whole point of doc 13: a dead pane is no
+// longer "cannot work", it only defers the last mile.
+//
+// Each rung is a STRUCTURED blocker: `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 one exception is a plugin-installed CLI:
+// `/plugin` is the only updater that replaces the binary on the session's PATH,
+// and the agent cannot drive it, so that rung hands back to the user (see
+// src/install-channel.mjs).
+function backendBlocker(pub) {
   if (!pub.paired) {
     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>`.",
+        "Not connected. In PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, and run the command it shows.",
     };
   }
   if ((pub.backends ?? []).every((b) => !b.ok)) {
@@ -1830,6 +2531,15 @@ function connectionBlocker(pub) {
         updateCliInstruction(),
     };
   }
+  return null;
+}
+
+// The live-PowerPoint half. Never gates render, bundle or the pane-free engine
+// routes — it only says whether the ops that genuinely type into an open deck
+// (push's insert, insert-slide, reading an unsaved presentation) can run now.
+// The `message` strings are BYTE-IDENTICAL to the pre-split ladder so doctor's
+// printed output never churns.
+function paneBlocker(pub) {
   if ((pub.presentations ?? []).length === 0) {
     return {
       code: "no_window",
@@ -1864,18 +2574,273 @@ function connectionBlocker(pub) {
       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.",
+        "Rendering is available, but pane operations are suspended. Bring PowerPoint forward and click/reopen the slidemind pane before push, insert-slide, or reading this window.",
     };
   }
   return null;
 }
 
+// The two ladders end-to-end, in the order a user hits them: nothing about a
+// window matters while the backend half is unmet. `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) {
+  return backendBlocker(pub) ?? paneBlocker(pub);
+}
+
 // 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 permission SNAPSHOT behind corpus search ages out when nobody opens the
+// add-in for a while. It is a DEGRADATION, never a blocker: render, bundle and
+// every already-materialized asset keep working, only corpus search stops — so
+// it must not sit on either ladder. Newer add-ins report it on the readiness
+// capabilities; the message is authored once, in the client, next to the live
+// 403 shape the engine routes return (client.permissionsStaleBlocker).
+// Which connected environments report an aged-out snapshot on
+// `/api/cli/readiness`. Newer add-ins emit the flag; older ones never do, and
+// there the condition only surfaces as a live 403 on a search.
+function permissionsStaleEnvs(pub) {
+  return (pub.backends ?? [])
+    .filter((b) => b.ok && b.capabilities?.permissionsStale === true)
+    .map((b) => b.env);
+}
+
+function permissionsStaleDegradation(pub, client) {
+  const stale = (pub.backends ?? []).find(
+    (b) => b.ok && b.capabilities?.permissionsStale === true,
+  );
+  if (!stale) return null;
+  const action = stale.capabilities?.permissionsStaleAction;
+  return client.permissionsStaleBlocker({
+    code: "permissions_stale",
+    body: typeof action === "string" ? { action } : {},
+  });
+}
+
+// ---------- one-command setup (npx bootstrap) ----------
+//
+// `npx --yes slidemind@latest setup <claim>` is the whole onboarding: the user
+// clicks "Connect CLI" in the add-in, pastes ONE command, and ends up with a
+// connected, globally-installed CLI. npx only runs the package from its cache —
+// it never installs it — so this command performs the persistent
+// `npm install -g` itself.
+//
+// Order matters: redeem FIRST. The claim is short-lived and one-time, while a
+// global npm install can take a while or hit an EACCES prefix problem. Spending
+// the claim up front means a failed install leaves a connected CLI the user can
+// fix at their leisure, instead of forcing them back to PowerPoint for a fresh
+// command.
+async function cmdSetup(rest) {
+  let claimArg = null;
+  // `auto` is the whole point: setup finishes onboarding by itself, so it
+  // deploys into the coding agents this machine actually has instead of asking
+  // the user to run `init` afterwards.
+  let target = "auto";
+  let doInstall = true;
+  let doReady = true;
+  let asJson = false;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--for" || a === "-f") {
+      target = rest[++i];
+      if (!target) fail("--for expects a target");
+      if (![...HARNESS_TARGETS, "all", "auto", "none"].includes(target)) {
+        fail(`unknown install target: ${target}`);
+      }
+    } else if (a === "--no-install") {
+      doInstall = false;
+    } else if (a === "--no-ready") {
+      doReady = false;
+    } else if (a === "--json") {
+      asJson = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else if (claimArg === null) {
+      claimArg = a;
+    } else {
+      fail("setup takes exactly one setup claim");
+    }
+  }
+
+  if (!claimArg) {
+    fail(
+      "setup needs the connection command from the add-in.\n" +
+        "  Open PowerPoint → slidemind → Settings → General → Connect CLI, copy the command, and paste it here.\n" +
+        "  Already have the CLI? The panel's `CLI already installed?` toggle gives the short `slidemind setup …` form.",
+    );
+  }
+
+  const pkg = readPackageJson();
+  const claims = await loadBridgeModule("setup-claim");
+  // Decode before any UI so a mistyped/partial paste fails in one clean line.
+  const { backendURL, secret } = claims.decodeSetupClaim(claimArg);
+  const cfg = await loadBridgeModule("config");
+  const envLabel = cfg.deriveEnvLabel(backendURL);
+
+  // The installers paint their own progress rail. In --json mode stdout is
+  // reserved for the payload, so silence the whole UI rather than letting it
+  // corrupt what the caller parses.
+  const ui = await loadInstallerUi();
+  if (asJson) ui.silence();
+  ui.banner(pkg.version, "setup");
+
+  // --- 1. spend the claim -------------------------------------------------
+  await ui.section("connect", envLabel);
+  const sessionToken = await claims.redeemSetupClaim({
+    backendURL,
+    secret,
+    cliVersion: pkg.version,
+  });
+  cfg.upsertSession({ backendURL, sessionToken, label: envLabel });
+  ui.step({ label: "authorize", value: envLabel, note: "session saved" });
+
+  // --- 2. make this CLI permanent ----------------------------------------
+  // Without this the whole thing evaporates with npx's cache: the user would be
+  // connected but have no `slidemind` on PATH.
+  let installed = false;
+  let installError = null;
+  const pluginInstall = isClaudePluginInstall();
+  if (doInstall && pluginInstall) {
+    ui.step({
+      status: "warn",
+      label: "install",
+      value: "skipped",
+      note: "this slidemind came from the Claude Code plugin — update it with /plugin",
+    });
+  } else if (doInstall) {
+    await ui.section("install", "npm global");
+    ui.step({ label: "install", value: "slidemind@latest", note: "global (npm)" });
+    try {
+      await spawnInherit(npmBin(), [
+        "install",
+        "-g",
+        "--loglevel=error",
+        "slidemind@latest",
+      ]);
+      installed = true;
+    } catch (err) {
+      installError = err?.message || String(err);
+      ui.step({
+        status: "warn",
+        label: "install",
+        value: "failed",
+        note: "the connection is saved — see the note below",
+      });
+    }
+  }
+
+  // --- 3. deploy the skills ----------------------------------------------
+  // In-process, from THIS package copy: the npx copy and the global install are
+  // the same published version, and going through PATH here would fail on a
+  // shell that has not rehashed yet.
+  //
+  // With the default `auto` this is what removes `slidemind init` from
+  // onboarding: the skills land in every coding agent present on the machine,
+  // and skip any whose plugin already supplies them (copying over a plugin's
+  // skills plants a second set that drifts on the next plugin update).
+  let skills = [];
+  let skippedPlugins = [];
+  if (target !== "none") {
+    if (target === "auto") {
+      const harnesses = await detectHarnesses();
+      skippedPlugins = harnesses
+        .filter((h) => h.present && h.pluginInstalled)
+        .map((h) => h.target);
+    }
+    await ui.section(
+      "skills",
+      target === "auto"
+        ? "detected harnesses"
+        : target === "all"
+          ? "all harnesses"
+          : target,
+    );
+    skills = await runInstaller(target, "install", []);
+    for (const t of skippedPlugins) {
+      ui.step({
+        status: "warn",
+        label: t,
+        value: "skipped",
+        note: "its slidemind plugin already supplies the skills",
+      });
+    }
+    if (skills.length === 0 && skippedPlugins.length === 0) {
+      ui.step({
+        status: "warn",
+        label: "harnesses",
+        value: "none detected",
+        note: "install a coding agent, then run `slidemind init --for auto`",
+      });
+    }
+    const bundleMod = await loadBridgeModule("bundle");
+    bundleMod.clearBundleCache();
+  }
+
+  if (asJson) {
+    const globalInstall =
+      doInstall && !pluginInstall
+        ? installed
+          ? "installed"
+          : "failed"
+        : "skipped";
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          connected: true,
+          env: envLabel,
+          globalInstall,
+          skills,
+          // Present-but-plugin-served harnesses, so an agent can tell "nothing
+          // deployed because nothing is installed" from "nothing needed".
+          skippedPlugins,
+          nextAction: "slidemind ready",
+          // Only on the unhappy path: the session IS saved, so `ok` stays true,
+          // but an agent needs to know the binary did not land.
+          ...(installError ? { installError } : {}),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+
+  ui.done(
+    target === "none" || (skills.length === 0 && skippedPlugins.length === 0)
+      ? `connected to ${envLabel} — run 'slidemind ready' to start`
+      : `connected to ${envLabel} and ready to use`,
+  );
+
+  if (installError) {
+    process.stderr.write(
+      "\nslidemind is connected, but the global install could not write to npm's global package directory.\n" +
+        "This usually happens on macOS/Linux when Node was installed with a system-owned npm prefix.\n\n" +
+        "Avoid `sudo npm`. Use Homebrew/nvm, or move npm's global prefix into your home directory:\n\n" +
+        "  mkdir -p ~/.npm-global\n" +
+        "  npm config set prefix ~/.npm-global\n" +
+        "  echo 'export PATH=\"$HOME/.npm-global/bin:$PATH\"' >> ~/.zshrc\n" +
+        "  source ~/.zshrc\n" +
+        "  npm install -g slidemind\n\n" +
+        `(details: ${installError})\n`,
+    );
+    return;
+  }
+
+  // --- 4. finish the session the user actually came for -------------------
+  // `ready` exits non-zero for every legitimate not-yet blocker (PowerPoint
+  // closed, no design activated). Setup already succeeded at that point, so its
+  // blocker is information, not a failure — run it for the message and the
+  // warmed bundle, and never inherit its exit code.
+  if (doReady) {
+    await spawnStatus(process.execPath, [__filename, "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
@@ -1890,6 +2855,7 @@ async function cmdReady(rest) {
   let asJson = false;
   let force = false;
   let connectOnly = false;
+  let brand = null;
   const positional = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
@@ -1902,12 +2868,18 @@ async function cmdReady(rest) {
       force = true;
     } else if (a === "--connect-only") {
       connectOnly = true;
+    } else if (a === "--brand") {
+      brand = rest[++i];
+      if (!brand) fail("--brand expects a design id (presFP)");
     } else if (a.startsWith("-")) {
       fail(`unknown flag: ${a}`);
     } else {
       positional.push(a);
     }
   }
+  if (brand && to) {
+    fail("--brand and --to are mutually exclusive (a design id or a window, not both)");
+  }
 
   // --- Local: resolve the deck dir (never create it) and read its existing
   // bundle ref. deckPresFP feeds ONLY the mirror tie-break + `suggested`; it
@@ -1954,10 +2926,20 @@ async function cmdReady(rest) {
     fail(blocker.message);
   };
 
-  // --- Local: not paired short-circuits before any network. ---
+  // --- First use: there is nothing this process can do on its own. Connecting
+  // starts in the add-in because the claim it mints carries the deployment's
+  // address, and an unconnected CLI has no way to learn which backend its user
+  // belongs to. So name the one action that works and stop. ---
   const cfg = await loadBridgeModule("config");
   if (cfg.readSessions().length === 0) {
-    finishBlocker({ blocker: connectionBlocker({ paired: false }) });
+    finishBlocker({
+      blocker: {
+        code: "not_connected",
+        actor: "user",
+        message:
+          "Connect this CLI first: in PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, copy the command it shows, and run it here.",
+      },
+    });
     return;
   }
 
@@ -1987,10 +2969,162 @@ async function cmdReady(rest) {
     return;
   }
 
+  // --- Backend authoring readiness beyond the connection itself: which
+  // environments serve the pane-free engine routes. Probed at most once (and
+  // only when a payload actually reports it), and never fatal — an add-in
+  // without them still authors, it just relays search through a window. ---
+  let engineInfo = null;
+  const engines = async () => {
+    if (!engineInfo) {
+      try {
+        engineInfo = await client.engineReachability({
+          backends: statusRaw.backends,
+        });
+      } catch {
+        engineInfo = { available: false, envs: [] };
+      }
+    }
+    return engineInfo;
+  };
+
+  // --- A design resolved WITHOUT a window — the deck's own binding, an
+  // explicit --brand, or the backend's brand list. Same payload either way:
+  // ready, `windowless: true`, and a pane status that is INFORMATIONAL. What
+  // the missing window actually costs depends on the engine routes: with them
+  // only push/insert-slide and reading an open presentation need PowerPoint.
+  //
+  // "Windowless" is about how the DESIGN was resolved, not about the registry:
+  // --brand runs before the registry is consulted at all, and the later rungs
+  // fire on "nothing render-ready", which a connected-but-still-matching window
+  // satisfies. So the pane status is DERIVED from the registry as it stands at
+  // call time (the hydration wait reassigns it), and the prose only claims
+  // "no PowerPoint window" when there genuinely is none. ---
+  const finishWindowless = async (result) => {
+    if (deckDir) {
+      bundle.writeDeckBundleRef(deckDir, {
+        presFP: result.presFP,
+        etag: result.etag,
+      });
+    }
+    const designName = readDesignName(result.dir);
+    const env = result.backendURL ? cfg.deriveEnvLabel(result.backendURL) : null;
+    const eng = await engines();
+    const paneReady = registry.some(client.isPaneReadyPresentation);
+    const noWindow = registry.length === 0;
+    const nextAction = noWindow
+      ? eng.available
+        ? "Ready (no PowerPoint window — authoring, engine search and build-pptx all work; only push/insert-slide and reading an open presentation need one)."
+        : "Ready (no PowerPoint window — build-pptx/build/review/view-draft work; push/search/read need a pane)."
+      : paneReady
+        ? "Ready (design resolved without targeting a window; a registered PowerPoint window is available for push/insert-slide)."
+        : eng.available
+          ? "Ready (design resolved without targeting a window; pane operations — push/insert-slide/read of a window — will wait for a pane click; engine search does not)."
+          : "Ready (design resolved without targeting a window; pane operations — push/search/read — will wait for a pane click).";
+    if (asJson) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            ready: true,
+            windowless: true,
+            deck: deckSlug,
+            bound: Boolean(deckDir),
+            env,
+            presId: null,
+            presFP: result.presFP,
+            designName,
+            bundleDir: result.dir,
+            bundleEtag: result.etag ?? null,
+            paneSuspended: !paneReady,
+            engines: eng,
+            warnings: result.warnings ?? [],
+            nextAction,
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+      return;
+    }
+    const designLabel = designName
+      ? `${designName} (${result.presFP})`
+      : result.presFP;
+    process.stdout.write(
+      `Ready — design ${designLabel}${env ? ` [${env}]` : ""}${noWindow ? " (no PowerPoint window)" : ""}\n`,
+    );
+    process.stdout.write(`  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`);
+    if (deckDir) process.stdout.write(`  deck ${deckSlug} bound\n`);
+    process.stdout.write(
+      noWindow
+        ? eng.available
+          ? "  Note: authoring, engine search and build-pptx need no window; push/insert-slide and reading an open presentation do.\n"
+          : "  Note: build-pptx/build/review/view-draft work without a window; push/search/read need a pane.\n"
+        : paneReady
+          ? "  Note: the design was resolved without targeting a window; a registered PowerPoint window is available for push/insert-slide.\n"
+          : eng.available
+            ? "  Note: pane operations (push/insert-slide/read of a window) will wait for a pane click; engine search does not.\n"
+            : "  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`);
+    }
+  };
+
+  // Materialize a design by id over the pane-free brand route. Returns null on
+  // any miss (old add-in, unknown/revoked design) so the caller can fall
+  // through to the window ladder instead of dead-ending.
+  const materializeBrand = async (brandId) => {
+    try {
+      return await bundle.materializeBundle(null, { force, brandId });
+    } catch {
+      return null;
+    }
+  };
+
+  // --- --brand <presFP>: the user (or the agent, after an ambiguous brand
+  // list) named the design outright. It resolves with or without a window, so
+  // it runs before the registry is consulted at all. ---
+  if (brand) {
+    const result = await materializeBrand(brand);
+    if (!result) {
+      finishBlocker({
+        blocker: {
+          code: "unknown_brand",
+          actor: "user",
+          message: `No connected slidemind add-in serves design '${brand}'. Run 'slidemind ready' with no --brand to see which designs are available.`,
+        },
+      });
+      return;
+    }
+    await finishWindowless(result);
+    return;
+  }
+
+  const isRR = client.isRenderReadyPresentation;
+
+  // --- Bound-deck ladder: session → bundle freshness, no pane precondition.
+  // The design identity (presFP == brandId) lives in the deck's
+  // .bundle-ref.json and the bundle syncs over the pane-free brand route, so
+  // with PowerPoint CLOSED (an empty registry) a bound deck readies straight
+  // away instead of sitting out the hydration wait for a window that isn't
+  // coming. A registry that holds windows still hydrates first — the open
+  // add-in stays the source of truth whenever there IS one. Skipped for
+  // --connect-only (which resolves no design at all) and for --to (an explicit
+  // window must resolve through the registry); a miss (old add-in, legacy ref,
+  // revoked grant) falls through to the window ladder. ---
+  const boundDeckLadder = deckDir && deckPresFP && !to && !connectOnly;
+  let boundRungTried = false;
+  if (boundDeckLadder && registry.length === 0) {
+    boundRungTried = true;
+    const result = await materializeBrand(deckPresFP);
+    if (result) {
+      await finishWindowless(result);
+      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) ||
@@ -2004,74 +3138,89 @@ async function cmdReady(rest) {
     }
   }
   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;
+    // --connect-only asks one question — "can I work?" — and since the engine
+    // routes answer off the session, a backend that serves them IS the answer:
+    // discovery, search and every per-result fetch run with PowerPoint closed.
+    // Without them search is still relayed through a pane, so the window rung
+    // below stands.
+    if (connectOnly && (await engines()).available) {
+      const eng = await engines();
+      if (asJson) {
+        process.stdout.write(
+          JSON.stringify(
+            {
+              ready: true,
+              connectOnly: true,
+              windowless: true,
+              engines: eng,
+              nextAction:
+                "Ready (no PowerPoint window — engine search runs off the connection; only insert-slide needs one).",
+              backends: (pub.backends ?? []).map((b) => ({ env: b.env, ok: b.ok })),
+            },
+            null,
+            2,
+          ) + "\n",
+        );
+      } else {
+        process.stdout.write(
+          `Connected. ${pub.backendCount} backend(s), 0 window(s) registered — ` +
+            `engine search runs without one [${eng.envs.join(", ")}].\n`,
+        );
+      }
+      return;
+    }
+    // The bound-deck ladder again, for the windows-registered-but-never-ready
+    // case the pre-poll rung deliberately left to the hydration wait.
+    if (boundDeckLadder && !boundRungTried) {
+      boundRungTried = true;
+      const result = await materializeBrand(deckPresFP);
+      if (result) {
+        await finishWindowless(result);
+        return;
+      }
+    }
+    // --- Unbound + no window: ask the backend which designs this user may
+    // build against. One is the answer; several genuinely need a human choice,
+    // which --brand records. A backend without the route (or a deck already
+    // bound to a design the brand route just refused) falls through unchanged. ---
+    if (!connectOnly && !to && !deckPresFP && !boundRungTried) {
+      let brands = [];
       try {
-        result = await bundle.materializeBundle(null, {
-          force,
-          brandId: deckPresFP,
-        });
+        brands = await client.listBrands();
       } catch {
-        /* fall through to the standard no_window / not_render_ready blocker */
+        /* no brand list — the window ladder below is the answer */
       }
-      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",
-          );
+      if (brands.length === 1) {
+        const result = await materializeBrand(brands[0].presFP);
+        if (result) {
+          await finishWindowless(result);
           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`,
+      } else if (brands.length > 1) {
+        const rows = brands.map(
+          (b) => `  ${b.presFP}${b.env ? `  [${b.env}]` : ""}  ${b.name ?? ""}`.trimEnd(),
         );
-        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`);
-        }
+        const blocker = {
+          code: "ambiguous_brand",
+          actor: "user",
+          message:
+            "Several corporate designs are available and no PowerPoint window says which — ask the user which to build against, then re-run: slidemind ready" +
+            `${deckSlug ? ` ${deckSlug}` : ""} --brand <presFP>.`,
+        };
+        finishBlocker({
+          blocker,
+          extras: {
+            brands: brands.map((b) => ({
+              presFP: b.presFP,
+              name: b.name ?? null,
+              env: b.env ?? null,
+            })),
+          },
+          humanLines:
+            "slidemind: several corporate designs are available — ask the user which to build against:\n" +
+            `${rows.join("\n")}\n` +
+            `Then re-run: slidemind ready${deckSlug ? ` ${deckSlug}` : ""} --brand <presFP>`,
+        });
         return;
       }
     }
@@ -2104,6 +3253,7 @@ async function cmdReady(rest) {
           {
             ready: true,
             connectOnly: true,
+            engines: await engines(),
             nextAction: "Ready.",
             backends: (pub.backends ?? []).map((b) => ({ env: b.env, ok: b.ok })),
           },
@@ -2227,6 +3377,7 @@ async function cmdReady(rest) {
 
   const designName = readDesignName(result.dir);
   const paneSuspended = !client.isPaneReadyPresentation(entry);
+  const engineInfoForWindow = await engines();
 
   if (asJson) {
     process.stdout.write(
@@ -2246,6 +3397,7 @@ async function cmdReady(rest) {
             fileName: entry.fileName ?? null,
           },
           paneSuspended,
+          engines: engineInfoForWindow,
           warnings: result.warnings ?? [],
           nextAction: "Ready.",
         },
@@ -2270,7 +3422,9 @@ async function cmdReady(rest) {
   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",
+      engineInfoForWindow.available
+        ? "  Note: pane operations (push/insert-slide/read of this window) will wait for a pane click; engine search does not.\n"
+        : "  Note: pane operations (push/search/read) will wait for a pane click.\n",
     );
   }
   for (const w of result.warnings ?? []) {
@@ -2289,11 +3443,14 @@ async function cmdDoctor(rest) {
   // still reaches the reader, as the `cli_update_required` rung of the ladder.
   client.setDiagnosticMode(true);
   if (sessions.length === 0) {
+    const blocker = backendBlocker({ paired: false });
     const pub = {
       paired: false,
       backendCount: 0,
       backends: [],
       presentations: [],
+      authoring: { ready: false, blocker, degraded: null, engines: null },
+      host: { ready: false, blocker: paneBlocker({ presentations: [] }) },
       nextAction: connectionNextAction({ paired: false }),
     };
     process[asJson ? "stdout" : "stderr"].write(
@@ -2301,7 +3458,30 @@ async function cmdDoctor(rest) {
     );
     return;
   }
-  const status = publicConnectionStatus(await client.connectionStatus(), client);
+  const statusRaw = await client.connectionStatus();
+  const status = publicConnectionStatus(statusRaw, client);
+  // The two ladders are INDEPENDENT: authoring (session → reachable backend →
+  // CLI version → engine reachability) is what render, bundle and the pane-free
+  // engine routes ride on, while the live-PowerPoint ladder only governs
+  // push/insert-slide and reading an open presentation. Reporting them
+  // separately is the point — a dead pane is not "cannot work".
+  const authoringBlocker = backendBlocker(status);
+  let engines = { available: false, envs: [] };
+  if (!authoringBlocker) {
+    try {
+      engines = await client.engineReachability({ backends: statusRaw.backends });
+    } catch {
+      /* leave it as unavailable — never fail a diagnosis on a probe */
+    }
+  }
+  status.authoring = {
+    ready: !authoringBlocker,
+    blocker: authoringBlocker,
+    degraded: permissionsStaleDegradation(status, client),
+    engines,
+  };
+  const hostBlocker = paneBlocker(status);
+  status.host = { ready: !hostBlocker, blocker: hostBlocker };
   status.nextAction = connectionNextAction(status);
   if (asJson) {
     process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
@@ -2315,6 +3495,32 @@ async function cmdDoctor(rest) {
         `\n`,
     );
   }
+  process.stdout.write(
+    `Backend authoring ready: ${status.authoring.ready ? "yes" : "no"}` +
+      `${status.authoring.ready ? "" : ` — ${authoringBlocker.message}`}\n`,
+  );
+  // One condition, one cause, named the same way everywhere: when the readiness
+  // capabilities already say the permission snapshot has aged out, this line
+  // says so too, instead of reporting a healthy pane-free surface that a corpus
+  // search is about to 403 on for a reason the user learns only then.
+  const staleEnvs = permissionsStaleEnvs(status);
+  process.stdout.write(
+    `  engine search (no window needed): ${
+      engines.available
+        ? `yes [${engines.envs.join(", ")}]` +
+          (staleEnvs.length
+            ? ` — corpus search degraded on ${staleEnvs.join(", ")}: stale permission snapshot`
+            : "")
+        : "no — relayed through an open pane"
+    }\n`,
+  );
+  if (status.authoring.degraded) {
+    process.stdout.write(`  degraded: ${status.authoring.degraded.message}\n`);
+  }
+  process.stdout.write(
+    `Live PowerPoint ready: ${status.host.ready ? "yes" : "no"}` +
+      `${status.host.ready ? "" : ` — ${hostBlocker.message}`}\n`,
+  );
   if (status.presentations.length === 0) {
     process.stdout.write("Open presentations: none\n");
   } else {
@@ -2456,93 +3662,23 @@ async function loadBridgeModule(name) {
   return import(pathToFileURL(path.join(SRC_DIR, "bridge", `${name}.mjs`)).href);
 }
 
-async function cmdPair(rest) {
-  let code = null;
-  let label = null;
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i];
-    if (a === "--label") {
-      label = rest[++i];
-      if (!label) fail("--label expects a name");
-    } else if (!a.startsWith("--") && !code) {
-      code = a;
-    }
-  }
-  if (!code) {
-    fail('usage: slidemind pair <code>   (copy the command from the add-in\'s "Connect CLI")');
-  }
-  const pairMod = await loadBridgeModule("pair");
-  const decoded = pairMod.decodePairingCode(code);
-  if (!decoded) {
-    fail("invalid pairing code — copy the exact `slidemind pair …` command shown in the add-in");
-  }
-  const res = await pairMod.httpJson(
-    "POST",
-    `${decoded.backendURL}/api/cli/pair/redeem`,
-    { body: { secret: decoded.secret } },
-  );
-  if (res.status !== 200 || !res.json?.sessionToken) {
-    fail(
-      `pairing failed (${res.status}): ${res.json?.error || "no session returned"}\n` +
-        "the code may have expired — generate a fresh one in the add-in's \"Connect CLI\"",
-    );
-  }
-  const cfg = await loadBridgeModule("config");
-  const sessions = cfg.upsertSession({
-    backendURL: decoded.backendURL,
-    sessionToken: res.json.sessionToken,
-    label,
-  });
-  const env = cfg.deriveEnvLabel(decoded.backendURL);
-  const others = sessions.length - 1;
-  const suffix =
-    others > 0
-      ? ` (${sessions.length} environments connected — commands now fan out across all of them)`
-      : "";
-  let verify = "";
-  try {
-    const client = await import(
-      pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
-    );
-    const deadline = Date.now() + 8000;
-    for (;;) {
-      const status = await client.connectionStatus();
-      if ((status.presentations ?? []).length > 0) {
-        verify = " Pane is registered.";
-        break;
-      }
-      if (Date.now() >= deadline) {
-        verify =
-          " No pane is registered yet; if PowerPoint is already open, reopen or click the slidemind task pane, then run 'slidemind doctor'.";
-        break;
-      }
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-    }
-  } catch {
-    // Pairing itself succeeded; diagnostics remain available via doctor.
-  }
-  process.stdout.write(
-    `Paired with ${label || env}${suffix}.${verify} Run 'slidemind doctor' to verify.\n`,
-  );
-}
-
 async function cmdWhoami() {
   const cfg = await loadBridgeModule("config");
   const sessions = cfg.readSessions();
   if (sessions.length === 0) {
     process.stderr.write(
-      'Not paired. Run `slidemind pair <code>` using the add-in\'s "Connect CLI".\n',
+      "Not connected. In PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, and run the command it shows.\n",
     );
     return;
   }
-  const pairMod = await loadBridgeModule("pair");
+  const { httpJson } = await loadBridgeModule("http-json");
   const def = cfg.getDefaultBackend();
   const lines = await Promise.all(
     sessions.map(async (s) => {
       const marker = s.backendURL === def ? "*" : " ";
       let detail;
       try {
-        const res = await pairMod.httpJson(
+        const res = await httpJson(
           "GET",
           `${s.backendURL}/api/cli/whoami`,
           { token: s.sessionToken },
@@ -2550,15 +3686,15 @@ async function cmdWhoami() {
         detail =
           res.status === 200 && res.json
             ? `user ${res.json.oid} · tenant ${res.json.tid ?? "(n/a)"}`
-            : `session invalid (${res.status}) — re-pair`;
+            : `session invalid (${res.status}) — authorize again`;
       } catch {
-        detail = "unreachable — check your connection or re-pair";
+        detail = "unreachable — check your connection or authorize again";
       }
       return `${marker} ${s.label}\n    ${detail}`;
     }),
   );
   process.stdout.write(
-    `Paired environments (${sessions.length}):\n${lines.join("\n")}\n`,
+    `Connected environments (${sessions.length}):\n${lines.join("\n")}\n`,
   );
 }
 
@@ -2593,10 +3729,10 @@ async function cmdLogout(rest) {
     toRemove = sessions.filter((s) => s.backendURL === def);
   }
 
-  const pairMod = await loadBridgeModule("pair");
+  const { httpJson } = await loadBridgeModule("http-json");
   for (const s of toRemove) {
     try {
-      await pairMod.httpJson("POST", `${s.backendURL}/api/cli/logout`, {
+      await httpJson("POST", `${s.backendURL}/api/cli/logout`, {
         token: s.sessionToken,
       });
     } catch {
@@ -2607,7 +3743,7 @@ async function cmdLogout(rest) {
   const remaining = cfg.readSessions().length;
   process.stdout.write(
     `Logged out of ${toRemove.map((s) => s.label).join(", ")}.` +
-      (remaining > 0 ? ` ${remaining} environment(s) still paired.\n` : "\n"),
+      (remaining > 0 ? ` ${remaining} environment(s) still connected.\n` : "\n"),
   );
 }
 
@@ -2785,20 +3921,56 @@ async function cmdNew(rest) {
   );
 }
 
-function parseTargetFlag(rest) {
+const HARNESS_TARGETS = ["claude", "codex", "opencode"];
+
+function parseTargetFlag(rest, { allowAuto = false } = {}) {
   const idx = rest.findIndex((a) => a === "--for" || a === "-f");
   if (idx < 0 || !rest[idx + 1]) {
-    fail("missing --for <claude|codex|opencode|all>");
+    fail(
+      `missing --for <claude|codex|opencode|all${allowAuto ? "|auto" : ""}>`,
+    );
   }
   const target = rest[idx + 1];
-  if (!["claude", "codex", "opencode", "all"].includes(target)) {
+  const allowed = allowAuto
+    ? [...HARNESS_TARGETS, "all", "auto"]
+    : [...HARNESS_TARGETS, "all"];
+  if (!allowed.includes(target)) {
     fail(`unknown install target: ${target}`);
   }
   return target;
 }
 
+// Which coding agents are actually on this machine, and which of them already
+// get their skills from a plugin. This is what lets `slidemind setup` finish the
+// job on its own: it deploys where a harness exists and stays out of the way
+// where a plugin already supplies the skills, so a separate `init` is no longer
+// part of onboarding.
+async function detectHarnesses() {
+  const found = [];
+  for (const target of HARNESS_TARGETS) {
+    const mod = await import(
+      pathToFileURL(path.join(INSTALLERS_DIR, `${target}.mjs`)).href
+    );
+    const info =
+      typeof mod.detect === "function"
+        ? mod.detect()
+        : { present: false, pluginInstalled: false, root: null };
+    found.push({ target, ...info });
+  }
+  return found;
+}
+
+/** Expand a `--for` value into the concrete harness list to act on. */
+async function resolveInstallTargets(target) {
+  if (target === "all") return [...HARNESS_TARGETS];
+  if (target !== "auto") return [target];
+  return (await detectHarnesses())
+    .filter((h) => h.present && !h.pluginInstalled)
+    .map((h) => h.target);
+}
+
 async function runInstaller(target, action, rest) {
-  const targets = target === "all" ? ["claude", "codex", "opencode"] : [target];
+  const targets = await resolveInstallTargets(target);
   for (const t of targets) {
     const mod = await import(
       pathToFileURL(path.join(INSTALLERS_DIR, `${t}.mjs`)).href
@@ -2812,6 +3984,7 @@ async function runInstaller(target, action, rest) {
       flags: rest,
     });
   }
+  return targets;
 }
 
 async function loadInstallerUi() {
@@ -2822,10 +3995,18 @@ async function loadInstallerUi() {
 }
 
 async function cmdInstall(rest) {
-  const target = parseTargetFlag(rest);
+  const target = parseTargetFlag(rest, { allowAuto: true });
   const ui = await loadInstallerUi();
   ui.banner(readPackageJson().version, "init");
-  await runInstaller(target, "install", rest);
+  const deployed = await runInstaller(target, "install", rest);
+  if (deployed.length === 0) {
+    ui.step({
+      status: "warn",
+      label: "harnesses",
+      value: "none detected",
+      note: "install a coding agent, then rerun with --for <claude|codex|opencode>",
+    });
+  }
 
   // Force every design bundle to re-download from the add-in on the next
   // build/push/download by wiping the materialized cache. init is the
@@ -2843,9 +4024,11 @@ async function cmdInstall(rest) {
   });
 
   ui.done(
-    target === "all"
-      ? "ready — ask your agent to plan, create, or edit a deck"
-      : `ready — ${target} can now plan, create, or edit decks`,
+    deployed.length === 0
+      ? "no coding agent found — the CLI is installed, skills are not"
+      : deployed.length === HARNESS_TARGETS.length
+        ? "ready — ask your agent to plan, create, or edit a deck"
+        : `ready — ${deployed.join(", ")} can now plan, create, or edit decks`,
   );
 }
 
@@ -2900,6 +4083,16 @@ function spawnInherit(file, args) {
   });
 }
 
+// Like spawnInherit, but resolves with the child's exit code instead of
+// rejecting — for a step whose failure is a message to the user rather than a
+// failure of the command that ran it (see `setup` → `ready`).
+function spawnStatus(file, args) {
+  return spawnInherit(file, args).then(
+    () => 0,
+    () => 1,
+  );
+}
+
 // ---------- distribution (public npm) ----------
 //
 // slidemind is published to public npm as `slidemind`. First install is
@@ -3040,6 +4233,9 @@ async function main(rawArgv) {
     case "build-pptx":
       await cmdBuildPptx(rest);
       return 0;
+    case "inspect-template-deck":
+      await cmdInspectTemplateDeck(rest);
+      return 0;
     case "view-draft":
       await cmdViewDraft(rest);
       return 0;
@@ -3052,6 +4248,9 @@ async function main(rawArgv) {
     case "view-slide":
       await cmdViewSlide(rest);
       return 0;
+    case "read-source":
+      await cmdReadSource(rest);
+      return 0;
     case "insert-slide":
       await cmdInsertSlide(rest);
       return 0;
@@ -3070,12 +4269,12 @@ async function main(rawArgv) {
     case "ready":
       await cmdReady(rest);
       return 0;
+    case "setup":
+      await cmdSetup(rest);
+      return 0;
     case "new":
       await cmdNew(rest);
       return 0;
-    case "pair":
-      await cmdPair(rest);
-      break;
     case "whoami":
       await cmdWhoami(rest);
       break;