slidemind 0.2.1 → 0.2.3

package/skills/create-slides/SKILL.md

@@ -39,34 +39,34 @@ Two gate invariants you must never break — one per gate, equally binding:
 
 ## Bootstrap (set yourself up — don't make the user do it)
 
-**The first step of every session is `slidemind ready`** (continuing an existing deck: `slidemind ready <deck>`). In one call it verifies pairing, connection, and CLI version; resolves the design the add-in has open; downloads or refreshes that design's bundle; and — given a deck arg — binds the deck to it.
+**The first step of every session is `slidemind ready`** (continuing an existing deck: `slidemind ready <deck>`). In one call it verifies authorization, connection, and CLI version; resolves the design the add-in has open; downloads or refreshes that design's bundle; and — given a deck arg — binds the deck to it.
 
 - **Exit 0** → you're fully set up. Read `workflow/flow.md` (the stage spine) and `design.md` from the reported `bundleDir` and start planning.
 - **Non-zero** → the CLI names exactly one blocker and one `nextAction`; do what it says. (The two blockers that ever need the user are handled in *First step* below.)
 
-`ready` drives the `slidemind` CLI, which reaches PowerPoint through the add-in's **cloud relay** — no local server. Patch a missing CLI yourself; **pairing** needs the user once (they hold the add-in's identity):
+`ready` drives the `slidemind` CLI, which reaches PowerPoint through the add-in's **cloud relay** — no local server. Patch a missing CLI yourself; **connecting** needs the user once (they hold the add-in's identity):
 
-- **CLI missing** (`slidemind` not on `PATH`): `npm install -g slidemind`, then `slidemind init --for <claude|codex|opencode|all>` ((re)deploys this skill). `npx slidemind <command>` runs one-off without a global install; `slidemind --version` confirms PATH; `slidemind update` upgrades (`--ref <version>` to pin).
-- **Not paired** (`ready` blocks with `not_paired`, or a command says *slidemind is not paired*): the one step you can't do for the user. 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.
+- **CLI missing** (`slidemind` not on `PATH`): `npm install -g slidemind` — that alone is the fix. Only run `slidemind init --for <claude|codex|opencode|all>` ((re)deploys this skill) when this skill did **not** come from a plugin: if the `SKILL.md` you are reading sits under a harness plugin cache (`~/.claude/plugins/…`, `~/.codex/plugins/…`), the plugin already supplies it and `init` would plant a second copy that drifts on the next plugin update. `npx slidemind <command>` runs one-off without a global install; `slidemind --version` confirms PATH; `slidemind update` upgrades (`--ref <version>` to pin) — unless the CLI itself came from a plugin, in which case update it there.
+- **Not connected:** `ready` exits with `not_connected` — the CLI cannot start a connection by itself, because the claim that carries the deployment's address is minted in the add-in. Ask the user to open PowerPoint → slidemind → **Settings → General → Connect CLI**, press the **link button**, and copy the command shown (press **CLI already installed?** for the short `slidemind setup …` form). Have them paste it to you and run it **verbatim** — it connects, refreshes the skills, and runs `ready` itself. Add `--no-install --for none` only if their install must not be touched. `slidemind whoami` lists connected environments.
 
-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.) A normal user pairs exactly one.
+The CLI is **multi-environment**: connect 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 first-use authorization with `--backend <url>`; scope later calls with `--backend <url|env>`.) A normal user connects to the baked-in production backend only.
 
-## Pairing the CLI with the add-in (one-time; you guide the user)
+## Connecting the CLI (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.
+Connecting is the **only** step that genuinely needs the user, and it starts in
+PowerPoint — not here. Every organization runs its own slidemind backend, so an
+unconnected CLI has no address to reach and nothing to discover it from; the
+authenticated add-in knows both, and mints a one-time claim carrying its address.
 
-**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.
+**1 — Ask for the command.** Tell the user to open the **slidemind add-in** task pane → **Settings** → **General** → **Connect CLI**, press the **link button**, and press **Copy command**. If they already have the CLI, **CLI already installed?** swaps it to the shorter `slidemind setup …` form; either works.
 
-**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**.
+**2 — Run it verbatim.** Paste it exactly as given. It redeems the claim, saves the session, installs the CLI globally if needed, deploys the skills into every coding agent on the machine, and finishes by running `ready` — so no `init` and no add-in restart belong to this flow.
 
-**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 ready` still reports no window** (a `no_window` blocker) 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 ready`. 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.
+**3 — If it fails.** A claim works once and expires in ~10 minutes; on *already used or expired*, ask for a fresh one. The pane flips to **Connected** by itself once the claim is spent.
 
 ## First step — `slidemind ready` (before anything else, every time)
 
-Everything about how a deck is authored, styled, and rendered is shaped by the corporate design **the add-in has open**, and every brand rule you follow is read from that design's **materialized bundle**. `slidemind ready` gets you there in one call: it walks the connection ladder (pairing → reachable backend → CLI version → an open render-ready window), resolves which open design to build against, downloads or refreshes that design's bundle (incremental — unchanged files cost nothing), and — when you pass a deck — binds the deck to it by writing `<deck>/.bundle-ref.json`.
+Everything about how a deck is authored, styled, and rendered is shaped by the corporate design **the add-in has open**, and every brand rule you follow is read from that design's **materialized bundle**. `slidemind ready` gets you there in one call: it walks the connection ladder (a saved session → reachable backend → CLI version → an open render-ready window), resolves which open design to build against, downloads or refreshes that design's bundle (incremental — unchanged files cost nothing), and — when you pass a deck — binds the deck to it by writing `<deck>/.bundle-ref.json`.
 
 - **New work:** `slidemind ready` — resolves + materializes the open design's bundle so you can read its `design.md` while planning.
 - **Continuing a deck:** `slidemind ready <deck>` — same, and (re)binds the deck to whatever design is open.
@@ -80,7 +80,7 @@ Everything about how a deck is authored, styled, and rendered is shaped by the c
 **On non-zero** the CLI names exactly one blocker `{code, actor, message}` and one `nextAction`. **The CLI owns the remediation text — relay `nextAction`, don't restate it.** Only two blockers ever need the user:
 
 - **`ambiguous_design`** — several windows with **different** corporate designs are open, so `ready` can't choose. The CLI lists the candidates (each with its `env` and window `title`/`fileName`, plus a design fingerprint); if the deck was last built against one of them it's marked `suggested`. **Ask the user which design to build against, naming the windows by `title`/`fileName` (and `env`) — never by raw id** — and mention the suggested one if present ("this deck was last built against X — continue with it?"). Then re-run `slidemind ready --to <presId>` for the window they pick.
-- **Connection blockers** (`not_paired`, `all_unreachable`, `cli_update_required`, `no_window`, `not_render_ready`) — relay the CLI's `nextAction` verbatim (pair / open PowerPoint / click the pane / run `slidemind update`). Pairing is walked through in *Pairing the CLI with the add-in* above. (`no_window` only ever surfaces for an **unbound** deck or deckless `ready` — a bound deck rides the pane-free rung above instead.)
+- **Connection blockers** (`not_connected`, `all_unreachable`, `cli_update_required`, `no_window`, `not_render_ready`) — relay the CLI's `nextAction` verbatim (copy the setup command / open PowerPoint / click the pane / run `slidemind update`). Connecting is walked through above. (`no_window` only ever surfaces for an **unbound** deck or deckless `ready` — a bound deck rides the pane-free rung above instead.)
 
 **The session spine** (= the stage todos you created up front): `slidemind ready` → read `workflow/flow.md` + `design.md` from `bundleDir` → intake/plan (below) → `slidemind new <slug>` (scaffolds **and** auto-binds the deck to the open design — zero extra download, because `ready` already materialized it) → `slidemind plan <slug>` (plan sign-off gate for decks; single slides stay in chat) → `slidemind concepts <slug>` (mandatory concept-mockup pass for a deck, then rebuild toward each) → author → `view-draft` → `review` (mandatory, the moment the deck builds clean) → deliver (`push` / `build-pptx`). `slidemind new` best-effort binds when the open design is unambiguous and the bundle is already materialized; if it can't (ambiguous, or no host), it scaffolds anyway and hints to run `slidemind ready <slug>`.
 

package/skills/search/SKILL.md

@@ -13,20 +13,20 @@ So this file owns only what is genuinely CLI-specific: the **host precondition**
 
 ## Bootstrap (set yourself up — don't make the user do it)
 
-**The first step of a search session is `slidemind ready --connect-only`** (see *Precondition gate* below). It drives the `slidemind` CLI, which reaches PowerPoint through the add-in's **cloud relay** — no local server. Patch a missing CLI yourself; **pairing** needs the user once (they hold the add-in's identity):
+**The first step of a search session is `slidemind ready --connect-only`** (see *Precondition gate* below). It drives the `slidemind` CLI, which reaches PowerPoint through the add-in's **cloud relay** — no local server. Patch a missing CLI yourself; **connecting** needs the user once (they hold the add-in's identity):
 
-- **CLI missing** (`slidemind` not on `PATH`): `npm install -g slidemind`, then `slidemind init --for <claude|codex|opencode|all>` ((re)deploys this skill).
-- **Not paired** (`ready` blocks with `not_paired`, or a command says *slidemind is not paired*): the one step you can't do for the user. Tell them: in the slidemind add-in open **Settings → General → Connect CLI**, press **Pair**, and run the shown one-time `slidemind pair <code>` command in this terminal (the code expires in ~10 min — re-press **Pair** for a fresh one). `slidemind whoami` lists every paired environment.
+- **CLI missing** (`slidemind` not on `PATH`): `npm install -g slidemind` — that alone is the fix. Add `slidemind init --for <claude|codex|opencode|all>` ((re)deploys this skill) only when this skill did **not** come from a plugin: a `SKILL.md` under a harness plugin cache (`~/.claude/plugins/…`, `~/.codex/plugins/…`) is already deployed, and `init` would just plant a second, drifting copy.
+- **Not connected:** `ready --connect-only` exits with `not_connected` — the CLI cannot start a connection by itself, because the claim carrying the deployment's address is minted in the add-in. Ask the user to open PowerPoint → slidemind → **Settings → General → Connect CLI**, press the **link button**, and copy the command shown (**CLI already installed?** gives the short `slidemind setup …` form). Have them paste it to you and run it **verbatim**. `slidemind whoami` lists connected environments.
 
-This is the same setup as `slidemind-create-slides`, whose **Pairing the CLI with the add-in** section carries the full step-by-step (including the restart-the-add-in-once nudge after a fresh pairing). If you set it up there it's already set up here.
+This is the same connection as `slidemind-create-slides`, whose **Connecting the CLI** section carries the full step-by-step. If it was approved there, it is already available here.
 
 ## Precondition gate (check this first, every time)
 
 Engine search and slide reuse are **host-required** operations — without an open PowerPoint host with the slidemind add-in loaded and an active corporate design, there are no engines to query and nowhere to insert. Check the connection in one call:
 
-1. Run `slidemind ready --connect-only`. It walks the connection ladder (pairing → reachable backend → CLI version → an open window) but does **not** resolve a design or download a bundle — search doesn't need one.
+1. Run `slidemind ready --connect-only`. It walks the connection ladder (a saved session → reachable backend → CLI version → an open window) but does **not** resolve a design or download a bundle — search doesn't need one.
    - **Exit 0 → you're set.** Proceed to `slidemind ls engines` (the live catalog is authoritative — the first real-work step).
-   - **Non-zero →** the CLI names exactly one blocker and one `nextAction`; relay it (pair / open PowerPoint / click the pane / run `slidemind update`). The CLI owns the remediation text — don't restate it.
+   - **Non-zero →** the CLI names exactly one blocker and one `nextAction`; relay it (copy the setup command / open PowerPoint / click the pane / run `slidemind update`). The CLI owns the remediation text — don't restate it.
 2. **Never pick a window for discovery.** The engine catalog is **per-user, not bound to a window**, so search and discovery attach to **any** connected window automatically. **Never ask the user which window to search with**, and don't pass `--to` to search just to disambiguate — leave it off and let the CLI grab one. (A window only matters when you *insert a slide live*, and even then it's simply the window the search already ran on — see Reuse.)
 
 The pane-touching ops here (`search`, `view_slide`, `insert-slide`, `download-result`) wait for the pane themselves: the CLI waits up to ~2 min, prints one *"click the slidemind pane"* line when user help is genuinely needed, and retries safely. Relay that line once and keep waiting — don't re-plan or babysit.

package/src/bridge/client.mjs

@@ -1,7 +1,8 @@
 // Client for the slidemind cloud relay.
 //
 // The CLI talks to `<backendURL>/api/cli/*` with a Bearer session token — both
-// established once by `slidemind pair` (see config.mjs). The add-in's cloud
+// established by redeeming a one-time setup claim minted in the authenticated add-in.
+// The add-in's cloud
 // backend runs render/bundle in-process and relays insert/replace/engine to the
 // open PowerPoint pane. No localhost, no shared loopback token, no cert.
 
@@ -121,11 +122,11 @@ function readinessTimeoutMs() {
 }
 
 const NOT_PAIRED_MESSAGE =
-  'slidemind is not paired. In the slidemind add-in, click "Connect CLI" ' +
-  "and run the shown `slidemind pair …` command, then retry.";
+  "slidemind is not connected. In PowerPoint open slidemind → Settings → " +
+  "General → Connect CLI, press the link button, and run the command it shows.";
 
 // The one-command remedy every host-precondition error now points at:
-// `slidemind ready` runs the whole pairing → reachability → version → window →
+// `slidemind ready` runs authorization → reachability → version → window →
 // design ladder and materializes the bundle, so a stuck author has a single
 // next step instead of a scavenger hunt across doctor/presentations/download.
 // Appended (never substituted) to the existing prose so callers' assert.match
@@ -230,7 +231,7 @@ async function bridgeFetch(pathPart, init = {}, backendURL = null) {
     if (err && /ECONNREFUSED|ECONNRESET|ENOTFOUND|self-signed|fetch failed/i.test(String(err.message || err))) {
       throw new Error(
         `slidemind relay unreachable (${deriveEnvLabel(session.backendURL)}). Check your connection; ` +
-          "if it persists, re-pair with `slidemind pair`.",
+          "if it persists, reconnect from the add-in's Connect CLI panel.",
       );
     }
     throw err;
@@ -238,8 +239,8 @@ async function bridgeFetch(pathPart, init = {}, backendURL = null) {
   enforceVersionFloor(response);
   if (response.status === 401) {
     throw new Error(
-      "slidemind session is invalid or expired. Re-pair: open the add-in, " +
-        'click "Connect CLI", and run the shown `slidemind pair …`.',
+      "slidemind session is invalid or expired. Run `slidemind logout --all`, then " +
+        "reconnect with a fresh command from the add-in's Connect CLI panel.",
     );
   }
   if (response.status < 200 || response.status >= 300) {
@@ -447,7 +448,7 @@ async function bridgeStreamToFile(pathPart, init, destPath, backendURL = null) {
     ) {
       throw new Error(
         `slidemind relay unreachable (${deriveEnvLabel(session.backendURL)}). Check your connection; ` +
-          "if it persists, re-pair with `slidemind pair`.",
+          "if it persists, reconnect from the add-in's Connect CLI panel.",
       );
     }
     throw err;
@@ -455,8 +456,8 @@ async function bridgeStreamToFile(pathPart, init, destPath, backendURL = null) {
   enforceVersionFloor(response);
   if (response.status === 401) {
     throw new Error(
-      "slidemind session is invalid or expired. Re-pair: open the add-in, " +
-        'click "Connect CLI", and run the shown `slidemind pair …`.',
+      "slidemind session is invalid or expired. Run `slidemind logout --all`, then " +
+        "reconnect with a fresh command from the add-in's Connect CLI panel.",
     );
   }
   if (response.status < 200 || response.status >= 300) {

package/src/bridge/config.mjs

@@ -1,5 +1,5 @@
-// CLI session config: where `slidemind pair` stores the cloud relay endpoint(s)
-// + the opaque session token each was issued. The CLI talks to
+// CLI session config: connecting stores the cloud relay endpoint(s) + the
+// opaque session token each was issued. The CLI talks to
 // <backendURL>/api/cli/* with `Authorization: Bearer <sessionToken>`; no
 // localhost, no cert.
 //

package/src/bridge/{pair.mjs → http-json.mjs}

@@ -1,18 +1,14 @@
-// Pairing + session helpers for the CLI side of the cloud relay.
-//
-// `slidemind pair <blob>` decodes {u: backendURL, s: secret} and redeems the
-// one-time secret for an opaque session token, stored by config.mjs. whoami/
-// logout call the session-gated endpoints with that token.
+// Minimal JSON-over-HTTP transport shared by setup-claim redemption and session
+// management. Validates real TLS certificates; loopback development may use a
+// self-signed HTTPS certificate or plain HTTP.
 
 import http from "node:http";
 import https from "node:https";
 
-function isLoopbackHostname(h) {
-  return h === "127.0.0.1" || h === "localhost" || h === "::1";
+function isLoopbackHostname(hostname) {
+  return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
 }
 
-// Minimal JSON request. Validates the cloud's real cert; skips only for a
-// loopback dev backend (self-signed).
 export function httpJson(method, urlStr, { body = null, token = null } = {}) {
   const url = new URL(urlStr);
   const transport = url.protocol === "https:" ? https : http;
@@ -30,11 +26,13 @@ export function httpJson(method, urlStr, { body = null, token = null } = {}) {
         method,
         headers,
         rejectUnauthorized:
-          url.protocol === "https:" ? !isLoopbackHostname(url.hostname) : undefined,
+          url.protocol === "https:"
+            ? !isLoopbackHostname(url.hostname)
+            : undefined,
       },
       (res) => {
         const chunks = [];
-        res.on("data", (c) => chunks.push(Buffer.from(c)));
+        res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
         res.on("end", () => {
           const text = Buffer.concat(chunks).toString("utf8");
           let json = null;
@@ -52,16 +50,3 @@ export function httpJson(method, urlStr, { body = null, token = null } = {}) {
     req.end();
   });
 }
-
-// Decode a `slidemind pair <blob>` code → { backendURL, secret } or null.
-export function decodePairingCode(code) {
-  try {
-    const obj = JSON.parse(Buffer.from(code, "base64url").toString("utf8"));
-    if (obj && typeof obj.u === "string" && typeof obj.s === "string") {
-      return { backendURL: obj.u, secret: obj.s };
-    }
-  } catch {
-    /* malformed */
-  }
-  return null;
-}

package/src/bridge/setup-claim.mjs

@@ -0,0 +1,127 @@
+// One-command setup claims — the CLI half of "click Connect CLI in PowerPoint,
+// paste one command".
+//
+// Why the add-in mints this rather than the CLI: the CLI cannot discover WHICH slidemind
+// deployment a user belongs to. Every customer runs its own backend, so an
+// anonymous CLI has no address to start an approval at. The authenticated
+// add-in already knows its deployment, so it mints a claim that carries the
+// backend URL alongside a one-time secret; the user pastes it once and the CLI
+// learns both at the same moment. This is the ONLY way a CLI gets a session.
+//
+// Wire shape: `smc1_<base64url({ v: 1, u: <backendURL>, s: <secret> })>`.
+// The secret is the credential — it is one-time, short-lived, and bound
+// server-side to the identity that minted it. Nothing here is a bearer token
+// for anything else, and the claim is worthless once redeemed.
+
+import os from "node:os";
+
+import { httpJson } from "./http-json.mjs";
+
+export const SETUP_CLAIM_PREFIX = "smc1_";
+
+function isLoopback(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+
+function invalid(detail) {
+  return new Error(
+    `${detail}\n\n` +
+      "Open PowerPoint → slidemind → Settings → General → Connect CLI and copy a fresh setup command.",
+  );
+}
+
+/**
+ * Decode + validate a setup claim into { backendURL, secret }.
+ *
+ * Tolerates the shapes a copied terminal command actually arrives in: wrapping
+ * whitespace, surrounding quotes, and the whole `npx --yes slidemind@latest
+ * setup <claim>` line pasted as one argument.
+ */
+export function decodeSetupClaim(raw) {
+  let text = String(raw ?? "").trim();
+  // A user who quotes the argument, or pastes the entire command as one shell
+  // word, still gets what they meant.
+  text = text.replace(/^['"]|['"]$/g, "").trim();
+  if (text.includes(SETUP_CLAIM_PREFIX) && !text.startsWith(SETUP_CLAIM_PREFIX)) {
+    const match = text.match(/smc1_[A-Za-z0-9_-]+/);
+    if (match) text = match[0];
+  }
+
+  if (!text.startsWith(SETUP_CLAIM_PREFIX)) {
+    throw invalid(
+      "that does not look like a slidemind setup command (it should end with a smc1_… claim).",
+    );
+  }
+
+  const body = text.slice(SETUP_CLAIM_PREFIX.length);
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+  } catch {
+    throw invalid("this setup command is damaged — it was probably copied only in part.");
+  }
+
+  if (!parsed || parsed.v !== 1) {
+    throw invalid(
+      "this setup command was made by a newer slidemind add-in than this CLI understands. Run `npm install -g slidemind@latest` and try again.",
+    );
+  }
+
+  const secret = typeof parsed.s === "string" ? parsed.s : "";
+  if (!secret) throw invalid("this setup command carries no connection secret.");
+
+  let url;
+  try {
+    url = new URL(String(parsed.u ?? ""));
+  } catch {
+    throw invalid("this setup command carries no valid slidemind address.");
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback(url.hostname))) {
+    throw invalid(
+      "this setup command points at a non-HTTPS slidemind address (HTTP is allowed only for loopback development).",
+    );
+  }
+
+  return { backendURL: url.toString().replace(/\/$/, ""), secret };
+}
+
+/**
+ * Spend the one-time secret at its own deployment and receive the CLI session.
+ * The claim is consumed server-side whether or not this process survives, so a
+ * failure here always means "get a fresh command", never "retry".
+ */
+export async function redeemSetupClaim({ backendURL, secret, cliVersion }) {
+  let result;
+  try {
+    result = await httpJson("POST", `${backendURL}/api/cli/connect/redeem`, {
+      body: {
+        secret,
+        deviceName: os.hostname() || "CLI device",
+        platform: `${process.platform}-${process.arch}`,
+        cliVersion,
+      },
+    });
+  } catch (error) {
+    throw new Error(
+      `could not reach slidemind to complete setup: ${error?.message || error}`,
+    );
+  }
+
+  if (result.status === 200 && result.json?.sessionToken) {
+    return String(result.json.sessionToken);
+  }
+  // Discriminate on the error CODE, not the status. A deployment that predates
+  // one-command setup has no such route, so the request falls through to that
+  // router's session guard and comes back 401 `no_session` — the same status a
+  // spent claim returns. Only the body tells the two apart.
+  if (result.status === 401 && result.json?.error === "setup_claim_invalid_or_expired") {
+    throw invalid("this setup command has already been used or has expired.");
+  }
+  if (result.status === 401 || result.status === 404 || result.status === 405) {
+    throw new Error(
+      "this slidemind add-in is too old for one-command setup — it needs an add-in update before the CLI can connect to it.",
+    );
+  }
+  const detail = result.json?.error || result.text || `HTTP ${result.status}`;
+  throw new Error(`slidemind could not complete setup: ${detail}`);
+}

package/src/builders/build.mjs

@@ -840,10 +840,10 @@ export async function buildDeck(deckDir, opts = {}) {
   if (!fs.existsSync(slidesDir) || !fs.statSync(slidesDir).isDirectory()) {
     throw new Error(`Expected a 'slides/' folder in ${deckDir}`);
   }
-  if (skill.mode === "fill-template" && !opts.internalProposalFreeformRender) {
-    // Proposal decks are PPTX-native. The exporter may render freeform JSX
+  if (skill.mode === "fill-template" && !opts.internalFillFreeformRender) {
+    // fill-template decks are PPTX-native. The exporter may render freeform JSX
     // inserts internally, but `slidemind build` should not create a lossy
-    // presentation.html artifact for proposal decks.
+    // presentation.html artifact for them.
     throw new Error(
       `Deck ${path.basename(deckDir)} uses skill '${skill.skillName}' (mode ` +
         `fill-template); it has no HTML preview. Run 'slidemind build-pptx ` +

package/src/builders/resolve-skill.mjs

@@ -92,12 +92,15 @@ export function resolveDeckMode(deckDir) {
   }
 }
 
-// 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:
+// Skill packs can live outside the npm package: private, org-internal packs
+// (templates, brand-specific assets) are distributed on their own and this
+// package never carries them. Lookup order:
 //   1. $SLIDEMIND_SKILLS_DIR/<name>   (tests / non-standard installs)
 //   2. ~/.config/slidemind/skills/<name>
-//   3. <package>/skills/<name>
+//   3. <package>/skills/<name>        (this CLI's own skills win on their names)
+//   4. the harness skill + plugin dirs (see harnessSkillDirs)
+// 3 precedes 4 so adding 4 is strictly additive: it is reached only for names
+// this package does not ship, i.e. exactly the externally-distributed packs.
 export function userSkillsRoot() {
   return (
     process.env.SLIDEMIND_SKILLS_DIR ||
@@ -109,12 +112,69 @@ export function userSkillsRoot() {
   );
 }
 
-function locateSkillDir(skillName) {
+// Every distribution channel a pack can arrive through — a Claude Code or
+// Codex plugin, or a workspace/admin-pushed skill — installs it into a HARNESS
+// directory, not ours. Without these the agent reads the pack's SKILL.md and
+// the build then fails to find the pack's own templates, which looks like a
+// broken pack rather than a lookup gap.
+//
+// Installers namespace copied skills as `slidemind-<name>`, so both spellings
+// are tried. Plugin caches nest as <root>/<marketplace>/<plugin>/skills/<name>.
+function harnessRoots() {
+  const home = os.homedir();
+  return [
+    path.join(home, ".claude"),
+    path.join(home, ".codex"),
+    // opencode keeps its config under XDG.
+    path.join(
+      process.env.XDG_CONFIG_HOME || path.join(home, ".config"),
+      "opencode",
+    ),
+  ];
+}
+
+function harnessSkillDirs(skillName) {
+  const names = [skillName, `slidemind-${skillName}`];
+  const dirs = [];
+  for (const root of harnessRoots()) {
+    for (const name of names) dirs.push(path.join(root, "skills", name));
+    // Plugin caches: <root>/plugins/cache/<marketplace>/<plugin>/skills/<name>
+    const cacheRoot = path.join(root, "plugins", "cache");
+    let marketplaces = [];
+    try {
+      marketplaces = fs.readdirSync(cacheRoot);
+    } catch {
+      continue;
+    }
+    for (const mp of marketplaces) {
+      let plugins = [];
+      try {
+        plugins = fs.readdirSync(path.join(cacheRoot, mp));
+      } catch {
+        continue;
+      }
+      for (const plugin of plugins) {
+        for (const name of names) {
+          dirs.push(path.join(cacheRoot, mp, plugin, "skills", name));
+        }
+      }
+    }
+  }
+  return dirs;
+}
+
+// Exported for tests: the pack-location rules are the contract every external
+// distribution channel depends on, and they deserve assertions that do not
+// also have to satisfy design resolution.
+export function locateSkillDir(skillName) {
   const candidates = [
     path.join(userSkillsRoot(), skillName),
     path.join(PACKAGE_ROOT, "skills", skillName),
+    ...harnessSkillDirs(skillName),
   ];
-  return firstExisting(candidates) ?? candidates[candidates.length - 1];
+  // The fallback stays the package path, so a missing pack still reports the
+  // location a bundled skill would live at rather than a harness cache dir.
+  return firstExisting(candidates) ?? path.join(PACKAGE_ROOT, "skills", skillName);
 }
 
 export function resolveSkill(skillName, planMeta = {}, opts = {}) {

package/src/installers/claude.mjs

@@ -14,6 +14,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import {
+  binaryOnPath,
   expandHome,
   installDir,
   isForce,
@@ -91,6 +92,29 @@ function pluginInstallDetected() {
   }
 }
 
+// Is Claude Code on this machine, and would deploying here duplicate a plugin?
+// `--for auto` (what `slidemind setup` uses) installs only where the harness
+// actually exists AND its plugin has not already supplied the skills — copying
+// over a plugin's skills plants a second set that drifts on the next plugin
+// update, which is the one thing plugin users must not do.
+//
+// Two signals, because either alone misses a real install: the config dir is
+// created the first time the agent RUNS (so a just-installed, never-launched
+// Claude Code has none), while the binary is missing for a desktop-app-only
+// install. Present if either says so.
+export function detect() {
+  const root = claudeRoot();
+  const configured = fs.existsSync(root);
+  const onPath = binaryOnPath("claude");
+  return {
+    root,
+    configured,
+    onPath,
+    present: configured || onPath,
+    pluginInstalled: pluginInstallDetected(),
+  };
+}
+
 export async function install({ packageRoot, flags }) {
   const link = isLinkMode(flags);
   const force = isForce(flags);

package/src/installers/codex.mjs

@@ -25,6 +25,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import {
+  binaryOnPath,
   expandHome,
   installDir,
   isForce,
@@ -81,6 +82,33 @@ function agentsFile() {
   return path.join(codexRoot(), "AGENTS.md");
 }
 
+// `$CODEX_HOME/plugins/cache/<marketplace>/slidemind/<version>/` — a non-empty
+// plugin directory means the Codex plugin is also installed, so the skills
+// copied by `init` duplicate the ones the plugin already carries (and will
+// drift the next time either side updates). Mirrors the Claude installer's
+// check. A marketplace-only `cache/slidemind/` (added but never installed from)
+// holds no `slidemind` child, so it correctly reads as "not installed".
+export function pluginInstallDetected() {
+  const cacheRoot = path.join(codexRoot(), "plugins", "cache");
+  try {
+    return fs.readdirSync(cacheRoot).some((mp) => {
+      const dir = path.join(cacheRoot, mp, NAMESPACE);
+      try {
+        return (
+          fs.statSync(dir).isDirectory() &&
+          fs
+            .readdirSync(dir)
+            .some((entry) => !entry.startsWith("."))
+        );
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+
 function configTomlFile() {
   return path.join(codexRoot(), "config.toml");
 }
@@ -119,13 +147,18 @@ function writeAgentsBlock() {
   const block =
     `${AGENTS_MARK_BEGIN}\n` +
     `## slidemind\n` +
-    `Slide-deck authoring skill installed via slidemind.\n` +
+    `Slide-deck authoring and slide-reuse skills installed via slidemind.\n` +
     `\n` +
     `When the user asks to create, plan, or edit a slide deck or presentation, load\n` +
     `the \`slidemind-create-slides\` skill (auto-discovered from\n` +
-    `${skillTarget("create-slides")}/SKILL.md) and follow it. The skill drives the\n` +
-    `slidemind PowerPoint add-in and reads every brand rule — tokens, layout\n` +
-    `palette, brand imagery — from the design bundle the add-in serves.\n` +
+    `${skillTarget("create-slides")}/SKILL.md) and follow it.\n` +
+    `\n` +
+    `When the user asks to find or reuse an existing slide or brand image — from the\n` +
+    `corporate design's engines or from a \`.pptx\` on disk — load the\n` +
+    `\`slidemind-search\` skill (${skillTarget("search")}/SKILL.md) instead.\n` +
+    `\n` +
+    `Both drive the slidemind PowerPoint add-in and read every brand rule — tokens,\n` +
+    `layout palette, brand imagery — from the design bundle the add-in serves.\n` +
     `\n` +
     `Build with: \`slidemind build <deck>\` (HTML) or \`slidemind build-pptx <deck>\` (PPTX).\n` +
     `${AGENTS_MARK_END}\n`;
@@ -155,6 +188,20 @@ function clearAgentsBlock() {
   fs.writeFileSync(file, existing);
 }
 
+// See claude.mjs `detect()` — same two-signal contract, Codex roots.
+export function detect() {
+  const root = codexRoot();
+  const configured = fs.existsSync(root);
+  const onPath = binaryOnPath("codex");
+  return {
+    root,
+    configured,
+    onPath,
+    present: configured || onPath,
+    pluginInstalled: pluginInstallDetected(),
+  };
+}
+
 export async function install({ packageRoot, flags }) {
   const link = isLinkMode(flags);
   const force = isForce(flags);
@@ -202,6 +249,15 @@ export async function install({ packageRoot, flags }) {
     ui.step({ status: "remove", label: "mcp server", value: mcpNote });
   }
 
+  if (pluginInstallDetected()) {
+    ui.step({
+      status: "info",
+      label: "plugin",
+      value:
+        "the slidemind Codex plugin is also installed — these copied skills duplicate its skills; plugin users only need `npm install -g slidemind` and can drop them with `slidemind uninstall --for codex`",
+    });
+  }
+
   ui.note("restart Codex to pick up the skill");
 }