slidemind 0.1.9 → 0.2.0

package/bin/slidemind.mjs

@@ -68,7 +68,7 @@ function printHelp() {
       `  slidemind review <deck>          Open a spatial preview review; blocks until the user\n` +
       `                                     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 (requires an open host)\n` +
+      `  slidemind build-pptx <deck>      Export native .pptx — via the add-in for compose decks (host), LOCALLY for template packs (host-free)\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --out <path>    output path (default <deck>/<deck>.pptx)\n` +
       `  slidemind view-draft <deck>      Render the deck's slides to per-slide PNGs (no push, no .pptx)\n` +
@@ -77,8 +77,10 @@ function printHelp() {
       `                                     --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 for images or slides (requires an open host)\n` +
-      `                                     --engine <id>   engine to search (default: first image engine; required for slides)\n` +
+      `  slidemind search "<query>"       Search an engine or scope for images or slides (requires 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` +
@@ -88,8 +90,8 @@ function printHelp() {
       `                                     --pick <n>      1-based selection number to view\n` +
       `                                     --to <presId>   the window the search ran on (required if >1 open)\n` +
       `                                     --out <dir>     output dir (default: a slidemind temp dir)\n` +
-      `  slidemind ls engines             List the live engine catalog for an active pane\n` +
-      `                                     --type <t>      collection | search\n` +
+      `  slidemind ls engines             List the live engine catalog + search scopes for an active pane\n` +
+      `                                     --type <t>      collection | search | scope\n` +
       `                                     --subtype <s>   image | slide | template | content\n` +
       `                                     --to <presId>   target a specific window/backend\n` +
       `                                     --all          include every paired backend\n` +
@@ -112,6 +114,12 @@ function printHelp() {
       `                                     --deck <deck>   deck to write the asset(s) into\n` +
       `                                     --to <presId>   the window the search ran on (required if >1 open)\n` +
       `                                     --icon-color <hex[,hex,..]>  bake a colour into SVG result(s) (one for all, or one per --pick)\n` +
+      `  slidemind 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` +
+      `                                     --out <name>    file name under assets/ (default imagen-N.png)\n` +
+      `                                     --size <s>      auto|1024x1024|1536x1024|1024x1536 (default auto)\n` +
+      `                                     --quality <q>   low|medium|high|auto\n` +
+      `                                     --brand-style   condition on the CD's reference samples\n` +
       `  slidemind download-bundle [deck] Materialize the active corporate design's bundle locally\n` +
       `                                     --to <presId>   target a specific window\n` +
       `                                     --force         re-download even if the cached bundle is current\n` +
@@ -306,6 +314,103 @@ function renderProgressPrinter() {
   };
 }
 
+// Generate one regular image via the paired add-in's image model and write it
+// into the deck's assets/. Pane-free: routes by the deck's bound design
+// (.bundle-ref.json), so it works with PowerPoint backgrounded or closed.
+async function cmdImagen(rest) {
+  let prompt = null;
+  let deck = null;
+  let outName = null;
+  let size = null;
+  let quality = null;
+  let brandStyle = false;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--deck") {
+      deck = rest[++i];
+      if (!deck) fail("--deck expects a deck");
+    } else if (a === "--out" || a === "-o") {
+      outName = rest[++i];
+      if (!outName) fail("--out expects a file name");
+    } else if (a === "--size") {
+      size = rest[++i];
+      if (!["auto", "1024x1024", "1536x1024", "1024x1536"].includes(size ?? "")) {
+        fail("--size expects auto|1024x1024|1536x1024|1024x1536");
+      }
+    } else if (a === "--quality") {
+      quality = rest[++i];
+      if (!["low", "medium", "high", "auto"].includes(quality ?? "")) {
+        fail("--quality expects low|medium|high|auto");
+      }
+    } else if (a === "--brand-style") {
+      brandStyle = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else if (prompt === null) {
+      prompt = a;
+    } else {
+      fail(`unexpected argument: ${a} (quote the prompt as one argument)`);
+    }
+  }
+  if (!prompt || !prompt.trim() || !deck) {
+    fail(
+      'usage: slidemind imagen "<prompt>" --deck <deck> [--out <name.png>] ' +
+        "[--size auto|1024x1024|1536x1024|1024x1536] [--quality low|medium|high|auto] [--brand-style]",
+    );
+  }
+  const deckDir = resolveDeckArg(deck);
+  const bundleMod = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  const ref = bundleMod.readDeckBundleRef(deckDir);
+  if (!ref?.presFP) {
+    fail(
+      `deck ${path.basename(deckDir)} is not bound to a design yet — run ` +
+        `'slidemind ready ${deck}' first (imagen routes by the deck's bound design).`,
+    );
+  }
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  process.stdout.write("  generating image (this can take a minute)…\n");
+  let result;
+  try {
+    result = await client.generateImageForBrand(ref.presFP, {
+      prompt,
+      size,
+      quality,
+      brandStyle,
+    });
+  } catch (err) {
+    if (err?.code === "imagen_route_unavailable") {
+      fail(
+        `${err.message}\n  The paired add-in does not offer image generation yet — ` +
+          `it ships with the next add-in update; until then add pictures to assets/ by hand ` +
+          `or via 'slidemind download-result'.`,
+      );
+    }
+    throw err;
+  }
+  const m = /^data:image\/(png|jpe?g);base64,(.+)$/.exec(result?.image ?? "");
+  if (!m) fail("backend returned no image data");
+  const ext = m[1] === "png" ? "png" : "jpeg";
+  const assetsDir = path.join(deckDir, "assets");
+  fs.mkdirSync(assetsDir, { recursive: true });
+  let file = outName;
+  if (!file) {
+    let n = 1;
+    while (fs.existsSync(path.join(assetsDir, `imagen-${n}.${ext}`))) n++;
+    file = `imagen-${n}.${ext}`;
+  }
+  const outPath = path.join(assetsDir, file);
+  fs.writeFileSync(outPath, Buffer.from(m[2], "base64"));
+  const styled = result.styleReferences > 0 ? ` (styled on ${result.styleReferences} brand sample(s))` : "";
+  process.stdout.write(
+    `Wrote ${path.relative(process.cwd(), outPath)}${styled}\n` +
+      `  Reference it from slide props as "assets/${file}" (e.g. summaryImage, illustration).\n`,
+  );
+}
+
 async function cmdBuildPptx(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "build-pptx");
   let to = null;
@@ -328,6 +433,57 @@ async function cmdBuildPptx(rest) {
   if (!fs.existsSync(path.join(deckDir, "slides"))) {
     fail(`expected 'slides/' folder in ${deckDir}`);
   }
+
+  // Template packs (mode: fill-template) build LOCALLY: the deck's slides are
+  // declarative fills over a template .pptx that ships in the pack, so no
+  // add-in render is involved and no PowerPoint host is needed. Compose decks
+  // take the bridge path below UNTOUCHED — the mode probe never throws, so a
+  // compose deck with an unmaterialized bundle still self-heals in the render.
+  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);
+    if (to) {
+      fail(
+        "--to targets a PowerPoint window, but fill-template decks build " +
+          "locally from the pack's template — drop --to (use 'slidemind push' " +
+          "to get slides into a window).",
+      );
+    }
+    // In-deck freeform slides (create-slides JSX next to the master-backed
+    // ones) render to sibling NN.pptx artifacts first — the only step that
+    // talks to the add-in; unchanged freeform slides keep the build offline.
+    const freeform = await import(
+      pathToFileURL(path.join(SRC_DIR, "pptx", "fill", "freeform.mjs")).href
+    );
+    const ff = await freeform.ensureFreeformRenders({
+      deckDir,
+      locale: skill.locale ?? "en",
+      srcDir: SRC_DIR,
+      onLog: (line) => process.stdout.write(`  ${line}\n`),
+    });
+    for (const w of ff.warnings) process.stderr.write(`  warning: ${w}\n`);
+
+    const engine = await import(
+      pathToFileURL(path.join(SRC_DIR, "pptx", "fill", "engine.mjs")).href
+    );
+    const result = await engine.buildFillTemplateDeck({
+      deckDir,
+      skill,
+      outPath,
+      onLog: (line) => process.stdout.write(`  ${line}\n`),
+    });
+    process.stdout.write(
+      `Wrote ${result.outPath} (${result.slideCount} slides) from template ` +
+        `'${skill.templateKey}' — host-free\n`,
+    );
+    for (const w of result.warnings ?? []) {
+      process.stderr.write(`  warning: ${w}\n`);
+    }
+    return;
+  }
+
   // The .pptx is rendered server-side by the add-in (one exporter, one truth).
   // A bound deck renders pane-free over the brand routes — no PowerPoint
   // window needed; unbound decks (or --to) resolve through the pane registry.
@@ -433,10 +589,96 @@ async function cmdViewDraft(rest) {
   }
 }
 
+// Turn the add-in's deliberately terse search failures into something actionable.
+// It withholds detail on purpose: the raw message used to carry the built OData
+// filter and physical index names, and "Engine not found" doubles as a permission
+// denial so engine existence stays undisclosed. So the CLI can't diagnose — it can
+// only name the next move.
+function searchFailureHint(error, engineId) {
+  const raw = error ?? "unknown error";
+  if (/engine not found/i.test(raw)) {
+    return (
+      `${raw} — '${engineId}' is unknown or not visible to you. ` +
+      `Re-run 'slidemind ls engines' (ids can be retired) and pick from the live list, ` +
+      `or search 'scope:all' to skip engines entirely.`
+    );
+  }
+  if (/^search failed$/i.test(raw)) {
+    return (
+      `${raw} — the add-in withholds the reason (it can leak index internals); ` +
+      `the detail is in the add-in's logs. Retry once, then try 'scope:all'.`
+    );
+  }
+  return raw;
+}
+
+// Zero results is now a routine, ambiguous outcome: the add-in answers "success,
+// nothing" for a corpus that isn't connected, one that is still embedding, and a
+// folder filter that matches nothing — all indistinguishable on the wire. Say that
+// instead of letting an empty list read as "this content does not exist".
+function writeEmptySearchDiagnostic(engineId, bundleMod) {
+  const isScope = bundleMod.isSearchScopeId(engineId);
+  const lines = [
+    `  No results — this does NOT mean the content doesn't exist. Any of these looks identical here:`,
+    `    · nothing is connected yet, so there is no corpus to search`,
+    `    · the corpus is still indexing (content appears progressively)`,
+  ];
+  if (!isScope) {
+    lines.push(
+      `    · this engine is a saved FOLDER FILTER and the content sits outside it`,
+    );
+  }
+  lines.push(`  Next:`);
+  if (!isScope) {
+    lines.push(
+      `    · widen to the unfiltered corpus: slidemind search "<query>" --engine ${bundleMod.SCOPE_ALL} --result-type slide`,
+    );
+  }
+  lines.push(
+    `    · re-word the query (content search matches phrasing, so a synonym can decide a hit)`,
+    `    · slidemind ls engines — see every engine and scope you can reach`,
+  );
+  if (isScope) {
+    lines.push(
+      `    · if the unfiltered corpus is also empty, report it as "not found" and name what you searched — don't author a replacement as if reuse had been tried`,
+    );
+  }
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+// Write the search's numbered collage to a file and tell the agent to look at it.
+//
+// The add-in composes ONE bounded 800x600 image showing every candidate with its
+// selection number burned in — the same picture the in-app agent sees. That is the
+// intended way to choose a visual result: one look at one file, rather than N
+// per-result previews (which is also why the relay ack carries no per-result bytes
+// — a corpus image is multi-megabyte and N of them can't cross the relay).
+//
+// Best-effort by design: a missing/…unparseable grid must never fail a search that
+// otherwise returned usable results. Content-intent searches have no grid at all —
+// their signal is the printed text.
+function writeSearchGrid(gridDataUri, searchId, resolveExt) {
+  if (typeof gridDataUri !== "string" || !gridDataUri.startsWith("data:")) {
+    return null;
+  }
+  try {
+    const m = /^data:([^;]+);base64,(.+)$/.exec(gridDataUri);
+    if (!m) return null;
+    const bytes = Buffer.from(m[2], "base64");
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-grid-"));
+    const target = path.join(dir, `grid-${searchId}.${resolveExt(m[1], bytes)}`);
+    fs.writeFileSync(target, bytes);
+    return target;
+  } catch {
+    return null;
+  }
+}
+
 async function cmdSearch(rest) {
   let asJson = false;
   let to = null;
   let engineId = null;
+  let resultType = null;
   let intent = null;
   let top = null;
   const queryParts = [];
@@ -450,6 +692,12 @@ async function cmdSearch(rest) {
     } else if (a === "--engine" || a === "-e" || a === "--engineId") {
       engineId = rest[++i];
       if (!engineId) fail("--engine expects an engineId");
+    } else if (a === "--result-type" || a === "--resultType") {
+      resultType = rest[++i];
+      if (!resultType) fail("--result-type expects slide|image");
+      if (!["slide", "image"].includes(resultType)) {
+        fail(`--result-type expects slide|image, got '${resultType}'`);
+      }
     } else if (a === "--intent") {
       intent = rest[++i];
       if (!intent) fail("--intent expects auto|content|visual");
@@ -472,7 +720,7 @@ async function cmdSearch(rest) {
   const query = queryParts.join(" ").trim();
   if (!query) {
     fail(
-      `usage: slidemind search "<query>" [--engine <id>] [--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>] [--to <presId>] [--json]`,
     );
   }
 
@@ -484,6 +732,9 @@ async function cmdSearch(rest) {
   const bundle = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
   );
+  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
@@ -493,42 +744,64 @@ async function cmdSearch(rest) {
   const presId = entry.presId;
   const backendURL = entry.backendURL ?? null;
 
-  // Slide search needs an explicit engine — the bundle's image-engine default
-  // only applies to image/visual intent. content/visual on a slide engine is
-  // the caller's choice via --engine.
+  // An explicit content/visual intent means "search slides", not imagery.
   const slideIntent = intent === "content" || intent === "visual";
   // Thread the engine subtype on the wire whenever the CLI can determine it:
   //   - the pickImageEngine default branch is, by construction, an image engine;
-  //   - an explicit slide intent (--intent content|visual) targets a slide
-  //     engine.
+  //   - an explicit slide intent (--intent content|visual) targets slides.
   // This is belt-and-suspenders for an add-in regression where a missing
   // subtype no longer defaulted to "image"; when the subtype is unknown we omit
   // it and let the add-in resolve it from the snapshot.
   let subtype = slideIntent ? "slide" : null;
   if (!engineId) {
     if (slideIntent) {
-      fail(
-        "slide search requires --engine <id>. Run 'slidemind ls engines --type search --subtype slide' to find one.",
-      );
-    }
-    const mat = await bundle.materializeBundle(presId, { backendURL });
-    let pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
-    if (!pick) {
-      // New backends no longer ship engines[] on the bundle wire — discovery
-      // is live-only. Fall back to the catalog the add-in's own design agent
-      // uses (its list_engines tool ≙ `slidemind ls engines`).
+      // Slide search with no engine named: search the corpus UNFILTERED rather
+      // than refusing. An engine is a saved folder filter over the add-in's
+      // shared corpus, so a workspace can hold a full corpus and zero slide
+      // engines — demanding --engine here dead-ended exactly that case.
+      engineId = bundle.SCOPE_ALL;
+      resultType = resultType ?? "slide";
+    } else {
+      // Imagery: resolve a real image engine (a scope is not a brand image
+      // source). Ask the LIVE catalog first — the same one the add-in's own
+      // design agent reads — and fall back to the materialized bundle only when
+      // the host can't answer. Bundle-first would be stale: engine ids can be
+      // retired server-side, and a dead id surfaces as "Engine not found".
       const live = await client
         .listEngines({ subtype: "image", backendURL })
         .catch(() => ({ engines: [] }));
-      pick = bundle.pickImageEngine(live.engines);
-    }
-    if (!pick) {
-      fail(
-        "This corporate design has no image engines to search. Run 'slidemind ls engines' to see what exists, or ask the add-in owner to wire an image/icon engine.",
-      );
+      let pick = bundle.pickImageEngine(live.engines);
+      if (!pick) {
+        // 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);
+        if (mat) pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
+      }
+      if (!pick) {
+        fail(
+          "This corporate design has no image engines to search. Run 'slidemind ls engines' to see what exists, or ask the add-in owner to wire an image/icon engine.",
+        );
+      }
+      engineId = pick.id;
+      subtype = "image";
     }
-    engineId = pick.id;
-    subtype = "image";
+  }
+
+  // A scope has no subtype of its own, so the index must be named explicitly —
+  // the add-in rejects a scope search without it. Default to slides: reusing an
+  // existing slide is what an unfiltered corpus search is overwhelmingly for.
+  if (bundle.isSearchScopeId(engineId)) {
+    resultType = resultType ?? "slide";
+    subtype = resultType;
+  } else if (resultType) {
+    // Harmless but meaningless on an engine, whose own subtype is authoritative.
+    process.stderr.write(
+      `note: --result-type is ignored for engine '${engineId}' (it applies to scope:* targets); the engine's own type decides.\n`,
+    );
+    resultType = null;
   }
 
   // Window-agnostic: tries the picked pane, then fails over to any other live
@@ -540,6 +813,7 @@ async function cmdSearch(rest) {
     engineId,
     query,
     subtype,
+    resultType,
     intent: intent ?? null,
     top: top ?? null,
   });
@@ -550,7 +824,7 @@ async function cmdSearch(rest) {
     return;
   }
   if (!res?.ok) {
-    process.stderr.write(`search failed: ${res?.error ?? "unknown error"}\n`);
+    process.stderr.write(`search failed: ${searchFailureHint(res?.error, engineId)}\n`);
     return;
   }
   // Prefer the new `results` array (image + slide engines); fall back to the
@@ -559,11 +833,18 @@ async function cmdSearch(rest) {
     ? res.results
     : (res.thumbnails ?? []).map((t, i) => ({ selection: i + 1, title: t.title }));
   const count = res.resultCount ?? results.length;
+  const targetLabel = bundle.isSearchScopeId(engineId)
+    ? `scope ${engineId}`
+    : `engine ${engineId}`;
   process.stdout.write(
-    `searchId ${res.searchId} — ${count} result(s) from engine ${engineId}` +
+    `searchId ${res.searchId} — ${count} result(s) from ${targetLabel}` +
       (res.intent ? ` (${res.intent})` : "") +
       `\n`,
   );
+  if (count === 0) {
+    writeEmptySearchDiagnostic(engineId, bundle);
+    return;
+  }
   const isContent = res.intent === "content";
   results.forEach((r, i) => {
     const sel = r.selection ?? i + 1;
@@ -577,10 +858,27 @@ async function cmdSearch(rest) {
         }
       }
     } else {
-      // Visual / image results: the numbered list.
-      process.stdout.write(`  ${sel}. ${r.title ?? "(untitled)"}\n`);
+      // Visual / image results: the numbered list. An image result carries its
+      // intrinsic size from the engine index — show it, so the box can be sized
+      // to the real aspect ratio at authoring time rather than after the fetch.
+      const dims =
+        r.kind === "image" && Number.isFinite(r.width) && Number.isFinite(r.height)
+          ? `  ${r.width}×${r.height}`
+          : "";
+      process.stdout.write(`  ${sel}. ${r.title ?? "(untitled)"}${dims}\n`);
     }
   });
+  // Visual results: point at the ONE collage rather than making the caller pull
+  // each preview separately. The numbers burned into it match the list above.
+  if (!isContent) {
+    const gridPath = writeSearchGrid(res.gridDataUri, res.searchId, resolveAssetExt);
+    if (gridPath) {
+      process.stdout.write(
+        `Contact sheet of all ${count} result(s) — LOOK AT THIS FILE to choose, ` +
+          `don't fetch previews one by one: ${gridPath}\n`,
+      );
+    }
+  }
   // Tailor the next-step hint to the result kind: slide verbs (insert-slide /
   // add-slide) for slide results, the image-download hint otherwise. The result
   // subtype is authoritative; fall back to a per-result `kind` for older
@@ -609,7 +907,7 @@ async function cmdSearch(rest) {
 async function cmdLs(rest) {
   const [sub, ...subRest] = rest;
   if (sub !== "engines") {
-    fail("usage: slidemind ls engines [--type collection|search] [--subtype image|slide|template|content] [--json]");
+    fail("usage: slidemind ls engines [--type collection|search|scope] [--subtype image|slide|template|content] [--json]");
   }
   let type = null;
   let subtype = null;
@@ -620,9 +918,10 @@ async function cmdLs(rest) {
     const a = subRest[i];
     if (a === "--type") {
       type = subRest[++i];
-      if (!type) fail("--type expects collection|search");
-      if (!["collection", "search"].includes(type)) {
-        fail(`--type expects collection|search, got '${type}'`);
+      if (!type) fail("--type expects collection|search|scope");
+      // "scope" narrows to the non-engine targets (scope:all / scope:sharepoint).
+      if (!["collection", "search", "scope"].includes(type)) {
+        fail(`--type expects collection|search|scope, got '${type}'`);
       }
     } else if (a === "--subtype") {
       subtype = subRest[++i];
@@ -659,7 +958,18 @@ async function cmdLs(rest) {
     return;
   }
   if (engines.length === 0) {
-    process.stderr.write("No engines available for the active corporate design.\n");
+    // 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.
+    const { SCOPE_ALL } = await import(
+      pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+    );
+    process.stderr.write(
+      "No engines or scopes matched. An engine is a saved folder filter over the corpus, " +
+        "so an empty list does NOT mean there is nothing to search — try " +
+        `'slidemind search "<query>" --engine ${SCOPE_ALL} --result-type slide' ` +
+        "to search it unfiltered.\n",
+    );
     return;
   }
   // Show the env tag only when more than one environment contributed engines.
@@ -668,7 +978,15 @@ async function cmdLs(rest) {
     const kind = [e.type, e.subtype].filter(Boolean).join("/");
     const env = multiEnv && e.env ? `[${e.env}] ` : "";
     const desc = e.description ? ` — ${e.description}` : "";
-    process.stdout.write(`${env}${e.id} · ${e.label ?? e.id} · ${kind}${desc}\n`);
+    // A scope takes --result-type instead of having a subtype of its own; spell
+    // that out so the agent doesn't have to infer it from the missing subtype.
+    const hint =
+      e.type === "scope"
+        ? ` (needs --result-type ${(e.capabilities?.resultTypes ?? ["slide", "image"]).join("|")})`
+        : "";
+    process.stdout.write(
+      `${env}${e.id} · ${e.label ?? e.id} · ${kind}${hint}${desc}\n`,
+    );
   }
 }
 
@@ -867,18 +1185,61 @@ async function cmdAddSlide(rest) {
   const reused = await import(
     pathToFileURL(path.join(SRC_DIR, "lib", "reused-slides.mjs")).href
   );
+  const { createTransferProgress } = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
+  );
+  // Stream each pick to a provisional file: the play-order filename can only be
+  // computed once every pick is in hand, and buffering a multi-megabyte slide in
+  // memory just to name it would defeat the streaming path.
   const extracted = [];
-  for (const pick of picks) {
-    const res = await client.extractSlide({
-      presId,
-      searchId,
-      selection: pick,
-      backendURL,
-    });
-    if (!res?.ok || !res.base64) {
-      fail(`add-slide failed for selection ${pick}: ${res?.error ?? "no slide bytes returned"}`);
+  const cleanupTemps = () => {
+    for (const s of extracted) {
+      if (s.tempPath) fs.rmSync(s.tempPath, { force: true });
     }
-    extracted.push({ selection: pick, slideId: res.slideId ?? null, base64: res.base64 });
+  };
+  try {
+    for (const pick of picks) {
+      const tempPath = path.join(slidesDir, `.reused-${searchId}-${pick}.part`);
+      if (typeof client.extractSlideToFile === "function") {
+        try {
+          const res = await client.extractSlideToFile({
+            presId,
+            searchId,
+            selection: pick,
+            destPath: tempPath,
+            backendURL,
+            onProgress: createTransferProgress(`extracting slide ${pick}`),
+          });
+          if (!res?.bytesWritten) throw new Error("stream produced no bytes");
+          extracted.push({ selection: pick, slideId: res.slideId ?? null, tempPath });
+          continue;
+        } catch (err) {
+          fs.rmSync(tempPath, { force: true });
+          // Route absent (bodyless 404 / 501) → this add-in predates the streaming
+          // route; fall through to the capped base64 ack path below.
+          const routeMissing =
+            (err?.status === 404 && !err?.code) || err?.status === 501;
+          if (!routeMissing) {
+            cleanupTemps();
+            fail(`add-slide failed for selection ${pick}: ${err.message}`);
+          }
+        }
+      }
+      const res = await client.extractSlide({
+        presId,
+        searchId,
+        selection: pick,
+        backendURL,
+      });
+      if (!res?.ok || !res.base64) {
+        cleanupTemps();
+        fail(`add-slide failed for selection ${pick}: ${res?.error ?? "no slide bytes returned"}`);
+      }
+      extracted.push({ selection: pick, slideId: res.slideId ?? null, base64: res.base64 });
+    }
+  } catch (err) {
+    cleanupTemps();
+    throw err;
   }
   const existing = fs
     .readdirSync(slidesDir)
@@ -887,7 +1248,11 @@ async function cmdAddSlide(rest) {
   const written = [];
   extracted.forEach((slide, i) => {
     const target = path.join(slidesDir, targets[i].filename);
-    fs.writeFileSync(target, Buffer.from(slide.base64, "base64"));
+    if (slide.tempPath) {
+      fs.renameSync(slide.tempPath, target);
+    } else {
+      fs.writeFileSync(target, Buffer.from(slide.base64, "base64"));
+    }
     written.push(path.relative(process.cwd(), target));
   });
   process.stdout.write(
@@ -957,7 +1322,7 @@ async function cmdViewSlide(rest) {
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
-  const { extFromMime } = await import(
+  const { resolveAssetExt } = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
   );
   const registry = await client.requirePaneHost();
@@ -979,8 +1344,15 @@ async function cmdViewSlide(rest) {
     ? path.resolve(process.cwd(), outDir)
     : fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-view-"));
   fs.mkdirSync(dir, { recursive: true });
-  const target = path.join(dir, `slide-${searchId}-${pick}.${extFromMime(m[1])}`);
-  fs.writeFileSync(target, Buffer.from(m[2], "base64"));
+  // Extension from the BYTES, not the declared MIME — engines inherit a
+  // Content-Type from upstream and it is demonstrably wrong for some corpus
+  // images (PNG served as image/jpeg).
+  const bytes = Buffer.from(m[2], "base64");
+  const target = path.join(
+    dir,
+    `slide-${searchId}-${pick}.${resolveAssetExt(m[1], bytes)}`,
+  );
+  fs.writeFileSync(target, bytes);
   process.stdout.write(
     `Wrote preview of result ${pick} (searchId ${searchId}) to ${target}\n`,
   );
@@ -1058,7 +1430,11 @@ async function cmdDownloadResult(rest) {
       ? r.value
       : { selection: picks[i], error: r.reason?.message ?? String(r.reason) },
   );
+  const { formatSize } = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "image-dimensions.mjs")).href
+  );
   let ok = 0;
+  let anySized = false;
   const lines = [];
   for (const r of results) {
     if (r.error) {
@@ -1067,12 +1443,21 @@ async function cmdDownloadResult(rest) {
     }
     ok++;
     const note = r.recolor?.note ? ` — ${r.recolor.note}` : "";
-    lines.push(`  ${r.reference}  (${r.recolor?.mode ?? "?"})${note}`);
+    // The intrinsic size is the agent's only handle on the asset's aspect
+    // ratio — without it the <img> box is a guess and the render stretches.
+    const dims = formatSize(r.size);
+    anySized ||= Boolean(dims);
+    const size = dims ? `  ${dims}` : "  (size unknown)";
+    lines.push(`  ${r.reference}${size}  (${r.recolor?.mode ?? "?"})${note}`);
   }
   process.stdout.write(
     `Downloaded ${ok}/${results.length} result(s) into ${path.relative(process.cwd(), assetsDir)}:\n` +
       lines.join("\n") +
-      `\nReference each from slide JSX as <img src="./assets/...">.\n`,
+      `\nReference each from slide JSX as <img src="./assets/...">.\n` +
+      (anySized
+        ? `Sizes above are the assets' intrinsic width×height — give each <img> a box ` +
+          `with that aspect ratio, or the render stretches it to whatever box you wrote.\n`
+        : ""),
   );
   if (ok === 0) process.exit(1);
 }
@@ -1561,6 +1946,10 @@ async function cmdReady(rest) {
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
+  // Same opt-out as doctor: `ready` OWNS the cli_update_required blocker (it is
+  // terminal, `actor: "agent"`, with the update command as its nextAction), so
+  // the raw header throw would only replace a structured answer with a worse one.
+  client.setDiagnosticMode(true);
 
   // --- Network (one parallel round): readiness ladder + the merged registry. ---
   const [statusRaw, detailed] = await Promise.all([
@@ -1878,6 +2267,9 @@ async function cmdDoctor(rest) {
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
+  // doctor diagnoses skew — it must never be killed BY skew. The version floor
+  // still reaches the reader, as the `cli_update_required` rung of the ladder.
+  client.setDiagnosticMode(true);
   if (sessions.length === 0) {
     const pub = {
       paired: false,
@@ -2610,6 +3002,9 @@ async function main(rawArgv) {
     case "review":
       await cmdReview(rest);
       return 0;
+    case "imagen":
+      await cmdImagen(rest);
+      break;
     case "build-pptx":
       await cmdBuildPptx(rest);
       return 0;