slidemind 0.3.20 → 0.4.1

package/skills/search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: slidemind-search
-description: Discover, search, and reuse content from the active corporate design's engines — image/icon engines and slide libraries — across whatever environment the slidemind PowerPoint add-in is wired to, or from a local PowerPoint file on disk. Finds existing slides and brand imagery — from the engines or from a local .pptx — then reuses them either by inserting them live into an open PowerPoint or by folding them into a deck as native one-slide .pptx files that survive re-render. Use whenever the user asks to find or reuse an existing slide ("is there a slide on X in our library", "find the Q3 results slide", "drop in / reuse our pricing slide"), to reuse a slide from another presentation or deck on disk, to ask what's in a local .pptx file, to search the brand's icon/image engines, or to ask what slide or image libraries exist. Skip when the user wants to author NEW slide content from scratch — that is slidemind-create-slides — or to merely open, present, or rename a deck.
+description: Discover, search, and reuse content from the active corporate design's engines — image/icon engines and slide libraries — or from a local PowerPoint file on disk. Finds existing slides and brand imagery — from the engines or from a local .pptx — then reuses them either by inserting them live into an open PowerPoint or by folding them into a deck as native one-slide .pptx files that survive re-render. Use whenever the user asks to find or reuse an existing slide ("is there a slide on X in our library", "find the Q3 results slide", "drop in / reuse our pricing slide"), to reuse a slide from another presentation or deck on disk, to ask what's in a local .pptx file, to search the brand's icon/image engines, or to ask what slide or image libraries exist. Skip when the user wants to author NEW slide content from scratch — that is slidemind-create-slides — or to merely open, present, or rename a deck.
 ---
 
 # slidemind-search
@@ -41,8 +41,7 @@ identity):
   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.
+  Have them paste it to you and run it **verbatim**.
 
 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.
@@ -108,18 +107,20 @@ Follow `workflow/search.md` for the discipline; this is the CLI shape of its loo
    (`--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
+   there is no presId to scope. (`--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.
+2. **Choose the target + intent.** Slide engines (`subtype slide`), content collections 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**, and so are **template collections** (`subtype template`): their text is
+   placeholder, so query the structure the content needs ("loop diagram with 5 steps",
+   "three-column comparison"), never the topic. 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
@@ -133,8 +134,6 @@ Follow `workflow/search.md` for the discipline; this is the CLI shape of its loo
      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
@@ -151,6 +150,11 @@ Follow `workflow/search.md` for the discipline; this is the CLI shape of its loo
    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)**, and **cite the sources** (see
    the rule below) whenever you report results back.
+   **Slides the user picks; imagery you pick.** Before you reuse slide or template results, show
+   the user the candidates — the contact sheet path, or the numbered titles with score and source —
+   and ask which to reuse through your harness's question tool; reuse exactly their picks. When none
+   fit, search again with a different query or engine and ask again. An image or icon result you
+   pick yourself.
 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
@@ -172,7 +176,13 @@ Follow `workflow/search.md` for the discipline; this is the CLI shape of its loo
 ## 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.**
+— **reuse is JSX-free; reused slides land as native `.pptx` and stay native until the user asks to change one** (`workflow/search.md`).
+Then convert that one slide in place — `slidemind adopt decks/<slug>/.slidemind/slides/<NN-reused-…>.pptx --in-place` — and
+edit its jsx like any deck slide (create-slides → editing). **A picked template is a starting
+layout, not the answer:** when the user asked for slides about something ("build two slides on X
+from our templates"), that request is the ask to change them — adopt each picked template in place
+and fill it with the content the slide must carry; never stop at placeholder text. Plain reuse (the
+user wants the existing slide itself) stays native.
 
 - **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
@@ -185,7 +195,7 @@ A found slide can be reused two ways. Both extract the picked result(s) as nativ
 - **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
+  file into `decks/<slug>/.slidemind/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.
@@ -201,7 +211,7 @@ deck), skip discovery entirely — no host, no window, no engine:
    <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
+This writes the **same** `decks/<slug>/.slidemind/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>`.
@@ -227,6 +237,19 @@ download-result` — it writes the asset into the deck's `assets/`. That mechani
 icon-recolor descriptor and `--icon-color`) is documented where it's used, in
 `slidemind-create-slides`.
 
+**A download is a found image, not a promised one.** `download-result` registers what it fetched in
+the deck's image registry, with its engine provenance — and that is all it does. Registration
+creates **no** obligation to place the picture on any slide: an image you fetched to satisfy a
+generic illustration stays an ordinary sourced asset, sized and placed like any other. It becomes a
+binding obligation only if the **user** chose that exact result for that exact spot and it is
+recorded as an `assetUses` entry in the plan, which `slidemind-create-slides` owns.
+
+**Never fill someone else's obligation with a search result.** If a slide already carries an
+`original` use — an image the user supplied — it is satisfied by those bytes and nothing else.
+Searching for something that looks like it, downloading a close match, or generating a replacement
+is the one failure this whole path exists to prevent, whatever the draft looks like. A missing or
+changed source is repaired by restoring or re-importing it, never by substitution.
+
 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`
@@ -236,7 +259,7 @@ re-states the size, measured from the delivered bytes.)
 
 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
+existing slide into the same `decks/<slug>/.slidemind/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.
 
@@ -247,16 +270,16 @@ insert live, fold into a deck, engine fetch). You are the local harness — this
 
 | 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); each result may carry a `source:` link — **always cite it back** |
+| **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 per-user; `--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; each result may carry a `source:` link — **always cite it back** |
 | **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>` — 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) |
+| **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>/.slidemind/slides/NN-reused-*.pptx` (add `--to <searchWindow>` only on the relayed path, where extraction runs on the search's window) |
 | **read a local `.pptx`** (host-free — no engine, no window) | `slidemind read <file.pptx> --mode summary\|raw` — list/read a local file's slides in play order without a host; use the printed numbers as `--pick` for `add-slide --from` |
-| **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`) |
+| **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>/.slidemind/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>/.slidemind/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.