slidemind 0.3.20 → 0.4.1

package/src/cli/transcribe.mjs

@@ -0,0 +1,854 @@
+// `slidemind transcribe <deck> [--only NN] [--force]` — write each slide's JSX
+// skeleton from its concept spec (src/builders/transcribe.mjs). Runs after
+// `slidemind concepts` wrote the specs; a slide file that already exists is
+// left alone unless --force. Prints, per slide, the file and the icon list the
+// fetcher fills (`download-result --name <file>`).
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { fail, requirePlanApproved, resolveDeckArg, SRC_DIR, BUILDERS_DIR } from "./common.mjs";
+import { SPECS_UNSUPPORTED_CODE, transcribeSpecsRefusal } from "./concept-spec-support.mjs";
+import { deckSlug } from "../lib/deck-paths.mjs";
+import crypto from "node:crypto";
+import { attachSpecAsset, pendingSpecAssets, recordSpecAssets, resolveBoundImageUses } from "../builders/spec-assets.mjs";
+import { resolveEngineRouting } from "./engine-helpers.mjs";
+import { conversionProvenance } from "../lib/conversions.mjs";
+import { pidAlive } from "../lib/revision.mjs";
+import { currentSpec, specSlidesByState, specState } from "../lib/concept-spec-binding.mjs";
+import { createBatcher, createEngineRetry, engineFailure, fetchAssetGroups } from "../builders/asset-fetch.mjs";
+
+// Ownership: transcribe stamps the hash of every JSX it writes
+// (state/transcribed.json). While a file still matches, the machine owns it:
+// counts apply and --force may rebuild it from the spec. Once it differs, a
+// person or an agent has taken it over and transcribe keeps it byte-for-byte:
+// --only is a slide SELECTION, never repair authorization, and --force refuses
+// unless told to discard. Bounded repair is the separate (not yet available)
+// --repair.
+const sha = (s) => crypto.createHash("sha256").update(s).digest("hex");
+const DELIVERY = "transcribed-delivery.json";
+function readStamps(deckDir, name = "transcribed.json") {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(deckDir, "state", name), "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeStamps(deckDir, stamps, name = "transcribed.json") {
+  const file = path.join(deckDir, "state", name);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(stamps, null, 2) + "\n");
+}
+export function ownership(deckDir, file, stamps = readStamps(deckDir)) {
+  const name = path.basename(file);
+  let src;
+  try {
+    src = fs.readFileSync(file, "utf8");
+  } catch {
+    return "missing";
+  }
+  if (!stamps[name]) return "hand"; // no stamp: not ours
+  return stamps[name] === sha(src) ? "machine" : "hand";
+}
+
+// The spec's icons, fetched by the CLI itself: one engine search per distinct
+// (query, colour), semantic match, downloaded under the file name the skeleton
+// already references. The hold-out run (2026-09-19) showed the parent agent
+// skipping its fetcher subagents outright — 71 icon rows, one file on disk,
+// "the icon engine is unavailable" — so the step that cannot be skipped runs
+// here. A miss keeps the unresolved reference and is reported for repair.
+// Pane-relayed add-ins (no `engineRoutes`) are skipped with a note.
+export async function fetchSpecIcons({ rows, out = () => {}, ...opts }) {
+  if (!rows.length) return { fetched: [], missed: [], skipped: null };
+  return attachSpecIcons(rows, [await downloadSpecIcons({ rows, out, ...opts })], out);
+}
+
+// The key `fetchAssetGroups` groups rows by: one search per (kind, query, colour).
+const assetGroupKey = (r) => `${r.kind ?? "icon"}|${String(r.query).toLowerCase()}|${r.colorHex ?? "source"}`;
+
+// Search and download only — no slide is touched, so it can run while settling
+// rewrites the sources (the add-in prefetches the same way). `attachSpecIcons`
+// then points each settled row at its group's file.
+export async function downloadSpecIcons({ deckDir, bundleDir, brandId, rows, out = () => {}, dependencies = {} }) {
+  const client = dependencies.client ?? await import(pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href);
+  const bundle = dependencies.bundle ?? await import(pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href);
+  const { downloadOneResult } = dependencies.downloads ?? await import(pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href);
+  const retry = createEngineRetry({
+    sleep: dependencies.sleep, now: dependencies.now,
+    onRetry: ({ code, delay }) => out(`ASSETS: ${code}; retrying the same request after ${Math.ceil(delay / 1000)}s (not a missing motif).\n`),
+  });
+  // Routing rides the same ladder as the engine calls: a probe that got no
+  // answer (`capability_unknown`) is a transport failure, retried here and —
+  // if it stays unknown — recorded per row as retryable, so a bare re-run picks
+  // the assets up (pendingSpecAssets). Only a KNOWN answer skips: an add-in
+  // without the routes, no window to relay through, an ambiguous environment.
+  let routing;
+  try {
+    routing = await retry(() => (dependencies.resolveRouting ?? resolveEngineRouting)(client, { brandId, pick: "any" }));
+  } catch (error) {
+    if (error?.retryable) return { failure: { ...engineFailure(error), attempts: error.attempts, retryAfterMs: error.retryAfterMs } };
+    return { skipped: error?.message ?? String(error) };
+  }
+  if (!routing?.direct) {
+    return { skipped: "this add-in relays engine calls through a PowerPoint window; fetch the icons with the search skill" };
+  }
+  const backendURL = routing.backendURL;
+  let live;
+  try { live = await retry(() => client.listEngines({ subtype: "image", backendURL })); }
+  catch (error) {
+    return { failure: { ...engineFailure(error), attempts: error.attempts, retryAfterMs: error.retryAfterMs } };
+  }
+  const engines = (live.engines ?? []).filter((e) => bundle.pickImageEngine([e]));
+  if (!engines.length) {
+    return { skipped: "this corporate design has no image engine" };
+  }
+  // Recolour only with the per-element paint resolved against the emitted
+  // background by the transcriber. Missing evidence leaves the source intact.
+  const assetsDir = path.join(deckDir, "assets");
+  fs.mkdirSync(assetsDir, { recursive: true });
+  const tempDirs = [];
+  // The collage decides, as it does for the agent: each search's numbered
+  // contact sheet goes to the backend's reader, several motifs per call. A
+  // backend without the reader leaves the pick to the file names.
+  let canPick = false;
+  try { canPick = Array.isArray(await client.pickAssets?.({ items: [], backendURL })); } catch { canPick = false; }
+  const pickBatch = createBatcher(async (items) => {
+    const picks = await client.pickAssets({ items, backendURL });
+    if (!Array.isArray(picks)) throw new Error("the collage reader is unavailable");
+    return picks;
+  }, { max: 8 });
+  const groups = await fetchAssetGroups({
+    rows,
+    engines,
+    retry,
+    search: async ({ engine, query }) => {
+      const res = await client.engineSearch({ engineId: engine.id, query, subtype: "image", resultType: null, intent: null, top: 9, backendURL });
+      if (!res?.ok) return res;
+      return { ...res, collage: res.gridDataUri, results: Array.isArray(res.results) ? res.results : (res.thumbnails ?? []).map((t, i) => ({ selection: i + 1 })) };
+    },
+    pick: canPick
+      ? ({ group, results, collage }) => pickBatch({ query: group.query, keywords: group.keywords, kind: group.kind, collage, count: results.length })
+      : null,
+    download: async ({ searchId, selection, recolor }) => {
+      const downloadDir = fs.mkdtempSync(path.join(assetsDir, ".fetch-"));
+      tempDirs.push(downloadDir);
+      const got = await downloadOneResult({ client, presId: null, backendURL, searchId, assetsDir: downloadDir, selection, iconColor: recolor });
+      return got?.path && fs.existsSync(got.path) ? got : null;
+    },
+    onError: (query, err) => process.stderr.write(`slidemind: icon "${query}": ${err?.message ?? err}\n`),
+  });
+  return { groups, assetsDir, tempDirs };
+}
+
+/** Place downloaded groups into their rows' slides; a row no download covers is a miss. */
+export function attachSpecIcons(rows, downloads, out = () => {}) {
+  const summary = { fetched: [], missed: [], skipped: null };
+  const groups = new Map(downloads.flatMap((dl) => (dl.groups ?? []).map((g) => [assetGroupKey(g.group), { ...g, assetsDir: dl.assetsDir }])));
+  const blocked = downloads.find((dl) => dl.skipped || dl.failure);
+  if (blocked?.skipped && !groups.size) return { ...summary, skipped: blocked.skipped };
+  for (const r of rows) {
+    const g = groups.get(assetGroupKey(r));
+    if (g?.result) {
+      try { summary.fetched.push(attachSpecAsset(r, g.result, g.assetsDir)); }
+      catch (err) { summary.missed.push({ ...r, error: err.message }); }
+    } else {
+      summary.missed.push({ ...r, ...(g ? g.failure : blocked?.failure ?? { error: blocked?.skipped }) });
+    }
+  }
+  for (const dir of downloads.flatMap((dl) => dl.tempDirs ?? [])) fs.rmSync(dir, { recursive: true, force: true });
+  if (!groups.size) {
+    // Nothing was searched: the fetch failed before its first engine call. Say
+    // why — the rows are recorded as retryable, and the cause is what tells a
+    // reader to re-run rather than to source every motif by hand.
+    if (blocked?.failure) {
+      summary.failure = blocked.failure;
+      out(
+        `ASSETS: not fetched — ${blocked.failure.error}` +
+          (blocked.failure.retryable
+            ? ` (${blocked.failure.code}; retryable — a bare re-run of transcribe retries every unresolved reference without touching the slides)`
+            : ` (${blocked.failure.code})`) +
+          "\n",
+      );
+    }
+    return summary;
+  }
+  // Missing assets remain explicit unresolved references; never silently
+  // remove approved content to make a build pass.
+  out(
+    `ASSETS: ${summary.fetched.length}/${rows.length} fetched from the available image engines into assets/` +
+      (summary.missed.length ? ` — ${summary.missed.length} miss${summary.missed.length === 1 ? "" : "es"} (unresolved references kept; source another motif for what each element stands for — a miss of one motif never drops, letters or numbers its element or its set): ${summary.missed.map((r) => r.file).join(", ")}` : "") +
+      "\n",
+  );
+  return summary;
+}
+
+// Blocks while another process holds the deck's `concepts` lock (up to
+// SLIDEMIND_CONCEPTS_WAIT_MS, default 30 min), with a heartbeat on stderr.
+export async function waitForConcepts(deckDir, { sleep = (ms) => new Promise((r) => setTimeout(r, ms)), limitMs = Number(process.env.SLIDEMIND_CONCEPTS_WAIT_MS) || 30 * 60_000 } = {}) {
+  const lockFile = path.join(deckDir, "state", "concepts.lock");
+  const holder = () => {
+    try {
+      const h = JSON.parse(fs.readFileSync(lockFile, "utf8"));
+      return h.pid !== process.pid && pidAlive(h.pid) ? h : null;
+    } catch {
+      return null;
+    }
+  };
+  const start = Date.now();
+  let told = 0;
+  for (let h = holder(); h; h = holder()) {
+    if (Date.now() - start > limitMs) fail(`concepts (pid ${h.pid}) is still running after ${Math.round(limitMs / 60000)} min; re-run transcribe when its CONCEPTS line has printed.`);
+    if (Date.now() - told >= 30_000) {
+      process.stderr.write(`slidemind: waiting for \`concepts\` (pid ${h.pid}) to finish reading this deck's mockups before transcribing…\n`);
+      told = Date.now();
+    }
+    await sleep(2000);
+  }
+}
+
+const slugify = (s) =>
+  String(s ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .split("-")
+    .filter(Boolean)
+    .slice(0, 4)
+    .join("-") || "slide";
+
+// Which planned slides this run can neither transcribe nor leave standing: no
+// concept spec on disk AND no slide file of their own. A spec read is a polled
+// job that saves each slide as it arrives, so a deck legitimately sits at
+// "3 of 4 read" for minutes; transcribing then is what x44 measured — a clean
+// `TRANSCRIBED: 3/3`, nothing said about the fourth slide, and an agent that
+// hand-authored it from the mockup WITHOUT the icon fetch, which only runs for
+// the slides this command writes. That slide lost all 14 of its icons and
+// scored the batch's worst fidelity. A slide someone is deliberately writing by
+// hand has a file, so it is not reported here.
+// A spec on disk read from another picture than the mockup now beside it (the
+// mockup was regenerated, or the spec predates the binding): `concepts` reads
+// it again from the mockup on disk.
+export function staleSpecMessage(deck, slides) {
+  const one = slides.length === 1;
+  return (
+    `the concept spec${one ? "" : "s"} of slide${one ? "" : "s"} ${slides.join(", ")} ${one ? "was" : "were"} not read from the mockup now on disk — ` +
+    `building from ${one ? "it" : "them"} would follow a picture that no longer exists. Run \`slidemind concepts ${deck}\`: it reads ` +
+    `${one ? "that spec" : "those specs"} again from the mockup${one ? "" : "s"} on disk, then transcribe.`
+  );
+}
+
+export function plannedWithoutSource(planned, specSlides, existingFiles, only = null) {
+  return planned
+    .filter((n) => Number.isInteger(n) && (only === null || n === only))
+    .filter((n) => !specSlides.includes(n))
+    .filter((n) => !existingFiles.some((f) => new RegExp(`^${String(n).padStart(2, "0")}[-_.]`).test(f)))
+    .sort((a, b) => a - b);
+}
+
+export async function cmdTranscribe(rest, { dependencies = {} } = {}) {
+  let deck = null;
+  let only = null;
+  let force = false;
+  let asJson = false;
+  let icons = true;
+  let settle = true;
+  let discardEdits = false;
+  let repair = false;
+  let readSpecOnly = false;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--only") {
+      only = Number(rest[++i]);
+      if (!Number.isFinite(only)) fail("--only expects a slide number");
+    } else if (a === "--force") force = true;
+    else if (a === "--discard-edits") discardEdits = true;
+    else if (a === "--repair") repair = true;
+    else if (a === "--json") asJson = true;
+    else if (a === "--read-spec") readSpecOnly = true;
+    else if (a === "--no-icons" || a === "--no-assets") icons = false;
+    else if (a === "--no-settle") settle = false;
+    else if (a.startsWith("-")) fail(`unknown flag: ${a}`);
+    else if (deck === null) deck = a;
+    else fail(`unexpected argument: ${a}`);
+  }
+  if (!deck) fail("usage: slidemind transcribe <deck> [--only NN] [--force [--discard-edits]] [--no-assets] [--no-settle] [--read-spec] [--json]");
+  // Repair (keep the source, fix what the render contradicts) and regeneration
+  // (replace the source from the spec) are opposite intents — refuse before
+  // anything is read, so neither can half-run.
+  if (repair && (force || discardEdits))
+    fail("--repair cannot be combined with --force/--discard-edits: repair keeps the existing source, regeneration replaces it from the spec");
+  const deckDir = resolveDeckArg(deck);
+  if (repair) return await runRepair({ deck, deckDir, only, asJson, dependencies });
+  if (readSpecOnly) {
+    const specs = await import(pathToFileURL(path.join(BUILDERS_DIR, "concept-spec.mjs")).href);
+    const slides = only === null ? specs.listSpecSlides(deckDir) : [only];
+    if (!slides.length) fail("no concept specs for this deck");
+    for (const slide of slides) {
+      const { status, spec } = specState(deckDir, slide);
+      if (spec && status !== "current") fail(staleSpecMessage(deck, [slide]));
+      if (!spec) fail(`no valid complete spec for slide ${slide}`);
+      process.stdout.write(JSON.stringify({ slide, spec, complete: true }, null, 2) + "\n");
+      process.stdout.write(`END OF SPEC ${slide} — ${spec.elements?.length ?? 0} elements, ${spec.connectors?.length ?? 0} connectors\n`);
+    }
+    return;
+  }
+  await requirePlanApproved(deckDir);
+  // A `concepts` run still writing this deck's specs: wait for it rather than
+  // refuse. x56 QBR started concepts in the background, ran transcribe early,
+  // read "no concept specs" as a dead end and hand-authored all six slides
+  // (judged 0.59 against 0.88 for the transcribed decks).
+  await waitForConcepts(deckDir);
+
+  const specMod = await import(pathToFileURL(path.join(BUILDERS_DIR, "concept-spec.mjs")).href);
+  const tr = await import(pathToFileURL(path.join(BUILDERS_DIR, "transcribe.mjs")).href);
+  const sbMod = await import(pathToFileURL(path.join(BUILDERS_DIR, "storyboard-markdown.mjs")).href);
+  const bundleMod = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href);
+  const bundleDir = bundleMod.resolveBundleDirForDeck(deckDir);
+  const planMarkdown = fs.readFileSync(path.join(deckDir, "plan.md"), "utf8");
+  const layoutBySlide = new Map();
+  const beatBySlide = new Map();
+  // Frame slides (cover, agenda, divider, closing) are chrome with text slots,
+  // authored from the plan — `concepts` generates no mockup and no spec for
+  // them by design (docs/…/17-deck-frame.md §2.5). Classify with the bundle's
+  // own job table, the same way `concepts` takes them out of `planned`, so the
+  // missing-spec gate below cannot fire on a slide that is never meant to have
+  // one.
+  const jobsMod = await import(pathToFileURL(path.join(BUILDERS_DIR, "layout-jobs.mjs")).href);
+  const jobs = jobsMod.layoutJobs(bundleDir);
+  const bodySlides = [];
+  // Body slides whose layout takes no inventory (none in the bundle, or no
+  // content slot): `concepts` reads no spec for them, so none is owed here.
+  const noInventory = new Map();
+  for (const segment of sbMod.splitPlanMarkdownIntoSegments(planMarkdown)) {
+    if (segment.type !== "storyboard" || !segment.data?.slide) continue;
+    // Resolved as the add-in resolves it: a near-miss name is the design's own.
+    const resolved = segment.data.layout ? specMod.plannedLayoutSlot(bundleDir, segment.data.layout) : { layout: null, slot: null };
+    const data = { ...segment.data, layout: resolved.layout ?? segment.data.layout };
+    layoutBySlide.set(data.slide, data.layout ?? null);
+    beatBySlide.set(data.slide, data);
+    const job = data.layout ? jobsMod.plannedJob(data, jobs) : null;
+    if (jobsMod.isFrameJob(job)) continue;
+    if (resolved.slot) bodySlides.push(data.slide);
+    else noInventory.set(data.slide, specMod.layoutSlotNote(segment.data.layout, resolved));
+  }
+  // NOT created here: a run that refuses (no specs, every slide hand-owned or
+  // converted) must leave the deck exactly as it was, and an empty `slides/`
+  // is a change like any other. The directory is made where the first file is
+  // actually written, below.
+  const slidesDir = path.join(deckDir, "slides");
+  // Only a spec read from the mockup on disk is one; a spec read from an
+  // earlier picture describes nothing that exists (concept-spec-binding.mjs).
+  const { current: specSlides, outdated: outdatedSpecs } = specSlidesByState(deckDir);
+  // Both refusals below say "run concepts again". Against an add-in that has
+  // no spec reader that advice loops forever, so the agent gives up and
+  // hand-builds — exactly what the 2026-10-06 proposal sim did after `concepts`
+  // came back with mockups and `specs: []`. Ask the add-in first, and only on
+  // the way to a refusal: a deck with every spec it needs never pays a probe.
+  const existingBefore = fs.existsSync(slidesDir)
+    ? fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx"))
+    : [];
+  const unread = plannedWithoutSource(bodySlides, specSlides, existingBefore, only);
+  if (specSlides.length === 0 || unread.length) {
+    const support = await (dependencies.conceptSpecs ?? (async () => {
+      const client = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href);
+      const backendURL = await client.resolveConceptBackend().catch(() => null);
+      return client.conceptSpecSupport(backendURL);
+    }))().catch(() => ({ status: "unknown" }));
+    if (support?.status === "unsupported") {
+      const message = transcribeSpecsRefusal(support, { deck, slides: unread });
+      if (asJson) {
+        process.stdout.write(JSON.stringify({
+          ok: false,
+          error: { code: SPECS_UNSUPPORTED_CODE, message, retryable: false, env: support.env ?? null, backendURL: support.backendURL ?? null, slides: unread },
+        }) + "\n");
+      }
+      fail(message, 2);
+    }
+  }
+  // A planned slide whose spec on disk belongs to another picture: built from
+  // it, the slide would follow a mockup that no longer exists (x112 GTM 1–3).
+  const outdatedToWrite = outdatedSpecs.filter((n) => unread.includes(n));
+  if (outdatedToWrite.length) fail(staleSpecMessage(deck, outdatedToWrite));
+  if (specSlides.length === 0) {
+    fail(`no concept specs for this deck yet. Run \`slidemind concepts ${deck}\` in the foreground and let it finish (it prints one CONCEPTS line), then transcribe again — do not author the slides by hand while mockups are waiting to be read.`);
+  }
+  // A spec read is a polled job that saves each slide as it arrives, so a
+  // deck can legitimately sit at "3 of 4 read" for minutes. Transcribing then
+  // is the failure x44 measured: the run reported a clean `TRANSCRIBED: 3/3`,
+  // said nothing about the fourth slide, and the agent hand-authored it from
+  // the mockup — without the icon fetch, which only runs for slides this
+  // command transcribes. That slide lost all 14 of its icons and scored the
+  // batch's worst fidelity. A planned slide with neither a spec nor a file of
+  // its own has nothing to transcribe from and nothing already standing, so
+  // stop rather than report success over the gap. A slide the author is
+  // deliberately writing by hand HAS a file and does not trip this. (`unread`
+  // is computed above, where the add-in is asked whether a re-run can help.)
+  if (unread.length) {
+    fail(
+      `the plan has ${bodySlides.length} body slide${bodySlides.length === 1 ? "" : "s"} and slide${unread.length === 1 ? "" : "s"} ${unread.join(", ")} ${unread.length === 1 ? "has" : "have"} no concept spec yet. ` +
+        `Run \`slidemind concepts ${deck}\` until it prints CONCEPTS: ${bodySlides.length}/${bodySlides.length} — the read saves each spec as it arrives and a re-run asks only for the rest. ` +
+        `Transcribing now would skip ${unread.length === 1 ? "that slide" : "those slides"} silently, and its assets are fetched only for the slides this command writes. ` +
+        `Only a slide \`concepts\` called unreadable is authored by hand from its concept (workflow/create.md, step 2): write its file, then transcribe the rest.`,
+    );
+  }
+  // Every line is written as a native line directive (nativeLinesV1) and there
+  // is no older markup to fall back to: an add-in that answered without the
+  // flag stops the run before the first slide is written. One that could not
+  // be asked (offline, several backends) is named and the run goes on — the
+  // bundle's lint refuses the directives at view-draft if it predates them.
+  // Asked once, and only when a slide is about to be written.
+  let lineSupport = null;
+  const requireNativeLines = async () => {
+    if (lineSupport) return;
+    lineSupport = await (dependencies.nativeLines ?? (async () => {
+      const client = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href);
+      const backendURL = await client.resolveConceptBackend().catch(() => null);
+      return client.nativeLinesSupport(backendURL);
+    }))();
+    if (lineSupport === "unsupported") {
+      const message = "[line:error] this add-in predates native lines — update the add-in (it does not advertise nativeLinesV1; nothing was written)";
+      if (asJson) process.stdout.write(JSON.stringify({ ok: false, error: { code: "native_lines_unsupported", message, retryable: false } }) + "\n");
+      fail(message, 2);
+    }
+    if (lineSupport !== "supported") process.stderr.write("slidemind: [line:note] whether the add-in exports native lines (nativeLinesV1) could not be checked; the lines are written in that vocabulary regardless\n");
+  };
+  const { readColorTokens, readTypeRamp } = await import(pathToFileURL(path.join(BUILDERS_DIR, "design-tokens.mjs")).href);
+  const tokens = readColorTokens(bundleDir);
+  const ramp = readTypeRamp(bundleDir);
+  // The deck's approved originals, resolved once for every slide this run
+  // touches. A deck with no image uses gets an empty map and an empty issue
+  // list, and everything below behaves exactly as it did before the contract.
+  const wanted = only === null ? specSlides : [only];
+  const { bound: boundUses, issues: boundIssues, reconstructed } = resolveBoundImageUses(deckDir, wanted, { planMarkdown });
+  const notesBySlide = new Map();
+  const noteFor = (slide, text) => {
+    if (!notesBySlide.has(slide)) notesBySlide.set(slide, []);
+    notesBySlide.get(slide).push(text);
+  };
+  for (const [slide, note] of noInventory) if (only === null || slide === only) noteFor(slide, note);
+  for (const issue of boundIssues) noteFor(issue.slide, specMod.unresolvedUseNote(issue));
+  // Rebuilding a slide (--force) from a spec read off another picture is the
+  // same mistake as a first build from one; without --force such a slide keeps
+  // its file and nothing is built from the spec.
+  const outdatedInScope = outdatedSpecs.filter((n) => only === null || n === only);
+  if (force && outdatedInScope.length) fail(staleSpecMessage(deck, outdatedInScope));
+  const stamps = readStamps(deckDir);
+  const existing = existingBefore;
+  const results = [];
+  for (const n of specSlides) {
+    if (only !== null && n !== only) continue;
+    const nn = String(n).padStart(2, "0");
+    const have = existing.find((s) => new RegExp(`^${nn}[-_.]`).test(s));
+    if (have) {
+      const source = fs.readFileSync(path.join(slidesDir, have), "utf8");
+      // Two signals, and the deck's own record is the one a worker cannot
+      // delete: removing the pragma does not make a converted slide semantic
+      // (E15), and a record that cannot be READ leaves the question open —
+      // which is not authorization to regenerate over it either.
+      const provenance = conversionProvenance(deckDir, have);
+      if (provenance === undefined) {
+        results.push({ slide: n, file: path.join(slidesDir, have), skipped: `conversions/${path.basename(have, ".jsx")}.json cannot be read, so whether this slide is converted is unknown — repair or remove that record` });
+        continue;
+      }
+      if (provenance || /^\s*\/\/\s*SLIDEMIND_DIALECT:\s*converted\b/m.test(source)) {
+        results.push({ slide: n, file: path.join(slidesDir, have), skipped: "converted slide — edit its JSX directly; transcription and settling do not apply" });
+        continue;
+      }
+      const owner = ownership(deckDir, path.join(slidesDir, have), stamps);
+      if (owner === "hand" && !(force && discardEdits)) {
+        // Someone edited this slide since it was transcribed: keep their file
+        // exactly as it is. --only selects slides, it does not authorize a
+        // rewrite, and --force refuses unless the edits are to be discarded.
+        results.push({
+          slide: n,
+          file: path.join(slidesDir, have),
+          skipped: force
+            ? "hand-edited since transcribe — --force refuses; add --discard-edits to rebuild it from the spec"
+            : "hand-edited since transcribe — kept unchanged; `--force --discard-edits` rebuilds it from the spec",
+        });
+        continue;
+      }
+      if (!force) {
+        results.push({ slide: n, file: path.join(slidesDir, have), skipped: "exists (--force rebuilds it from the spec)" });
+        continue;
+      }
+    }
+    const spec = currentSpec(deckDir, n);
+    if (!spec) continue;
+    await requireNativeLines();
+    // The plan's layout, always: the concept is drawn for it, never the other
+    // way round. One the bundle does not carry is a plan defect, reported.
+    const usedLayout = layoutBySlide.get(n);
+    // Skipped, not fatal: a run that exits here would leave the slides it
+    // already wrote unstamped, and the next run would keep them as hand-edited.
+    if (!usedLayout) {
+      results.push({ slide: n, skipped: "the plan names no layout for this slide; correct the plan before transcription" });
+      continue;
+    }
+    let layoutSource;
+    try {
+      layoutSource = fs.readFileSync(path.join(bundleDir, "layouts", `${usedLayout}.jsx`), "utf8");
+    } catch {
+      results.push({ slide: n, skipped: `the plan's layout ${usedLayout} is not in this design's bundle — restore the planned layout or correct the plan; never substitute a layout from the concept image` });
+      continue;
+    }
+    // A concept drawn against its layout's tone is a concept-generation defect;
+    // a reader-flagged flaw and the template's own marks the reader left out
+    // are what the agent corrects or keeps out.
+    const notes = specMod.specAuthorNotes(spec);
+    const scaffolded = tr.scaffoldSlideJsx(spec, { slide: n, layout: usedLayout, layoutSource, tokens, ramp, bound: boundUses, literal: reconstructed.has(n) });
+    const { jsx, icons } = scaffolded;
+    const warnings = [...notes, ...scaffolded.warnings];
+    const file = have ? path.join(slidesDir, have) : path.join(slidesDir, `${nn}-${slugify(spec.chrome?.kicker || spec.chrome?.headline)}.jsx`);
+    fs.mkdirSync(slidesDir, { recursive: true });
+    fs.writeFileSync(file, jsx);
+    results.push({ slide: n, file, spec, layout: usedLayout, layoutSource, elements: spec.counts?.elements ?? spec.elements?.length ?? 0, connectors: spec.connectors?.length ?? 0, icons, warnings, dropped: scaffolded.dropped, connectorLines: scaffolded.connectorLines });
+  }
+  // Settle: render the skeletons, measure them, fit each text to the room the
+  // image gives it, re-render — then fit every connector once on the final
+  // geometry (src/builders/settle-driver.mjs, shared with the add-in). Without
+  // a render (--no-settle, or a bundle with no capture engine) connectors are
+  // fitted against the spec's own rectangles.
+  let settled = { passes: 0, changes: 0 };
+  const written = results.filter((r) => !r.skipped);
+  // Icon searches do not wait for settling: a row's query is the spec's, which
+  // settling never changes. Downloaded now, placed below once the settled
+  // source is final (settling rescaffolds it, references included).
+  const assetOut = (t) => (asJson ? process.stderr : process.stdout).write(t);
+  const iconDeps = { deckDir, bundleDir, brandId: bundleMod.readDeckBundleRef(deckDir)?.presFP ?? null, out: assetOut, dependencies: dependencies.icons ?? {} };
+  const firstRows = written.flatMap((r) => r.icons.map((ic) => ({ ...ic, slide: r.slide, slideFile: r.file })));
+  const prefetch = icons && firstRows.length ? downloadSpecIcons({ ...iconDeps, rows: firstRows }).catch(() => null) : null;
+  if (written.length) {
+    const cap = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "capture.mjs")).href);
+    const { settleWrittenSlides } = await import(pathToFileURL(path.join(BUILDERS_DIR, "settle-driver.mjs")).href);
+    const byKey = new Map(written.map((r) => [r.file, r]));
+    const slides = written.map((r) => ({ key: r.file, spec: r.spec, plan: beatBySlide.get(r.slide) ?? null }));
+    // Words that still do not fit after the ladder's step down are shortened
+    // by the add-in's model (copy-fit.mjs): the CLI holds no model key.
+    const client = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href);
+    const brandId = bundleMod.readDeckBundleRef(deckDir)?.presFP ?? null;
+    const copyBackend = settle && brandId ? await client.resolveConceptBackend().catch(() => null) : null;
+    const driverOpts = {
+      slides,
+      ramp,
+      fitCopy: copyBackend
+        ? async ({ items, context, plan }) => (await client.fitCopyForBrand(brandId, { items, context, plan, backendURL: copyBackend })) ?? []
+        : null,
+      capture: settle && cap.bundleHasCaptureEngine(bundleDir)
+        ? async (keys) => {
+            const render = await cap.captureDeckLocally({ deckDir, bundleDir, only: keys.map((k) => path.basename(k)) });
+            return new Map(keys.map((k) => [k, (render?.slides ?? []).find((sl) => sl.fileName === path.basename(k))?.render]));
+          }
+        : null,
+      // `normalize: false`: the row/centre normalizers already ran on the first
+      // write and re-running them here would snap the geometry this pass just
+      // measured and moved straight back to where it overlapped.
+      // `bound` rides along: without it this rewrite would drop every
+      // binding the first write placed and re-open the pictures to search.
+      rescaffold: (s, spec) => {
+        const r = byKey.get(s.key);
+        r.spec = spec;
+        const again = tr.scaffoldSlideJsx(spec, { slide: r.slide, layout: r.layout, layoutSource: r.layoutSource, tokens, ramp, normalize: false, bound: boundUses, literal: reconstructed.has(r.slide) });
+        r.icons = again.icons;
+        r.dropped = again.dropped;
+        r.connectorLines = again.connectorLines;
+        r.warnings = [...new Set([...r.warnings, ...again.warnings])];
+        fs.writeFileSync(r.file, again.jsx);
+      },
+      readSource: (key) => fs.readFileSync(key, "utf8"),
+      writeSource: (key, src) => fs.writeFileSync(key, src),
+      onPass: (pass, n) => process.stderr.write(`slidemind: settle pass ${pass} — rendering ${n} slide${n === 1 ? "" : "s"}…\n`),
+      onError: (step, err) => process.stderr.write(`slidemind: ${step === "settle" ? "settle skipped" : step === "connectors" ? "connector fit uses the spec's rectangles" : step} — ${err?.message ?? err}\n`),
+    };
+    const run = await settleWrittenSlides(driverOpts);
+    settled = { passes: run.passes, changes: run.changes };
+    for (const s of slides) {
+      const r = byKey.get(s.key);
+      if (run.bySlide.has(s.key)) r.settleChanges = run.bySlide.get(s.key);
+      if (s.routeChanges) r.routeChanges = s.routeChanges;
+      const beyond = (s.routeChanges ?? []).filter((line) => line.includes("beyond tolerance"));
+      if (beyond.length) r.warnings = [...(r.warnings ?? []), ...beyond];
+    }
+  }
+
+  // Fetch only the visual assets the spec requests (--no-assets skips fetching).
+  //
+  // Two sources, and the second is what makes a resume work (task 7.3 / E22).
+  // The rows THIS run wrote are the fresh work; `pendingSpecAssets` adds the
+  // ones an earlier run could not resolve — a slide that is skipped here
+  // ("exists", or hand-edited) still gets its missing picture retried, without
+  // its spec being re-extracted, its source regenerated or its geometry
+  // settled. A reference the author repointed at their own file is not in that
+  // list: the ledger matches on the exact string the machine wrote.
+  let iconSummary = null;
+  const fresh = results
+    .filter((r) => !r.skipped)
+    .flatMap((r) => r.icons.map((ic) => ({ ...ic, slide: r.slide, slideFile: r.file })));
+  recordSpecAssets(deckDir, fresh.map((row) => ({ ...row, resolved: false })));
+  const freshKeys = new Set(fresh.map((r) => `${r.slide}|${r.id}`));
+  const retried = pendingSpecAssets(
+    deckDir,
+    new Map(results.filter((r) => r.file).map((r) => [r.slide, r.file])),
+  ).filter((r) => !freshKeys.has(`${r.slide}|${r.id}`));
+  const iconRows = [...fresh, ...retried];
+  // Ownership BEFORE the fetch: resolving a reference rewrites one token of a
+  // slide's source, and a slide the machine still owned must not be demoted to
+  // hand-owned by our own edit. A hand-owned slide stays hand-owned.
+  // Only the SKIPPED slides: a slide this run wrote is stamped below anyway,
+  // and `stamps` still holds the pre-run values here, so asking about one
+  // would answer about the file it replaced.
+  const ownedBefore = new Map(
+    results.filter((r) => r.skipped && r.file).map((r) => [r.slide, ownership(deckDir, r.file, stamps)]),
+  );
+  if (icons && iconRows.length) {
+    if (retried.length) {
+      // stderr: a progress note, never stdout — a --json payload stays data.
+      const slides = new Set(retried.map((r) => r.slide)).size;
+      process.stderr.write(
+        `slidemind: retrying ${retried.length} unresolved asset reference${retried.length === 1 ? "" : "s"} on ` +
+          `${slides} already-written slide${slides === 1 ? "" : "s"} — no spec re-read, no source regenerated, no geometry settled\n`,
+      );
+    }
+    // Under --json the payload owns stdout; the fetch's progress line is a
+    // note, so it goes to stderr (`assetOut`) instead of corrupting it.
+    const early = await prefetch;
+    const usable = early && !early.skipped && !early.failure ? [early] : [];
+    const covered = new Set(usable.flatMap((dl) => dl.groups.map((g) => assetGroupKey(g.group))));
+    const rest = iconRows.filter((r) => !covered.has(assetGroupKey(r)));
+    const later = rest.length ? [await downloadSpecIcons({ ...iconDeps, rows: rest })] : [];
+    iconSummary = attachSpecIcons(iconRows, [...usable, ...later], assetOut);
+    for (const result of results) if (result.icons) result.icons = result.icons.map((row) =>
+      iconSummary.fetched.find((asset) => asset.slide === result.slide && asset.id === row.id) ?? row);
+    if (iconSummary.skipped) (asJson ? process.stderr : process.stdout).write(`ASSETS: not fetched — ${iconSummary.skipped}; the rows below name what each slide needs.\n`);
+    // The outcome, per row: a resolved row records the file name the bytes
+    // actually produced, a miss keeps its reference and stays retriable.
+    recordSpecAssets(deckDir, [
+      ...iconSummary.fetched.map((row) => ({ ...row, resolved: true, error: null })),
+      ...iconSummary.missed.map((row) => ({ ...row, resolved: false })),
+    ]);
+  }
+  // Every approved original the plan gives a slide must actually be placed on
+  // it. An obligation added after the slide was written — or an edit that
+  // dropped the picture — is REPORTED here and never repaired by rewriting the
+  // file: a slide someone edited is theirs, and a missing binding is not
+  // authorization to reset it. The render-side proof is a separate, stricter
+  // check on the captured pictures; this one only needs to tell the author.
+  for (const r of results) {
+    let source = "";
+    try {
+      source = r.file ? fs.readFileSync(r.file, "utf8") : "";
+    } catch {
+      /* the slide was never written — the note is the right answer */
+    }
+    for (const note of specMod.unplacedUseNotes(source, boundUses, r.slide)) noteFor(r.slide, note);
+  }
+  for (const r of results) {
+    const notes = notesBySlide.get(r.slide);
+    if (!notes?.length) continue;
+    if (r.skipped) r.warnings = [...(r.warnings ?? []), ...notes];
+    else r.warnings = [...new Set([...(r.warnings ?? []), ...notes])];
+    notesBySlide.delete(r.slide);
+  }
+
+  // Stamp the final JSX after settling and resolving asset formats. A run that
+  // wrote nothing (every slide kept or refused) rewrites no stamp either —
+  // except where a RETRY resolved a reference on a slide the machine still
+  // owned. That rewrite is ours, so the stamp follows it; a hand-owned slide
+  // keeps its file and its ownership, and gets no stamp from us.
+  const restamped = results.filter(
+    (r) => r.skipped && r.file && ownedBefore.get(r.slide) === "machine"
+      && (iconSummary?.fetched ?? []).some((a) => a.slide === r.slide),
+  );
+  if (written.length || restamped.length) {
+    for (const r of [...results.filter((x) => !x.skipped), ...restamped]) {
+      if (!r.file) continue;
+      try {
+        stamps[path.basename(r.file)] = sha(fs.readFileSync(r.file, "utf8"));
+      } catch {}
+    }
+    writeStamps(deckDir, stamps);
+    // Beside each stamp, what that write left out and the line id each
+    // connector went under: preservation seeding binds the concept's
+    // obligations to it (src/lib/edit-state.mjs `bindDelivered`).
+    const delivery = readStamps(deckDir, DELIVERY);
+    for (const r of results.filter((x) => !x.skipped && x.file)) {
+      delivery[path.basename(r.file)] = { dropped: r.dropped ?? [], connectorLines: r.connectorLines ?? [] };
+    }
+    writeStamps(deckDir, delivery, DELIVERY);
+  }
+  const imageIntent = boundUses.size || boundIssues.length
+    ? {
+        bound: [...boundUses.values()].map(({ notes, ...b }) => b),
+        issues: boundIssues,
+      }
+    : null;
+  if (asJson) {
+    process.stdout.write(JSON.stringify({ deck: deckSlug(deckDir), results: results.map(({ spec, layoutSource, ...r }) => r), icons: iconSummary, retried: retried.map(({ slideFile: _f, ...r }) => r), settled, ...(imageIntent ? { imageIntent } : {}) }, null, 2) + "\n");
+    return;
+  }
+  // Notes about a slide this run never reached (and the deck-wide ones) still
+  // have to be said: an unresolvable source is not less true for being found
+  // outside the slide set.
+  for (const [slide, notes] of notesBySlide) {
+    for (const note of notes) process.stdout.write(`${slide ? `slide ${slide}` : "deck"}: note: ${note}\n`);
+  }
+  for (const r of results) {
+    if (r.skipped) {
+      process.stdout.write(`slide ${r.slide}: skipped — ${r.skipped}${r.file ? ` (${path.relative(process.cwd(), r.file)})` : ""}\n`);
+      for (const w of r.warnings ?? []) process.stdout.write(`  note: ${w}\n`);
+      continue;
+    }
+    process.stdout.write(`slide ${r.slide}: ${path.relative(process.cwd(), r.file)} — ${r.elements} elements, ${r.connectors} connectors, ${r.icons.length} assets${r.settleChanges?.length ? `, settled ${r.settleChanges.length} (${r.settleChanges.slice(0, 3).join("; ")}${r.settleChanges.length > 3 ? "; …" : ""})` : ""}${r.routeChanges?.length ? `, routed ${r.routeChanges.length} (${r.routeChanges.slice(0, 2).join("; ")})` : ""}\n`);
+    for (const u of r.routeUnresolved ?? []) process.stdout.write(`  note: connector ${u}\n`);
+    if (!iconSummary || iconSummary.skipped || iconSummary.failure) for (const ic of r.icons) process.stdout.write(`  ${ic.kind ?? "icon"} ${ic.file} | ${ic.query} | ${ic.color}\n`);
+    for (const w of r.warnings) process.stdout.write(`  note: ${w}\n`);
+  }
+  const iconsDone = !iconRows.length || (iconSummary && !iconSummary.skipped && !iconSummary.missed.length);
+  if (settled.passes) process.stdout.write(`SETTLED: ${settled.changes} geometry change${settled.changes === 1 ? "" : "s"} over ${settled.passes} render pass${settled.passes === 1 ? "" : "es"}\n`);
+  process.stdout.write(
+    `TRANSCRIBED: ${written.length}/${results.length}` +
+      (written.length
+        ? iconsDone
+          ? ` — next: \`slidemind view-draft ${deck} --only NN\` per slide, fix what it prints in the JSX, then compare each PNG with its draft once. A slide you edit is yours: transcribe leaves it alone from then on — edit its JSX directly; \`--force --discard-edits\` rebuilds it from the mockup.`
+          : iconSummary?.failure?.retryable
+            ? ` — next: re-run \`slidemind transcribe ${deck}\` — the asset fetch failed (${iconSummary.failure.code}) before any motif was searched, and a bare re-run retries every unresolved reference without re-reading specs or touching the slides. Do not hand-draw or letter the missing icons.`
+            : ` — next: resolve the asset rows above (download-result --name <file>), then \`slidemind view-draft ${deck} --only NN\` per slide and fix what it prints.`
+        : "") +
+      "\n",
+  );
+}
+
+// ---- `slidemind transcribe <deck> --repair` (safeguard-slide-editing 6.4)
+//
+// Bounded repair of source that already exists: keep the author's slide, fix
+// only what its own render contradicts, inside the budget its operation
+// declares (src/builders/repair.mjs). It is the opposite intent from
+// regeneration — which is why the flags refuse each other above — and it is
+// never something a plain `transcribe` slips into: the authorization is the
+// recorded scope, not the flag.
+//
+// Deliberately NOT gated on `requirePlanApproved`: repair authors no content
+// from the plan. It moves what is already there, under a scope a human opened
+// with `revision begin`, which is the authorization that matters here — and an
+// adopted deck being repaired may have no plan at all.
+async function runRepair({ deck, deckDir, only, asJson, dependencies = {} }) {
+  const { openOperations } = await import(pathToFileURL(path.join(SRC_DIR, "lib", "edit-state.mjs")).href);
+  const { repairOperation } = await import(pathToFileURL(path.join(BUILDERS_DIR, "repair.mjs")).href);
+
+  let open;
+  try {
+    open = openOperations(deckDir);
+  } catch (err) {
+    fail(err.message, 2);
+  }
+  const scopeHint =
+    `Open one first: \`slidemind revision begin ${deck} --operation repair --slides <sel>\`, ` +
+    `export the printed SLIDEMIND_OWNER, then run this command inside that session.`;
+  const nn = only === null ? null : String(only).padStart(2, "0");
+  const namesSlide = (op) => op.targets.some((t) => new RegExp(`(^|/)${nn}[-_.]`).test(t.jsxPath));
+  const repairs = open.filter((o) => o.kind === "repair");
+  const scoped = nn === null ? repairs : repairs.filter(namesSlide);
+  if (scoped.length === 0) {
+    fail(
+      `--repair needs an open repair scope${nn === null ? "" : ` covering slide ${only}`} — this deck has ` +
+        `${repairs.length === 0 ? "none" : `${repairs.length} that do not name it (${repairs.flatMap((o) => o.targets.map((t) => t.jsxPath)).join(", ")})`}. ${scopeHint}`,
+      2,
+    );
+  }
+  if (scoped.length > 1) {
+    fail(`this deck has ${scoped.length} open repair scopes (${scoped.map((o) => o.operationId).join(", ")}); finish one before running another.`, 2);
+  }
+  const operation = scoped[0];
+  // Unsupported scope: the scope is the unit of repair. `--only` may confirm a
+  // single-slide scope, never carve a smaller one out of a wider one — a
+  // partial run would commit its operation record as done for slides it never
+  // touched.
+  if (nn !== null && operation.targets.length !== 1) {
+    fail(
+      `--only ${only} asks for part of a repair scope that covers ${operation.targets.length} slides ` +
+        `(${operation.targets.map((t) => t.jsxPath).join(", ")}): repair runs the whole scope. ` +
+        `Re-open it with \`--slides ${only}\` to repair that slide alone.`,
+      2,
+    );
+  }
+  // Unrecorded source: bounded repair rewrites source this deck wrote down as
+  // transcribed. Never having been recorded is not a syntax verdict — that is
+  // `validateSettleTarget`'s job, on the bytes, a moment later — it is the
+  // ancestry question, and an unknown answer refuses.
+  const stamps = readStamps(deckDir);
+  const unrecorded = operation.targets.filter((t) => !stamps[path.basename(t.jsxPath)]);
+  if (unrecorded.length) {
+    fail(
+      `bounded repair only rewrites source this deck recorded as transcribed; ` +
+        `${unrecorded.map((t) => t.jsxPath).join(", ")} ${unrecorded.length === 1 ? "has" : "have"} no entry in state/transcribed.json. ` +
+        `Edit the JSX directly instead.`,
+      2,
+    );
+  }
+
+  // The renderer is the one injectable seam here (the test harness measures
+  // without Chrome); everything above and below it is the real command.
+  let capture = dependencies.repair?.capture ?? null;
+  if (!capture) {
+    const cap = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "capture.mjs")).href);
+    const st = await import(pathToFileURL(path.join(BUILDERS_DIR, "settle.mjs")).href);
+    const bundleMod = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href);
+    const bundleDir = bundleMod.resolveBundleDirForDeck(deckDir);
+    if (!cap.bundleHasCaptureEngine(bundleDir)) {
+      fail(`bounded repair measures each slide by rendering it, and this deck's design bundle carries no capture engine. Run \`slidemind download-bundle ${deck}\` first.`, 2);
+    }
+    // The candidate is rendered, never the deck: `workspaceDir` is the staged
+    // copy repair.mjs hands us. A slide the capture does not return is a failed
+    // render, not an empty measurement — measuring nothing would settle nothing
+    // and report the slide as fine.
+    let pass = 0;
+    capture = async ({ workspaceDir, files }) => {
+      process.stderr.write(`slidemind: repair pass ${++pass} — rendering ${files.length} slide${files.length === 1 ? "" : "s"}…\n`);
+      const render = await cap.captureDeckLocally({ deckDir: workspaceDir, bundleDir, only: files.map((f) => path.basename(f)) });
+      const out = new Map();
+      for (const file of files) {
+        const slide = (render?.slides ?? []).find((sl) => sl.fileName === path.basename(file));
+        if (!slide?.render?.boxes) throw new Error(`${file} did not render; its geometry cannot be measured`);
+        out.set(file, st.measuredFromRender(slide.render));
+      }
+      return out;
+    };
+  }
+
+  const result = await repairOperation(deckDir, { operation, capture });
+  // Exit codes, refusal side: 1 is a malformed invocation (the flag conflict
+  // above), 2 is "blocked, not malformed" — the same code `deck_busy`,
+  // `needs_reconcile` and a rebase conflict use. A repair the budget or the
+  // representation refuses is state, not usage, so it exits 2.
+  if (asJson) {
+    process.stdout.write(JSON.stringify({ deck: deckSlug(deckDir), operation: operation.operationId, repair: result }, null, 2) + "\n");
+    if (!result.ok) process.exitCode = 2;
+    return;
+  }
+  for (const s of result.slides) {
+    const scopes = [...new Set(s.elements.flatMap((e) => e.properties))].sort();
+    process.stdout.write(
+      `${s.jsxPath} (${s.slideKey}): ${s.verdict}` +
+        (s.elements.length ? ` — ${s.elements.length} element${s.elements.length === 1 ? "" : "s"} [${scopes.join(", ") || "no named scope"}]` : " — nothing to change") +
+        "\n",
+    );
+    for (const line of [...s.changes, ...s.routeChanges]) process.stdout.write(`  ${line}\n`);
+    for (const e of s.elements) process.stdout.write(`  changed: ${e.elementId} ${e.action} [${e.properties.join(", ")}]\n`);
+    for (const u of s.unknown) process.stdout.write(`  note: ${u.elementId}: ${u.detail}\n`);
+    // The router has already established that the only move left is relocating
+    // a node, which the budget forbids: reported, never repaired.
+    for (const u of s.unresolved) process.stdout.write(`  note: connector ${u}\n`);
+  }
+  if (!result.ok) {
+    for (const r of result.reasons) process.stderr.write(`  [${r.code}]${r.elementId ? ` ${r.elementId}:` : ""} ${r.message}\n`);
+    fail(`REPAIR REFUSED after ${result.passes} pass${result.passes === 1 ? "" : "es"} — the deck is exactly as it was; nothing was written.`, 2);
+  }
+  const changed = result.slides.filter((s) => s.verdict === "repaired");
+  process.stdout.write(
+    `REPAIRED: ${changed.length}/${result.slides.length} slide${result.slides.length === 1 ? "" : "s"} over ${result.passes} render pass${result.passes === 1 ? "" : "es"}, verified` +
+      (changed.length
+        ? ` — next: \`slidemind view-draft ${deck}\` to see the repaired slides, then deliver: the review is one-time per deck.`
+        : " — nothing moved, so nothing was published.") +
+      "\n",
+  );
+}
+