slidemind 0.1.5 → 0.1.6

package/CLAUDE.md

@@ -64,7 +64,7 @@ slidemind/
 ├── .claude-plugin/
 │   └── plugin.json               Claude Code plugin manifest
 ├── bin/
-│   └── slidemind.mjs             CLI dispatcher (presentations, download-bundle, init, build, build-pptx, push, ls engines, search, insert-slide, add-slide, install, pair/whoami/use/logout)
+│   └── 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)
 ├── 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.
@@ -77,7 +77,7 @@ slidemind/
 ├── 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/push + list_engines/search_engine/view_slide/insert_slide/add_slide_to_deck/download_result
+│   ├── mcp/                      MCP server: list/read/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
@@ -93,11 +93,13 @@ We **do not** ship separate slash commands. Earlier versions had a top-level `co
 
 ```bash
 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 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 view-draft <deck>        # render the deck's slides to per-slide PNGs so the agent can look before review; no push, no .pptx (host-free once the bundle is materialized)
 slidemind push <deck>              # render + push slides into a running PowerPoint (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)
@@ -144,7 +146,9 @@ 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 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)

package/README.md

@@ -128,21 +128,23 @@ npx slidemind <command>
 
 The CLI talks to PowerPoint through the add-in's cloud relay, so you pair once per machine.
 
-1. In PowerPoint, open the **slidemind add-in** task pane and click **"Connect CLI"**.
-2. It shows a one-time command. Copy and run it:
+1. In PowerPoint, open the **slidemind add-in** task pane → **Settings → General → Connect CLI**, and press **Pair**.
+2. It shows a one-time command (it expires in ~10 min — press **Pair** again for a fresh one). Copy and run it:
 
    ```bash
    slidemind pair <code>
    ```
 
-3. Verify the link:
+3. **Restart the add-in once.** Pairing turns CLI integration on, but the task pane that's already running may not pick up the connection — so close the slidemind task pane and reopen it from the ribbon (if needed, reopen the presentation). The wizard doesn't prompt for this, but a freshly-booted pane is what registers your window with the CLI.
+
+4. Verify the link:
 
    ```bash
    slidemind whoami          # lists the paired environment(s)
    slidemind presentations   # lists open PowerPoint windows the add-in sees
    ```
 
-If `slidemind presentations` is empty, the add-in isn't reachable — open PowerPoint with the slidemind add-in and an active corporate design, then retry.
+If `slidemind presentations` is empty even though PowerPoint is open with the add-in and an active corporate design, restart the add-in (step 3) and retry.
 
 ```bash
 slidemind logout            # unpair this machine
@@ -158,6 +160,7 @@ 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 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)
@@ -191,6 +194,8 @@ 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 view-draft <deck>      Render slides to per-slide PNGs, no push — look before review (offline once cached)
+                                 --to <presId> --out <dir> --open
 slidemind push <deck>            Build + push slides into an open PowerPoint  (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)
@@ -201,6 +206,8 @@ slidemind add-slide [opts]       Fold reused slide results into a deck as native
                                  --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 read [presId]          Pull the current content of an open presentation (host required)
+                                 --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)
 slidemind use <url|env>          Set the default environment
@@ -287,7 +294,8 @@ 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. |
-| `Not paired` | Run `slidemind pair <code>` using the code from the add-in's **"Connect CLI"**. Codes are one-time and expire — generate a fresh one if it's stale. |
+| `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. |
 

package/bin/slidemind.mjs

@@ -10,6 +10,7 @@
 //   slidemind build <deck>            build self-contained HTML deck
 //   slidemind review <deck>           spatial preview-review gate (blocks for approve/comments)
 //   slidemind build-pptx <deck>       render the deck as native .pptx (via the add-in)
+//   slidemind view-draft <deck>       render the deck's slides to per-slide PNGs (no push)
 //   slidemind uninstall --for <target>
 //   slidemind update [--for <target>] [--ref <version>]
 //                                       npm install -g slidemind@latest + redeploy
@@ -52,6 +53,12 @@ function printHelp() {
       `  slidemind build-pptx <deck>      Export native .pptx via the add-in (requires an open host)\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --out <path>    output path (default <deck>/<deck>.pptx)\n` +
+      `  slidemind view-draft <deck>      Render the deck's slides to per-slide PNGs (no push, no .pptx)\n` +
+      `                                     so the agent can look before review; host-free once the\n` +
+      `                                     bundle is materialized\n` +
+      `                                     --to <presId>   window to fetch the bundle from (only if not cached)\n` +
+      `                                     --out <dir>     output dir (default <deck>/.draft-preview/)\n` +
+      `                                     --open          open each rendered PNG\n` +
       `  slidemind search "<query>"       Search an engine for images or slides (requires an open host)\n` +
       `                                     --engine <id>   engine to search (default: first image engine; required for slides)\n` +
       `                                     --intent <i>    auto | content | visual (slide engines)\n` +
@@ -77,6 +84,12 @@ function printHelp() {
       `                                     --to <presId>   target a specific window\n` +
       `                                     --force         re-download even if the cached bundle is current\n` +
       `  slidemind presentations          List PowerPoint windows registered with the add-in\n` +
+      `  slidemind doctor                 Diagnose CLI/add-in pairing, backend, and pane readiness\n` +
+      `                                     --json          print machine-readable status\n` +
+      `  slidemind read [presId]          Pull the current content of an open presentation (requires a host)\n` +
+      `                                     --mode <m>      summary | raw (default: raw)\n` +
+      `                                     --to <presId>   target a specific window (required if >1 open)\n` +
+      `                                     --json          print the raw content payload\n` +
       `  slidemind push <deck> [opts]     Build deck and push slides into a running PowerPoint\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --at <index>    insert after slide N (0-based); default = append\n` +
@@ -247,6 +260,87 @@ async function cmdBuildPptx(rest) {
   }
 }
 
+function dataUriToPng(dataUri) {
+  const m = /^data:image\/png;base64,(.+)$/.exec(dataUri || "");
+  return m ? Buffer.from(m[1], "base64") : null;
+}
+
+async function cmdViewDraft(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "view-draft");
+  let to = null;
+  let outDir = null;
+  let open = false;
+  for (let i = 0; i < passthrough.length; i++) {
+    const a = passthrough[i];
+    if (a === "--to") {
+      to = passthrough[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--out" || a === "-o") {
+      outDir = passthrough[++i];
+      if (!outDir) fail("--out expects a directory");
+    } else if (a === "--open") {
+      open = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  const deckDir = resolveDeckArg(deck);
+  if (!fs.existsSync(path.join(deckDir, "slides"))) {
+    fail(`expected 'slides/' folder in ${deckDir}`);
+  }
+  // Draft previews are produced locally by the add-in's shipped capture engine
+  // (no push, no .pptx) — the same module that hosts the render+push path.
+  const mod = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "build-and-push.mjs")).href
+  );
+  const result = await mod.viewDraft(deckDir, {
+    presentationId: to,
+    onProgress: renderProgressPrinter(),
+  });
+
+  const previewDir = outDir
+    ? path.resolve(process.cwd(), outDir)
+    : path.join(deckDir, ".draft-preview");
+  fs.mkdirSync(previewDir, { recursive: true });
+
+  const written = [];
+  for (const slide of result.slides ?? []) {
+    const png = slide.dataUri ? dataUriToPng(slide.dataUri) : null;
+    if (png) {
+      const stem = slide.fileName.replace(/\.[^.]+$/, "");
+      const file = path.join(previewDir, `${stem}.png`);
+      fs.writeFileSync(file, png);
+      written.push(file);
+      const flag = slide.status === "degraded" ? " (DEGRADED)" : "";
+      process.stdout.write(`  ${slide.fileName}${flag} → ${file}\n`);
+      if (slide.note) process.stderr.write(`    note: ${slide.note}\n`);
+    } else {
+      process.stdout.write(`  ${slide.fileName} — ${slide.note ?? slide.status}\n`);
+    }
+  }
+  if (written.length === 0) {
+    process.stdout.write(
+      "No draft preview images were produced (no freeform slides to capture).\n",
+    );
+  } else {
+    process.stdout.write(
+      `Wrote ${written.length} draft preview${written.length === 1 ? "" : "s"} to ${previewDir} — NOT pushed. ` +
+        "Fix anything visibly wrong in the JSX, then re-run, or 'slidemind review' / 'push' when sound.\n",
+    );
+  }
+  for (const w of result.warnings ?? []) {
+    process.stderr.write(`  warning: ${w}\n`);
+  }
+  if (open && written.length > 0) {
+    const { openInBrowser } = await import(
+      pathToFileURL(path.join(BUILDERS_DIR, "build.mjs")).href
+    );
+    for (const file of written) openInBrowser(file);
+  }
+}
+
 async function cmdSearch(rest) {
   let asJson = false;
   let to = null;
@@ -298,7 +392,7 @@ async function cmdSearch(rest) {
   const bundle = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
   );
-  const registry = await client.requireHost();
+  const registry = await client.requirePaneHost();
   // The engine is per-user, not window-bound — so search just attaches to any
   // connected window (preferring a live one). No "which window?" prompt; pass
   // --to only to pin a specific one. The chosen window is printed below so
@@ -522,7 +616,7 @@ async function cmdInsertSlide(rest) {
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
-  const registry = await client.requireHost();
+  const registry = await client.requirePaneHost();
   const entry = client.pickPresentationEntry(registry, to);
   const res = await client.insertSlideLive({
     presId: entry.presId,
@@ -583,7 +677,7 @@ async function cmdAddSlide(rest) {
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
-  const registry = await client.requireHost();
+  const registry = await client.requirePaneHost();
   // The searchId is presentation-scoped, so --to targets the window the search
   // ran on. Without it, a registry with >1 open window is a dead-end.
   const entry = client.pickPresentationEntry(registry, to);
@@ -656,7 +750,7 @@ async function cmdDownloadBundle(rest) {
   const deckRef = positional[0]
     ? bundle.readDeckBundleRef(resolveDeckArg(positional[0]))
     : null;
-  const registry = await client.requireHost();
+  const registry = await client.requireRenderHost();
   const entry = client.pickPresentationEntry(registry, to, {
     preferBrandId: deckRef?.presFP ?? null,
   });
@@ -714,7 +808,185 @@ async function cmdPresentations(rest) {
   for (const p of list) {
     const label = p.title || p.fileName || "(untitled)";
     const env = p.env ? `[${p.env}]\t` : "";
-    process.stdout.write(`${p.presId}\t${env}${label}\n`);
+    const state =
+      p.connectionState ||
+      (p.connected === false || p.suspendedAt ? "suspended" : "connected");
+    const design = p.designState ? `\tcd:${p.designState}` : "";
+    process.stdout.write(`${p.presId}\t${env}${label}\t${state}${design}\n`);
+  }
+}
+
+function publicConnectionStatus(status, client) {
+  return {
+    paired: status.paired,
+    backendCount: status.backendCount,
+    backends: (status.backends ?? []).map((b) => ({
+      env: b.env,
+      ok: b.ok,
+      readinessV1: b.readinessV1 === true,
+      capabilities: b.capabilities ?? null,
+      error: b.error,
+      summary: b.summary ?? null,
+      presentations: (b.presentations ?? []).map(client.toPublicPresentation),
+    })),
+    presentations: (status.presentations ?? []).map(client.toPublicPresentation),
+  };
+}
+
+function connectionNextAction(pub) {
+  if (!pub.paired) {
+    return 'Not paired. In the add-in open Settings → General → Connect CLI, press Pair, then run the shown `slidemind pair <code>`.';
+  }
+  if ((pub.backends ?? []).every((b) => !b.ok)) {
+    return "Every paired backend is unreachable. Check network/VPN/backend status, or re-pair if the environment moved.";
+  }
+  if ((pub.presentations ?? []).length === 0) {
+    return "No PowerPoint window is registered. Open PowerPoint, load the slidemind add-in, and activate or create a corporate design.";
+  }
+  const renderReady = pub.presentations.some(
+    (p) =>
+      p.capabilities?.render === true ||
+      (!p.connectionState && p.connected !== false) ||
+      p.designState === "ready",
+  );
+  if (!renderReady) {
+    return "PowerPoint is connected, but no window is render-ready. Wait for corporate design matching or activate/create a corporate design.";
+  }
+  const paneReady = pub.presentations.some(
+    (p) =>
+      p.capabilities?.paneOps === true ||
+      ((!p.connectionState || p.connectionState === "connected") &&
+        p.connected !== false &&
+        !p.suspendedAt),
+  );
+  if (!paneReady) {
+    return "Rendering is available, but pane operations are suspended. Bring PowerPoint forward and click/reopen the slidemind pane before push/search/read.";
+  }
+  return "Ready.";
+}
+
+async function cmdDoctor(rest) {
+  const asJson = rest.includes("--json");
+  const cfg = await loadBridgeModule("config");
+  const sessions = cfg.readSessions();
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  if (sessions.length === 0) {
+    const pub = {
+      paired: false,
+      backendCount: 0,
+      backends: [],
+      presentations: [],
+      nextAction: connectionNextAction({ paired: false }),
+    };
+    process[asJson ? "stdout" : "stderr"].write(
+      asJson ? `${JSON.stringify(pub, null, 2)}\n` : `${pub.nextAction}\n`,
+    );
+    return;
+  }
+  const status = publicConnectionStatus(await client.connectionStatus(), client);
+  status.nextAction = connectionNextAction(status);
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(`Paired backends: ${status.backendCount}\n`);
+  for (const b of status.backends) {
+    process.stdout.write(
+      `  ${b.env}: ${b.ok ? "reachable" : `unreachable — ${b.error}`}` +
+        (b.readinessV1 ? " (readiness)" : " (legacy)") +
+        `\n`,
+    );
+  }
+  if (status.presentations.length === 0) {
+    process.stdout.write("Open presentations: none\n");
+  } else {
+    process.stdout.write("Open presentations:\n");
+    for (const p of status.presentations) {
+      const label = p.title || p.fileName || "(untitled)";
+      const state =
+        p.connectionState ||
+        (p.connected === false || p.suspendedAt ? "suspended" : "connected");
+      const design = p.designState || (p.brandId ? "ready" : "unknown");
+      const caps = p.capabilities
+        ? ` render:${p.capabilities.render === true ? "yes" : "no"} pane:${p.capabilities.paneOps === true ? "yes" : "no"}`
+        : "";
+      process.stdout.write(
+        `  ${p.presId}\t${p.env ? `[${p.env}] ` : ""}${label}\t${state}\tcd:${design}${caps}\n`,
+      );
+    }
+  }
+  process.stdout.write(`Next action: ${status.nextAction}\n`);
+}
+
+// Pull the current content of an open presentation. Content is window-bound, so
+// pick exactly one window (positional presId or --to; pickPresentationEntry errors
+// listing the windows if several are open and none was named). `--mode summary`
+// prints a per-slide outline; default `raw` prints each slide's plain text.
+async function cmdRead(rest) {
+  let presId = null;
+  let mode = "raw";
+  let asJson = false;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--mode") {
+      const next = rest[++i];
+      if (next !== "summary" && next !== "raw") {
+        fail(`--mode expects 'summary' or 'raw', got '${next ?? ""}'`);
+      }
+      mode = next;
+    } else if (a === "--to") {
+      presId = rest[++i];
+      if (!presId) fail("--to expects a presId");
+    } else if (a === "--json") {
+      asJson = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else if (!presId) {
+      presId = a; // positional presId
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  const registry = await client.requirePaneHost();
+  const entry = client.pickPresentationEntry(registry, presId);
+  const res = await client.getPresentationContent({
+    presId: entry.presId,
+    mode,
+    backendURL: entry.backendURL ?? null,
+  });
+  if (!res?.ok) {
+    fail(`read failed: ${res?.error ?? "unknown error"}`);
+  }
+  if (asJson) {
+    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+    return;
+  }
+  const slides = Array.isArray(res.slides) ? res.slides : [];
+  if (slides.length === 0) {
+    process.stderr.write("(presentation has no slides)\n");
+    return;
+  }
+  if (res.mode === "summary") {
+    for (const s of slides) {
+      const label = s.title || "(untitled)";
+      const sub = s.subtitle ? ` — ${s.subtitle}` : "";
+      const layout = s.layout ? `  [${s.layout}]` : "";
+      process.stdout.write(
+        `${String(s.index).padStart(3)}.${layout}  ${label}${sub}\n`,
+      );
+    }
+  } else {
+    slides.forEach((s, i) => {
+      if (i > 0) process.stdout.write("\n");
+      const layout = s.layout ? ` (${s.layout})` : "";
+      process.stdout.write(`── Slide ${s.index}${layout} ──\n`);
+      process.stdout.write(`${s.text && s.text.length ? s.text : "(no text)"}\n`);
+    });
   }
 }
 
@@ -765,8 +1037,30 @@ async function cmdPair(rest) {
     others > 0
       ? ` (${sessions.length} environments connected — commands now fan out across all of them)`
       : "";
+  let verify = "";
+  try {
+    const client = await import(
+      pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+    );
+    const deadline = Date.now() + 8000;
+    for (;;) {
+      const status = await client.connectionStatus();
+      if ((status.presentations ?? []).length > 0) {
+        verify = " Pane is registered.";
+        break;
+      }
+      if (Date.now() >= deadline) {
+        verify =
+          " No pane is registered yet; if PowerPoint is already open, reopen or click the slidemind task pane, then run 'slidemind doctor'.";
+        break;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  } catch {
+    // Pairing itself succeeded; diagnostics remain available via doctor.
+  }
   process.stdout.write(
-    `Paired with ${label || env}${suffix}. Run 'slidemind presentations' to verify.\n`,
+    `Paired with ${label || env}${suffix}.${verify} Run 'slidemind doctor' to verify.\n`,
   );
 }
 
@@ -1192,6 +1486,9 @@ async function main(rawArgv) {
     case "build-pptx":
       await cmdBuildPptx(rest);
       return 0;
+    case "view-draft":
+      await cmdViewDraft(rest);
+      return 0;
     case "search":
       await cmdSearch(rest);
       return 0;
@@ -1225,6 +1522,14 @@ async function main(rawArgv) {
     case "presentations":
       await cmdPresentations(rest);
       return 0;
+    case "doctor":
+    case "connection":
+    case "status":
+      await cmdDoctor(rest);
+      return 0;
+    case "read":
+      await cmdRead(rest);
+      return 0;
     case "push":
       await cmdPush(rest);
       return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Connect Claude Code, Codex & opencode to the slidemind PowerPoint add-in — let your coding agent build and edit native, on-brand PowerPoint decks against your active corporate design, from the terminal.",
   "type": "module",
   "bin": {

package/skills/create-slides/SKILL.md

@@ -18,11 +18,32 @@ So this file owns only what is genuinely CLI-specific: the **host precondition**
 This skill drives the `slidemind` CLI + its MCP server (`slidemind_list_open_presentations`, `slidemind_push_deck`, `slidemind_search_engine`, `slidemind_download_result`). The CLI reaches PowerPoint through the add-in's **cloud relay** — it doesn't run any local server. Patch what's missing yourself, but the **pairing** step needs the user once (they hold the add-in's identity):
 
 - **CLI missing** (`slidemind` not on `PATH`, or the `slidemind_*` MCP tools absent): `npm install -g slidemind`, then `slidemind init --for <claude|codex|opencode|all>` (registers the MCP server + (re)deploys this skill). The harness may need a restart for the `slidemind_*` tools to appear.
-- **Not paired** (a command says *slidemind is not paired*): this is the one step you can't do for the user. Tell them: in the slidemind add-in click **"Connect CLI"**, then paste the shown `slidemind pair …` command into this terminal. It's one-time per environment (the code carries that backend's URL + a session token — no hardcoded URLs, no separate login; the add-in's own session is the auth). `slidemind whoami` lists every paired environment.
+- **Not paired** (a command says *slidemind is not paired*): the one step you can't do for the user — they hold the add-in's identity. Walk them through **Pairing the CLI with the add-in** below (it carries the restart step the in-app wizard never mentions). `slidemind whoami` lists every paired environment.
 - `npx slidemind <command>` runs one-off without a global install; `slidemind --version` confirms PATH; `slidemind update` upgrades (`--ref <version>` to pin).
 
 After pairing once: **CLI paired + the add-in open ≡ it just works**, against whatever environment (dev / prod / a client deployment) the add-in is wired to. The CLI is **multi-environment**: pair once per backend (local / dev / prod) and every command fans out across all of them, tags each open window with its `env`, and routes to the right backend automatically — no manual switching. (Scope to one with `--backend <url|env>` when you need to.)
 
+## Pairing the CLI with the add-in (one-time; you guide the user)
+
+Pairing is the **only** step that genuinely needs the user — the pairing code carries the add-in's own session, so only they can mint it. When a command fails with *slidemind is not paired* (or `slidemind whoami` lists nothing for this machine), don't retry blindly: walk the user through the steps below, then resume. It's one-time per environment; once paired, `slidemind whoami` shows it.
+
+**1 — Mint a pairing code in the add-in.** Tell the user: in PowerPoint, open the **slidemind add-in** task pane → **Settings** → **General** → the **Connect CLI** section (it's marked *Preview*) → press **Pair**. That opens a small 3-step wizard with copy buttons:
+   1. `npm install -g slidemind` — skip if the CLI is already installed.
+   2. pick the coding agent(s) → the wizard prints the exact `slidemind init --for <…>` — skip if you already ran `init`.
+   3. a **one-time** `slidemind pair <code>` command — this is the one that matters.
+
+**2 — Run the pair command in this terminal.** Have the user copy the step-3 `slidemind pair <code>` line and paste it here; run it. The code is single-use and expires (~10 min) — if it fails as expired/invalid, have them press **Pair** again for a fresh one. On success the add-in's Connect CLI panel flips to **Connected**.
+
+**3 — Restart the add-in once (the wizard does NOT tell the user this).** Pairing flips CLI integration on, but the task pane that's *already running* often won't pick up the live connection — so the freshly-paired window may not show up yet. **If, right after pairing, `slidemind presentations` still doesn't list the window** (or a push/search behaves as though nothing is connected) even though PowerPoint is open with the add-in loaded and a corporate design active, tell the user to **restart the add-in**: close the slidemind task pane and reopen it from the ribbon; if the window still doesn't appear, close and reopen the presentation (or PowerPoint). A fresh pane re-reads the now-enabled pairing and registers itself so the CLI can see it. Then re-run `slidemind presentations`. This is a one-time nudge right after the first pairing — once the window appears it stays, and the add-in can't trigger this restart itself, so you have to ask for it.
+
+**Two states, two different fixes — don't conflate them:**
+
+| What you see | What it means | What to tell the user |
+|---|---|---|
+| *slidemind is not paired* (or empty `whoami`) | this machine has no session | mint a code via **Connect CLI** and run `slidemind pair <code>` (steps 1–2) |
+| `slidemind presentations` is **empty**, but PowerPoint is open with the add-in + a CD active, **and** this machine is already paired | the pane hasn't registered on the relay — typically a just-paired pane that needs a fresh boot | **restart the add-in** (step 3), then retry |
+| `slidemind presentations` is **empty** and no PowerPoint is connected | nothing to talk to | open PowerPoint, load the add-in, pick/create a corporate design |
+
 ## Precondition gate (check this first, every time)
 
 Authoring and rendering hard-require an **open PowerPoint host with the slidemind add-in loaded and an active corporate design**. Without a host there is no bundle to read and no renderer to push to; `download-bundle`, `build-pptx`, and `push` all fail.
@@ -31,7 +52,7 @@ Authoring and rendering hard-require an **open PowerPoint host with the slidemin
 2. One registered → that's your target `presentation_id`. **Several → ask the user which**, by `title`/`fileName` (never raw ids) — once for **which presentation's corporate design to download**, and again at render time for **which presentation to push into** (the CD source and the push target may be different presentations).
 3. **None registered → stop.** Tell the user: *open PowerPoint, load the slidemind add-in, and pick or create a corporate design, then retry.*
 
-> **Empty list vs. not paired — different fixes.** An *empty* registry means no PowerPoint is connected (step 3 → ask the user to open it / enable Connect CLI). A *not paired* error means this machine has no session — ask the user to pair once via the add-in's **"Connect CLI"** (see Bootstrap); don't ask them to open PowerPoint for that.
+> **Empty list vs. not paired — different fixes** (full triage in *Pairing the CLI with the add-in* above). An *empty* registry with no PowerPoint connected means open it / enable Connect CLI (step 3). A *not paired* error means this machine has no session — pair once via the add-in's **"Connect CLI"**; don't ask them to open PowerPoint for that. An *empty* registry **while** PowerPoint is open with the add-in **and** this machine is already paired usually means the just-paired pane never registered — ask the user to **restart the add-in** (close + reopen the task pane), then retry.
 
 **Backgrounded PowerPoint is expected to work.** Do not pre-emptively ask the user to focus PowerPoint or the task pane, and never ask them to keep it foregrounded while something runs. The render itself (`build-pptx`, the render half of `push`) **never needs the task pane awake** — it captures the slides with a local headless browser and assembles the `.pptx` server-side — streams its own `rendering slide n/m…` progress, and survives long decks. Only the pane-touching ops (the insert half of `push`, engine search/download) need the pane, and the CLI handles that itself: it waits up to ~2 min, prints one *"click the slidemind pane"* line when user help is genuinely needed, and retries safely. If you see that line, relay it once and keep waiting — do not rebuild, re-plan, or babysit. If a `push` still times out, the rendered `.pptx` was saved next to the deck (`paneSuspended` + `fallbackFile` in the result) — nothing is lost; retry the push after the user clicks the pane. Reserve the full "open PowerPoint…" instruction in (3) for when nothing is registered at all.
 
@@ -57,12 +78,13 @@ Keep planning about intent and content. Don't materialize the bundle or read bra
 3. **Study brand samples (before composing).** The materialized bundle's `samples/` dir holds the brand's own reference slides. If it's non-empty, pick **3 at random** and **Read** each (the Read tool renders images) *before* writing any JSX — this is the local-harness stand-in for the in-app persona's reference thumbnails, and it is what keeps a deck looking on-brand rather than merely compliant. Study them for whitespace rhythm, shape density, hierarchy, accent use, and layering, then compose in that spirit (never copy a sample 1:1). This is `composition.md`'s samples discipline; skip only when `samples/` is empty.
 4. **Read, then author.** Read the four create-stage references together — `workflow/create.md` (the procedure), `workflow/composition.md` (the composition baseline), `workflow/layouts.md` (palette + working area), and `workflow/authoring.md` (the substrate rules) — plus the deck's `design.md` and the specific `layouts/*.jsx` the plan uses. (That is the read set `workflow/create.md` → Context loading prescribes; follow it as written.) Then write `decks/<slug>/slides/NN-<topic>.jsx` — zero-padded numeric prefix from the first file on (play order is filename order here; see the slide-file row in the command mapping), one default export per slide, composing one bundle layout (Mode A) or a blank-content layout with freeform children (Mode B), exactly as those docs prescribe.
 5. **Imagery from the engine.** Per the `### Brand Image Sources` block in `design.md`, search the brand engine and place results. The engine search/reuse mechanics live in **`slidemind-search`** — use it to find and fetch imagery; the create-only icon-recolour detail is in *Recolouring engine icons* below. To pull in an **existing whole slide** (not just an image), use `slidemind-search`'s `add-slide` — it folds the slide into `decks/<slug>/slides/` as a native `.pptx` that coexists with your JSX in play order and survives re-push.
-6. **Preview review, then push.** This is `build_and_push` in `workflow/build-and-export.md`, including its preview review gate — the local harness has a native port: before the FIRST export of new slides, run `slidemind review <deck>`. It builds the HTML preview, opens it in the browser with a spatial comment overlay, and **blocks until the user decides** (host-free — no open PowerPoint needed for the gate). The command then prints its verdict to stdout:
+6. **Look at your own draft first (you, the agent).** This is `see_draft` in `workflow/build-and-export.md` — the agent's pre-check, *before* any human sees the deck. The local-harness port is `slidemind view-draft <deck>` (MCP `slidemind_view_draft({ deck_path })`): it renders each authored `slides/*.jsx` to a per-slide PNG and hands the images back to you — **nothing is pushed, no `.pptx` is written, no review gate opens**. Read every image the way the audience will, fix anything visibly wrong **in the JSX** (re-express, never delete), and view again until each slide is sound. One round usually suffices. It runs locally against the materialized bundle, so it needs no awake pane and no open host once the bundle has been downloaded once. Two faithful limits to know: a slide on a **purpose-built (Mode A) layout** (cover/divider/agenda) and a **reused native `.pptx`** slide have no freeform region to capture, so they come back as a status line, not an image — judge those at the full-deck `review`/`build` step below. Do this self-check before the human review gate; don't push a draft you haven't looked at.
+7. **Preview review, then push.** This is `build_and_push` in `workflow/build-and-export.md`, including its preview review gate — the local harness has a native port: before the FIRST export of new slides, run `slidemind review <deck>`. It builds the HTML preview, opens it in the browser with a spatial comment overlay, and **blocks until the user decides** (host-free — no open PowerPoint needed for the gate). The command then prints its verdict to stdout:
    - `DECISION: approved` → proceed to the export the user actually asked for: `slidemind push <deck>` (into PowerPoint) or `slidemind build-pptx <deck>` (to a file).
    - `DECISION: comments` → the user left spatially-anchored notes, each citing a `slides/<file>.jsx:line:col`, the source line, and the click position (plus a readonly-layout note where the click landed on a layout slot). **Edit the cited files in place at the given line**, then **re-run `slidemind review <deck>`** — the prior round shows as read-only ghost pins so the user can confirm each note was addressed. Loop until approved. Nothing is exported on a comments round.
 
    `slidemind review` is the only step that pauses; `push`/`build-pptx` never pause — they render pane-free (local capture + server-side assembly, with live per-slide progress). One approval covers the task: push follow-up fixes without re-running review unless the user wants another look. If several presentations are open, confirm **which one to push into** first (it can differ from the CD source). After approval, run the push without asking; it works while PowerPoint is backgrounded, and the CLI itself waits + retries if the pane is needed (see the precondition gate). If a push still times out, the rendered `.pptx` is saved next to the deck — re-run `push` after the user clicks the pane, without rebuilding.
-7. **Sanity pass.** Run the checks in `workflow/create.md` before reporting done.
+8. **Sanity pass.** Run the checks in `workflow/create.md` before reporting done.
 
 ## Recolouring engine icons (create-authoring specifics)
 
@@ -83,11 +105,13 @@ The bundle's `workflow/*.md` are written for the in-app design agent and name **
 | In `workflow/*.md` (in-app agent) | Your equivalent (local harness) |
 |---|---|
 | `build_and_push` | `slidemind push <deck>` (into the open PowerPoint) · `slidemind build-pptx <deck>` (to a `.pptx` file) — both render server-side via the bridge |
+| `read_presentation_context` (read the live deck) | `slidemind read [presId] [--mode summary\|raw]` · MCP `slidemind_read_presentation({ presentation_id?, mode? })` — pull the current content of an open presentation (`summary` = per-slide outline; `raw` = each slide's plain text) to inspect what's there before editing. Plain text, not authoring markup |
 | `engine_search` / `engine_add` / `insert_image` | **`slidemind-search`** owns the engine search + reuse mechanics (`slidemind_search_engine` → `slidemind_download_result`, plus whole-slide reuse via `add-slide`). For placing a fetched icon in your JSX, pass `icon_color` / batch with `selections: [{ selection, icon_color }, …]` and colour per *Recolouring engine icons* below |
 | writing `slides/<topic>.jsx` in the chat workspace — unprefixed kebab-case names; play order = the ordered list passed to `build_and_push` | write `decks/<slug>/slides/NN-<topic>.jsx` on disk with a **zero-padded numeric prefix** (`01-cover.jsx`, `02-agenda.jsx`, …) — over the CLI play order is **numeric-aware filename order**; there is no ordered-list channel, so reordering = renaming files. The bundle's "don't pad with index prefixes" rule is in-app-only; here it inverts |
 | reading workspace files (`design.md`, `layouts/`, `workflow/*`) | read them from the materialized bundle dir (`<bundle>/…`) and your `decks/<slug>/` |
 | reference-slide thumbnails injected at `add_slide` (in-app persona) | **Read** 3 random images from the materialized bundle's `samples/` dir — the Read tool renders them (see *The create flow* step 3) |
 | `present_plan_for_review` (manager-owned) | **you** run intake → plan with the user (above); persist `decks/<slug>/plan.md` for decks |
+| `see_draft` (agent looks at its OWN draft before pushing) | `slidemind view-draft <deck>` · MCP `slidemind_view_draft({ deck_path })` — renders each `slides/*.jsx` to a per-slide PNG and returns the images to **you**; **no push, no `.pptx`, no review gate**. Look, fix the JSX, view again. Host-free once the bundle is materialized. Freeform slides only — purpose-built (Mode A) and reused native `.pptx` slides report as a status line (judge those at `review`/`build`). This is the agent self-check; `slidemind review` is the *human* gate |
 | the `build_and_push` **preview review gate** (pause on rendered previews → approve / per-element comments) | `slidemind review <deck>` — a native port of the same gate: serves the HTML preview with a spatial comment overlay and **blocks until the user decides**, then prints `DECISION: approved` or `DECISION: comments` (each comment cited to `slides/<file>.jsx:line:col`). On approve → run the export (`slidemind push` / `build-pptx`); on comments → edit the cited files and re-run `slidemind review` (prior round shows as ghost pins). One approval covers the task. `push`/`build-pptx` never pause; only `review` does. |
 
 Everything else in `workflow/*.md` — the composition craft, the substrate/authoring rules, the layout discovery and slot/working-area rules, the sanity bar — applies to you unchanged.