slidemind 0.3.20 → 0.4.1

package/src/cli/concepts.mjs

@@ -2,6 +2,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { fail, requirePlanApproved, resolveDeckArg, freshenDeckBundle, base64FromDataUri, SRC_DIR, BUILDERS_DIR } from "./common.mjs";
+import { deckSlug } from "../lib/deck-paths.mjs";
+import { pidAlive } from "../lib/revision.mjs";
+import { imageDigest, mockupFileFor, replaceMockup, specSlidesByState, specState } from "../lib/concept-spec-binding.mjs";
+import { engineFailure } from "../builders/asset-fetch.mjs";
+import { SPECS_UNSUPPORTED, specsUnsupportedPayload, specsUnsupportedWarning } from "./concept-spec-support.mjs";
 
 export const REFERENCE_MIME = {
   ".png": "image/png",
@@ -11,8 +16,10 @@ export const REFERENCE_MIME = {
   ".gif": "image/gif",
 };
 
-// `--concept <image>[@N,M]` / `--style <image>[@N,M]` → one inline reference
-// `{ role, image, slides?, name }` for the concept-images route.
+// `--concept <image>[@N,M]` / `--style <image>[@N,M]` → the flag, parsed:
+// `{ role, file, slides?, name }`. The image-intent adapter imports `file`
+// (src/builders/legacy-reference-uses.mjs) and records the use in plan.md; the
+// request then carries it in the image-intent envelope, never as a flag.
 export function readReferenceArg(role, spec) {
   if (!spec) fail(`--${role} expects <image>[@slides]`);
   const at = spec.lastIndexOf("@");
@@ -28,26 +35,169 @@ export function readReferenceArg(role, spec) {
   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`);
-  }
+  if (!REFERENCE_MIME[path.extname(file).toLowerCase()]) fail(`--${role} ${file}: expected a png/jpg/webp/gif image`);
+  if (!fs.existsSync(file)) fail(`--${role} ${file}: file not found`);
   return {
     role,
-    image: `data:${mime};base64,${bytes.toString("base64")}`,
+    file,
     ...(slides.length > 0 ? { slides } : {}),
     name: path.basename(file),
   };
 }
 
+/**
+ * The plan's image obligations as the trailing block of `concepts`' human
+ * output (`imageObligations()` builds the records; `--json` carries the same
+ * ones as `imageUses`).
+ *
+ * It prints on every exit that has any, including the ones with no mockup and
+ * no spec at all: a frame slide, and a deck whose backend cannot generate or
+ * extract. The source path is what the slide's `<img>` references, so the agent
+ * can author the picture straight from the plan.
+ */
+export function imageUseLines(uses) {
+  if (!uses?.length) return "";
+  const lines = [
+    `IMAGE USES: ${uses.length} from the plan — an \`original\` must appear as that exact file; it is never searched for, regenerated or recoloured.`,
+  ];
+  for (const u of uses) {
+    const where = u.frame ? `slide ${u.slide} (frame slide, no mockup)` : `slide ${u.slide}`;
+    const src = u.source
+      ? `./${u.source}${u.displayName ? ` ("${u.displayName}")` : ""}`
+      : `source ${u.assetId} is not in this deck's registry`;
+    lines.push(`  ${where} · ${u.useId} · ${u.obligation} · ${src} — "${u.instruction}"`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * The image-intent half of one `slides[]` entry of a spec request: the
+ * fingerprint RECORDED beside that slide's mockup, or nothing.
+ *
+ * Two rules, and its own function so that a test can hold it to them.
+ *
+ * **Recorded, never recomputed.** At request time the recorded value and a
+ * freshly computed one are always equal — the local staleness guard either
+ * regenerates a slide whose intent moved (rewriting the record) or skips it, so
+ * no reachable state has them differ. Nothing observable would therefore
+ * distinguish `recordedIntent[slide]` from a fresh `slideIntentFingerprints()`
+ * call, and swapping one for the other would quietly turn the server's
+ * staleness check into a no-op that always passes. This signature cannot
+ * compute a fingerprint, so a unit test can hand it a value no computation
+ * could produce and see it arrive verbatim.
+ *
+ * **No envelope, no fingerprint.** The server checks a declared fingerprint
+ * against the intent THIS request carries; declaring one without the envelope
+ * compares it against "no uses" and refuses the slide.
+ */
+export function specIntentFields(recordedIntent, imageIntent, slide) {
+  const recorded = imageIntent ? (recordedIntent?.[slide] ?? null) : null;
+  return recorded ? { intentFingerprint: recorded } : {};
+}
+
+// Two spec requests of four slides, not one of eight: a sync request died at the
+// ingress's ~240 s on dense slides, and one 8-slide deck run sequentially cost 9
+// minutes of empty polling (x27). Four keeps each body under ~8 MB.
+export const SPEC_BATCH = 4;
+
+// Is a failed spec read worth another `concepts` run? The one rule, for both
+// kinds of failure:
+//   - `thrown`: the request itself failed (a client timeout, a 429, a relay or
+//     gateway error) — it says nothing about the mockup: re-run.
+//   - `answer`: a per-slide failure inside a response the server did give. Only
+//     a rate limit is a re-run; an abort or timeout there means the server
+//     spent its whole per-slide budget on that slide, so on the retry pass —
+//     the second time — the slide is authored from its concept by hand
+//     (`workflow/create.md`, step 2).
+// `wireFailed` carries a first pass that threw: its slides were never read at
+// all, so nothing the retry answers can make them unreadable. A transient
+// failure is never sent to hand authoring: `transcribe` refuses while a spec is
+// still owed (x69: a timed-out POST said "author from its PNG", transcribe
+// exited 1, a plain re-run read 3/3).
+export function transientSpecFailure({ wireFailed = false, thrown = null, answer = null } = {}) {
+  const text = (x) => String(x?.message ?? x ?? "");
+  const rateLimited = (x) => x?.status === 429 || x?.code === "rate_limited" || /\b429\b|rate.?limit|too many requests/i.test(text(x));
+  if (wireFailed) return true;
+  if (thrown) {
+    return rateLimited(thrown) || thrown.code === "bridge_timeout" || engineFailure(thrown).retryable ||
+      /timed out|abort|connection error/i.test(text(thrown));
+  }
+  return rateLimited(answer);
+}
+
+export function specFailureLine(f, deck) {
+  if (f.code === "image_intent_stale") return `slidemind: slide ${f.slide} — ${f.error}`;
+  return f.transient
+    ? `slidemind: concept spec for slide ${f.slide} not read (${f.error}) — a transient failure, not the mockup; re-run \`slidemind concepts ${deck}\` before transcribe (it asks only for the missing slides).`
+    : `slidemind: concept spec for slide ${f.slide} failed on both passes (${f.error}) — author that slide by hand from its concept against its layout (workflow/create.md, step 2); write its file before \`slidemind transcribe ${deck}\`, which then writes the others.`;
+}
+
+// The same two remedies, folded into the one CONCEPTS line.
+export function specFailureNote(failed, deck) {
+  const slides = (transient) => failed
+    .filter((f) => f.code !== "image_intent_stale" && Boolean(f.transient) === transient)
+    .map((f) => f.slide)
+    .sort((a, b) => a - b);
+  const [rerun, unreadable] = [slides(true), slides(false)];
+  const s = (list) => (list.length === 1 ? "" : "s");
+  return [
+    rerun.length ? `slide${s(rerun)} ${rerun.join(", ")} not read (transient) — re-run \`slidemind concepts ${deck}\` before transcribe` : "",
+    unreadable.length ? `slide${s(unreadable)} ${unreadable.join(", ")} unreadable — author ${unreadable.length === 1 ? "it" : "them"} by hand from the concept (workflow/create.md, step 2)` : "",
+  ].filter(Boolean).join("; ");
+}
+
+/**
+ * Cut the spec-extraction work into requests, grouped by SLOT and never by
+ * slide number.
+ *
+ * `slot` is a REQUEST-level field — every slide in one request is measured
+ * against it — and consecutive slides rarely share a layout (cover, content,
+ * divider). A batch cut by index therefore mapped every element rect of its
+ * 2nd..4th slide onto geometry belonging to its 1st. The tone was already
+ * resolved per slide; the slot has to be too.
+ *
+ * Slot identity is the slot's VALUE, not the layout's name: two layouts with
+ * the same content rect measure identically and may share a request.
+ */
+export function batchBySlot(items, slotOf, size = SPEC_BATCH, { weightOf = null, maxBytes = 0 } = {}) {
+  const bySlot = new Map();
+  for (const item of items) {
+    const slot = slotOf(item);
+    const key = JSON.stringify(slot ?? null);
+    if (!bySlot.has(key)) bySlot.set(key, { slot, items: [] });
+    bySlot.get(key).items.push(item);
+  }
+  const batches = [];
+  for (const { slot, items: group } of bySlot.values()) {
+    let batch = [];
+    let bytes = 0;
+    for (const item of group) {
+      const weight = weightOf ? weightOf(item) : 0;
+      // Two ceilings, whichever comes first: the slide COUNT (four dense slides
+      // is what the server parallelises well) and the encoded BYTE size of what
+      // this request will actually carry. The count alone stopped being a proxy
+      // for the size the moment a request could also carry source images — four
+      // slides of ordinary mockups is a few MB, four with screenshots attached
+      // is not. An item heavier than the whole budget still gets its own
+      // request: the list is never shortened to make it fit (guide §4).
+      if (batch.length && (batch.length >= size || (maxBytes > 0 && bytes + weight > maxBytes))) {
+        batches.push({ slot, batch });
+        batch = [];
+        bytes = 0;
+      }
+      batch.push(item);
+      bytes += weight;
+    }
+    if (batch.length) batches.push({ slot, batch });
+  }
+  return batches;
+}
+
 export async function cmdConceptImages(rest) {
   let deck = null;
   let force = false;
   let asJson = false;
+  let statusOnly = false;
   const references = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
@@ -58,6 +208,8 @@ export async function cmdConceptImages(rest) {
       force = true;
     } else if (a === "--json") {
       asJson = true;
+    } else if (a === "--status") {
+      statusOnly = 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.
@@ -73,6 +225,29 @@ export async function cmdConceptImages(rest) {
   if (!deck) fail("usage: slidemind concepts <deck>");
 
   const deckDir = resolveDeckArg(deck);
+  // Whether a run is in progress and how far it got, read from disk — the
+  // agent's sandbox blocks ps, and without this it started concepts again
+  // (x51, x53, x58: four to five runs on one deck).
+  if (statusOnly) {
+    let running = null;
+    try {
+      const holder = JSON.parse(fs.readFileSync(path.join(deckDir, "state", "concepts.lock"), "utf8"));
+      if (pidAlive(holder.pid)) running = holder;
+    } catch {}
+    const count = (dir, re) => { try { return fs.readdirSync(dir).filter((f) => re.test(f)).length; } catch { return 0; } };
+    const mockups = count(path.join(deckDir, "concepts"), /^concept-slide-\d+\.png$/);
+    // Only a spec read from the mockup now on disk counts; one read from an
+    // earlier picture is named, not counted (concept-spec-binding.mjs).
+    const { current, outdated } = specSlidesByState(deckDir);
+    const specs = current.length;
+    const status = { deck: deckSlug(deckDir), running: Boolean(running), since: running?.at ?? null, mockups, specs, outdatedSpecs: outdated };
+    process.stdout.write(asJson
+      ? `${JSON.stringify(status)}\n`
+      : `CONCEPTS: ${running ? `running since ${running.at}` : "not running"} — ${mockups} mockup${mockups === 1 ? "" : "s"}, ${specs} spec${specs === 1 ? "" : "s"} on disk` +
+          (outdated.length ? ` (slide${outdated.length === 1 ? "" : "s"} ${outdated.join(", ")}: spec not read from the mockup on disk — the next \`concepts\` run reads ${outdated.length === 1 ? "it" : "them"} again)` : "") +
+          `${running ? "; wait, do not start another run" : ""}\n`);
+    return;
+  }
   const planPath = path.join(deckDir, "plan.md");
   if (!fs.existsSync(planPath)) {
     fail(
@@ -80,42 +255,522 @@ export async function cmdConceptImages(rest) {
         `Run \`slidemind plan ${deck}\` to compose and sign off a plan first.`,
     );
   }
+  // The legacy flags become durable image uses BEFORE anything reads the plan:
+  // the file is imported into the deck's registry and the use is recorded in
+  // plan.md, where the user reviews it. A changed plan then re-arms the
+  // existing sign-off gate below — this never approves anything itself.
+  if (references.length) await adaptLegacyReferences(deckDir, references, deck);
+
   const planMarkdown = fs.readFileSync(planPath, "utf8");
   // Every exit ends on ONE machine-readable line — `CONCEPTS: n/m …` — so a
   // harness that cut the output short, and an agent reading a summary, can
   // tell "generated", "none available" and "still running" apart without a
   // double-evidence ritual. --json prints the same facts as a payload.
-  const finish = ({ paths = [], planned = 0, status, reason = null, missing = [], seeded = false, extra = "" }) => {
+  const finish = async ({ paths = [], planned = 0, status, reason = null, missing = [], extra = "" }) => {
     const conceptsDir = path.join(deckDir, "concepts");
+    // The spec step runs on every exit that has mockups on disk — generated
+    // now or re-printed from disk — so a deck whose specs failed last time
+    // (or predate a newer add-in) gets them on the next `concepts` call.
+    const specs = paths.length ? await ensureConceptSpecs(paths) : { written: [], failed: [], skipped: null, unsupported: null };
+    // An add-in that cannot read mockups at all is said on stderr in every
+    // mode: the `--json` field alone is what let a designer agent walk past it.
+    if (specs.unsupported) for (const line of specsUnsupportedWarning(specs.unsupported, deck)) process.stderr.write(`${line}\n`);
+    const imageUses = await imageObligations();
+    const notes = conceptIntent.readConceptNotes(deckDir);
+    const onDisk = paths.map((p) => Number(/concept-slide-(\d+)\.png$/.exec(p)?.[1])).filter(Boolean);
+    const noteLines = conceptIntent.conceptNoteLines(notes, onDisk);
     if (asJson) {
+      const conceptNotes = Object.fromEntries(onDisk.filter((n) => notes[n]).map((n) => [n, notes[n]]));
       process.stdout.write(
-        `${JSON.stringify({ deck: path.basename(deckDir), status, generated: paths.length, planned, paths, missing, reason, conceptsDir, assetPlan: path.join(deckDir, "asset-plan.md"), seededAssetPlan: seeded }, null, 2)}\n`,
+        `${JSON.stringify({ deck: deckSlug(deckDir), status, generated: paths.length, planned, paths, specs: specs.written, specsFailed: specs.failed, specsSkipped: specs.skipped, specsUnsupported: specsUnsupportedPayload(specs.unsupported, deck), missing, imageUses, conceptNotes, notes: noteLines, reason, conceptsDir }, null, 2)}\n`,
       );
     } else {
       if (paths.length) process.stdout.write(paths.join("\n") + "\n");
+      const usage = specUsageTotals(deckDir);
+      const unread = specFailureNote(specs.failed, deck);
+      // A skipped read keeps the specs already on disk (a re-run in an outage,
+      // an unbound deck): the PNG is the source only while there are none.
+      const specNote = paths.length
+        ? specs.skipped
+          ? specs.written.length
+            ? ` — ${specs.written.length}/${paths.length} specs on disk (${specs.skipped}); next: \`slidemind transcribe ${deck}\``
+            : ` — no specs (${specs.skipped}) — Read each PNG, then rebuild as slide JSX (workflow/create.md).`
+          : (specs.written.length ? ` — ${specs.written.length}/${paths.length} read into specs${usage.slides ? ` (${usage.model ?? "vision model"}: ${Math.round(usage.inputTokens / 1000)}k in / ${Math.round(usage.outputTokens / 1000)}k out)` : ""}` : "") +
+            (unread ? ` — ${unread}` : "") +
+            (specs.written.length && !specs.failed.some((f) => f.transient) ? `; next: \`slidemind transcribe ${deck}\`` : "")
+        : "";
       process.stdout.write(
         `CONCEPTS: ${paths.length}/${planned} ${status}${reason ? ` — ${reason}` : ""}` +
           (missing.length ? ` (no mockup for slide${missing.length > 1 ? "s" : ""} ${missing.join(", ")} — author from the storyboard)` : "") +
-          (paths.length ? ` — Read each PNG, then rebuild as slide JSX (workflow/create.md).` : "") +
-          `\n${extra}`,
+          specNote +
+          `\n${imageUseLines(imageUses)}${noteLines.map((l) => `${l}\n`).join("")}${extra}`,
       );
     }
     process.exit(0);
   };
+
+  // Concept specs: the add-in's vision inventory of each mockup (elements with
+  // slot-pixel rects, verbatim text, icons, connectors, charts). Written once
+  // per PNG as .spec.json for mechanical transcription; `--force` rewrites.
+  // Never fatal: a slide without a spec gets a re-run or its storyboard
+  // (specFailureLine), never its PNG.
+  const specMod = await import(pathToFileURL(path.join(BUILDERS_DIR, "concept-spec.mjs")).href);
+  const bundleForSpecs = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href);
+  // The deck's image intent: what each slide's approved uses fingerprint to
+  // (src/bridge/image-intent-envelope.mjs) and what the mockups on disk were
+  // generated under (src/builders/concept-intent.mjs).
+  const intentMod = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "image-intent-envelope.mjs")).href);
+  const conceptIntent = await import(pathToFileURL(path.join(BUILDERS_DIR, "concept-intent.mjs")).href);
+  // The slides whose mockup on disk was generated under a DIFFERENT image
+  // intent than the plan now carries (filled in below, once the planned set is
+  // known). Marking, not deleting: the bytes stay — they may be the only copy,
+  // and one of them may be a mockup a human supplied — but every path that
+  // would REUSE them is closed against this set (design decision 6).
+  const staleSlides = new Set();
+  // The slides whose mockup THIS RUN actually rewrote. A stale slide is only
+  // safe to read into a spec once it is in here: everywhere else the file on
+  // disk is still the one the mark refers to.
+  const regeneratedSlides = new Set();
+  // The fingerprint each slide's SPEC is keyed by — the same approved uses in
+  // the `spec` context, plus the generation of the persisted spec shape. It is
+  // a second fingerprint on purpose: a mockup and the inventory read out of it
+  // are separate derived outputs, and `concepts` routinely hands a slide a
+  // current mockup (adopted, or regenerated in an earlier run) beside a spec
+  // that was read before the plan carried the image at all. Filled in below,
+  // once the planned set is known.
+  let specFingerprints = new Map();
+  const sbForSpecs = await import(pathToFileURL(path.join(BUILDERS_DIR, "storyboard-markdown.mjs")).href);
+  const storyboardBySlide = new Map();
+  for (const segment of sbForSpecs.splitPlanMarkdownIntoSegments(planMarkdown)) {
+    if (segment.type === "storyboard" && segment.data?.slide) storyboardBySlide.set(segment.data.slide, segment.data);
+  }
+  /**
+   * Every image obligation the PLAN carries, for every slide it names — frame
+   * slides included.
+   *
+   * A frame slide (cover, divider, closing) gets no mockup and no spec by
+   * design, and a backend that cannot generate or extract leaves a body slide
+   * in exactly the same position: no picture to read, no inventory to read it
+   * into. The obligation is the plan's either way, so it is reported FROM the
+   * plan on every exit. Nothing here needs a spec to exist, nothing invents one,
+   * and a missing concept service cannot relax what the user approved
+   * (design decision 4; guide §5, A19).
+   */
+  async function imageObligations() {
+    const slides = [...storyboardBySlide.keys()].sort((a, b) => a - b);
+    if (!slides.length) return [];
+    const uses = intentMod.effectiveUsesForSlides(deckDir, slides, { planMarkdown });
+    if (![...uses.values()].some((list) => list.length)) return [];
+    const { describeUse } = await import(pathToFileURL(path.join(SRC_DIR, "lib", "image-intent.mjs")).href);
+    const { readImageAssetManifest } = await import(pathToFileURL(path.join(SRC_DIR, "lib", "image-assets.mjs")).href);
+    // A registry that cannot be read costs the lines their file name, never the
+    // obligation itself — the one thing this must not be able to drop.
+    let byId = new Map();
+    try {
+      byId = new Map(readImageAssetManifest(deckDir).assets.map((a) => [a.assetId, a]));
+    } catch {}
+    const frames = new Set(frameSlides.map((f) => f.slideNumber));
+    const out = [];
+    for (const slide of slides) {
+      for (const use of uses.get(slide) ?? []) {
+        const asset = byId.get(use.assetId) ?? null;
+        out.push({
+          slide,
+          frame: frames.has(slide),
+          useId: use.useId,
+          assetId: use.assetId,
+          fidelity: use.fidelity,
+          obligation: describeUse(use),
+          instruction: use.instruction,
+          source: asset?.workspacePath ?? null,
+          displayName: asset?.displayName ?? null,
+        });
+      }
+    }
+    return out;
+  }
+
+  // The model tokens the deck's specs cost, summed from the spec files.
+  function specUsageTotals(dir) {
+    const t = { slides: 0, inputTokens: 0, outputTokens: 0, model: null };
+    for (const n of specMod.listSpecSlides(dir)) {
+      const u = specMod.readSpec(dir, n)?.usage;
+      if (!u) continue;
+      t.slides++;
+      t.inputTokens += u.inputTokens ?? 0;
+      t.outputTokens += u.outputTokens ?? 0;
+      t.model ??= u.model ?? null;
+    }
+    return t;
+  }
+  async function ensureConceptSpecs(pngPaths) {
+    const conceptsDir = path.join(deckDir, "concepts");
+    const todo = [];
+    const written = [];
+    const staleUnreplaced = [];
+    // Specs on disk whose recorded identity no longer matches the plan's.
+    const refused = [];
+    // Specs on disk that were not read from the mockup now beside them.
+    const rebound = [];
+    for (const png of pngPaths) {
+      const m = /concept-slide-(\d+)\.png$/.exec(png);
+      if (!m) continue;
+      const n = Number(m[1]);
+      // The mockup on disk is the one whose image intent changed, and nothing
+      // replaced it this run (generation was unavailable, or failed for this
+      // slide). Reading a spec from it would inventory a picture the plan no
+      // longer describes AND record that inventory as current — the same silent
+      // reuse the fast path and the spec reuse below already refuse. The guard
+      // is structural on purpose: it must not rest on the extraction backend
+      // happening to be unreachable too, which is only true while
+      // `conceptSpecs` and `conceptImages` travel together.
+      if (staleSlides.has(n) && !regeneratedSlides.has(n)) {
+        staleUnreplaced.push(n);
+        continue;
+      }
+      // A spec read from a mockup whose image intent has since changed cannot
+      // be reused either: nothing is deleted, so the old spec stays readable
+      // until a new one replaces it. Nor can one read from other bytes than
+      // the mockup on disk, or with no record of its bytes: a spec is the
+      // inventory of one picture (concept-spec-binding.mjs, x112 GTM).
+      const state = force || staleSlides.has(n) ? null : specState(deckDir, n);
+      const onDisk = state?.status === "current" ? state.spec : null;
+      if (state && state.status !== "current" && state.status !== "absent") rebound.push(n);
+      if (onDisk) {
+        // The spec's own identity, checked against the plan as it stands. Since
+        // NOTHING is deleted on a mismatch, a reusable-looking file is sitting
+        // right there and the refusal has to be explicit — an absent spec means
+        // "not read yet", never "the stale one was cleaned up".
+        //
+        // null === null is the legacy case and stays reusable: a slide with no
+        // image uses records no fingerprint, and neither did any spec written
+        // before this contract existed.
+        const want = specFingerprints.get(n) ?? null;
+        if ((onDisk.intentFingerprint ?? null) === want) {
+          written.push(specMod.specFileFor(deckDir, n));
+          continue;
+        }
+        refused.push(n);
+      }
+      todo.push({ n, png });
+    }
+    if (staleUnreplaced.length) {
+      const one = staleUnreplaced.length === 1;
+      process.stderr.write(
+        `slidemind: slide${one ? "" : "s"} ${staleUnreplaced.join(", ")} still show${one ? "s" : ""} the earlier image intent — ` +
+          `no spec is read from ${one ? "that mockup" : "those mockups"}, and the spec${one ? "" : "s"} already on disk ` +
+          `${one ? "is" : "are"} left as ${one ? "it is" : "they are"}. Re-run once a backend can regenerate ${one ? "it" : "them"}.\n`,
+      );
+    }
+    if (rebound.length) {
+      const one = rebound.length === 1;
+      process.stderr.write(
+        `slidemind: the spec${one ? "" : "s"} on disk for slide${one ? "" : "s"} ${rebound.join(", ")} ` +
+          `${one ? "was" : "were"} not read from the mockup now on disk — read again below.\n`,
+      );
+    }
+    if (refused.length) {
+      const one = refused.length === 1;
+      process.stderr.write(
+        `slidemind: the spec${one ? "" : "s"} on disk for slide${one ? "" : "s"} ${refused.join(", ")} ` +
+          `${one ? "was" : "were"} read under a different image intent — ${one ? "it is" : "they are"} not reused; ` +
+          `${one ? "the file stays" : "the files stay"} on disk until a new read replaces ${one ? "it" : "them"}.\n`,
+      );
+    }
+    // The plan's layout, resolved against the bundle as the add-in resolves it,
+    // and its content slot. A slide on a layout with no slot (or one the design
+    // does not carry) takes no inventory: it is said once, and transcribe owes
+    // it nothing either.
+    const bundleDir = bundleForSpecs.resolveBundleDirForDeck(deckDir);
+    const slotBySlide = new Map();
+    for (const item of [...todo]) {
+      const planned = storyboardBySlide.get(item.n)?.layout;
+      const resolved = specMod.plannedLayoutSlot(bundleDir, planned);
+      if (resolved.slot) {
+        slotBySlide.set(item.n, resolved.slot);
+        continue;
+      }
+      todo.splice(todo.indexOf(item), 1);
+      process.stderr.write(`slidemind: slide ${item.n}: ${specMod.layoutSlotNote(planned, resolved)}\n`);
+    }
+    if (todo.length === 0) return { written, failed: [], skipped: null };
+    const brandIdForSpecs = bundleForSpecs.readDeckBundleRef(deckDir)?.presFP ?? null;
+    if (!brandIdForSpecs) return { written, failed: [], skipped: "deck not bound to a design" };
+    const clientForSpecs = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href);
+    let backendForSpecs;
+    try {
+      backendForSpecs = await clientForSpecs.resolveConceptBackend();
+    } catch {
+      return { written, failed: [], skipped: "this add-in has no concept route" };
+    }
+    if (!backendForSpecs) {
+      // Several capable backends: like the mockup generation, the design's
+      // brandId is globally unique, so the first backend that answers 2xx
+      // for it is the one (getDesignBundleForBrandAnyBackend does the same).
+      const transport = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "client", "transport.mjs")).href);
+      for (const sess of transport.sessionsInScope()) {
+        try {
+          await clientForSpecs.getDesignBundleForBrand(brandIdForSpecs, { backendURL: sess.backendURL });
+          backendForSpecs = sess.backendURL;
+          break;
+        } catch {}
+      }
+      if (!backendForSpecs) return { written, failed: [], skipped: "no connected backend serves this design" };
+    }
+    // Asked BEFORE the "reading N mockups" line: an add-in without the reader
+    // used to be announced as a 2–6 minute vision pass and then dropped to a
+    // JSON string (2026-10-06 proposal sim). `unknown` keeps the old path —
+    // the extraction call asks again and decides.
+    const specSupport = await clientForSpecs.conceptSpecSupport(backendForSpecs);
+    const unsupportedDetail = () => ({ ...specSupport, slides: todo.map((t) => t.n) });
+    if (specSupport.status === "unsupported") {
+      return { written, failed: [], skipped: SPECS_UNSUPPORTED, unsupported: unsupportedDetail() };
+    }
+    // This design's own colours, by name, travel with the request: the reader
+    // NAMES the colour it means instead of leaving a hex for the CLI to match
+    // by nearest-neighbour afterwards. Whatever tokens the bundle ships are
+    // what it gets — nothing here knows a colour or a token name.
+    const { readColorTokens, readTypeRamp } = await import(pathToFileURL(path.join(BUILDERS_DIR, "design-tokens.mjs")).href);
+    // Where the content slot sits on a stage this wide: the reader leaves out
+    // the template's own marks outside it.
+    const stageW = readTypeRamp(bundleDir).stageWidthPx;
+    // Preserve semantic aliases: equal hex values do not imply equal roles.
+    const palette = readColorTokens(bundleDir).map(({ name, hex }) => ({ name, hex }));
+    const failed = [];
+    process.stderr.write(
+      `slidemind: reading ${todo.length} mockup${todo.length === 1 ? "" : "s"} into specs — a vision pass of 2–6 minutes; a progress line follows every 30 s. Do not interrupt: each spec is saved as it arrives, and a re-run asks only for the rest.\n`,
+    );
+    // What the extraction request carries for the deck's approved images: the
+    // sources INLINE (the add-in's model cannot reach this machine) and, per
+    // slide, the fingerprint RECORDED beside its mockup when it was generated.
+    //
+    // The two travel together and are never split. The server checks a declared
+    // fingerprint against the intent THIS request carries, so a fingerprint
+    // without an envelope would compare against "no uses" and refuse every
+    // slide that has one. And it must be the RECORDED value, never one computed
+    // here: a fresh one always matches, which would quietly turn the server's
+    // staleness check into a no-op that no test of ours could catch.
+    const recordedIntent = conceptIntent.readConceptIntent(deckDir);
+    // Every batch in flight at once: the server inventories a batch's slides
+    // in parallel, and one 8-slide deck run sequentially cost 9 minutes of
+    // empty polling (x27). Two requests of four keep each body under ~8 MB.
+    let batches;
+    const envelopes = new Map();
+    try {
+      // The second term of the byte budget: the sources a slide's uses put on
+      // the wire, base64'd (+1/3). An asset used by two slides of one batch
+      // travels once, so this over-counts it — the safe direction for a
+      // ceiling, and the batch is not known until after the cut.
+      const intentBytes = new Map();
+      const uses = intentMod.effectiveUsesForSlides(deckDir, todo.map((item) => item.n), { planMarkdown });
+      if ([...uses.values()].some((list) => list.length)) {
+        const { readImageAssetManifest } = await import(pathToFileURL(path.join(SRC_DIR, "lib", "image-assets.mjs")).href);
+        const sizeOf = new Map(readImageAssetManifest(deckDir).assets.map((a) => [a.assetId, a.byteLength]));
+        for (const [slide, list] of uses) {
+          const bytes = [...new Set(list.map((use) => use.assetId))].reduce((sum, id) => sum + (sizeOf.get(id) ?? 0), 0);
+          if (bytes) intentBytes.set(slide, Math.ceil((bytes * 4) / 3));
+        }
+      }
+      batches = batchBySlot(
+        todo,
+        (item) => ({ ...slotBySlide.get(item.n), ...(stageW ? { stageW } : {}) }),
+        SPEC_BATCH,
+        {
+          // What each slide actually weighs on the wire: its mockup, base64'd
+          // (+1/3), plus the sources its image uses carry inline.
+          weightOf: (item) => {
+            let bytes = intentBytes.get(item.n) ?? 0;
+            try {
+              bytes += Math.ceil((fs.statSync(item.png).size * 4) / 3);
+            } catch {}
+            return bytes;
+          },
+          maxBytes: intentMod.IMAGE_INTENT_REQUEST_BYTE_BUDGET,
+        },
+      );
+      // Null for every batch of a deck with no image uses, so those requests
+      // serialize exactly as they did before this contract existed.
+      for (const { batch } of batches) {
+        envelopes.set(
+          batch,
+          intentMod.buildImageIntentEnvelope(deckDir, { slides: batch.map((item) => item.n), planMarkdown }),
+        );
+      }
+    } catch (err) {
+      // A registered source that is gone or no longer hashes to what the
+      // registry recorded. Extraction without it would inventory the mockup's
+      // approximation of the user's picture as slide elements — the exact
+      // substitution the contract forbids — so this stops, naming the repair.
+      if (!err?.code) throw err;
+      fail(`${err.code} — ${err.message}${err.issue?.action ? `\n${err.issue.action}` : ""}`);
+    }
+    // A capability answer belongs to the command, not to one batch: returning it
+    // from inside the map only filled an array nobody reads.
+    let unsupported = null;
+    // The bytes each slide's request carried, hashed: the spec records them, so
+    // it is only ever paired with this exact mockup.
+    const sentDigest = new Map();
+    await Promise.all(batches.map(async ({ slot, batch }) => {
+      const imageIntent = envelopes.get(batch) ?? null;
+      const slides = batch.map(({ n, png }) => {
+        const sb = storyboardBySlide.get(n);
+        const bytes = fs.readFileSync(png);
+        sentDigest.set(n, imageDigest(bytes));
+        return {
+          slide: n,
+          image: `data:image/png;base64,${bytes.toString("base64")}`,
+          // Read from the sidecar, never recomputed, and only alongside the
+          // envelope it is checked against (`specIntentFields`). A slide with no
+          // uses records none and declares none — the server deliberately does
+          // not check an entry that declares nothing, so a legacy slide's
+          // request is unchanged.
+          ...specIntentFields(recordedIntent, imageIntent, n),
+          // The whole storyboard: the add-in projects what the reader sees
+          // (`readerStoryboard` in concept-spec.ts), so this request and an
+          // in-app delegation show it the same fields — imagePrompts included,
+          // whose words the content check counts as stated.
+          storyboard: sb ? JSON.stringify(sb) : null,
+        };
+      });
+      const writeSpecs = (res) => {
+        const done = new Set();
+        for (const entry of res?.specs ?? []) {
+          const n = Number(entry?.slide);
+          if (!Number.isFinite(n) || !entry?.spec) continue;
+          // Preserve the mapped reader response BEFORE local normalization.
+          // Re-running the normalizer on its output only proves idempotence.
+          const rawDir = path.join(deckDir, "state", "reader-specs");
+          fs.mkdirSync(rawDir, { recursive: true });
+          fs.writeFileSync(path.join(rawDir, `concept-slide-${String(n).padStart(2, "0")}.json`), JSON.stringify({ ...entry.spec, imageSha256: sentDigest.get(n) ?? null }, null, 2) + "\n");
+          const { layout } = specMod.plannedLayoutSlot(bundleDir, storyboardBySlide.get(n)?.layout);
+          const spec = specMod.normalizeForLayout(entry.spec, {
+            tone: specMod.layoutToneFor(bundleDir, layout),
+          });
+          // What this inventory was read under, recorded IN the spec rather than
+          // beside it: a spec is JSON, so its identity travels with its content
+          // and a deleted spec takes its record with it — no sidecar to prune.
+          // Null for a slide with no image uses, which is what keeps a legacy
+          // spec reusable forever (design decision 6).
+          spec.intentFingerprint = specFingerprints.get(n) ?? null;
+          // The exact mockup this inventory was read from (concept-spec-binding.mjs):
+          // a spec whose mockup is later replaced is no spec of it.
+          spec.imageSha256 = sentDigest.get(n) ?? null;
+          // An original the reader could not place (or bound twice) comes back
+          // as an issue and the spec is persisted anyway — the obligation is
+          // the plan's; transcribe tells the author (specAuthorNotes), who
+          // places the picture by hand.
+          written.push(specMod.writeSpec(deckDir, n, spec));
+          done.add(n);
+        }
+        return done;
+      };
+      let res;
+      let pending = slides;
+      // A first pass that died on the wire never ANSWERED for its slides, so
+      // the second pass alone cannot call one of them unreadable.
+      let wireFailed = false;
+      try {
+        const streamedDone = new Set();
+        let lastLine = "";
+        res = await clientForSpecs.extractConceptSpecsForBrand(brandIdForSpecs, {
+          slides,
+          slot,
+          palette,
+          imageIntent,
+          backendURL: backendForSpecs,
+          onSpec: (entry) => {
+            for (const n of writeSpecs({ specs: [entry] })) streamedDone.add(n);
+          },
+          onProgress: ({ done, total, elapsedMs }) => {
+            const line = `slidemind: concept specs ${done}/${total} read (${Math.round((elapsedMs ?? 0) / 1000)}s)…`;
+            if (line !== lastLine) process.stderr.write(`${line}\n`);
+            lastLine = line;
+          },
+        });
+        if (res === null) {
+          unsupported = SPECS_UNSUPPORTED;
+          return;
+        }
+        const done = res?.streamed ? streamedDone : writeSpecs(res);
+        pending = slides.filter((s) => !done.has(s.slide));
+        // A slide the server refused because its mockup predates the intent
+        // this request carries is not one a second, cheaper read can rescue:
+        // extraction never ran for it, and the same bytes would be refused
+        // again. It leaves the retry with its own words — the repair is a new
+        // mockup, not a coarser inventory.
+        for (const f of res?.failures ?? []) {
+          const n = Number(f?.slide);
+          if (f?.code !== "image_intent_stale" || !pending.some((s) => s.slide === n)) continue;
+          pending = pending.filter((s) => s.slide !== n);
+          failed.push({ slide: n, code: f.code, error: f.error ?? "the mockup predates this request's image intent" });
+        }
+      } catch (err) {
+        // A whole-batch failure (a gateway timeout, a network drop): every
+        // slide is still pending and gets the retry below.
+        wireFailed = transientSpecFailure({ thrown: err });
+        process.stderr.write(`slidemind: concept spec batch failed (${err?.message ?? err}); reading the slides once more…\n`);
+      }
+      if (pending.length) {
+        // Once more before a slide is given up, at the effort the admin set:
+        // the reader is never coarsened to fit a budget (a lower effort misses
+        // structure — rings, repeat sets, whole rows); the server's hedged
+        // re-reads already answer a slow read.
+        try {
+          process.stderr.write(`slidemind: concept spec${pending.length === 1 ? "" : "s"} for slide${pending.length === 1 ? "" : "s"} ${pending.map((s) => s.slide).join(", ")} not read yet; one more pass…\n`);
+          const retry = await clientForSpecs.extractConceptSpecsForBrand(brandIdForSpecs, {
+            slides: pending,
+            slot,
+            palette,
+            imageIntent,
+            backendURL: backendForSpecs,
+            onProgress: ({ done, total, elapsedMs }) => {
+              process.stderr.write(`slidemind: second pass ${done}/${total} read (${Math.round((elapsedMs ?? 0) / 1000)}s)…\n`);
+            },
+          });
+          const done = writeSpecs(retry);
+          for (const s of pending) {
+            if (done.has(s.slide)) continue;
+            const f = (retry?.failures ?? []).find((x) => Number(x?.slide) === s.slide);
+            const error = f?.error ?? "no spec returned";
+            failed.push({ slide: s.slide, error, transient: transientSpecFailure({ wireFailed, answer: error }) });
+          }
+        } catch (err) {
+          const transient = transientSpecFailure({ wireFailed, thrown: err });
+          for (const s of pending) failed.push({ slide: s.slide, error: err?.message ?? String(err), transient });
+        }
+      }
+    }));
+    for (const f of failed) process.stderr.write(`${specFailureLine(f, deck)}\n`);
+    written.sort();
+    return { written, failed, skipped: unsupported, unsupported: unsupported ? unsupportedDetail() : null };
+  }
   // 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);
+  // One run per deck: a second `concepts` started while the first was still
+  // reading rewrote a spec under a running `transcribe` (x54 cloud 4 — the
+  // slide was built from a spec no longer on disk).
+  const lockFile = path.join(deckDir, "state", "concepts.lock");
+  try {
+    const holder = JSON.parse(fs.readFileSync(lockFile, "utf8"));
+    if (holder.pid !== process.pid && pidAlive(holder.pid)) fail(`concepts: already running for this deck (pid ${holder.pid}, since ${holder.at}). Wait for it to finish — \`slidemind concepts ${deck} --status\` shows its progress; a second run would rewrite specs another step is reading.`);
+  } catch (err) {
+    if (err?.code !== "ENOENT" && !(err instanceof SyntaxError)) throw err;
+  }
+  fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+  fs.writeFileSync(lockFile, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }));
+  process.on("exit", () => { try { if (JSON.parse(fs.readFileSync(lockFile, "utf8")).pid === process.pid) fs.rmSync(lockFile); } catch {} });
   await freshenDeckBundle(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 conceptWaves = await import(
+    pathToFileURL(path.join(BUILDERS_DIR, "concept-waves.mjs")).href
   );
-  const planned = new Set(families.plannedSlideNumbers(planMarkdown));
+  const planned = new Set(conceptWaves.plannedSlideNumbers(planMarkdown));
   // Frame slides (cover / agenda / divider / closing by the layout's job) get
   // no mockup: they are chrome with text slots, authored from the plan. The
   // server skips them too; taking them out of `planned` keeps them out of the
@@ -126,19 +781,121 @@ export async function cmdConceptImages(rest) {
   const jobs = jobsMod.layoutJobs(bundleMod.resolveBundleDirForDeck(deckDir));
   const frameSlides = [];
   for (const segment of sbMod.splitPlanMarkdownIntoSegments(planMarkdown)) {
-    if (segment.type !== "storyboard" || !segment.data?.layout) continue;
+    if (segment.type !== "storyboard" || !segment.data) continue;
     const job = jobsMod.plannedJob(segment.data, jobs);
     if (jobsMod.isFrameJob(job) && planned.has(segment.data.slide)) {
       planned.delete(segment.data.slide);
       frameSlides.push({ slideNumber: segment.data.slide, job, layout: segment.data.layout });
     }
   }
+  // Every body slide is built from its full content draft — the approved key
+  // points alone let the mockup decide how much the slide says.
+  const planMod = await import(pathToFileURL(path.join(BUILDERS_DIR, "plan.mjs")).href);
+  const withoutContent = planMod.slidesWithoutContent(deckDir, planMarkdown);
+  if (withoutContent.length) {
+    fail(
+      `concepts: slide${withoutContent.length === 1 ? "" : "s"} ${withoutContent.join(", ")} ha${withoutContent.length === 1 ? "s" : "ve"} no \`content\` in plan.md. ` +
+        `Write ${planMod.CONTENT_DRAFT}. ` +
+        "Leave `contentNotes` as approved; the draft needs no new sign-off. Then run concepts again.",
+    );
+  }
   if (frameSlides.length) {
     process.stderr.write(
       `slidemind: ${frameSlides.length} frame slide${frameSlides.length === 1 ? "" : "s"} (${frameSlides.map((f) => `${f.slideNumber}:${f.job}`).join(", ")}) — no mockup; author from the plan using the layout's slots and content areas, including required images.\n`,
     );
   }
 
+  // Mockups a human (or a fixture step) dropped at the deck ROOT —
+  // decks/<slug>/concepts/concept-slide-NN.png, the folder next to plan.html —
+  // are the deck's mockups too: adopt them into .slidemind/concepts before the
+  // on-disk check, or the command generates new ones over the supplied images
+  // (x29: both sessions copied to the root and got fresh lorem-ipsum decks).
+  const adoptedNums = new Set();
+  {
+    const conceptsDirNow = path.join(deckDir, "concepts");
+    const rootDir = path.basename(deckDir) === ".slidemind" ? path.join(path.dirname(deckDir), "concepts") : null;
+    if (rootDir && rootDir !== conceptsDirNow && fs.existsSync(rootDir)) {
+      let adopted = 0;
+      for (const f of fs.readdirSync(rootDir)) {
+        if (!/^concept-slide-\d+\.(png|jpe?g)$/i.test(f)) continue;
+        const dest = path.join(conceptsDirNow, f);
+        if (fs.existsSync(dest)) continue;
+        fs.mkdirSync(conceptsDirNow, { recursive: true });
+        fs.copyFileSync(path.join(rootDir, f), dest);
+        adoptedNums.add(Number(f.match(/(\d+)/)[1]));
+        adopted++;
+      }
+      if (adopted) {
+        process.stderr.write(
+          `slidemind: adopted ${adopted} mockup${adopted === 1 ? "" : "s"} from ${path.relative(process.cwd(), rootDir) || rootDir} into the deck's concepts/ — they are the deck's mockups now; nothing is generated over them.\n`,
+        );
+      }
+    }
+  }
+
+  // What image intent each planned slide carries NOW — the plan's approved uses
+  // for that slide, or the targeted edit that superseded them, fingerprinted
+  // canonically (design decision 6: instruction, fit, crop and source digest
+  // count; a renamed file does not).
+  let intentFingerprints;
+  try {
+    intentFingerprints = intentMod.slideIntentFingerprints(deckDir, [...planned], {
+      planMarkdown,
+      context: { output: "concept" },
+    });
+    // The spec's own key: the same uses, in the `spec` context, plus the
+    // generation of the persisted spec shape — so a spec written before the
+    // shape could carry a binding is refused even when its mockup is current.
+    specFingerprints = intentMod.slideIntentFingerprints(deckDir, [...planned], {
+      planMarkdown,
+      context: { output: "spec", schema: specMod.SPEC_SCHEMA_VERSION },
+    });
+  } catch (err) {
+    if (!err?.code) throw err;
+    fail(`${err.code} — ${err.message}${err.issue?.action ? `\n${err.issue.action}` : ""}`);
+  }
+  // A mockup a human just handed the deck is the mockup for the plan AS IT
+  // STANDS — that is what supplying it means, and the adoption note above says
+  // as much ("nothing is generated over them"). So it records the current
+  // intent: without this, a slide whose plan carries image uses would find an
+  // adopted file with no fingerprint, call it stale, and regenerate over the
+  // picture the user chose — the x29 failure in a new disguise.
+  if (adoptedNums.size) {
+    conceptIntent.recordConceptIntent(
+      deckDir,
+      new Map(
+        [...adoptedNums]
+          .filter((n) => planned.has(n))
+          .map((n) => [n, intentFingerprints.get(n) ?? null]),
+      ),
+    );
+    // A supplied picture continues nothing it was not generated from.
+    conceptIntent.recordConceptNotes(deckDir, [...adoptedNums].map((slideNumber) => ({ slideNumber })), planned);
+  }
+
+  // A mockup generated before the user attached a screenshot — or before they
+  // changed what that screenshot is FOR — depicts a plan that no longer exists.
+  // Those slides are MARKED, not cleaned up: deleting the mockup and its spec
+  // would destroy the only copy of an image nobody can regenerate while the
+  // backend is down (and a mockup a human supplied is a file this command did
+  // not create). The mark is what stops the reuse — the fast path below and the
+  // spec reuse above both refuse it — and it survives in the sidecar, because
+  // only a slide that actually gets a NEW mockup records a new fingerprint
+  // (design decision 6, guide §6 `image_intent_stale`).
+  for (const n of conceptIntent.staleConceptSlides(deckDir, intentFingerprints)) {
+    staleSlides.add(n);
+  }
+  if (staleSlides.size) {
+    const list = [...staleSlides].join(", ");
+    const one = staleSlides.size === 1;
+    process.stderr.write(
+      `slidemind: the image intent of slide${one ? "" : "s"} ${list} changed since ` +
+        `${one ? "its mockup was" : "their mockups were"} generated — ` +
+        `${one ? "it is" : "they are"} regenerated below, and the file${one ? "" : "s"} on disk ` +
+        `${one ? "is" : "are"} kept until a new one replaces ${one ? "it" : "them"}. Slide files are untouched.\n`,
+    );
+  }
+
   // 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
@@ -146,39 +903,45 @@ export async function cmdConceptImages(rest) {
   // 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) {
-      finish({
-        paths: existing.map((f) => path.join(conceptsDirEarly, f)),
-        planned: planned.size,
-        status: "on disk",
-        reason: "already generated for this plan (--force regenerates)",
-      });
+  //
+  // The run makes only the mockups the plan lacks: a planned slide with no
+  // mockup on disk, or one whose image intent changed (the mark above);
+  // `--force` remakes them all. A mockup already on disk for the plan as it
+  // stands IS that slide's concept — regenerating it would hand the slide a
+  // different picture than the spec and any slide built from it describe
+  // (x112 GTM: 3 of 4 on disk, all four regenerated, slides 1–3 transcribed
+  // from pictures that no longer existed).
+  const conceptsDirEarly = path.join(deckDir, "concepts");
+  const onDiskNums = new Set();
+  try {
+    for (const f of fs.readdirSync(conceptsDirEarly)) {
+      const m = /^concept-slide-(\d+)\.png$/.exec(f);
+      if (m) onDiskNums.add(Number(m[1]));
     }
+  } catch {}
+  const needed = new Set([...planned].filter((n) => force || staleSlides.has(n) || !onDiskNums.has(n)));
+  // Mockups of slides the plan no longer names (a longer earlier plan).
+  const pruneUnplanned = () => {
+    for (const n of onDiskNums) {
+      if (!planned.has(n)) fs.rmSync(mockupFileFor(deckDir, n), { force: true });
+    }
+  };
+  const plannedOnDisk = () =>
+    [...planned].sort((a, b) => a - b).map((n) => mockupFileFor(deckDir, n)).filter((f) => fs.existsSync(f));
+  if (planned.size > 0 && needed.size === 0) {
+    pruneUnplanned();
+    await finish({
+      paths: plannedOnDisk(),
+      planned: planned.size,
+      status: "on disk",
+      reason: "already generated for this plan (--force regenerates)",
+    });
   }
 
-  // No storyboards, nothing to generate: the server builds its beats from the
-  // same blocks, so a request would come back with zero images anyway.
+  // No slide records, nothing to generate: the server builds its beats from the
+  // same fences, so a request would come back with zero images anyway.
   if (planned.size === 0) {
-    finish({ status: "none", reason: "plan.md has no storyboard-canvas blocks (re-run `slidemind plan` to compose the storyboards)" });
+    await finish({ status: "none", reason: "plan.md has no storyboard-canvas fences (re-run `slidemind plan` to draft the slides)" });
   }
 
   const bundle = await import(
@@ -187,7 +950,7 @@ export async function cmdConceptImages(rest) {
   const brandId = bundle.readDeckBundleRef(deckDir)?.presFP ?? null;
   if (!brandId) {
     fail(
-      `deck ${deck} is not bound to a corporate design (no .bundle-ref.json). ` +
+      `deck ${deck} is not bound to a corporate design (no state/bundle-ref.json). ` +
         `Run \`slidemind ready ${deck}\` to bind it first.`,
     );
   }
@@ -196,8 +959,36 @@ export async function cmdConceptImages(rest) {
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
 
-  const skipNote = () =>
-    finish({ planned: planned.size, status: "unavailable", reason: "this add-in does not generate concept mockups; author from the storyboards" });
+  // No backend can generate right now. Whatever is already on disk is still the
+  // deck's best mockup set and is reported as such — a stale slide must not
+  // cost the agent the mockups of every OTHER slide, which is what happens if
+  // this exits with an empty path list because one slide fell out of the fast
+  // path. A stale slide is named, not hidden: it still shows the earlier image
+  // intent, and nothing recorded a new fingerprint for it, so the next run with
+  // a reachable backend regenerates it.
+  const skipNote = async () => {
+    const dir = path.join(deckDir, "concepts");
+    let onDisk = [];
+    try {
+      onDisk = fs
+        .readdirSync(dir)
+        .filter((f) => /^concept-slide-\d+\.png$/.test(f))
+        .filter((f) => planned.has(Number(f.match(/(\d+)/)[1])))
+        .sort()
+        .map((f) => path.join(dir, f));
+    } catch {}
+    const stale = [...staleSlides].join(", ");
+    return finish({
+      paths: onDisk,
+      planned: planned.size,
+      status: onDisk.length ? "on disk" : "unavailable",
+      reason:
+        (onDisk.length
+          ? "this add-in does not generate concept mockups; the mockups already on disk are unchanged"
+          : "this add-in does not generate concept mockups; author from the storyboards") +
+        (stale ? ` — slide${staleSlides.size === 1 ? "" : "s"} ${stale} still show${staleSlides.size === 1 ? "s" : ""} the earlier image intent` : ""),
+    });
+  };
 
   // 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
@@ -216,11 +1007,80 @@ export async function cmdConceptImages(rest) {
   try {
     backendURL = await client.resolveConceptBackend();
   } catch (err) {
-    if (err?.code === "concept_route_unavailable") skipNote();
+    if (err?.code === "concept_route_unavailable") await skipNote();
     throw err;
   }
 
-  const slideCount = planned.size;
+  // A deck whose plan records approved image uses needs an add-in that speaks
+  // the image-intent contract — end to end, from the mockup to the rendered
+  // picture. Checked HERE, before the first mockup is generated, because a run
+  // that discovers it at the spec step has already spent minutes of image
+  // generation on pixels that cannot be delivered. Nothing is written on the
+  // refusal: plan.md, the registry and the imported sources are untouched, and
+  // any mockup already on disk stays there.
+  //
+  // A deck with no uses never reaches this, which is what keeps every legacy
+  // deck free of the capability entirely. `backendURL` is null only when
+  // SEVERAL environments generate mockups (developer machines): the waves then
+  // fan out, and each request is gated by its own transport.
+  let deckHasUses = false;
+  try {
+    const planUses = intentMod.effectiveUsesForSlides(deckDir, [...planned], { planMarkdown });
+    deckHasUses = [...planUses.values()].some((list) => list.length);
+  } catch (err) {
+    // A registry or override file that does not parse. Generating against it
+    // would build mockups from obligations nobody can read — the deck's own
+    // state is the repair, and it is named rather than stack-traced. A deck
+    // with no registry at all reads as an empty one and never lands here.
+    if (!err?.code) throw err;
+    fail(`${err.code} — ${err.message}${err.issue?.action ? `\n${err.issue.action}` : ""}`);
+  }
+  if (deckHasUses && backendURL) {
+    const { assertImageIntentSupported } = await import(
+      pathToFileURL(path.join(SRC_DIR, "bridge", "client", "transport.mjs")).href
+    );
+    try {
+      await assertImageIntentSupported(backendURL);
+    } catch (err) {
+      if (err?.code !== "image_intent_unsupported") throw err;
+      fail(`${err.code} — ${err.message}`);
+    }
+  }
+
+  // The envelope each slide's generation request carries: the sources its
+  // approved uses name, inline, so the model sees the user's own picture rather
+  // than a description of it. Built HERE rather than inside the worker for the
+  // same reason the capability is checked here — the builder resolves and
+  // re-hashes every registered source on the way, so a deleted or overwritten
+  // original stops the run before one mockup exists (A14), instead of failing
+  // slide 7 after six minutes of generation.
+  //
+  // Empty map for a deck with no uses: those requests then serialize exactly as
+  // they did before this contract existed.
+  //
+  // A continuing slide is generated from the slide it continues, and the add-in
+  // keys that predecessor's concept by its own chain's uses: the envelope
+  // carries the chain (`continuationChain`), so the later wave finds the
+  // predecessor the earlier one made instead of painting a second one.
+  const intentEnvelopes = new Map();
+  if (deckHasUses) {
+    try {
+      for (const n of planned) {
+        const slides = conceptWaves.continuationChain(planMarkdown, n);
+        const envelope = intentMod.buildImageIntentEnvelope(deckDir, { slides, planMarkdown });
+        if (envelope) intentEnvelopes.set(n, envelope);
+      }
+    } catch (err) {
+      if (!err?.code) throw err;
+      fail(`${err.code} — ${err.message}${err.issue?.action ? `\n${err.issue.action}` : ""}`);
+    }
+  }
+
+  // The `--concept` / `--style` flags never travel as such: by this point every
+  // one has been imported and recorded as a canonical use (adaptLegacyReferences),
+  // so the envelope carries the same bytes with the approved obligation attached.
+
+  const slideCount = needed.size;
   const images = [];
   const collect = (res) => {
     if (!Array.isArray(res?.images)) return;
@@ -232,11 +1092,16 @@ export async function cmdConceptImages(rest) {
     }
   };
 
-  // Family variants depend on their lowest-numbered anchor. Run independent
-  // slides + anchors first, then variants; the server's per-family anchor cache
-  // (keyed by brand + CLI user) is what makes the anchor cross the two waves'
-  // separate requests.
-  const waves = families.conceptGenerationWaves(planMarkdown);
+  // A slide whose storyboard `continues` an earlier one is generated from that
+  // slide's concept, so it runs one wave later; everything else runs in the
+  // first wave. The server's continued-slide cache (keyed by brand + CLI user)
+  // is what carries a predecessor across the waves' separate requests.
+  // Only the slides this run must make; a kept predecessor is not remade for
+  // its successor (the add-in finds or rebuilds it server-side).
+  const waves = conceptWaves
+    .conceptGenerationWaves(planMarkdown)
+    .map((wave) => wave.filter((n) => needed.has(n)))
+    .filter((wave) => wave.length);
   const CONCURRENCY = 3;
   async function runWave(slides) {
     let cursor = 0;
@@ -249,7 +1114,7 @@ export async function cmdConceptImages(rest) {
           const res = await client.generateConceptImagesForBrand(brandId, {
             planMarkdown,
             slideNumbers: [n],
-            references,
+            imageIntent: intentEnvelopes.get(n) ?? null,
             backendURL,
             force,
           });
@@ -265,71 +1130,105 @@ export async function cmdConceptImages(rest) {
       Array.from({ length: Math.min(CONCURRENCY, slides.length) }, () => worker()),
     );
   }
-  await runWave(waves.firstWave);
-  await runWave(waves.variants);
+  for (const wave of waves) await runWave(wave);
 
+  // The mockups kept from disk are still this deck's: they are reported (and
+  // their specs ensured) on every exit, a generation that failed included.
+  const kept = [...planned].filter((n) => !needed.has(n) && onDiskNums.has(n)).sort((a, b) => a - b);
   if (images.length === 0) {
-    finish({ planned: planned.size, status: "generated", reason: "the add-in returned no image for any slide (see the per-slide failures above); author from the storyboards" });
+    await finish({ paths: plannedOnDisk(), planned: planned.size, status: "generated", reason: "the add-in returned no image for any slide (see the per-slide failures above); author from the storyboards", missing: [...needed].sort((a, b) => a - b) });
   }
 
-  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;
+    if (!Number.isFinite(n) || n < 1 || !needed.has(n)) continue;
     const b64 = base64FromDataUri(img?.dataUri);
     if (!b64) continue;
-    const name = `concept-slide-${String(n).padStart(2, "0")}.png`;
-    const abs = path.join(conceptsDir, name);
-    fs.writeFileSync(abs, Buffer.from(b64, "base64"));
-    written.push(abs);
+    // Atomic, and the slide's old spec goes in the same step: nothing can pair
+    // the new picture with the inventory of the one it replaces.
+    written.push(replaceMockup(deckDir, n, Buffer.from(b64, "base64")));
     writtenNums.add(n);
   }
 
-  // Drop stale mockups from a previous, longer plan — any concept-slide-NN.png
-  // 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 && isStale(Number(m[1]))) {
-      fs.rmSync(path.join(conceptsDir, entry), { force: true });
-    }
-  }
+  // Drop mockups from a previous, longer plan — any concept-slide-NN.png the
+  // plan no longer names.
+  pruneUnplanned();
+  // The mark lifts for exactly the slides that got a new mockup; the rest keep
+  // it, so nothing downstream reads a spec out of a picture that did not change.
+  for (const n of writtenNums) regeneratedSlides.add(n);
+
+  // Each fresh mockup records the intent it was made under, so the next run can
+  // tell "already generated for this plan" from "generated before the user's
+  // image existed". A slide with no uses records nothing — that absence IS what
+  // a legacy no-intent concept looks like, and it stays reusable.
+  conceptIntent.recordConceptIntent(
+    deckDir,
+    new Map([...writtenNums].map((n) => [n, intentFingerprints.get(n) ?? null])),
+  );
+  conceptIntent.pruneConceptIntent(deckDir, planned);
+  conceptIntent.recordConceptNotes(
+    deckDir,
+    images.filter((img) => writtenNums.has(Number(img?.slideNumber))),
+    planned,
+  );
+
   // 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));
+  const missing = [...needed].filter((n) => !writtenNums.has(n)).sort((a, b) => a - b);
 
   if (written.length === 0) {
-    finish({ planned: planned.size, status: "generated", reason: "the add-in returned images without usable bytes; author from the storyboards", missing });
+    await finish({ paths: plannedOnDisk(), planned: planned.size, status: "generated", reason: "the add-in returned images without usable bytes; author from the storyboards", missing });
   }
 
-  written.sort();
-  // The inventory form is seeded next to the mockups (never over a filled
-  // one): the organism/connector list becomes a file the draft check counts,
-  // not a step the agent may skip.
-  const check = await import(
-    pathToFileURL(path.join(BUILDERS_DIR, "draft-check.mjs")).href
-  );
-  const seeded = check.seedAssetPlan(
-    deckDir,
-    [
-      ...images
-        .filter((img) => writtenNums.has(Number(img?.slideNumber)))
-        .map((img) => ({ slideNumber: Number(img.slideNumber), label: img.label })),
-      ...frameSlides.map((f) => ({ slideNumber: f.slideNumber, label: `${f.job} (${f.layout})`, frame: f.job })),
-    ],
-  );
-  finish({
-    paths: written,
+  await finish({
+    paths: plannedOnDisk(),
     planned: planned.size,
     status: "generated",
+    reason: kept.length ? `slide${kept.length === 1 ? "" : "s"} ${kept.join(", ")} kept as on disk` : null,
     missing,
-    seeded,
-    extra: seeded
-      ? `Seeded ${path.join(deckDir, check.ASSET_PLAN_FILE)} — fill its regions/organisms/connectors/icons rows per slide from the mockups BEFORE writing any slide.\n`
-      : "",
   });
 }
+
+// ---------------------------------------------------------------------------
+// legacy --concept / --style → image-intent uses
+// ---------------------------------------------------------------------------
+
+async function adaptLegacyReferences(deckDir, references, deckArg) {
+  const { applyLegacyReferenceFlags, writePlanMarkdown } = await import(
+    pathToFileURL(path.join(BUILDERS_DIR, "legacy-reference-uses.mjs")).href
+  );
+  const planMarkdown = fs.readFileSync(path.join(deckDir, "plan.md"), "utf8");
+  let result;
+  try {
+    result = await applyLegacyReferenceFlags(deckDir, references, { planMarkdown });
+  } catch (err) {
+    // A typed import failure (unsupported format, unreadable file) reads as
+    // itself; anything else is re-thrown for the generic handler.
+    if (!err?.code) throw err;
+    fail(`${err.code} — ${err.message}${err.issue?.action ? `\n${err.issue.action}` : ""}`);
+  }
+  if (result.issues.length) {
+    // Nothing is written: the plan and the flags disagree about what an image
+    // is for, and guessing which one wins is exactly the failure this contract
+    // exists to prevent.
+    fail(
+      `image_intent_conflict — ${result.issues.length} conflicting image use(s):\n` +
+        result.issues.map((i) => `  - ${i.message}`).join("\n") +
+        `\nResolve them in ${path.join(deckDir, "plan.md")} (or drop the flag) and re-run.`,
+    );
+  }
+  for (const entry of result.imported) {
+    process.stderr.write(
+      `slidemind: ${entry.reused ? "already imported" : "imported"} ${entry.file} as ${entry.assetId}\n`,
+    );
+  }
+  if (!result.changed) return;
+  writePlanMarkdown(deckDir, result.planMarkdown);
+  process.stderr.write(
+    `slidemind: recorded ${result.added.length} image use${result.added.length === 1 ? "" : "s"} in plan.md ` +
+      `(slide${result.added.length === 1 ? "" : "s"} ${[...new Set(result.added.map((a) => a.slide))].sort((a, b) => a - b).join(", ")}). ` +
+      `The plan now needs a fresh sign-off: run \`slidemind plan ${deckArg}\`, then re-run this command.\n`,
+  );
+}