slidemind 0.1.7 → 0.1.9

package/CLAUDE.md

@@ -78,7 +78,8 @@ slidemind/
 │                                 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), engine-download.mjs + recolor.mjs (image/icon fetch + recolour)
-│   ├── 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)
+│   ├── 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)
+│   ├── pptx/                     host-free local-.pptx support (fflate-based): read-local.mjs (read a file's slides — output-identical to the host read), slide-swap.mjs (fold a picked slide into a deck as native .pptx — swaps it into the lowest slot the splicer reads, then prunes the package to that slide's dependency closure so a slice carries only what it needs), zip.mjs + ooxml.mjs (shared unzip/order helpers)
 │   └── 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
@@ -96,9 +97,10 @@ We **do not** ship separate slash commands. Earlier versions had a top-level `co
 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 read [presId|file.pptx]  # pull an open presentation's content (presId; HOST REQUIRED) OR read a local .pptx on disk (file path; host-free) — same per-slide output (--mode summary|raw)
 slidemind download-bundle [deck]   # materialize the active corporate design's bundle locally
 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)
@@ -107,7 +109,7 @@ slidemind push <deck>              # render + push slides into a running PowerPo
 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 add-slide [opts]         # fold slide(s) into a deck as native .pptx — from an engine (--search/--pick/--deck/--to/--at; HOST REQUIRED) or a local file (--from <file.pptx>/--pick/--deck/--at; host-free, mutually exclusive with --search)
 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
@@ -126,10 +128,10 @@ slidemind uninstall --for <target>   # remove the skill (also clears the bundle
 
 The corporate design is **served by the add-in, not shipped by the CLI.** `slidemind download-bundle` materializes it (keyed by the deck's `.bundle-ref.json`) into `${XDG_CACHE_HOME:-~/.cache}/slidemind/bundles/<presFP>/`:
 
-- `design.md` — the **single source of brand rules** (tokens, type scale, layout palette, the authoring contract, and a `### Brand Image Sources` block). **Read it; never restate it.**
+- `design.md` — the **single source of brand rules** (tokens, type scale, layout palette, the authoring contract). **Read it; never restate it.**
 - `corporate-design.css` — the design tokens to link/inline and compose with token classes.
 - `layouts/*.jsx` + `layouts/layouts.css` — the closed layout palette to compose against.
-- `assets/`, `engines.json` — brand assets and the searchable image/icon engines.
+- `assets/` — brand assets. (Engine discovery is **live-only** via `slidemind ls engines` — new backends no longer ship an engine list on the bundle wire; `engines.json` is still written for older backends but is `[]` going forward.)
 
 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.
 
@@ -146,17 +148,18 @@ Both skills are **brand-agnostic workflow guidance** and must not duplicate any
 ```bash
 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)
 slidemind build-pptx <deck>       # native PPTX rendered server-side via the add-in (host required)
 slidemind view-draft <deck>       # per-slide PNG draft preview, no push/no .pptx — the agent's look-before-review self-check (host-free once the bundle is cached)
 slidemind push <deck>             # render + push into a running PowerPoint (host required)
-slidemind read [presId]           # pull current content of an open presentation (--mode summary|raw) (host required)
+slidemind read [presId|file.pptx] # pull current content of an open presentation (presId; host required) OR read a local .pptx (file path; host-free) (--mode summary|raw)
 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)
+slidemind add-slide [opts]        # fold slide(s) into a deck as native .pptx — engine (--search; host required) or local file (--from <file.pptx>; host-free)
 npm run lint:parity               # assert EVERY skill (create-slides + search) carries no brand rules (CI guard)
 ```
 

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, 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>`).
+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. Reading a local PowerPoint file (`read <file.pptx>`) or folding a slide from one into a deck (`add-slide --from <file.pptx>`) is host-free too — no PowerPoint, no pairing, no bundle needed. `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>`).
 
 ---
 
@@ -100,7 +100,18 @@ The global install lands in `%APPDATA%\npm`, which the Node installer puts on yo
    slidemind --version
    ```
 
-If `npm install -g` fails with `EACCES`, you've hit a permissions issue with a system-owned npm prefix — the cleanest fix is a user-owned Node from [Homebrew](https://brew.sh) or [nvm](https://github.com/nvm-sh/nvm) (avoid `sudo npm`). Credentials are stored under `~/.config/slidemind/`.
+If `npm install -g` fails with `EACCES` on `/usr/local/lib/node_modules`, you've hit a permissions issue with the official macOS Node installer: npm's global package directory is system-owned. Avoid `sudo npm`; it can leave root-owned files in npm's cache and makes later updates brittle. Either install a user-owned Node with [Homebrew](https://brew.sh) or [nvm](https://github.com/nvm-sh/nvm), or move npm's global prefix into your home directory:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+npm install -g slidemind
+slidemind init --for all
+```
+
+Credentials are stored under `~/.config/slidemind/`.
 
 ### Linux
 
@@ -161,11 +172,11 @@ 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 read <presId>           # pull the current content of an open presentation (host required)
+slidemind read <presId|file.pptx> # read an open presentation (host required) or a local .pptx on disk (host-free)
 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)
+slidemind add-slide ...           # fold a found slide — or one from a local .pptx (--from, host-free) — into a deck as a native .pptx
 ```
 
 `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.
@@ -197,6 +208,7 @@ slidemind ready [deck]           One-shot session start: connect + resolve the o
                                  --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)
@@ -210,13 +222,14 @@ slidemind view-slide [opts]      Fetch a slide result's preview image to a file
                                  --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)
+slidemind add-slide [opts]       Fold slide(s) into a deck as native .pptx — from an engine (host required) or a local file (host-free)
                                  --search <id> --pick <n[,n,...]> --deck <deck> [--to <presId>] [--at <N>]
+                                 --from <file.pptx> --pick <n[,n,...]> --deck <deck> [--at <N>]   (local file; host-free; not with --search)
 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)
+slidemind read [presId|file.pptx] Read an open presentation (presId; host required) or a local .pptx on disk (file path; host-free)
                                  --mode summary|raw (default raw) [--to <presId>] [--json]
 slidemind pair <code>            Pair with an add-in (copy the code from "Connect CLI")
 slidemind whoami                 Show paired environment(s)
@@ -307,7 +320,7 @@ Equivalently: `npm install -g slidemind@latest && slidemind init --for all`.
 | `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. |
-| `EACCES` on `npm install -g` (macOS/Linux) | Don't `sudo npm`. Use a user-owned Node via [nvm](https://github.com/nvm-sh/nvm) or Homebrew, or set a user-writable npm prefix. |
+| `EACCES` on `npm install -g` (macOS/Linux) | Don't `sudo npm`. Use a user-owned Node via [nvm](https://github.com/nvm-sh/nvm) or Homebrew, or run `mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global`, add `~/.npm-global/bin` to `PATH`, then retry. |
 
 ---