slidemind 0.2.3 → 0.3.0

package/bin/slidemind.mjs

@@ -29,12 +29,19 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-// The only eager `src/` import: node-builtins only, and the version-floor
-// ladder below is sync, so it cannot be lazily loaded like the rest.
+// The eager `src/` imports. Everything else is lazy-loaded for startup speed;
+// these cannot be. `install-channel` because the version-floor ladder below is
+// sync; `secrets` because it wraps the output streams before the first line can
+// be written — a scrubber installed after the leak is not a scrubber; and the
+// env-label helpers because they are called from string builders all over this
+// file, most of which have no `cfg` handle. All three are node-builtins only
+// (fs / os / path / crypto / child_process), so none of them costs startup.
 import {
   isClaudePluginInstall,
   updateCliInstruction,
 } from "../src/install-channel.mjs";
+import { register as registerSecret, scrub } from "../src/bridge/secrets.mjs";
+import { envPhrase, envTag, isMultiEnv } from "../src/bridge/config.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -63,12 +70,15 @@ function printHelp() {
       `                                                     coding agent found on this machine; none to skip)\n` +
       `                                     --no-install    skip the global npm install (already installed)\n` +
       `                                     --no-ready      skip the closing readiness check\n` +
+      `                                     --no-login      skip the Microsoft 365 browser sign-in offer\n` +
       `                                     --json          machine-readable result\n` +
       `  slidemind ready [deck]           One-command session setup — run this FIRST each session.\n` +
       `                                     Verifies authorization/connection/CLI version, resolves the open\n` +
       `                                     design, materializes its bundle, and (with a deck) binds it.\n` +
       `                                     Exit 0 = ready; non-zero prints one actionable blocker.\n` +
+      `                                     A deck already bound to a design readies with PowerPoint closed.\n` +
       `                                     --to <presId>   bind to a specific open window\n` +
+      `                                     --brand <id>    bind to a design by id (presFP) — no window needed\n` +
       `                                     --force         re-download the bundle even if current\n` +
       `                                     --connect-only  check the connection only (no design/bundle)\n` +
       `                                     --json          machine-readable readiness payload\n` +
@@ -80,7 +90,8 @@ function printHelp() {
       `                                     blocks until the user decides, prints DECISION: approved | comments\n` +
       `                                     --port <n>          bind a fixed port (default: ephemeral)\n` +
       `  slidemind concepts <deck>        After plan sign-off, generate one concept mockup PNG per planned\n` +
-      `                                     slide into <deck>/concepts/concept-slide-NN.png (requires a host).\n` +
+      `                                     slide into <deck>/concepts/concept-slide-NN.png (bound deck,\n` +
+      `                                     pane-free — no PowerPoint window needed).\n` +
       `                                     Read each as a design target, then rebuild it as slide JSX.\n` +
       `                                     Optional aid — skips cleanly (exit 0) if unavailable.\n` +
       `  slidemind build <deck>           Build self-contained HTML\n` +
@@ -88,31 +99,47 @@ function printHelp() {
       `                                     approves or leaves comments (host-free)\n` +
       `                                     --port <n>      bind a fixed port (default: ephemeral)\n` +
       `  slidemind build-pptx <deck>      Export native .pptx — via the add-in for compose decks (host), LOCALLY for template packs (host-free)\n` +
+      `                                     --pack <dir>   explicit template-pack directory (plugin integrations)\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --out <path>    output path (default <deck>/<deck>.pptx)\n` +
+      `                                     --force         discard manual PowerPoint edits instead of reconciling them\n` +
+      `  slidemind inspect-template-deck <deck>  Inspect a template deck as JSON for pack-owned validation\n` +
+      `                                     --pack <dir>   explicit template-pack directory (required)\n` +
+      `                                     --allow-unrendered-freeform  include JSX inserts without .pptx artifacts\n` +
+      `                                     --json          print the normalized deck model\n` +
       `  slidemind view-draft <deck>      Render the deck's slides to per-slide PNGs (no push, no .pptx)\n` +
       `                                     so the agent can look before review; host-free once the\n` +
       `                                     bundle is materialized\n` +
       `                                     --to <presId>   window to fetch the bundle from (only if not cached)\n` +
       `                                     --out <dir>     output dir (default <deck>/.draft-preview/)\n` +
       `                                     --open          open each rendered PNG\n` +
-      `  slidemind search "<query>"       Search an engine or scope for images or slides (requires an open host)\n` +
+      `  slidemind search "<query>"       Search an engine or scope for images or slides (no window needed on\n` +
+      `                                     add-ins that serve the pane-free engine routes; older ones relay\n` +
+      `                                     through an open host)\n` +
       `                                     --engine <id>   engine, or scope:all | scope:sharepoint to search unfiltered\n` +
       `                                                     (default: first image engine; scope:all for slide intents)\n` +
       `                                     --result-type <t>  slide | image — required for a scope:* target\n` +
       `                                     --intent <i>    auto | content | visual (slide engines)\n` +
       `                                     --top <N>       max results\n` +
-      `                                     --to <presId>   target a specific window (required if >1 open)\n` +
-      `                                     --json          print the raw result payload\n` +
-      `  slidemind view-slide [opts]      Fetch a slide search result's preview image to a file (requires a host)\n` +
+      `                                     --deck <deck>   route by this deck's bound design (multi-environment)\n` +
+      `                                     --to <presId>   pin a window on the relayed path (ignored pane-free)\n` +
+      `                                     --json          print the raw result payload (carries the searchId)\n` +
+      `  slidemind view-slide [opts]      Fetch a slide search result's preview image to a file\n` +
       `                                     --search <id>   searchId from 'slidemind search'\n` +
       `                                     --pick <n>      1-based selection number to view\n` +
-      `                                     --to <presId>   the window the search ran on (required if >1 open)\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
       `                                     --out <dir>     output dir (default: a slidemind temp dir)\n` +
-      `  slidemind ls engines             List the live engine catalog + search scopes for an active pane\n` +
+      `  slidemind read-source [opts]     Read the ORIGINAL deck a slide search result came from\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `                                     --pick <n>      1-based selection number\n` +
+      `                                     --from-slide <n>  first slide to read (1-based)\n` +
+      `                                     --to-slide <n>    last slide to read (1-based)\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
+      `                                     --out <file>    write the Markdown to a file instead of stdout\n` +
+      `  slidemind ls engines             List the live engine catalog + search scopes\n` +
       `                                     --type <t>      collection | search | scope\n` +
       `                                     --subtype <s>   image | slide | template | content\n` +
-      `                                     --to <presId>   target a specific window/backend\n` +
+      `                                     --to <presId>   target a specific window/backend (relayed path only)\n` +
       `                                     --all          include every paired backend\n` +
       `                                     --json          print the raw engine list\n` +
       `  slidemind insert-slide [opts]    Insert reused slide search results live into a window (requires a host)\n` +
@@ -121,17 +148,23 @@ function printHelp() {
       `                                     --to <presId>   target window (required if >1 open)\n` +
       `                                     --at <N>        insert after slide N (0-based); default = append\n` +
       `  slidemind add-slide [opts]       Fold reused slide(s) into a deck as native .pptx\n` +
-      `                                     --search <id>   searchId from 'slidemind search' (requires a host)\n` +
+      `                                     --search <id>   searchId from 'slidemind search'\n` +
       `                                     --from <file.pptx>  fold slide(s) from a local .pptx instead (host-free)\n` +
       `                                     --pick <n,..>   1-based selection number(s)\n` +
       `                                     --deck <deck>   deck to add the slides to\n` +
-      `                                     --to <presId>   target the window the search ran on (required if >1 open; ignored with --from)\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only; ignored with --from)\n` +
       `                                     --at <N>        numeric prefix to start at (default: append)\n` +
-      `  slidemind download-result [opts] Download image/icon search result(s) into a deck's assets/ (requires a host)\n` +
+      `                                     --json          machine-readable result (carries the searchId)\n` +
+      `  slidemind adopt <file.pptx>      Rebuild a deck workspace from a file's embedded source; foreign\n` +
+      `                                     slides are converted to editable jsx where the add-in offers it\n` +
+      `                                     --deck <slug>   deck folder to write (default: the file's name)\n` +
+      `                                     --brand <presFP>  design to convert against (when the file names none)\n` +
+      `                                     --no-convert    fold every untagged slide as native .pptx instead\n` +
+      `  slidemind download-result [opts] Download image/icon search result(s) into a deck's assets/\n` +
       `                                     --search <id>   searchId from 'slidemind search'\n` +
       `                                     --pick <n,..>   1-based selection number(s)\n` +
       `                                     --deck <deck>   deck to write the asset(s) into\n` +
-      `                                     --to <presId>   the window the search ran on (required if >1 open)\n` +
+      `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
       `                                     --icon-color <hex[,hex,..]>  bake a colour into SVG result(s) (one for all, or one per --pick)\n` +
       `  slidemind imagen "<prompt>"      Generate ONE image with the add-in's image model into a deck's assets/ (paired backend, pane-free)\n` +
       `                                     --deck <deck>   bound deck to write the image into (required)\n` +
@@ -144,7 +177,9 @@ function printHelp() {
       `                                     --force         re-download even if the cached bundle is current\n` +
       `  slidemind presentations          List active PowerPoint panes registered with the add-in\n` +
       `                                     --all          include retained suspended entries\n` +
-      `  slidemind doctor                 Diagnose CLI/add-in authorization, backend, and pane readiness\n` +
+      `  slidemind doctor                 Diagnose two independent ladders: backend authoring readiness\n` +
+      `                                     (session, backend, CLI version, engine routes) and live\n` +
+      `                                     PowerPoint readiness (windows, pane)\n` +
       `                                     --json          print machine-readable status\n` +
       `  slidemind read [presId|file.pptx]  Pull the content of an open presentation (requires a host),\n` +
       `                                     or of a local .pptx path (read host-free from disk)\n` +
@@ -156,6 +191,11 @@ 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` +
+      `                                     --accept-conversions  replace even when a converted slide is unconfirmed\n` +
+      `                                     --force         discard manual PowerPoint edits instead of reconciling them\n` +
+      `  slidemind login                  Sign in to Microsoft 365 in your browser so SharePoint-backed\n` +
+      `                                     slides and images download without an open PowerPoint window\n` +
+      `                                     --backend <url|env>  environment to sign in for (default: the default one)\n` +
       `  slidemind whoami                 Show every connected environment (* = default)\n` +
       `  slidemind use <url|env>          Set the default environment\n` +
       `  slidemind logout [url|env]       Unpair one environment (--all to unpair every one)\n` +
@@ -429,15 +469,89 @@ async function cmdImagen(rest) {
   );
 }
 
+async function cmdInspectTemplateDeck(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "inspect-template-deck");
+  let packDir = null;
+  let json = false;
+  let allowUnrenderedFreeform = false;
+  for (let i = 0; i < passthrough.length; i++) {
+    const a = passthrough[i];
+    if (a === "--pack") {
+      packDir = passthrough[++i];
+      if (!packDir) fail("--pack expects a directory");
+    } else if (a === "--json") {
+      json = true;
+    } else if (a === "--allow-unrendered-freeform") {
+      allowUnrenderedFreeform = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (!packDir) fail("inspect-template-deck requires --pack <dir>");
+
+  const deckDir = resolveDeckArg(deck);
+  const resolveMod = await import(
+    pathToFileURL(path.join(SRC_DIR, "builders", "resolve-skill.mjs")).href
+  );
+  const skill = resolveMod.resolveSkillForDeck(deckDir, {
+    packDir: path.resolve(packDir),
+  });
+  if (skill.mode !== "fill-template") {
+    fail(`pack ${skill.skillDir} is mode ${skill.mode}, not fill-template`);
+  }
+  const engine = await import(
+    pathToFileURL(path.join(SRC_DIR, "pptx", "fill", "engine.mjs")).href
+  );
+  const result = engine.inspectFillTemplateDeck({
+    deckDir,
+    skill,
+    allowUnrenderedFreeform,
+  });
+  const payload = {
+    version: 1,
+    pack: {
+      name: skill.skillName,
+      mode: skill.mode,
+      directory: skill.skillDir,
+      template: result.templateKey,
+      locale: result.locale,
+    },
+    slides: result.sequence,
+    warnings: result.warnings,
+    problems: result.problems,
+  };
+  if (json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else {
+    for (const item of result.sequence) {
+      const suffix = item.kind === "master" ? ` → template ${item.no}` : "";
+      process.stdout.write(`${item.file}: ${item.kind}${suffix}\n`);
+    }
+    for (const warning of result.warnings) process.stderr.write(`  warning: ${warning}\n`);
+  }
+  if (result.problems.length) {
+    fail(`inspection failed:\n  - ${result.problems.join("\n  - ")}`);
+  }
+}
+
 async function cmdBuildPptx(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "build-pptx");
   let to = null;
   let outPath = null;
+  let packDir = null;
+  let force = false;
   for (let i = 0; i < passthrough.length; i++) {
     const a = passthrough[i];
-    if (a === "--to") {
+    if (a === "--force") {
+      force = true;
+    } else if (a === "--to") {
       to = passthrough[++i];
       if (!to) fail("--to expects a presId");
+    } else if (a === "--pack") {
+      packDir = passthrough[++i];
+      if (!packDir) fail("--pack expects a directory");
     } else if (a === "--out" || a === "-o") {
       outPath = passthrough[++i];
       if (!outPath) fail("--out expects a path");
@@ -460,8 +574,13 @@ async function cmdBuildPptx(rest) {
   const resolveMod = await import(
     pathToFileURL(path.join(SRC_DIR, "builders", "resolve-skill.mjs")).href
   );
-  if (resolveMod.resolveDeckMode(deckDir).mode === "fill-template") {
-    const skill = resolveMod.resolveSkillForDeck(deckDir);
+  const resolveOpts = packDir ? { packDir: path.resolve(packDir) } : {};
+  const deckMode = resolveMod.resolveDeckMode(deckDir, resolveOpts);
+  if (packDir && deckMode.mode !== "fill-template") {
+    fail(`explicit --pack ${path.resolve(packDir)} is mode ${deckMode.mode}, not fill-template`);
+  }
+  if (deckMode.mode === "fill-template") {
+    const skill = resolveMod.resolveSkillForDeck(deckDir, resolveOpts);
     if (to) {
       fail(
         "--to targets a PowerPoint window, but fill-template decks build " +
@@ -519,6 +638,7 @@ async function cmdBuildPptx(rest) {
     deckDir,
     presentationId: to,
     outPath,
+    force,
     onProgress: renderProgressPrinter(),
   });
   process.stdout.write(
@@ -699,9 +819,211 @@ function writeSearchGrid(gridDataUri, searchId, resolveExt) {
   }
 }
 
+// Where an engine op runs. Newer add-ins serve the engine surface off the CLI
+// session itself (`/api/cli/engines`, `/api/cli/searches/*`), so discovery,
+// search, download and extraction need no PowerPoint window at all; older ones
+// relay every one of them through a task-pane webview, which is what
+// requirePaneHost gates. The DIRECT path is preferred whenever it exists and the
+// pane path stays as the compat fallback, so both add-in generations work.
+//
+// `--to <presId>` stops being a REQUIREMENT — the searchId is server-owned
+// rather than bound to a window, so nothing has to be targeted — but it is still
+// honoured, and naming a window means "relay through THAT pane". That is the
+// escape hatch for the two things the pane-free routes refuse (`asset_needs_host`
+// for SharePoint-hosted bytes, `recolor_needs_host` for an icon tint), both of
+// which the pane can do; ignoring --to made their own remediation unreachable.
+// `brandId` is the deck's bound design — the only thing that routes an engine op
+// in a multi-environment session when no window is involved.
+// No connected environment holds a server-owned search record. Authored once
+// because every consumer of an opaque searchId reaches the same dead end and
+// the same way out — the record's own environment is the only thing that can
+// serve it, so a re-search is the fix regardless of who asked.
+function expiredSearchMessage(searchId) {
+  return (
+    `search ${searchId} was not found on any connected environment — server-side ` +
+    "search records expire after ~2 hours. Re-run 'slidemind search' and pick again."
+  );
+}
+
+async function resolveEngineRouting(client, { to = null, brandId = null, pick = "one", searchId = null } = {}) {
+  // An opaque (server-minted) searchId pins the route by itself: the record
+  // lives on the environment that minted it, and the pane relay can never
+  // serve it — its handler only knows its own per-window numeric ids. So the
+  // record's origin outranks the deck's design AND --to, and when no connected
+  // environment holds the record the only honest answer is "search again",
+  // not a pane fallback that is guaranteed to 4xx.
+  if (client.isOpaqueSearchId?.(searchId)) {
+    if (to) {
+      fail(
+        `searchId ${searchId} is a pane-free search — it cannot be relayed through a window. ` +
+          `To go through the pane, re-run 'slidemind search "<query>" --to ${to}' and use ITS searchId.`,
+      );
+    }
+    let origin = null;
+    try {
+      origin = await client.resolveSearchBackend(searchId);
+    } catch (err) {
+      // The probe distinguishes "no environment holds this record" from the
+      // failures that only LOOK like it — a dead session, a missing sign-in —
+      // and hands the latter back for their own remediation.
+      await failOnEngineBlocker(client, err, { to });
+    }
+    if (origin) {
+      return { direct: true, backendURL: origin, presId: null, registry: null, entry: null };
+    }
+    fail(expiredSearchMessage(searchId));
+  }
+  let backendURL = null;
+  if (!to) {
+    backendURL = await client.resolveEngineBackend({ brandId });
+  }
+  if (backendURL) {
+    return { direct: true, backendURL, presId: null, registry: null, entry: null };
+  }
+  const registry = await client.requirePaneHost();
+  const entry =
+    pick === "any"
+      ? client.pickAnyPresentationEntry(registry, to)
+      : client.pickPresentationEntry(registry, to);
+  return {
+    direct: false,
+    backendURL: entry.backendURL ?? null,
+    presId: entry.presId,
+    registry,
+    entry,
+  };
+}
+
+// The design a deck is bound to (presFP == brandId), or null when it isn't bound
+// / isn't a deck. Routing state only — never printed.
+async function deckBrandId(deckDir) {
+  if (!deckDir) return null;
+  const bundleMod = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  return bundleMod.readDeckBundleRef(deckDir)?.presFP ?? null;
+}
+
+// A pane-ready window, or null — never a throw, and never a wait. Used by the
+// login_required paths below, where an open pane is an OPTION rather than a
+// precondition. `to` is honoured only when it names a window that is actually
+// registered; a stale --to must not cost the caller its fallback.
+async function openPaneEntry(client, to = null) {
+  const registry = (await client.paneReadyPresentations?.()) ?? [];
+  if (registry.length === 0) return null;
+  const explicit = registry.some((p) => p.presId === to) ? to : null;
+  try {
+    return { registry, entry: client.pickAnyPresentationEntry(registry, explicit) };
+  } catch {
+    // Several windows and no way to choose — no automatic fallback from here.
+    return null;
+  }
+}
+
+// The ONE rendering of a corpus-identity refusal: the pane-free routes run as
+// the USER and answer `login_required` without the delegated tokens `slidemind
+// login` mints (the CLI attempts that sign-in itself before ever sending a
+// token-less request, so reaching this means the browser step was refused or
+// abandoned). The refusal backs the PANE-FREE path only: an open task pane
+// signs every request with a live browser token, so when a pane-ready window
+// is already open, that window can serve a fresh search right now — say so.
+// Returns the message, or null for any other failure.
+async function loginRequiredMessage(client, err, { to = null } = {}) {
+  const blocker = client.loginRequiredBlocker?.(err);
+  if (!blocker) return null;
+  const pane = await openPaneEntry(client, to);
+  if (!pane) return blocker.message;
+  const env = envTag(pane.entry.env);
+  return (
+    `${blocker.message} A slidemind pane is already open${env} and signs each request live, so a fresh ` +
+    `search through that window works now: slidemind search "<query>" --to ${pane.entry.presId}.`
+  );
+}
+
+// Engine-route failures the USER has to clear get one actionable line instead of
+// a relay error. `login_required` means the corpus routes want the user's own
+// Microsoft 365 sign-in. Only corpus search stops; render and bundle don't.
+// Anything else is re-thrown for the top-level handler.
+async function failOnEngineBlocker(client, err, { to = null } = {}) {
+  const message = await loginRequiredMessage(client, err, { to });
+  if (message) fail(message);
+  throw err;
+}
+
+// A login_required refusal that an OPEN PANE can simply route around. Only an
+// operation that can be replayed pane-side qualifies — creating a NEW search,
+// whose id the pane mints itself. A record-bound op on an opaque searchId
+// cannot: the pane's handler only understands its own per-window numeric ids,
+// so those get loginRequiredMessage's extended blocker instead. Returns
+// { registry, entry } or null.
+async function paneRelayForLoginRequired(client, err, { to = null } = {}) {
+  if (!client.loginRequiredBlocker?.(err)) return null;
+  return openPaneEntry(client, to);
+}
+
+// The pane-free routes refuse exactly two things outright: bytes that live in
+// SharePoint (`asset_needs_host`, which needs a delegated token only a browser
+// can mint) and an icon tint (`recolor_needs_host`, whose classifier is
+// DOM-based). An open pane does both, so the remediation is the RELAY — name it,
+// rather than echoing a 409 whose "retry" would take the identical route.
+// Returns null for anything else.
+function describeHostOnlyEngineFailure(err) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  if (code !== "asset_needs_host" && code !== "recolor_needs_host") return null;
+  const detail =
+    typeof err?.body?.error === "string" ? err.body.error : (err?.message ?? "");
+  return (
+    `${detail} Run 'slidemind search "<query>" --to <presId>' against an open window and ` +
+    "re-pick, then repeat this download with the same --to — that relays it through the pane."
+  );
+}
+
+// The other half of the same boundary: a SharePoint-backed SLIDE. The extract
+// route fetches it with the caller's identity, so without a delegated token the
+// add-in falls back to a managed identity that is not configured for the corpus
+// site and the fetch dies inside the provider. That route answers a plain 400
+// with no discrete code, so the provider text is the only signal there is.
+function isSharePointProviderFailure(err) {
+  const text = `${err?.body?.error ?? ""} ${err?.message ?? ""}`;
+  return /sharepoint provider/i.test(text);
+}
+
+// `slidemind login` as the WINDOW-FREE way past both — named only on a backend
+// that honours the delegated token and only while no sign-in is stored, so the
+// sentence never appears where following it would change nothing. Null
+// otherwise, which keeps every pre-existing message byte-identical.
+async function graphLoginRemediation(client, backendURL) {
+  if (!backendURL) return null;
+  try {
+    if (!(await client.backendSupportsGraphDelegated?.(backendURL))) return null;
+    const graph = await loadBridgeModule("graph-auth");
+    if (graph.hasGraphSession(backendURL)) return null;
+  } catch {
+    // A capability probe that fails is not a reason to withhold the download's
+    // real error — just say nothing extra.
+    return null;
+  }
+  return (
+    "Or run 'slidemind login' once: it signs this CLI in to Microsoft 365 with your own " +
+    "identity, and SharePoint-backed content then downloads with no window at all."
+  );
+}
+
+// The user-facing text for an engine byte fetch that failed for want of an
+// identity — either refusal shape. Returns null when the failure is something
+// else entirely (the caller keeps its own message).
+async function describeEngineByteFailure(client, err, { backendURL = null } = {}) {
+  const paneAdvice = describeHostOnlyEngineFailure(err);
+  if (!paneAdvice && !isSharePointProviderFailure(err)) return null;
+  const login = await graphLoginRemediation(client, backendURL);
+  if (!login) return paneAdvice;
+  return paneAdvice ? `${paneAdvice} ${login}` : `${err.message} ${login}`;
+}
+
 async function cmdSearch(rest) {
   let asJson = false;
   let to = null;
+  let deck = null;
   let engineId = null;
   let resultType = null;
   let intent = null;
@@ -714,6 +1036,9 @@ async function cmdSearch(rest) {
     } else if (a === "--to") {
       to = rest[++i];
       if (!to) fail("--to expects a presId");
+    } else if (a === "--deck") {
+      deck = rest[++i];
+      if (!deck) fail("--deck expects a deck name or path");
     } else if (a === "--engine" || a === "-e" || a === "--engineId") {
       engineId = rest[++i];
       if (!engineId) fail("--engine expects an engineId");
@@ -745,12 +1070,13 @@ async function cmdSearch(rest) {
   const query = queryParts.join(" ").trim();
   if (!query) {
     fail(
-      `usage: slidemind search "<query>" [--engine <id|scope:all|scope:sharepoint>] [--result-type slide|image] [--intent auto|content|visual] [--top <N>] [--to <presId>] [--json]`,
+      `usage: slidemind search "<query>" [--engine <id|scope:all|scope:sharepoint>] [--result-type slide|image] [--intent auto|content|visual] [--top <N>] [--deck <deck>] [--to <presId>] [--json]`,
     );
   }
 
-  // Engine search runs against the add-in's live engine over the bridge — an
-  // open host is required.
+  // Engine search runs against the add-in's live engine over the bridge —
+  // pane-free where the add-in serves the direct routes, relayed through an open
+  // window (host required) where it doesn't.
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
@@ -760,14 +1086,23 @@ async function cmdSearch(rest) {
   const { resolveAssetExt } = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
   );
-  const registry = await client.requirePaneHost();
-  // The engine is per-user, not window-bound — so search just attaches to any
-  // connected window (preferring a live one). No "which window?" prompt; pass
-  // --to only to pin a specific one. The chosen window is printed below so
-  // follow-up insert/add-slide can target the same pane the searchId lives on.
-  const entry = client.pickAnyPresentationEntry(registry, to);
-  const presId = entry.presId;
-  const backendURL = entry.backendURL ?? null;
+  // The engine catalog is per-user, not window-bound. On the pane path search
+  // attaches to any connected window (preferring a live one) and the chosen
+  // window is printed below, because the searchId lives on that pane; on the
+  // direct path the searchId is the backend's and no window is involved.
+  const routing = await resolveEngineRouting(client, {
+    to,
+    brandId: await deckBrandId(deck ? resolveDeckArg(deck) : null),
+    pick: "any",
+  });
+  const presId = routing.presId;
+  const backendURL = routing.backendURL;
+  // Mutable, because a login_required refusal can push a direct search onto
+  // the pane relay below — and once it does, the searchId belongs to a WINDOW
+  // and every next-step hint has to name it.
+  let direct = routing.direct;
+  let registry = routing.registry;
+  let entry = routing.entry;
 
   // An explicit content/visual intent means "search slides", not imagery.
   const slideIntent = intent === "content" || intent === "visual";
@@ -776,7 +1111,7 @@ async function cmdSearch(rest) {
   //   - an explicit slide intent (--intent content|visual) targets slides.
   // This is belt-and-suspenders for an add-in regression where a missing
   // subtype no longer defaulted to "image"; when the subtype is unknown we omit
-  // it and let the add-in resolve it from the snapshot.
+  // it and let the add-in resolve the caller's groups itself.
   let subtype = slideIntent ? "slide" : null;
   if (!engineId) {
     if (slideIntent) {
@@ -800,9 +1135,18 @@ async function cmdSearch(rest) {
         // Best-effort: a bundle that can't be materialized (e.g. an incomplete
         // one) must not replace the actionable "wire an image engine" message
         // below with a bundle error — the live catalog is the real answer here.
-        const mat = await bundle
-          .materializeBundle(presId, { backendURL })
-          .catch(() => null);
+        // Pane path: fetch by the window's presId. Direct path: there is no
+        // window, so only a bound deck (--deck) can name the design; without one
+        // there is nothing to fall back to and the live catalog's answer stands.
+        const brandId = presId
+          ? null
+          : await deckBrandId(deck ? resolveDeckArg(deck) : null);
+        const mat =
+          presId || brandId
+            ? await bundle
+                .materializeBundle(presId, { backendURL, brandId })
+                .catch(() => null)
+            : null;
         if (mat) pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
       }
       if (!pick) {
@@ -829,23 +1173,64 @@ async function cmdSearch(rest) {
     resultType = null;
   }
 
-  // Window-agnostic: tries the picked pane, then fails over to any other live
-  // window on the same backend if it's suspended/frozen. The answering window
-  // (res.presId) is what reuse must target — the searchId is bound to it.
-  const res = await client.engineSearchAnyPane({
-    registry,
-    explicitPresId: to,
-    engineId,
-    query,
-    subtype,
-    resultType,
-    intent: intent ?? null,
-    top: top ?? null,
-  });
-  const ranPresId = res?.presId ?? presId;
-  const ranEntry = registry.find((p) => p.presId === ranPresId) ?? entry;
+  // Direct: one pane-free call against the backend that owns the searchId.
+  // Pane: window-agnostic — tries the picked pane, then fails over to any other
+  // live window on the same backend if it's suspended/frozen. The answering
+  // window (res.presId) is what reuse must target there, since the searchId is
+  // bound to it.
+  const relaySearch = (reg) =>
+    client.engineSearchAnyPane({
+      registry: reg,
+      explicitPresId: to,
+      engineId,
+      query,
+      subtype,
+      resultType,
+      intent: intent ?? null,
+      top: top ?? null,
+    });
+  let res;
+  try {
+    res = direct
+      ? await client.engineSearch({
+          engineId,
+          query,
+          subtype,
+          resultType,
+          intent: intent ?? null,
+          top: top ?? null,
+          backendURL,
+        })
+      : await relaySearch(routing.registry);
+  } catch (err) {
+    // login_required stops the PANE-FREE path only — an open pane signs each
+    // request with the browser's live token. Creating a new search is exactly
+    // the operation the pane can replay (it mints its own searchId), so relay
+    // it rather than parking the search on a sign-in the user hasn't finished.
+    const relay = direct ? await paneRelayForLoginRequired(client, err, { to }) : null;
+    if (!relay) await failOnEngineBlocker(client, err, { to });
+    process.stderr.write(
+      `note: this CLI is not signed in to Microsoft 365, so the search ran through the open ` +
+        `slidemind pane${envTag(relay.entry.env)} instead (it signs each request live).\n`,
+    );
+    direct = false;
+    registry = relay.registry;
+    entry = relay.entry;
+    try {
+      res = await relaySearch(registry);
+    } catch (relayErr) {
+      await failOnEngineBlocker(client, relayErr, { to });
+    }
+  }
+  const ranPresId = res?.presId ?? entry?.presId ?? presId;
+  const ranEntry = direct
+    ? { env: res?.env ?? null }
+    : (registry.find((p) => p.presId === ranPresId) ?? entry);
   if (asJson) {
-    process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+    // The searchId rides the JSON so an interrupted agent can resume its picks
+    // without re-searching. The backendURL never does — env label only.
+    const { backendURL: _routingOnly, ...pub } = res ?? {};
+    process.stdout.write(`${JSON.stringify(pub, null, 2)}\n`);
     return;
   }
   if (!res?.ok) {
@@ -902,6 +1287,16 @@ async function cmdSearch(rest) {
         `Contact sheet of all ${count} result(s) — LOOK AT THIS FILE to choose, ` +
           `don't fetch previews one by one: ${gridPath}\n`,
       );
+    } else if (direct) {
+      // The pane composes the collage in a DOM; the pane-free route may not
+      // have one to hand back (`gridUnavailable`, or simply no grid field on an
+      // add-in that hasn't grown it yet). Say where previews come from instead
+      // — otherwise an agent that has learned to expect a contact sheet quietly
+      // issues N thumbnail fetches to rebuild it.
+      process.stdout.write(
+        `No contact sheet on this path — preview candidates one at a time instead: ` +
+          `slidemind view-slide --search ${res.searchId} --pick <n>\n`,
+      );
     }
   }
   // Tailor the next-step hint to the result kind: slide verbs (insert-slide /
@@ -910,12 +1305,28 @@ async function cmdSearch(rest) {
   // add-ins that don't echo a top-level subtype.
   const isSlideResults =
     res.subtype === "slide" || results.some((r) => r.kind === "slide");
-  const envTag = ranEntry.env ? ` [${ranEntry.env}]` : "";
-  if (isSlideResults) {
+  const envLabel = envTag(ranEntry?.env);
+  if (direct) {
+    // The searchId belongs to the BACKEND here, not to a window: picks work with
+    // PowerPoint closed, so the follow-up commands carry no --to. Live insert is
+    // the one step that still names a window (it types into an open deck).
+    if (isSlideResults) {
+      process.stdout.write(
+        `searchId ${res.searchId}${envLabel} is held by the add-in — reuse it with no PowerPoint window:\n` +
+          `  slidemind add-slide --search ${res.searchId} --pick <n> --deck <deck>\n` +
+          `  slidemind insert-slide --search ${res.searchId} --pick <n> --to <presId>   (live insert needs an open window)\n`,
+      );
+    } else {
+      process.stdout.write(
+        `searchId ${res.searchId}${envLabel} is held by the add-in — download image result(s) into a deck (no window needed):\n` +
+          `  slidemind download-result --search ${res.searchId} --pick <n[,n,...]> --deck <deck> [--icon-color <hex>]\n`,
+      );
+    }
+  } else if (isSlideResults) {
     // The searchId is bound to the window the search ran on — reuse must target
     // that same window, so spell out its presId in the next-step commands.
     process.stdout.write(
-      `searchId ${res.searchId} ran on window ${ranPresId}${envTag} — reuse from THIS window:\n` +
+      `searchId ${res.searchId} ran on window ${ranPresId}${envLabel} — reuse from THIS window:\n` +
         `  slidemind insert-slide --search ${res.searchId} --pick <n> --to ${ranPresId}\n` +
         `  slidemind add-slide --search ${res.searchId} --pick <n> --deck <deck> --to ${ranPresId}\n`,
     );
@@ -923,7 +1334,7 @@ async function cmdSearch(rest) {
     // The searchId is bound to the window the search ran on — download must
     // target that same window, so spell out its presId in the next-step command.
     process.stdout.write(
-      `searchId ${res.searchId} ran on window ${ranPresId}${envTag} — download image result(s) into a deck:\n` +
+      `searchId ${res.searchId} ran on window ${ranPresId}${envLabel} — download image result(s) into a deck:\n` +
         `  slidemind download-result --search ${res.searchId} --pick <n[,n,...]> --deck <deck> --to ${ranPresId} [--icon-color <hex>]\n`,
     );
   }
@@ -973,16 +1384,58 @@ async function cmdLs(rest) {
   if (all && to) fail("--all cannot be combined with --to");
   let backendURL = null;
   if (!all) {
-    const registry = await client.requirePaneHost();
-    const entry = client.pickAnyPresentationEntry(registry, to);
-    backendURL = entry.backendURL ?? null;
+    // Pane-free where the add-in serves the direct routes; otherwise the catalog
+    // is relayed through a window, so a live pane is still the precondition.
+    try {
+      backendURL = (await resolveEngineRouting(client, { to, pick: "any" }))
+        .backendURL;
+    } catch (err) {
+      // Listing is the one engine op that can simply show EVERY environment
+      // (each engine is tagged with its env), so an ambiguous multi-environment
+      // session fans out here rather than demanding --backend.
+      if (err?.code !== "engine_backend_ambiguous") throw err;
+      backendURL = null;
+    }
+  }
+  let engines;
+  // The pane-free route's summary of the catalog BEFORE the type/subtype
+  // filter; null on older add-ins and on the pane-relay path.
+  let catalog = null;
+  // Which environments answered. The catalog is POOLED, and pooling dedupes the
+  // scopes every environment repeats — so a second environment can contribute
+  // no row of its own, and the surviving rows can no longer be counted to learn
+  // whether more than one answered.
+  let envs = [];
+  try {
+    ({ engines, catalog, envs = [] } = await client.listEngines({
+      type,
+      subtype,
+      backendURL,
+    }));
+  } catch (err) {
+    // No pane fallback here: `GET /api/cli/engines` is the catalog route on both
+    // add-in generations (newer ones answer it directly, older ones relay it
+    // themselves), so there is no second route to retry on. The message does
+    // name the open pane, because searching THROUGH it still works.
+    await failOnEngineBlocker(client, err, { to });
   }
-  const { engines } = await client.listEngines({ type, subtype, backendURL });
   if (asJson) {
-    process.stdout.write(`${JSON.stringify(engines, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({ engines, catalog, envs }, null, 2)}\n`);
     return;
   }
   if (engines.length === 0) {
+    // A filter that matched nothing is NOT an empty deployment — the summary is
+    // the only thing that tells the two apart, so say which one this is and the
+    // next move follows (drop the filter vs. search the corpus unfiltered).
+    const unfiltered = catalog ? catalog.totalEngines + catalog.totalScopes : 0;
+    if (catalog?.filtered && unfiltered > 0) {
+      process.stderr.write(
+        `No engine or scope matched this filter, but ${catalog.totalEngines} engine(s) ` +
+          `and ${catalog.totalScopes} scope(s) exist. Re-run 'slidemind ls engines' ` +
+          "without --type/--subtype to see them.\n",
+      );
+      return;
+    }
     // Deliberately not "nothing to search": an engine is a saved folder filter
     // over the add-in's shared corpus, so an empty catalog says only that nobody
     // saved a filter. An older add-in that predates scopes lands here too.
@@ -997,8 +1450,12 @@ async function cmdLs(rest) {
     );
     return;
   }
-  // Show the env tag only when more than one environment contributed engines.
-  const multiEnv = new Set(engines.map((e) => e.env)).size > 1;
+  // Show the env tag only when more than one environment contributed. Two
+  // environments can carry identically-named engines, and without the tag the
+  // pooled list gives no way to tell them apart. Deduped scope rows carry no env
+  // of their own (they exist on every environment), so they stay untagged.
+  const multiEnv =
+    isMultiEnv() || envs.length > 1 || new Set(engines.map((e) => e.env)).size > 1;
   for (const e of engines) {
     const kind = [e.type, e.subtype].filter(Boolean).join("/");
     const env = multiEnv && e.env ? `[${e.env}] ` : "";
@@ -1009,12 +1466,28 @@ async function cmdLs(rest) {
       e.type === "scope"
         ? ` (needs --result-type ${(e.capabilities?.resultTypes ?? ["slide", "image"]).join("|")})`
         : "";
+    // An engine that exists but has nothing indexed yet returns zero hits for
+    // every query; say so here so an empty search isn't read as a bad engine id.
+    const state =
+      e.content?.state === "empty"
+        ? " (nothing indexed yet)"
+        : e.content?.state === "indexing"
+          ? " (indexing)"
+          : "";
     process.stdout.write(
-      `${env}${e.id} · ${e.label ?? e.id} · ${kind}${hint}${desc}\n`,
+      `${env}${e.id} · ${e.label ?? e.id} · ${kind}${hint}${state}${desc}\n`,
     );
   }
 }
 
+// A searchId is a number when the pane minted it (the relay path) and an opaque
+// server-minted id on the pane-free engine routes, where the search record lives
+// on the backend. Accept both so a pick round-trips whichever search produced it.
+function parseSearchIdArg(raw, flag = "--search") {
+  if (!raw || raw.startsWith("-")) fail(`${flag} expects a searchId, got '${raw}'`);
+  return /^\d+$/.test(raw) ? parseInt(raw, 10) : raw;
+}
+
 function parsePicks(raw, flag = "--pick") {
   if (!raw) fail(`${flag} expects a comma-separated list of selection numbers`);
   // Tolerate a trailing/empty segment ("1," or "1,,2") by dropping blank parts
@@ -1034,6 +1507,45 @@ function parsePicks(raw, flag = "--pick") {
   return picks;
 }
 
+/**
+ * Turn a live-insert failure into the action that actually fixes it. The client
+ * has already re-listed the registry and retried ONCE against the live window
+ * (a pane reconnect churns the presId), so a pane error that reaches here is one
+ * only the user can clear — and the way around it is the window-free fold.
+ *
+ * A login_required refusal is NOT among them: it is authored once, in
+ * loginRequiredMessage, which the caller consults first.
+ */
+function describeInsertSlideFailure(err, searchId) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  if (code === "unknown_search") {
+    return `searchId ${searchId} is no longer available. Run 'slidemind search' again, then re-pick.`;
+  }
+  if (code === "searchId_required") {
+    // The pane was handed an id it cannot resolve — its search context is
+    // per-window and numeric, and a server-minted id was never in it.
+    return (
+      `searchId ${searchId} belongs to the add-in, not to that PowerPoint window. ` +
+      `Re-run 'slidemind search' (the CLI picks the reuse route from where the search ran), then re-pick.`
+    );
+  }
+  const paneAsleep =
+    code === "pane_suspended" ||
+    code === "pane_timeout" ||
+    // A relay 404 about the presId itself carries prose and no machine code,
+    // and bridgeFetch falls `code` back to that prose — so read the PARSED one.
+    (err?.status === 404 &&
+      (!err?.body?.code || err.body.code === "unknown_presentation"));
+  if (paneAsleep) {
+    return (
+      "the slidemind task pane in that PowerPoint window is not responding (already retried once). " +
+      "Foreground PowerPoint and click the slidemind pane to wake it, then re-run — or reuse the same " +
+      `result with no window at all: slidemind add-slide --search ${searchId} --pick <n> --deck <deck>.`
+    );
+  }
+  return `insert-slide failed: ${err?.message ?? "unknown error"}`;
+}
+
 async function cmdInsertSlide(rest) {
   let searchId = null;
   let picks = null;
@@ -1042,10 +1554,7 @@ async function cmdInsertSlide(rest) {
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--search") {
-      const next = rest[++i];
-      const n = parseInt(next, 10);
-      if (!Number.isFinite(n)) fail(`--search expects a searchId, got '${next}'`);
-      searchId = n;
+      searchId = parseSearchIdArg(rest[++i]);
     } else if (a === "--pick") {
       picks = parsePicks(rest[++i]);
     } else if (a === "--to") {
@@ -1070,20 +1579,97 @@ async function cmdInsertSlide(rest) {
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
+  // Live insert types into an OPEN presentation, so it stays window- and
+  // pane-bound even where the rest of the engine surface has moved off the pane.
   const registry = await client.requirePaneHost();
   const entry = client.pickPresentationEntry(registry, to);
-  const res = await client.insertSlideLive({
-    presId: entry.presId,
-    searchId,
-    selections: picks,
-    at,
-    backendURL: entry.backendURL ?? null,
-  });
+  // Window identity for the client's single retry: a pane reconnect mints a NEW
+  // presId for the same window, and the design fingerprint re-matches it — but
+  // only against windows we did NOT already see next to the target, or a second
+  // deck on the same corporate design would take the insert.
+  const identity = {
+    fileName: entry.fileName ?? entry.title ?? null,
+    brandId: entry.brandId ?? null,
+    otherPresIds: registry
+      .map((p) => p.presId)
+      .filter((id) => id && id !== entry.presId),
+  };
+  // WHERE the searchId lives decides how the reuse runs. A number came from
+  // that window's own pane search and the pane resolves it; an opaque id is the
+  // backend's (the pane-free search) and the pane has never seen it — so those
+  // picks are extracted pane-free and inserted as bytes instead.
+  //
+  // Which backend extracts them is the RECORD's, not the window's. Those are
+  // different environments as soon as two are connected, and spending a
+  // server-owned id against the window's origin 404s as `unknown_search` — read
+  // as "the search expired", which sends the agent round a re-search loop that
+  // can never resolve. The window stays the INSERT target either way.
+  let engineBackendURL = null;
+  if (client.isOpaqueSearchId?.(searchId)) {
+    try {
+      engineBackendURL = await client.resolveSearchBackend(searchId);
+    } catch (err) {
+      await failOnEngineBlocker(client, err, { to: entry.presId });
+    }
+    if (!engineBackendURL) fail(expiredSearchMessage(searchId));
+  }
+  let res;
+  try {
+    res = engineBackendURL
+      ? await client.insertSlidesFromSearch({
+          presId: entry.presId,
+          searchId,
+          selections: picks,
+          at,
+          backendURL: entry.backendURL ?? null,
+          engineBackendURL,
+          ...identity,
+        })
+      : await client.insertSlideLive({
+          presId: entry.presId,
+          searchId,
+          selections: picks,
+          at,
+          backendURL: entry.backendURL ?? null,
+          ...identity,
+        });
+  } catch (err) {
+    fail(
+      (await loginRequiredMessage(client, err, { to: entry.presId })) ??
+        describeInsertSlideFailure(err, searchId),
+    );
+  }
   if (!res?.ok) {
     fail(`insert-slide failed: ${res?.error ?? "unknown error"}`);
   }
   process.stdout.write(
-    `Inserted ${res.insertedCount ?? picks.length} slide(s) into presentation ${entry.presId}\n`,
+    `Inserted ${res.insertedCount ?? picks.length} slide(s) into presentation ${res.presId ?? entry.presId}\n`,
+  );
+}
+
+// One line per written slide, plus the machine-readable twin. The searchId is
+// echoed on purpose: an agent interrupted between picks can resume from the JSON
+// without re-running the search (the record lives on the backend now).
+function writeAddSlideResult({ asJson, searchId, deckDir, deck, written, slides }) {
+  if (asJson) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          searchId,
+          deck: path.relative(process.cwd(), deckDir),
+          slides,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+  process.stdout.write(
+    `Added ${written.length} reused slide(s) to ${path.relative(process.cwd(), deckDir)}:\n` +
+      written.map((w) => `  ${w}`).join("\n") +
+      `\nThey are native .pptx in slides/ — re-run 'slidemind build-pptx ${deck}' or 'slidemind push ${deck}' to render the deck with them spliced in.\n`,
   );
 }
 
@@ -1094,13 +1680,13 @@ async function cmdAddSlide(rest) {
   let at = null;
   let to = null;
   let from = null;
+  let asJson = false;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
-    if (a === "--search") {
-      const next = rest[++i];
-      const n = parseInt(next, 10);
-      if (!Number.isFinite(n)) fail(`--search expects a searchId, got '${next}'`);
-      searchId = n;
+    if (a === "--json") {
+      asJson = true;
+    } else if (a === "--search") {
+      searchId = parseSearchIdArg(rest[++i]);
     } else if (a === "--from") {
       from = rest[++i];
       if (!from) fail("--from expects a path to a .pptx file");
@@ -1173,21 +1759,30 @@ async function cmdAddSlide(rest) {
       .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"));
     const targets = reused.reusedSlideTargets(existing, results, at);
     const written = [];
+    const slides = [];
     results.forEach((r, i) => {
       const target = path.join(slidesDir, targets[i].filename);
       fs.writeFileSync(target, Buffer.from(r.bytes));
       written.push(path.relative(process.cwd(), target));
+      slides.push({
+        selection: picks[i] ?? null,
+        slideId: r.slideId ?? null,
+        file: path.relative(process.cwd(), target),
+      });
+    });
+    writeAddSlideResult({
+      asJson,
+      searchId: null,
+      deckDir,
+      deck,
+      written,
+      slides,
     });
-    process.stdout.write(
-      `Added ${written.length} reused slide(s) to ${path.relative(process.cwd(), deckDir)}:\n` +
-        written.map((w) => `  ${w}`).join("\n") +
-        `\nThey are native .pptx in slides/ — re-run 'slidemind build-pptx ${deck}' or 'slidemind push ${deck}' to render the deck with them spliced in.\n`,
-    );
     return;
   }
 
   if (searchId === null || !picks || !deck) {
-    fail("usage: slidemind add-slide (--search <id> | --from <file.pptx>) --pick <n[,n,...]> --deck <deck> [--to <presId>] [--at <N>]");
+    fail("usage: slidemind add-slide (--search <id> | --from <file.pptx>) --pick <n[,n,...]> --deck <deck> [--to <presId>] [--at <N>] [--json]");
   }
   const deckDir = resolveDeckArg(deck);
   const slidesDir = path.join(deckDir, "slides");
@@ -1196,12 +1791,17 @@ async function cmdAddSlide(rest) {
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
-  const registry = await client.requirePaneHost();
-  // The searchId is presentation-scoped, so --to targets the window the search
-  // ran on. Without it, a registry with >1 open window is a dead-end.
-  const entry = client.pickPresentationEntry(registry, to);
-  const presId = entry.presId;
-  const backendURL = entry.backendURL ?? null;
+  // Direct path: an opaque searchId routes to the environment that minted the
+  // record; the deck's bound design only decides when the id can't. Pane path:
+  // the searchId is presentation-scoped, so --to targets the window the search
+  // ran on (without it, a registry with >1 open window is a dead-end).
+  const routing = await resolveEngineRouting(client, {
+    to,
+    brandId: await deckBrandId(deckDir),
+    searchId,
+  });
+  const presId = routing.presId;
+  const backendURL = routing.backendURL;
 
   // Extract each picked slide's bytes over the bridge, then let the shared
   // helper compute the play-order filenames (NN-reused-<shortid>.pptx). The
@@ -1222,9 +1822,12 @@ async function cmdAddSlide(rest) {
       if (s.tempPath) fs.rmSync(s.tempPath, { force: true });
     }
   };
+  // A searchId can be an opaque server id on the direct path — keep it usable as
+  // a file name component.
+  const searchKey = String(searchId).replace(/[^A-Za-z0-9._-]/g, "_");
   try {
     for (const pick of picks) {
-      const tempPath = path.join(slidesDir, `.reused-${searchId}-${pick}.part`);
+      const tempPath = path.join(slidesDir, `.reused-${searchKey}-${pick}.part`);
       if (typeof client.extractSlideToFile === "function") {
         try {
           const res = await client.extractSlideToFile({
@@ -1240,13 +1843,22 @@ async function cmdAddSlide(rest) {
           continue;
         } catch (err) {
           fs.rmSync(tempPath, { force: true });
+          const stale = await loginRequiredMessage(client, err, { to });
+          if (stale) {
+            cleanupTemps();
+            fail(stale);
+          }
           // Route absent (bodyless 404 / 501) → this add-in predates the streaming
-          // route; fall through to the capped base64 ack path below.
+          // route; fall through to the capped base64 ack path below. On the
+          // pane-free path there is no ack path to fall back to.
           const routeMissing =
             (err?.status === 404 && !err?.code) || err?.status === 501;
-          if (!routeMissing) {
+          if (!routeMissing || !presId) {
+            const described = await describeEngineByteFailure(client, err, {
+              backendURL,
+            });
             cleanupTemps();
-            fail(`add-slide failed for selection ${pick}: ${err.message}`);
+            fail(`add-slide failed for selection ${pick}: ${described ?? err.message}`);
           }
         }
       }
@@ -1271,6 +1883,7 @@ async function cmdAddSlide(rest) {
     .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"));
   const targets = reused.reusedSlideTargets(existing, extracted, at);
   const written = [];
+  const slides = [];
   extracted.forEach((slide, i) => {
     const target = path.join(slidesDir, targets[i].filename);
     if (slide.tempPath) {
@@ -1279,12 +1892,13 @@ async function cmdAddSlide(rest) {
       fs.writeFileSync(target, Buffer.from(slide.base64, "base64"));
     }
     written.push(path.relative(process.cwd(), target));
+    slides.push({
+      selection: slide.selection,
+      slideId: slide.slideId ?? null,
+      file: path.relative(process.cwd(), target),
+    });
   });
-  process.stdout.write(
-    `Added ${written.length} reused slide(s) to ${path.relative(process.cwd(), deckDir)}:\n` +
-      written.map((w) => `  ${w}`).join("\n") +
-      `\nThey are native .pptx in slides/ — re-run 'slidemind build-pptx ${deck}' or 'slidemind push ${deck}' to render the deck with them spliced in.\n`,
-  );
+  writeAddSlideResult({ asJson, searchId, deckDir, deck, written, slides });
 }
 
 // Map a `--icon-color` value onto the `--pick` list. Accepts either one colour
@@ -1318,10 +1932,7 @@ async function cmdViewSlide(rest) {
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--search") {
-      const next = rest[++i];
-      const n = parseInt(next, 10);
-      if (!Number.isFinite(n)) fail(`--search expects a searchId, got '${next}'`);
-      searchId = n;
+      searchId = parseSearchIdArg(rest[++i]);
     } else if (a === "--pick") {
       const next = rest[++i];
       const n = parseInt(next, 10);
@@ -1342,7 +1953,7 @@ async function cmdViewSlide(rest) {
     }
   }
   if (searchId === null || pick === null) {
-    fail("usage: slidemind view-slide --search <id> --pick <n> --to <presId> [--out <dir>]");
+    fail("usage: slidemind view-slide --search <id> --pick <n> [--to <presId>] [--out <dir>]");
   }
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
@@ -1350,16 +1961,18 @@ async function cmdViewSlide(rest) {
   const { resolveAssetExt } = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
   );
-  const registry = await client.requirePaneHost();
-  // The searchId is presentation-scoped, so --to targets the window the search
-  // ran on. Without it, a registry with >1 open window is a dead-end.
-  const entry = client.pickPresentationEntry(registry, to);
-  const res = await client.viewSlide({
-    presId: entry.presId,
-    searchId,
-    selection: pick,
-    backendURL: entry.backendURL ?? null,
-  });
+  const routing = await resolveEngineRouting(client, { to, searchId });
+  let res;
+  try {
+    res = await client.viewSlide({
+      presId: routing.presId,
+      searchId,
+      selection: pick,
+      backendURL: routing.backendURL,
+    });
+  } catch (err) {
+    await failOnEngineBlocker(client, err, { to });
+  }
   if (!res?.ok || !res.dataUri) {
     fail(`view-slide failed: ${res?.error ?? "no image returned"}`);
   }
@@ -1383,6 +1996,135 @@ async function cmdViewSlide(rest) {
   );
 }
 
+async function cmdReadSource(rest) {
+  let searchId = null;
+  let pick = null;
+  let fromSlide = null;
+  let toSlide = null;
+  let to = null;
+  let outFile = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--search") {
+      searchId = parseSearchIdArg(rest[++i]);
+    } else if (a === "--pick") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--pick expects a positive selection number, got '${next}'`);
+      }
+      pick = n;
+    } else if (a === "--from-slide") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--from-slide expects a positive slide number, got '${next}'`);
+      }
+      fromSlide = n;
+    } else if (a === "--to-slide") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--to-slide expects a positive slide number, got '${next}'`);
+      }
+      toSlide = n;
+    } else if (a === "--to") {
+      // Deliberately the WINDOW, matching every other search-scoped command.
+      // The slide window is --from-slide/--to-slide.
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--out" || a === "-o") {
+      outFile = rest[++i];
+      if (!outFile) fail("--out expects a file path");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (searchId === null || pick === null) {
+    fail(
+      "usage: slidemind read-source --search <id> --pick <n> [--from-slide <n>] [--to-slide <n>] [--to <presId>] [--out <file>]",
+    );
+  }
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  // Pane path: the searchId is presentation-scoped, so --to targets the window
+  // the search ran on — same rule as view-slide. Direct path: the record is the
+  // backend's, so no window is involved.
+  const routing = await resolveEngineRouting(client, { to, searchId });
+  let res;
+  try {
+    res = await client.readSourcePresentation({
+      presId: routing.presId,
+      searchId,
+      selection: pick,
+      fromSlide,
+      toSlide,
+      backendURL: routing.backendURL,
+    });
+  } catch (err) {
+    // The login_required line is authored once and knows about an open pane;
+    // everything else is this command's own vocabulary.
+    fail(
+      (await loginRequiredMessage(client, err, { to })) ??
+        describeReadSourceFailure(err, searchId, pick),
+    );
+  }
+  if (!res?.markdown) {
+    fail("read-source returned no content. Try the search again, then re-pick.");
+  }
+  if (outFile) {
+    const target = path.resolve(process.cwd(), outFile);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, res.markdown, "utf8");
+    process.stdout.write(
+      `Wrote the source presentation of result ${pick} (searchId ${searchId}) to ${target}\n`,
+    );
+  } else {
+    process.stdout.write(res.markdown.endsWith("\n") ? res.markdown : `${res.markdown}\n`);
+  }
+  // Truncation is the one thing a reader must not miss: the body they just got
+  // is a slide map, not the deck.
+  if (res.truncated) {
+    process.stderr.write(
+      `note: this deck was too long to return in full — the output is its slide map. ` +
+        `Re-run with --from-slide/--to-slide to read a range.\n`,
+    );
+  } else if (res.totalSlideCount && res.slideCount < res.totalSlideCount) {
+    process.stderr.write(
+      `note: showing ${res.slideCount} of ${res.totalSlideCount} slides.\n`,
+    );
+  }
+}
+
+/**
+ * Turn a source-presentation failure into the action that actually fixes it.
+ * A login_required refusal is handled one level up, in loginRequiredMessage —
+ * it is the one blocker only the USER can clear and it reads identically
+ * across every command.
+ */
+function describeReadSourceFailure(err, searchId, pick) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  switch (code) {
+    case "unknown_search":
+      return `searchId ${searchId} is no longer available on that window. Run 'slidemind search' again, then re-pick.`;
+    case "wrong_result_type":
+      return `result ${pick} has no source presentation — only slide search results come from a deck (image and collection results do not).`;
+    case "access_denied":
+      return "you do not have access to that result's source presentation.";
+    case "no_indexed_content":
+      return "that presentation has no indexed slides yet. It may still be syncing — try again later.";
+    case "invalid_source":
+      return `result ${pick} carries no source file reference. Re-run the search, or pick a different result.`;
+    case "source_presentation_unsupported":
+      return err.message;
+    default:
+      return `read-source failed: ${err?.message ?? "unknown error"}`;
+  }
+}
+
 async function cmdDownloadResult(rest) {
   let searchId = null;
   let picks = null;
@@ -1392,10 +2134,7 @@ async function cmdDownloadResult(rest) {
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--search") {
-      const next = rest[++i];
-      const n = parseInt(next, 10);
-      if (!Number.isFinite(n)) fail(`--search expects a searchId, got '${next}'`);
-      searchId = n;
+      searchId = parseSearchIdArg(rest[++i]);
     } else if (a === "--pick") {
       picks = parsePicks(rest[++i]);
     } else if (a === "--deck") {
@@ -1415,7 +2154,7 @@ async function cmdDownloadResult(rest) {
   }
   if (searchId === null || !picks || !deck) {
     fail(
-      "usage: slidemind download-result --search <id> --pick <n[,n,...]> --deck <deck> --to <presId> [--icon-color <hex[,hex,...]>]",
+      "usage: slidemind download-result --search <id> --pick <n[,n,...]> --deck <deck> [--to <presId>] [--icon-color <hex[,hex,...]>]",
     );
   }
   const iconColors = parseIconColors(iconColorsRaw, picks.length);
@@ -1430,10 +2169,15 @@ async function cmdDownloadResult(rest) {
   const { downloadOneResult } = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
   );
-  const registry = await client.requirePaneHost();
-  // The searchId is presentation-scoped, so --to targets the window the search
-  // ran on. Without it, a registry with >1 open window is a dead-end.
-  const entry = client.pickPresentationEntry(registry, to);
+  // Direct path: an opaque searchId routes to the record's own environment,
+  // else the deck's bound design decides; no window needed. Pane path: the
+  // searchId is presentation-scoped, so --to targets the window the search ran
+  // on (without it, >1 open window is a dead-end).
+  const routing = await resolveEngineRouting(client, {
+    to,
+    brandId: await deckBrandId(deckDir),
+    searchId,
+  });
 
   // Concurrent — each download is its own bridge round-trip; allSettled so one
   // bad selection doesn't sink the rest of the batch.
@@ -1441,8 +2185,8 @@ async function cmdDownloadResult(rest) {
     picks.map((selection, i) =>
       downloadOneResult({
         client,
-        presId: entry.presId,
-        backendURL: entry.backendURL ?? null,
+        presId: routing.presId,
+        backendURL: routing.backendURL,
         searchId,
         assetsDir,
         selection,
@@ -1450,10 +2194,26 @@ async function cmdDownloadResult(rest) {
       }),
     ),
   );
-  const results = settled.map((r, i) =>
-    r.status === "fulfilled"
-      ? r.value
-      : { selection: picks[i], error: r.reason?.message ?? String(r.reason) },
+  // One user-clearable blocker sinks the whole batch identically — every pick
+  // would fail the same way, and the fix is one action, not N error lines.
+  const stale = settled.find(
+    (r) => r.status === "rejected" && client.loginRequiredBlocker?.(r.reason),
+  );
+  if (stale) fail(await loginRequiredMessage(client, stale.reason, { to }));
+  const results = await Promise.all(
+    settled.map(async (r, i) =>
+      r.status === "fulfilled"
+        ? r.value
+        : {
+            selection: picks[i],
+            error:
+              (await describeEngineByteFailure(client, r.reason, {
+                backendURL: routing.backendURL,
+              })) ??
+              r.reason?.message ??
+              String(r.reason),
+          },
+    ),
   );
   const { formatSize } = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "image-dimensions.mjs")).href
@@ -1539,7 +2299,9 @@ async function cmdConceptImages(rest) {
     pathToFileURL(path.join(BUILDERS_DIR, "plan.mjs")).href
   );
   const planState = plan.loadPlanState(deckDir);
-  if (planState?.decision !== "approved") {
+  // "approve" is the gate's own persisted vocabulary (stdout says "approved");
+  // comparing against "approved" here made the note fire on every approved deck.
+  if (planState?.decision !== "approve") {
     process.stderr.write(
       `slidemind: note — ${deck}'s plan is not signed off yet ` +
         `(run \`slidemind plan ${deck}\`); generating concept mockups from the current plan.md anyway.\n`,
@@ -1760,7 +2522,7 @@ async function cmdPresentations(rest) {
   }
   for (const p of sorted) {
     const label = p.title || p.fileName || "(untitled)";
-    const env = p.env ? `[${p.env}]\t` : "";
+    const env = p.env && isMultiEnv() ? `[${p.env}]\t` : "";
     const state =
       p.connectionState ||
       (p.connected === false || p.suspendedAt ? "suspended" : "connected");
@@ -1798,20 +2560,22 @@ function publicConnectionStatus(status, client) {
   };
 }
 
-// The ordered connection-readiness ladder as a STRUCTURED blocker: the first
-// unmet precondition, or null when the connection is fully ready. `code` is the
-// machine-copeable reason an agent switches on; `actor` says who can clear it —
-// only `cli_update_required` is the AGENT's to fix (it can run `slidemind
-// update`), every other rung needs a human at the add-in. The one exception is
-// a plugin-installed CLI: `/plugin` is the only updater that replaces the
-// binary on the session's PATH, and the agent cannot drive it, so that rung
-// hands back to the user (see src/install-channel.mjs). The `message` strings
-// are otherwise BYTE-IDENTICAL to the old connectionNextAction ladder so
-// doctor's printed output never churns (connectionNextAction is now a thin
-// projection over this).
-// `slidemind ready` layers `ambiguous_design` on top and treats `pane_suspended`
-// as non-blocking (a render-ready-but-suspended window is still a design source).
-function connectionBlocker(pub) {
+// The readiness ladder splits in two, because the two halves fail
+// independently: BACKEND AUTHORING readiness (a session, a reachable add-in
+// backend, a supported CLI — everything render, bundle and the pane-free engine
+// routes need) and LIVE POWERPOINT readiness (a registered window, render-ready
+// metadata, an awake pane — what push/insert-slide and reading an open deck
+// need). Keeping them apart is the whole point of doc 13: a dead pane is no
+// longer "cannot work", it only defers the last mile.
+//
+// Each rung is a STRUCTURED blocker: `code` is the machine-copeable reason an
+// agent switches on; `actor` says who can clear it — only `cli_update_required`
+// is the AGENT's to fix (it can run `slidemind update`), every other rung needs
+// a human at the add-in. The one exception is a plugin-installed CLI:
+// `/plugin` is the only updater that replaces the binary on the session's PATH,
+// and the agent cannot drive it, so that rung hands back to the user (see
+// src/install-channel.mjs).
+function backendBlocker(pub) {
   if (!pub.paired) {
     return {
       code: "not_paired",
@@ -1841,6 +2605,15 @@ function connectionBlocker(pub) {
         updateCliInstruction(),
     };
   }
+  return null;
+}
+
+// The live-PowerPoint half. Never gates render, bundle or the pane-free engine
+// routes — it only says whether the ops that genuinely type into an open deck
+// (push's insert, insert-slide, reading an unsaved presentation) can run now.
+// The `message` strings are BYTE-IDENTICAL to the pre-split ladder so doctor's
+// printed output never churns.
+function paneBlocker(pub) {
   if ((pub.presentations ?? []).length === 0) {
     return {
       code: "no_window",
@@ -1875,12 +2648,20 @@ function connectionBlocker(pub) {
       code: "pane_suspended",
       actor: "user",
       message:
-        "Rendering is available, but pane operations are suspended. Bring PowerPoint forward and click/reopen the slidemind pane before push/search/read.",
+        "Rendering is available, but pane operations are suspended. Bring PowerPoint forward and click/reopen the slidemind pane before push, insert-slide, or reading this window.",
     };
   }
   return null;
 }
 
+// The two ladders end-to-end, in the order a user hits them: nothing about a
+// window matters while the backend half is unmet. `slidemind ready` layers
+// `ambiguous_design` on top and treats `pane_suspended` as non-blocking (a
+// render-ready-but-suspended window is still a design source).
+function connectionBlocker(pub) {
+  return backendBlocker(pub) ?? paneBlocker(pub);
+}
+
 // Back-compat projection for doctor: just the blocker's message, or "Ready."
 // when the ladder is clear. Keeps the ladder authored in ONE place.
 function connectionNextAction(pub) {
@@ -1908,6 +2689,7 @@ async function cmdSetup(rest) {
   let target = "auto";
   let doInstall = true;
   let doReady = true;
+  let doLogin = true;
   let asJson = false;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
@@ -1921,6 +2703,8 @@ async function cmdSetup(rest) {
       doInstall = false;
     } else if (a === "--no-ready") {
       doReady = false;
+    } else if (a === "--no-login") {
+      doLogin = false;
     } else if (a === "--json") {
       asJson = true;
     } else if (a.startsWith("-")) {
@@ -1955,14 +2739,24 @@ async function cmdSetup(rest) {
   ui.banner(pkg.version, "setup");
 
   // --- 1. spend the claim -------------------------------------------------
-  await ui.section("connect", envLabel);
+  // Whether to name the environment at all. Decided BEFORE the claim is spent
+  // so every line in this run agrees: a first connection has nothing to
+  // disambiguate against and stays quiet, while adding a second (or third)
+  // environment names each one. Computing it per-line would flip mid-run, since
+  // `upsertSession` below changes the count.
+  const showEnv = cfg.readSessions().length > 0;
+  await ui.section("connect", showEnv ? envLabel : "");
   const sessionToken = await claims.redeemSetupClaim({
     backendURL,
     secret,
     cliVersion: pkg.version,
   });
   cfg.upsertSession({ backendURL, sessionToken, label: envLabel });
-  ui.step({ label: "authorize", value: envLabel, note: "session saved" });
+  ui.step({
+    label: "authorize",
+    value: showEnv ? envLabel : "connected",
+    note: "session saved",
+  });
 
   // --- 2. make this CLI permanent ----------------------------------------
   // Without this the whole thing evaporates with npx's cache: the user would be
@@ -2046,6 +2840,52 @@ async function cmdSetup(rest) {
     bundleMod.clearBundleCache();
   }
 
+  // --- 4. Microsoft 365 sign-in (best-effort) -----------------------------
+  // The pasted-claim moment is the one time the user is reliably at the
+  // keyboard in consent headspace, so offer the browser sign-in NOW and no
+  // later command has to interrupt a task for it. Strictly best-effort and
+  // interactive-only: --json or no TTY (an agent ran setup — a browser tab it
+  // cannot see must never block onboarding), --no-login, a backend that does
+  // not honour the token, a decline or a timeout all skip WITHOUT failing
+  // setup — the closing `ready` and the failure-time remediations still name
+  // `slidemind login`.
+  if (doLogin && !asJson && process.stdout.isTTY) {
+    try {
+      const client = await loadBridgeModule("client");
+      if (await client.backendSupportsGraphDelegated(backendURL)) {
+        await ui.section("sign in", "Microsoft 365");
+        process.stderr.write(
+          "Opening your browser to sign in to Microsoft 365 — this lets SharePoint-backed\n" +
+            "content download with no PowerPoint window open.\n",
+        );
+        const graph = await loadBridgeModule("graph-auth");
+        const res = await graph.loginGraph({
+          backendURL,
+          // Shorter than `slidemind login`'s: the user is mid-setup, not
+          // parked on a sign-in they asked for — a walked-away browser tab
+          // should not stall onboarding for five minutes.
+          timeoutMs: 120_000,
+          onUrl: (url) =>
+            process.stderr.write(
+              `If no browser opens, paste this link into one:\n  ${url}\n`,
+            ),
+        });
+        ui.step({
+          label: "Microsoft 365",
+          value: res.username ?? "signed in",
+          ...(showEnv ? { note: envLabel } : {}),
+        });
+      }
+    } catch {
+      ui.step({
+        status: "warn",
+        label: "Microsoft 365",
+        value: "skipped",
+        note: "run 'slidemind login' anytime for window-free SharePoint downloads",
+      });
+    }
+  }
+
   if (asJson) {
     const globalInstall =
       doInstall && !pluginInstall
@@ -2078,8 +2918,8 @@ async function cmdSetup(rest) {
 
   ui.done(
     target === "none" || (skills.length === 0 && skippedPlugins.length === 0)
-      ? `connected to ${envLabel} — run 'slidemind ready' to start`
-      : `connected to ${envLabel} and ready to use`,
+      ? `connected${showEnv ? ` to ${envLabel}` : ""} — run 'slidemind ready' to start`
+      : `connected${showEnv ? ` to ${envLabel}` : ""} and ready to use`,
   );
 
   if (installError) {
@@ -2097,7 +2937,7 @@ async function cmdSetup(rest) {
     return;
   }
 
-  // --- 4. finish the session the user actually came for -------------------
+  // --- 5. finish the session the user actually came for -------------------
   // `ready` exits non-zero for every legitimate not-yet blocker (PowerPoint
   // closed, no design activated). Setup already succeeded at that point, so its
   // blocker is information, not a failure — run it for the message and the
@@ -2121,6 +2961,7 @@ async function cmdReady(rest) {
   let asJson = false;
   let force = false;
   let connectOnly = false;
+  let brand = null;
   const positional = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
@@ -2133,12 +2974,18 @@ async function cmdReady(rest) {
       force = true;
     } else if (a === "--connect-only") {
       connectOnly = true;
+    } else if (a === "--brand") {
+      brand = rest[++i];
+      if (!brand) fail("--brand expects a design id (presFP)");
     } else if (a.startsWith("-")) {
       fail(`unknown flag: ${a}`);
     } else {
       positional.push(a);
     }
   }
+  if (brand && to) {
+    fail("--brand and --to are mutually exclusive (a design id or a window, not both)");
+  }
 
   // --- Local: resolve the deck dir (never create it) and read its existing
   // bundle ref. deckPresFP feeds ONLY the mirror tie-break + `suggested`; it
@@ -2228,10 +3075,213 @@ async function cmdReady(rest) {
     return;
   }
 
+  // --- Backend authoring readiness beyond the connection itself: which
+  // environments serve the pane-free engine routes. Probed at most once (and
+  // only when a payload actually reports it), and never fatal — an add-in
+  // without them still authors, it just relays search through a window. ---
+  let engineInfo = null;
+  const engines = async () => {
+    if (!engineInfo) {
+      try {
+        engineInfo = await client.engineReachability({
+          backends: statusRaw.backends,
+        });
+      } catch {
+        engineInfo = { available: false, envs: [] };
+      }
+    }
+    return engineInfo;
+  };
+
+  // Microsoft 365 sign-in, surfaced HERE because ready is the agent's
+  // session-start preflight and browser SSO is the one step an agent cannot do
+  // itself — it has to ask its human, and this is where it learns to. Reported
+  // only when a backend advertises graphDelegated (older backends have no
+  // window-free SharePoint path, so there is nothing to sign in FOR).
+  // On a cliLoginV1 backend the sign-in is REQUIRED for the whole pane-free
+  // engine surface (catalog, search, downloads, extraction answer 401
+  // login_required without it) — so the degradation says that plainly and up
+  // front, before the agent's first search meets the 401. Render and bundle
+  // still never need it. null = no backend advertises it.
+  let m365Info;
+  const m365 = async () => {
+    if (m365Info !== undefined) return m365Info;
+    const advertising = (statusRaw.backends ?? []).filter(
+      (b) => b.ok && b.capabilities?.graphDelegated === true && b.backendURL,
+    );
+    if (advertising.length === 0) {
+      m365Info = null;
+      return m365Info;
+    }
+    const graph = await loadBridgeModule("graph-auth");
+    const signedOut = advertising.filter(
+      (b) => !graph.hasGraphSession(b.backendURL),
+    );
+    const signedOutEnvs = signedOut.map((b) => cfg.deriveEnvLabel(b.backendURL));
+    m365Info =
+      signedOut.length === 0
+        ? { signedIn: true, degradation: null, line: "Microsoft 365: signed in" }
+        : {
+            signedIn: false,
+            degradation: {
+              code: "login_required",
+              actor: "user",
+              envs: signedOutEnvs,
+              message:
+                "Microsoft 365: not signed in — engine search, downloads and slide " +
+                "extraction run as the USER. The first engine command opens a browser " +
+                "sign-in AUTOMATICALLY and waits; tell the user to complete it there " +
+                "(you cannot). Render, build and bundle work without it.",
+            },
+            line:
+              `Microsoft 365: not signed in${envTag(signedOutEnvs.join(", "))} — the next engine ` +
+              "command opens a browser sign-in for the user to complete (automatic; " +
+              "`slidemind login` also works any time).",
+          };
+    return m365Info;
+  };
+
+  // --- A design resolved WITHOUT a window — the deck's own binding, an
+  // explicit --brand, or the backend's brand list. Same payload either way:
+  // ready, `windowless: true`, and a pane status that is INFORMATIONAL. What
+  // the missing window actually costs depends on the engine routes: with them
+  // only push/insert-slide and reading an open presentation need PowerPoint.
+  //
+  // "Windowless" is about how the DESIGN was resolved, not about the registry:
+  // --brand runs before the registry is consulted at all, and the later rungs
+  // fire on "nothing render-ready", which a connected-but-still-matching window
+  // satisfies. So the pane status is DERIVED from the registry as it stands at
+  // call time (the hydration wait reassigns it), and the prose only claims
+  // "no PowerPoint window" when there genuinely is none. ---
+  const finishWindowless = async (result) => {
+    if (deckDir) {
+      bundle.writeDeckBundleRef(deckDir, {
+        presFP: result.presFP,
+        etag: result.etag,
+      });
+    }
+    const designName = readDesignName(result.dir);
+    const env = result.backendURL ? cfg.deriveEnvLabel(result.backendURL) : null;
+    const eng = await engines();
+    const m = await m365();
+    const paneReady = registry.some(client.isPaneReadyPresentation);
+    const noWindow = registry.length === 0;
+    const nextAction = noWindow
+      ? eng.available
+        ? "Ready (no PowerPoint window — authoring, engine search and build-pptx all work; only push/insert-slide and reading an open presentation need one)."
+        : "Ready (no PowerPoint window — build-pptx/build/review/view-draft work; push/search/read need a pane)."
+      : paneReady
+        ? "Ready (design resolved without targeting a window; a registered PowerPoint window is available for push/insert-slide)."
+        : eng.available
+          ? "Ready (design resolved without targeting a window; pane operations — push/insert-slide/read of a window — will wait for a pane click; engine search does not)."
+          : "Ready (design resolved without targeting a window; pane operations — push/search/read — will wait for a pane click).";
+    if (asJson) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            ready: true,
+            windowless: true,
+            deck: deckSlug,
+            bound: Boolean(deckDir),
+            env,
+            presId: null,
+            presFP: result.presFP,
+            designName,
+            bundleDir: result.dir,
+            bundleEtag: result.etag ?? null,
+            paneSuspended: !paneReady,
+            engines: eng,
+            ...(m ? { m365: { signedIn: m.signedIn, degradation: m.degradation } } : {}),
+            warnings: result.warnings ?? [],
+            nextAction,
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+      return;
+    }
+    const designLabel = designName
+      ? `${designName} (${result.presFP})`
+      : result.presFP;
+    process.stdout.write(
+      `Ready — design ${designLabel}${envTag(env)}${noWindow ? " (no PowerPoint window)" : ""}\n`,
+    );
+    process.stdout.write(`  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`);
+    if (deckDir) process.stdout.write(`  deck ${deckSlug} bound\n`);
+    process.stdout.write(
+      noWindow
+        ? eng.available
+          ? "  Note: authoring, engine search and build-pptx need no window; push/insert-slide and reading an open presentation do.\n"
+          : "  Note: build-pptx/build/review/view-draft work without a window; push/search/read need a pane.\n"
+        : paneReady
+          ? "  Note: the design was resolved without targeting a window; a registered PowerPoint window is available for push/insert-slide.\n"
+          : eng.available
+            ? "  Note: pane operations (push/insert-slide/read of a window) will wait for a pane click; engine search does not.\n"
+            : "  Note: pane operations (push/search/read) will wait for a pane click.\n",
+    );
+    if (m) process.stdout.write(`  ${m.line}\n`);
+    for (const w of result.warnings ?? []) {
+      process.stderr.write(`  warning: ${w}\n`);
+    }
+  };
+
+  // Materialize a design by id over the pane-free brand route. Returns null on
+  // any miss (old add-in, unknown/revoked design) so the caller can fall
+  // through to the window ladder instead of dead-ending.
+  const materializeBrand = async (brandId) => {
+    try {
+      return await bundle.materializeBundle(null, { force, brandId });
+    } catch {
+      return null;
+    }
+  };
+
+  // --- --brand <presFP>: the user (or the agent, after an ambiguous brand
+  // list) named the design outright. It resolves with or without a window, so
+  // it runs before the registry is consulted at all. ---
+  if (brand) {
+    const result = await materializeBrand(brand);
+    if (!result) {
+      finishBlocker({
+        blocker: {
+          code: "unknown_brand",
+          actor: "user",
+          message: `No connected slidemind add-in serves design '${brand}'. Run 'slidemind ready' with no --brand to see which designs are available.`,
+        },
+      });
+      return;
+    }
+    await finishWindowless(result);
+    return;
+  }
+
+  const isRR = client.isRenderReadyPresentation;
+
+  // --- Bound-deck ladder: session → bundle freshness, no pane precondition.
+  // The design identity (presFP == brandId) lives in the deck's
+  // .bundle-ref.json and the bundle syncs over the pane-free brand route, so
+  // with PowerPoint CLOSED (an empty registry) a bound deck readies straight
+  // away instead of sitting out the hydration wait for a window that isn't
+  // coming. A registry that holds windows still hydrates first — the open
+  // add-in stays the source of truth whenever there IS one. Skipped for
+  // --connect-only (which resolves no design at all) and for --to (an explicit
+  // window must resolve through the registry); a miss (old add-in, legacy ref,
+  // revoked grant) falls through to the window ladder. ---
+  const boundDeckLadder = deckDir && deckPresFP && !to && !connectOnly;
+  let boundRungTried = false;
+  if (boundDeckLadder && registry.length === 0) {
+    boundRungTried = true;
+    const result = await materializeBrand(deckPresFP);
+    if (result) {
+      await finishWindowless(result);
+      return;
+    }
+  }
+
   // --- Bounded hydration wait when nothing is render-ready yet: covers the
   // just-clicked / just-woke pane still hydrating brand metadata. Polls even on
   // an empty registry (that's the flaky window this papers over). ---
-  const isRR = client.isRenderReadyPresentation;
   if (!registry.some(isRR)) {
     const waitMs =
       parseInt(process.env.SLIDEMIND_BRIDGE_PRESENTATIONS_WAIT_MS || "6000", 10) ||
@@ -2245,74 +3295,92 @@ async function cmdReady(rest) {
     }
   }
   if (!registry.some(isRR)) {
-    // --- Pane-free rung: a BOUND deck readies over the brand routes with no
-    // window at all — the design identity (presFP == brandId) lives in the
-    // deck's .bundle-ref.json, and the render half never needed the pane.
-    // Degraded: build-pptx/build/review/view-draft work; push/search/read
-    // still need a pane. Skipped for --connect-only (search needs a pane) and
-    // --to (an explicit window must resolve through the registry). Any miss
-    // (old add-in, legacy ref, revoked grant) falls through to the ladder.
-    if (deckDir && deckPresFP && !to && !connectOnly) {
-      let result = null;
+    // --connect-only asks one question — "can I work?" — and since the engine
+    // routes answer off the session, a backend that serves them IS the answer:
+    // discovery, search and every per-result fetch run with PowerPoint closed.
+    // Without them search is still relayed through a pane, so the window rung
+    // below stands.
+    if (connectOnly && (await engines()).available) {
+      const eng = await engines();
+      const m = await m365();
+      if (asJson) {
+        process.stdout.write(
+          JSON.stringify(
+            {
+              ready: true,
+              connectOnly: true,
+              windowless: true,
+              engines: eng,
+              ...(m ? { m365: { signedIn: m.signedIn, degradation: m.degradation } } : {}),
+              nextAction:
+                "Ready (no PowerPoint window — engine search runs off the connection; only insert-slide needs one).",
+              backends: (pub.backends ?? []).map((b) => ({ env: b.env, ok: b.ok })),
+            },
+            null,
+            2,
+          ) + "\n",
+        );
+      } else {
+        process.stdout.write(
+          `Connected. ${pub.backendCount} backend(s), 0 window(s) registered — ` +
+            `engine search runs without one${envTag(eng.envs.join(", "))}.\n`,
+        );
+        if (m) process.stdout.write(`  ${m.line}\n`);
+      }
+      return;
+    }
+    // The bound-deck ladder again, for the windows-registered-but-never-ready
+    // case the pre-poll rung deliberately left to the hydration wait.
+    if (boundDeckLadder && !boundRungTried) {
+      boundRungTried = true;
+      const result = await materializeBrand(deckPresFP);
+      if (result) {
+        await finishWindowless(result);
+        return;
+      }
+    }
+    // --- Unbound + no window: ask the backend which designs this user may
+    // build against. One is the answer; several genuinely need a human choice,
+    // which --brand records. A backend without the route (or a deck already
+    // bound to a design the brand route just refused) falls through unchanged. ---
+    if (!connectOnly && !to && !deckPresFP && !boundRungTried) {
+      let brands = [];
       try {
-        result = await bundle.materializeBundle(null, {
-          force,
-          brandId: deckPresFP,
-        });
+        brands = await client.listBrands();
       } catch {
-        /* fall through to the standard no_window / not_render_ready blocker */
+        /* no brand list — the window ladder below is the answer */
       }
-      if (result) {
-        bundle.writeDeckBundleRef(deckDir, {
-          presFP: result.presFP,
-          etag: result.etag,
-        });
-        const designName = readDesignName(result.dir);
-        const env = result.backendURL
-          ? cfg.deriveEnvLabel(result.backendURL)
-          : null;
-        const nextAction =
-          "Ready (no PowerPoint window — build-pptx/build/review/view-draft work; push/search/read need a pane).";
-        if (asJson) {
-          process.stdout.write(
-            JSON.stringify(
-              {
-                ready: true,
-                windowless: true,
-                deck: deckSlug,
-                bound: true,
-                env,
-                presId: null,
-                presFP: result.presFP,
-                designName,
-                bundleDir: result.dir,
-                bundleEtag: result.etag ?? null,
-                paneSuspended: true,
-                warnings: result.warnings ?? [],
-                nextAction,
-              },
-              null,
-              2,
-            ) + "\n",
-          );
+      if (brands.length === 1) {
+        const result = await materializeBrand(brands[0].presFP);
+        if (result) {
+          await finishWindowless(result);
           return;
         }
-        const designLabel = designName
-          ? `${designName} (${result.presFP})`
-          : result.presFP;
-        process.stdout.write(
-          `Ready — design ${designLabel}${env ? ` [${env}]` : ""} (no PowerPoint window)\n`,
-        );
-        process.stdout.write(
-          `  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`,
-        );
-        process.stdout.write(`  deck ${deckSlug} bound\n`);
-        process.stdout.write(
-          "  Note: build-pptx/build/review/view-draft work without a window; push/search/read need a pane.\n",
+      } else if (brands.length > 1) {
+        const rows = brands.map(
+          (b) => `  ${b.presFP}${envTag(b.env)}  ${b.name ?? ""}`.trimEnd(),
         );
-        for (const w of result.warnings ?? []) {
-          process.stderr.write(`  warning: ${w}\n`);
-        }
+        const blocker = {
+          code: "ambiguous_brand",
+          actor: "user",
+          message:
+            "Several corporate designs are available and no PowerPoint window says which — ask the user which to build against, then re-run: slidemind ready" +
+            `${deckSlug ? ` ${deckSlug}` : ""} --brand <presFP>.`,
+        };
+        finishBlocker({
+          blocker,
+          extras: {
+            brands: brands.map((b) => ({
+              presFP: b.presFP,
+              name: b.name ?? null,
+              env: b.env ?? null,
+            })),
+          },
+          humanLines:
+            "slidemind: several corporate designs are available — ask the user which to build against:\n" +
+            `${rows.join("\n")}\n` +
+            `Then re-run: slidemind ready${deckSlug ? ` ${deckSlug}` : ""} --brand <presFP>`,
+        });
         return;
       }
     }
@@ -2339,12 +3407,15 @@ async function cmdReady(rest) {
   // --- --connect-only: the connection is up with ≥1 render-ready window; the
   // search skill needs nothing more (no design resolution, no bundle). ---
   if (connectOnly) {
+    const m = await m365();
     if (asJson) {
       process.stdout.write(
         JSON.stringify(
           {
             ready: true,
             connectOnly: true,
+            engines: await engines(),
+            ...(m ? { m365: { signedIn: m.signedIn, degradation: m.degradation } } : {}),
             nextAction: "Ready.",
             backends: (pub.backends ?? []).map((b) => ({ env: b.env, ok: b.ok })),
           },
@@ -2357,6 +3428,7 @@ async function cmdReady(rest) {
       process.stdout.write(
         `Connected. ${pub.backendCount} backend(s), ${windows} window(s) registered.\n`,
       );
+      if (m) process.stdout.write(`  ${m.line}\n`);
     }
     return;
   }
@@ -2395,7 +3467,7 @@ async function cmdReady(rest) {
     };
     const rows = windows.map(
       (p) =>
-        `  ${p.presId}  ${p.env ? `[${p.env}]  ` : ""}${p.title || p.fileName || "(untitled)"}`,
+        `  ${p.presId} ${envTag(p.env)}  ${p.title || p.fileName || "(untitled)"}`,
     );
     finishBlocker({
       blocker,
@@ -2416,7 +3488,7 @@ async function cmdReady(rest) {
         "Multiple corporate designs are open — ask the user which to build against, then re-run: slidemind ready --to <presId>.",
     };
     const rows = cand.map((c) => {
-      const env = c.env ? `  [${c.env}]` : "";
+      const env = envTag(c.env) ? ` ${envTag(c.env)}` : "";
       const label = c.title || c.fileName || "(untitled)";
       return `  ${c.presId}${env}  ${label}    (design ${c.brandId ?? "?"})`;
     });
@@ -2468,6 +3540,8 @@ async function cmdReady(rest) {
 
   const designName = readDesignName(result.dir);
   const paneSuspended = !client.isPaneReadyPresentation(entry);
+  const engineInfoForWindow = await engines();
+  const m365ForWindow = await m365();
 
   if (asJson) {
     process.stdout.write(
@@ -2487,6 +3561,15 @@ async function cmdReady(rest) {
             fileName: entry.fileName ?? null,
           },
           paneSuspended,
+          engines: engineInfoForWindow,
+          ...(m365ForWindow
+            ? {
+                m365: {
+                  signedIn: m365ForWindow.signedIn,
+                  degradation: m365ForWindow.degradation,
+                },
+              }
+            : {}),
           warnings: result.warnings ?? [],
           nextAction: "Ready.",
         },
@@ -2498,22 +3581,25 @@ async function cmdReady(rest) {
   }
 
   // --- Human success: compact multi-line summary on stdout. ---
-  const envTag = entry.env ? ` [${entry.env}]` : "";
+  const entryEnv = envTag(entry.env);
   const presLabel = entry.title || entry.fileName || "(untitled)";
   const designLabel = designName
     ? `${designName} (${result.presFP})`
     : result.presFP;
   process.stdout.write(`Ready — design ${designLabel}\n`);
-  process.stdout.write(`  presentation: ${presLabel}${envTag}\n`);
+  process.stdout.write(`  presentation: ${presLabel}${entryEnv}\n`);
   process.stdout.write(
     `  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`,
   );
   if (bound) process.stdout.write(`  deck ${deckSlug} bound\n`);
   if (paneSuspended) {
     process.stdout.write(
-      "  Note: pane operations (push/search/read) will wait for a pane click.\n",
+      engineInfoForWindow.available
+        ? "  Note: pane operations (push/insert-slide/read of this window) will wait for a pane click; engine search does not.\n"
+        : "  Note: pane operations (push/search/read) will wait for a pane click.\n",
     );
   }
+  if (m365ForWindow) process.stdout.write(`  ${m365ForWindow.line}\n`);
   for (const w of result.warnings ?? []) {
     process.stderr.write(`  warning: ${w}\n`);
   }
@@ -2530,11 +3616,14 @@ async function cmdDoctor(rest) {
   // still reaches the reader, as the `cli_update_required` rung of the ladder.
   client.setDiagnosticMode(true);
   if (sessions.length === 0) {
+    const blocker = backendBlocker({ paired: false });
     const pub = {
       paired: false,
       backendCount: 0,
       backends: [],
       presentations: [],
+      authoring: { ready: false, blocker, degraded: null, engines: null },
+      host: { ready: false, blocker: paneBlocker({ presentations: [] }) },
       nextAction: connectionNextAction({ paired: false }),
     };
     process[asJson ? "stdout" : "stderr"].write(
@@ -2542,7 +3631,29 @@ async function cmdDoctor(rest) {
     );
     return;
   }
-  const status = publicConnectionStatus(await client.connectionStatus(), client);
+  const statusRaw = await client.connectionStatus();
+  const status = publicConnectionStatus(statusRaw, client);
+  // The two ladders are INDEPENDENT: authoring (session → reachable backend →
+  // CLI version → engine reachability) is what render, bundle and the pane-free
+  // engine routes ride on, while the live-PowerPoint ladder only governs
+  // push/insert-slide and reading an open presentation. Reporting them
+  // separately is the point — a dead pane is not "cannot work".
+  const authoringBlocker = backendBlocker(status);
+  let engines = { available: false, envs: [] };
+  if (!authoringBlocker) {
+    try {
+      engines = await client.engineReachability({ backends: statusRaw.backends });
+    } catch {
+      /* leave it as unavailable — never fail a diagnosis on a probe */
+    }
+  }
+  status.authoring = {
+    ready: !authoringBlocker,
+    blocker: authoringBlocker,
+    engines,
+  };
+  const hostBlocker = paneBlocker(status);
+  status.host = { ready: !hostBlocker, blocker: hostBlocker };
   status.nextAction = connectionNextAction(status);
   if (asJson) {
     process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
@@ -2556,6 +3667,41 @@ async function cmdDoctor(rest) {
         `\n`,
     );
   }
+  process.stdout.write(
+    `Backend authoring ready: ${status.authoring.ready ? "yes" : "no"}` +
+      `${status.authoring.ready ? "" : ` — ${authoringBlocker.message}`}\n`,
+  );
+  process.stdout.write(
+    `  engine search (no window needed): ${
+      engines.available
+        ? `yes [${engines.envs.join(", ")}]`
+        : "no — relayed through an open pane"
+    }\n`,
+  );
+  // Human output only — doctor's --json shape is a contract and the m365 state
+  // already rides `ready --json`. Printed only when a backend can actually
+  // spend a sign-in (graphDelegated), so old deployments stay noise-free.
+  const graphAdvertising = (statusRaw.backends ?? []).filter(
+    (b) => b.ok && b.capabilities?.graphDelegated === true && b.backendURL,
+  );
+  if (graphAdvertising.length > 0) {
+    const graph = await loadBridgeModule("graph-auth");
+    const signedOut = graphAdvertising.filter(
+      (b) => !graph.hasGraphSession(b.backendURL),
+    );
+    const signedOutEnvs = signedOut.map((b) => cfg.deriveEnvLabel(b.backendURL));
+    process.stdout.write(
+      signedOut.length === 0
+        ? "  Microsoft 365: signed in\n"
+        : `  Microsoft 365: not signed in [${signedOutEnvs.join(", ")}] — engine search and ` +
+          "downloads run as the user; the next engine command opens a browser " +
+          "sign-in for them to complete (or run 'slidemind login' now)\n",
+    );
+  }
+  process.stdout.write(
+    `Live PowerPoint ready: ${status.host.ready ? "yes" : "no"}` +
+      `${status.host.ready ? "" : ` — ${hostBlocker.message}`}\n`,
+  );
   if (status.presentations.length === 0) {
     process.stdout.write("Open presentations: none\n");
   } else {
@@ -2697,16 +3843,88 @@ async function loadBridgeModule(name) {
   return import(pathToFileURL(path.join(SRC_DIR, "bridge", `${name}.mjs`)).href);
 }
 
+// The one line every "you are not connected" path speaks, so the remedy reads
+// the same wherever a user meets it.
+const NOT_CONNECTED_LINE =
+  "Not connected. In PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, and run the command it shows.";
+
+// Match a `--backend`-style argument against a paired session the way logout and
+// use do: exact URL, stored label, derived env label, or a substring of the URL.
+function matchesBackend(cfg, session, want) {
+  return (
+    session.backendURL === want ||
+    session.label === want ||
+    cfg.deriveEnvLabel(session.backendURL) === want ||
+    session.backendURL.includes(want)
+  );
+}
+
+// `slidemind login [--backend <url|env>]` — sign this CLI in to Microsoft 365 so
+// the pane-free engine routes can fetch SharePoint-backed content with the
+// user's OWN identity (docs/slidemind-cli-connect/15-graph-delegated-cli.md).
+// Separate from the CLI session on purpose: that one is minted by the add-in for
+// whoever pressed Connect CLI, this one is an Entra token for whoever completes
+// the browser sign-in, and only the second may read a user's SharePoint content.
+// Everything else — render, bundle, whoami — is unaffected either way.
+async function cmdLogin(rest) {
+  const stray = rest.find((a) => a.startsWith("-"));
+  if (stray) {
+    fail(`unexpected argument: ${stray}\nusage: slidemind login [--backend <url|env>]`);
+  }
+  const cfg = await loadBridgeModule("config");
+  const sessions = cfg.readSessions();
+  if (sessions.length === 0) fail(NOT_CONNECTED_LINE);
+  // A browser flow targets ONE environment — there is nothing to fan out. The
+  // scope flag picks it; otherwise the default environment does, and the closing
+  // line names the others so nothing looks silently skipped.
+  const want = (process.env.SLIDEMIND_BACKEND || "").trim();
+  let target;
+  if (want) {
+    target = sessions.find((s) => matchesBackend(cfg, s, want));
+    if (!target) {
+      fail(`not paired with '${want}'. Run 'slidemind whoami' to list environments.`);
+    }
+  } else {
+    const def = cfg.getDefaultBackend();
+    target = sessions.find((s) => s.backendURL === def) ?? sessions[0];
+  }
+  const graph = await loadBridgeModule("graph-auth");
+  // This command is routinely typed by an AI agent on the human's machine, and
+  // the browser is where the agent's reach ends — say the handoff out loud.
+  process.stderr.write(
+    `Opening your browser to sign in to Microsoft 365${envPhrase(target.label, "for")}…\n` +
+      "A HUMAN must complete this step (agents: ask your user to finish the " +
+      "sign-in in the browser window that just opened).\n",
+  );
+  const res = await graph.loginGraph({
+    backendURL: target.backendURL,
+    // Printed before the opener runs: on a machine where no opener works this
+    // link is the only way through, and it is useless after the wait times out.
+    onUrl: (url) =>
+      process.stderr.write(`If no browser opens, paste this link into one:\n  ${url}\n`),
+  });
+  process.stdout.write(
+    `Signed in to Microsoft 365 as ${res.username ?? "your account"}${envPhrase(target.label, "for")}.\n` +
+      "SharePoint-backed slides and images now download with no PowerPoint window open.\n",
+  );
+  const others = sessions.filter((s) => s.backendURL !== target.backendURL);
+  if (others.length > 0) {
+    process.stdout.write(
+      `Still signed out: ${others.map((s) => s.label).join(", ")} ` +
+        "(each needs its own 'slidemind login --backend <env>').\n",
+    );
+  }
+}
+
 async function cmdWhoami() {
   const cfg = await loadBridgeModule("config");
   const sessions = cfg.readSessions();
   if (sessions.length === 0) {
-    process.stderr.write(
-      "Not connected. In PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, and run the command it shows.\n",
-    );
+    process.stderr.write(`${NOT_CONNECTED_LINE}\n`);
     return;
   }
   const { httpJson } = await loadBridgeModule("http-json");
+  const graph = await loadBridgeModule("graph-auth");
   const def = cfg.getDefaultBackend();
   const lines = await Promise.all(
     sessions.map(async (s) => {
@@ -2725,7 +3943,12 @@ async function cmdWhoami() {
       } catch {
         detail = "unreachable — check your connection or authorize again";
       }
-      return `${marker} ${s.label}\n    ${detail}`;
+      // Storage-only — no probe. The Graph sign-in is a SECOND identity, so it
+      // is reported next to the session rather than folded into it.
+      const graphLine = graph.hasGraphSession(s.backendURL)
+        ? "Microsoft 365: signed in"
+        : "Microsoft 365: not signed in — needed only for window-free SharePoint downloads (`slidemind login`)";
+      return `${marker} ${s.label}\n    ${detail}\n    ${graphLine}`;
     }),
   );
   process.stdout.write(
@@ -2765,6 +3988,10 @@ async function cmdLogout(rest) {
   }
 
   const { httpJson } = await loadBridgeModule("http-json");
+  // Unpairing takes the WHOLE record, the Microsoft 365 refresh token included —
+  // it was stored for this environment's session and must not outlive it. Said
+  // out loud because signing back in is a second command, not part of `setup`.
+  const droppedGraph = toRemove.filter((s) => s.msGraphRefreshToken);
   for (const s of toRemove) {
     try {
       await httpJson("POST", `${s.backendURL}/api/cli/logout`, {
@@ -2773,12 +4000,21 @@ async function cmdLogout(rest) {
     } catch {
       /* best-effort server-side revoke; we still drop the local session */
     }
+    // Through the token setter, not just the record removal: the refresh token
+    // may live in the macOS keychain (config.mjs), which removing the session
+    // record alone would orphan.
+    cfg.setGraphRefreshToken(s.backendURL, null);
     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 connected.\n` : "\n"),
+      (remaining > 0 ? ` ${remaining} environment(s) still connected.\n` : "\n") +
+      (droppedGraph.length > 0
+        ? `The Microsoft 365 sign-in for ${droppedGraph
+            .map((s) => s.label)
+            .join(", ")} was dropped too — run 'slidemind login' after reconnecting.\n`
+        : ""),
   );
 }
 
@@ -2803,12 +4039,114 @@ async function cmdUse(rest) {
   );
 }
 
+// `slidemind adopt <file.pptx> [--deck <slug>] [--brand <presFP>] [--no-convert]`
+// — reconstruct a local deck workspace from a presentation's deck-embedded
+// source tags (slides authored with slidemind carry their jsx inside the file).
+// Slides with no source are handed to the add-in's deterministic PPTX→JSX
+// conversion route where it is available (`docs/slidemind-cli-connect/
+// 14-foreign-slide-conversion.md`); whatever it declines folds in as native
+// reused .pptx. See also intern-slidemind docs/deck-embedded-source-spec.md.
+async function cmdAdopt(rest) {
+  const args = [...rest];
+  let deckSlug = null;
+  let brand = null;
+  let convert = true;
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--deck") {
+      deckSlug = args[++i] ?? null;
+      if (!deckSlug) fail("--deck expects a deck slug");
+    } else if (a === "--brand") {
+      brand = args[++i] ?? null;
+      if (!brand) fail("--brand expects a design id (presFP)");
+    } else if (a === "--no-convert") {
+      convert = false;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      positional.push(a);
+    }
+  }
+  const pptxArg = positional[0];
+  if (!pptxArg) {
+    fail("usage: slidemind adopt <file.pptx> [--deck <slug>] [--brand <presFP>] [--no-convert]");
+  }
+  // v1 is FILE decks only. A presId (or any non-file argument) would mean
+  // converting a LIVE presentation, which needs slide-export and tag-read
+  // events the relay does not have — say so instead of "no such file".
+  const {
+    LIVE_DECK_UNSUPPORTED,
+    adoptDeckFromPptx,
+    convertUntaggedSlides,
+    readSourceDeck,
+  } = await import(pathToFileURL(path.join(SRC_DIR, "lib", "adopt.mjs")).href);
+  if (!LOCAL_PPTX_RE.test(pptxArg)) fail(LIVE_DECK_UNSUPPORTED);
+  const pptxPath = path.resolve(pptxArg);
+  if (!fs.existsSync(pptxPath)) fail(`no such file: ${pptxArg}`);
+  const slug = deckSlug ?? path.basename(pptxPath).replace(/\.pptx$/i, "");
+  // The decks dir, not a hardcoded ./decks — otherwise `adopt` writes where no
+  // other subcommand looks whenever SLIDEMIND_DECKS is set. A RELATIVE slug
+  // must stay inside it (an explicit absolute path is the user's own choice) —
+  // every other untrusted name in this feature is escape-guarded, and this one
+  // rides agent-authored command lines.
+  const decksRoot = path.resolve(resolveDecksDir());
+  const deckDir = path.isAbsolute(slug) ? slug : path.resolve(decksRoot, slug);
+  if (
+    !path.isAbsolute(slug) &&
+    (deckDir === decksRoot || !deckDir.startsWith(decksRoot + path.sep))
+  ) {
+    fail(
+      `--deck '${slug}' escapes the decks directory (${decksRoot}) — ` +
+        "pass an absolute path to adopt somewhere else on purpose",
+    );
+  }
+  // ONE read/unzip/tag-decode of the source file, threaded into both halves —
+  // they must see the same snapshot (and a 40 MB deck decodes slowly).
+  const source = readSourceDeck(pptxPath);
+  const converted = convert
+    ? await convertUntaggedSlides({
+        pptxPath,
+        deckDir,
+        brandId: brand,
+        note: (line) => process.stderr.write(`${line}\n`),
+        source,
+      })
+    : null;
+  const result = adoptDeckFromPptx({ pptxPath, deckDir, converted, source });
+  // A decks dir outside the cwd (SLIDEMIND_DECKS) relativizes to ../../.. noise
+  // — print the absolute path there instead.
+  const shown = path.relative(process.cwd(), deckDir);
+  process.stdout.write(
+    `Adopted ${result.adopted.length} slide(s) with embedded source` +
+      (result.converted.length
+        ? `, converted ${result.converted.length} foreign slide(s) to editable jsx`
+        : "") +
+      (result.native.length
+        ? ` and folded ${result.native.length} untagged slide(s) as native .pptx`
+        : "") +
+      ` into ${shown.startsWith("..") ? deckDir : shown}/.\n` +
+      (result.skipped.length
+        ? `${result.skipped.length} slide(s) stayed native: ` +
+          `${result.skipped
+            .map((s) => `#${s.index ?? "?"} ${s.reason ?? "unknown"}`)
+            .join(", ")}\n`
+        : "") +
+      (result.bundle?.presFP && result.bundle.presFP !== "unknown"
+        ? `Deck bound to bundle ${result.bundle.presFP}.\n`
+        : `No bundle reference found in the file — run 'slidemind download-bundle ${slug}' before rendering.\n`) +
+      `Edit slides/*.jsx and run 'slidemind push ${slug}' or 'slidemind build-pptx ${slug}'.\n`,
+  );
+}
+
 async function cmdPush(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "push");
   let to = null;
   let at = null;
   let replace = false;
   let slides = null;
+  let acceptConversions = false;
+  let force = false;
   for (let i = 0; i < passthrough.length; i++) {
     const a = passthrough[i];
     if (a === "--to") {
@@ -2823,6 +4161,10 @@ async function cmdPush(rest) {
       at = n;
     } else if (a === "--replace") {
       replace = true;
+    } else if (a === "--accept-conversions") {
+      acceptConversions = true;
+    } else if (a === "--force") {
+      force = true;
     } else if (a === "--slides") {
       const next = passthrough[++i];
       if (!next) fail("--slides expects a comma-separated list of slide ids");
@@ -2851,6 +4193,8 @@ async function cmdPush(rest) {
     insertAt: at,
     replace,
     slideIds: slides,
+    acceptConversions,
+    force,
     onProgress: renderProgressPrinter(),
   });
   for (const w of result.warnings ?? []) {
@@ -3241,7 +4585,35 @@ function extractBackendScope(argv) {
   return out;
 }
 
+// Route every printed byte through the credential scrubber, once, before any
+// command runs. The alternative is scrubbing at ~80 individual write sites
+// across `bin/` and `src/` and remembering to do it at the next one — this way
+// a secret cannot reach a stream no matter who writes it or how it got into the
+// string (a response body used as an error detail, a `--json` payload spread
+// from a server response, an argv echo). Only strings are touched: the CLI
+// writes binary to files, never to a stream, and a non-string chunk passes
+// through untouched regardless.
+function scrubOutputStreams() {
+  for (const stream of [process.stdout, process.stderr]) {
+    const write = stream.write.bind(stream);
+    stream.write = (chunk, ...rest) =>
+      write(typeof chunk === "string" ? scrub(chunk) : chunk, ...rest);
+  }
+}
+
 async function main(rawArgv) {
+  scrubOutputStreams();
+  // A claim pasted WITHOUT the `setup` verb never reaches `decodeSetupClaim`,
+  // so nothing would register it — and `unknown command: <argv>` would print it
+  // whole. Registering straight off argv closes that without the error message
+  // needing to know what a claim is.
+  for (const a of rawArgv) {
+    // The claim, not the whole argument: a user who pastes the entire
+    // `npx … setup smc1_…` line as one word must still have the credential
+    // inside it scrubbed, not just that exact line.
+    const claim = typeof a === "string" ? a.match(/smc1_[A-Za-z0-9_-]+/) : null;
+    if (claim) registerSecret(claim[0]);
+  }
   const argv = extractBackendScope(rawArgv);
   const [cmd, ...rest] = argv;
   if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
@@ -3268,6 +4640,9 @@ async function main(rawArgv) {
     case "build-pptx":
       await cmdBuildPptx(rest);
       return 0;
+    case "inspect-template-deck":
+      await cmdInspectTemplateDeck(rest);
+      return 0;
     case "view-draft":
       await cmdViewDraft(rest);
       return 0;
@@ -3280,6 +4655,9 @@ async function main(rawArgv) {
     case "view-slide":
       await cmdViewSlide(rest);
       return 0;
+    case "read-source":
+      await cmdReadSource(rest);
+      return 0;
     case "insert-slide":
       await cmdInsertSlide(rest);
       return 0;
@@ -3304,6 +4682,9 @@ async function main(rawArgv) {
     case "new":
       await cmdNew(rest);
       return 0;
+    case "login":
+      await cmdLogin(rest);
+      break;
     case "whoami":
       await cmdWhoami(rest);
       break;
@@ -3324,6 +4705,9 @@ async function main(rawArgv) {
     case "read":
       await cmdRead(rest);
       return 0;
+    case "adopt":
+      await cmdAdopt(rest);
+      return 0;
     case "push":
       await cmdPush(rest);
       return 0;