slidemind 0.1.3 → 0.1.4

package/CLAUDE.md

@@ -64,26 +64,30 @@ slidemind/
 ├── .claude-plugin/
 │   └── plugin.json               Claude Code plugin manifest
 ├── bin/
-│   └── slidemind.mjs             CLI dispatcher (presentations, download-bundle, init, build, build-pptx, push, search, install, pair/whoami/use/logout)
+│   └── slidemind.mjs             CLI dispatcher (presentations, download-bundle, init, build, build-pptx, push, ls engines, search, insert-slide, add-slide, install, pair/whoami/use/logout)
 ├── skills/                       canonical, installable skill payload — thin CLI workflow glue only
-│   └── create-slides/
-│       └── SKILL.md              the whole skill: host gate + intake/plan + create flow + CLI⇄in-app command map.
-│                                 Brand AND the authoring workflow craft (create/edit/composition/layouts/
-│                                 authoring/build-export) are READ from the materialized bundle — owned by the add-in.
+│   ├── create-slides/
+│   │   └── SKILL.md              authoring skill: host gate + intake/plan + create flow + CLI⇄in-app command map.
+│   │                             Brand AND the authoring workflow craft (create/edit/composition/layouts/
+│   │                             authoring/build-export) are READ from the materialized bundle — owned by the add-in.
+│   └── search/
+│       └── SKILL.md              engine-search + slide-reuse skill (installs as slidemind-search): host gate +
+│                                 discover → search → pick → reuse loop + CLI⇄in-app command map. The craft is READ
+│                                 from the bundle's workflow/search.md — owned by the add-in.
 ├── src/                          implementation of the slidemind CLI
-│   ├── bridge/                   add-in local-bridge: client.mjs, bundle.mjs (materialize), build-and-push.mjs (server render)
-│   ├── builders/                 build.mjs (HTML preview), resolve-skill.mjs (→ bundle), primitives.json (fallback)
-│   ├── mcp/                      MCP server: list/push + slidemind_search_engine / slidemind_download_result
+│   ├── bridge/                   add-in local-bridge: client.mjs, bundle.mjs (materialize), build-and-push.mjs (server render; native-slide splicing)
+│   ├── builders/                 build.mjs (HTML preview), review.mjs (spatial preview-review gate + local server), resolve-skill.mjs (→ bundle), lint.mjs (runs the add-in's engine)
+│   ├── mcp/                      MCP server: list/push + list_engines/search_engine/view_slide/insert_slide/add_slide_to_deck/download_result
 │   └── installers/               per-harness installers: claude.mjs, codex.mjs, opencode.mjs, lib.mjs
 ├── archive/                      retired code/assets (local exporter, icon library, brand design files) — NOT shipped
 ├── decks/                        the user's working decks; sources are slides/*.jsx, design via .bundle-ref.json
 ├── docs/slidemind-cli-connect/   the connect architecture (bridge contract, bundle, engine, phasing)
-└── test/                         node:test suites (bridge client/bundle/build-and-push/resolve-skill/lint/packaging)
+└── test/                         node:test suites (bridge client/bundle/build-and-push/resolve-skill/lint-wrapper/packaging/engine-search/native-slides/cli-dispatch/mcp-server)
 ```
 
-The skill at the **root** of `skills/` is deliberate: that's the layout Claude Code, Codex (0.128+), and opencode all expect for skill auto-discovery — `<harness-root>/skills/<name>/SKILL.md`. There's a single skill (`create-slides`); it gets copied into each harness as `slidemind-create-slides` and owns the user-facing plan / create / edit / render workflow. It is **brand-agnostic** — every brand rule lives in the per-CD bundle's `design.md`, which the skill points the agent at. (Pre-skills opencode versions used an `agent/` shim under `~/.config/opencode/`; the installer removes any leftover from those installs on every run.)
+The skills at the **root** of `skills/` are deliberate: that's the layout Claude Code, Codex (0.128+), and opencode all expect for skill auto-discovery — `<harness-root>/skills/<name>/SKILL.md`. There are **two** skills, each auto-discovered by `listSkills()` (no installer change to add one): `create-slides` (installs as `slidemind-create-slides`) owns the user-facing plan / create / edit / render workflow, and `search` (installs as `slidemind-search`) owns engine discovery + slide reuse (search → insert live / fold into a deck). Both are **brand-agnostic** — every brand rule lives in the per-CD bundle's `design.md` / `workflow/*.md`, which the skills point the agent at. (Pre-skills opencode versions used an `agent/` shim under `~/.config/opencode/`; the installer removes any leftover from those installs on every run.)
 
-We **do not** ship separate slash commands. Earlier versions had a top-level `commands/` directory that became `/slidemind:plan` etc. on Claude Code and `~/.codex/prompts/slidemind-*.md` on Codex. The Codex prompts mechanism is broken in 0.117+ ([openai/codex#15941](https://github.com/openai/codex/issues/15941)) and officially deprecated in favour of skills, so we collapsed everything into the skill itself. Re-running `slidemind init` actively wipes legacy command/prompt entries on every harness.
+We **do not** ship separate slash commands. Earlier versions had a top-level `commands/` directory that became `/slidemind:plan` etc. on Claude Code and `~/.codex/prompts/slidemind-*.md` on Codex. The Codex prompts mechanism is broken in 0.117+ ([openai/codex#15941](https://github.com/openai/codex/issues/15941)) and officially deprecated in favour of skills, so we collapsed everything into the skill itself. Re-running `slidemind init` actively wipes legacy command/prompt entries on every harness, and clears the materialized bundle cache (`bundleCacheRoot()`) so the next `build`/`push`/`download-bundle` re-fetches every design bundle fresh from the add-in.
 
 ## CLI surface
 
@@ -92,22 +96,26 @@ slidemind presentations            # list PowerPoint windows registered with the
 slidemind download-bundle [deck]   # materialize the active corporate design's bundle locally
 slidemind new <name>               # scaffold ./decks/<name>/
 slidemind build <deck>             # build self-contained HTML preview
+slidemind review <deck>            # spatial preview-review gate; blocks for approve/comments (host-free)
 slidemind build-pptx <deck>        # render native .pptx via the add-in (HOST REQUIRED)
 slidemind push <deck>              # render + push slides into a running PowerPoint (HOST REQUIRED)
-slidemind search "<query>"         # search the brand engine for imagery (HOST REQUIRED)
+slidemind ls engines               # list the live engine catalog (image + slide; --type/--subtype) (HOST REQUIRED)
+slidemind search "<query>"         # search an engine for imagery or slides (--engine/--intent/--top) (HOST REQUIRED)
+slidemind insert-slide [opts]      # reuse found slide(s) live into a window (--search/--pick/--to/--at) (HOST REQUIRED)
+slidemind add-slide [opts]         # fold found slide(s) into a deck as native .pptx (--search/--pick/--deck/--to/--at) (HOST REQUIRED)
 slidemind pair <code>              # pair with an add-in environment (copy from its "Connect CLI")
 slidemind whoami                   # list every paired environment (* = default)
 slidemind use <url|env>            # set the default environment
 slidemind logout [url|env]         # unpair one environment (--all unpairs every one)
-slidemind init --for <target>   # install skill into claude | codex | opencode | all
-slidemind uninstall --for <target>
+slidemind init --for <target>   # install skill into claude | codex | opencode | all (also clears the bundle cache)
+slidemind uninstall --for <target>   # remove skill + MCP server (also clears the bundle cache)
 ```
 
 `<deck>` resolves as: absolute path → `./<arg>` if it exists → `./decks/<arg>`. The decks directory is `./decks/` by default; override with `SLIDEMIND_DECKS=/abs/path`.
 
 **Multi-environment pairing.** The CLI stores one session **per backend** (`~/.config/slidemind/session.json`, v2 `{version, sessions[], default}`; the legacy single-record v1 shape is migrated on read). Pair once per environment (local / dev / prod) and every command **fans out** across all paired backends, tags each open window with its `env`, and **routes by the presentation's origin backend** automatically — no manual switching. Scope a command to one backend with `--backend <url|env>` (or `SLIDEMIND_BACKEND`). This is a developer convenience; a normal user pairs exactly one. See the memory note *CLI↔add-in: cloud relay + pairing*.
 
-**The design truth lives in the add-in, not the CLI.** The `.pptx` is rendered server-side over the local bridge (no local exporter), the corporate design is fetched as a bundle, and brand imagery comes from the add-in's engine. So `create`/`build-pptx`/`push`/`search` all hard-require an **open PowerPoint host with the slidemind add-in and an active corporate design**. See `docs/slidemind-cli-connect/`.
+**The design truth lives in the add-in, not the CLI.** The `.pptx` is rendered server-side over the local bridge (no local exporter), the corporate design is fetched as a bundle, brand imagery comes from the add-in's engine, and slide reuse (extract / insert / splice) executes in the add-in too. So `create`/`build-pptx`/`push`/`ls engines`/`search`/`insert-slide`/`add-slide` all hard-require an **open PowerPoint host with the slidemind add-in and an active corporate design**. The engine-search + slide-reuse wire contract is in `docs/slidemind-cli-connect/11-engine-search-slide-reuse.md`; see `docs/slidemind-cli-connect/` for the rest.
 
 ## Design system ground rules
 
@@ -118,7 +126,7 @@ The corporate design is **served by the add-in, not shipped by the CLI.** `slide
 - `layouts/*.jsx` + `layouts/layouts.css` — the closed layout palette to compose against.
 - `assets/`, `engines.json` — brand assets and the searchable image/icon engines.
 
-The skill is **brand-agnostic workflow guidance** and must not duplicate any brand rule — `scripts/check-skill-parity.mjs` (`npm run lint:parity`) fails the build if a hardcoded color, design token, or layout name leaks into a skill doc.
+Both skills are **brand-agnostic workflow guidance** and must not duplicate any brand rule — `scripts/check-skill-parity.mjs` (`npm run lint:parity`) scans **every** `skills/<name>/SKILL.md` and fails the build if a hardcoded color, design token, or layout name leaks into any skill doc.
 
 ## Sanity rules when editing slides
 
@@ -134,10 +142,14 @@ The skill is **brand-agnostic workflow guidance** and must not duplicate any bra
 slidemind download-bundle <deck>  # materialize the corporate design locally (do this first)
 slidemind build <deck>            # HTML preview (reads the materialized bundle)
 slidemind build <deck> --open     # HTML + open in browser
+slidemind review <deck>           # spatial preview-review gate; blocks until approve/comments (host-free)
 slidemind build-pptx <deck>       # native PPTX rendered server-side via the add-in (host required)
 slidemind push <deck>             # render + push into a running PowerPoint (host required)
-slidemind search "<query>"        # search the brand engine for imagery (host required)
-npm run lint:parity               # assert the skill carries no brand rules (CI guard)
+slidemind ls engines             # list the live engine catalog (image + slide) (host required)
+slidemind search "<query>"        # search an engine for imagery or slides (host required)
+slidemind insert-slide [opts]     # reuse found slide(s) live into a window (host required)
+slidemind add-slide [opts]        # fold found slide(s) into a deck as native .pptx (host required)
+npm run lint:parity               # assert EVERY skill (create-slides + search) carries no brand rules (CI guard)
 ```
 
-No linter beyond the parity guard, `node --test` for the suite, no package manager beyond npm itself. CI (`.github/workflows/test.yml`) runs the suite + parity guard on Linux, **Windows**, and macOS (Node 18 + 22) — the CLI promises native-Windows support, so keep it green there. The HTML preview is self-contained except for React + Babel-standalone pulled from a CDN on first load.
+No linter beyond the parity guard, `node --test` for the suite, no package manager beyond npm itself. Slide-JSX lint in `slidemind build` runs the **add-in's** capability-table engine, materialized into the bundle cache as `lint-engine.mjs` (+ `primitives.json`) and dynamic-imported by `src/builders/lint.mjs` — this repo owns no lint rules; they update on the next bundle fetch. CI (`.github/workflows/test.yml`) runs the suite + parity guard on Linux, **Windows**, and macOS (Node 18 + 22) — the CLI promises native-Windows support, so keep it green there. The HTML preview is self-contained except for React + Babel-standalone pulled from a CDN on first load.

package/README.md

@@ -49,7 +49,7 @@ Both drive the same add-in bridge, so an agent and a human end up producing the
 
 The CLI reaches PowerPoint through the add-in's **cloud relay** (no localhost, no certificates). Because of that, the machine running the CLI **does not have to be the same machine running PowerPoint** — pair once and commands route to wherever your add-in is registered.
 
-Commands that read the design, render, or push (`download-bundle`, `build-pptx`, `push`, `search`) **require an open PowerPoint host with the add-in and an active corporate design.** Only `new` and `build` (HTML preview) work fully offline.
+Commands that read the design, render, push, or reach an engine (`download-bundle`, `build-pptx`, `push`, `ls engines`, `search`, `insert-slide`, `add-slide`) **require an open PowerPoint host with the add-in and an active corporate design.** Only `new`, `build`, and `review` (HTML preview) work fully offline.
 
 ---
 
@@ -70,6 +70,8 @@ slidemind --version
 
 `slidemind init --for <claude|codex|opencode|all|none>` scopes the harness deployment. Use `none` to install the CLI only.
 
+> **Heads-up — first install downloads a headless Chrome.** slidemind renders decks by capturing slides with a local headless browser (then assembling the `.pptx` server-side), so `npm install -g slidemind` pulls a pinned Chromium (~150–300 MB) via `puppeteer`'s postinstall. Behind a corporate proxy/firewall this download can fail; set `HTTPS_PROXY` (and, if needed, `PUPPETEER_DOWNLOAD_BASE_URL`) so npm can reach it, or point `PUPPETEER_EXECUTABLE_PATH` at an existing Chrome/Edge. The browser lives in puppeteer's own cache, not the slidemind package.
+
 ### Windows
 
 slidemind runs on native Windows (PowerShell, Windows Terminal, or cmd) — no WSL or Git Bash required.
@@ -153,9 +155,13 @@ slidemind logout            # unpair this machine
 ```bash
 slidemind new my-deck             # scaffold ./decks/my-deck/
 slidemind build my-deck           # build a self-contained HTML preview (offline)
+slidemind review my-deck          # spatial preview review: leave comments / approve in the browser (offline)
 slidemind build-pptx my-deck      # render a native .pptx via the add-in (host required)
 slidemind push my-deck            # stream slides straight into an open PowerPoint (host required)
-slidemind search "shield"         # search the active design's brand engine (host required)
+slidemind ls engines              # list the active design's image + slide engines (host required)
+slidemind search "shield"         # search an engine for imagery or slides (host required)
+slidemind insert-slide ...        # reuse a found slide live into an open PowerPoint (host required)
+slidemind add-slide ...           # fold a found slide into a deck as a native .pptx (host required)
 ```
 
 Decks live under `./decks/` in your current working directory — one folder per deck: `decks/<name>/slides/*.jsx`. Override the location with `SLIDEMIND_DECKS=/abs/path`.
@@ -172,7 +178,9 @@ You don't hand-write OOXML or hardcode brand colors — slides are small `.jsx`
 
 Your agent (Claude Code, Codex, or opencode) auto-discovers the `slidemind-create-slides` skill, reads the active corporate design's rules from the add-in, writes the slide files, and renders + pushes them into PowerPoint for you. The skill owns the whole **plan → create → edit → render** workflow — there are no slash commands to memorize.
 
-The MCP server registered by `slidemind init` gives the agent direct tools to list open presentations, push decks, and search brand imagery.
+A second skill, `slidemind-search`, owns engine discovery and **slide reuse**: ask "is there a slide on X in our library?" or "drop in our pricing slide" and the agent searches the brand's image/slide engines, then either inserts a found slide live into PowerPoint or folds it into a deck as a native `.pptx`.
+
+The MCP server registered by `slidemind init` gives the agent direct tools to list open presentations, push decks, list engines, search for imagery or slides, view a result, insert a slide live, fold a slide into a deck, and download brand imagery.
 
 ---
 
@@ -181,17 +189,24 @@ The MCP server registered by `slidemind init` gives the agent direct tools to li
 ```text
 slidemind new <name>             Scaffold ./decks/<name>/
 slidemind build <deck>           Build a self-contained HTML preview (offline)
+slidemind review <deck>          Spatial preview review; blocks for approve/comments (offline)
 slidemind build-pptx <deck>      Render a native .pptx via the add-in        (host required)
 slidemind push <deck>            Build + push slides into an open PowerPoint  (host required)
-slidemind search "<query>"       Search the active design's brand engine      (host required)
+slidemind ls engines             List the live engine catalog (image + slide) (host required)
+slidemind search "<query>"       Search an engine for imagery or slides       (host required)
+                                 --engine <id> --intent auto|content|visual --top <N>
+slidemind insert-slide [opts]    Insert reused slide results live into a window (host required)
+                                 --search <id> --pick <n[,n,...]> --to <presId> [--at <N>]
+slidemind add-slide [opts]       Fold reused slide results into a deck as native .pptx (host required)
+                                 --search <id> --pick <n[,n,...]> --deck <deck> [--to <presId>] [--at <N>]
 slidemind download-bundle [deck] Materialize the active corporate design locally (host required)
 slidemind presentations          List PowerPoint windows registered with the add-in
 slidemind pair <code>            Pair with an add-in (copy the code from "Connect CLI")
 slidemind whoami                 Show paired environment(s)
 slidemind use <url|env>          Set the default environment
 slidemind logout [url|env]       Unpair an environment (--all unpairs every one)
-slidemind init --for <target>    Install the skill + MCP server into a harness
-slidemind uninstall --for <t>    Remove a previously-installed skill
+slidemind init --for <target>    Install the skill + MCP server into a harness (clears the bundle cache)
+slidemind uninstall --for <t>    Remove a previously-installed skill (clears the bundle cache)
 slidemind update [--for <t>]     Fetch the latest release and redeploy
 slidemind --help                 Full usage
 slidemind --version              Print version
@@ -207,6 +222,16 @@ slidemind --version              Print version
 | `slidemind build-pptx <deck>` | `decks/<deck>/<deck>.pptx` | An editable native PowerPoint file |
 | `slidemind push <deck>` | (streamed via the add-in) | Live insertion into an open PowerPoint window |
 
+### Reviewing before you export
+
+`slidemind review <deck>` opens the HTML preview in your browser with a comment overlay and **waits** until you decide:
+
+- **Click any element** on a slide to leave a comment pinned to that spot. Each comment is anchored to the exact slide source (`slides/<file>.jsx:line:col`), so your agent knows precisely what to change.
+- **Approve & continue** when it looks right — the command unblocks and your agent proceeds to the export you asked for (`push` / `build-pptx`).
+- **Send comments** to hand your notes back to the agent; it edits the cited files and re-runs `review`, where your previous notes appear as faded "ghost" pins so you can confirm each was addressed.
+
+It runs entirely offline (no open PowerPoint needed) — review happens *before* the native render. There's no copy-paste: the moment you approve or send comments in the browser, your coding agent picks up where it left off.
+
 ---
 
 ## Pushing slides into an open PowerPoint