slidemind 0.3.5 → 0.3.13

package/bin/slidemind.mjs

@@ -83,6 +83,7 @@ function printHelp() {
       `                                     --connect-only  check the connection only (no design/bundle)\n` +
       `                                     --json          machine-readable readiness payload\n` +
       `  slidemind new <name>             Scaffold ./decks/<name>/ (auto-binds to the open design)\n` +
+      `                                     --brand <presFP>  bind to a chosen (cached) design instead\n` +
       `                                     --to <presId>   bind to a specific open window\n` +
       `                                     --no-bind       skip the auto-bind\n` +
       `  slidemind plan <deck>            Plan sign-off gate on <deck>/plan.md: opens it in the browser\n` +
@@ -94,6 +95,10 @@ function printHelp() {
       `                                     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` +
+      `                                     --concept <image>[@N,M]  the user's own sketch/mockup IS the\n` +
+      `                                                          mockup for slides N,M (default: all)\n` +
+      `                                     --style <image>[@N,M]    the user's look-and-feel reference,\n` +
+      `                                                          leads the generation (repeatable)\n` +
       `  slidemind build <deck>           Build self-contained HTML\n` +
       `  slidemind review <deck>          Open a spatial preview review; blocks until the user\n` +
       `                                     approves or leaves comments (host-free)\n` +
@@ -171,7 +176,6 @@ function printHelp() {
       `                                     --out <name>    file name under assets/ (default imagen-N.png)\n` +
       `                                     --size <s>      auto|1024x1024|1536x1024|1024x1536 (default auto)\n` +
       `                                     --quality <q>   low|medium|high|auto\n` +
-      `                                     --brand-style   condition on the CD's reference samples\n` +
       `  slidemind download-bundle [deck] Materialize the active corporate design's bundle locally\n` +
       `                                     --to <presId>   target a specific window\n` +
       `                                     --force         re-download even if the cached bundle is current\n` +
@@ -221,6 +225,23 @@ function fail(msg, code = 1) {
   process.exit(code);
 }
 
+// The two human checkmarks the CLI enforces itself, so no harness timeout,
+// context loss, or agent rationalisation can walk past a gate: nothing after
+// the plan gate (concepts, build, view-draft, review) runs on an unapproved or
+// since-edited plan, and nothing ships (push, build-pptx) from a preview the
+// user has not approved exactly as it stands. Both fast-fail before any
+// bridge call with the command that clears them.
+async function requirePlanApproved(deckDir) {
+  const plan = await import(pathToFileURL(path.join(BUILDERS_DIR, "plan.mjs")).href);
+  const why = plan.requirePlanApproved(deckDir);
+  if (why) fail(why);
+}
+async function requireReviewApproved(deckDir) {
+  const review = await import(pathToFileURL(path.join(BUILDERS_DIR, "review.mjs")).href);
+  const why = review.requireReviewApproved(deckDir);
+  if (why) fail(why);
+}
+
 // The local PowerPoint files `read` and `add-slide --from` accept host-free.
 // All are OPC (zip) OOXML packages with the same ppt/presentation.xml +
 // ppt/slides/ structure — presentation (.pptx/.pptm), template (.potx/.potm),
@@ -287,6 +308,78 @@ function readDesignName(bundleDir) {
   }
 }
 
+// The slide master's theme colours, from the one line design.md carries them
+// on (`Theme colors: dk1=#000000, lt1=#FFFFFF, …, accent1=#0000FF, …`). This
+// is what lets the agent SHOW a design to the user instead of naming it —
+// {dk1, lt1, dk2, lt2, accent1..6} → "#RRGGBB", or null when the bundle has
+// no such line.
+function readThemeColors(bundleDir) {
+  if (!bundleDir) return null;
+  try {
+    const md = fs.readFileSync(path.join(bundleDir, "design.md"), "utf8");
+    const line = md.split("\n").find((l) => /^\s*Theme colors:/i.test(l));
+    if (!line) return null;
+    const colors = {};
+    for (const [, key, hex] of line.matchAll(/(\w+)=(#[0-9a-fA-F]{6})/g)) {
+      colors[key] = hex.toUpperCase();
+    }
+    return Object.keys(colors).length ? colors : null;
+  } catch {
+    return null;
+  }
+}
+
+// Every design materialized on this machine, the way `ready` reports it: name
+// + theme colours per design so the agent can put the choice to the user when
+// more than one is at hand. `current` marks the one this run resolved.
+function cachedDesigns(bundle, currentPresFP) {
+  return bundle.listCachedBundles().map((b) => ({
+    presFP: b.presFP,
+    name: readDesignName(b.dir),
+    colors: readThemeColors(b.dir),
+    current: b.presFP === currentPresFP,
+  }));
+}
+
+// One menu row per design: id, name, theme swatch, and the verified windows
+// open on it. `(not cached)` marks a design only a window or the backend knows.
+function designRows(designs) {
+  return designs.map((d) => {
+    const c = d.colors ?? {};
+    const swatch = ["accent1", "accent2", "dk1", "lt1"]
+      .filter((k) => c[k])
+      .map((k) => `${k} ${c[k]}`)
+      .join(", ");
+    const open = (d.windows ?? [])
+      .map((w) => `${w.title || w.fileName || "(untitled)"}${envTag(w.env)}`)
+      .join(", ");
+    return (
+      `  ${d.current ? "*" : " "} ${d.presFP}  ${d.name ?? "(unnamed)"}` +
+      `${swatch ? `  [${swatch}]` : ""}` +
+      `${d.cached === false ? "  (not cached)" : ""}` +
+      `${open ? `  open: ${open}` : ""}`
+    );
+  });
+}
+
+function designsHumanLines(designs) {
+  if (designs.length < 2) return "";
+  return (
+    `  ${designs.length} designs at hand — ask the user which to build against (* = current):\n` +
+    `${designRows(designs).join("\n")}\n` +
+    "  Switch with: slidemind ready [deck] --brand <presFP>\n"
+  );
+}
+
+function windowsHumanLine(windows) {
+  if (windows.length === 0) return "";
+  const rows = windows.map(
+    (w) =>
+      `${w.title || w.fileName || "(untitled)"}${envTag(w.env)}${w.paneReady ? "" : " (suspended)"}`,
+  );
+  return `  windows: ${rows.join(", ")}\n`;
+}
+
 function runNode(script, args) {
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [script, ...args], {
@@ -320,11 +413,9 @@ function splitDeckArg(rest, cmd) {
 
 async function cmdBuild(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "build");
-  await runNode(path.join(BUILDERS_DIR, "build.mjs"), [
-    "--deck",
-    resolveDeckArg(deck),
-    ...passthrough,
-  ]);
+  const deckDir = resolveDeckArg(deck);
+  await requirePlanApproved(deckDir);
+  await runNode(path.join(BUILDERS_DIR, "build.mjs"), ["--deck", deckDir, ...passthrough]);
 }
 
 async function cmdPlan(rest) {
@@ -338,11 +429,9 @@ async function cmdPlan(rest) {
 
 async function cmdReview(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "review");
-  await runNode(path.join(BUILDERS_DIR, "review.mjs"), [
-    "--deck",
-    resolveDeckArg(deck),
-    ...passthrough,
-  ]);
+  const deckDir = resolveDeckArg(deck);
+  await requirePlanApproved(deckDir);
+  await runNode(path.join(BUILDERS_DIR, "review.mjs"), ["--deck", deckDir, ...passthrough]);
 }
 
 // Live render progress for build-pptx/push (the job protocol streams it; the
@@ -381,7 +470,6 @@ async function cmdImagen(rest) {
   let outName = null;
   let size = null;
   let quality = null;
-  let brandStyle = false;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--deck") {
@@ -400,8 +488,6 @@ async function cmdImagen(rest) {
       if (!["low", "medium", "high", "auto"].includes(quality ?? "")) {
         fail("--quality expects low|medium|high|auto");
       }
-    } else if (a === "--brand-style") {
-      brandStyle = true;
     } else if (a.startsWith("-")) {
       fail(`unknown flag: ${a}`);
     } else if (prompt === null) {
@@ -413,7 +499,7 @@ async function cmdImagen(rest) {
   if (!prompt || !prompt.trim() || !deck) {
     fail(
       'usage: slidemind imagen "<prompt>" --deck <deck> [--out <name.png>] ' +
-        "[--size auto|1024x1024|1536x1024|1024x1536] [--quality low|medium|high|auto] [--brand-style]",
+        "[--size auto|1024x1024|1536x1024|1024x1536] [--quality low|medium|high|auto]",
     );
   }
   const deckDir = resolveDeckArg(deck);
@@ -437,7 +523,6 @@ async function cmdImagen(rest) {
       prompt,
       size,
       quality,
-      brandStyle,
     });
   } catch (err) {
     if (err?.code === "imagen_route_unavailable") {
@@ -462,9 +547,8 @@ async function cmdImagen(rest) {
   }
   const outPath = path.join(assetsDir, file);
   fs.writeFileSync(outPath, Buffer.from(m[2], "base64"));
-  const styled = result.styleReferences > 0 ? ` (styled on ${result.styleReferences} brand sample(s))` : "";
   process.stdout.write(
-    `Wrote ${path.relative(process.cwd(), outPath)}${styled}\n` +
+    `Wrote ${path.relative(process.cwd(), outPath)}\n` +
       `  Reference it from slide props as "assets/${file}" (e.g. summaryImage, illustration).\n`,
   );
 }
@@ -579,6 +663,9 @@ async function cmdBuildPptx(rest) {
   if (packDir && deckMode.mode !== "fill-template") {
     fail(`explicit --pack ${path.resolve(packDir)} is mode ${deckMode.mode}, not fill-template`);
   }
+  // Template packs have no HTML preview to review and carry their own plan
+  // sign-off; compose decks ship only from an approved, unchanged preview.
+  if (deckMode.mode !== "fill-template") await requireReviewApproved(deckDir);
   if (deckMode.mode === "fill-template") {
     const skill = resolveMod.resolveSkillForDeck(deckDir, resolveOpts);
     if (to) {
@@ -683,6 +770,7 @@ async function cmdViewDraft(rest) {
   if (!fs.existsSync(path.join(deckDir, "slides"))) {
     fail(`expected 'slides/' folder in ${deckDir}`);
   }
+  await requirePlanApproved(deckDir);
   // Draft previews are produced locally by the add-in's shipped capture engine
   // (no push, no .pptx) — the same module that hosts the render+push path.
   const mod = await import(
@@ -1106,13 +1194,16 @@ async function cmdSearch(rest) {
 
   // An explicit content/visual intent means "search slides", not imagery.
   const slideIntent = intent === "content" || intent === "visual";
-  // Thread the engine subtype on the wire whenever the CLI can determine it:
-  //   - the pickImageEngine default branch is, by construction, an image engine;
-  //   - 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 the caller's groups itself.
-  let subtype = slideIntent ? "slide" : null;
+  // Thread the engine subtype on the wire only when the CLI actually KNOWS it:
+  // `--intent content` is slide-only by contract (image engines are
+  // visual-only), the pickImageEngine default branch is an image engine by
+  // construction, and a scope search names its index below. `--intent visual`
+  // asserts NOTHING — it is a valid intent for image AND slide engines, and
+  // asserting "slide" from it made the backend record an icon-engine search
+  // as slide results (the footer then taught add-slide instead of
+  // download-result). Omitted subtype → the backend derives it from what the
+  // results actually are.
+  let subtype = intent === "content" ? "slide" : null;
   // `--engine Icons` — a display name straight off `ls engines` — would reach
   // the backend verbatim and 404 as "Engine not found". Humans type names,
   // agents paste ids; when the value cannot be an id (spaces, non-hex), look it
@@ -1327,11 +1418,16 @@ async function cmdSearch(rest) {
     }
   }
   // Tailor the next-step hint to the result kind: slide verbs (insert-slide /
-  // add-slide) for slide results, the image-download hint otherwise. The result
-  // subtype is authoritative; fall back to a per-result `kind` for older
-  // add-ins that don't echo a top-level subtype.
-  const isSlideResults =
-    res.subtype === "slide" || results.some((r) => r.kind === "slide");
+  // add-slide) for slide results, the image-download hint otherwise. The
+  // per-result `kind`s are authoritative — the top-level subtype echo has been
+  // observed WRONG on live backends (icon-engine searches echoing
+  // subtype:"slide" over kind:"image" results, which pointed agents at
+  // add-slide instead of download-result) — with the subtype as the fallback
+  // for add-ins that don't stamp per-result kinds.
+  const resultKinds = results.map((r) => r.kind).filter(Boolean);
+  const isSlideResults = resultKinds.length
+    ? resultKinds.some((k) => k === "slide")
+    : res.subtype === "slide";
   const envLabel = envTag(ranEntry?.env);
   if (direct) {
     // The searchId belongs to the BACKEND here, not to a window: picks work with
@@ -1346,7 +1442,7 @@ async function cmdSearch(rest) {
     } 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`,
+          `  slidemind download-result --search ${res.searchId} --pick <n[,n,...]> --deck <deck> [--icon-color "#0A7E8C"]\n`,
       );
     }
   } else if (isSlideResults) {
@@ -1362,7 +1458,7 @@ async function cmdSearch(rest) {
     // target that same window, so spell out its presId in the next-step command.
     process.stdout.write(
       `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`,
+        `  slidemind download-result --search ${res.searchId} --pick <n[,n,...]> --deck <deck> --to ${ranPresId} [--icon-color "#0A7E8C"]\n`,
     );
   }
 }
@@ -2282,13 +2378,62 @@ function base64FromDataUri(dataUri) {
   return m ? m[1] : null;
 }
 
+const REFERENCE_MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+};
+
+// `--concept <image>[@N,M]` / `--style <image>[@N,M]` → one inline reference
+// `{ role, image, slides?, name }` for the concept-images route.
+function readReferenceArg(role, spec) {
+  if (!spec) fail(`--${role} expects <image>[@slides]`);
+  const at = spec.lastIndexOf("@");
+  const file = at > 0 ? spec.slice(0, at) : spec;
+  const slides =
+    at > 0
+      ? spec
+          .slice(at + 1)
+          .split(",")
+          .map((n) => Number(n.trim()))
+          .filter((n) => Number.isInteger(n) && n > 0)
+      : [];
+  if (at > 0 && slides.length === 0) {
+    fail(`--${role} ${spec}: expected slide numbers after '@', e.g. sketch.png@2,3`);
+  }
+  const mime = REFERENCE_MIME[path.extname(file).toLowerCase()];
+  if (!mime) fail(`--${role} ${file}: expected a png/jpg/webp/gif image`);
+  let bytes;
+  try {
+    bytes = fs.readFileSync(file);
+  } catch {
+    fail(`--${role} ${file}: file not found`);
+  }
+  return {
+    role,
+    image: `data:${mime};base64,${bytes.toString("base64")}`,
+    ...(slides.length > 0 ? { slides } : {}),
+    name: path.basename(file),
+  };
+}
+
 async function cmdConceptImages(rest) {
   let deck = null;
+  let force = false;
+  const references = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--deck") {
       deck = rest[++i];
       if (!deck) fail("--deck expects a deck name or path");
+    } else if (a === "--force") {
+      force = true;
+    } else if (a === "--concept" || a === "--style") {
+      references.push(readReferenceArg(a.slice(2), rest[++i]));
+      // A new user reference changes what the mockups should be.
+      force = true;
     } else if (a.startsWith("-")) {
       fail(`unknown flag: ${a}`);
     } else if (deck === null) {
@@ -2308,6 +2453,58 @@ async function cmdConceptImages(rest) {
     );
   }
   const planMarkdown = fs.readFileSync(planPath, "utf8");
+  // Mockups are the first post-plan step, so this is where an unapproved or
+  // since-edited plan stops the agent — before any authoring, and before the
+  // fast path below re-prints mockups that would belong to a stale plan.
+  await requirePlanApproved(deckDir);
+
+  // The slides the plan's storyboards name — the set every step below works
+  // against (fast-path completeness, request waves, pruning, the missing
+  // note). The server's slideCount is a progress figure only: it counts the
+  // beats IT parsed, and a beat it drops must not shrink the request range.
+  const families = await import(
+    pathToFileURL(path.join(BUILDERS_DIR, "visual-families.mjs")).href
+  );
+  const planned = new Set(families.plannedSlideNumbers(planMarkdown));
+
+  // Idempotent fast path: mockups already on disk are re-printed IMMEDIATELY.
+  // Generation takes 1-2 minutes and agent harnesses time commands out and
+  // show the model only the output-so-far — while the detached process still
+  // finishes writing the PNGs. The model's mandated retry then lands here and
+  // gets the full path list within any timeout, instead of racing generation
+  // again (measured: sessions that never saw the paths authored without the
+  // concepts — the single biggest fidelity loss). `--force` regenerates.
+  if (!force) {
+    const conceptsDirEarly = path.join(deckDir, "concepts");
+    let existing = [];
+    try {
+      existing = fs
+        .readdirSync(conceptsDirEarly)
+        .filter((f) => /^concept-slide-\d+\.png$/.test(f))
+        .sort();
+    } catch {}
+    // Only when the on-disk set EXACTLY matches the plan's slide numbering —
+    // a partial or stale set (leftover concept-slide-03.png on a 2-slide
+    // plan) falls through to regeneration, which prunes and refills.
+    const existingNums = new Set(
+      existing.map((f) => Number(f.match(/(\d+)/)[1])),
+    );
+    const matchesPlan =
+      planned.size > 0 &&
+      planned.size === existingNums.size &&
+      [...planned].every((n) => existingNums.has(n));
+    if (existing.length > 0 && matchesPlan) {
+      for (const f of existing) {
+        process.stdout.write(path.join(conceptsDirEarly, f) + "\n");
+      }
+      process.stdout.write(
+        `${existing.length} concept mockup(s) already in ${conceptsDirEarly} — ` +
+          "Read each, then rebuild as slide JSX (workflow/create.md → Preconditions). " +
+          "Pass --force to regenerate from the current plan.\n",
+      );
+      return;
+    }
+  }
 
   const bundle = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
@@ -2320,21 +2517,6 @@ async function cmdConceptImages(rest) {
     );
   }
 
-  // Plan sign-off is advisory here, not a hard gate: warn but proceed if the
-  // plan wasn't approved, so an agent can still fetch mockups while iterating.
-  const plan = await import(
-    pathToFileURL(path.join(BUILDERS_DIR, "plan.mjs")).href
-  );
-  const planState = plan.loadPlanState(deckDir);
-  // "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`,
-    );
-  }
-
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
@@ -2347,12 +2529,22 @@ async function cmdConceptImages(rest) {
     process.exit(0);
   };
 
+  // Generation is silent for 1–2 min otherwise, and a harness that yields a
+  // long-running command early then hands the agent an empty output it reads
+  // as "no mockups". Say up front what is happening and what to wait for.
+  process.stderr.write(
+    `slidemind: generating concept mockups for ${deck} — this takes 1–2 minutes. ` +
+      `Wait for the concept-slide-NN.png paths below; an empty output so far means still running, ` +
+      `not "no mockups". Do not re-run this command while it is still running.\n`,
+  );
+
   // First request learns slideCount (and pins the serving backend for the rest).
   let first;
   try {
     first = await client.generateConceptImagesForBrand(brandId, {
       planMarkdown,
       slideNumbers: [1],
+      references,
     });
   } catch (err) {
     if (err?.code === "concept_route_unavailable") skipNote();
@@ -2363,16 +2555,19 @@ async function cmdConceptImages(rest) {
   const slideCount = Number.isFinite(first.slideCount) ? first.slideCount : 0;
   const images = [];
   const collect = (res) => {
-    if (Array.isArray(res?.images)) images.push(...res.images);
+    if (!Array.isArray(res?.images)) return;
+    for (const img of res.images) {
+      images.push(img);
+      process.stderr.write(
+        `slidemind: concept mockup ${images.length}/${slideCount} ready (slide ${img?.slideNumber})\n`,
+      );
+    }
   };
   collect(first);
 
   // Family variants depend on their lowest-numbered anchor. Run independent
   // slides + anchors first, then variants; the server cache remains a safety
   // net for older clients and retries.
-  const families = await import(
-    pathToFileURL(path.join(BUILDERS_DIR, "visual-families.mjs")).href
-  );
   const waves = families.conceptGenerationWaves(planMarkdown, slideCount);
   const CONCURRENCY = 3;
   async function runWave(slides) {
@@ -2386,6 +2581,7 @@ async function cmdConceptImages(rest) {
           const res = await client.generateConceptImagesForBrand(brandId, {
             planMarkdown,
             slideNumbers: [n],
+            references,
             backendURL,
           });
           collect(res);
@@ -2413,6 +2609,7 @@ async function cmdConceptImages(rest) {
   const conceptsDir = path.join(deckDir, "concepts");
   fs.mkdirSync(conceptsDir, { recursive: true });
   const written = [];
+  const writtenNums = new Set();
   for (const img of images) {
     const n = Number(img?.slideNumber);
     if (!Number.isFinite(n) || n < 1) continue;
@@ -2422,16 +2619,28 @@ async function cmdConceptImages(rest) {
     const abs = path.join(conceptsDir, name);
     fs.writeFileSync(abs, Buffer.from(b64, "base64"));
     written.push(abs);
+    writtenNums.add(n);
   }
 
   // Drop stale mockups from a previous, longer plan — any concept-slide-NN.png
-  // whose slide number now exceeds the plan's slideCount.
+  // the plan no longer names (fallback: beyond the server's slideCount).
+  const isStale = (n) =>
+    planned.size > 0 ? !planned.has(n) : n > slideCount;
   for (const entry of fs.readdirSync(conceptsDir)) {
     const m = /^concept-slide-(\d+)\.png$/.exec(entry);
-    if (m && Number(m[1]) > slideCount) {
+    if (m && isStale(Number(m[1]))) {
       fs.rmSync(path.join(conceptsDir, entry), { force: true });
     }
   }
+  // A planned slide the server returned nothing for is invisible otherwise —
+  // the agent would author it blind without knowing a mockup was expected.
+  const missing = [...planned].filter((n) => !writtenNums.has(n));
+  if (missing.length > 0) {
+    process.stderr.write(
+      `slidemind: no concept mockup returned for slide${missing.length > 1 ? "s" : ""} ` +
+        `${missing.join(", ")} — author ${missing.length > 1 ? "those" : "it"} from the storyboard.\n`,
+    );
+  }
 
   if (written.length === 0) {
     process.stdout.write(
@@ -2580,6 +2789,8 @@ function publicConnectionStatus(status, client) {
       minCliVersion: b.minCliVersion ?? null,
       cliUpdateRequired: b.cliUpdateRequired === true,
       error: b.error,
+      code: b.code ?? null,
+      status: b.status ?? null,
       summary: b.summary ?? null,
       presentations: (b.presentations ?? []).map(client.toPublicPresentation),
     })),
@@ -2612,6 +2823,22 @@ function backendBlocker(pub) {
     };
   }
   if ((pub.backends ?? []).every((b) => !b.ok)) {
+    // Something answered 503 (already retried by the probe): the add-in whose
+    // session store did not answer (code `backend_unavailable`), or a proxy in
+    // front of it with no machine code at all. The session is intact, so the
+    // remedy is to wait — never to re-pair, which is what the generic wording
+    // below invites. Same predicate as the probe's retry.
+    const unavailable = (b) =>
+      b.code === "backend_unavailable" || (b.status === 503 && b.code !== "pane_suspended");
+    if ((pub.backends ?? []).every(unavailable)) {
+      return {
+        code: "backend_unavailable",
+        actor: "agent",
+        message:
+          "The add-in backend is temporarily unavailable (its session store did not answer). " +
+          "Wait a minute and run `slidemind ready` again; the CLI session itself is fine, do not reconnect.",
+      };
+    }
     return {
       code: "all_unreachable",
       actor: "user",
@@ -2773,12 +3000,12 @@ async function cmdSetup(rest) {
   // `upsertSession` below changes the count.
   const showEnv = cfg.readSessions().length > 0;
   await ui.section("connect", showEnv ? envLabel : "");
-  const sessionToken = await claims.redeemSetupClaim({
+  const { sessionToken, oid } = await claims.redeemSetupClaim({
     backendURL,
     secret,
     cliVersion: pkg.version,
   });
-  cfg.upsertSession({ backendURL, sessionToken, label: envLabel });
+  cfg.upsertSession({ backendURL, sessionToken, label: envLabel, oid });
   ui.step({
     label: "authorize",
     value: showEnv ? envLabel : "connected",
@@ -3168,6 +3395,91 @@ async function cmdReady(rest) {
     return m365Info;
   };
 
+  const isRR = client.isRenderReadyPresentation;
+
+  // The render-ready windows as the payloads report them — after the zombie
+  // prune below, so a listed window is one PowerPoint actually has. One row
+  // per window: a presId mirrored across backends is still one window.
+  const publicWindows = () => {
+    const seen = new Set();
+    return registry.filter(isRR).filter((p) => !seen.has(p.presId) && seen.add(p.presId)).map((p) => {
+      const q = client.toPublicPresentation(p);
+      return {
+        presId: q.presId,
+        env: q.env ?? null,
+        title: q.title ?? null,
+        fileName: q.fileName ?? null,
+        presFP: p.brandId ?? null,
+        paneReady: client.isPaneReadyPresentation(p),
+      };
+    });
+  };
+
+  // The design menu: every design at hand — cached here, open in a verified
+  // window, or (when asked) listed by the backend — one row per presFP with
+  // name, theme colours and the windows on it. Success payloads and the
+  // ambiguous blocker report the same shape, so the agent always has the
+  // menu to put to the user.
+  const designMenu = async ({ current = null, withBackend = false } = {}) => {
+    const blank = (presFP) => ({
+      presFP,
+      name: null,
+      colors: null,
+      current: presFP === current,
+      cached: false,
+      windows: [],
+    });
+    const rows = new Map(
+      cachedDesigns(bundle, current).map((d) => [
+        d.presFP,
+        { ...d, cached: true, windows: [] },
+      ]),
+    );
+    for (const w of publicWindows()) {
+      if (!w.presFP) continue;
+      if (!rows.has(w.presFP)) rows.set(w.presFP, blank(w.presFP));
+      rows.get(w.presFP).windows.push(w);
+    }
+    if (withBackend) {
+      try {
+        for (const b of await client.listBrands()) {
+          if (!rows.has(b.presFP)) rows.set(b.presFP, blank(b.presFP));
+          rows.get(b.presFP).name ??= b.name ?? null;
+        }
+      } catch {
+        /* no brand list — the menu is what this machine knows */
+      }
+    }
+    return [...rows.values()];
+  };
+
+  // The one question ready cannot answer: several designs at hand and neither
+  // a deck binding, a --brand, nor a single verified window says which.
+  const finishAmbiguous = async () => {
+    const designs = await designMenu({ withBackend: true });
+    const suggested =
+      deckPresFP && designs.some((d) => d.presFP === deckPresFP) ? deckPresFP : null;
+    const rerun = `slidemind ready${deckSlug ? ` ${deckSlug}` : ""} --brand <presFP>`;
+    const blocker = {
+      code: "ambiguous_design",
+      actor: "user",
+      message: `Several corporate designs are at hand and nothing says which — ask the user which to build against (by name and colours), then re-run: ${rerun}.`,
+    };
+    let human =
+      "slidemind: several corporate designs are at hand — ask the user which to build against:\n" +
+      `${designRows(designs).join("\n")}\n`;
+    if (suggested) {
+      const s = designs.find((d) => d.presFP === suggested);
+      human += `  (this deck was last built against ${s?.name ?? suggested} (${suggested}))\n`;
+    }
+    human += `Then re-run: ${rerun}`;
+    finishBlocker({
+      blocker,
+      extras: { designs, suggested, windows: publicWindows() },
+      humanLines: human,
+    });
+  };
+
   // --- 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
@@ -3214,6 +3526,8 @@ async function cmdReady(rest) {
             presId: null,
             presFP: result.presFP,
             designName,
+            designs: await designMenu({ current: result.presFP }),
+            windows: publicWindows(),
             bundleDir: result.dir,
             bundleEtag: result.etag ?? null,
             paneSuspended: !paneReady,
@@ -3236,6 +3550,8 @@ async function cmdReady(rest) {
     );
     process.stdout.write(`  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`);
     if (deckDir) process.stdout.write(`  deck ${deckSlug} bound\n`);
+    process.stdout.write(windowsHumanLine(publicWindows()));
+    process.stdout.write(designsHumanLines(await designMenu({ current: result.presFP })));
     process.stdout.write(
       noWindow
         ? eng.available
@@ -3283,8 +3599,6 @@ async function cmdReady(rest) {
     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
@@ -3371,48 +3685,35 @@ async function cmdReady(rest) {
         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) {
+    // --- Unbound + no window: the ONE design cached here is the answer, else
+    // the ONE design the backend lists; several of either genuinely need a
+    // human choice, which --brand records. A backend without the brand route
+    // (or a deck already bound to a design it just refused) falls through
+    // unchanged — as does a connection with every backend down, where a
+    // design menu would only hide the real blocker. ---
+    if (!connectOnly && !to && !deckPresFP && !boundRungTried && !backendBlocker(pub)) {
+      const cached = bundle.listCachedBundles();
+      if (cached.length === 1) {
+        const result = await materializeBrand(cached[0].presFP);
+        if (result) {
+          await finishWindowless(result);
+          return;
+        }
+      }
       let brands = [];
       try {
         brands = await client.listBrands();
       } catch {
         /* no brand list — the window ladder below is the answer */
       }
-      if (brands.length === 1) {
+      if (cached.length === 0 && brands.length === 1) {
         const result = await materializeBrand(brands[0].presFP);
         if (result) {
           await finishWindowless(result);
           return;
         }
-      } else if (brands.length > 1) {
-        const rows = brands.map(
-          (b) => `  ${b.presFP}${envTag(b.env)}  ${b.name ?? ""}`.trimEnd(),
-        );
-        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>`,
-        });
+      } else if (cached.length > 1 || brands.length > 1) {
+        await finishAmbiguous();
         return;
       }
     }
@@ -3435,6 +3736,49 @@ async function cmdReady(rest) {
     finishBlocker({ blocker: b });
     return;
   };
+  // --- Zombie prune, BEFORE any resolution: a webview whose document was
+  // closed keeps its socket — and thus a "connected" registry lease — alive
+  // indefinitely, and only a host round-trip inside the pane can tell. Every
+  // window claiming a LIVE pane gets one truth ping (in parallel); a dead one
+  // leaves the registry, so it can neither win silently nor fake a second
+  // design. Narrow on purpose: an explicit --to is the user's call, a
+  // suspended window keeps its silent-adopt semantics (backgrounded
+  // PowerPoint must not start asking questions), and a backend without
+  // paneLivenessV1 fails open. ---
+  const backendAdvertisesPing = (entry) =>
+    (statusRaw.backends ?? []).some(
+      (b) =>
+        b.ok &&
+        b.backendURL === entry.backendURL &&
+        b.capabilities?.paneLivenessV1 === true,
+    );
+  const entryIsAlive = async (entry) => {
+    try {
+      const ack = await client.pingPresentation({
+        presId: entry.presId,
+        backendURL: entry.backendURL ?? null,
+      });
+      return ack?.ok !== false;
+    } catch (err) {
+      // Dead only on the typed pane verdicts; anything else (404 route on an
+      // older backend, a transport blip) fails open — adopt as before.
+      return ![
+        "pane_suspended",
+        "pane_timeout",
+        "pane_disconnected",
+        "bridge_timeout",
+      ].includes(err?.code);
+    }
+  };
+  if (!to) {
+    const suspects = registry.filter(
+      (p) => isRR(p) && client.isPaneReadyPresentation(p) && backendAdvertisesPing(p),
+    );
+    const alive = await Promise.all(suspects.map(entryIsAlive));
+    const dead = new Set(suspects.filter((_, i) => !alive[i]));
+    if (dead.size > 0) registry = registry.filter((p) => !dead.has(p));
+  }
+
   if (!registry.some(isRR)) {
     await finishNoRenderReady();
     return;
@@ -3469,64 +3813,33 @@ async function cmdReady(rest) {
     return;
   }
 
-  // --- Local: resolve WHICH design to bind against. ---
-  let resolution = client.resolveDesignSource(registry, {
-    explicitPresId: to,
-    deckPresFP,
-  });
-
-  // --- Zombie check: an implicitly adopted window that claims a LIVE pane gets
-  // one truth ping before its design silently wins. A webview whose document
-  // was closed keeps its socket — and thus a "connected" registry lease —
-  // alive indefinitely, and only a host round-trip inside the pane can tell.
-  // Narrow on purpose: an explicit --to is the user's call, a suspended window
-  // keeps today's silent-adopt semantics (backgrounded PowerPoint must not
-  // start asking questions), and a backend without paneLivenessV1 fails open.
-  // A dead window is pruned and resolution re-runs on the remainder; pruning
-  // the last one lands on the same rungs as an empty registry (bound deck →
-  // brand list → blocker). ---
-  const backendAdvertisesPing = (entry) =>
-    (statusRaw.backends ?? []).some(
-      (b) =>
-        b.ok &&
-        b.backendURL === entry.backendURL &&
-        b.capabilities?.paneLivenessV1 === true,
-    );
-  const entryIsAlive = async (entry) => {
-    try {
-      const ack = await client.pingPresentation({
-        presId: entry.presId,
-        backendURL: entry.backendURL ?? null,
-      });
-      return ack?.ok !== false;
-    } catch (err) {
-      // Dead only on the typed pane verdicts; anything else (404 route on an
-      // older backend, a transport blip) fails open — adopt as before.
-      return ![
-        "pane_suspended",
-        "pane_timeout",
-        "pane_disconnected",
-        "bridge_timeout",
-      ].includes(err?.code);
-    }
-  };
-  while (
-    !to &&
-    resolution.status === "resolved" &&
-    client.isPaneReadyPresentation(resolution.entry) &&
-    backendAdvertisesPing(resolution.entry)
-  ) {
-    if (await entryIsAlive(resolution.entry)) break;
-    const deadId = resolution.entry.presId;
-    registry = registry.filter((p) => p.presId !== deadId);
-    if (!registry.some(isRR)) {
-      await finishNoRenderReady();
-      return;
-    }
+  // --- Local: pick WHICH design. The order is the user's, not the window's:
+  // an explicit --to, else the deck's own binding (a window on that design is
+  // targeted, none at all readies windowless over the brand route), else the
+  // ONE design the verified windows agree on. Anything else is a choice only
+  // the user can make — the ambiguous blocker puts the menu in front of them. ---
+  let resolution;
+  if (to) {
     resolution = client.resolveDesignSource(registry, {
       explicitPresId: to,
       deckPresFP,
     });
+  } else {
+    const onDeckDesign = deckPresFP
+      ? registry.filter((p) => isRR(p) && p.brandId === deckPresFP)
+      : [];
+    if (boundDeckLadder && onDeckDesign.length === 0) {
+      boundRungTried = true;
+      const result = await materializeBrand(deckPresFP);
+      if (result) {
+        await finishWindowless(result);
+        return;
+      }
+    }
+    resolution = client.resolveDesignSource(
+      onDeckDesign.length > 0 ? onDeckDesign : registry,
+      { deckPresFP },
+    );
   }
 
   if (resolution.status === "none") {
@@ -3570,41 +3883,7 @@ async function cmdReady(rest) {
   }
 
   if (resolution.status === "ambiguous") {
-    const cand = resolution.candidates;
-    const blocker = {
-      code: "ambiguous_design",
-      actor: "user",
-      message:
-        "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 = envTag(c.env) ? ` ${envTag(c.env)}` : "";
-      const label = c.title || c.fileName || "(untitled)";
-      return `  ${c.presId}${env}  ${label}    (design ${c.brandId ?? "?"})`;
-    });
-    let human =
-      "slidemind: multiple corporate designs are open — ask the user which to build against:\n" +
-      `${rows.join("\n")}\n`;
-    if (resolution.suggested) {
-      const s = cand.find((c) => c.presId === resolution.suggested);
-      const sLabel = s?.title || s?.fileName || "(untitled)";
-      human += `(this deck was last built against ${s?.brandId ?? deckPresFP} — ${sLabel})\n`;
-    }
-    human += "Then re-run: slidemind ready --to <presId>";
-    finishBlocker({
-      blocker,
-      extras: {
-        candidates: cand.map((c) => ({
-          presId: c.presId,
-          env: c.env ?? null,
-          title: c.title ?? null,
-          fileName: c.fileName ?? null,
-          presFP: c.brandId ?? null,
-        })),
-        suggested: resolution.suggested,
-      },
-      humanLines: human,
-    });
+    await finishAmbiguous();
     return;
   }
 
@@ -3644,6 +3923,8 @@ async function cmdReady(rest) {
           presId: entry.presId,
           presFP: result.presFP,
           designName,
+          designs: await designMenu({ current: result.presFP }),
+          windows: publicWindows(),
           bundleDir: result.dir,
           bundleEtag: result.etag ?? null,
           presentation: {
@@ -3682,6 +3963,8 @@ async function cmdReady(rest) {
     `  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`,
   );
   if (bound) process.stdout.write(`  deck ${deckSlug} bound\n`);
+  process.stdout.write(windowsHumanLine(publicWindows()));
+  process.stdout.write(designsHumanLines(await designMenu({ current: result.presFP })));
   if (paneSuspended) {
     process.stdout.write(
       engineInfoForWindow.available
@@ -4273,6 +4556,7 @@ async function cmdPush(rest) {
   if (!fs.existsSync(path.join(deckDir, "slides"))) {
     fail(`expected 'slides/' folder in ${deckDir}`);
   }
+  await requireReviewApproved(deckDir);
 
   const mod = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "build-and-push.mjs")).href
@@ -4309,6 +4593,7 @@ async function cmdPush(rest) {
 
 async function cmdNew(rest) {
   let to = null;
+  let brand = null;
   let noBind = false;
   const positional = [];
   for (let i = 0; i < rest.length; i++) {
@@ -4316,6 +4601,9 @@ async function cmdNew(rest) {
     if (a === "--to") {
       to = rest[++i];
       if (!to) fail("--to expects a presId");
+    } else if (a === "--brand") {
+      brand = rest[++i];
+      if (!brand) fail("--brand expects a design id (presFP)");
     } else if (a === "--no-bind") {
       noBind = true;
     } else if (a.startsWith("-")) {
@@ -4324,8 +4612,11 @@ async function cmdNew(rest) {
       positional.push(a);
     }
   }
+  if (brand && to) {
+    fail("--brand and --to are mutually exclusive (a design id or a window, not both)");
+  }
   const name = positional[0];
-  if (!name) fail("usage: slidemind new <name>");
+  if (!name) fail("usage: slidemind new <name> [--brand <presFP> | --to <presId>] [--no-bind]");
   if (!/^[a-z0-9][a-z0-9-]*$/i.test(name)) {
     fail(`deck name must be kebab-case alphanumerics, got '${name}'`);
   }
@@ -4356,6 +4647,23 @@ async function cmdNew(rest) {
   const cfg = await loadBridgeModule("config");
   if (cfg.readSessions().length === 0) return;
   let boundMsg = null;
+  // --brand: the user picked a design (the Clarify question) — bind to THAT,
+  // never to whatever window happens to be open. Cache-only, so it needs the
+  // bundle `ready` already materialized; a miss names the command that does.
+  if (brand) {
+    const bundle = await loadBridgeModule("bundle");
+    const meta = bundle.readMaterializedBundleMeta(brand);
+    if (!meta?.presFP) {
+      process.stdout.write(
+        `not bound — design '${brand}' is not materialized here; run \`slidemind ready ${name} --brand ${brand}\`\n`,
+      );
+      return;
+    }
+    bundle.writeDeckBundleRef(deckDir, { presFP: meta.presFP, etag: meta.etag ?? null });
+    const label = readDesignName(bundle.bundleDirForPresFP(meta.presFP)) ?? meta.presFP;
+    process.stdout.write(`bound to design ${label}\n`);
+    return;
+  }
   try {
     const client = await import(
       pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
@@ -4367,9 +4675,18 @@ async function cmdNew(rest) {
     const resolution = client.resolveDesignSource(presentations, {
       explicitPresId: to,
     });
-    if (resolution.status === "resolved") {
-      const entry = resolution.entry;
-      const meta = bundle.readMaterializedBundleMeta(entry.brandId);
+    // The same order as ready: the one design open, else the one design
+    // cached here. (No liveness ping — a zombie's false ambiguity just leaves
+    // the deck unbound, and `ready <name>` prunes it.)
+    const cached = bundle.listCachedBundles();
+    const presFP =
+      resolution.status === "resolved"
+        ? resolution.entry.brandId
+        : resolution.status === "none" && !to && cached.length === 1
+          ? cached[0].presFP
+          : null;
+    if (presFP) {
+      const meta = bundle.readMaterializedBundleMeta(presFP);
       if (meta?.presFP) {
         bundle.writeDeckBundleRef(deckDir, {
           presFP: meta.presFP,
@@ -4386,7 +4703,7 @@ async function cmdNew(rest) {
   process.stdout.write(
     boundMsg
       ? `${boundMsg}\n`
-      : `not bound to a design yet — run \`slidemind ready ${name}\` when a window is open\n`,
+      : `not bound to a design yet — run \`slidemind ready ${name}\`\n`,
   );
 }
 
@@ -4693,6 +5010,27 @@ function scrubOutputStreams() {
 
 async function main(rawArgv) {
   scrubOutputStreams();
+  // Simulation-only env bootstrap (scripts/codex-sim.mjs): codex's env
+  // passthrough to spawned shells proved NONDETERMINISTIC per session, and a
+  // session that misses SLIDEMIND_GATE_AUTOAPPROVE runs the plan/review gates
+  // INTERACTIVELY — browser windows on the operator's machine and blocking
+  // waits with no timeout. So the sim runner also drops `.slidemind-sim.json` into
+  // each session workdir (= the CWD of every command the session runs), and
+  // the CLI fills the env from it itself. Real users never have this file;
+  // explicit env always wins.
+  try {
+    const sim = JSON.parse(fs.readFileSync(".slidemind-sim.json", "utf8"));
+    for (const [k, v] of Object.entries(sim.env ?? {})) {
+      // !process.env[k], not === undefined: codex has been observed delivering
+      // an injected var as an EMPTY string, which would win over the marker
+      // and send the gate down the interactive path anyway.
+      if (/^SLIDEMIND_[A-Z_]+$/.test(k) && !process.env[k]) {
+        process.env[k] = String(v);
+      }
+    }
+  } catch {
+    // no sim marker — the normal case
+  }
   // 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