slidemind 0.1.9 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Connect Claude Code, Codex & opencode to the slidemind PowerPoint add-in — let your coding agent build and edit native, on-brand PowerPoint decks against your active corporate design, from the terminal.",
   "type": "module",
   "bin": {

package/skills/create-slides/SKILL.md

@@ -146,7 +146,7 @@ Keep planning about intent and content. The bundle is already materialized by `s
 1. **Study brand samples (before composing).** The materialized bundle's `samples/` dir holds the brand's own reference slides. If it's non-empty, pick **3 at random** and **Read** each (the Read tool renders images) *before* writing any JSX — this is the local-harness stand-in for the in-app persona's reference thumbnails, and it is what keeps a deck looking on-brand rather than merely compliant. Study them for whitespace rhythm, shape density, hierarchy, accent use, and layering, then compose in that spirit (never copy a sample 1:1). This is `composition.md`'s samples discipline; skip only when `samples/` is empty.
 2. **Read, then author.** Read the create-stage references together — `workflow/create.md` (the procedure), `workflow/composition.md` (the composition baseline), `workflow/layouts.md` (palette + working area), and `workflow/authoring.md` (the substrate rules) — plus the deck's `design.md` and the specific `layouts/*.jsx` the plan uses. (That is the read set `workflow/create.md` → Context loading prescribes; follow it as written — `workflow/flow.md` you already read after `ready`.) Then write `decks/<slug>/slides/NN-<topic>.jsx` — zero-padded numeric prefix from the first file on (play order is filename order here; see the slide-file row in the command mapping), one default export per slide, composing one bundle layout (Mode A) or a blank-content layout with freeform children (Mode B), exactly as those docs prescribe. The approved `plan.md` is a **content contract, not a rendering spec** — you drew its storyboards yourself, but approval covered the story and content, not the sketch's geometry; how to interpret the `storyboard-canvas` blocks at author time (design hypothesis: reinterpret freely, never transcribe coordinates, block geometry, or block labels) is owned by `workflow/create.md` → Preconditions. **Generate concept mockups first — mandatory for a deck (stage 4).** Before authoring a deck from an approved plan, run `slidemind concepts <deck>` — the local-harness equivalent of the in-app manager's *unconditional* concept pass (`generateConceptImages` fires for every `approvedPlan && !targetSlideScope` delegation). Then **Read** each `decks/<slug>/concepts/concept-slide-NN.png` as the per-slide design target and rebuild it under your constraints — the rebuild rule is owned by `workflow/create.md` → Preconditions (reproduce the mockup's composition, hierarchy, graphic mechanism, AND granularity — its organism count, badges, satellites, and annotation layers are part of the target, and restraint is a colour budget, never an element budget; texts follow the story). It never hard-fails: if it produces no mockups (exit 0 — the add-in can't generate them) author from the storyboards alone. Skip it only where the add-in's `!targetSlideScope` gate would — a single slide, a tiny in-chat set, or a targeted rework of existing slides.
    When storyboard objects share a `visualFamily`, rebuild those mockups as one recognizable visual series. The lowest-numbered member is the anchor. Preserve its shape vocabulary, framing, hierarchy, annotation style, illustration treatment, and spatial rhythm across the family, but adapt every member's element count, sizing, arrangement, labels, emphasis, and connections to its own complete `keyMessage`, `contentNotes`, role, and structure. Never copy another member's text, claims, or data, never force its exact geometry, and never omit approved content because it does not fit the anchor composition.
-3. **Imagery from the engine.** Discover the available image engines by listing them — `slidemind ls engines --subtype image` (the local-harness equivalent of the in-app design agent's `list_engines` tool) — judge which engine fits from its label and description, then search it and place results. (`slidemind search` without `--engine` picks an image engine the same way.) The engine search/reuse mechanics live in **`slidemind-search`** — use it to find and fetch imagery; the create-only icon-recolour detail is in *Recolouring engine icons* below. To pull in an **existing whole slide** (not just an image), use `slidemind-search`'s `add-slide` — it folds the slide into `decks/<slug>/slides/` as a native `.pptx` that coexists with your JSX in play order and survives re-push. The slide can come from an engine search **or** from a local `.pptx` on disk (`add-slide --from <file.pptx> --pick <n> --deck <slug>`, host-free); both fold in identically — see `slidemind-search`.
+3. **Imagery from the engine.** Discover the available image engines by listing them — `slidemind ls engines --subtype image` (the local-harness equivalent of the in-app design agent's `list_engines` tool) — judge which engine fits from its label and description, then search it and place results. (`slidemind search` without `--engine` picks an image engine the same way.) The engine search/reuse mechanics live in **`slidemind-search`** — use it to find and fetch imagery; the create-only detail — sizing a fetched asset's box and recolouring an icon — is in *Placing engine imagery* below. To pull in an **existing whole slide** (not just an image), use `slidemind-search`'s `add-slide` — it folds the slide into `decks/<slug>/slides/` as a native `.pptx` that coexists with your JSX in play order and survives re-push. The slide can come from an engine search **or** from a local `.pptx` on disk (`add-slide --from <file.pptx> --pick <n> --deck <slug>`, host-free); both fold in identically — see `slidemind-search`.
 4. **Look at your own draft first (you, the agent).** This is the **draft check** in `workflow/build-and-export.md` — your pre-check, *before* any human sees the deck. Run `slidemind view-draft <deck>`: it renders each authored `slides/*.jsx` to a per-slide PNG and hands the images back to you — **nothing is pushed, no `.pptx` is written, no review gate opens**. Read every image the way the audience will, fix anything visibly wrong **in the JSX** (re-express, never delete), and view again until each slide is sound. One round usually suffices. It runs locally against the materialized bundle, so it needs no awake pane and no open host once the bundle has been downloaded once. Two faithful limits to know: a slide on a **purpose-built (Mode A) layout** (cover/divider/agenda) and a **reused native `.pptx`** slide have no freeform region to capture, so they come back as a status line, not an image — judge those at the full-deck `review`/`build` step below. Do this self-check before the human review gate; don't push a draft you haven't looked at.
 5. **The review gate — the moment the deck builds clean.** This is the **review gate** in `workflow/build-and-export.md`; the CLI's gate command is `slidemind review <deck>`. Run it the instant the authored set builds clean — before any deliver, without asking whether the user wants a review. It builds the HTML preview first (the same lint the render enforces, so a gate that *opens* is a clean build; while lint errors remain it exits non-zero — fix and re-run), then opens the browser with a spatial comment overlay and **blocks until the user decides** (host-free — no open PowerPoint needed for the gate). Announce it per *Two UX rules*: tell the user the browser opened and give the clickable gate URL. **Blocking is the point: give the shell call a generous timeout (the gate waits up to 30 min) and let it sit — a long quiet wait means the user is reviewing, not that something hung. Never cancel it; if your harness kills the call early, just re-run it (the user's open tab reconnects).** The verdict prints to stdout:
    - `DECISION: approved` → proceed to the deliver the user chose at intake: `slidemind push <deck>` (into PowerPoint) or `slidemind build-pptx <deck>` (to a file).
@@ -157,12 +157,13 @@ Keep planning about intent and content. The bundle is already materialized by `s
 
    **On a clean approve + deliver, the task is done.** Report what landed (slide count + target) and stop — no sanity pass, no re-verification. The visual QA already happened at the draft check (step 4) and the user signed off at the review gate.
 
-## Recolouring engine icons (create-authoring specifics)
+## Placing engine imagery (create-authoring specifics)
 
-Finding and fetching engine imagery is `slidemind-search`'s job (`slidemind search` → `slidemind download-result`). What follows is **create-only**: how to colour a fetched icon so it reads on-brand in your JSX, honoured in both the `slidemind build` preview and the render.
+Finding and fetching engine imagery is `slidemind-search`'s job (`slidemind search` → `slidemind download-result`). What follows is **create-only**: how to size and colour a fetched asset so it reads on-brand in your JSX, honoured in both the `slidemind build` preview and the render.
 
 Engine results land as files referenced with `<img src="./assets/<file>">`. These facts are specific to the local harness (the bundle's `workflow/*.md` stay harness-neutral):
 
+- **Size the box from the asset's own dimensions.** Both `slidemind search` (from the engine index, before any fetch) and `slidemind download-result` (measured from the delivered bytes) print each image's intrinsic `width×height`. **Use it.** A plain `<img>` is stretched to whatever box you write, so a box whose aspect ratio disagrees with the asset ships a distorted picture. Derive one side from your layout and compute the other from the printed ratio. `object-fit: contain`/`cover` is honoured in the render as well as the preview, but it is a *fallback*, not a substitute: it converts a wrong ratio into letterboxing or a crop, both of which you chose blind. When the size prints as `(size unknown)`, the format carried no readable header — give the asset a square-ish box and check it at the draft check.
 - **Never open the SVG to find out whether it recolours.** `slidemind download-result` prints a `recolor` descriptor for each asset — `{ recolorable, mode, applied, note }`, where `mode` is `currentColor`, `mono`, `multicolor`, or `raster`. Read it; that *is* the answer.
 - **Two ways to colour an icon, both honoured in the `slidemind build` preview *and* the render:**
   - **Bake it in (prefer this):** pass `--icon-color <hex>` — a hex you resolve from a token in the bundle's `corporate-design.css` — to `slidemind download-result`. Works for any `recolorable` glyph and the colour is in the saved file, so preview and render always agree.
@@ -186,8 +187,8 @@ The bundle's `workflow/*.md` speak the harness-neutral verbs defined in `workflo
 | **build & push** | `slidemind push <deck>` (into the open PowerPoint) · `slidemind build-pptx <deck>` (to a `.pptx` file) — deliver whichever target was locked at intake; both render server-side via the bridge, and for a bound deck the render is pane-free (`build-pptx` needs no PowerPoint window at all) |
 | **the review gate** | `slidemind review <deck>` — builds the HTML preview (lint-clean or it doesn't open), serves it with a spatial comment overlay and **blocks until the user decides**, then prints `DECISION: approved` or `DECISION: comments` (each comment cited to `slides/<file>.jsx:line:col`). On approve → deliver (`slidemind push` / `build-pptx`); on comments → edit the cited files and re-run `slidemind review` (prior round shows as ghost pins). CLI delivers happen out of the user's sight, so **every deliver follows an approved review of what it delivers — re-run `review` after any slide change**. `push`/`build-pptx` never pause; only `review` does. |
 | **inspect the deck** | `slidemind read [presId\|file.pptx] [--mode summary\|raw]` — one verb, two sources: pull the current content of an open presentation (a presId; host) **or** read a local `.pptx` on disk (a file path; host-free — no PowerPoint, no pairing). `summary` = per-slide outline; `raw` = each slide's plain text — to inspect what's there before editing. Plain text, not authoring markup |
-| **discover engines** (`list_engines`) | `slidemind ls engines [--type <collection\|search>] [--subtype <image\|slide\|template\|content>]` — the live catalog is the only engine list (the bundle carries none); pick an engine `id` from it, never guess one |
-| **engine search / fetch** | **`slidemind-search`** owns the engine search + reuse mechanics (`slidemind search` → `slidemind download-result`, plus whole-slide reuse via `add-slide`). For placing a fetched icon in your JSX, pass `--icon-color` / batch with `--pick <n,n,…>` and colour per *Recolouring engine icons* below |
+| **discover engines** (`list_engines`) | `slidemind ls engines [--type <collection\|search\|scope>] [--subtype <image\|slide\|template\|content>]` — the live catalog is the only engine list (the bundle carries none); pick an `id` from it, never guess one. It also lists **search scopes** for unfiltered corpus search — those belong to `slidemind-search`, not to imagery |
+| **engine search / fetch** | **`slidemind-search`** owns the engine search + reuse mechanics (`slidemind search` → `slidemind download-result`, plus whole-slide reuse via `add-slide`). For placing a fetched asset in your JSX, size its box from the printed `width×height`, pass `--icon-color` / batch with `--pick <n,n,…>` and colour per *Placing engine imagery* below |
 | **see** a live slide | no CLI analog — once delivered, the user is looking at the result; your visual authority runs at the draft check and the review gate instead |
 
 Everything else in `workflow/*.md` — the composition craft, the substrate/authoring rules, the layout discovery and slot/working-area rules, the visual quality bar (applied at the draft check) — applies to you unchanged.

package/skills/search/SKILL.md

@@ -37,9 +37,10 @@ The pane-touching ops here (`search`, `view_slide`, `insert-slide`, `download-re
 
 Follow `workflow/search.md` for the discipline; this is the CLI shape of its loop.
 
-1. **Discover engines — never guess an id.** Run `slidemind ls engines` and read the catalog before searching. Filter to what you need with `--type <collection|search>` and `--subtype <image|slide|template|content>` (e.g. `slidemind ls engines --type search --subtype slide` for slide libraries). The catalog is **per-user, not per-presentation** — there is no presId to scope; spanning every paired environment, each engine is tagged with its `env`. (`--to` is accepted for symmetry with the other commands but ignored — it does not narrow the catalog.) Pick an engine **id** from the list — do not invent one.
-2. **Choose the engine + intent.** Slide engines (`subtype slide`) support two intents: **content** (the slide's text is the signal — title, body, tables, notes) and **visual** (the slide image is the signal). Image/icon engines (`subtype image`) are **visual-only**. Match the intent to the ask: "a slide that says X" / "covers topic Y" → `--intent content`; "a slide that looks like X" / brand imagery → `--intent visual`. `--intent auto` lets the engine decide.
-3. **Search — no window to choose.** `slidemind search "<query>" --engine <id> --intent <auto|content|visual> [--top N]` (leave `--to` off — search attaches to any connected window itself). It returns a `searchId` plus numbered results, and prints **which window it ran on** (`searchId N ran on window <presId>`). **Thread that `presId` into every follow-up** as `--to <presId>` (view-slide / insert-slide / add-slide / download-result): the `searchId` is bound to that window, so a follow-up aimed at a different window won't find it.
+1. **Discover targets — never guess an id.** Run `slidemind ls engines` and read the catalog before searching. It lists two kinds of target: **engines** (`--type collection|search`) and **scopes** (`--type scope` — `scope:all`, and `scope:sharepoint` once a site is connected), which search the corpus unfiltered. Filter with `--subtype <image|slide|template|content>` (e.g. `slidemind ls engines --type search --subtype slide`). The catalog is **per-user, not per-presentation** — there is no presId to scope; spanning every paired environment, each row is tagged with its `env`. (`--to` is accepted for symmetry but ignored.) Pick an **id** from the list — do not invent one. **An empty or thin engine list is not "nothing to search"** (see `workflow/search.md`): fall through to a scope.
+2. **Choose the target + intent.** Slide engines (`subtype slide`) and scopes support two intents: **content** (the slide's text is the signal — title, body, tables, notes) and **visual** (the slide image is the signal). Image/icon engines (`subtype image`) are **visual-only**. Match the intent to the ask: "a slide that says X" / "covers topic Y" → `--intent content`; "a slide that looks like X" / brand imagery → `--intent visual`. `--intent auto` lets the engine decide.
+3. **Search — no window to choose.** `slidemind search "<query>" --engine <id> --intent <auto|content|visual> [--top N]` (leave `--to` off — search attaches to any connected window itself). A **scope** target additionally needs `--result-type slide|image` (it has no subtype of its own; the CLI defaults it to `slide`). Omit `--engine` entirely and the CLI picks for you: a slide intent searches `scope:all` for slides, anything else resolves a live image engine. It returns a `searchId` plus numbered results, and prints **which window it ran on** (`searchId N ran on window <presId>`). **Thread that `presId` into every follow-up** as `--to <presId>` (view-slide / insert-slide / add-slide / download-result): the `searchId` is bound to that window, so a follow-up aimed at a different window won't find it.
+   - **On `0 result(s)`, read the diagnostic the CLI prints and act on it** — it lists the causes that look identical from here (nothing connected, still indexing, the engine's folder filter excludes the content) and the next moves. Reuse from a scope works exactly like reuse from an engine, so widening costs you nothing.
 4. **Read / view, then pick.** For **content** results, read the per-slide **text + score** the search prints — that is the on-the-wire signal; you usually don't need the picture. For **visual** results, scan the numbered thumbnail list; pull a single result's image on demand with `slidemind view-slide --search <searchId> --pick <n> --to <presId>` (it writes the preview to a file you can Read), or `slidemind search … --json` for the structured payload. Pick by **selection number(s)**.
 5. **Reuse.** Insert live or fold into a deck — see the next section.
 
@@ -65,6 +66,8 @@ This writes the **same** `decks/<slug>/slides/NN-reused-*.pptx` as the engine pa
 
 For brand **imagery** (icons/images, not whole slides), the reuse step is `slidemind download-result` — it writes the asset into the deck's `assets/`. That mechanism (including the icon-recolor descriptor and `--icon-color`) is documented where it's used, in `slidemind-create-slides`.
 
+Image results print their **intrinsic `width×height`** next to the title — the engine indexes it, so the aspect ratio is yours *before* you fetch anything. Carry it into the pick: a result whose shape doesn't suit the slot you have in mind is the wrong pick, whatever it depicts. (`download-result` re-states the size, measured from the delivered bytes.)
+
 ## Working with slidemind-create-slides
 
 These two skills compose. When the user is **authoring** a deck (that's `slidemind-create-slides`) and wants an **existing** slide incorporated, reach for this skill's `add-slide`: it folds the existing slide into the same `decks/<slug>/slides/` directory as the authored JSX. The reused `.pptx` and the authored `.jsx` coexist in play order (numeric filename prefix) and the reused slide is **not lost on re-push**. Hand back to `slidemind-create-slides` for any new content authoring.
@@ -75,8 +78,9 @@ These two skills compose. When the user is **authoring** a deck (that's `slidemi
 
 | Verb (`workflow/search.md`) | Your equivalent (local harness) |
 |---|---|
-| **discover engines** ("list what you can reach") | `slidemind ls engines [--type …] [--subtype …]` — returns the engine catalog (pick an `id`; never guess one). The catalog is backend/user-scoped; `--to` is accepted but ignored (informational only). |
+| **discover engines** ("list what you can reach") | `slidemind ls engines [--type collection\|search\|scope] [--subtype …]` — returns the engine catalog **plus the search scopes** (pick an `id`; never guess one). The catalog is backend/user-scoped; `--to` is accepted but ignored (informational only). |
 | **engine search** (with `intent`) | `slidemind search "<query>" --engine <id> --intent <auto\|content\|visual> [--top N]` — leave `--to` off (attaches to any window) → a `searchId` + numbered results, **plus the presId it ran on** (thread that in as `--to` on the follow-ups below) |
+| **search a scope** (unfiltered corpus, no engine) | `slidemind search "<query>" --engine <scope:all\|scope:sharepoint> --result-type <slide\|image> [--intent …]` — `--result-type` is required for a scope (defaults to `slide`). Results reuse identically to engine results. |
 | **pull an on-demand thumbnail** for a stored result | `slidemind view-slide --search <searchId> --pick <n> --to <searchWindow>` — writes one result's preview image to a file (`--to` = the window the search returned) · or `slidemind search … --json` for the structured payload. |
 | **insert live** (reuse a slide → the open window) | `slidemind insert-slide --search <searchId> --pick <n[,n,…]> --to <searchWindow> [--at N]` — `--to` = the window the search returned; the slide lands there |
 | **fold into a deck** (reuse a slide → deck source) | `slidemind add-slide --search <searchId> --pick <n[,n,…]> --deck <deck> --to <searchWindow> [--at N]` → writes `decks/<slug>/slides/NN-reused-*.pptx`; `--to` = the window the search returned (extraction runs there) |
@@ -89,3 +93,5 @@ Everything else in `workflow/search.md` — the engine-discovery discipline, con
 ## The engines and the workflow both live in the bundle, not here
 
 Do not restate which engines exist, what they contain, or any brand rule — the engine catalog comes from `slidemind ls engines` (live discovery — the bundle carries no engine list), and the search/reuse craft is in `workflow/search.md`. Read them and follow them. If the corporate design moves mid-task, re-list engines before searching again, since the catalog may have changed.
+
+`workflow/search.md` also owns the judgement this skill deliberately does **not** restate: what an engine actually is (a saved filter over a shared corpus, not a library of its own), when to reach for a scope instead, and why zero results are not evidence that the content doesn't exist. Read it before concluding a search came up empty.

package/src/bridge/bundle.mjs

@@ -648,11 +648,29 @@ export function loadEnginesForDeck(deckDir) {
   return readEnginesFromDir(resolveBundleDirForDeck(deckDir));
 }
 
+// Reserved non-engine search targets. An engine is a saved FILTER over the
+// add-in's shared corpus; a scope searches that corpus unfiltered. They ride in
+// the same id slot as engines — engine ids are UUIDs and can never contain ":",
+// so the namespace can't collide. Kept in sync with the add-in's
+// `types/search-scope.ts` / `models/domain/search_scopes.py`.
+export const SCOPE_PREFIX = "scope:";
+export const SCOPE_ALL = "scope:all";
+export const SCOPE_SHAREPOINT = "scope:sharepoint";
+
+// True when an id names a search scope rather than an engine. Matches unknown
+// `scope:*` values too, so a typo is reported as a bad scope by the add-in
+// instead of being looked up as an engine and reported as "Engine not found".
+export function isSearchScopeId(id) {
+  return typeof id === "string" && id.startsWith(SCOPE_PREFIX);
+}
+
 // Image-producing engine kinds — the modality "image" plus the finer image
 // content kinds an authored bundle may carry. Excludes "slide" (a slide-search
-// engine returns whole slides, not insertable bytes). Mirrors the add-in's
-// local-bridge `engine_not_image` gate so the CLI never picks an engine the
-// bridge would reject.
+// engine returns whole slides, not insertable bytes) and scopes (whose subtype
+// is empty — they are not a brand image source, so the imagery default must not
+// silently resolve to one). Mirrors the add-in's local-bridge
+// `engine_not_image` gate so the CLI never picks an engine the bridge would
+// reject.
 const IMAGE_ENGINE_KIND_RE = /^(image|icon|photo|illustration|vector)$/i;
 
 // True when an engine produces insertable image bytes. Gates on the engine's

package/src/bridge/client.mjs

@@ -51,6 +51,42 @@ export function compareCliVersions(a, b) {
   return 0;
 }
 
+// The one error every version-floor check raises, so the probe path
+// (assertCliVersionSupported) and the per-response header path are
+// indistinguishable to callers and to the skills that relay the text.
+function cliUpdateRequiredError(min) {
+  const err = new Error(
+    `slidemind CLI ${cliVersion()} is older than the minimum this add-in ` +
+      `supports (${min}). Run \`slidemind update\` (or ` +
+      "`npm install -g slidemind@latest`), then retry.",
+  );
+  err.code = "cli_update_required";
+  return err;
+}
+
+// `doctor` and `ready` exist to EXPLAIN a broken connection, version skew
+// included — they render it as a structured blocker with an `actor` and a
+// nextAction. Throwing the raw error out of bridgeFetch would break the one
+// command that diagnoses the problem, so they opt out of the header check
+// (their own ladder still reports cli_update_required, terminally).
+let diagnosticMode = false;
+export function setDiagnosticMode(on) {
+  diagnosticMode = on !== false;
+}
+
+// Every add-in response carries the version floor in `x-slidemind-min-cli`.
+// Checking it here covers routes no capability probe guards — the pane ops
+// (search/read/insert) and pairing itself — for zero extra round-trips, and it
+// fires BEFORE the status handling below so a stale CLI hitting a route that
+// does not exist yet reads "run slidemind update" instead of a bare 404.
+function enforceVersionFloor(response) {
+  if (diagnosticMode) return;
+  const min = response?.headers?.["x-slidemind-min-cli"];
+  if (typeof min !== "string" || !min) return;
+  if (compareCliVersions(cliVersion(), min) >= 0) return;
+  throw cliUpdateRequiredError(min);
+}
+
 function isLoopbackHostname(hostname) {
   return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
 }
@@ -199,6 +235,7 @@ async function bridgeFetch(pathPart, init = {}, backendURL = null) {
     }
     throw err;
   }
+  enforceVersionFloor(response);
   if (response.status === 401) {
     throw new Error(
       "slidemind session is invalid or expired. Re-pair: open the add-in, " +
@@ -267,6 +304,7 @@ function nodeRequest(urlString, init = {}) {
           resolve({
             status: res.statusCode ?? 0,
             statusText: res.statusMessage ?? "",
+            headers: res.headers,
             body: Buffer.concat(chunks).toString("utf8"),
           });
         });
@@ -290,6 +328,163 @@ function nodeRequest(urlString, init = {}) {
   });
 }
 
+// A streaming sibling of `nodeRequest`, for responses too large to hold in
+// memory. `nodeRequest` concatenates the whole body and decodes it as UTF-8 —
+// fine for JSON, but it would both balloon memory and CORRUPT binary. This pipes
+// a success response straight to `destPath` and never materializes it.
+//
+// Error and JSON bodies are still buffered: both are small by construction (an
+// error message, or the inline SVG the download route answers with), and the
+// caller needs them whole to act on.
+function nodeRequestToFile(urlString, init = {}, destPath) {
+  const url = new URL(urlString);
+  const isHttps = url.protocol === "https:";
+  const transport = isHttps ? https : http;
+  const body = init.body ?? null;
+  const headers = { ...(init.headers ?? {}) };
+  if (
+    body &&
+    headers["content-length"] === undefined &&
+    headers["Content-Length"] === undefined
+  ) {
+    headers["content-length"] = Buffer.byteLength(body);
+  }
+  const timeoutMs =
+    init.timeoutMs ??
+    (parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) || 35000);
+
+  return new Promise((resolve, reject) => {
+    const req = transport.request(
+      url,
+      {
+        method: init.method ?? "GET",
+        headers,
+        rejectUnauthorized: isHttps
+          ? !isLoopbackHostname(url.hostname)
+          : undefined,
+      },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        const contentType = String(res.headers["content-type"] ?? "");
+        const buffered = status < 200 || status >= 300 || contentType.includes("application/json");
+        if (buffered) {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(Buffer.from(c)));
+          res.on("end", () =>
+            resolve({
+              status,
+              statusText: res.statusMessage ?? "",
+              headers: res.headers,
+              body: Buffer.concat(chunks).toString("utf8"),
+              streamed: false,
+            }),
+          );
+          res.on("error", reject);
+          return;
+        }
+        const out = fs.createWriteStream(destPath);
+        let bytesWritten = 0;
+        const total = Number.parseInt(
+          String(res.headers["content-length"] ?? ""),
+          10,
+        );
+        res.on("data", (c) => {
+          bytesWritten += c.length;
+          init.onProgress?.(bytesWritten, Number.isFinite(total) ? total : null);
+        });
+        res.pipe(out);
+        // A stream that dies mid-flight must reject, not resolve with a truncated
+        // file — the caller deletes the partial and surfaces the failure.
+        res.on("error", (err) => {
+          out.destroy();
+          reject(err);
+        });
+        out.on("error", reject);
+        out.on("finish", () =>
+          resolve({
+            status,
+            statusText: res.statusMessage ?? "",
+            headers: res.headers,
+            bytesWritten,
+            streamed: true,
+          }),
+        );
+      },
+    );
+    req.setTimeout(timeoutMs, () => {
+      const err = new Error(
+        `slidemind bridge request timed out after ${timeoutMs}ms`,
+      );
+      err.code = "bridge_timeout";
+      req.destroy(err);
+    });
+    req.on("error", reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+// `bridgeFetch` for a response streamed to disk. Shares the session lookup,
+// auth header and non-2xx error mapping so a streaming call fails exactly like
+// every other bridge call.
+async function bridgeStreamToFile(pathPart, init, destPath, backendURL = null) {
+  const session = sessionForBackend(backendURL);
+  const url = `${session.backendURL}${pathPart}`;
+  const headers = {
+    accept: "application/octet-stream, application/json",
+    ...init.headers,
+    authorization: `Bearer ${session.sessionToken}`,
+  };
+  let response;
+  try {
+    response = await nodeRequestToFile(url, { ...init, headers }, destPath);
+  } catch (err) {
+    if (
+      err &&
+      /ECONNREFUSED|ECONNRESET|ENOTFOUND|self-signed|fetch failed/i.test(
+        String(err.message || err),
+      )
+    ) {
+      throw new Error(
+        `slidemind relay unreachable (${deriveEnvLabel(session.backendURL)}). Check your connection; ` +
+          "if it persists, re-pair with `slidemind pair`.",
+      );
+    }
+    throw err;
+  }
+  enforceVersionFloor(response);
+  if (response.status === 401) {
+    throw new Error(
+      "slidemind session is invalid or expired. Re-pair: open the add-in, " +
+        'click "Connect CLI", and run the shown `slidemind pair …`.',
+    );
+  }
+  if (response.status < 200 || response.status >= 300) {
+    let parsed = null;
+    try {
+      parsed = response.body ? JSON.parse(response.body) : null;
+    } catch {
+      /* non-JSON error body */
+    }
+    const machineCode =
+      parsed && typeof parsed.code === "string" ? parsed.code : null;
+    const humanError =
+      parsed && typeof parsed.error === "string" ? parsed.error : null;
+    const detail =
+      humanError ?? (response.body ? response.body.slice(0, 400) : "");
+    const err = new Error(
+      `slidemind bridge ${response.status} ${response.statusText} for ${pathPart}` +
+        (detail ? `: ${detail}` : ""),
+    );
+    err.status = response.status;
+    const code = machineCode ?? humanError;
+    if (code) err.code = code;
+    if (parsed) err.body = parsed;
+    throw err;
+  }
+  return response;
+}
+
 // List one backend's open presentations, tagging each entry with its origin
 // (backendURL + a short env label) so the merged registry can be routed and
 // displayed per environment. Transient blips retry per-backend.
@@ -879,6 +1074,82 @@ export async function generateConceptImagesForBrand(
   throw err;
 }
 
+// gpt-image calls routinely take 60-120s; budget like the concept relay so a
+// typed server error wins over a client timeout.
+function imagenTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_IMAGEN_TIMEOUT_MS || "200000", 10) ||
+    200000
+  );
+}
+
+async function postGenerateImage(brandId, body, backendURL) {
+  const res = await bridgeFetch(
+    `/api/cli/brands/${encodeURIComponent(brandId)}/images`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      timeoutMs: imagenTimeoutMs(),
+    },
+    backendURL,
+  );
+  const data = (await res.json()) ?? {};
+  return { ...data, backendURL };
+}
+
+// Generate ONE regular image over the pane-free brand route
+// (`slidemind imagen`). Body `{ prompt, size?, quality?, brandStyle? }`;
+// returns the server's `{ ok, image, styleReferences }` augmented with the
+// resolved `backendURL`. Fan-out and degradation mirror
+// generateConceptImagesForBrand: throws a typed `imagen_route_unavailable`
+// when no paired backend serves the route (older add-ins, unknown brand,
+// missing grant) so callers can print the one actionable fix.
+export async function generateImageForBrand(
+  brandId,
+  { prompt, size = null, quality = null, brandStyle = false, backendURL = null } = {},
+) {
+  if (!brandId) {
+    throw new Error("generateImageForBrand: brandId is required");
+  }
+  if (typeof prompt !== "string" || !prompt.trim()) {
+    throw new Error("generateImageForBrand: prompt is required");
+  }
+  const body = { prompt };
+  if (size) body.size = size;
+  if (quality) body.quality = quality;
+  if (brandStyle) body.brandStyle = true;
+  if (backendURL) {
+    return postGenerateImage(brandId, body, backendURL);
+  }
+  const sessions = sessionsInScope();
+  const failures = [];
+  for (const s of sessions) {
+    try {
+      if (!(await backendSupportsImageGeneration(s.backendURL))) {
+        failures.push({
+          env: deriveEnvLabel(s.backendURL),
+          reason: "no image-generation route (update the add-in)",
+        });
+        continue;
+      }
+      return await postGenerateImage(brandId, body, s.backendURL);
+    } catch (err) {
+      failures.push({
+        env: deriveEnvLabel(s.backendURL),
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  const detail = failures.map((f) => `${f.env}: ${f.reason}`).join("; ");
+  const err = new Error(
+    `no paired backend generates images for design '${brandId}'` +
+      `${detail ? ` (${detail})` : ""}.`,
+  );
+  err.code = "imagen_route_unavailable";
+  throw err;
+}
+
 // List the LIVE engine catalog (NOT the bundle's curated set) for the paired
 // backend(s). `GET /api/cli/engines` is backend-scoped, not presId-scoped, so
 // when several environments are paired this fans out and tags each engine with
@@ -1004,6 +1275,14 @@ export async function backendSupportsConceptImages(backendURL) {
   return caps?.conceptImages === true;
 }
 
+// Whether a backend generates regular images over the pane-free
+// `/api/cli/brands/:brandId/images` route (see generateImageForBrand).
+// Advertised by newer add-ins only.
+export async function backendSupportsImageGeneration(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.imageGeneration === true;
+}
+
 // The add-in's hard version floor: /api/cli/capabilities advertises the oldest
 // CLI it still speaks (`minCliVersion`). An older CLI must refuse to proceed —
 // mid-rollout skew otherwise surfaces as confusing route/contract errors deep
@@ -1013,13 +1292,7 @@ export async function assertCliVersionSupported(backendURL) {
   const caps = await backendCapabilities(backendURL);
   const min = typeof caps?.minCliVersion === "string" ? caps.minCliVersion : null;
   if (!min || compareCliVersions(cliVersion(), min) >= 0) return;
-  const err = new Error(
-    `slidemind CLI ${cliVersion()} is older than the minimum this add-in ` +
-      `supports (${min}). Run \`slidemind update\` (or ` +
-      "`npm install -g slidemind@latest`), then retry.",
-  );
-  err.code = "cli_update_required";
-  throw err;
+  throw cliUpdateRequiredError(min);
 }
 
 // Rebuild a job failure into the exact error shape bridgeFetch throws for the
@@ -1330,11 +1603,17 @@ async function engineOpWithPaneWait(presId, backendURL, attempt) {
 // slide results carrying per-slide text + metadata). `subtype`/`intent`/`top`
 // are passed through for slide engines (image engines ignore intent); omit them
 // and the server uses its defaults (back-compat with older add-ins).
+//
+// `engineId` may also be a SCOPE sentinel (`scope:all` / `scope:sharepoint`) —
+// an unfiltered search over the whole corpus rather than one engine's saved
+// folder filter. A scope has no subtype to derive its index from, so it needs an
+// explicit `resultType`; the add-in rejects a scope search without one.
 export async function engineSearch({
   presId,
   engineId,
   query,
   subtype = null,
+  resultType = null,
   intent = null,
   top = null,
   backendURL = null,
@@ -1350,6 +1629,8 @@ export async function engineSearch({
   const be = backendURL || (await resolveBackendForPres(presId));
   const body = { engineId, query };
   if (subtype) body.subtype = subtype;
+  // Additive: omitted unless set, so the body an older add-in sees is unchanged.
+  if (resultType) body.resultType = resultType;
   if (intent) body.intent = intent;
   if (typeof top === "number") body.top = top;
   const run = async (pid, b) => {
@@ -1384,6 +1665,7 @@ export async function engineSearchAnyPane({
   engineId,
   query,
   subtype = null,
+  resultType = null,
   intent = null,
   top = null,
 }) {
@@ -1417,6 +1699,7 @@ export async function engineSearchAnyPane({
         engineId,
         query,
         subtype,
+        resultType,
         intent,
         top,
         backendURL: cand.backendURL ?? primaryBackend,
@@ -1483,6 +1766,130 @@ export async function engineDownload({
   });
 }
 
+// Stream a chosen engine result's bytes to `destPath`. The size-unbounded
+// download: the pane's Socket.IO ack carries only a signed source reference, and
+// the add-in server fetches it and pipes the body here — so nothing buffers the
+// whole image and there is no base64 4/3 inflation. `engineDownload` above sends
+// the bytes through the pane ack instead and is therefore capped by the relay's
+// 10 MB frame limit; prefer this for anything that might be large.
+//
+// An SVG result comes back as JSON (`{ ok, mimeType, svgMarkup }`) rather than a
+// byte stream: it is kilobytes and its recolour happens pane-side. Callers get
+// `{ svgMarkup }` in that case and `{ bytesWritten, mimeType }` otherwise, so they
+// can persist whichever arrived.
+export async function engineDownloadToFile({
+  presId,
+  searchId,
+  selection,
+  destPath,
+  iconColor = null,
+  backendURL = null,
+  onProgress = null,
+}) {
+  if (!presId) throw new Error("engineDownloadToFile: presId is required");
+  if (typeof searchId !== "number") {
+    throw new Error("engineDownloadToFile: searchId (number) is required");
+  }
+  if (typeof selection !== "number") {
+    throw new Error("engineDownloadToFile: selection (number) is required");
+  }
+  if (!destPath) throw new Error("engineDownloadToFile: destPath is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { searchId, selection };
+  if (iconColor) body.iconColor = iconColor;
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeStreamToFile(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/download-stream`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        // A large image legitimately takes longer than an engine op: the server
+        // is fetching from SharePoint/blob AND piping. Separate budget so raising
+        // it doesn't loosen every other relay call.
+        timeoutMs:
+          parseInt(
+            process.env.SLIDEMIND_BRIDGE_DOWNLOAD_TIMEOUT_MS || "600000",
+            10,
+          ) || 600000,
+        onProgress,
+      },
+      destPath,
+      b,
+    );
+    if (!res.streamed) {
+      // The inline-SVG answer (kilobytes) arrives as JSON, not as a byte stream.
+      const parsed = res.body ? JSON.parse(res.body) : {};
+      return { ok: true, streamed: false, ...parsed };
+    }
+    const warningsHeader = res.headers?.["x-slidemind-warnings"];
+    let warnings;
+    if (warningsHeader) {
+      try {
+        warnings = JSON.parse(warningsHeader);
+      } catch {
+        // A malformed header must not fail a download that otherwise succeeded.
+      }
+    }
+    return {
+      ok: true,
+      streamed: true,
+      mimeType: String(res.headers?.["content-type"] ?? "") || null,
+      bytesWritten: res.bytesWritten,
+      ...(warnings ? { warnings } : {}),
+    };
+  });
+}
+
+// Stream a chosen slide-search result to `destPath` as a native one-slide .pptx.
+// The size-unbounded sibling of `extractSlide`: the pane ack carries only the
+// request, and the add-in server performs it and pipes the (base64-decoded) bytes
+// here. `extractSlide` puts the whole slide through the pane's Socket.IO ack as
+// base64, so it is capped at ~7 MB of real bytes — which real reused slides reach.
+export async function extractSlideToFile({
+  presId,
+  searchId,
+  selection,
+  destPath,
+  backendURL = null,
+  onProgress = null,
+}) {
+  if (!presId) throw new Error("extractSlideToFile: presId is required");
+  if (typeof searchId !== "number") {
+    throw new Error("extractSlideToFile: searchId (number) is required");
+  }
+  if (typeof selection !== "number") {
+    throw new Error("extractSlideToFile: selection (number) is required");
+  }
+  if (!destPath) throw new Error("extractSlideToFile: destPath is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeStreamToFile(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-extract-stream`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ searchId, selection }),
+        timeoutMs:
+          parseInt(
+            process.env.SLIDEMIND_BRIDGE_DOWNLOAD_TIMEOUT_MS || "600000",
+            10,
+          ) || 600000,
+        onProgress,
+      },
+      destPath,
+      b,
+    );
+    const title = res.headers?.["x-slidemind-presentation-title"];
+    return {
+      ok: true,
+      bytesWritten: res.bytesWritten,
+      slideId: res.headers?.["x-slidemind-slide-id"] ?? undefined,
+      presentationTitle: title ? decodeURIComponent(String(title)) : undefined,
+    };
+  });
+}
+
 // Extract a chosen slide-search result as a standalone one-slide .pptx (base64),
 // WITHOUT inserting it anywhere — the "fold into a deck" path. Relayed through
 // the pane like search/download.