slidemind 0.0.29 → 0.1.1

package/CLAUDE.md

@@ -64,7 +64,7 @@ slidemind/
 ├── .claude-plugin/
 │   └── plugin.json               Claude Code plugin manifest
 ├── bin/
-│   └── slidemind.mjs             CLI dispatcher (presentations, download-bundle, init, build, build-pptx, push, search, install)
+│   └── slidemind.mjs             CLI dispatcher (presentations, download-bundle, init, build, build-pptx, push, search, install, pair/whoami/use/logout)
 ├── skills/                       canonical, installable skill payload — thin CLI workflow glue only
 │   └── create-slides/
 │       └── SKILL.md              the whole skill: host gate + intake/plan + create flow + CLI⇄in-app command map.
@@ -95,12 +95,18 @@ slidemind build <deck>             # build self-contained HTML preview
 slidemind build-pptx <deck>        # render native .pptx via the add-in (HOST REQUIRED)
 slidemind push <deck>              # render + push slides into a running PowerPoint (HOST REQUIRED)
 slidemind search "<query>"         # search the brand engine for imagery (HOST REQUIRED)
+slidemind pair <code>              # pair with an add-in environment (copy from its "Connect CLI")
+slidemind whoami                   # list every paired environment (* = default)
+slidemind use <url|env>            # set the default environment
+slidemind logout [url|env]         # unpair one environment (--all unpairs every one)
 slidemind init --for <target>   # install skill into claude | codex | opencode | all
 slidemind uninstall --for <target>
 ```
 
 `<deck>` resolves as: absolute path → `./<arg>` if it exists → `./decks/<arg>`. The decks directory is `./decks/` by default; override with `SLIDEMIND_DECKS=/abs/path`.
 
+**Multi-environment pairing.** The CLI stores one session **per backend** (`~/.config/slidemind/session.json`, v2 `{version, sessions[], default}`; the legacy single-record v1 shape is migrated on read). Pair once per environment (local / dev / prod) and every command **fans out** across all paired backends, tags each open window with its `env`, and **routes by the presentation's origin backend** automatically — no manual switching. Scope a command to one backend with `--backend <url|env>` (or `SLIDEMIND_BACKEND`). This is a developer convenience; a normal user pairs exactly one. See the memory note *CLI↔add-in: cloud relay + pairing*.
+
 **The design truth lives in the add-in, not the CLI.** The `.pptx` is rendered server-side over the local bridge (no local exporter), the corporate design is fetched as a bundle, and brand imagery comes from the add-in's engine. So `create`/`build-pptx`/`push`/`search` all hard-require an **open PowerPoint host with the slidemind add-in and an active corporate design**. See `docs/slidemind-cli-connect/`.
 
 ## Design system ground rules

package/README.md

@@ -62,6 +62,33 @@ slidemind push my-deck --slides 02,05,07  # push only a subset of source slides
 
 If `slidemind presentations` returns nothing, the add-in isn't running — open PowerPoint with the slidemind add-in and an active corporate design, then retry. (Rendering is server-side now, so `build-pptx` needs a host too.)
 
+## Pairing
+
+The CLI reaches PowerPoint through the add-in's cloud relay. Pair once: in the add-in click **"Connect CLI"** and run the shown command.
+
+```bash
+slidemind pair <code>          # copy the exact command from the add-in's "Connect CLI"
+slidemind whoami               # show the paired account
+slidemind logout               # unpair this machine
+```
+
+### Pairing multiple environments
+
+For slidemind developers who run the add-in against more than one backend (local / dev / prod), the CLI is **multi-environment**: pair once per backend and every command automatically discovers your open PowerPoint across all of them — no manual switching.
+
+```bash
+slidemind pair <local-code> --label local
+slidemind pair <dev-code>   --label dev
+slidemind whoami                          # lists every paired environment (* = default)
+slidemind presentations                   # windows from all environments, each tagged [env]
+slidemind push my-deck --to <presId>      # routed to whichever environment owns that window
+slidemind use dev                         # set the default environment
+slidemind logout dev                      # unpair one (or --all to unpair every one)
+slidemind --backend local presentations   # scope a single command to one environment
+```
+
+Each "Connect CLI" code carries its own backend URL and session token, so pairing is per-environment and routing is automatic. A normal user just pairs one.
+
 ## Export formats at a glance
 
 | Command | Output | When to use |

package/bin/slidemind.mjs

@@ -59,6 +59,12 @@ function printHelp() {
       `                                     --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` +
+      `  slidemind pair <code>            Pair with an add-in (copy the code from its "Connect CLI")\n` +
+      `                                     --label <name>  name this environment (default: derived from URL)\n` +
+      `                                   Pair once per environment; commands fan out across all of them.\n` +
+      `  slidemind whoami                 Show every paired environment (* = default)\n` +
+      `  slidemind use <url|env>          Set the default environment\n` +
+      `  slidemind logout [url|env]       Unpair one environment (--all to unpair every one)\n` +
       `  slidemind init --for <t>         Set up slidemind in a harness (registers the MCP server + skill)\n` +
       `  slidemind uninstall --for <t>    Remove a previously-installed skill\n` +
       `  slidemind update [--for <t>]     Fetch the latest release and redeploy\n` +
@@ -69,7 +75,8 @@ function printHelp() {
       `\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`,
+      `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`,
   );
 }
 
@@ -218,10 +225,12 @@ async function cmdSearch(rest) {
     pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
   );
   const registry = await client.requireHost();
-  const presId = client.pickPresentation(registry, to);
+  const entry = client.pickPresentationEntry(registry, to);
+  const presId = entry.presId;
+  const backendURL = entry.backendURL ?? null;
 
   if (!engineId) {
-    const mat = await bundle.materializeBundle(presId);
+    const mat = await bundle.materializeBundle(presId, { backendURL });
     const pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
     if (!pick) {
       fail(
@@ -231,7 +240,7 @@ async function cmdSearch(rest) {
     engineId = pick.id;
   }
 
-  const res = await client.engineSearch({ presId, engineId, query });
+  const res = await client.engineSearch({ presId, engineId, query, backendURL });
   if (asJson) {
     process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
     return;
@@ -276,8 +285,12 @@ async function cmdDownloadBundle(rest) {
     pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
   );
   const registry = await client.requireHost();
-  const presId = client.pickPresentation(registry, to);
-  const result = await bundle.materializeBundle(presId, { force });
+  const entry = client.pickPresentationEntry(registry, to);
+  const presId = entry.presId;
+  const result = await bundle.materializeBundle(presId, {
+    force,
+    backendURL: entry.backendURL ?? null,
+  });
 
   // Optionally bind a deck to this bundle so build-pptx/push pass the right
   // etag and the local HTML/editor read the right design files.
@@ -306,7 +319,9 @@ async function cmdPresentations(rest) {
   );
   const list = await mod.listOpenPresentations();
   if (asJson) {
-    process.stdout.write(JSON.stringify(list, null, 2) + "\n");
+    process.stdout.write(
+      JSON.stringify(list.map(mod.toPublicPresentation), null, 2) + "\n",
+    );
     return;
   }
   if (list.length === 0) {
@@ -317,8 +332,167 @@ async function cmdPresentations(rest) {
   }
   for (const p of list) {
     const label = p.title || p.fileName || "(untitled)";
-    process.stdout.write(`${p.presId}\t${label}\n`);
+    const env = p.env ? `[${p.env}]\t` : "";
+    process.stdout.write(`${p.presId}\t${env}${label}\n`);
+  }
+}
+
+async function loadBridgeModule(name) {
+  return import(pathToFileURL(path.join(SRC_DIR, "bridge", `${name}.mjs`)).href);
+}
+
+async function cmdPair(rest) {
+  let code = null;
+  let label = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--label") {
+      label = rest[++i];
+      if (!label) fail("--label expects a name");
+    } else if (!a.startsWith("--") && !code) {
+      code = a;
+    }
+  }
+  if (!code) {
+    fail('usage: slidemind pair <code>   (copy the command from the add-in\'s "Connect CLI")');
+  }
+  const pairMod = await loadBridgeModule("pair");
+  const decoded = pairMod.decodePairingCode(code);
+  if (!decoded) {
+    fail("invalid pairing code — copy the exact `slidemind pair …` command shown in the add-in");
+  }
+  const res = await pairMod.httpJson(
+    "POST",
+    `${decoded.backendURL}/api/cli/pair/redeem`,
+    { body: { secret: decoded.secret } },
+  );
+  if (res.status !== 200 || !res.json?.sessionToken) {
+    fail(
+      `pairing failed (${res.status}): ${res.json?.error || "no session returned"}\n` +
+        "the code may have expired — generate a fresh one in the add-in's \"Connect CLI\"",
+    );
+  }
+  const cfg = await loadBridgeModule("config");
+  const sessions = cfg.upsertSession({
+    backendURL: decoded.backendURL,
+    sessionToken: res.json.sessionToken,
+    label,
+  });
+  const env = cfg.deriveEnvLabel(decoded.backendURL);
+  const others = sessions.length - 1;
+  const suffix =
+    others > 0
+      ? ` (${sessions.length} environments connected — commands now fan out across all of them)`
+      : "";
+  process.stdout.write(
+    `Paired with ${label || env}${suffix}. Run 'slidemind presentations' to verify.\n`,
+  );
+}
+
+async function cmdWhoami() {
+  const cfg = await loadBridgeModule("config");
+  const sessions = cfg.readSessions();
+  if (sessions.length === 0) {
+    process.stderr.write(
+      'Not paired. Run `slidemind pair <code>` using the add-in\'s "Connect CLI".\n',
+    );
+    return;
+  }
+  const pairMod = await loadBridgeModule("pair");
+  const def = cfg.getDefaultBackend();
+  const lines = await Promise.all(
+    sessions.map(async (s) => {
+      const marker = s.backendURL === def ? "*" : " ";
+      let detail;
+      try {
+        const res = await pairMod.httpJson(
+          "GET",
+          `${s.backendURL}/api/cli/whoami`,
+          { token: s.sessionToken },
+        );
+        detail =
+          res.status === 200 && res.json
+            ? `user ${res.json.oid} · tenant ${res.json.tid ?? "(n/a)"}`
+            : `session invalid (${res.status}) — re-pair`;
+      } catch {
+        detail = "unreachable — check your connection or re-pair";
+      }
+      return `${marker} ${s.label}\n    ${detail}`;
+    }),
+  );
+  process.stdout.write(
+    `Paired environments (${sessions.length}):\n${lines.join("\n")}\n`,
+  );
+}
+
+async function cmdLogout(rest) {
+  const cfg = await loadBridgeModule("config");
+  const all = rest.includes("--all");
+  const target = rest.find((a) => !a.startsWith("--")) ?? null;
+
+  // Which sessions to revoke + remove: all, one (by url/env/label), or the
+  // default (the bare `slidemind logout`).
+  const sessions = cfg.readSessions();
+  if (sessions.length === 0) {
+    process.stdout.write("Already logged out.\n");
+    return;
+  }
+  let toRemove;
+  if (all) {
+    toRemove = sessions;
+  } else if (target) {
+    toRemove = sessions.filter(
+      (s) =>
+        s.backendURL === target ||
+        s.label === target ||
+        cfg.deriveEnvLabel(s.backendURL) === target ||
+        s.backendURL.includes(target),
+    );
+    if (toRemove.length === 0) {
+      fail(`not paired with '${target}'. Run 'slidemind whoami' to list environments.`);
+    }
+  } else {
+    const def = cfg.getDefaultBackend();
+    toRemove = sessions.filter((s) => s.backendURL === def);
+  }
+
+  const pairMod = await loadBridgeModule("pair");
+  for (const s of toRemove) {
+    try {
+      await pairMod.httpJson("POST", `${s.backendURL}/api/cli/logout`, {
+        token: s.sessionToken,
+      });
+    } catch {
+      /* best-effort server-side revoke; we still drop the local session */
+    }
+    cfg.removeSession(s.backendURL);
   }
+  const remaining = cfg.readSessions().length;
+  process.stdout.write(
+    `Logged out of ${toRemove.map((s) => s.label).join(", ")}.` +
+      (remaining > 0 ? ` ${remaining} environment(s) still paired.\n` : "\n"),
+  );
+}
+
+async function cmdUse(rest) {
+  const target = rest.find((a) => !a.startsWith("--")) ?? null;
+  if (!target) fail("usage: slidemind use <url|env>");
+  const cfg = await loadBridgeModule("config");
+  const sessions = cfg.readSessions();
+  const match = sessions.find(
+    (s) =>
+      s.backendURL === target ||
+      s.label === target ||
+      cfg.deriveEnvLabel(s.backendURL) === target ||
+      s.backendURL.includes(target),
+  );
+  if (!match) {
+    fail(`not paired with '${target}'. Run 'slidemind whoami' to list environments.`);
+  }
+  cfg.setDefaultBackend(match.backendURL);
+  process.stdout.write(
+    `Default environment set to ${match.label}.\n`,
+  );
 }
 
 async function cmdPush(rest) {
@@ -370,6 +544,12 @@ async function cmdPush(rest) {
     replace,
     slideIds: slides,
   });
+  for (const w of result.warnings ?? []) {
+    process.stderr.write(`  warning: ${w}\n`);
+  }
+  for (const s of result.skippedSlides ?? []) {
+    process.stderr.write(`  skipped ${s.stem}: ${s.reason}\n`);
+  }
   if (result.paneSuspended) {
     process.stdout.write(
       `PowerPoint is backgrounded — the deck rendered but couldn't be pushed.\n` +
@@ -401,7 +581,8 @@ async function cmdNew(rest) {
     path.join(deckDir, "plan.md"),
     `# ${name}\n\n` +
       `Ask your agent (Claude Code / Codex / opencode) to plan and author this deck —\n` +
-      `the slidemind-create-slides skill fills this in, then writes slides under ./slides/.\n`,
+      `the slidemind-create-slides skill fills this in, then writes slides under ./slides/\n` +
+      `as NN-<topic>.jsx (zero-padded prefix — slide order is filename order).\n`,
   );
   process.stdout.write(`Created ${path.relative(process.cwd(), deckDir)}\n`);
   process.stdout.write(
@@ -546,7 +727,26 @@ async function cmdUpdate(rest) {
 
 // ---------- main ----------
 
-async function main(argv) {
+// Pull a global `--backend <url|env>` out of argv (it may appear anywhere) and
+// expose it as SLIDEMIND_BACKEND, which scopes the fan-out across paired
+// backends down to one — for speed or to disambiguate a presId that's open in
+// more than one environment. Returns argv with the flag (and its value) removed.
+function extractBackendScope(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--backend") {
+      const val = argv[++i];
+      if (!val) fail("--backend expects a url or env name");
+      process.env.SLIDEMIND_BACKEND = val;
+    } else {
+      out.push(argv[i]);
+    }
+  }
+  return out;
+}
+
+async function main(rawArgv) {
+  const argv = extractBackendScope(rawArgv);
   const [cmd, ...rest] = argv;
   if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
     printHelp();
@@ -572,6 +772,18 @@ async function main(argv) {
     case "new":
       await cmdNew(rest);
       return 0;
+    case "pair":
+      await cmdPair(rest);
+      break;
+    case "whoami":
+      await cmdWhoami(rest);
+      break;
+    case "logout":
+      await cmdLogout(rest);
+      break;
+    case "use":
+      await cmdUse(rest);
+      break;
     case "presentations":
       await cmdPresentations(rest);
       return 0;

package/package.json

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

package/skills/create-slides/SKILL.md

@@ -13,18 +13,15 @@ This skill is **thin workflow glue for the local harness**. Everything that dete
 
 So this file owns only what is genuinely CLI-specific: the **host precondition**, a compact **intake/plan**, the **create flow**, and the **command mapping** that translates the add-in's in-app tool names (used throughout the bundle's `workflow/*.md`) into your `slidemind` commands and MCP tools. Read the workflow + brand from the bundle; never restate or duplicate them here.
 
-## Make sure the slidemind CLI is installed (npm)
+## Bootstrap (set yourself up — don't make the user do it)
 
-This skill drives the `slidemind` CLI and its MCP server (`slidemind_list_open_presentations`, `slidemind_push_deck`, `slidemind_search_engine`, `slidemind_download_result`). If `slidemind` isn't on `PATH` — or those `slidemind_*` MCP tools aren't available — install the package from npm, then register it with the harness:
+This skill drives the `slidemind` CLI + its MCP server (`slidemind_list_open_presentations`, `slidemind_push_deck`, `slidemind_search_engine`, `slidemind_download_result`). The CLI reaches PowerPoint through the add-in's **cloud relay** — it doesn't run any local server. Patch what's missing yourself, but the **pairing** step needs the user once (they hold the add-in's identity):
 
-```bash
-npm install -g slidemind
-slidemind init --for <claude|codex|opencode|all>   # registers the MCP server + (re)deploys this skill
-```
+- **CLI missing** (`slidemind` not on `PATH`, or the `slidemind_*` MCP tools absent): `npm install -g slidemind`, then `slidemind init --for <claude|codex|opencode|all>` (registers the MCP server + (re)deploys this skill). The harness may need a restart for the `slidemind_*` tools to appear.
+- **Not paired** (a command says *slidemind is not paired*): this is the one step you can't do for the user. Tell them: in the slidemind add-in click **"Connect CLI"**, then paste the shown `slidemind pair …` command into this terminal. It's one-time per environment (the code carries that backend's URL + a session token — no hardcoded URLs, no separate login; the add-in's own session is the auth). `slidemind whoami` lists every paired environment.
+- `npx slidemind <command>` runs one-off without a global install; `slidemind --version` confirms PATH; `slidemind update` upgrades (`--ref <version>` to pin).
 
-- For a one-off command without a global install, `npx slidemind <command>` works.
-- `slidemind --version` confirms it's on `PATH`. `slidemind update` upgrades to the latest npm release (`--ref <version>` to pin).
-- If `slidemind init` just registered the MCP server, the harness may need a restart before the `slidemind_*` tools appear.
+After pairing once: **CLI paired + the add-in open ≡ it just works**, against whatever environment (dev / prod / a client deployment) the add-in is wired to. The CLI is **multi-environment**: pair once per backend (local / dev / prod) and every command fans out across all of them, tags each open window with its `env`, and routes to the right backend automatically — no manual switching. (Scope to one with `--backend <url|env>` when you need to.)
 
 ## Precondition gate (check this first, every time)
 
@@ -34,6 +31,8 @@ Authoring and rendering hard-require an **open PowerPoint host with the slidemin
 2. One registered → that's your target `presentation_id`. **Several → ask the user which**, by `title`/`fileName` (never raw ids) — once for **which presentation's corporate design to download**, and again at render time for **which presentation to push into** (the CD source and the push target may be different presentations).
 3. **None registered → stop.** Tell the user: *open PowerPoint, load the slidemind add-in, and pick or create a corporate design, then retry.*
 
+> **Empty list vs. not paired — different fixes.** An *empty* registry means no PowerPoint is connected (step 3 → ask the user to open it / enable Connect CLI). A *not paired* error means this machine has no session — ask the user to pair once via the add-in's **"Connect CLI"** (see Bootstrap); don't ask them to open PowerPoint for that.
+
 **Backgrounded PowerPoint is expected to work.** Do not pre-emptively ask the user to focus PowerPoint or the task pane. The bridge retains the registered presentation and pane-free routes keep working; live push/replace waits for the task-pane socket to reconnect if it truly dropped. Only if a command fails with *no host registered* (or a bridge wait timeout) do you ask the user to click the slidemind task pane once so it reconnects, then retry the same command — the deck and bundle are already prepared. Reserve the full "open PowerPoint…" instruction in (3) for when nothing is registered at all.
 
 Local HTML preview (`slidemind build`) runs offline, but it reads a **previously materialized bundle** — so the host must have been available at least once.
@@ -56,7 +55,7 @@ Keep planning about intent and content. Don't materialize the bundle or read bra
    - `corporate-design.css`, `layouts/*.jsx`, `layouts/layouts.css`, `assets/`, `samples/` (the brand's own reference slides), `engines.json`.
    - `workflow/` — the add-in-owned authoring craft: `create.md`, `edit.md`, `composition.md`, `layouts.md`, `authoring.md`, `build-and-export.md`.
 3. **Study brand samples (before composing).** The materialized bundle's `samples/` dir holds the brand's own reference slides. If it's non-empty, pick **3 at random** and **Read** each (the Read tool renders images) *before* writing any JSX — this is the local-harness stand-in for the in-app persona's reference thumbnails, and it is what keeps a deck looking on-brand rather than merely compliant. Study them for whitespace rhythm, shape density, hierarchy, accent use, and layering, then compose in that spirit (never copy a sample 1:1). This is `composition.md`'s samples discipline; skip only when `samples/` is empty.
-4. **Read, then author.** Read the four create-stage references together — `workflow/create.md` (the procedure), `workflow/composition.md` (the composition baseline), `workflow/layouts.md` (palette + working area), and `workflow/authoring.md` (the substrate rules) — plus the deck's `design.md` and the specific `layouts/*.jsx` the plan uses. (That is the read set `workflow/create.md` → Context loading prescribes; follow it as written.) Then write `decks/<slug>/slides/*.jsx` — one default export per slide, composing one bundle layout (Mode A) or a blank-content layout with freeform children (Mode B), exactly as those docs prescribe.
+4. **Read, then author.** Read the four create-stage references together — `workflow/create.md` (the procedure), `workflow/composition.md` (the composition baseline), `workflow/layouts.md` (palette + working area), and `workflow/authoring.md` (the substrate rules) — plus the deck's `design.md` and the specific `layouts/*.jsx` the plan uses. (That is the read set `workflow/create.md` → Context loading prescribes; follow it as written.) Then write `decks/<slug>/slides/NN-<topic>.jsx` — zero-padded numeric prefix from the first file on (play order is filename order here; see the slide-file row in the command mapping), one default export per slide, composing one bundle layout (Mode A) or a blank-content layout with freeform children (Mode B), exactly as those docs prescribe.
 5. **Imagery from the engine.** Per the `### Brand Image Sources` block in `design.md`, search the brand engine and place results (see the command mapping — this is `engine_search`/`engine_add` in the workflow docs).
 6. **Render / push.** `slidemind push <deck>` (into PowerPoint) or `slidemind build-pptx <deck>` (to a file) — both render server-side. This is `build_and_push` in `workflow/build-and-export.md`. If several presentations are open, confirm **which one to push into** first (it can differ from the CD source). **Run the push without asking otherwise**; it should work while PowerPoint is backgrounded. If it times out waiting for a true task-pane reconnect, ask the user to click the slidemind task pane once and re-run `push` without rebuilding.
 7. **Sanity pass.** Run the checks in `workflow/create.md` before reporting done.
@@ -80,7 +79,7 @@ The bundle's `workflow/*.md` are written for the in-app design agent and name **
 | `build_and_push` | `slidemind push <deck>` (into the open PowerPoint) · `slidemind build-pptx <deck>` (to a `.pptx` file) — both render server-side via the bridge |
 | `engine_search` | MCP `slidemind_search_engine({ presentation_id, query })` → returns a `searchId` + numbered results |
 | `engine_add` / `insert_image` | MCP `slidemind_download_result({ presentation_id, deck_path, search_id, selection, icon_color? })` — or batch many at once with `selections: [{ selection, icon_color? }, …]`. Writes each asset into `decks/<slug>/assets/`, returns a `./assets/<file>` reference for `<img src=...>` plus a `recolor` descriptor (see *Recolouring engine icons*) |
-| writing `slides/<topic>.jsx` in the chat workspace | write files under `decks/<slug>/slides/*.jsx` on disk |
+| writing `slides/<topic>.jsx` in the chat workspace — unprefixed kebab-case names; play order = the ordered list passed to `build_and_push` | write `decks/<slug>/slides/NN-<topic>.jsx` on disk with a **zero-padded numeric prefix** (`01-cover.jsx`, `02-agenda.jsx`, …) — over the CLI play order is **numeric-aware filename order**; there is no ordered-list channel, so reordering = renaming files. The bundle's "don't pad with index prefixes" rule is in-app-only; here it inverts |
 | reading workspace files (`design.md`, `layouts/`, `workflow/*`) | read them from the materialized bundle dir (`<bundle>/…`) and your `decks/<slug>/` |
 | reference-slide thumbnails injected at `add_slide` (in-app persona) | **Read** 3 random images from the materialized bundle's `samples/` dir — the Read tool renders them (see *The create flow* step 3) |
 | `present_plan_for_review` (manager-owned) | **you** run intake → plan with the user (above); persist `decks/<slug>/plan.md` for decks |

package/src/bridge/build-and-push.mjs

@@ -14,7 +14,7 @@ import { randomUUID } from "node:crypto";
 
 import {
   insertSlides,
-  pickPresentation,
+  pickPresentationEntry,
   renderPptx,
   replaceSlides,
   requireHost,
@@ -24,16 +24,16 @@ import {
   readDeckBundleRef,
   writeDeckBundleRef,
 } from "./bundle.mjs";
+import { slideOrderWarning, sortSlideFilenames } from "../lib/slide-order.mjs";
 
 function gatherSlides(deckDir) {
   const slidesDir = path.join(deckDir, "slides");
   if (!fs.existsSync(slidesDir) || !fs.statSync(slidesDir).isDirectory()) {
     throw new Error(`Expected 'slides/' folder in ${deckDir}`);
   }
-  const files = fs
-    .readdirSync(slidesDir)
-    .filter((f) => f.endsWith(".jsx"))
-    .sort();
+  const files = sortSlideFilenames(
+    fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx")),
+  );
   if (files.length === 0) {
     throw new Error(`No .jsx slides under ${slidesDir}`);
   }
@@ -41,7 +41,7 @@ function gatherSlides(deckDir) {
   for (const f of files) {
     slides[f] = fs.readFileSync(path.join(slidesDir, f), "utf8");
   }
-  return slides;
+  return { slides, orderWarning: slideOrderWarning(files) };
 }
 
 // Collect deck-local assets (icons the agent downloaded, deck photos) as
@@ -68,8 +68,8 @@ function gatherDeckAssets(deckDir) {
 
 // Render a deck to base64 .pptx over the bridge. Pass the deck's authored-against
 // bundle etag (when recorded) so the server can detect CD skew.
-export async function renderDeckToBase64(deckDir, { presId }) {
-  const slides = gatherSlides(deckDir);
+export async function renderDeckToBase64(deckDir, { presId, backendURL = null }) {
+  const { slides, orderWarning } = gatherSlides(deckDir);
   const deckAssets = gatherDeckAssets(deckDir);
   // Bind the deck to a materialized bundle if it isn't already. Without a
   // `.bundle-ref.json` the etag below is null (server-side skew detection
@@ -79,7 +79,7 @@ export async function renderDeckToBase64(deckDir, { presId }) {
   let ref = readDeckBundleRef(deckDir);
   if (!ref?.etag) {
     try {
-      const mat = await materializeBundle(presId);
+      const mat = await materializeBundle(presId, { backendURL });
       writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
       ref = readDeckBundleRef(deckDir);
     } catch {
@@ -93,10 +93,14 @@ export async function renderDeckToBase64(deckDir, { presId }) {
     slides,
     deckAssets,
     etag: ref?.etag ?? null,
+    backendURL,
   });
   if (!result?.base64) {
     throw new Error("render-pptx returned no pptx bytes");
   }
+  if (orderWarning) {
+    result.warnings = [orderWarning, ...(result.warnings ?? [])];
+  }
   return result; // { ok, base64, slideCount, warnings, skippedSlides }
 }
 
@@ -122,9 +126,11 @@ export async function buildAndPush({
   }
 
   const registry = await requireHost();
-  const presId = pickPresentation(registry, presentationId);
+  const entry = pickPresentationEntry(registry, presentationId);
+  const presId = entry.presId;
+  const backendURL = entry.backendURL ?? null;
 
-  const result = await renderDeckToBase64(deckDir, { presId });
+  const result = await renderDeckToBase64(deckDir, { presId, backendURL });
   const base64 = result.base64;
   const bytes = Buffer.byteLength(base64, "base64");
   const mode = replace ? "replace" : "insert";
@@ -132,13 +138,14 @@ export async function buildAndPush({
 
   const doPush = () =>
     replace
-      ? replaceSlides({ presId, base64, operationId })
+      ? replaceSlides({ presId, base64, operationId, backendURL })
       : insertSlides({
           presId,
           base64,
           insertAt,
           sourceSlideIds: slideIds,
           operationId,
+          backendURL,
         });
 
   const resp = await doPush();
@@ -162,8 +169,12 @@ export async function buildPptxFile({
 }) {
   if (!deckDir) throw new Error("buildPptxFile: deckDir is required");
   const registry = await requireHost();
-  const presId = pickPresentation(registry, presentationId);
-  const result = await renderDeckToBase64(deckDir, { presId });
+  const entry = pickPresentationEntry(registry, presentationId);
+  const presId = entry.presId;
+  const result = await renderDeckToBase64(deckDir, {
+    presId,
+    backendURL: entry.backendURL ?? null,
+  });
   const out =
     outPath || path.join(deckDir, `${path.basename(deckDir)}.pptx`);
   fs.writeFileSync(out, Buffer.from(result.base64, "base64"));

package/src/bridge/bundle.mjs

@@ -8,6 +8,14 @@
 // the presentation fingerprint (`presFP`) so multiple decks sharing a CD share
 // one materialized bundle.
 //
+// NOTE (multi-backend): with the CLI paired to several backends (local/dev/prod)
+// the cache is shared across them and keyed ONLY by `presFP`. That assumes a
+// backend contract: `presFP` must be globally unique across deployments (it is a
+// corporate-design fingerprint, deliberately shared across decks/presentations
+// on the same CD — so it must NOT be keyed by backendURL, which would break that
+// sharing). If two backends ever mint the same presFP for different content,
+// they would collide here.
+//
 //   ${XDG_CACHE_HOME:-~/.cache}/slidemind/bundles/<presFP>/
 //   ├── corporate-design.css      (from wire.css)
 //   ├── design.md                 (from wire.designRules)
@@ -120,8 +128,11 @@ function sampleExt(contentType) {
 // Fetch + write the bundle for `presId`. Returns { dir, presFP, etag, version,
 // cached }. Skips the re-download when the cached bundle's etag already matches
 // (unless `force`).
-export async function materializeBundle(presId, { force = false } = {}) {
-  const wire = await getDesignBundle(presId);
+export async function materializeBundle(
+  presId,
+  { force = false, backendURL = null } = {},
+) {
+  const wire = await getDesignBundle(presId, { backendURL });
   if (!wire || !wire.presFP) {
     throw new Error("design-bundle response is missing presFP");
   }