slidemind 0.3.4 → 0.3.12

package/skills/search/SKILL.md

@@ -5,90 +5,243 @@ description: Discover, search, and reuse content from the active corporate desig
 
 # slidemind-search
 
-This skill is **thin workflow glue for the local harness**. The capability it drives — engine discovery, image/slide search, and slide reuse — runs on the **slidemind PowerPoint add-in**: the engines, the corporate design they belong to, and the search/extraction execution all live there and reach you over the add-in's cloud relay. The **craft** of using it well — how to discover engines, choose content-vs-visual search, pick a result, and reuse a slide responsibly — is authored once by the add-in and served on the materialized bundle as `workflow/search.md`, **byte-identical** to what the in-app design agent reads.
-
-So this file owns only what is genuinely CLI-specific: the **host precondition**, the **discover → search → pick → reuse** loop, the **reuse targets** (insert live vs fold into a deck), and the **command mapping** that translates `workflow/search.md`'s harness-neutral verbs into your `slidemind` CLI commands. **Read `workflow/search.md` from the bundle; never restate the craft here.**
-
-**slidemind is a CLI you drive directly.** Run `slidemind <command>` in your shell — the same way you'd run `git` or `npm`. There is no separate tool layer to go through; every step below is a real command you type.
+This skill is **thin workflow glue for the local harness**. The capability it drives — engine
+discovery, image/slide search, and slide reuse — runs on the **slidemind PowerPoint add-in**: the
+engines, the corporate design they belong to, and the search/extraction execution all live there and
+reach you over the add-in's cloud relay. The **craft** of using it well — how to discover engines,
+choose content-vs-visual search, pick a result, and reuse a slide responsibly — is authored once by
+the add-in and served on the materialized bundle as `workflow/search.md`, **byte-identical** to what
+the in-app design agent reads.
+
+So this file owns only what is genuinely CLI-specific: the **host precondition**, the **discover →
+search → pick → reuse** loop, the **reuse targets** (insert live vs fold into a deck), and the
+**command mapping** that translates `workflow/search.md`'s harness-neutral verbs into your
+`slidemind` CLI commands. **Read `workflow/search.md` from the bundle; never restate the craft
+here.**
+
+**slidemind is a CLI you drive directly.** Run `slidemind <command>` in your shell — the same way
+you'd run `git` or `npm`. There is no separate tool layer to go through; every step below is a real
+command you type.
 
 ## Bootstrap (set yourself up — don't make the user do it)
 
-**The first step of a search session is `slidemind ready --connect-only`** (see *Precondition gate* below). It drives the `slidemind` CLI, which reaches PowerPoint through the add-in's **cloud relay** — no local server. Patch a missing CLI yourself; **connecting** needs the user once (they hold the add-in's identity):
-
-- **CLI missing** (`slidemind` not on `PATH`): `npm install -g slidemind` — that alone is the fix. Add `slidemind init --for <claude|codex|opencode|all>` ((re)deploys this skill) only when this skill did **not** come from a plugin: a `SKILL.md` under a harness plugin cache (`~/.claude/plugins/…`, `~/.codex/plugins/…`) is already deployed, and `init` would just plant a second, drifting copy.
-- **Not connected:** `ready --connect-only` exits with `not_connected` — the CLI cannot start a connection by itself, because the claim carrying the deployment's address is minted in the add-in. Ask the user to open PowerPoint → slidemind → **Settings → General → Connect CLI**, press the **link button**, and copy the command shown (**CLI already installed?** gives the short `slidemind setup …` form). Have them paste it to you and run it **verbatim**. `slidemind whoami` lists connected environments.
-
-This is the same connection as `slidemind-create-slides`, whose **Connecting the CLI** section carries the full step-by-step. If it was approved there, it is already available here.
+**There is no preflight for a search session.** Every engine command checks the connection itself
+and, on failure, names exactly one blocker and one remediation — so start directly with
+`slidemind ls engines` (the first real-work step, see *Precondition gate* below) and act on what a
+failing command prints. The CLI reaches PowerPoint through the add-in's **cloud relay** — no local
+server. Patch a missing CLI yourself; **connecting** needs the user once (they hold the add-in's
+identity):
+
+- **CLI missing** (`slidemind` not on `PATH`): `npm install -g slidemind` — that alone is the fix.
+  Add `slidemind init --for <claude|codex|opencode|all>` ((re)deploys this skill) only when this
+  skill did **not** come from a plugin: a `SKILL.md` under a harness plugin cache
+  (`~/.claude/plugins/…`, `~/.codex/plugins/…`) is already deployed, and `init` would just plant a
+  second, drifting copy.
+- **Not connected:** the command exits with `not_connected` — the CLI cannot start a connection by
+  itself, because the claim carrying the deployment's address is minted in the add-in. Ask the user
+  to open PowerPoint → slidemind → **Settings → General → Connect CLI**, press the **link button**,
+  and copy the command shown (**CLI already installed?** gives the short `slidemind setup …` form).
+  Have them paste it to you and run it **verbatim**. `slidemind whoami` lists connected
+  environments.
+
+This is the same connection as `slidemind-create-slides`, whose **Connecting the CLI** section
+carries the full step-by-step. If it was approved there, it is already available here.
 
 ## Precondition gate (check this first, every time)
 
-Search and reuse need a **connected** CLI. Whether they also need an open PowerPoint depends on the add-in: newer deployments answer engine discovery, search, previews, downloads, and slide extraction **off the connection itself**, so PowerPoint can be backgrounded or closed; older ones relay every one of those through the add-in's task pane and need a live window. The CLI detects which and picks the path — you only have to know which ops stay host-required either way.
-
-1. Run `slidemind ready --connect-only`. It walks the connection ladder (a saved session → reachable backend → CLI version → whether the engines are reachable without a window) but does **not** resolve a design or download a bundle — search doesn't need one.
-   - **Exit 0 → you're set.** Proceed to `slidemind ls engines` (the live catalog is authoritative — the first real-work step). The payload's `engines: { available, envs }` tells you which path you're on: `available: true` means every search step below runs with PowerPoint closed.
-   - **Non-zero →** the CLI names exactly one blocker and one `nextAction`; relay it (copy the setup command / open PowerPoint / click the pane / run `slidemind update` / open the add-in once). The CLI owns the remediation text — don't restate it.
-2. **Never pick a window for discovery.** The engine catalog is **per-user, not bound to a window**. On the pane-free path there is no window in the loop at all; on the relayed path search attaches to **any** connected window by itself. Either way, **never ask the user which window to search with** and don't pass `--to` to disambiguate. (A window matters in exactly two places: when you *insert a slide live*, and when the pane-free path refuses a download — see Reuse.)
-
-**Host-required, always:** `insert-slide` (it types into an open deck) and `slidemind read <presId>` (the live, possibly unsaved content of an open presentation). Everything else here — `ls engines`, `search`, `view-slide`, `read-source`, `download-result`, `add-slide` — is host-free wherever the add-in serves the pane-free routes, and self-waits for a pane where it doesn't: the CLI waits up to ~2 min, prints one *"click the slidemind pane"* line when user help is genuinely needed, and retries safely. Relay that line once and keep waiting — don't re-plan or babysit.
-
-**Microsoft 365 sign-in — automatic; just let it happen.** Every engine operation here — the catalog, `search`, previews, downloads, `add-slide` extraction — runs **as the user**. When no sign-in is stored yet, the first engine command opens the user's browser ITSELF, prints `Microsoft 365 sign-in needed — opening your browser…`, and **blocks until the human finishes**. When you see that line, tell the user to complete the sign-in in the browser window that just opened (you cannot do it) and keep waiting — don't kill or re-run the command. After that one sign-in, every command runs silently for ~90 days. Rendering, bundles, and already-downloaded assets never need it.
-
-**`login_required` → the sign-in was refused or abandoned.** If the automatic sign-in didn't finish (browser closed, 5-minute window elapsed), the command fails with one line naming `slidemind login`; relay it — the user runs it whenever they're ready — and don't work around it with a different engine. **Read the line before relaying it:** when a slidemind pane is already open, the CLI says so — a new `search` simply runs through that window instead (one `note:` on stderr, and the follow-up commands then carry its `--to`), and a command that can't be re-routed tells you to re-run `slidemind search` there. Follow whichever the CLI printed.
-
-**Add-in unreachable → block and name the tab.** When a host-required command can't reach the add-in (a connection blocker, a pane that never wakes, the *click the slidemind pane* line with no effect), **stop** — don't skip the step, work around it, or retry silently. Ask the user to go back into the PowerPoint tab of presentation **<title/fileName>** (name it from the command output or `slidemind presentations` — never a raw id), then re-run the failed command once they have.
+Search and reuse need a **connected** CLI. Whether they also need an open PowerPoint depends on the
+add-in: newer deployments answer engine discovery, search, previews, downloads, and slide extraction
+**off the connection itself**, so PowerPoint can be backgrounded or closed; older ones relay every
+one of those through the add-in's task pane and need a live window. The CLI detects which and picks
+the path — you only have to know which ops stay host-required either way.
+
+1. Start with `slidemind ls engines` — the live catalog is authoritative, and the command doubles
+   as the connection check (no separate preflight; search needs no design bundle).
+   - **Exit 0 → you're set.** The catalog is in front of you; proceed to choose a target. Which
+     path you're on shows up in each command's own output: on the pane-free path every search step
+     below runs with PowerPoint closed, on the relayed path the follow-up commands name the window
+     they ran on.
+   - **Non-zero →** the CLI names exactly one blocker and one remediation; relay it (copy the setup
+     command / open PowerPoint / click the pane / run `slidemind update` / open the add-in once).
+     The CLI owns the remediation text — don't restate it.
+2. **Never pick a window for discovery.** The engine catalog is **per-user, not bound to a window**.
+   On the pane-free path there is no window in the loop at all; on the relayed path search attaches
+   to **any** connected window by itself. Either way, **never ask the user which window to search
+   with** and don't pass `--to` to disambiguate. (A window matters in exactly two places: when you
+   *insert a slide live*, and when the pane-free path refuses a download — see Reuse.)
+
+**Host-required, always:** `insert-slide` (it types into an open deck) and `slidemind read <presId>`
+(the live, possibly unsaved content of an open presentation). Everything else here — `ls engines`,
+`search`, `view-slide`, `read-source`, `download-result`, `add-slide` — is host-free wherever the
+add-in serves the pane-free routes, and self-waits for a pane where it doesn't: the CLI waits up to
+~2 min, prints one *"click the slidemind pane"* line when user help is genuinely needed, and retries
+safely. Relay that line once and keep waiting — don't re-plan or babysit.
+
+**Microsoft 365 sign-in — automatic; just let it happen.** Every engine operation here — the
+catalog, `search`, previews, downloads, `add-slide` extraction — runs **as the user**. When no
+sign-in is stored yet, the first engine command opens the user's browser ITSELF, prints `Microsoft
+365 sign-in needed — opening your browser…`, and **blocks until the human finishes**. When you see
+that line, tell the user to complete the sign-in in the browser window that just opened (you cannot
+do it) and keep waiting — don't kill or re-run the command. After that one sign-in, every command
+runs silently for ~90 days. Rendering, bundles, and already-downloaded assets never need it.
+
+**`login_required` → the sign-in was refused or abandoned.** If the automatic sign-in didn't finish
+(browser closed, 5-minute window elapsed), the command fails with one line naming `slidemind login`;
+relay it — the user runs it whenever they're ready — and don't work around it with a different
+engine. **Read the line before relaying it:** when a slidemind pane is already open, the CLI says so
+— a new `search` simply runs through that window instead (one `note:` on stderr, and the follow-up
+commands then carry its `--to`), and a command that can't be re-routed tells you to re-run
+`slidemind search` there. Follow whichever the CLI printed.
+
+**Add-in unreachable → block and name the tab.** When a host-required command can't reach the add-in
+(a connection blocker, a pane that never wakes, the *click the slidemind pane* line with no effect),
+**stop** — don't skip the step, work around it, or retry silently. Ask the user to go back into the
+PowerPoint tab of presentation **<title/fileName>** (name it from the command output or `slidemind
+presentations` — never a raw id), then re-run the failed command once they have.
 
 ## Discover → search → pick → reuse
 
 Follow `workflow/search.md` for the discipline; this is the CLI shape of its loop.
 
-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 but never needed here.) 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. An empty list **under a `--type`/`--subtype` filter** says so explicitly — it reports how many engines and scopes exist unfiltered — so the next move there is to drop the filter, not to jump to a scope. A row marked *nothing indexed yet* / *indexing* exists but will return nothing right now; pick another target.
-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). 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 — **keep that `searchId`** (it also rides `--json`): every follow-up below is `--search <searchId> --pick <n>`, so an interrupted run resumes its picks without re-searching.
-   - **How the follow-ups are addressed** is printed for you, and differs by path: *"searchId N is held by the add-in"* means the id lives on the connection — the follow-up commands carry **no `--to`** and work with PowerPoint closed; *"searchId N ran on window `<presId>`"* means the older relayed path, where the id is bound to that window — thread that `presId` in as `--to <presId>`. **Copy the next-step commands the search prints** rather than composing them from memory.
-   - Connected to **several environments**? Pass `--deck <deck>` so the search routes by that deck's bound design instead of asking you to choose an environment.
-   - **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; when the search prints a **contact sheet** path, Read that ONE file — every candidate is on it with its selection number burned in — and when it says there is none on this path, pull individual previews with `slidemind view-slide --search <searchId> --pick <n>` (it writes one result's preview to a file you can Read), or `slidemind search … --json` for the structured payload. Pick by **selection number(s)**.
-5. **Read the source deck when the story matters.** A found slide came out of a real presentation, and often the answer the user needs is in the *rest* of it — how the slide was framed, what came before and after, whether that deck already covers more of the ask. `slidemind read-source --search <searchId> --pick <n>` prints the whole source presentation as Markdown, one section per slide. Skip it when you only need the one slide. Two things to know: it is the **last-synced** text, so very recent edits to the original may be missing; and a long deck comes back as a slide map instead, which you narrow with `--from-slide`/`--to-slide`. Only slide results have a source deck — image and collection results do not.
+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 but never needed here.) 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. An empty list **under a `--type`/`--subtype` filter** says so explicitly — it
+   reports how many engines and scopes exist unfiltered — so the next move there is to drop the
+   filter, not to jump to a scope. A row marked *nothing indexed yet* / *indexing* exists but will
+   return nothing right now; pick another target.
+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). 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 —
+   **keep that `searchId`** (it also rides `--json`): every follow-up below is `--search <searchId>
+   --pick <n>`, so an interrupted run resumes its picks without re-searching.
+   - **How the follow-ups are addressed** is printed for you, and differs by path: *"searchId N is
+     held by the add-in"* means the id lives on the connection — the follow-up commands carry **no
+     `--to`** and work with PowerPoint closed; *"searchId N ran on window `<presId>`"* means the
+     older relayed path, where the id is bound to that window — thread that `presId` in as `--to
+     <presId>`. **Copy the next-step commands the search prints** rather than composing them from
+     memory.
+   - Connected to **several environments**? Pass `--deck <deck>` so the search routes by that deck's
+     bound design instead of asking you to choose an environment.
+   - **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; when the search prints a **contact sheet**
+   path, Read that ONE file — every candidate is on it with its selection number burned in. With no
+   contact sheet, previews depend on the result type: **slide-library results** support `slidemind
+   view-slide --search <searchId> --pick <n>` (writes one result's preview to a file you can Read);
+   **image/icon results have NO preview on this path** — `view-slide` answers "no image returned"
+   for them, so never call it on an image search, and never retry it hoping for a different answer.
+   For icons, pick by title + score, `download-result` the pick (downloads are cheap), Read the
+   saved file, and re-search once if it was wrong — two failed downloads for the same need means
+   mark it unresolved and move on. Pick by **selection number(s)**.
+5. **Read the source deck when the story matters.** A found slide came out of a real presentation,
+   and often the answer the user needs is in the *rest* of it — how the slide was framed, what came
+   before and after, whether that deck already covers more of the ask. `slidemind read-source
+   --search <searchId> --pick <n>` prints the whole source presentation as Markdown, one section per
+   slide. Skip it when you only need the one slide. Two things to know: it is the **last-synced**
+   text, so very recent edits to the original may be missing; and a long deck comes back as a slide
+   map instead, which you narrow with `--from-slide`/`--to-slide`. Only slide results have a source
+   deck — image and collection results do not.
 6. **Reuse.** Insert live or fold into a deck — see the next section.
 
 ## Reuse targets — insert live, or fold into a deck
 
-A found slide can be reused two ways. Both extract the picked result(s) as native PowerPoint slides — **reuse is JSX-free; reused slides are native `.pptx`, never JSX.**
-
-- **Insert LIVE into an open PowerPoint** — `slidemind insert-slide --search <searchId> --pick <n[,n,…]> --to <presId> [--at <N>]`. **This is the one host-required step:** the picked slides land in that open window (at position `--at`, else appended), so PowerPoint must be open with the slidemind pane. Name the target window from `slidemind presentations` (or, on the relayed path, use the window the search ran on). A window that reconnects mid-run gets a **new** id; the CLI re-finds it and retries once by itself, so a stale id is not your problem. If it still reports the pane asleep, **don't loop** — relay its line, or fold the same pick into a deck (below) and push it once the user is back in PowerPoint.
-- **Fold into a DECK on disk** — `slidemind add-slide --search <searchId> --pick <n[,n,…]> --deck <deck> [--at <N>]` (add `--to <searchWindow>` only on the relayed path, where the extraction must run on the window that holds the `searchId`). Each picked result is written as a native one-slide file into `decks/<slug>/slides/NN-reused-*.pptx`, in play order; no live window is changed, and nothing needs one. `--json` returns `{ searchId, deck, slides[] }`. Use this when the reused slide should become **part of a deck the user keeps and re-renders** — and prefer it when PowerPoint isn't open: fold now, `slidemind push <deck>` later.
+A found slide can be reused two ways. Both extract the picked result(s) as native PowerPoint slides
+— **reuse is JSX-free; reused slides are native `.pptx`, never JSX.**
+
+- **Insert LIVE into an open PowerPoint** — `slidemind insert-slide --search <searchId> --pick
+  <n[,n,…]> --to <presId> [--at <N>]`. **This is the one host-required step:** the picked slides
+  land in that open window (at position `--at`, else appended), so PowerPoint must be open with the
+  slidemind pane. Name the target window from `slidemind presentations` (or, on the relayed path,
+  use the window the search ran on). A window that reconnects mid-run gets a **new** id; the CLI
+  re-finds it and retries once by itself, so a stale id is not your problem. If it still reports the
+  pane asleep, **don't loop** — relay its line, or fold the same pick into a deck (below) and push
+  it once the user is back in PowerPoint.
+- **Fold into a DECK on disk** — `slidemind add-slide --search <searchId> --pick <n[,n,…]> --deck
+  <deck> [--at <N>]` (add `--to <searchWindow>` only on the relayed path, where the extraction must
+  run on the window that holds the `searchId`). Each picked result is written as a native one-slide
+  file into `decks/<slug>/slides/NN-reused-*.pptx`, in play order; no live window is changed, and
+  nothing needs one. `--json` returns `{ searchId, deck, slides[] }`. Use this when the reused slide
+  should become **part of a deck the user keeps and re-renders** — and prefer it when PowerPoint
+  isn't open: fold now, `slidemind push <deck>` later.
 
 ### A local `.pptx` file as the source (host-free — no engine, no search)
 
-When the slide to reuse already lives in a `.pptx` **on disk** (another presentation, an exported deck), skip discovery entirely — no host, no window, no engine:
-
-1. **List the file's slides.** `slidemind read <file.pptx> --mode summary` prints one outline line per slide **in play order**; note the number(s) you want (1-based).
-2. **Fold the picked slide(s) into a deck.** `slidemind add-slide --from <file.pptx> --pick <n[,n,…]> --deck <deck> [--at <N>]`. `--from` is the local-file alternative to `--search` (they are **mutually exclusive**), and it needs no `--to` — there is no window in the loop.
-
-This writes the **same** `decks/<slug>/slides/NN-reused-*.pptx` as the engine path, so the durable rule below applies unchanged (deck source-of-truth, spliced by play-order filename, survives every re-render). To deliver a local slide **live** into an open window there is no `insert-slide --from`: fold it into a deck as above, then `slidemind push <deck>`.
-
-> **The durable rule:** a slide folded into a deck with `add-slide` is **deck source-of-truth**. The render pipeline splices native `slides/*.pptx` into the deck **by play-order filename**, alongside any authored `.jsx`, so a reused slide **survives every `build-pptx` and `push` re-render** — it is never lost on re-push. Reorder it the same way you reorder JSX: rename its numeric prefix.
-
-> **Building a `.pptx` file from found slides → one combined deck, always.** When the user wants the reused slides as a **`.pptx` file** (rather than a live insert), collect **every** picked slide into **one** deck and render **one** file — never one `.pptx` per slide and never a deck per slide. Fold all picks into the same deck — pass every selection in a single `add-slide` call (`--pick n1,n2,…`), repeating only to cover picks that came from different `searchId`s (always the same `--deck`) — then run `slidemind build-pptx <deck>` once. The render splices every native `slides/*.pptx` into a **single `decks/<slug>/<slug>.pptx`** in play-order, so all the found slides land in one file. That combined `.pptx` is the deliverable; hand back its path. (Need new authored slides interleaved with the reused ones in that same file? That's still one deck — hand off to `slidemind-create-slides` to add the JSX, then `build-pptx` the whole deck once.)
-
-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.)
+When the slide to reuse already lives in a `.pptx` **on disk** (another presentation, an exported
+deck), skip discovery entirely — no host, no window, no engine:
+
+1. **List the file's slides.** `slidemind read <file.pptx> --mode summary` prints one outline line
+   per slide **in play order**; note the number(s) you want (1-based).
+2. **Fold the picked slide(s) into a deck.** `slidemind add-slide --from <file.pptx> --pick
+   <n[,n,…]> --deck <deck> [--at <N>]`. `--from` is the local-file alternative to `--search` (they
+   are **mutually exclusive**), and it needs no `--to` — there is no window in the loop.
+
+This writes the **same** `decks/<slug>/slides/NN-reused-*.pptx` as the engine path, so the durable
+rule below applies unchanged (deck source-of-truth, spliced by play-order filename, survives every
+re-render). To deliver a local slide **live** into an open window there is no `insert-slide --from`:
+fold it into a deck as above, then `slidemind push <deck>`.
+
+> **The durable rule:** a slide folded into a deck with `add-slide` is **deck source-of-truth**. The
+> render pipeline splices native `slides/*.pptx` into the deck **by play-order filename**, alongside
+> any authored `.jsx`, so a reused slide **survives every `build-pptx` and `push` re-render** — it
+> is never lost on re-push. Reorder it the same way you reorder JSX: rename its numeric prefix.
+
+> **Building a `.pptx` file from found slides → one combined deck, always.** When the user wants the
+> reused slides as a **`.pptx` file** (rather than a live insert), collect **every** picked slide
+> into **one** deck and render **one** file — never one `.pptx` per slide and never a deck per
+> slide. Fold all picks into the same deck — pass every selection in a single `add-slide` call
+> (`--pick n1,n2,…`), repeating only to cover picks that came from different `searchId`s (always the
+> same `--deck`) — then run `slidemind build-pptx <deck>` once. The render splices every native
+> `slides/*.pptx` into a **single `decks/<slug>/<slug>.pptx`** in play-order, so all the found
+> slides land in one file. That combined `.pptx` is the deliverable; hand back its path. (Need new
+> authored slides interleaved with the reused ones in that same file? That's still one deck — hand
+> off to `slidemind-create-slides` to add the JSX, then `build-pptx` the whole deck once.)
+
+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.
+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.
 
 ## Command mapping (the search vocabulary ⇄ your CLI)
 
-`workflow/search.md` speaks harness-neutral verbs (discover engines, search with intent, pick, insert live, fold into a deck, engine fetch). You are the local harness — this is your mapping:
+`workflow/search.md` speaks harness-neutral verbs (discover engines, search with intent, pick,
+insert live, fold into a deck, engine fetch). You are the local harness — this is your mapping:
 
 | Verb (`workflow/search.md`) | Your equivalent (local harness) |
 |---|---|
 | **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 never needed. No window needed where the add-in serves the pane-free routes. |
 | **engine search** (with `intent`) | `slidemind search "<query>" --engine <id> --intent <auto\|content\|visual> [--top N] [--deck <deck>]` — leave `--to` off → a `searchId` + numbered results, plus the exact follow-up commands for the path it took (`--deck` routes by that deck's design when several environments are connected) |
 | **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>` — writes one result's preview image to a file (add `--to <searchWindow>` only on the relayed path) · or `slidemind search … --json` for the structured payload. |
+| **pull an on-demand thumbnail** for a stored result | `slidemind view-slide --search <searchId> --pick <n>` — SLIDE-library results only; image/icon results have no preview ("no image returned") — download and Read the file instead (add `--to <searchWindow>` only on the relayed path) · or `slidemind search … --json` for the structured payload. |
 | **read a result's SOURCE deck** (the presentation it came from) | `slidemind read-source --search <searchId> --pick <n> [--from-slide N] [--to-slide N] [--out <file.md>]` — Markdown of the whole source presentation, one section per slide (add `--to <searchWindow>` only on the relayed path). Indexed text, not the live file. Slide results only. |
 | **insert live** (reuse a slide → the open window) | `slidemind insert-slide --search <searchId> --pick <n[,n,…]> --to <presId> [--at N]` — **host-required**: the slide lands in that open window |
 | **fold into a deck** (reuse a slide → deck source) | `slidemind add-slide --search <searchId> --pick <n[,n,…]> --deck <deck> [--at N] [--json]` → writes `decks/<slug>/slides/NN-reused-*.pptx` (add `--to <searchWindow>` only on the relayed path, where extraction runs on the search's window) |
@@ -96,10 +249,17 @@ These two skills compose. When the user is **authoring** a deck (that's `slidemi
 | **fold a LOCAL slide into a deck** (`--from`, host-free) | `slidemind add-slide --from <file.pptx> --pick <n[,n,…]> --deck <deck> [--at N]` → same `decks/<slug>/slides/NN-reused-*.pptx` output as the engine path; `--from` replaces `--search`/`--to` (mutually exclusive with `--search`; no host). Live delivery = fold + `slidemind push <deck>` |
 | **engine fetch** (reuse an image asset) | `slidemind download-result --search <searchId> --pick <n[,n,…]> --deck <deck> [--icon-color <hex[,hex,…]>]` — writes into `decks/<slug>/assets/` (add `--to <searchWindow>` only on the relayed path; recolor descriptor + tinting are covered in `slidemind-create-slides`) |
 
-Everything else in `workflow/search.md` — the engine-discovery discipline, content-vs-visual judgement, the picking and reuse craft — applies to you unchanged.
+Everything else in `workflow/search.md` — the engine-discovery discipline, content-vs-visual
+judgement, the picking and reuse craft — applies to you unchanged.
 
 ## 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.
+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.
+`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/build-and-push.mjs

@@ -273,10 +273,10 @@ export async function renderDeckToBase64(
   // server splices them back from. Keyed by slide file name, like `slides`.
   const conversions = loadConversions(deckDir);
   const hasConversions = Object.keys(conversions).length > 0;
-  for (const file of conversionsMissingPreserveSource(conversions)) {
+  for (const file of conversionsMissingPreserveSource(conversions, deckDir)) {
     process.stderr.write(
-      `note: ${file} has preserved native objects but no conversions/*.slide.pptx ` +
-        `to splice them from — re-run 'slidemind adopt' for that deck\n`,
+      `note: ${file} has preserved native objects or a sourced chart but no ` +
+        `conversions/*.slide.pptx to read them from — re-run 'slidemind adopt' for that deck\n`,
     );
   }
 

package/src/bridge/bundle.mjs

@@ -30,7 +30,6 @@
 //   ├── assets/brand-images.md    (on-demand manifest of the reusable master images,
 //   │                              built from wire.extractedImages — design.md only
 //   │                              carries a sparse pointer + per-kind counts)
-//   ├── samples/*                 (downloaded from wire.samples[].url — brand reference slides)
 //   ├── fonts/*                   (downloaded from wire.fonts[].url, optional)
 //   ├── master/empty-layout.pptx  (downloaded from wire.master.url, optional)
 //   ├── engines.json              (wire.engines[] — legacy: new backends dropped the
@@ -87,6 +86,33 @@ export function readMaterializedBundleMeta(presFP) {
   }
 }
 
+// Every design materialized on this machine: one entry per cache dir that
+// carries a readable bundle.json. `ready` reports these so the agent can ask
+// the user WHICH design to build against when more than one is at hand —
+// no network, never throws.
+export function listCachedBundles() {
+  const root = bundleCacheRoot();
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(root, entry.name);
+    try {
+      const meta = JSON.parse(fs.readFileSync(path.join(dir, "bundle.json"), "utf8"));
+      const presFP = meta?.presFP ?? entry.name;
+      out.push({ presFP, dir, meta });
+    } catch {
+      /* half-written or foreign dir — not a design */
+    }
+  }
+  return out;
+}
+
 // Wipe the whole materialized bundle cache so the next build/push/download
 // re-fetches every design bundle fresh from the add-in. `slidemind init` calls
 // this: init is the deliberate (re)setup point — and `slidemind update`
@@ -164,22 +190,6 @@ async function downloadInto(targetPath, url) {
   fs.writeFileSync(targetPath, buf);
 }
 
-// File extension for a sample image, derived from its wire `contentType`. The
-// sample's stable `id` is the basename; samples carry no `filename` on the wire.
-function sampleExt(contentType) {
-  switch (contentType) {
-    case "image/jpeg":
-      return ".jpg";
-    case "image/webp":
-      return ".webp";
-    case "image/svg+xml":
-      return ".svg";
-    case "image/png":
-    default:
-      return ".png";
-  }
-}
-
 const REUSABLE_KIND_ORDER = [
   "logo",
   "icon",
@@ -235,11 +245,11 @@ function buildReusableImagesManifest(extractedImages) {
 
 // Sync the bundle for `presId`. Idempotent: every call rewrites all inline
 // text from the freshly fetched wire (the wire is fetched on every call
-// anyway), downloads only binaries whose per-item blob etag changed (samples
-// are write-once by id), and prunes files the wire no longer serves. There is
+// anyway), downloads only binaries whose per-item blob etag changed, and
+// prunes files the wire no longer serves. There is
 // deliberately NO staleness token to compare — the materialized dir is always
 // a per-item projection of the last wire, so authored-layer edits that bypass
-// a bundle re-produce (engines, image-source guidelines, sample curation) and
+// a bundle re-produce (engines, image-source guidelines) and
 // deployment-owned content (workflow refs, the lint engine) can never go
 // stale here. `force` re-downloads binaries even when their etags match.
 // Target: `presId` (pane registry), or `brandId` in options for the pane-free
@@ -376,7 +386,7 @@ export async function materializeBundle(
       return;
     }
     if (!force && exists && !etag) {
-      return; // write-once binary (samples carry no etag) — presence is currency
+      return; // write-once binary without an etag — presence is currency
     }
     downloads.push({ rel, target, url, etag: etag ?? null, label });
   };
@@ -408,21 +418,6 @@ export async function materializeBundle(
       "master empty-layout.pptx",
     );
   }
-  // Per-CD sample slides (the brand's own reference slides) — write-once
-  // captures keyed by the sample's stable `id`; extension derived from
-  // `contentType`.
-  for (const sample of wire.samples ?? []) {
-    if (!sample?.url || !sample?.id) continue;
-    queueBinary(
-      path.join(
-        "samples",
-        `${path.basename(sample.id)}${sampleExt(sample.contentType)}`,
-      ),
-      sample.url,
-      null,
-      `sample ${sample.id}`,
-    );
-  }
   // Reusable master images (logos, decorations, illustrations the add-in's
   // vision pass lifted from the brand's own master and flagged `reusable`).
   // Each carries a `workspacePath` (e.g. `assets/master-<sha8>.<ext>`) that the
@@ -522,6 +517,21 @@ export async function materializeBundle(
         role: f.role,
         family: f.family,
         filename: path.basename(f.filename),
+        // Face descriptors (multi-face families: Regular/Bold/Italic/…).
+        // Without them every face of a family registers descriptor-less and
+        // the last one wins for ALL weights — bold measured with the regular
+        // face. Older backends omit them; default to a plain 400/normal face.
+        weight:
+          typeof f.weight === "number" && f.weight >= 100 && f.weight <= 900
+            ? f.weight
+            : 400,
+        style: f.style === "italic" ? "italic" : "normal",
+        variable:
+          f.variable &&
+          typeof f.variable.minWeight === "number" &&
+          typeof f.variable.maxWeight === "number"
+            ? { minWeight: f.variable.minWeight, maxWeight: f.variable.maxWeight }
+            : null,
       })),
     binaries,
     fetchedAt: new Date().toISOString(),
@@ -529,9 +539,13 @@ export async function materializeBundle(
   };
   fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), "utf8");
 
+  // Last, after every write AND the prune — the overlay must win over the wire.
+  const overlaid = applyBundleOverlay(dir);
+
   return {
     dir,
     presFP,
+    overlaid,
     etag: wire.etag ?? null,
     version: wire.version ?? null,
     // Which backend actually served the wire — meaningful on the brandId
@@ -545,6 +559,47 @@ export async function materializeBundle(
   };
 }
 
+// Copy `$SLIDEMIND_BUNDLE_OVERLAY/**` over a materialized bundle. Experiment-only
+// hook for the skill-optimization loop (LOOP_PLAN.md): it lets a run vary the
+// add-in-owned workflow/design docs without a deploy. Deliberately undocumented
+// in user-facing help. The wire re-syncs every text file on EVERY materialize
+// (and the prune deletes anything it doesn't own), so this re-applies each time.
+export function applyBundleOverlay(dir) {
+  const overlay = process.env.SLIDEMIND_BUNDLE_OVERLAY;
+  if (!overlay) return 0;
+  let copied = 0;
+  try {
+    if (!fs.statSync(overlay).isDirectory()) return 0;
+    fs.cpSync(overlay, dir, {
+      recursive: true,
+      force: true,
+      // Docs only (.md/.css): the bundle dir also holds lint-engine.mjs and
+      // capture-engine.mjs, which the CLI dynamic-imports — an overlay must
+      // never be able to swap executable code, and text files re-sync from the
+      // wire on every materialize so a doc overlay can't persist past the
+      // experiment (binaries would).
+      filter: (src) => {
+        let st;
+        try {
+          st = fs.lstatSync(src);
+        } catch {
+          return false; // dangling symlink — skip, never fail the materialize
+        }
+        if (st.isDirectory()) return true;
+        if (!/\.(md|css)$/i.test(src)) return false;
+        copied += 1;
+        return true;
+      },
+    });
+  } catch (err) {
+    // The overlay is an experiment convenience — a bad overlay must not break
+    // ready/build/push after an otherwise successful sync.
+    process.stderr.write(`bundle overlay skipped: ${err.message}\n`);
+    return 0;
+  }
+  return copied;
+}
+
 // Delete files the current sync doesn't own and collapse empty directories.
 // `expected` holds dir-relative paths exactly as `path.join` built them, so
 // the comparison is platform-consistent.

package/src/bridge/capture.mjs

@@ -114,6 +114,12 @@ export function buildCaptureInput(deckDir, bundleDir) {
       family: f.family,
       filename: path.basename(f.filename),
       bytesB64: fs.readFileSync(fontPath).toString("base64"),
+      // Face descriptors — the capture engine emits per-face @font-face
+      // weight/style rules from these (engine defaults 400/normal when a
+      // pre-descriptor meta.json omits them).
+      weight: f.weight,
+      style: f.style,
+      variable: f.variable ?? null,
     });
   }
 
@@ -214,3 +220,31 @@ export async function captureDeckLocally({ deckDir, bundleDir, onProgress }) {
   const input = buildCaptureInput(deckDir, bundleDir);
   return withBrowser((browser) => engine.captureDeck(browser, input, { onProgress }));
 }
+
+/**
+ * The `<Chart>` stand-in runtime the add-in exports from the SAME artifact
+ * (`chartPreview: { scripts: [{ filename, source }], tokensCss }`), for the
+ * host-free HTML preview (`slidemind build`, and the review gate that serves
+ * it). The CLI ships no chart source: the page inlines these before any slide
+ * is evaluated, exactly where the add-in's own page loads them.
+ *
+ * null when the bundle has no engine or the engine predates charts. That is
+ * never a silent degradation: such a bundle's lint engine (same deployment)
+ * rejects `<Chart>` as an unknown component before a page is ever built.
+ */
+export async function loadChartPreview(bundleDir) {
+  if (!bundleDir || !bundleHasCaptureEngine(bundleDir)) return null;
+  const enginePath = path.join(bundleDir, "capture-engine.mjs");
+  const version = readBundleMeta(bundleDir).captureEngineVersion ?? "0";
+  const engine = await import(
+    `${pathToFileURL(enginePath).href}?v=${encodeURIComponent(version)}`
+  );
+  const preview = engine.chartPreview;
+  if (!preview || !Array.isArray(preview.scripts)) return null;
+  return {
+    scripts: preview.scripts.filter(
+      (s) => s && typeof s.filename === "string" && typeof s.source === "string",
+    ),
+    tokensCss: typeof preview.tokensCss === "string" ? preview.tokensCss : "",
+  };
+}