slidemind 0.1.6 → 0.1.8

package/.claude-plugin/plugin.json

@@ -13,11 +13,5 @@
     "office-addin",
     "slidemind"
   ],
-  "skills": "./skills",
-  "mcpServers": {
-    "slidemind": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/src/mcp/server.mjs"]
-    }
-  }
+  "skills": "./skills"
 }

package/CLAUDE.md

@@ -9,7 +9,7 @@ This repository (`STATWORX/intern-slidemind-cli`) publishes **slidemind** — th
 The package contains two layers:
 
 1. **An installable skill** (canonical markdown + assets) that ships into a coding-agent harness so the agent knows how to plan, compose, and review slides on-brand — reading every brand rule from the add-in's design bundle.
-2. **A Node CLI + MCP server** (`slidemind`) that exposes the add-in bridge (render `.pptx`, push slides into an open window, search the brand engine) to the user and the agent directly.
+2. **A Node CLI** (`slidemind`) that exposes the add-in bridge (render `.pptx`, push slides into an open window, search the brand engine) to the user and the agent directly. The agent drives it by running `slidemind <command>` in its shell — there is no separate tool layer.
 
 Both drive the same add-in bridge, so an agent and a human end up producing the same artefact: native PowerPoint slides on the active corporate design.
 
@@ -64,25 +64,26 @@ slidemind/
 ├── .claude-plugin/
 │   └── plugin.json               Claude Code plugin manifest
 ├── bin/
-│   └── slidemind.mjs             CLI dispatcher (presentations, read, download-bundle, init, build, build-pptx, view-draft, push, ls engines, search, insert-slide, add-slide, install, pair/whoami/use/logout)
+│   └── slidemind.mjs             CLI dispatcher (ready, doctor, presentations, read, download-bundle, new, init, build, build-pptx, view-draft, 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              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.
+│   │   └── SKILL.md              authoring skill: stage-todo bootstrap + host gate + intake/plan + create flow +
+│   │                             the vocabulary→CLI command map (the harness-neutral verbs of the bundle's
+│   │                             workflow/flow.md). Brand AND the authoring workflow craft (flow/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.
+│                                 discover → search → pick → reuse loop + vocabulary→CLI 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; 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/read/push + list_engines/search_engine/view_slide/insert_slide/add_slide_to_deck/download_result
+│   ├── bridge/                   add-in local-bridge: client.mjs, bundle.mjs (materialize), build-and-push.mjs (server render; native-slide splicing), engine-download.mjs + recolor.mjs (image/icon fetch + recolour)
+│   ├── builders/                 build.mjs (HTML preview), review.mjs (spatial preview-review gate + local server; stable per-deck port, graceful fallback, tab reuse across rounds), plan.mjs (plan sign-off gate) + plan-overlay.js + plan-md.mjs (markdown→HTML) + gate-server.mjs (shared gate primitives), resolve-skill.mjs (→ bundle), lint.mjs (runs the add-in's engine)
 │   └── 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-wrapper/packaging/engine-search/native-slides/cli-dispatch/mcp-server)
+└── test/                         node:test suites (bridge client/bundle/build-and-push/resolve-skill/lint-wrapper/packaging/engine-search/native-slides/cli-dispatch/cli-download-result)
 ```
 
 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.)
@@ -92,10 +93,13 @@ We **do not** ship separate slash commands. Earlier versions had a top-level `co
 ## CLI surface
 
 ```bash
+slidemind ready [deck]             # one-shot session start: connection ladder + design resolution + bundle download + deck bind; --to/--force/--connect-only/--json (HOST REQUIRED)
+slidemind doctor                   # read-only connection diagnostics (ordered next-action ladder; does NOT materialize or bind — `ready` is the preflight)
 slidemind presentations            # list PowerPoint windows registered with the add-in
 slidemind read [presId]            # pull the current content of an open presentation (--mode summary|raw) (HOST REQUIRED)
 slidemind download-bundle [deck]   # materialize the active corporate design's bundle locally
-slidemind new <name>               # scaffold ./decks/<name>/
+slidemind new <name>               # scaffold ./decks/<name>/ (auto-binds to the open design when unambiguous + bundle already materialized; --to/--no-bind)
+slidemind plan <deck>              # plan sign-off gate on <deck>/plan.md; markdown editor + live preview + overall feedback, blocks for approve/comments (host-free)
 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)
@@ -110,7 +114,7 @@ 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 (also clears the bundle cache)
-slidemind uninstall --for <target>   # remove skill + MCP server (also clears the bundle cache)
+slidemind uninstall --for <target>   # remove the skill (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`.
@@ -136,12 +140,14 @@ Both skills are **brand-agnostic workflow guidance** and must not duplicate any
 - No hardcoded colors, sizes, or fonts in slide files. Everything goes through the tokens in the bundle's `corporate-design.css`.
 - **Never add a layout.** The layout palette is the closed set in `<bundle>/layouts/` — read-only. Need markup a layout doesn't expose? Build it as Mode B children of the blank-content layout the bundle's `design.md` names — never a new layout file.
 - Re-run `slidemind push <deck>` (or `build-pptx`) after any `.jsx` change — the .pptx is rendered server-side, not edited by hand; the HTML preview is generated.
-- For generic concept icons/images, use the brand engine: `slidemind_search_engine` → pick a result → `slidemind_download_result` (writes into the deck's `assets/`). Don't invent SVGs. The full authoring workflow is read from the materialized bundle's `workflow/*.md` (owned by the add-in).
+- For generic concept icons/images, use the brand engine: `slidemind search` → pick a result → `slidemind download-result` (writes into the deck's `assets/`). Don't invent SVGs. The full authoring workflow is read from the materialized bundle's `workflow/*.md` (owned by the add-in).
 
 ## Build commands (terse reference)
 
 ```bash
-slidemind download-bundle <deck>  # materialize the corporate design locally (do this first)
+slidemind ready <deck>            # do this first: connection ladder + resolve the open design + materialize its bundle + bind the deck (host required)
+slidemind download-bundle <deck>  # lower-level: materialize-only (no connection ladder, no bind) — `ready` now covers this
+slidemind plan <deck>             # plan sign-off gate on <deck>/plan.md; blocks until approve/comments (host-free)
 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)

package/README.md

@@ -10,7 +10,7 @@ Connect **Claude Code, Codex, and opencode** to the **slidemind PowerPoint add-i
 
 slidemind is a **thin client**. The corporate design, the layout palette, and the native `.pptx` render all live in the **slidemind PowerPoint add-in** — this package is the bridge that lets a coding agent drive it. It ships two things:
 
-1. **A CLI + MCP server** that talks to a running PowerPoint over the add-in's cloud bridge — render native `.pptx`, push slides straight into an open window, and search the active design's brand engine for imagery.
+1. **A CLI** that talks to a running PowerPoint over the add-in's cloud bridge — render native `.pptx`, push slides straight into an open window, and search the active design's brand engine for imagery. The agent drives it by running `slidemind <command>` in its shell.
 2. **An installable skill** for Claude Code, Codex, and opencode — so the agent in your editor knows how to plan, compose, and review slides on-brand from the design bundle the add-in serves.
 
 Both drive the same add-in bridge, so an agent and a human end up producing the same artefact: native PowerPoint slides on the active corporate design.
@@ -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, 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.
+Commands that read the design, render, push, or reach an engine (`ready`, `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.** `build`, `review`, and `view-draft` work fully offline against a previously materialized bundle. `new` scaffolds offline too; when you're paired and a design is open it also best-effort binds the new deck (otherwise it just scaffolds and hints to run `slidemind ready <slug>`).
 
 ---
 
@@ -59,7 +59,7 @@ The package is published to **public npm** as [`slidemind`](https://www.npmjs.co
 
 ```bash
 npm install -g slidemind
-slidemind init --for all      # register the MCP server + skill into Claude Code / Codex / opencode
+slidemind init --for all      # deploy the skill into Claude Code / Codex / opencode
 ```
 
 Then confirm it's on your `PATH`:
@@ -155,7 +155,8 @@ slidemind logout            # unpair this machine
 ## Quick start
 
 ```bash
-slidemind new my-deck             # scaffold ./decks/my-deck/
+slidemind ready                   # one-shot session start: check the connection, resolve the open design, fetch its bundle (host required)
+slidemind new my-deck             # scaffold ./decks/my-deck/ (auto-binds to the open design when one is available)
 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)
@@ -167,6 +168,8 @@ slidemind insert-slide ...        # reuse a found slide live into an open PowerP
 slidemind add-slide ...           # fold a found slide into a deck as a native .pptx (host required)
 ```
 
+`slidemind ready` is the one command to run at the start of a session — it verifies the connection, resolves whichever corporate design the add-in has open, and downloads its bundle in a single call, printing exactly one next step if anything's missing. Continuing an existing deck? `slidemind ready <deck>` also binds the deck to that design.
+
 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`.
 
 You don't hand-write OOXML or hardcode brand colors — slides are small `.jsx` files that compose the layouts and tokens the add-in serves. The render happens server-side in PowerPoint; `slidemind build` gives you a quick HTML preview while you iterate.
@@ -183,14 +186,18 @@ Your agent (Claude Code, Codex, or opencode) auto-discovers the `slidemind-creat
 
 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.
+Under the hood the skill just runs the `slidemind` CLI in the agent's shell — 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 are all plain subcommands (see the command reference below).
 
 ---
 
 ## Command reference
 
 ```text
-slidemind new <name>             Scaffold ./decks/<name>/
+slidemind ready [deck]           One-shot session start: connect + resolve the open design + fetch bundle + bind deck (host required)
+                                 --to <presId> --force --connect-only --json
+slidemind new <name>             Scaffold ./decks/<name>/ (auto-binds to the open design when available)
+                                 --to <presId> --no-bind
+slidemind plan <deck>            Plan sign-off gate on <deck>/plan.md; blocks for approve/comments (offline)
 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)
@@ -200,11 +207,15 @@ slidemind push <deck>            Build + push slides into an open PowerPoint  (h
 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 view-slide [opts]      Fetch a slide result's preview image to a file (host required)
+                                 --search <id> --pick <n> --to <presId> [--out <dir>]
 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 download-result [opts] Download image/icon result(s) into a deck's assets/ (host required)
+                                 --search <id> --pick <n[,n,...]> --deck <deck> --to <presId> [--icon-color <hex[,hex,...]>]
+slidemind download-bundle [deck] Materialize the active corporate design locally (host required; lower-level — `ready` covers this)
 slidemind presentations          List PowerPoint windows registered with the add-in
 slidemind read [presId]          Pull the current content of an open presentation (host required)
                                  --mode summary|raw (default raw) [--to <presId>] [--json]
@@ -212,7 +223,7 @@ slidemind pair <code>            Pair with an add-in (copy the code from "Connec
 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 (clears the bundle cache)
+slidemind init --for <target>    Install the skill 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
@@ -293,7 +304,7 @@ Equivalently: `npm install -g slidemind@latest && slidemind init --for all`.
 |---|---|
 | `slidemind: command not found` (or not recognized) | The npm global bin isn't on your `PATH`. Run `npm prefix -g` and add its `bin` (Windows: `%APPDATA%\npm`) to `PATH`, or use `npx slidemind`. |
 | PowerShell: *running scripts is disabled* | npm's `.ps1` shim hit the execution policy. Use `slidemind.cmd <command>`, or `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`. |
-| `slidemind presentations` is empty | The add-in isn't reachable. Open PowerPoint with the slidemind add-in and an active corporate design; click the task pane once to re-register, then retry. |
+| A command can't reach PowerPoint (empty `presentations`, "no host", nothing seems connected) | Run **`slidemind ready`** — it checks pairing, the connection, the CLI version, and open windows in one shot and prints the single next step to take (open PowerPoint / click the pane / pair / update). |
 | `slidemind presentations` is empty right after pairing (PowerPoint + add-in already open) | The just-paired task pane never registered. **Restart the add-in** — close the slidemind task pane and reopen it from the ribbon (or reopen the presentation). The pairing wizard doesn't prompt for this. |
 | `Not paired` | In the add-in, open **Settings → General → Connect CLI**, press **Pair**, and run the shown `slidemind pair <code>`. Codes are one-time and expire — generate a fresh one if it's stale. |
 | `build-pptx` / `push` / `search` error about no host | These require an open PowerPoint host with an active corporate design. `slidemind build` (HTML) is the only fully-offline preview. |
@@ -304,7 +315,7 @@ Equivalently: `npm install -g slidemind@latest && slidemind init --for all`.
 ## Uninstall
 
 ```bash
-slidemind uninstall --for all    # remove the skill + MCP registration from each harness
+slidemind uninstall --for all    # remove the skill from each harness
 npm uninstall -g slidemind       # remove the CLI
 ```