slidemind 0.1.9 → 0.2.1

package/src/bridge/engine-download.mjs

@@ -9,8 +9,16 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import {
+  DIMENSION_PROBE_BYTES,
+  imageSizeFromBuffer,
+  svgSizeFromMarkup,
+} from "./image-dimensions.mjs";
 import { describeRecolor } from "./recolor.mjs";
 
+// Every image format an engine accepts, plus the alias spellings seen in the
+// wild. Mirrors the add-in's `searchImage` set (lib/image-formats.ts there);
+// `extFromMime`'s `image/*` fallback below still covers anything newer.
 const MIME_EXT = {
   "image/svg+xml": "svg",
   "image/png": "png",
@@ -18,6 +26,9 @@ const MIME_EXT = {
   "image/jpg": "jpg",
   "image/webp": "webp",
   "image/gif": "gif",
+  "image/bmp": "bmp",
+  "image/x-ms-bmp": "bmp",
+  "image/tiff": "tiff",
 };
 
 // Derive a usable file extension from an engine result's MIME type. The brand
@@ -42,8 +53,186 @@ export function extFromMime(mimeType) {
   return "bin";
 }
 
+// Below this, a transfer finishes faster than a progress line is worth reading.
+// Most brand icons and slide slices are well under it, so the common case stays
+// silent.
+const PROGRESS_MIN_BYTES = 2 * 1024 * 1024;
+/** Emit at most one line per this much progress. */
+const PROGRESS_STEP_BYTES = 4 * 1024 * 1024;
+
+const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+
+// Progress reporter for a streamed transfer.
+//
+// Deliberately NOT an in-place bar: this CLI's convention (see
+// `renderProgressPrinter` in bin/slidemind.mjs — "one stderr line per state
+// change — works in plain logs and TTYs alike") is milestone lines, because the
+// primary consumer is an agent reading piped stdout, where `\r` repainting is
+// noise rather than motion. So: nothing for small files, and a line every few MB
+// for large ones, on stderr so it never pollutes parseable stdout.
+export function createTransferProgress(label, write = process.stderr.write.bind(process.stderr)) {
+  let nextAt = PROGRESS_STEP_BYTES;
+  let announced = false;
+  return (bytesWritten, total) => {
+    if (total != null && total < PROGRESS_MIN_BYTES) return;
+    if (bytesWritten < nextAt) return;
+    nextAt = bytesWritten + PROGRESS_STEP_BYTES;
+    if (total != null && total > 0) {
+      const pct = Math.min(99, Math.floor((bytesWritten / total) * 100));
+      write(`  ${label}: ${mb(bytesWritten)}/${mb(total)} MB (${pct}%)…\n`);
+    } else {
+      // No content-length (a decoded/chunked stream): report absolute progress.
+      write(`  ${label}: ${mb(bytesWritten)} MB…\n`);
+    }
+    announced = true;
+    return announced;
+  };
+}
+
+const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+
+// Magic-number signatures for the image formats an engine ACCEPTS — the add-in's
+// `searchImage` set (lib/image-formats.ts there, EngineFileExtensions.search_image
+// in its API). An engine cannot hold a format it refuses at ingest, so this list
+// is complete by construction; keep it in step with that set.
+//
+// `svg` is absent deliberately: it is XML with no signature, so it can only be
+// trusted from its declared type.
+const MAGIC_SIGNATURES = [
+  { ext: "png", parts: [[0, [0x89, ...ascii("PNG"), 0x0d, 0x0a, 0x1a, 0x0a]]] },
+  { ext: "jpg", parts: [[0, [0xff, 0xd8, 0xff]]] },
+  { ext: "gif", parts: [[0, ascii("GIF8")]] },
+  { ext: "bmp", parts: [[0, ascii("BM")]] },
+  // Endian-dependent: "II" + 42 little, "MM" + 42 big.
+  { ext: "tiff", parts: [[0, [...ascii("II"), 0x2a, 0x00]]] },
+  { ext: "tiff", parts: [[0, [...ascii("MM"), 0x00, 0x2a]]] },
+  // RIFF<4-byte size>WEBP — the format tag sits past the container header.
+  { ext: "webp", parts: [[0, ascii("RIFF")], [8, ascii("WEBP")]] },
+];
+
+// Identify an image from its BYTES, ignoring any declared MIME type. Returns null
+// when nothing matches (an SVG, or a format this system never ingests) so the
+// caller keeps its MIME-derived guess rather than inventing one.
+//
+// Why sniff at all: the declared type is only as good as the upstream
+// `Content-Type`, and it is demonstrably wrong in the wild — a 1024x1024 PNG in
+// the corpus arrived as `data:image/jpeg`, so the CLI wrote PNG bytes into a
+// `.jpg` file. A wrong extension is not cosmetic here: the asset is referenced
+// from slide JSX as `<img src>` and the renderer picks its decoder from the file
+// type, so a mislabelled asset can fail to render in the .pptx.
+export function extFromBytes(buf) {
+  if (!buf || buf.length < 2) return null;
+  for (const { ext, parts } of MAGIC_SIGNATURES) {
+    const matched = parts.every(([offset, bytes]) => {
+      if (buf.length < offset + bytes.length) return false;
+      return bytes.every((b, i) => buf[offset + i] === b);
+    });
+    if (matched) return ext;
+  }
+  return null;
+}
+
+// The extension to write bytes under: what the bytes ARE beats what the wire
+// claims. SVG is exempt — it is XML with no magic number, and the SVG path is
+// already gated on `svgMarkup` being present.
+export function resolveAssetExt(mimeType, buf) {
+  const declared = extFromMime(mimeType);
+  if (declared === "svg") return declared;
+  return extFromBytes(buf) ?? declared;
+}
+
+// Stream one result into assetsDir via the add-in's streaming route.
+//
+// Returns the same shape as `downloadOneResult`, or null when the paired add-in
+// has no streaming route (404/501) so the caller can fall back to the capped
+// ack path. A real failure (bad selection, dead source) throws.
+async function streamOneResult({
+  client,
+  presId,
+  backendURL,
+  searchId,
+  assetsDir,
+  selection,
+  iconColor,
+}) {
+  if (typeof client.engineDownloadToFile !== "function") return null;
+  // Write under a provisional name: the true extension is only knowable from the
+  // bytes, and buffering the image just to sniff its header would defeat the
+  // purpose of streaming.
+  const tempPath = path.join(assetsDir, `.engine-${searchId}-${selection}.part`);
+  let res;
+  try {
+    res = await client.engineDownloadToFile({
+      presId,
+      backendURL,
+      searchId,
+      selection,
+      destPath: tempPath,
+      iconColor: iconColor ?? null,
+      onProgress: createTransferProgress(`downloading result ${selection}`),
+    });
+  } catch (err) {
+    fs.rmSync(tempPath, { force: true });
+    // Route absent → this add-in predates streaming; let the caller fall back.
+    // A 404 that carries a machine code is the ROUTE talking (`unknown_search`
+    // for a stale selection), not Express saying "no such path" — retrying that
+    // on the capped path would just fail again, more slowly.
+    if ((err?.status === 404 && !err?.code) || err?.status === 501) return null;
+    throw err;
+  }
+
+  try {
+    if (res?.svgMarkup) {
+      // SVG arrives inline, not as a stream.
+      fs.rmSync(tempPath, { force: true });
+      const filename = `engine-${searchId}-${selection}.svg`;
+      const target = path.join(assetsDir, filename);
+      fs.writeFileSync(target, res.svgMarkup, "utf8");
+      return {
+        selection,
+        path: target,
+        reference: `./assets/${filename}`,
+        mimeType: res.mimeType ?? "image/svg+xml",
+        recolor: describeRecolor(res.svgMarkup, res.mimeType, iconColor ?? null),
+        size: svgSizeFromMarkup(res.svgMarkup),
+      };
+    }
+
+    if (!res?.bytesWritten) {
+      throw new Error("stream produced no bytes");
+    }
+    // Read only the leading header block, not the whole file: enough to sniff
+    // the format AND to reach a JPEG's SOF segment past its EXIF/ICC blocks.
+    const fd = fs.openSync(tempPath, "r");
+    const probeBytes = Math.min(DIMENSION_PROBE_BYTES, res.bytesWritten);
+    const header = Buffer.alloc(probeBytes);
+    let read = 0;
+    try {
+      read = fs.readSync(fd, header, 0, probeBytes, 0);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const probe = header.subarray(0, read);
+    const ext = resolveAssetExt(res.mimeType, probe);
+    const filename = `engine-${searchId}-${selection}.${ext}`;
+    const target = path.join(assetsDir, filename);
+    fs.renameSync(tempPath, target);
+    return {
+      selection,
+      path: target,
+      reference: `./assets/${filename}`,
+      mimeType: res.mimeType ?? null,
+      recolor: describeRecolor(null, res.mimeType, iconColor ?? null),
+      size: imageSizeFromBuffer(probe),
+    };
+  } catch (err) {
+    fs.rmSync(tempPath, { force: true });
+    throw err;
+  }
+}
+
 // Download one chosen engine result via the bridge and write it into assetsDir.
-// Returns { selection, path, reference, mimeType, recolor }. Throws on failure
+// Returns { selection, path, reference, mimeType, recolor, size }. Throws on failure
 // so callers can Promise.allSettled a batch without one bad selection sinking
 // the rest.
 export async function downloadOneResult({
@@ -55,6 +244,23 @@ export async function downloadOneResult({
   selection,
   iconColor,
 }) {
+  // Preferred path: stream via the add-in server, which is unbounded in image
+  // size. The extension can only be decided once bytes exist, so stream to a
+  // temp name first and rename — cheaper than buffering a 100 MB image to sniff
+  // its header.
+  const streamed = await streamOneResult({
+    client,
+    presId,
+    backendURL,
+    searchId,
+    assetsDir,
+    selection,
+    iconColor,
+  });
+  if (streamed) return streamed;
+
+  // Fallback for an add-in that predates the streaming route: bytes ride the
+  // pane's Socket.IO ack, capped by its 10 MB frame limit.
   const res = await client.engineDownload({
     presId,
     backendURL,
@@ -63,16 +269,28 @@ export async function downloadOneResult({
     iconColor: iconColor ?? null,
   });
   if (!res?.ok) {
-    throw new Error(res?.error ?? "download failed");
+    // `payload_too_large` is the add-in refusing an ack the relay's Socket.IO
+    // frame cap would otherwise DROP — which previously surfaced as an
+    // unexplained "task pane did not respond" timeout. Its message already
+    // carries the sizes, so pass it through as the cause rather than restating.
+    const err = new Error(res?.error ?? "download failed");
+    if (res?.code) err.code = res.code;
+    throw err;
   }
-  const ext = extFromMime(res.mimeType);
+  // Decode first so the extension can be decided by the BYTES, not by a
+  // Content-Type the engine inherited from upstream and may have wrong.
+  const bytes =
+    typeof res.base64 === "string" && res.base64.length > 0
+      ? Buffer.from(res.base64, "base64")
+      : null;
+  const ext = resolveAssetExt(res.mimeType, bytes);
   const filename = `engine-${searchId}-${selection}.${ext}`;
   const target = path.join(assetsDir, filename);
   if (res.svgMarkup && ext === "svg") {
     // The (possibly recoloured) SVG markup is the canonical asset.
     fs.writeFileSync(target, res.svgMarkup, "utf8");
-  } else if (typeof res.base64 === "string" && res.base64.length > 0) {
-    fs.writeFileSync(target, Buffer.from(res.base64, "base64"));
+  } else if (bytes) {
+    fs.writeFileSync(target, bytes);
   } else if (res.svgMarkup) {
     // SVG bytes arrived only as markup (mimeType lacked an svg hint).
     fs.writeFileSync(target, res.svgMarkup, "utf8");
@@ -85,5 +303,11 @@ export async function downloadOneResult({
     reference: `./assets/${filename}`,
     mimeType: res.mimeType,
     recolor: describeRecolor(res.svgMarkup ?? null, res.mimeType, iconColor ?? null),
+    // Measured from the asset actually written: SVG user units for markup,
+    // pixels for a raster. Null when the format carries no readable header.
+    size:
+      ext === "svg"
+        ? svgSizeFromMarkup(res.svgMarkup ?? null)
+        : imageSizeFromBuffer(bytes),
   };
 }

package/src/bridge/image-dimensions.mjs

@@ -0,0 +1,181 @@
+// Intrinsic pixel dimensions of an image, read from its own header bytes.
+//
+// Why here and not from the add-in: the engine wire carries a MIME type and the
+// bytes, never a size, and both transfer paths (the streaming route and the
+// capped ack fallback) end with the file already on disk. Measuring locally
+// therefore works against every add-in version with no wire change, and it
+// measures the asset the deck will actually reference rather than a thumbnail.
+//
+// Consumers: `slidemind download-result` reports the size so the agent can size
+// an `<img>` box to the real aspect ratio instead of guessing one.
+
+// Scan far enough into a JPEG to reach its first SOF segment past the EXIF/ICC
+// blocks that routinely occupy the first few dozen KB.
+export const DIMENSION_PROBE_BYTES = 128 * 1024;
+
+const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+
+const startsWith = (buf, offset, bytes) =>
+  buf.length >= offset + bytes.length && bytes.every((b, i) => buf[offset + i] === b);
+
+function pngSize(buf) {
+  // 8-byte signature, then the IHDR chunk: length(4) type(4) width(4) height(4).
+  if (!startsWith(buf, 12, ascii("IHDR"))) return null;
+  if (buf.length < 24) return null;
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+
+function gifSize(buf) {
+  if (buf.length < 10) return null;
+  return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+}
+
+function bmpSize(buf) {
+  if (buf.length < 26) return null;
+  const headerSize = buf.readUInt32LE(14);
+  // BITMAPCOREHEADER is 16-bit; every later DIB header is 32-bit signed, with a
+  // negative height meaning a top-down bitmap.
+  if (headerSize === 12) {
+    return { width: buf.readUInt16LE(18), height: buf.readUInt16LE(20) };
+  }
+  if (buf.length < 27) return null;
+  return { width: Math.abs(buf.readInt32LE(18)), height: Math.abs(buf.readInt32LE(22)) };
+}
+
+function webpSize(buf) {
+  // RIFF<size>WEBP, then one of three chunk flavours.
+  if (buf.length < 30) return null;
+  const chunk = String.fromCharCode(buf[12], buf[13], buf[14], buf[15]);
+  if (chunk === "VP8 ") {
+    // Lossy: 3-byte frame tag, 3-byte sync code, then 14-bit width/height.
+    return {
+      width: buf.readUInt16LE(26) & 0x3fff,
+      height: buf.readUInt16LE(28) & 0x3fff,
+    };
+  }
+  if (chunk === "VP8L") {
+    // Lossless: signature byte 0x2f, then 14 bits width-1 and 14 bits height-1.
+    if (buf[20] !== 0x2f) return null;
+    const bits = buf.readUInt32LE(21);
+    return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+  }
+  if (chunk === "VP8X") {
+    // Extended: canvas size as two 24-bit little-endian values, minus one.
+    return {
+      width: buf.readUIntLE(24, 3) + 1,
+      height: buf.readUIntLE(27, 3) + 1,
+    };
+  }
+  return null;
+}
+
+// Markers that carry no payload and so must not be length-skipped.
+const JPEG_STANDALONE = new Set([0x01, 0xd8, 0xd9, 0xd0, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7]);
+// Every Start-Of-Frame flavour (baseline, progressive, lossless, …). The three
+// holes are DHT (0xc4), JPG extension (0xc8) and DAC (0xcc), which are not SOFs.
+const isJpegSof = (m) => m >= 0xc0 && m <= 0xcf && m !== 0xc4 && m !== 0xc8 && m !== 0xcc;
+
+function jpegSize(buf) {
+  let pos = 2; // past SOI
+  while (pos + 3 < buf.length) {
+    if (buf[pos] !== 0xff) {
+      // Resync: fill bytes (0xff) and the odd stray byte are legal between
+      // segments; anything else means the header is not parseable.
+      pos++;
+      continue;
+    }
+    let marker = buf[pos + 1];
+    // Any number of 0xff fill bytes may precede the marker itself.
+    let markerPos = pos + 1;
+    while (marker === 0xff && markerPos + 1 < buf.length) {
+      marker = buf[++markerPos];
+    }
+    if (JPEG_STANDALONE.has(marker)) {
+      pos = markerPos + 1;
+      continue;
+    }
+    if (markerPos + 3 >= buf.length) return null;
+    const length = buf.readUInt16BE(markerPos + 1);
+    if (isJpegSof(marker)) {
+      // SOF payload: precision(1) height(2) width(2).
+      if (markerPos + 7 >= buf.length) return null;
+      return {
+        height: buf.readUInt16BE(markerPos + 4),
+        width: buf.readUInt16BE(markerPos + 6),
+      };
+    }
+    if (length < 2) return null;
+    pos = markerPos + 1 + length;
+  }
+  return null;
+}
+
+/**
+ * Intrinsic pixel size of a raster image, read from its header bytes.
+ *
+ * Takes the same "the bytes beat the declared type" stance as `extFromBytes`
+ * (engine-download.mjs): the format is sniffed, never taken from a MIME type.
+ * Returns null for anything unrecognised (TIFF, a truncated header, an SVG) so
+ * the caller reports "unknown" rather than a fabricated size.
+ */
+export function imageSizeFromBuffer(buf) {
+  if (!buf || buf.length < 16) return null;
+  let size = null;
+  if (startsWith(buf, 0, [0x89, ...ascii("PNG"), 0x0d, 0x0a, 0x1a, 0x0a])) size = pngSize(buf);
+  else if (startsWith(buf, 0, [0xff, 0xd8, 0xff])) size = jpegSize(buf);
+  else if (startsWith(buf, 0, ascii("GIF8"))) size = gifSize(buf);
+  else if (startsWith(buf, 0, ascii("BM"))) size = bmpSize(buf);
+  else if (startsWith(buf, 0, ascii("RIFF")) && startsWith(buf, 8, ascii("WEBP"))) size = webpSize(buf);
+  if (!size) return null;
+  if (!Number.isFinite(size.width) || !Number.isFinite(size.height)) return null;
+  if (size.width <= 0 || size.height <= 0) return null;
+  return size;
+}
+
+/**
+ * Intrinsic size of an SVG, in its own user units.
+ *
+ * `width`/`height` win when both are plain lengths; otherwise the viewBox
+ * supplies the aspect ratio (the common case for icon sets, which size
+ * themselves from CSS and carry only a viewBox). Percentage widths are ignored
+ * for the same reason — they describe the container, not the graphic.
+ */
+export function svgSizeFromMarkup(markup) {
+  if (typeof markup !== "string" || markup.length === 0) return null;
+  // Only the opening <svg …> tag may contribute; a nested <symbol width=…>
+  // further down must not be mistaken for the root size.
+  const openTag = /<svg\b[^>]*>/i.exec(markup)?.[0];
+  if (!openTag) return null;
+
+  const length = (name) => {
+    const m = new RegExp(`\\b${name}\\s*=\\s*["']?\\s*([\\d.]+)\\s*([a-z%]*)`, "i").exec(openTag);
+    if (!m) return null;
+    // Only unitless user units and `px` are a pixel count. `%` sizes the
+    // container, not the graphic, and physical units (mm/pt/in) would need a DPI
+    // — both fall through to the viewBox, which always states the true ratio.
+    const unit = m[2].toLowerCase();
+    if (unit !== "" && unit !== "px") return null;
+    const n = Number.parseFloat(m[1]);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  };
+
+  const width = length("width");
+  const height = length("height");
+  if (width && height) return { width, height };
+
+  const viewBox = /\bviewBox\s*=\s*["']?\s*([-\d.\s,]+)/i.exec(openTag);
+  if (viewBox) {
+    const parts = viewBox[1].trim().split(/[\s,]+/).map(Number.parseFloat);
+    if (parts.length === 4 && parts.every(Number.isFinite) && parts[2] > 0 && parts[3] > 0) {
+      return { width: width ?? parts[2], height: height ?? parts[3] };
+    }
+  }
+  return null;
+}
+
+/** `1200×800` for display, or null when the size could not be read. */
+export function formatSize(size) {
+  if (!size) return null;
+  const round = (n) => (Number.isInteger(n) ? n : Math.round(n * 100) / 100);
+  return `${round(size.width)}×${round(size.height)}`;
+}

package/src/builders/resolve-skill.mjs

@@ -22,6 +22,7 @@
 // declare: `mode`, `templates`, `defaultTemplate`, `designSystem.css`.
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -74,8 +75,50 @@ export function resolveSkillForDeck(deckDir) {
   return resolveSkill(skillName, planMeta, { deckDir, bundleDir });
 }
 
+// Cheap, NEVER-throwing mode probe: plan frontmatter → skill manifest → mode.
+// Callers that only need to know WHICH pipeline a deck belongs to (compose vs
+// fill-template) must not pay resolveSkill's design-root requirement — a
+// compose deck with an unmaterialized bundle self-heals inside the render
+// path, and an early resolver throw here would break that.
+export function resolveDeckMode(deckDir) {
+  try {
+    const planMeta = readPlanFrontmatter(deckDir);
+    const skillName = planMeta.skill || DEFAULT_SKILL;
+    const skillDir = locateSkillDir(skillName);
+    const manifest = fs.existsSync(skillDir) ? readManifest(skillDir) : {};
+    return { skillName, mode: manifest.mode || "compose" };
+  } catch {
+    return { skillName: DEFAULT_SKILL, mode: "compose" };
+  }
+}
+
+// Skill packs can live outside the npm package: confidential template packs
+// (e.g. proposal masters) install to the user-level skills dir and are found
+// FIRST, so the public package never has to carry them. Lookup order:
+//   1. $SLIDEMIND_SKILLS_DIR/<name>   (tests / non-standard installs)
+//   2. ~/.config/slidemind/skills/<name>
+//   3. <package>/skills/<name>
+export function userSkillsRoot() {
+  return (
+    process.env.SLIDEMIND_SKILLS_DIR ||
+    path.join(
+      process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"),
+      "slidemind",
+      "skills",
+    )
+  );
+}
+
+function locateSkillDir(skillName) {
+  const candidates = [
+    path.join(userSkillsRoot(), skillName),
+    path.join(PACKAGE_ROOT, "skills", skillName),
+  ];
+  return firstExisting(candidates) ?? candidates[candidates.length - 1];
+}
+
 export function resolveSkill(skillName, planMeta = {}, opts = {}) {
-  const skillDir = path.join(PACKAGE_ROOT, "skills", skillName);
+  const skillDir = locateSkillDir(skillName);
   const manifest = fs.existsSync(skillDir) ? readManifest(skillDir) : {};
   const cssName = manifest.designSystem?.css || "corporate-design.css";
 
@@ -167,6 +210,7 @@ export function resolveSkill(skillName, planMeta = {}, opts = {}) {
     templateKey,
     templatePath,
     locale: planMeta.locale || null,
+    planMeta,
     packageRoot: PACKAGE_ROOT,
     bundleDir,
   };

package/src/builders/review.mjs

@@ -56,7 +56,10 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const OVERLAY_PATH = path.join(__dirname, "review-overlay.js");
 const REVIEW_STATE_FILE = "review.json";
-const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+// Keep the review preview available for a working session, then let the
+// existing finally block close the local server when the decision or timeout
+// resolves.
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 60 * 1000;
 
 function clamp01(n) {
   return n < 0 ? 0 : n > 1 ? 1 : n;

package/src/install-channel.mjs

@@ -0,0 +1,61 @@
+// Which channel installed the CLI that is running right now?
+//
+// npm (`npm install -g slidemind`, or `npx`) is the default and the one every
+// "your CLI is too old" remediation used to assume. Claude Code's plugin
+// channel breaks that assumption: the plugin ships its OWN copy of the CLI and
+// puts it on the plugin session's PATH, so `npm install -g slidemind@latest`
+// installs a second, unrelated global and the session keeps running the old
+// plugin copy. A plugin user following the npm remediation would watch the
+// update succeed and stay blocked on the add-in's version floor forever.
+//
+// Detection is by the path this file lives at — where the running code came
+// from — not by env, so it holds for any process the plugin session spawns.
+// `CLAUDE_PLUGIN_ROOT` is honoured as a secondary signal when Claude Code
+// exports it.
+//
+// Codex is deliberately NOT detected: Codex plugins carry the skills only (they
+// cannot put a bin on PATH), so a Codex-plugin session always runs the npm CLI
+// and the npm remediation is already correct there.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+
+// `~/.claude/plugins/cache/<marketplace>/<plugin>/…` — a `plugins` segment
+// directly under `.claude`. Matching the pair (not either half alone) keeps a
+// user's own `~/dev/.claude/plugins`-shaped checkout from being the only thing
+// that can false-positive.
+function underClaudePlugins(root) {
+  const segs = path.resolve(root).split(/[\\/]+/);
+  for (let i = 1; i < segs.length; i += 1) {
+    if (segs[i] === "plugins" && segs[i - 1] === ".claude") return true;
+  }
+  return false;
+}
+
+export function isClaudePluginInstall(root = PACKAGE_ROOT) {
+  const resolved = path.resolve(root);
+  if (underClaudePlugins(resolved)) return true;
+  const declared = process.env.CLAUDE_PLUGIN_ROOT;
+  if (declared) {
+    const rel = path.relative(path.resolve(declared), resolved);
+    if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// The one sentence every version-floor / too-old-CLI message ends with, so the
+// remediation always names the updater that actually replaces THIS binary.
+export function updateCliInstruction() {
+  return isClaudePluginInstall()
+    ? "This CLI came from the slidemind Claude Code plugin, so update it there: " +
+        "`/plugin` → slidemind → update (a global `npm install -g slidemind@latest` " +
+        "installs a separate copy and will NOT change the `slidemind` this session runs)."
+    : "Run `slidemind update` (or `npm install -g slidemind@latest`), then retry.";
+}

package/src/installers/claude.mjs

@@ -78,6 +78,19 @@ function unregisterMcpServer() {
   return false;
 }
 
+// ~/.claude/plugins/cache/<marketplace>/slidemind/ — presence means the Claude
+// Code plugin is also installed; skills copied by `init` duplicate its skills.
+function pluginInstallDetected() {
+  const cacheRoot = path.join(claudeRoot(), "plugins", "cache");
+  try {
+    return fs
+      .readdirSync(cacheRoot)
+      .some((mp) => fs.existsSync(path.join(cacheRoot, mp, NAMESPACE)));
+  } catch {
+    return false;
+  }
+}
+
 export async function install({ packageRoot, flags }) {
   const link = isLinkMode(flags);
   const force = isForce(flags);
@@ -108,6 +121,15 @@ export async function install({ packageRoot, flags }) {
   if (unregisterMcpServer()) {
     ui.step({ status: "remove", label: "mcp server", value: "removed legacy registration (slidemind is a CLI)" });
   }
+
+  if (pluginInstallDetected()) {
+    ui.step({
+      status: "info",
+      label: "plugin",
+      value:
+        "the slidemind Claude Code plugin is also installed — these copied skills duplicate its skills; plugin users can drop them with `slidemind uninstall --for claude`",
+    });
+  }
 }
 
 export async function uninstall() {