slidemind 0.3.12 → 0.3.14

package/src/cli/engine-results.mjs

@@ -0,0 +1,320 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { fail, resolveDeckArg, SRC_DIR } from "./common.mjs";
+import { resolveEngineRouting, deckBrandId, loginRequiredMessage, failOnEngineBlocker, describeEngineByteFailure, parseSearchIdArg, parsePicks, parseIconColors, describeReadSourceFailure } from "./engine-helpers.mjs";
+
+export async function cmdViewSlide(rest) {
+  let searchId = null;
+  let pick = null;
+  let to = null;
+  let outDir = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--search") {
+      searchId = parseSearchIdArg(rest[++i]);
+    } else if (a === "--pick") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--pick expects a positive selection number, got '${next}'`);
+      }
+      pick = n;
+    } else if (a === "--to") {
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--out" || a === "-o") {
+      outDir = rest[++i];
+      if (!outDir) fail("--out expects a directory");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (searchId === null || pick === null) {
+    fail("usage: slidemind view-slide --search <id> --pick <n> [--to <presId>] [--out <dir>]");
+  }
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  const { resolveAssetExt } = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
+  );
+  const routing = await resolveEngineRouting(client, { to, searchId });
+  let res;
+  try {
+    res = await client.viewSlide({
+      presId: routing.presId,
+      searchId,
+      selection: pick,
+      backendURL: routing.backendURL,
+    });
+  } catch (err) {
+    await failOnEngineBlocker(client, err, { to });
+  }
+  if (!res?.ok || !res.dataUri) {
+    fail(`view-slide failed: ${res?.error ?? "no image returned"}`);
+  }
+  const m = /^data:([^;]+);base64,(.+)$/.exec(res.dataUri);
+  if (!m) fail("view-slide returned an unparseable data URI");
+  const dir = outDir
+    ? path.resolve(process.cwd(), outDir)
+    : fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-view-"));
+  fs.mkdirSync(dir, { recursive: true });
+  // Extension from the BYTES, not the declared MIME — engines inherit a
+  // Content-Type from upstream and it is demonstrably wrong for some corpus
+  // images (PNG served as image/jpeg).
+  const bytes = Buffer.from(m[2], "base64");
+  const target = path.join(
+    dir,
+    `slide-${searchId}-${pick}.${resolveAssetExt(m[1], bytes)}`,
+  );
+  fs.writeFileSync(target, bytes);
+  process.stdout.write(
+    `Wrote preview of result ${pick} (searchId ${searchId}) to ${target}\n`,
+  );
+}
+
+export async function cmdReadSource(rest) {
+  let searchId = null;
+  let pick = null;
+  let fromSlide = null;
+  let toSlide = null;
+  let to = null;
+  let outFile = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--search") {
+      searchId = parseSearchIdArg(rest[++i]);
+    } else if (a === "--pick") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--pick expects a positive selection number, got '${next}'`);
+      }
+      pick = n;
+    } else if (a === "--from-slide") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--from-slide expects a positive slide number, got '${next}'`);
+      }
+      fromSlide = n;
+    } else if (a === "--to-slide") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--to-slide expects a positive slide number, got '${next}'`);
+      }
+      toSlide = n;
+    } else if (a === "--to") {
+      // Deliberately the WINDOW, matching every other search-scoped command.
+      // The slide window is --from-slide/--to-slide.
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--out" || a === "-o") {
+      outFile = rest[++i];
+      if (!outFile) fail("--out expects a file path");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (searchId === null || pick === null) {
+    fail(
+      "usage: slidemind read-source --search <id> --pick <n> [--from-slide <n>] [--to-slide <n>] [--to <presId>] [--out <file>]",
+    );
+  }
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  // Pane path: the searchId is presentation-scoped, so --to targets the window
+  // the search ran on — same rule as view-slide. Direct path: the record is the
+  // backend's, so no window is involved.
+  const routing = await resolveEngineRouting(client, { to, searchId });
+  let res;
+  try {
+    res = await client.readSourcePresentation({
+      presId: routing.presId,
+      searchId,
+      selection: pick,
+      fromSlide,
+      toSlide,
+      backendURL: routing.backendURL,
+    });
+  } catch (err) {
+    // The login_required line is authored once and knows about an open pane;
+    // everything else is this command's own vocabulary.
+    fail(
+      (await loginRequiredMessage(client, err, { to })) ??
+        describeReadSourceFailure(err, searchId, pick),
+    );
+  }
+  if (!res?.markdown) {
+    fail("read-source returned no content. Try the search again, then re-pick.");
+  }
+  if (outFile) {
+    const target = path.resolve(process.cwd(), outFile);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, res.markdown, "utf8");
+    process.stdout.write(
+      `Wrote the source presentation of result ${pick} (searchId ${searchId}) to ${target}\n`,
+    );
+  } else {
+    process.stdout.write(res.markdown.endsWith("\n") ? res.markdown : `${res.markdown}\n`);
+  }
+  // Truncation is the one thing a reader must not miss: the body they just got
+  // is a slide map, not the deck.
+  if (res.truncated) {
+    process.stderr.write(
+      `note: this deck was too long to return in full — the output is its slide map. ` +
+        `Re-run with --from-slide/--to-slide to read a range.\n`,
+    );
+  } else if (res.totalSlideCount && res.slideCount < res.totalSlideCount) {
+    process.stderr.write(
+      `note: showing ${res.slideCount} of ${res.totalSlideCount} slides.\n`,
+    );
+  }
+}
+
+/**
+ * Turn a source-presentation failure into the action that actually fixes it.
+ * A login_required refusal is handled one level up, in loginRequiredMessage —
+ * it is the one blocker only the USER can clear and it reads identically
+ * across every command.
+ */
+
+export async function cmdDownloadResult(rest) {
+  let searchId = null;
+  let picks = null;
+  let deck = null;
+  let to = null;
+  let asJson = false;
+  let iconColorsRaw = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--search") {
+      searchId = parseSearchIdArg(rest[++i]);
+    } else if (a === "--pick") {
+      picks = parsePicks(rest[++i]);
+    } else if (a === "--deck") {
+      deck = rest[++i];
+      if (!deck) fail("--deck expects a deck name or path");
+    } else if (a === "--to") {
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--json") {
+      asJson = true;
+    } else if (a === "--icon-color" || a === "--icon-colour") {
+      iconColorsRaw = rest[++i];
+      if (!iconColorsRaw) fail("--icon-color expects a hex colour (or comma-separated list aligned to --pick)");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (searchId === null || !picks || !deck) {
+    fail(
+      "usage: slidemind download-result --search <id> --pick <n[,n,...]> --deck <deck> [--to <presId>] [--icon-color <hex[,hex,...]>] [--json]",
+    );
+  }
+  const iconColors = parseIconColors(iconColorsRaw, picks.length);
+  const deckDir = resolveDeckArg(deck);
+  const assetsDir = path.join(deckDir, "assets");
+  fs.mkdirSync(assetsDir, { recursive: true });
+
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  // Shared image/icon download logic (src/bridge/engine-download.mjs).
+  const { downloadOneResult } = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
+  );
+  // Direct path: an opaque searchId routes to the record's own environment,
+  // else the deck's bound design decides; no window needed. Pane path: the
+  // searchId is presentation-scoped, so --to targets the window the search ran
+  // on (without it, >1 open window is a dead-end).
+  const routing = await resolveEngineRouting(client, {
+    to,
+    brandId: await deckBrandId(deckDir),
+    searchId,
+  });
+
+  // Concurrent — each download is its own bridge round-trip; allSettled so one
+  // bad selection doesn't sink the rest of the batch.
+  const settled = await Promise.allSettled(
+    picks.map((selection, i) =>
+      downloadOneResult({
+        client,
+        presId: routing.presId,
+        backendURL: routing.backendURL,
+        searchId,
+        assetsDir,
+        selection,
+        iconColor: iconColors[i],
+      }),
+    ),
+  );
+  // One user-clearable blocker sinks the whole batch identically — every pick
+  // would fail the same way, and the fix is one action, not N error lines.
+  const stale = settled.find(
+    (r) => r.status === "rejected" && client.loginRequiredBlocker?.(r.reason),
+  );
+  if (stale) fail(await loginRequiredMessage(client, stale.reason, { to }));
+  const results = await Promise.all(
+    settled.map(async (r, i) =>
+      r.status === "fulfilled"
+        ? r.value
+        : {
+            selection: picks[i],
+            error:
+              (await describeEngineByteFailure(client, r.reason, {
+                backendURL: routing.backendURL,
+              })) ??
+              r.reason?.message ??
+              String(r.reason),
+          },
+    ),
+  );
+  const { formatSize } = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "image-dimensions.mjs")).href
+  );
+  let ok = 0;
+  let anySized = false;
+  const lines = [];
+  for (const r of results) {
+    if (r.error) {
+      lines.push(`  ✗ selection ${r.selection}: ${r.error}`);
+      continue;
+    }
+    ok++;
+    const note = r.recolor?.note ? ` — ${r.recolor.note}` : "";
+    // The intrinsic size is the agent's only handle on the asset's aspect
+    // ratio — without it the <img> box is a guess and the render stretches.
+    const dims = formatSize(r.size);
+    anySized ||= Boolean(dims);
+    const size = dims ? `  ${dims}` : "  (size unknown)";
+    lines.push(`  ${r.reference}${size}  (${r.recolor?.mode ?? "?"})${note}`);
+  }
+  if (asJson) {
+    process.stdout.write(
+      `${JSON.stringify({ searchId, assetsDir, downloaded: ok, results: results.map((r) => (r.error ? { selection: r.selection, error: r.error } : { selection: r.selection, file: r.reference, size: r.size ?? null, recolor: r.recolor ?? null })) }, null, 2)}\n`,
+    );
+    if (ok === 0) process.exit(1);
+    return;
+  }
+  process.stdout.write(
+    `Downloaded ${ok}/${results.length} result(s) into ${path.relative(process.cwd(), assetsDir)}:\n` +
+      lines.join("\n") +
+      `\nReference each from slide JSX as <img src="./assets/...">.\n` +
+      (anySized
+        ? `Sizes above are the assets' intrinsic width×height — give each <img> a box ` +
+          `with that aspect ratio, or the render stretches it to whatever box you wrote.\n`
+        : ""),
+  );
+  if (ok === 0) process.exit(1);
+}

package/src/cli/help.mjs

@@ -0,0 +1,201 @@
+import path from "node:path";
+import { readPackageJson } from "./common.mjs";
+
+// `printHelp("view-draft")` prints only that command's block — every command
+// accepts `--help` (agents reach for it before the full 15KB listing).
+export function printHelp(cmd = null) {
+  const pkg = readPackageJson();
+  const text =
+    `slidemind ${pkg.version} — drive the slidemind PowerPoint add-in to build native, on-brand decks\n` +
+      `\n` +
+      `Usage:\n` +
+      `  slidemind setup <claim>          One-command onboarding. Copy the command from PowerPoint →\n` +
+      `                                     slidemind → Settings → General → Connect CLI and paste it:\n` +
+      `                                     it connects this machine, installs slidemind globally, deploys\n` +
+      `                                     the skills, and runs 'ready'. Designed for 'npx slidemind@latest'.\n` +
+      `                                     --for <target>  harness to deploy skills into (default: auto — every\n` +
+      `                                                     coding agent found on this machine; none to skip)\n` +
+      `                                     --no-install    skip the global npm install (already installed)\n` +
+      `                                     --no-ready      skip the closing readiness check\n` +
+      `                                     --no-login      skip the Microsoft 365 browser sign-in offer\n` +
+      `                                     --json          machine-readable result\n` +
+      `  slidemind ready [deck]           One-command session setup — run this FIRST each session.\n` +
+      `                                     Verifies authorization/connection/CLI version, resolves the open\n` +
+      `                                     design, materializes its bundle, and (with a deck) binds it.\n` +
+      `                                     Exit 0 = ready; non-zero prints one actionable blocker.\n` +
+      `                                     A deck already bound to a design readies with PowerPoint closed.\n` +
+      `                                     --to <presId>   bind to a specific open window\n` +
+      `                                     --brand <id>    bind to a design by id (presFP) — no window needed\n` +
+      `                                     --force         re-download the bundle even if current\n` +
+      `                                     --connect-only  check the connection only (no design/bundle)\n` +
+      `                                     --diagnose      read-only report instead: both ladders (backend\n` +
+      `                                                     authoring / live PowerPoint), every paired backend,\n` +
+      `                                                     Microsoft 365 state and every registered window\n` +
+      `                                     --json          machine-readable readiness payload\n` +
+      `                                     With a deck, also prints its stage (plan / concepts / assets / slides /\n` +
+      `                                     draft check / review) and the next command — read from disk.\n` +
+      `  slidemind new <name>             Scaffold ./decks/<name>/ (auto-binds to the open design)\n` +
+      `                                     --brand <presFP>  bind to a chosen (cached) design instead\n` +
+      `                                     --to <presId>   bind to a specific open window\n` +
+      `                                     --no-bind       skip the auto-bind\n` +
+      `  slidemind plan <deck>            Plan sign-off gate on <deck>/plan.md: opens it in the browser\n` +
+      `                                     as a markdown editor + live preview + overall feedback box,\n` +
+      `                                     blocks until the user decides, prints DECISION: approved | comments\n` +
+      `                                     --port <n>          bind a fixed port (default: ephemeral)\n` +
+      `  slidemind concepts <deck>        After plan sign-off, generate one concept mockup PNG per planned\n` +
+      `                                     slide into <deck>/concepts/concept-slide-NN.png (bound deck,\n` +
+      `                                     pane-free — no PowerPoint window needed).\n` +
+      `                                     Read each as a design target, then rebuild it as slide JSX.\n` +
+      `                                     Optional aid — skips cleanly (exit 0) if unavailable.\n` +
+      `                                     --concept <image>[@N,M]  the user's own sketch/mockup IS the\n` +
+      `                                                          mockup for slides N,M (default: all)\n` +
+      `                                     --style <image>[@N,M]    the user's look-and-feel reference,\n` +
+      `                                                          leads the generation (repeatable)\n` +
+      `                                     --json          machine-readable result (paths, missing, status)\n` +
+      `                                     Always ends on one line: CONCEPTS: <n>/<planned> <status>\n` +
+      `  slidemind review <deck>          Open a spatial preview review; blocks until the user\n` +
+      `                                     approves or leaves comments (host-free)\n` +
+      `                                     --port <n>      bind a fixed port (default: ephemeral)\n` +
+      `                                     --allow-draft-defects  open even while the last view-draft's measured defects stand\n` +
+      `  slidemind build-pptx <deck>      Export native .pptx — via the add-in for compose decks (pane-free: the deck's design, else the one design cached/listed; a window only with --to), LOCALLY for template packs (host-free)\n` +
+      `                                     --pack <dir>   explicit template-pack directory (plugin integrations)\n` +
+      `                                     --to <presId>   target a specific window (required if >1 open)\n` +
+      `                                     --out <path>    output path (default <deck>/<deck>.pptx)\n` +
+      `                                     --force         discard manual PowerPoint edits instead of reconciling them\n` +
+      `                                     --json          machine-readable result\n` +
+      `  slidemind inspect-template-deck <deck>  Inspect a template deck as JSON for pack-owned validation\n` +
+      `                                     --pack <dir>   explicit template-pack directory (required)\n` +
+      `                                     --allow-unrendered-freeform  include JSX inserts without .pptx artifacts\n` +
+      `                                     --json          print the normalized deck model\n` +
+      `  slidemind view-draft <deck>      Lint + build the HTML preview, then render the deck's slides to\n` +
+      `                                     per-slide PNGs (no push, no .pptx)\n` +
+      `                                     so the agent can look before review; host-free once the\n` +
+      `                                     bundle is materialized. Prints the measured defects ([fill:warn], [inventory:warn])\n` +
+      `                                     Also runs the server's export gate on the captured slides (slot-fit,\n` +
+      `                                     diagram geometry, connector endpoints) so build-pptx's 422s surface here.\n` +
+      `                                     --only <file|N>[,…]  render just these slides (a per-slide builder's own check)\n` +
+      `                                     --fix           apply the deterministic lint autofixes first\n` +
+      `                                     --lint-only     lint + HTML build, no render (fast fix loop)\n` +
+      `                                     --no-translate  skip the export gate (purely local check)\n` +
+      `                                     --translate     insist on the export gate (fail instead of skipping when the backend is unreachable)\n` +
+      `                                     --json          machine-readable result (slides, defects, reviewCanOpen)\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 or scope for images or slides (no window needed on\n` +
+      `                                     add-ins that serve the pane-free engine routes; older ones relay\n` +
+      `                                     through an open host)\n` +
+      `                                     --engine <id>   engine, or scope:all | scope:sharepoint to search unfiltered\n` +
+      `                                                     (default: first image engine; scope:all for slide intents)\n` +
+      `                                     --result-type <t>  slide | image — required for a scope:* target\n` +
+      `                                     --intent <i>    auto | content | visual (slide engines)\n` +
+      `                                     --top <N>       max results\n` +
+      `                                     --deck <deck>   route by this deck's bound design (multi-environment)\n` +
+      `                                     --to <presId>   pin a window on the relayed path (ignored pane-free)\n` +
+      `                                     --json          print the raw result payload (carries the searchId)\n` +
+      `  slidemind view-slide [opts]      Fetch a slide search result's preview image to a file\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `                                     --pick <n>      1-based selection number to view\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
+      `                                     --out <dir>     output dir (default: a slidemind temp dir)\n` +
+      `  slidemind read-source [opts]     Read the ORIGINAL deck a slide search result came from\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `                                     --pick <n>      1-based selection number\n` +
+      `                                     --from-slide <n>  first slide to read (1-based)\n` +
+      `                                     --to-slide <n>    last slide to read (1-based)\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
+      `                                     --out <file>    write the Markdown to a file instead of stdout\n` +
+      `  slidemind ls designs             List every corporate design at hand: cached here + listed by the\n` +
+      `                                     add-in (presFP, name, theme colours) — read-only, picks nothing\n` +
+      `                                     --json          print the raw design list\n` +
+      `  slidemind ls engines             List the live engine catalog + search scopes\n` +
+      `                                     --type <t>      collection | search | scope\n` +
+      `                                     --subtype <s>   image | slide | template | content\n` +
+      `                                     --to <presId>   target a specific window/backend (relayed path only)\n` +
+      `                                     --all          include every paired backend\n` +
+      `                                     --json          print the raw engine list\n` +
+      `  slidemind insert-slide [opts]    Insert reused slide search results live into a window (requires a host)\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `                                     --pick <n,..>   1-based selection number(s)\n` +
+      `                                     --to <presId>   target window (required if >1 open)\n` +
+      `                                     --at <N>        insert after slide N (0-based); default = append\n` +
+      `  slidemind add-slide [opts]       Fold reused slide(s) into a deck as native .pptx\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `                                     --from <file.pptx>  fold slide(s) from a local .pptx instead (host-free)\n` +
+      `                                     --pick <n,..>   1-based selection number(s)\n` +
+      `                                     --deck <deck>   deck to add the slides to\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only; ignored with --from)\n` +
+      `                                     --at <N>        numeric prefix to start at (default: append)\n` +
+      `                                     --json          machine-readable result (carries the searchId)\n` +
+      `  slidemind adopt <file.pptx>      Rebuild a deck workspace from a file's embedded source; foreign\n` +
+      `                                     slides are converted to editable jsx where the add-in offers it\n` +
+      `                                     --deck <slug>   deck folder to write (default: the file's name)\n` +
+      `                                     --brand <presFP>  design to convert against (when the file names none)\n` +
+      `                                     --no-convert    fold every untagged slide as native .pptx instead\n` +
+      `  slidemind download-result [opts] Download image/icon search result(s) into a deck's assets/\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `                                     --pick <n,..>   1-based selection number(s)\n` +
+      `                                     --deck <deck>   deck to write the asset(s) into\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
+      `                                     --icon-color <hex[,hex,..]>  bake a colour into SVG result(s) (one for all, or one per --pick)\n` +
+      `                                     --json          machine-readable result (file, size, recolor per pick)\n` +
+      `  slidemind imagen "<prompt>"      Generate ONE image with the add-in's image model into a deck's assets/ (paired backend, pane-free)\n` +
+      `                                     --deck <deck>   bound deck to write the image into (required)\n` +
+      `                                     --out <name>    file name under assets/ (default imagen-N.png)\n` +
+      `                                     --size <s>      auto|1024x1024|1536x1024|1024x1536 (default auto)\n` +
+      `                                     --quality <q>   low|medium|high|auto\n` +
+      `  slidemind download-bundle [deck] Materialize or refresh a corporate design's bundle locally\n` +
+      `                                     (pane-free for a bound deck, --brand or --all — no PowerPoint needed)\n` +
+      `                                     --to <presId>   target a specific window (forces the pane route)\n` +
+      `                                     --brand <presFP> materialize a named design without a window\n` +
+      `                                     --all           refresh every design already cached on this machine\n` +
+      `                                     --force         re-download even if the cached bundle is current\n` +
+
+      `  slidemind read [presId|file.pptx]  Pull the content of an open presentation (requires a host),\n` +
+      `                                     or of a local .pptx path (read host-free from disk)\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` +
+      `                                     --replace       delete existing slides first (destructive)\n` +
+      `                                     --slides <ids>  comma-separated source slide ids to push\n` +
+      `                                     --accept-conversions  replace even when a converted slide is unconfirmed\n` +
+      `                                     --force         discard manual PowerPoint edits instead of reconciling them\n` +
+      `  slidemind login                  Sign in to Microsoft 365 in your browser so SharePoint-backed\n` +
+      `                                     slides and images download without an open PowerPoint window\n` +
+      `                                     --backend <url|env>  environment to sign in for (default: the default one)\n` +
+      `  slidemind whoami                 Show every connected environment (* = default)\n` +
+      `  slidemind logout [url|env]       Unpair one environment (--all to unpair every one)\n` +
+      `  slidemind init --for <t>         Set up slidemind in a harness (deploys the skill; clears the bundle cache)\n` +
+      `                                     <t> = claude | codex | opencode | all | auto (every harness found here)\n` +
+      `                                     'setup' already does this — only needed after installing a new agent\n` +
+      `  slidemind uninstall --for <t>    Remove a previously-installed skill (clears the bundle cache)\n` +
+      `  slidemind update [--for <t>]     Fetch the latest release and redeploy\n` +
+      `                                     --for <t>     harness to redeploy into (default: all)\n` +
+      `                                     --ref <ver>   pin to a release version (e.g. v0.1.0)\n` +
+      `  slidemind <command> --help       Show one command's usage\n` +
+      `  slidemind --help                 Show this help\n` +
+      `  slidemind --version              Print version\n` +
+      `\n` +
+      `Install targets: claude | codex | opencode | all\n` +
+      `Decks live in ./decks/ relative to your current directory.\n` +
+      `Override with env: SLIDEMIND_DECKS=/abs/path/to/decks\n` +
+      `Global: --backend <url|env>  scope a command to one paired environment (also SLIDEMIND_BACKEND)\n`;
+  process.stdout.write(cmd ? commandBlock(text, cmd) : text);
+}
+
+// The usage block of one command: its `  slidemind <cmd>` line and the indented
+// flag lines under it, up to the next command line. Falls back to the full text
+// for a name the listing does not carry.
+export function commandBlock(text, cmd) {
+  const head = new RegExp(`^  slidemind ${cmd.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}( |$)`);
+  const out = [];
+  let inBlock = false;
+  for (const line of text.split("\n")) {
+    if (/^  slidemind /.test(line) || line === "") inBlock = head.test(line);
+    if (inBlock) out.push(line);
+  }
+  return out.length ? out.join("\n") + "\n" : text;
+}