slidemind 0.3.20 → 0.4.1

package/src/builders/plan.mjs

@@ -52,11 +52,15 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { openInBrowser } from "./build.mjs";
-import { loadReviewState } from "./review.mjs";
+import { loadReviewState, writeStateAtomic } from "./review.mjs";
 import { renderPlanMarkdown } from "./plan-md.mjs";
 import { splitPlanFrontmatter } from "./resolve-skill.mjs";
 import { layoutJobs, isFrameJob, plannedJob } from "./layout-jobs.mjs";
 import { splitPlanMarkdownIntoSegments } from "./storyboard-markdown.mjs";
+import { serializeStoryboardCanvas } from "./storyboard-schema.mjs";
+import { isEditRouteDeck } from "./edit-route.mjs";
+import { planCommentBullet } from "./plan-comments.mjs";
+import { CONTENT_DRAFT, PLAN_NOT_PRESENTED, bodySlidesWithoutContent, parseDeliverable, planCheckErrors as checkPlan } from "./plan-checks.mjs";
 import {
   FAVICON_LINK,
   MIME,
@@ -76,7 +80,25 @@ import {
   POLL_MS,
   POLL_TTL_MS,
 } from "./gate-server.mjs";
-import { resolveBrandAsset, resolveBundleDirForDeck } from "../bridge/bundle.mjs";
+import {
+  listCachedBundles,
+  readDeckBundleRef,
+  resolveBrandAsset,
+  resolveBundleDirForDeck,
+  writeDeckBundleRef,
+} from "../bridge/bundle.mjs";
+import { readDesignName, readThemeColors } from "../cli/designs.mjs";
+import { readImageAssetManifest } from "../lib/image-assets.mjs";
+import { reconcileImageUseOverrides } from "./image-use-reconcile.mjs";
+import {
+  PLAN_PAGE_MARKER,
+  deckSlug,
+  planPageOwner,
+  planPagePath,
+  readPlanOwner,
+  statePath,
+  writePlanOwner,
+} from "../lib/deck-paths.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -85,12 +107,22 @@ const PLAN_MD_PATH = path.join(__dirname, "plan-md.mjs");
 // The storyboard/red-thread plan-review modules, bundled into the browser page
 // alongside plan-md.mjs (see bundlePlanModules). Order matters: each file's
 // inter-module imports are stripped, so a module must be concatenated AFTER the
-// module whose exports it references (schema ← storyboard-markdown ← backbone).
+// module whose exports it references (image-intent ← schema ←
+// storyboard-markdown ← backbone). image-intent.mjs lives under src/lib/ and
+// was written browser-safe (no Node builtins, `ii`/`II_`-prefixed module
+// scope) precisely so it can ride along here — the schema parses `assetUses`
+// through it.
+const IMAGE_INTENT_PATH = path.join(__dirname, "..", "lib", "image-intent.mjs");
 const STORYBOARD_SCHEMA_PATH = path.join(__dirname, "storyboard-schema.mjs");
 const STORYBOARD_MARKDOWN_PATH = path.join(__dirname, "storyboard-markdown.mjs");
 const RED_THREAD_BACKBONE_PATH = path.join(__dirname, "red-thread-backbone.mjs");
 const PLAN_MARKDOWN_EDIT_PATH = path.join(__dirname, "plan-markdown-edit.mjs");
 const PLAN_STATE_FILE = "plan-review.json";
+// What a body slide's content draft holds — one wording (plan-checks.mjs) for
+// the approval output, the deck stage, the concepts refusal and the add-in.
+export { CONTENT_DRAFT, parseDeliverable };
+const NEXT_AFTER_APPROVAL =
+  `write ${CONTENT_DRAFT} into each storyboard's \`content\` in plan.md (no new sign-off needed), then run \`slidemind concepts\`.`;
 // No decision timeout: the gate returns only on the user's decision (or when
 // no browser could be opened at all — see openFailedGraceMs). An agent cannot
 // proceed past a plan a human has not approved, so the process waits as long as
@@ -135,7 +167,7 @@ export function normalizePlanComments(raw) {
 // drives the tab-reuse grace window in runPlanReview (a waiting tab can only
 // exist after a prior comments round).
 export function loadPlanState(deckDir) {
-  const f = path.join(deckDir, PLAN_STATE_FILE);
+  const f = statePath(deckDir, PLAN_STATE_FILE);
   if (!fs.existsSync(f)) return { ...EMPTY_STATE };
   try {
     const data = JSON.parse(fs.readFileSync(f, "utf8"));
@@ -146,7 +178,14 @@ export function loadPlanState(deckDir) {
       comments: normalizePlanComments(data.comments),
       edited: data.edited ?? false,
       planHash: data.planHash ?? null,
+      storyHash: data.storyHash ?? null,
       at: data.at ?? null,
+      // Workspace provenance (respondPlan): which operation wrote this round and
+      // who answered. Absent on rounds the standalone gate recorded.
+      operationId: typeof data.operationId === "string" ? data.operationId : null,
+      actor: data.actor ?? null,
+      // The design the user switched the deck to with this answer (switchPlanDesign).
+      design: data.design && typeof data.design.to === "string" ? data.design : null,
     };
   } catch {
     return { ...EMPTY_STATE };
@@ -154,10 +193,10 @@ export function loadPlanState(deckDir) {
 }
 
 export function savePlanState(deckDir, state) {
-  fs.writeFileSync(
-    path.join(deckDir, PLAN_STATE_FILE),
-    JSON.stringify(state, null, 2) + "\n",
-  );
+  writeStateAtomic(deckDir, PLAN_STATE_FILE, JSON.stringify(state, null, 2) + "\n");
+  // Every writer of the record re-renders the page in the same command —
+  // a plan.html nobody refreshed is worse than none at all.
+  writePlanPage(deckDir);
 }
 
 // The human checkmark every post-plan command (concepts, build, view-draft,
@@ -169,14 +208,32 @@ export function savePlanState(deckDir, state) {
 // The gate binds only until the deck has passed a review: from then on the plan
 // has been executed and plan.md is a record, not a contract — the add-in's
 // manager likewise hands an edit delegation `approvedPlan: null` and never
-// re-gates the old plan. Edits to existing slides are the review gate's job
-// (it re-arms on every slide change); the plan rule for slides added to a
-// reviewed deck stays the skill's, as it is in-app.
+// re-gates the old plan. The preview review is one-time too, so neither gate
+// re-arms on a later change; the plan rule for slides added to a reviewed deck
+// stays the skill's, as it is in-app.
+
+// Both gates ask it; it lives in edit-route.mjs so review.mjs can import it too.
+export { isEditRouteDeck };
+
+/**
+ * The plan gate's own question: was THIS plan signed off at the plan gate?
+ * Stricter than requirePlanApproved, which also lets later stages through once
+ * the preview was approved — a gate asked again about a changed plan must ask.
+ */
+export function planApprovedExactly(deckDir) {
+  const planPath = path.join(deckDir, "plan.md");
+  if (!fs.existsSync(planPath)) return false;
+  const state = loadPlanState(deckDir);
+  if (state.decision !== "approve") return false;
+  return state.planHash === hashPlan(planPath) || state.storyHash === planStoryHash(deckDir);
+}
+
 export function requirePlanApproved(deckDir) {
   const planPath = path.join(deckDir, "plan.md");
   if (!fs.existsSync(planPath)) return null;
-  if (loadReviewState(deckDir).decision === "approve") return null;
-  const base = path.basename(deckDir);
+  if (isEditRouteDeck(deckDir)) return null;
+  if (loadReviewState(deckDir).approval) return null;
+  const base = deckSlug(deckDir);
   const state = loadPlanState(deckDir);
   if (state.decision !== "approve") {
     return (
@@ -184,7 +241,9 @@ export function requirePlanApproved(deckDir) {
       `run \`slidemind plan ${base}\` and wait for DECISION: approved.`
     );
   }
-  if (state.planHash !== hashPlan(planPath)) {
+  // A content expansion after sign-off is allowed (planStoryHash); anything that
+  // moves the story is not.
+  if (state.planHash !== hashPlan(planPath) && state.storyHash !== planStoryHash(deckDir)) {
     return (
       `${base}/plan.md changed since the user approved it — ` +
       `re-run \`slidemind plan ${base}\` for a fresh sign-off.`
@@ -197,16 +256,25 @@ export function requirePlanApproved(deckDir) {
 // harness output
 // ---------------------------------------------------------------------------
 
-// One anchored bullet per comment: `- [Slide 3: "Align the next outcome"] text`
-// or `- [Whole story] text`. Continuation lines are indented under the bullet so
-// a multi-line note can't be mistaken for a second comment.
-function commentBullet(c) {
-  const anchor =
-    c.scope === "slide"
-      ? `Slide ${c.slideIndex ?? "?"}${c.slideHeading ? `: "${c.slideHeading}"` : ""}`
-      : "Whole story";
-  const [first, ...rest] = String(c.text).split("\n");
-  return [`- [${anchor}] ${first}`, ...rest.map((l) => `  ${l}`)].join("\n");
+// The design the user switched the deck to at the gate, said once in either
+// decision: the agent planned against the old design.md and must not author
+// from it. Concept mockups made before the switch show the old design, and
+// `concepts` keeps a mockup it already has — so they are named for `--force`.
+function designSwitchLine(deckDir, design) {
+  if (!design?.to) return null;
+  const dir = resolveBundleDirForDeck(deckDir);
+  const read = dir ? `Re-read ${path.join(dir, "design.md")}` : `Run \`slidemind ready ${deckSlug(deckDir)}\``;
+  let line =
+    `The user switched this deck's corporate design to ${design.name ?? design.to} (${design.to}) at the gate. ` +
+    `${read} before you go on — every later step builds against it.`;
+  try {
+    if (fs.readdirSync(path.join(deckDir, "concepts")).some((f) => /^concept-slide-\d+\.png$/.test(f))) {
+      line += ` The existing concept mockups show the previous design: regenerate them with \`slidemind concepts ${deckSlug(deckDir)} --force\`.`;
+    }
+  } catch {
+    /* no concepts yet */
+  }
+  return line;
 }
 
 // Render the comments round for the harness — the plan analog of review.mjs's
@@ -216,11 +284,13 @@ function commentBullet(c) {
 // next `slidemind plan` run — nothing reaches them until it runs. An agent that
 // ends its turn here strands them, so the re-run instruction says "same turn"
 // and says why more comment rounds may follow.
-export function formatPlanCommentsForHarness(deckDir, comments, { edited = false } = {}) {
+export function formatPlanCommentsForHarness(deckDir, comments, { edited = false, design = null } = {}) {
   const rows = normalizePlanComments(comments);
   const out = [];
   out.push("DECISION: comments");
   out.push("The user requested changes to the plan. Nothing was authored.");
+  const switched = designSwitchLine(deckDir, design);
+  if (switched) out.push(switched);
   if (edited) {
     out.push(
       "The user also edited plan.md directly — re-read it before revising; the " +
@@ -229,14 +299,14 @@ export function formatPlanCommentsForHarness(deckDir, comments, { edited = false
   }
   out.push("");
   if (rows.length) {
-    for (const c of rows) out.push(commentBullet(c));
+    for (const c of rows) out.push(planCommentBullet(c));
   } else if (edited) {
     out.push("(No written comments — their direct edits to plan.md are the change.)");
   }
   out.push("");
   out.push("Revise plan.md to address ALL comments — change only what the feedback");
   out.push("requires; keep unaffected slides verbatim.");
-  out.push(`Then run \`slidemind plan ${path.basename(deckDir)}\` again in the same turn.`);
+  out.push(`Then run \`slidemind plan ${deckSlug(deckDir)}\` again in the same turn.`);
   out.push("The reviewer then reviews the revised plan — several comment rounds are");
   out.push("normal, not an error. Do NOT end your turn and do NOT send the user back");
   out.push("to the browser before you re-run the gate.");
@@ -245,17 +315,49 @@ export function formatPlanCommentsForHarness(deckDir, comments, { edited = false
   // the round is persisted before this prints, so a lost capture is recoverable.
   out.push(
     `This round (decision + comments) is also saved verbatim in ` +
-      `${path.join(deckDir, PLAN_STATE_FILE)} — if this output looks truncated, read ` +
+      `${statePath(deckDir, PLAN_STATE_FILE)} — if this output looks truncated, read ` +
       `that file instead of guessing.`,
   );
   return out.join("\n") + "\n";
 }
 
+// The approval as the harness reads it — one wording for the standalone gate
+// and the workspace gate (an edit made at the gate is the approved plan).
+export function planApprovedText(deckDir, { edited = false, note = null, design = null } = {}) {
+  const switched = designSwitchLine(deckDir, design);
+  return (
+    "DECISION: approved\n" +
+    (note ? `${note}\n` : "") +
+    (switched ? `${switched}\n` : "") +
+    (edited
+      ? "The user approved the plan — and edited plan.md directly before approving. " +
+        `Re-read ${deckDir}/plan.md: the edited text IS the approved plan. Author from ` +
+        `it, not from your earlier draft. Next: ${NEXT_AFTER_APPROVAL}\n`
+      : `The user approved the plan. Next: ${NEXT_AFTER_APPROVAL}\n`)
+  );
+}
+
+/**
+ * A workspace task's answer, printed exactly as the standalone gate prints its
+ * own: the comments come from the gate record the answer wrote (plan-review.json,
+ * the same operation), else from the task itself. "Edited" is the record's flag
+ * or the task having followed an edit the human made in the page.
+ */
+export function formatPlanTaskDecision(deckDir, task, { note = null, editedInPage = false } = {}) {
+  const state = loadPlanState(deckDir);
+  const mine = Boolean(state.operationId) && task?.response?.operationId === state.operationId;
+  const edited = Boolean(editedInPage || (mine && state.edited) || (task?.subject?.requestedHash && task.subject.requestedHash !== task.subject.hash));
+  const design = mine ? state.design : null;
+  if (task?.response?.action === "approve") return planApprovedText(deckDir, { edited, note, design });
+  const comments = mine ? state.comments : task?.response?.comment ? [{ text: task.response.comment, scope: "story" }] : [];
+  return (note ? `NOTE: ${note}\n` : "") + formatPlanCommentsForHarness(deckDir, comments, { edited, design });
+}
+
 // Render the no-answer outcome for the harness. A timed-out gate is an EXPECTED
 // state (the user stepped away), not a failure — the agent must neither treat
 // it as approval nor abort the task; it wraps up with clear resume instructions.
 export function formatPlanPendingForHarness(deckDir, { timeoutMs, pageLoaded, url } = {}) {
-  const base = path.basename(deckDir);
+  const base = deckSlug(deckDir);
   const waited = timeoutMs
     ? `the gate waited ${Math.max(1, Math.round(timeoutMs / 60000))} minutes and the user hasn't answered.`
     : "the gate closed without an answer from the user.";
@@ -288,7 +390,7 @@ const PLAN_NAMESPACE_EXPORTS = [
   "splitPlanMarkdownIntoSegments",
   "replaceStoryboardSegment",
   "setStoryboardLayoutForAll",
-  "setStoryboardStyle",
+  "remapStoryboardLayouts",
   "extractRedThreadMessages",
   "findRedThreadSection",
   "parseStoryboardCanvas",
@@ -297,14 +399,6 @@ const PLAN_NAMESPACE_EXPORTS = [
   "parsePlanBackbone",
   "applyPlanBackbone",
   "stageStoryIteration",
-  "STORYBOARD_WIDTH",
-  "STORYBOARD_HEIGHT",
-  "BODY_SAFE_AREA",
-  "MIN_BLOCK_WIDTH",
-  "MIN_BLOCK_HEIGHT",
-  "MAX_BLOCKS",
-  "MAX_DESIGN_ELEMENT_LENGTH",
-  "MAX_CONTENT_LENGTH",
   "MAX_IMAGE_PROMPT_LENGTH",
 ];
 
@@ -313,14 +407,15 @@ const PLAN_NAMESPACE_EXPORTS = [
 // caller and the module tests reach for it on this path.
 export { stripModuleSyntax };
 
-// Bundle the five plan-review modules into one IIFE for the browser page, in
-// dependency order (schema → storyboard-markdown → backbone → edit → plan-md).
+// Bundle the plan-review modules into one IIFE for the browser page, in
+// dependency order (image-intent → schema → storyboard-markdown → backbone →
+// edit → plan-md).
 // The IIFE exposes window.__SLIDEMIND_RENDER_MD__ (back-compat with the old
 // preview) and window.__SLIDEMIND_PLAN__ (the full namespace the overlay reads).
 // Exported so a test can evaluate the output against a stub window and catch a
 // strip-regex miss or a top-level name collision for real.
-export function bundlePlanModules({ schema, storyboardMd, backbone, edit, planMd } = {}) {
-  const body = [schema, storyboardMd, backbone, edit, planMd]
+export function bundlePlanModules({ intent, schema, storyboardMd, backbone, edit, planMd } = {}) {
+  const body = [intent, schema, storyboardMd, backbone, edit, planMd]
     .map(stripModuleSyntax)
     .join("\n");
   return (
@@ -333,10 +428,11 @@ export function bundlePlanModules({ schema, storyboardMd, backbone, edit, planMd
   );
 }
 
-// Read the five module sources off disk and bundle them. Split from
+// Read the module sources off disk and bundle them. Split from
 // bundlePlanModules so the pure string→string step stays unit-testable.
 export function bundlePlanModulesFromDisk() {
   return bundlePlanModules({
+    intent: fs.readFileSync(IMAGE_INTENT_PATH, "utf8"),
     schema: fs.readFileSync(STORYBOARD_SCHEMA_PATH, "utf8"),
     storyboardMd: fs.readFileSync(STORYBOARD_MARKDOWN_PATH, "utf8"),
     backbone: fs.readFileSync(RED_THREAD_BACKBONE_PATH, "utf8"),
@@ -471,96 +567,55 @@ export function parsePlaceholderOutlines(source, layoutsCss) {
 // `/brand/chrome/<file>`. No bundle → `{ layouts: [], chromeDir: null }` and
 // the picker degrades to read-only (the host-free contract holds).
 // ---------------------------------------------------------------------------
-// The plan's `## Deliverable` block and the deck frame it implies
-// (docs/slidemind-cli-connect/17-deck-frame.md). Parsed leniently: the block
-// is a contract the agent writes and the user edits by hand.
+// The plan checks (plan-checks.mjs, shared with the add-in), read against this
+// deck's bundle: what job each layout does.
 // ---------------------------------------------------------------------------
 
-export function parseDeliverable(markdown) {
-  const m = /^##\s+Deliverable\s*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/m.exec(markdown ?? "");
-  if (!m) return null;
-  const get = (key) => {
-    const r = new RegExp(`^\\s*-?\\s*${key}\\s*:\\s*(.+)$`, "im").exec(m[1]);
-    return r ? r[1].trim() : null;
-  };
-  const shape = (get("shape") ?? "").toLowerCase().replace(/[^a-z]/g, "");
-  const body = Number.parseInt(get("body slides") ?? get("body") ?? "", 10);
-  const frameRaw = (get("frame") ?? "").toLowerCase();
-  const frame = /^(none|-|—|no)\b/.test(frameRaw)
-    ? []
-    : frameRaw.split(/[,;/]+/).map((x) => x.trim().replace(/s$/, "")).filter(Boolean);
-  return {
-    shape: shape === "deck" || shape === "slides" ? shape : null,
-    bodySlides: Number.isFinite(body) ? body : null,
-    frame,
-    target: get("target"),
-  };
+function deckJobs(deckDir) {
+  const jobs = layoutJobs(resolveBundleDirForDeck(deckDir));
+  return { jobs, isFrameSlide: (data) => isFrameJob(plannedJob(data, jobs)) };
 }
 
 /**
- * `[plan:warn]` lines for a plan whose deliverable block and storyboards do
- * not agree with each other or with the bundle's layout jobs. Advisory: the
- * gate still opens — the user decides in it — but the agent reads these
- * before the user does.
+ * The body slides still owing their full content draft — the step between
+ * sign-off and `concepts`, read by the deck stage and the concepts refusal.
  */
-export function planDeliverableWarnings(deckDir, markdown) {
-  const out = [];
-  const dir = resolveBundleDirForDeck(deckDir);
-  const jobs = layoutJobs(dir);
-  const beats = [];
-  for (const segment of splitPlanMarkdownIntoSegments(markdown ?? "")) {
-    if (segment.type !== "storyboard" || !segment.data) continue;
-    const layout = segment.data.layout ?? null;
-    if (!segment.data.role) out.push(`[plan:warn] slide ${segment.data.slide} has no role; legacy layout inference is being used. Write role: body | frame before the next approval.`);
-    if (segment.data.role === "frame" && !segment.data.frameKind) out.push(`[plan:warn] frame slide ${segment.data.slide} needs a frameKind.`);
-    beats.push({ slide: segment.data.slide, layout, job: plannedJob(segment.data, jobs) });
-  }
-  if (beats.length === 0) return out;
-  const frameBeats = beats.filter((b) => isFrameJob(b.job));
-  const bodyBeats = beats.filter((b) => !isFrameJob(b.job));
-  const d = parseDeliverable(markdown);
-  if (!d) {
-    out.push(
-      `[plan:warn] plan.md has no \`## Deliverable\` block (shape: deck | slides, body slides: N, frame: <jobs>, target). ` +
-        `Without it the frame (cover/agenda/dividers/closing) is unspecified — write the block before the gate.`,
-    );
-    return out;
-  }
-  if (d.shape === "deck" && frameBeats.length === 0) {
-    const offered = [...jobs.values()].filter((j) => isFrameJob(j.job)).map((j) => j.job);
-    out.push(
-      `[plan:warn] shape is deck but no storyboard sits on a frame layout — this design offers ${offered.length ? [...new Set(offered)].join(", ") : "no frame layouts"}; a deck ships its cover${offered.includes("closing") ? " and closing" : ""}.`,
-    );
-  }
-  if (d.shape === "slides" && frameBeats.length > 0 && d.frame.length === 0) {
-    out.push(
-      `[plan:warn] shape is slides but slide${frameBeats.length > 1 ? "s" : ""} ${frameBeats.map((b) => b.slide).join(", ")} sit on frame layouts (${[...new Set(frameBeats.map((b) => b.job))].join(", ")}) — slides extend a deck that has its own frame; drop them or set shape: deck.`,
-    );
-  }
-  if (d.bodySlides != null && d.bodySlides !== bodyBeats.length) {
-    out.push(
-      `[plan:warn] Deliverable says body slides: ${d.bodySlides}, the storyboards carry ${bodyBeats.length} body slide${bodyBeats.length === 1 ? "" : "s"} (frame slides excluded).`,
-    );
-  }
-  for (const want of d.frame) {
-    if (!isFrameJob(want)) continue;
-    if (!frameBeats.some((b) => b.job === want)) {
-      out.push(`[plan:warn] frame lists ${want} but no storyboard declares that frameKind.`);
-    }
-  }
-  const cover = frameBeats.find((b) => b.job === "cover");
-  if (cover && beats.some((b) => b.slide < cover.slide)) {
-    out.push(`[plan:warn] the cover is slide ${cover.slide} — a cover is slide 1.`);
-  }
-  const closing = frameBeats.find((b) => b.job === "closing");
-  if (closing && beats.some((b) => b.slide > closing.slide)) {
-    out.push(`[plan:warn] the closing is slide ${closing.slide} but slides follow it — a closing is the last slide.`);
-  }
-  return out;
+export function slidesWithoutContent(deckDir, markdown) {
+  return bodySlidesWithoutContent(markdown, { isFrameSlide: deckJobs(deckDir).isFrameSlide });
 }
 
-export function resolvePlanLayouts(deckDir) {
-  const dir = resolveBundleDirForDeck(deckDir);
+/**
+ * `[plan:error]` lines for a plan whose deliverable block, red thread and
+ * storyboards do not agree with each other or with the bundle's layout jobs.
+ */
+export function planCheckErrors(deckDir, markdown) {
+  const { jobs } = deckJobs(deckDir);
+  return checkPlan(markdown, {
+    slideJob: (data) => plannedJob(data, jobs),
+    isFrameJob,
+    offeredJobs: [...jobs.values()].map((j) => j.job),
+  });
+}
+
+/**
+ * The refusal for opening a NEW plan round on plan.md as it stands, or null —
+ * the add-in's `present_plan_for_review` refuses the same plans. Never asked of
+ * an answer the user already gave: their edits are their decision.
+ */
+export function planRefusal(deckDir) {
+  const errors = planCheckErrors(deckDir, fs.readFileSync(path.join(deckDir, "plan.md"), "utf8"));
+  if (errors.length === 0) return null;
+  return (
+    `${PLAN_NOT_PRESENTED} Fix each line below in plan.md (workflow/plan.md), then run ` +
+    `\`slidemind plan ${deckSlug(deckDir)}\` again:\n` +
+    errors.map((line) => `  ${line}\n`).join("")
+  );
+}
+
+// `bundleDir` reads another cached design's palette instead of the deck's own
+// (the design picker); the deck's layout context still applies by layoutKey.
+export function resolvePlanLayouts(deckDir, { bundleDir = null } = {}) {
+  const dir = bundleDir ?? resolveBundleDirForDeck(deckDir);
   if (!dir) return { layouts: [], chromeDir: null };
   const layoutsDir = path.join(dir, "layouts");
   const assetsDir = path.join(dir, "assets");
@@ -696,36 +751,144 @@ export function resolvePlanLayouts(deckDir) {
   }
   // Target context is opt-in, written by `read --deck`; it never changes the brand bundle.
   try {
-    const context = JSON.parse(fs.readFileSync(path.join(deckDir, ".layout-context.json"), "utf8"));
+    const context = JSON.parse(fs.readFileSync(statePath(deckDir, "layout-context.json"), "utf8"));
     for (const layout of layouts) {
       const selected = context.selections?.[layout.componentName];
       if (!layout.selection) continue;
       // A modern scoped identity mismatch must never fall back to a name join.
       if (selected?.layoutKey) {
         if (selected.layoutKey !== layout.layoutKey) continue;
-        layout.selection = { ...layout.selection, currentCount: selected.currentCount,
-          sectionCount: selected.sectionCount };
+        layout.selection = { ...layout.selection, currentCount: selected.currentCount };
       } else if (context.selections === undefined &&
         Object.hasOwn(context.layoutCounts ?? {}, layout.nativeLayoutName) &&
         layouts.filter((other) => other.nativeLayoutName === layout.nativeLayoutName).length === 1) {
         layout.selection = { ...layout.selection, currentCount: context.layoutCounts[layout.nativeLayoutName] };
       }
       const p = layout.selection;
-      p.source = p.sectionCount > 0 ? "section" : p.currentCount > 0 ? "presentation" : p.usage?.count > 0 ? "brand" : "suggested";
+      p.source = p.currentCount > 0 ? "presentation" : p.usage?.count > 0 ? "brand" : "suggested";
     }
   } catch {}
-  // Same precedence as the add-in profile: capability, section, target, brand.
-  // Brand ranks are supplied by the add-in; legacy bundles retain their order.
+  // Same precedence as the add-in profile (layout-selection.ts): capability,
+  // target, brand. The brand rank is the add-in's own order, so its remaining
+  // tie-breaks (writable canvas area, then name) carry over unchanged.
   layouts.sort((a, b) => {
     if (!a.selection || !b.selection) return (a.selection?.rank ?? Infinity) - (b.selection?.rank ?? Infinity);
     return Number(b.selection.composition) - Number(a.selection.composition) ||
-      (b.selection.sectionCount ?? 0) - (a.selection.sectionCount ?? 0) ||
       (b.selection.currentCount ?? 0) - (a.selection.currentCount ?? 0) ||
-      b.selection.usage.share - a.selection.usage.share || a.componentName.localeCompare(b.componentName);
+      b.selection.usage.share - a.selection.usage.share ||
+      (a.selection.rank ?? Infinity) - (b.selection.rank ?? Infinity) ||
+      a.componentName.localeCompare(b.componentName);
   });
   return { layouts, chromeDir: chromeFiles.length ? assetsDir : null };
 }
 
+// ---------------------------------------------------------------------------
+// The design picker: every design cached on this machine, offered at the gate.
+// Choosing one is part of the answer (`design` on the decision), not a write of
+// its own — the deck is rebound when the user sends, together with the plan
+// whose layouts the page moved onto the new design.
+// ---------------------------------------------------------------------------
+
+const ACCENT_KEYS = ["accent1", "accent2", "accent3", "accent4", "accent5", "accent6"];
+
+function cachedDesign(presFP) {
+  return (presFP && listCachedBundles().find((b) => b.presFP === presFP)) || null;
+}
+
+/**
+ * The picker's menu: name + accent colours per cached design, sorted by name,
+ * `current` on the one the deck is bound to. Every other design carries its
+ * layout palette so the page can swap the layout picker without a round trip;
+ * its chrome thumbnails are addressed with `?design=<presFP>` (see
+ * `planChromeDir`). `mapUrl` prefixes those URLs for the workspace's routes.
+ */
+export function planDesignOptions(deckDir, { mapUrl = (u) => u } = {}) {
+  const bound = readDeckBundleRef(deckDir)?.presFP ?? null;
+  return listCachedBundles()
+    .map((b) => {
+      const colors = readThemeColors(b.dir) ?? {};
+      const current = b.presFP === bound;
+      const design = {
+        presFP: b.presFP,
+        name: readDesignName(b.dir) ?? b.presFP,
+        accents: ACCENT_KEYS.map((k) => colors[k]).filter(Boolean),
+        current,
+      };
+      if (!current) {
+        design.layouts = resolvePlanLayouts(deckDir, { bundleDir: b.dir }).layouts.map((l) => ({
+          ...l,
+          previewUrl: l.previewUrl ? mapUrl(`${l.previewUrl}?design=${encodeURIComponent(b.presFP)}`) : null,
+        }));
+      }
+      return design;
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The picker's whole menu: the cached designs above (`cached: true`) and, after
+ * them, every other design a connected backend serves (`cached: false` — a name,
+ * no palette yet), downloaded when picked (`downloadPlanDesign`). A backend that does not
+ * answer leaves the menu at what this machine already has. The page asks for it
+ * after it loads, so a slow backend never holds up the plan.
+ */
+export async function listPlanDesigns(deckDir, { mapUrl = (u) => u, listBrands = null } = {}) {
+  const cached = planDesignOptions(deckDir, { mapUrl }).map((d) => ({ ...d, cached: true }));
+  let listed = [];
+  try {
+    listed = await (listBrands ?? (await import("../bridge/client.mjs")).listBrands)();
+  } catch {
+    listed = [];
+  }
+  const seen = new Set(cached.map((d) => d.presFP));
+  const more = [];
+  for (const b of listed) {
+    if (!b?.presFP || seen.has(b.presFP)) continue;
+    seen.add(b.presFP);
+    more.push({ presFP: b.presFP, name: b.name || b.presFP, accents: [], current: false, cached: false });
+  }
+  // what this machine has first (each sorted by name), what would still have to
+  // be downloaded last — the page draws those rows smaller, under a divider
+  const byName = (a, b) => a.name.localeCompare(b.name);
+  return [...cached.sort(byName), ...more.sort(byName)];
+}
+
+/**
+ * A design picked at the gate that this machine has not downloaded yet:
+ * materialize it over the pane-free brand route, then return its picker entry
+ * (palette, layouts) like any cached one. Throws `unknown_design` when no
+ * connected backend serves it.
+ */
+export async function downloadPlanDesign(deckDir, presFP, { mapUrl = (u) => u, materialize = null } = {}) {
+  if (!cachedDesign(presFP)) {
+    const run = materialize ?? (async (brandId) => (await import("../bridge/bundle.mjs")).materializeBundle(null, { brandId }));
+    await run(presFP);
+  }
+  const design = planDesignOptions(deckDir, { mapUrl }).find((d) => d.presFP === presFP);
+  if (!design) throw Object.assign(new Error(`no connected backend serves design '${presFP}'`), { code: "unknown_design" });
+  return { ...design, cached: true };
+}
+
+/** Where `/brand/chrome/<file>` reads from: the named cached design, else the deck's own. */
+export function planChromeDir(deckDir, design = null) {
+  const dir = design ? cachedDesign(design)?.dir : resolveBundleDirForDeck(deckDir);
+  return dir ? path.join(dir, "assets") : null;
+}
+
+/**
+ * Rebind the deck to the cached design the user chose at the gate. Returns
+ * `{ from, to, name }` when the binding moved, null when it already was that
+ * design, or `{ error }` for a design this machine does not hold.
+ */
+export function switchPlanDesign(deckDir, presFP) {
+  const hit = cachedDesign(presFP);
+  if (!hit) return { error: `design '${presFP}' is not cached on this machine` };
+  const from = readDeckBundleRef(deckDir)?.presFP ?? null;
+  if (from === presFP) return null;
+  writeDeckBundleRef(deckDir, { presFP, etag: hit.meta?.etag ?? null });
+  return { from, to: presFP, name: readDesignName(hit.dir) ?? presFP };
+}
+
 // Build the standalone plan-review page: the rendered markdown in #plan-root
 // (the no-JS fallback and the preview's initial state), the injected overlay
 // config, the bundled plan-review modules, then the overlay script itself.
@@ -744,16 +907,34 @@ export function buildPlanPage({
   deck,
   ledgerSeed,
   layouts,
+  designs,
+  imageAssets,
+  // The plan.md record this page was rendered from, verbatim. It rides in the
+  // page so the file at the deck root IS the plan — recoverable, diffable, and
+  // enough for `extract` to be unnecessary.
+  planRecord = null,
+  // The command that serves this page for editing. Set on the copy written to
+  // disk (a browser cannot write back to a file), null on the served copy —
+  // the overlay stays dormant while it is set, so the file reads as a document.
+  readOnly = null,
 }) {
   const cfg = safeInlineJson({
     endpoint: "/plan-review",
     heartbeat: "/__plan/heartbeat",
+    readOnly,
+    planRecord,
     round: round ?? null,
     pollMs: POLL_MS,
     pollTtlMs: POLL_TTL_MS,
     logoMark: logoMark ?? null,
     // Brand layouts for the per-slide layout picker (empty → picker read-only).
     layouts: Array.isArray(layouts) ? layouts : [],
+    // The cached designs for the design picker (planDesignOptions; empty → none).
+    designs: Array.isArray(designs) ? designs : [],
+    // The deck's image registry, for the per-slide image-use summary: name +
+    // preview for each `assetUses[].assetId`. Names and previews only — the
+    // obligation itself lives in the plan record the page already carries.
+    imageAssets: Array.isArray(imageAssets) ? imageAssets : [],
     planBody: planBody ?? "",
     bodyStartLine: bodyStartLine ?? 1,
     // deck: the sessionStorage namespace for this deck's comment ledger.
@@ -770,11 +951,19 @@ export function buildPlanPage({
   const rendererBlock = modulesSrc ? "<script>\n" + modulesSrc + "\n</script>\n" : "";
   // The shared gate session goes in before the overlay, which reads it at boot.
   const gateBlock = "<script>\n" + bundleGateSession().replace(/<\/script>/g, "<\\/script>") + "\n</script>\n";
+  const banner = readOnly
+    ? `<div id="plan-readonly-note" style="max-width:720px;margin:0 auto;` +
+      `padding:14px 28px 0;font:500 13.5px/1.5 ui-sans-serif,system-ui,sans-serif;` +
+      `color:#a8a8ad">This is the saved plan, read-only. To edit it, run ` +
+      `<code style="background:#1c1c20;padding:.12em .42em;border-radius:5px">` +
+      `${escapeHtml(readOnly)}</code>.</div>\n`
+    : "";
   return (
     "<!doctype html>\n" +
     '<html lang="en">\n' +
     "<head>\n" +
     '<meta charset="utf-8">\n' +
+    `${PLAN_PAGE_MARKER}\n` +
     '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
     "<title>Plan review — slidemind</title>\n" +
     FAVICON_LINK +
@@ -782,8 +971,11 @@ export function buildPlanPage({
     `<style>${PAGE_CSS}</style>\n` +
     "</head>\n" +
     "<body>\n" +
+    banner +
     `<div id="plan-root">${bodyHtml}</div>\n` +
     `<script>window.__SLIDEMIND_PLAN_REVIEW__ = ${cfg};</script>\n` +
+    LIVE_PATCH_SLOT +
+    "\n" +
     gateBlock +
     rendererBlock +
     `<script>\n${overlay}\n</script>\n` +
@@ -792,6 +984,125 @@ export function buildPlanPage({
   );
 }
 
+// The served page IS the file at the deck root: the plan gate reads plan.html
+// back and swaps this slot for the run's write channel (endpoint, round,
+// layouts), which also clears `readOnly` and drops the banner. One rendering
+// path, so the page the user edits and the page they reopen cannot diverge.
+const LIVE_PATCH_SLOT = "<!--__PLAN_LIVE__-->";
+
+export function withPlanWriteChannel(html, live) {
+  const patch =
+    "<script>\n" +
+    `Object.assign(window.__SLIDEMIND_PLAN_REVIEW__, ${safeInlineJson({ ...live, readOnly: null })});\n` +
+    'document.addEventListener("DOMContentLoaded", function () {\n' +
+    '  var n = document.getElementById("plan-readonly-note");\n' +
+    "  if (n) n.remove();\n" +
+    "});\n" +
+    "</script>";
+  // Function replacers: `patch` embeds JSON.stringify'd reviewer comments and
+  // user file names (imageAssets[].displayName), so a `$'`, `$&` or `` $` `` in
+  // any of them would be expanded by String.replace and corrupt the script.
+  return html.includes(LIVE_PATCH_SLOT)
+    ? html.replace(LIVE_PATCH_SLOT, () => patch)
+    : html.replace("</body>", () => `${patch}\n</body>`);
+}
+
+function escapeHtml(text) {
+  return String(text).replace(/[&<>"]/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c],
+  );
+}
+
+// A deck root has one plan page and one writer of it (see planPageOwner). When
+// that is an extension — a pack deck, whose page renders a record this CLI
+// cannot read — the generic gates leave the page alone and name the command that
+// opens it. Reported once per workspace, on stderr so --json payloads stay clean.
+const ownerNoted = new Set();
+function foreignPlanPageOwner(deckDir) {
+  const owner = planPageOwner(deckDir);
+  if (owner.owner === "core") return null;
+  if (!ownerNoted.has(deckDir)) {
+    ownerNoted.add(deckDir);
+    process.stderr.write(
+      `slidemind: plan.html belongs to ${owner.owner} — left as it is. ` +
+        `${owner.reviewCommand ? `Open it with \`${owner.reviewCommand}\`.` : `Its owner is not installed here.`}\n`,
+    );
+  }
+  return owner;
+}
+
+// Render `plan.html` at the DECK ROOT from the workspace's plan.md. Called
+// after every write to the record, so the file the user opens is never stale.
+// Returns the path written, or null when the deck has no plan record yet or the
+// page belongs to an extension.
+export function writePlanPage(deckDir) {
+  const planPath = path.join(deckDir, "plan.md");
+  let raw;
+  try {
+    raw = fs.readFileSync(planPath, "utf8");
+  } catch {
+    return null;
+  }
+  if (foreignPlanPageOwner(deckDir)) return null;
+  const { body, bodyStartLine } = splitPlanFrontmatter(raw);
+  const slug = deckSlug(deckDir);
+  const html = buildPlanPage({
+    bodyHtml: renderPlanMarkdown(body, { lineOffset: bodyStartLine - 1 }),
+    overlayJs: fs.readFileSync(OVERLAY_PATH, "utf8"),
+    planModulesJs: bundlePlanModulesFromDisk(),
+    logoMark: null,
+    planBody: body,
+    bodyStartLine,
+    round: null,
+    deck: slug,
+    ledgerSeed: loadPlanState(deckDir).comments || [],
+    layouts: [],
+    planRecord: raw,
+    readOnly: `slidemind plan ${slug}`,
+  });
+  const out = planPagePath(deckDir);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, html);
+  // Claim the page the first time core renders it, so a later extension sees an
+  // owner rather than having to guess from the page it finds.
+  if (!readPlanOwner(deckDir)) {
+    writePlanOwner(deckDir, {
+      owner: "core",
+      reviewCommand: `slidemind plan ${slug}`,
+      recordPath: "plan.md",
+    });
+  }
+  return out;
+}
+
+/**
+ * The deck's image registry as the plan page needs it: enough to NAME and SHOW
+ * each asset a slide's `assetUses` points at, and nothing else.
+ *
+ * `previewUrl` is the manifest's own portable workspace path served off the
+ * deck root — `serveStaticFile({roots:[deckRoot]})` already answers it, so
+ * there is no second image route and no data URI inflating the page. An
+ * unreadable manifest yields an empty list: the plan gate is how a user fixes
+ * a deck, and it must open even when the registry is broken (the fence's own
+ * typed issue still reports it).
+ */
+export function planImageAssets(deckDir) {
+  let manifest;
+  try {
+    manifest = readImageAssetManifest(deckDir);
+  } catch {
+    return [];
+  }
+  return manifest.assets.map((a) => ({
+    assetId: a.assetId,
+    displayName: a.displayName,
+    mimeType: a.mimeType,
+    width: a.width,
+    height: a.height,
+    previewUrl: `/${a.workspacePath}`,
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // server
 // ---------------------------------------------------------------------------
@@ -810,7 +1121,7 @@ export async function createPlanReviewServer({
   brandAssetPath = null,
   ledgerSeed = [],
   layouts = [],
-  chromeDir = null,
+  designs = [],
   port = 0,
 }) {
   const gate = createDecisionGate({
@@ -819,20 +1130,31 @@ export async function createPlanReviewServer({
   // Own service marker so a tab left waiting on this port only reloads into the
   // NEXT plan round — never into the preview gate or a foreign app on the port.
   const hb = createHeartbeat({ service: "slidemind-plan" });
-  const overlay = overlayJs ?? fs.readFileSync(OVERLAY_PATH, "utf8");
-  const planModules = planModulesJs ?? bundlePlanModulesFromDisk();
-  const bodyHtml = renderPlanMarkdown(body, { lineOffset: bodyStartLine - 1 });
-  const indexHtml = buildPlanPage({
-    bodyHtml,
-    overlayJs: overlay,
-    planModulesJs: planModules,
-    logoMark,
-    planBody: body,
-    bodyStartLine,
+  // What the gate serves IS the plan.html at the deck root: re-rendered from
+  // the current record, then handed this run's write channel. So the page the
+  // user edits here and the page they reopen from disk cannot drift apart.
+  const pageFile = writePlanPage(deckDir);
+  const diskHtml = pageFile
+    ? fs.readFileSync(pageFile, "utf8")
+    : buildPlanPage({
+        bodyHtml: renderPlanMarkdown(body, { lineOffset: bodyStartLine - 1 }),
+        overlayJs: overlayJs ?? fs.readFileSync(OVERLAY_PATH, "utf8"),
+        planModulesJs: planModulesJs ?? bundlePlanModulesFromDisk(),
+        logoMark: null,
+        planBody: body,
+        bodyStartLine,
+        round: null,
+        deck: deckSlug(deckDir),
+        ledgerSeed: normalizePlanComments(ledgerSeed),
+        layouts: [],
+      });
+  const indexHtml = withPlanWriteChannel(diskHtml, {
     round: hb.round,
-    deck: path.basename(path.resolve(deckDir)),
-    ledgerSeed: normalizePlanComments(ledgerSeed),
+    logoMark,
     layouts,
+    designs,
+    imageAssets: planImageAssets(deckDir),
+    ledgerSeed: normalizePlanComments(ledgerSeed),
   });
   const deckRoot = path.resolve(deckDir);
 
@@ -854,6 +1176,7 @@ export async function createPlanReviewServer({
             decision,
             comments,
             editedPlan: typeof payload.editedPlan === "string" ? payload.editedPlan : null,
+            design: typeof payload.design === "string" ? payload.design : null,
           });
         },
       });
@@ -912,9 +1235,11 @@ export async function createPlanReviewServer({
     }
 
     // Layout chrome thumbnails for the picker — served from the materialized
-    // bundle's assets dir, basename-guarded to the chrome-<Name>.<ext> shape.
+    // bundle's assets dir (another cached design's with `?design=`, for the
+    // design picker), basename-guarded to the chrome-<Name>.<ext> shape.
     if (pathname.startsWith("/brand/chrome/")) {
       const name = path.basename(pathname);
+      const chromeDir = planChromeDir(deckDir, u.searchParams.get("design"));
       if (!chromeDir || !CHROME_ASSET_RE.test(name)) {
         res.writeHead(404);
         res.end("not found");
@@ -981,21 +1306,178 @@ export function applyPlanEdit({ planPath, frontmatterRaw, body, editedPlan }) {
   return { edited: true };
 }
 
+// Fold the targeted-edit image-use overrides into the plan being approved and
+// say so. Reported on stderr, never fatal: a sidecar this CLI cannot read must
+// not refuse a human's sign-off, and the obligation stays on file either way.
+function noteImageUseReconcile(deckDir) {
+  const result = reconcileImageUseOverrides(deckDir);
+  if (result.error) {
+    process.stderr.write(`slidemind: image use overrides could not be read (${result.error}) — left as they are.\n`);
+    return result;
+  }
+  if (result.applied.length) {
+    process.stderr.write(
+      `slidemind: folded image uses from ${result.applied.length} targeted edit${result.applied.length === 1 ? "" : "s"} ` +
+        `into the approved plan (slide${result.applied.length === 1 ? "" : "s"} ${result.applied.map((a) => a.slide).join(", ")}).\n`,
+    );
+  }
+  for (const entry of result.kept) {
+    process.stderr.write(`slidemind: image use override for ${entry.slideId} kept — ${entry.why}.\n`);
+  }
+  return result;
+}
+
 // Persisted with the decision as this round's plan fingerprint (the round
 // TRANSITION a reloaded tab detects is the server's heartbeat nonce, not this).
 function hashPlan(planPath) {
   return crypto.createHash("sha256").update(fs.readFileSync(planPath)).digest("hex");
 }
 
+/**
+ * The plan's STORY fingerprint: the same markdown with every record's
+ * `content` stripped before hashing.
+ *
+ * What a human signs off at the gate is the story, the layouts, the structure
+ * and each slide's 3-5 key points (`contentNotes`). The agent then writes each
+ * slide's full content draft into `content` — an elaboration of what was
+ * already approved, not a new plan. Hashing the bytes would re-arm the gate on
+ * that draft and stall every deck at the step after sign-off.
+ *
+ * Narrow on purpose, and safe by construction: a reworded beat or key point, a
+ * swapped layout, a renamed heading or a reordered red thread all move this
+ * hash and re-arm the gate. Only `content` is exempt.
+ */
+export function planStoryHash(deckDir) {
+  const markdown = fs.readFileSync(path.join(deckDir, "plan.md"), "utf8");
+  const story = splitPlanMarkdownIntoSegments(markdown)
+    .map((segment) => {
+      if (segment.type !== "storyboard") return segment.text ?? "";
+      if (!segment.data) return segment.raw ?? "";
+      const { content: _content, ...rest } = segment.data;
+      return serializeStoryboardCanvas(rest);
+    })
+    .join("\n");
+  return crypto.createHash("sha256").update(story).digest("hex");
+}
+
+/** The plan subject as the workspace names it: `sha256:<hex of plan.md bytes>`. */
+export function planSubjectHash(deckDir) {
+  return "sha256:" + hashPlan(path.join(deckDir, "plan.md"));
+}
+
+function bareHash(h) {
+  return typeof h === "string" ? h.replace(/^sha256:/, "") : null;
+}
+
+function refusal(status, code, message, details) {
+  return { status, body: { ok: false, error: { code, message, retryable: false, ...(details ? { details } : {}) } } };
+}
+
+// The ONE write path of a plan decision — the standalone gate's tail and the
+// workspace task response both land here, so plan.md, plan-review.json and
+// plan.html come out the same whichever page answered. `action` is approve,
+// comments (also `request-changes`, the task-contract name) or `done` (a
+// plan-edit task: the record is re-rendered, no decision is recorded).
+// `expectedHash` is the plan the reviewer saw (`planSubjectHash` or its bare
+// hex) — a plan.md rewritten since is refused, never approved by accident.
+// `operationId` makes a repeat idempotent; a different decision under the same
+// id is refused. `write` is the seam a crash test injects; the record is
+// written last and atomically, so a throw here leaves no approval behind.
+export function respondPlan(
+  deckDir,
+  {
+    action,
+    expectedHash = null,
+    payload = {},
+    actor = null,
+    operationId = null,
+    at = new Date().toISOString(),
+    write = savePlanState,
+  } = {},
+) {
+  const decision =
+    action === "approve"
+      ? "approve"
+      : action === "comments" || action === "comment" || action === "request-changes"
+        ? "comments"
+        : action === "done"
+          ? "done"
+          : null;
+  if (!decision) return refusal(422, "validation_failed", `unknown plan action '${action}'`);
+  const planPath = path.join(deckDir, "plan.md");
+  if (!fs.existsSync(planPath)) return refusal(404, "plan_missing", `no plan.md in ${deckSlug(deckDir)}`);
+  const prev = loadPlanState(deckDir);
+  if (operationId && prev.operationId === operationId) {
+    if (prev.decision !== decision || (expectedHash != null && bareHash(expectedHash) !== prev.planHash)) {
+      return refusal(409, "operation_mismatch", "this operation id already recorded a different response");
+    }
+    return {
+      status: 200,
+      body: { ok: true, decision: prev.decision, comments: prev.comments, edited: prev.edited, design: prev.design, planHash: prev.planHash, hash: "sha256:" + prev.planHash, at: prev.at, replayed: true },
+    };
+  }
+  if (expectedHash != null && bareHash(expectedHash) !== hashPlan(planPath)) {
+    return refusal(409, "stale_subject", "plan.md changed since this plan was reviewed", {
+      expected: expectedHash,
+      current: planSubjectHash(deckDir),
+    });
+  }
+  if (decision === "done") {
+    writePlanPage(deckDir);
+    return { status: 200, body: { ok: true, decision, hash: planSubjectHash(deckDir), at } };
+  }
+  // A design picked at the gate rides with the answer; checked before anything
+  // is written, so an unknown one refuses the whole answer, not half of it.
+  const wantDesign = typeof payload?.design === "string" && payload.design ? payload.design : null;
+  if (wantDesign && !cachedDesign(wantDesign)) {
+    return refusal(422, "unknown_design", `design '${wantDesign}' is not cached on this machine`);
+  }
+  const { frontmatterRaw, body } = splitPlanFrontmatter(fs.readFileSync(planPath, "utf8"));
+  const applied = applyPlanEdit({
+    planPath,
+    frontmatterRaw,
+    body,
+    editedPlan: typeof payload?.editedPlan === "string" ? payload.editedPlan : null,
+  });
+  // `payload.edited`: the workspace committed the human's edit just before this
+  // answer (so the answer is about the edited plan); the record still says so.
+  const edited = applied.edited || payload?.edited === true;
+  const comments = decision === "comments" ? normalizePlanComments(payload?.comments) : [];
+  // An approved revision makes the plan the source of approved intent again:
+  // every image use a targeted edit recorded out-of-band is folded into its
+  // slide's storyboard and cleared. BEFORE the hash, so the planHash recorded
+  // with the approval is the hash of the plan that was folded into — otherwise
+  // the very next command would read the plan as changed since sign-off.
+  if (decision === "approve") noteImageUseReconcile(deckDir);
+  const switched = wantDesign ? switchPlanDesign(deckDir, wantDesign) : null;
+  const design = switched && !switched.error ? switched : null;
+  const planHash = hashPlan(planPath);
+  write(deckDir, {
+    version: 3,
+    decision,
+    comments,
+    edited,
+    planHash,
+    storyHash: planStoryHash(deckDir),
+    at,
+    ...(design ? { design } : {}),
+    ...(operationId ? { operationId } : {}),
+    ...(actor ? { actor } : {}),
+  });
+  return { status: 200, body: { ok: true, decision, comments, edited, design, planHash, hash: "sha256:" + planHash, at } };
+}
+
 export async function runPlanReview({
   deckDir,
   port = null,
   timeoutMs = DEFAULT_TIMEOUT_MS,
+  // null = decide (gateUsesWorkspace); tests force either path
+  useWorkspace = null,
   // quiet: serveAndOpen's BROWSER: line owns all open/failed messaging.
   open = (url) => openInBrowser(url, { quiet: true }),
   openFailedGraceMs = OPEN_FAILED_GRACE_MS,
 } = {}) {
-  const base = path.basename(deckDir);
+  const base = deckSlug(deckDir);
   const planPath = path.join(deckDir, "plan.md");
   if (!fs.existsSync(planPath)) {
     process.stderr.write(
@@ -1005,31 +1487,67 @@ export async function runPlanReview({
     return;
   }
 
-  for (const line of planDeliverableWarnings(deckDir, fs.readFileSync(planPath, "utf8"))) {
-    process.stdout.write(`  ${line}\n`);
-  }
+  // A plan that fails the plan checks opens no round (refuse). Only a NEW round
+  // is checked: handing over an answer the user already gave never is.
+  const refuse = () => {
+    const why = planRefusal(deckDir);
+    if (why) {
+      process.stdout.write(why);
+      process.exitCode = 1;
+    }
+    return why;
+  };
 
   // Headless simulation runs (scripts/codex-sim.mjs): approve without a browser.
   if (process.env.SLIDEMIND_GATE_AUTOAPPROVE === "1") {
+    if (refuse()) return null;
+    noteImageUseReconcile(deckDir);
     savePlanState(deckDir, {
       version: 3,
       decision: "approve",
       comments: [],
       edited: false,
       planHash: hashPlan(planPath),
+      storyHash: planStoryHash(deckDir),
       at: new Date().toISOString(),
     });
     process.stdout.write(
       "DECISION: approved\n" +
         "Auto-approved via SLIDEMIND_GATE_AUTOAPPROVE — no human reviewed this plan. " +
-        "Proceed to author the slides.\n",
+        `Next: ${NEXT_AFTER_APPROVAL}\n`,
     );
     return { decision: "approve", comments: [] };
   }
 
-  const { frontmatterRaw, body, bodyStartLine } = splitPlanFrontmatter(
-    fs.readFileSync(planPath, "utf8"),
-  );
+  // The human answers in the workspace: ask there and return at once (ASK + SAY;
+  // the agent ends its turn). The user's pasted message names this command again,
+  // which then hands their answer over. A workspace that cannot be used is a
+  // blocker — never a second, standalone page (doc 21). Only headless runs and
+  // SLIDEMIND_WORKSPACE=0 reach the standalone gate below.
+  const gate = await import("../workspace/gate-client.mjs");
+  if (useWorkspace ?? gate.gateUsesWorkspace(deckDir, "plan-approval")) {
+    const r = await gate.runWorkspaceGate({
+      deckDir,
+      kind: "plan-approval",
+      approvedNow: () => planApprovedExactly(deckDir),
+      refuseOpen: () => planRefusal(deckDir),
+      // the plan as it stands is the one the user last saved in the workspace's editor: they edited it
+      format: (task, { note }) => process.stdout.write(formatPlanTaskDecision(deckDir, task, { note, editedInPage: gate.planLastSavedInPage(deckDir) })),
+    });
+    if (r.refused) {
+      process.exitCode = 1;
+      return null;
+    }
+    if (r.blocked) {
+      process.stdout.write(`BLOCKED: ${r.blocked.code}\n${r.blocked.message}\n`);
+      process.exitCode = 2;
+      return null;
+    }
+    return r.decision === "pending" ? null : { decision: r.decision };
+  }
+
+  if (refuse()) return null;
+  const { body, bodyStartLine } = splitPlanFrontmatter(fs.readFileSync(planPath, "utf8"));
 
   // The plan window's logo is the add-in's genuine per-brand orb when a bundle
   // is materialized (dark variant preferred, matching the dark UI). Absent a
@@ -1037,7 +1555,7 @@ export async function runPlanReview({
   const mark = resolveBrandAsset(deckDir, ["logoMarkDark", "logoMark", "logoMarkLight"]);
   const logoMark = mark ? "/brand/logo" : null;
   const brandAssetPath = mark?.path ?? null;
-  const { layouts, chromeDir } = resolvePlanLayouts(deckDir);
+  const { layouts } = resolvePlanLayouts(deckDir);
 
   const prev = loadPlanState(deckDir);
 
@@ -1052,7 +1570,7 @@ export async function runPlanReview({
     // (the plan gate's analogue of review.json's ghost pins).
     ledgerSeed: prev.comments || [],
     layouts,
-    chromeDir,
+    designs: planDesignOptions(deckDir),
     port: wantPort,
   });
   // A waiting tab can only exist when the previous round ended in comments — so
@@ -1103,40 +1621,18 @@ export async function runPlanReview({
     server.close();
   }
 
-  const { edited } = applyPlanEdit({
-    planPath,
-    frontmatterRaw,
-    body,
-    editedPlan: decision.editedPlan,
-  });
-
-  const comments = normalizePlanComments(decision.comments);
-  savePlanState(deckDir, {
-    version: 3,
-    decision: decision.decision,
-    comments,
-    edited,
-    planHash: hashPlan(planPath),
-    at: new Date().toISOString(),
+  const answered = respondPlan(deckDir, {
+    action: decision.decision,
+    payload: { comments: decision.comments, editedPlan: decision.editedPlan, design: decision.design },
   });
+  if (answered.status !== 200) throw new Error(answered.body.error.message);
+  const { edited, comments, design } = answered.body;
 
   if (decision.decision === "approve") {
-    if (edited) {
-      process.stdout.write(
-        "DECISION: approved\n" +
-          "The user approved the plan — and edited plan.md directly before approving. " +
-          `Re-read ${deckDir}/plan.md: the edited text IS the approved plan. Author from ` +
-          "it, not from your earlier draft.\n",
-      );
-    } else {
-      process.stdout.write(
-        "DECISION: approved\n" +
-          "The user approved the plan. Proceed to author the slides — the plan is agreed.\n",
-      );
-    }
+    process.stdout.write(planApprovedText(deckDir, { edited, design }));
   } else {
     process.stdout.write(
-      formatPlanCommentsForHarness(deckDir, comments, { edited }),
+      formatPlanCommentsForHarness(deckDir, comments, { edited, design }),
     );
   }
   return decision;
@@ -1153,6 +1649,13 @@ function parseArgs(argv) {
       args.deck = argv[++i];
     } else if (a === "--port" && i + 1 < argv.length) {
       args.port = parseInt(argv[++i], 10) || 0;
+    } else if (a === "--wait" && i + 1 < argv.length) {
+      // retired with the bounded wait (a question returns at once); accepted so a
+      // stale skill or script that still passes it does not fail
+      i++;
+    } else if (a === "--json") {
+      // Accepted like every deck command's --json (SKILL.md); the gate's
+      // output already is its machine contract — the one DECISION: line.
     } else if (a === "-h" || a === "--help") {
       process.stdout.write(usage);
       process.exit(0);