slidemind 0.1.8 → 0.2.0

package/bin/slidemind.mjs

@@ -60,11 +60,15 @@ function printHelp() {
       `                                     as a markdown editor + live preview + overall feedback box,\n` +
       `                                     blocks until the user decides, prints DECISION: approved | comments\n` +
       `                                     --port <n>          bind a fixed port (default: ephemeral)\n` +
+      `  slidemind 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` +
+      `                                     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` +
       `  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` +
@@ -73,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` +
@@ -84,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` +
@@ -95,11 +101,12 @@ function printHelp() {
       `                                     --pick <n,..>   1-based selection number(s)\n` +
       `                                     --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 search results into a deck as native .pptx\n` +
-      `                                     --search <id>   searchId from 'slidemind search'\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` +
+      `                                     --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)\n` +
+      `                                     --to <presId>   target the window the search ran on (required if >1 open; 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` +
       `                                     --search <id>   searchId from 'slidemind search'\n` +
@@ -107,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` +
@@ -114,7 +127,8 @@ function printHelp() {
       `                                     --all          include retained suspended entries\n` +
       `  slidemind doctor                 Diagnose CLI/add-in pairing, backend, and pane readiness\n` +
       `                                     --json          print machine-readable status\n` +
-      `  slidemind read [presId]          Pull the current content of an open presentation (requires a host)\n` +
+      `  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` +
       `                                     --mode <m>      summary | raw (default: raw)\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --json          print the raw content payload\n` +
@@ -149,6 +163,15 @@ function fail(msg, code = 1) {
   process.exit(code);
 }
 
+// The local PowerPoint files `read` and `add-slide --from` accept host-free.
+// All are OPC (zip) OOXML packages with the same ppt/presentation.xml +
+// ppt/slides/ structure — presentation (.pptx/.pptm), template (.potx/.potm),
+// slideshow (.ppsx/.ppsm) — so the src/pptx/ reader/swapper handle them
+// identically. Presentation IDs are opaque and never carry these extensions,
+// so this stays a safe discriminator for "positional is a local file, not a
+// presId".
+const LOCAL_PPTX_RE = /\.(pptx|pptm|potx|potm|ppsx|ppsm)$/i;
+
 function resolveDecksDir() {
   if (process.env.SLIDEMIND_DECKS) {
     return path.resolve(process.env.SLIDEMIND_DECKS);
@@ -168,12 +191,25 @@ function resolveDeckArg(arg) {
   return path.join(decksDir, arg);
 }
 
-// Best-effort human name of a materialized design: the first `# ` heading in
-// the bundle's design.md, with the add-in's trailing " — design rules" suffix
-// stripped. Returns null on any failure (missing file, no heading) so callers
-// fall back to the raw presFP. Shared by `ready` and `new`'s auto-bind.
+// Best-effort human name of a materialized design. Prefers the live `name`
+// the wire carries (persisted into bundle.json by materializeBundle) — the
+// owner-set brand name, which survives renames. Falls back to the first `# `
+// heading in design.md (frozen at authoring time, so it may still show the
+// original auto codename), with the " — design rules" suffix stripped.
+// Returns null on any failure so callers fall back to the raw presFP.
+// Shared by `ready` and `new`'s auto-bind.
 function readDesignName(bundleDir) {
   if (!bundleDir) return null;
+  try {
+    const meta = JSON.parse(
+      fs.readFileSync(path.join(bundleDir, "bundle.json"), "utf8"),
+    );
+    if (typeof meta.name === "string" && meta.name.trim()) {
+      return meta.name.trim();
+    }
+  } catch {
+    /* no meta or unreadable — fall through to the design.md heading */
+  }
   try {
     const md = fs.readFileSync(path.join(bundleDir, "design.md"), "utf8");
     for (const raw of md.split("\n")) {
@@ -278,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;
@@ -300,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.
@@ -405,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 = [];
@@ -422,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");
@@ -444,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]`,
     );
   }
 
@@ -456,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
@@ -465,33 +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 });
-    const pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
-    if (!pick) {
-      fail(
-        "This corporate design has no brand engines to search. Ask the add-in owner to wire an image/icon engine.",
-      );
+      // 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: [] }));
+      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
@@ -503,6 +813,7 @@ async function cmdSearch(rest) {
     engineId,
     query,
     subtype,
+    resultType,
     intent: intent ?? null,
     top: top ?? null,
   });
@@ -513,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
@@ -522,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;
@@ -540,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
@@ -572,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;
@@ -583,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];
@@ -622,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.
@@ -631,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`,
+    );
   }
 }
 
@@ -713,6 +1068,7 @@ async function cmdAddSlide(rest) {
   let deck = null;
   let at = null;
   let to = null;
+  let from = null;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--search") {
@@ -720,6 +1076,9 @@ async function cmdAddSlide(rest) {
       const n = parseInt(next, 10);
       if (!Number.isFinite(n)) fail(`--search expects a searchId, got '${next}'`);
       searchId = n;
+    } else if (a === "--from") {
+      from = rest[++i];
+      if (!from) fail("--from expects a path to a .pptx file");
     } else if (a === "--pick") {
       picks = parsePicks(rest[++i]);
     } else if (a === "--deck") {
@@ -741,8 +1100,69 @@ async function cmdAddSlide(rest) {
       fail(`unexpected argument: ${a}`);
     }
   }
+
+  // Host-free local source: fold picked slides from a .pptx on disk (no bridge
+  // client, no requirePaneHost). Mutually exclusive with --search; --to is
+  // accepted-but-ignored here (symmetric with the other reuse commands — there's
+  // no window to target when the source is a local file).
+  if (from !== null) {
+    if (searchId !== null) fail("--from and --search are mutually exclusive");
+    if (!picks || !deck) {
+      fail("usage: slidemind add-slide --from <file.pptx> --pick <n[,n,...]> --deck <deck> [--at <N>]");
+    }
+    const fromPath = path.isAbsolute(from)
+      ? from
+      : path.resolve(process.cwd(), from);
+    let st = null;
+    try {
+      st = fs.statSync(fromPath);
+    } catch {
+      st = null;
+    }
+    if (!st || !st.isFile() || !LOCAL_PPTX_RE.test(fromPath)) {
+      fail(`--from: '${from}' is not an existing PowerPoint file (.pptx/.pptm/.potx/.potm/.ppsx/.ppsm)`);
+    }
+    const deckDir = resolveDeckArg(deck);
+    const slidesDir = path.join(deckDir, "slides");
+    fs.mkdirSync(slidesDir, { recursive: true });
+
+    const { foldPickedSlides } = await import(
+      pathToFileURL(path.join(SRC_DIR, "pptx", "slide-swap.mjs")).href
+    );
+    let results;
+    try {
+      results = foldPickedSlides(fs.readFileSync(fromPath), picks, {
+        sourceName: path.basename(fromPath),
+      });
+    } catch (err) {
+      fail(`add-slide failed: ${err.message}`);
+    }
+
+    // Same filename math + write loop as the --search branch; results already
+    // carry a `.slideId` and `.bytes` (a Uint8Array of a one-slide package).
+    const reused = await import(
+      pathToFileURL(path.join(SRC_DIR, "lib", "reused-slides.mjs")).href
+    );
+    const existing = fs
+      .readdirSync(slidesDir)
+      .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"));
+    const targets = reused.reusedSlideTargets(existing, results, at);
+    const written = [];
+    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));
+    });
+    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> --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>]");
   }
   const deckDir = resolveDeckArg(deck);
   const slidesDir = path.join(deckDir, "slides");
@@ -765,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)
@@ -785,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(
@@ -855,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();
@@ -877,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`,
   );
@@ -956,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) {
@@ -965,16 +1443,197 @@ 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);
 }
 
+// Strip the `data:<mime>;base64,` prefix off a data URI and return the raw
+// base64 payload (or null when the URI isn't a base64 data URI we can decode).
+function base64FromDataUri(dataUri) {
+  if (typeof dataUri !== "string") return null;
+  const m = /^data:[^;,]*;base64,(.*)$/s.exec(dataUri.trim());
+  return m ? m[1] : null;
+}
+
+async function cmdConceptImages(rest) {
+  let deck = null;
+  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 name or path");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else if (deck === null) {
+      deck = a;
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (!deck) fail("usage: slidemind concepts <deck>");
+
+  const deckDir = resolveDeckArg(deck);
+  const planPath = path.join(deckDir, "plan.md");
+  if (!fs.existsSync(planPath)) {
+    fail(
+      `no plan.md in ${path.relative(process.cwd(), deckDir) || deckDir}. ` +
+        `Run \`slidemind plan ${deck}\` to compose and sign off a plan first.`,
+    );
+  }
+  const planMarkdown = fs.readFileSync(planPath, "utf8");
+
+  const bundle = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  const brandId = bundle.readDeckBundleRef(deckDir)?.presFP ?? null;
+  if (!brandId) {
+    fail(
+      `deck ${deck} is not bound to a corporate design (no .bundle-ref.json). ` +
+        `Run \`slidemind ready ${deck}\` to bind it first.`,
+    );
+  }
+
+  // Plan sign-off is advisory here, not a hard gate: warn but proceed if the
+  // plan wasn't approved, so an agent can still fetch mockups while iterating.
+  const plan = await import(
+    pathToFileURL(path.join(BUILDERS_DIR, "plan.mjs")).href
+  );
+  const planState = plan.loadPlanState(deckDir);
+  if (planState?.decision !== "approved") {
+    process.stderr.write(
+      `slidemind: note — ${deck}'s plan is not signed off yet ` +
+        `(run \`slidemind plan ${deck}\`); generating concept mockups from the current plan.md anyway.\n`,
+    );
+  }
+
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+
+  const skipNote = () => {
+    process.stdout.write(
+      "no concept mockups generated — continuing without " +
+        "(this add-in doesn't generate concept mockups; author from the storyboards).\n",
+    );
+    process.exit(0);
+  };
+
+  // First request learns slideCount (and pins the serving backend for the rest).
+  let first;
+  try {
+    first = await client.generateConceptImagesForBrand(brandId, {
+      planMarkdown,
+      slideNumbers: [1],
+    });
+  } catch (err) {
+    if (err?.code === "concept_route_unavailable") skipNote();
+    throw err;
+  }
+
+  const backendURL = first.backendURL ?? null;
+  const slideCount = Number.isFinite(first.slideCount) ? first.slideCount : 0;
+  const images = [];
+  const collect = (res) => {
+    if (Array.isArray(res?.images)) images.push(...res.images);
+  };
+  collect(first);
+
+  // Family variants depend on their lowest-numbered anchor. Run independent
+  // slides + anchors first, then variants; the server cache remains a safety
+  // net for older clients and retries.
+  const families = await import(
+    pathToFileURL(path.join(BUILDERS_DIR, "visual-families.mjs")).href
+  );
+  const waves = families.conceptGenerationWaves(planMarkdown, slideCount);
+  const CONCURRENCY = 3;
+  async function runWave(slides) {
+    let cursor = 0;
+    async function worker() {
+      for (;;) {
+        const idx = cursor++;
+        if (idx >= slides.length) return;
+        const n = slides[idx];
+        try {
+          const res = await client.generateConceptImagesForBrand(brandId, {
+            planMarkdown,
+            slideNumbers: [n],
+            backendURL,
+          });
+          collect(res);
+        } catch (err) {
+          process.stderr.write(
+            `slidemind: concept mockup for slide ${n} failed: ${err?.message ?? err}\n`,
+          );
+        }
+      }
+    }
+    await Promise.all(
+      Array.from({ length: Math.min(CONCURRENCY, slides.length) }, () => worker()),
+    );
+  }
+  await runWave(waves.firstWave);
+  await runWave(waves.variants);
+
+  if (images.length === 0) {
+    process.stdout.write(
+      "no concept mockups generated — continuing without.\n",
+    );
+    process.exit(0);
+  }
+
+  const conceptsDir = path.join(deckDir, "concepts");
+  fs.mkdirSync(conceptsDir, { recursive: true });
+  const written = [];
+  for (const img of images) {
+    const n = Number(img?.slideNumber);
+    if (!Number.isFinite(n) || n < 1) continue;
+    const b64 = base64FromDataUri(img?.dataUri);
+    if (!b64) continue;
+    const name = `concept-slide-${String(n).padStart(2, "0")}.png`;
+    const abs = path.join(conceptsDir, name);
+    fs.writeFileSync(abs, Buffer.from(b64, "base64"));
+    written.push(abs);
+  }
+
+  // Drop stale mockups from a previous, longer plan — any concept-slide-NN.png
+  // whose slide number now exceeds the plan's slideCount.
+  for (const entry of fs.readdirSync(conceptsDir)) {
+    const m = /^concept-slide-(\d+)\.png$/.exec(entry);
+    if (m && Number(m[1]) > slideCount) {
+      fs.rmSync(path.join(conceptsDir, entry), { force: true });
+    }
+  }
+
+  if (written.length === 0) {
+    process.stdout.write(
+      "no concept mockups generated — continuing without.\n",
+    );
+    process.exit(0);
+  }
+
+  written.sort();
+  process.stdout.write(
+    written.join("\n") +
+      `\nWrote ${written.length} concept mockup(s) to ${conceptsDir} — ` +
+      "Read each, then rebuild as slide JSX (workflow/create.md → Preconditions).\n",
+  );
+}
+
 async function cmdDownloadBundle(rest) {
   let to = null;
   let force = false;
@@ -1287,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([
@@ -1604,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,
@@ -1652,14 +2318,54 @@ async function cmdDoctor(rest) {
   process.stdout.write(`Next action: ${status.nextAction}\n`);
 }
 
+// Print a read result — the `{ ok, mode, slideCount, slides[] }` shape, whether
+// it came from the add-in (open presentation) or a local .pptx. Shared by both
+// `cmdRead` branches so their output is byte-for-byte identical.
+function printReadResult(res, asJson) {
+  if (asJson) {
+    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+    return;
+  }
+  const slides = Array.isArray(res.slides) ? res.slides : [];
+  if (slides.length === 0) {
+    process.stderr.write("(presentation has no slides)\n");
+    return;
+  }
+  if (res.mode === "summary") {
+    for (const s of slides) {
+      const label = s.title || "(untitled)";
+      const sub = s.subtitle ? ` — ${s.subtitle}` : "";
+      const layout = s.layout ? `  [${s.layout}]` : "";
+      process.stdout.write(
+        `${String(s.index).padStart(3)}.${layout}  ${label}${sub}\n`,
+      );
+    }
+  } else {
+    slides.forEach((s, i) => {
+      if (i > 0) process.stdout.write("\n");
+      const layout = s.layout ? ` (${s.layout})` : "";
+      process.stdout.write(`── Slide ${s.index}${layout} ──\n`);
+      process.stdout.write(`${s.text && s.text.length ? s.text : "(no text)"}\n`);
+    });
+  }
+}
+
 // Pull the current content of an open presentation. Content is window-bound, so
 // pick exactly one window (positional presId or --to; pickPresentationEntry errors
 // listing the windows if several are open and none was named). `--mode summary`
 // prints a per-slide outline; default `raw` prints each slide's plain text.
+//
+// A positional arg with a local PowerPoint extension (LOCAL_PPTX_RE: .pptx and
+// its .pptm/.potx/.potm/.ppsx/.ppsm siblings) AND resolving to an existing
+// regular file is read host-free from disk instead (no bridge). The gate is
+// strict: a nonexistent path or a real presId falls through to the host path
+// unchanged, and it is skipped when --to is given (--to targets an open window).
 async function cmdRead(rest) {
   let presId = null;
   let mode = "raw";
   let asJson = false;
+  let toGiven = false;
+  let fileArg = null; // the positional (a candidate local .pptx path)
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--mode") {
@@ -1671,16 +2377,47 @@ async function cmdRead(rest) {
     } else if (a === "--to") {
       presId = rest[++i];
       if (!presId) fail("--to expects a presId");
+      toGiven = true;
     } else if (a === "--json") {
       asJson = true;
     } else if (a.startsWith("-")) {
       fail(`unknown flag: ${a}`);
     } else if (!presId) {
-      presId = a; // positional presId
+      presId = a; // positional presId (or local .pptx path)
+      fileArg = a;
     } else {
       fail(`unexpected argument: ${a}`);
     }
   }
+
+  // Local-file gate: applies ONLY to the positional, and never when --to is set.
+  // The positional must end in .pptx and resolve to an existing regular file;
+  // anything else (missing path, real presId) falls through to the host path.
+  if (fileArg && !toGiven && LOCAL_PPTX_RE.test(fileArg)) {
+    const p = path.isAbsolute(fileArg)
+      ? fileArg
+      : path.resolve(process.cwd(), fileArg);
+    let st = null;
+    try {
+      st = fs.statSync(p);
+    } catch {
+      st = null;
+    }
+    if (st && st.isFile()) {
+      const { readLocalPptx } = await import(
+        pathToFileURL(path.join(SRC_DIR, "pptx", "read-local.mjs")).href
+      );
+      let res;
+      try {
+        res = readLocalPptx(fs.readFileSync(p), { mode });
+      } catch (err) {
+        fail(`read failed: ${err.message}`);
+      }
+      printReadResult(res, asJson);
+      return;
+    }
+  }
+
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
@@ -1694,32 +2431,7 @@ async function cmdRead(rest) {
   if (!res?.ok) {
     fail(`read failed: ${res?.error ?? "unknown error"}`);
   }
-  if (asJson) {
-    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
-    return;
-  }
-  const slides = Array.isArray(res.slides) ? res.slides : [];
-  if (slides.length === 0) {
-    process.stderr.write("(presentation has no slides)\n");
-    return;
-  }
-  if (res.mode === "summary") {
-    for (const s of slides) {
-      const label = s.title || "(untitled)";
-      const sub = s.subtitle ? ` — ${s.subtitle}` : "";
-      const layout = s.layout ? `  [${s.layout}]` : "";
-      process.stdout.write(
-        `${String(s.index).padStart(3)}.${layout}  ${label}${sub}\n`,
-      );
-    }
-  } else {
-    slides.forEach((s, i) => {
-      if (i > 0) process.stdout.write("\n");
-      const layout = s.layout ? ` (${s.layout})` : "";
-      process.stdout.write(`── Slide ${s.index}${layout} ──\n`);
-      process.stdout.write(`${s.text && s.text.length ? s.text : "(no text)"}\n`);
-    });
-  }
+  printReadResult(res, asJson);
 }
 
 async function loadBridgeModule(name) {
@@ -2221,7 +2933,22 @@ async function cmdUpdate(rest) {
     : "slidemind@latest";
   await ui.section("release", ref ? `pinned ${spec}` : "latest");
   ui.step({ label: "install", value: spec, note: "global (npm)" });
-  await spawnInherit(npmBin(), ["install", "-g", "--loglevel=error", spec]);
+  try {
+    await spawnInherit(npmBin(), ["install", "-g", "--loglevel=error", spec]);
+  } catch (err) {
+    console.error(
+      "\nslidemind update 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" +
+        "Then run `slidemind init --for all`.\n",
+    );
+    throw err;
+  }
 
   if (target !== "none") {
     await spawnInherit("slidemind", ["init", "--for", target]);
@@ -2275,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;
@@ -2299,6 +3029,9 @@ async function main(rawArgv) {
     case "download-result":
       await cmdDownloadResult(rest);
       return 0;
+    case "concepts":
+      await cmdConceptImages(rest);
+      return 0;
     case "download-bundle":
       await cmdDownloadBundle(rest);
       return 0;