slidemind 0.2.4 → 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,6 +70,7 @@ 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` +
@@ -94,6 +102,7 @@ function printHelp() {
       `                                     --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` +
@@ -146,6 +155,11 @@ function printHelp() {
       `                                     --to <presId>   the window the search ran on (relayed path only; ignored with --from)\n` +
       `                                     --at <N>        numeric prefix to start at (default: append)\n` +
       `                                     --json          machine-readable result (carries the searchId)\n` +
+      `  slidemind adopt <file.pptx>      Rebuild a deck workspace from a file's embedded source; foreign\n` +
+      `                                     slides are converted to editable jsx where the add-in offers it\n` +
+      `                                     --deck <slug>   deck folder to write (default: the file's name)\n` +
+      `                                     --brand <presFP>  design to convert against (when the file names none)\n` +
+      `                                     --no-convert    fold every untagged slide as native .pptx instead\n` +
       `  slidemind download-result [opts] Download image/icon search result(s) into a deck's assets/\n` +
       `                                     --search <id>   searchId from 'slidemind search'\n` +
       `                                     --pick <n,..>   1-based selection number(s)\n` +
@@ -177,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` +
@@ -522,9 +541,12 @@ async function cmdBuildPptx(rest) {
   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") {
@@ -616,6 +638,7 @@ async function cmdBuildPptx(rest) {
     deckDir,
     presentationId: to,
     outPath,
+    force,
     onProgress: renderProgressPrinter(),
   });
   process.stdout.write(
@@ -841,7 +864,7 @@ async function resolveEngineRouting(client, { to = null, brandId = null, pick =
       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 stale snapshot —
+      // 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 });
     }
@@ -882,7 +905,7 @@ async function deckBrandId(deckDir) {
 }
 
 // A pane-ready window, or null — never a throw, and never a wait. Used by the
-// stale-snapshot paths below, where an open pane is an OPTION rather than a
+// 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) {
@@ -897,19 +920,20 @@ async function openPaneEntry(client, to = null) {
   }
 }
 
-// The ONE rendering of a stale permission snapshot. The snapshot is the
-// backend's cached copy of the user's group memberships and it backs the
-// PANE-FREE path only: an open task pane signs every request with a live
-// browser token, which is strictly fresher than any snapshot. So when a
-// pane-ready window is already open, "open the slidemind add-in once" is wrong
-// twice over — it IS open, and that window can serve a fresh search right now.
-// Returns the message, or null when this isn't a stale-snapshot failure.
-async function staleSnapshotMessage(client, err, { to = null } = {}) {
-  const blocker = client.permissionsStaleBlocker?.(err);
+// 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 = pane.entry.env ? ` [${pane.entry.env}]` : "";
+  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}.`
@@ -917,24 +941,23 @@ async function staleSnapshotMessage(client, err, { to = null } = {}) {
 }
 
 // Engine-route failures the USER has to clear get one actionable line instead of
-// a relay error. `permissions_stale` is the search permission snapshot having
-// aged out — the server hands back the exact remediation ("open the slidemind
-// add-in once…"), and only corpus search degrades; render and bundle don't.
+// 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 staleSnapshotMessage(client, err, { to });
+  const message = await loginRequiredMessage(client, err, { to });
   if (message) fail(message);
   throw err;
 }
 
-// A stale snapshot 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
-// staleSnapshotMessage's extended blocker instead. Returns { registry, entry }
-// or null.
-async function paneRelayForStaleSnapshot(client, err, { to = null } = {}) {
-  if (!client.permissionsStaleBlocker?.(err)) return null;
+// 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);
 }
 
@@ -955,6 +978,48 @@ function describeHostOnlyEngineFailure(err) {
   );
 }
 
+// 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;
@@ -1032,7 +1097,7 @@ async function cmdSearch(rest) {
   });
   const presId = routing.presId;
   const backendURL = routing.backendURL;
-  // Mutable, because a stale permission snapshot can push a direct search onto
+  // 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;
@@ -1046,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) {
@@ -1138,16 +1203,15 @@ async function cmdSearch(rest) {
         })
       : await relaySearch(routing.registry);
   } catch (err) {
-    // A stale permission snapshot degrades the PANE-FREE path only — an open
-    // pane signs each request live, which is strictly fresher than the
-    // snapshot. Creating a new search is exactly the operation the pane can
-    // replay (it mints its own searchId), so relay it rather than telling the
-    // user to open an add-in that is already open.
-    const relay = direct ? await paneRelayForStaleSnapshot(client, err, { to }) : null;
+    // 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 environment's search permission snapshot has aged out, so the search ran through the open ` +
-        `slidemind pane${relay.entry.env ? ` [${relay.entry.env}]` : ""} instead (it signs each request live).\n`,
+      `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;
@@ -1241,20 +1305,20 @@ 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}]` : "";
+  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}${envTag} is held by the add-in — reuse it with no PowerPoint window:\n` +
+        `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}${envTag} is held by the add-in — download image result(s) into a deck (no window needed):\n` +
+        `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`,
       );
     }
@@ -1262,7 +1326,7 @@ async function cmdSearch(rest) {
     // 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`,
     );
@@ -1270,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`,
     );
   }
@@ -1390,7 +1454,8 @@ async function cmdLs(rest) {
   // 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 = envs.length > 1 || new Set(engines.map((e) => e.env)).size > 1;
+  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}] ` : "";
@@ -1448,8 +1513,8 @@ function parsePicks(raw, flag = "--pick") {
  * (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 stale permission snapshot is NOT among them: it is authored once, in
- * staleSnapshotMessage, which the caller consults first.
+ * 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;
@@ -1570,7 +1635,7 @@ async function cmdInsertSlide(rest) {
         });
   } catch (err) {
     fail(
-      (await staleSnapshotMessage(client, err, { to: entry.presId })) ??
+      (await loginRequiredMessage(client, err, { to: entry.presId })) ??
         describeInsertSlideFailure(err, searchId),
     );
   }
@@ -1778,7 +1843,7 @@ async function cmdAddSlide(rest) {
           continue;
         } catch (err) {
           fs.rmSync(tempPath, { force: true });
-          const stale = await staleSnapshotMessage(client, err, { to });
+          const stale = await loginRequiredMessage(client, err, { to });
           if (stale) {
             cleanupTemps();
             fail(stale);
@@ -1789,8 +1854,11 @@ async function cmdAddSlide(rest) {
           const routeMissing =
             (err?.status === 404 && !err?.code) || err?.status === 501;
           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}`);
           }
         }
       }
@@ -1997,10 +2065,10 @@ async function cmdReadSource(rest) {
       backendURL: routing.backendURL,
     });
   } catch (err) {
-    // The stale-snapshot line is authored once and knows about an open pane;
+    // The login_required line is authored once and knows about an open pane;
     // everything else is this command's own vocabulary.
     fail(
-      (await staleSnapshotMessage(client, err, { to })) ??
+      (await loginRequiredMessage(client, err, { to })) ??
         describeReadSourceFailure(err, searchId, pick),
     );
   }
@@ -2033,8 +2101,8 @@ async function cmdReadSource(rest) {
 
 /**
  * Turn a source-presentation failure into the action that actually fixes it.
- * A stale permission snapshot is handled one level up, in staleSnapshotMessage
- * — it is the one blocker only the USER can clear and it reads identically
+ * 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) {
@@ -2129,19 +2197,23 @@ async function cmdDownloadResult(rest) {
   // 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.permissionsStaleBlocker?.(r.reason),
+    (r) => r.status === "rejected" && client.loginRequiredBlocker?.(r.reason),
   );
-  if (stale) fail(await staleSnapshotMessage(client, stale.reason, { to }));
-  const results = settled.map((r, i) =>
-    r.status === "fulfilled"
-      ? r.value
-      : {
-          selection: picks[i],
-          error:
-            describeHostOnlyEngineFailure(r.reason) ??
-            r.reason?.message ??
-            String(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
@@ -2227,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`,
@@ -2448,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");
@@ -2594,33 +2668,6 @@ function connectionNextAction(pub) {
   return connectionBlocker(pub)?.message ?? "Ready.";
 }
 
-// The permission SNAPSHOT behind corpus search ages out when nobody opens the
-// add-in for a while. It is a DEGRADATION, never a blocker: render, bundle and
-// every already-materialized asset keep working, only corpus search stops — so
-// it must not sit on either ladder. Newer add-ins report it on the readiness
-// capabilities; the message is authored once, in the client, next to the live
-// 403 shape the engine routes return (client.permissionsStaleBlocker).
-// Which connected environments report an aged-out snapshot on
-// `/api/cli/readiness`. Newer add-ins emit the flag; older ones never do, and
-// there the condition only surfaces as a live 403 on a search.
-function permissionsStaleEnvs(pub) {
-  return (pub.backends ?? [])
-    .filter((b) => b.ok && b.capabilities?.permissionsStale === true)
-    .map((b) => b.env);
-}
-
-function permissionsStaleDegradation(pub, client) {
-  const stale = (pub.backends ?? []).find(
-    (b) => b.ok && b.capabilities?.permissionsStale === true,
-  );
-  if (!stale) return null;
-  const action = stale.capabilities?.permissionsStaleAction;
-  return client.permissionsStaleBlocker({
-    code: "permissions_stale",
-    body: typeof action === "string" ? { action } : {},
-  });
-}
-
 // ---------- one-command setup (npx bootstrap) ----------
 //
 // `npx --yes slidemind@latest setup <claim>` is the whole onboarding: the user
@@ -2642,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];
@@ -2655,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("-")) {
@@ -2689,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
@@ -2780,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
@@ -2812,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) {
@@ -2831,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
@@ -2987,6 +3093,54 @@ async function cmdReady(rest) {
     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
@@ -3009,6 +3163,7 @@ async function cmdReady(rest) {
     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
@@ -3036,6 +3191,7 @@ async function cmdReady(rest) {
             bundleEtag: result.etag ?? null,
             paneSuspended: !paneReady,
             engines: eng,
+            ...(m ? { m365: { signedIn: m.signedIn, degradation: m.degradation } } : {}),
             warnings: result.warnings ?? [],
             nextAction,
           },
@@ -3049,7 +3205,7 @@ async function cmdReady(rest) {
       ? `${designName} (${result.presFP})`
       : result.presFP;
     process.stdout.write(
-      `Ready — design ${designLabel}${env ? ` [${env}]` : ""}${noWindow ? " (no PowerPoint window)" : ""}\n`,
+      `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`);
@@ -3064,6 +3220,7 @@ async function cmdReady(rest) {
             ? "  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`);
     }
@@ -3145,6 +3302,7 @@ async function cmdReady(rest) {
     // below stands.
     if (connectOnly && (await engines()).available) {
       const eng = await engines();
+      const m = await m365();
       if (asJson) {
         process.stdout.write(
           JSON.stringify(
@@ -3153,6 +3311,7 @@ async function cmdReady(rest) {
               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 })),
@@ -3164,8 +3323,9 @@ async function cmdReady(rest) {
       } else {
         process.stdout.write(
           `Connected. ${pub.backendCount} backend(s), 0 window(s) registered — ` +
-            `engine search runs without one [${eng.envs.join(", ")}].\n`,
+            `engine search runs without one${envTag(eng.envs.join(", "))}.\n`,
         );
+        if (m) process.stdout.write(`  ${m.line}\n`);
       }
       return;
     }
@@ -3198,7 +3358,7 @@ async function cmdReady(rest) {
         }
       } else if (brands.length > 1) {
         const rows = brands.map(
-          (b) => `  ${b.presFP}${b.env ? `  [${b.env}]` : ""}  ${b.name ?? ""}`.trimEnd(),
+          (b) => `  ${b.presFP}${envTag(b.env)}  ${b.name ?? ""}`.trimEnd(),
         );
         const blocker = {
           code: "ambiguous_brand",
@@ -3247,6 +3407,7 @@ 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(
@@ -3254,6 +3415,7 @@ async function cmdReady(rest) {
             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 })),
           },
@@ -3266,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;
   }
@@ -3304,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,
@@ -3325,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 ?? "?"})`;
     });
@@ -3378,6 +3541,7 @@ 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(
@@ -3398,6 +3562,14 @@ async function cmdReady(rest) {
           },
           paneSuspended,
           engines: engineInfoForWindow,
+          ...(m365ForWindow
+            ? {
+                m365: {
+                  signedIn: m365ForWindow.signedIn,
+                  degradation: m365ForWindow.degradation,
+                },
+              }
+            : {}),
           warnings: result.warnings ?? [],
           nextAction: "Ready.",
         },
@@ -3409,13 +3581,13 @@ 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`,
   );
@@ -3427,6 +3599,7 @@ async function cmdReady(rest) {
         : "  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`);
   }
@@ -3477,7 +3650,6 @@ async function cmdDoctor(rest) {
   status.authoring = {
     ready: !authoringBlocker,
     blocker: authoringBlocker,
-    degraded: permissionsStaleDegradation(status, client),
     engines,
   };
   const hostBlocker = paneBlocker(status);
@@ -3499,23 +3671,32 @@ async function cmdDoctor(rest) {
     `Backend authoring ready: ${status.authoring.ready ? "yes" : "no"}` +
       `${status.authoring.ready ? "" : ` — ${authoringBlocker.message}`}\n`,
   );
-  // One condition, one cause, named the same way everywhere: when the readiness
-  // capabilities already say the permission snapshot has aged out, this line
-  // says so too, instead of reporting a healthy pane-free surface that a corpus
-  // search is about to 403 on for a reason the user learns only then.
-  const staleEnvs = permissionsStaleEnvs(status);
   process.stdout.write(
     `  engine search (no window needed): ${
       engines.available
-        ? `yes [${engines.envs.join(", ")}]` +
-          (staleEnvs.length
-            ? ` — corpus search degraded on ${staleEnvs.join(", ")}: stale permission snapshot`
-            : "")
+        ? `yes [${engines.envs.join(", ")}]`
         : "no — relayed through an open pane"
     }\n`,
   );
-  if (status.authoring.degraded) {
-    process.stdout.write(`  degraded: ${status.authoring.degraded.message}\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"}` +
@@ -3662,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) => {
@@ -3690,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(
@@ -3730,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`, {
@@ -3738,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`
+        : ""),
   );
 }
 
@@ -3768,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") {
@@ -3788,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");
@@ -3816,6 +4193,8 @@ async function cmdPush(rest) {
     insertAt: at,
     replace,
     slideIds: slides,
+    acceptConversions,
+    force,
     onProgress: renderProgressPrinter(),
   });
   for (const w of result.warnings ?? []) {
@@ -4206,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") {
@@ -4275,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;
@@ -4295,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;