@koda-sl/baker-cli 0.121.0 → 0.122.0-dev.4a85b9f30

package/dist/cli.js

@@ -1,19 +1,28 @@
 #!/usr/bin/env node
 import {
+  BackendClient,
   ELEVENLABS_MAX_MUSIC_LENGTH_MS,
   IMAGE_GENERATE_MODELS,
   LayerExecutionError,
   MODEL_REGISTRY,
+  REF_PREFIX,
   SEEDANCE_DURATIONS,
   ValidationError,
+  collectAssetRefLikes,
   createEngineFromEnv,
   defaultRegistry,
   describeFailureReason,
   elementMentionKeywords,
   generateCatalog,
+  isPersistedAssetRef,
+  parseRefExpr,
+  requireCredentialsFromEnv,
   resolveConcurrency,
+  sha256Hex,
+  toModelSafeImage,
+  ulid,
   validateCanvasDeep
-} from "./chunk-IWPAXJC3.js";
+} from "./chunk-43KBQLP5.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -848,6 +857,7 @@ var LINKEDIN_LIMITS = {
     choiceOptionsMax: 30,
     choiceOptionTextMax: 100,
     thankYouMessageMax: 300,
+    privacyPolicyTextMax: 2e3,
     legalDisclaimerMax: 2e3,
     consentsMax: 5,
     // Campaign Manager caps disclosure checkboxes at 5
@@ -1442,6 +1452,7 @@ var leadFormFields = {
   /** Form language, e.g. { country: "US", language: "en" }. Defaults to the account locale on LinkedIn. */
   locale: z2.object({ country: z2.string().length(2), language: z2.string().length(2) }).optional(),
   privacyPolicyUrl: httpsUrlSchema,
+  privacyPolicyText: z2.string().max(LEAD.privacyPolicyTextMax).optional(),
   questions: z2.array(leadFormQuestionSchema).min(1).max(LEAD.questionsMax),
   consents: z2.array(leadFormConsentSchema).max(LEAD.consentsMax).optional(),
   hiddenFields: z2.array(leadFormHiddenFieldSchema).max(LEAD.hiddenFieldsMax).optional(),
@@ -4662,11 +4673,11 @@ function rawTextEntries(value) {
   const values = Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
   return values.filter((v) => typeof v === "string").flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean);
 }
-function rawFileEntries(path12) {
-  if (typeof path12 !== "string" || path12.length === 0) {
+function rawFileEntries(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return [];
   }
-  return readFileSync2(path12, "utf8").split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"));
+  return readFileSync2(path15, "utf8").split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"));
 }
 function keywordEntries(args) {
   const defaultMatch = typeof args["match-type"] === "string" ? args["match-type"].toUpperCase() : void 0;
@@ -4689,19 +4700,19 @@ function keywordEntries(args) {
   }
   return entries;
 }
-function loadJsonFileArg(path12) {
-  if (typeof path12 !== "string" || path12.length === 0) {
+function loadJsonFileArg(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync2(path12, "utf8"));
+    const parsed = JSON.parse(readFileSync2(path15, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      failWriteValidation(`${path12} must contain a JSON object`);
+      failWriteValidation(`${path15} must contain a JSON object`);
     }
     return parsed;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      failWriteValidation(`${path12} is not valid JSON: ${err.message}`);
+      failWriteValidation(`${path15} is not valid JSON: ${err.message}`);
     }
     throw err;
   }
@@ -4812,10 +4823,10 @@ async function stageUpdate(kind, customerId, target, payload) {
 async function stageTarget(kind, customerId, target) {
   await stageGoogleOp({ kind, customerId, target });
 }
-async function draftAction(path12, body) {
+async function draftAction(path15, body) {
   try {
     const chatId = requireChatId();
-    const response = await apiPost(path12, { chatId, ...body });
+    const response = await apiPost(path15, { chatId, ...body });
     writeJsonEnvelope(response);
   } catch (err) {
     handleGoogleError(err);
@@ -8570,19 +8581,19 @@ function failWriteValidation2(message) {
   writeJsonEnvelope({ ok: false, error: { code: "VALIDATION_ERROR", message } });
   process.exit(1);
 }
-function loadJsonFileArg2(path12) {
-  if (typeof path12 !== "string" || path12.length === 0) {
+function loadJsonFileArg2(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync6(path12, "utf8"));
+    const parsed = JSON.parse(readFileSync6(path15, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      failWriteValidation2(`${path12} must contain a JSON object`);
+      failWriteValidation2(`${path15} must contain a JSON object`);
     }
     return parsed;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      failWriteValidation2(`${path12} is not valid JSON: ${err.message}`);
+      failWriteValidation2(`${path15} is not valid JSON: ${err.message}`);
     }
     throw err;
   }
@@ -8667,15 +8678,15 @@ function parseLocaleFlag(value) {
   }
   return { language: match[1], country: match[2].toUpperCase() };
 }
-function loadTargetingFileArg(path12) {
-  if (typeof path12 !== "string" || path12.length === 0) {
+function loadTargetingFileArg(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return void 0;
   }
-  const parsed = loadJsonFileArg2(path12);
+  const parsed = loadJsonFileArg2(path15);
   const criteria = parsed.targetingCriteria ?? parsed;
   if (!criteria.include) {
     failWriteValidation2(
-      `${path12} must contain targeting criteria with an "include" block (see baker schema ads.linkedin.campaigns.create)`
+      `${path15} must contain targeting criteria with an "include" block (see baker schema ads.linkedin.campaigns.create)`
     );
   }
   return criteria;
@@ -8710,14 +8721,14 @@ function parseCsvLine(line) {
   cells.push(current);
   return cells.map((cell) => cell.trim());
 }
-function parseListFileArg(path12, maxRows) {
-  if (typeof path12 !== "string" || path12.length === 0) {
+function parseListFileArg(path15, maxRows) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return void 0;
   }
-  const raw = readFileSync6(path12, "utf8");
+  const raw = readFileSync6(path15, "utf8");
   const lines = raw.split(/\r?\n/).filter((line) => line.trim().length > 0);
   if (lines.length < 2) {
-    failWriteValidation2(`${path12} needs a header row and at least one data row`);
+    failWriteValidation2(`${path15} needs a header row and at least one data row`);
   }
   const columns = parseCsvLine(lines[0]).map((column) => column.trim());
   const rows = [];
@@ -8736,7 +8747,7 @@ function parseListFileArg(path12, maxRows) {
     }
   }
   if (rows.length > maxRows) {
-    failWriteValidation2(`${path12} has ${rows.length} rows \u2014 the inline limit is ${maxRows}. Split the list.`);
+    failWriteValidation2(`${path15} has ${rows.length} rows \u2014 the inline limit is ${maxRows}. Split the list.`);
   }
   return { columns, rows };
 }
@@ -9381,7 +9392,7 @@ var leadFormsCreateCommand = defineCommand38({
 Required: name, headline (\u226460), privacyPolicyUrl, questions[] (\u226412; playbook: \u22644 for completion).
 Each question is a predefined profile field ({ name, predefinedField: "EMAIL" }) or a custom question ({ name, questionType: "MULTIPLE_CHOICE", options: [...] }; \u22643 custom).
 Best-practice fields the preview will nudge for if missing: 1-3 qualifying questions, consents[] (disclosure checkboxes), thankYou.message + thankYou.landingUrl|appointmentUrl.
-Also supported: locale, formImageId|formImageUrn, hiddenFields[], legalDisclaimer, thankYou.cta. Example: baker ads linkedin lead-forms create --file form.json`
+Also supported: locale, formImageId|formImageUrn, privacyPolicyText, hiddenFields[], legalDisclaimer, thankYou.cta. Example: baker ads linkedin lead-forms create --file form.json`
   },
   args: {
     ...accountArgs,
@@ -10819,11 +10830,11 @@ var updateStatusSchema = z9.enum(UPDATE_STATUSES);
 function currencyMinimums2(currencyCode) {
   return CURRENCY_MINIMUMS2[currencyCode] ?? DEFAULT_CURRENCY_MINIMUM2;
 }
-function validateDailyBudgetFloor(money, ctx, path12) {
+function validateDailyBudgetFloor(money, ctx, path15) {
   if (money?.currencyCode) {
     const min = currencyMinimums2(money.currencyCode).dailyBudgetMin;
     if (Number(money.amount) < min) {
-      ctx.addIssue({ code: "custom", path: path12, message: `below the ${min} ${money.currencyCode} daily minimum` });
+      ctx.addIssue({ code: "custom", path: path15, message: `below the ${min} ${money.currencyCode} daily minimum` });
     }
   }
 }
@@ -11311,19 +11322,19 @@ function failWriteValidation3(message) {
   writeJsonEnvelope({ ok: false, error: { code: "VALIDATION_ERROR", message } });
   process.exit(1);
 }
-function loadJsonFileArg3(path12) {
-  if (typeof path12 !== "string" || path12.length === 0) {
+function loadJsonFileArg3(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync8(path12, "utf8"));
+    const parsed = JSON.parse(readFileSync8(path15, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      failWriteValidation3(`${path12} must contain a JSON object`);
+      failWriteValidation3(`${path15} must contain a JSON object`);
     }
     return parsed;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      failWriteValidation3(`${path12} is not valid JSON: ${err.message}`);
+      failWriteValidation3(`${path15} is not valid JSON: ${err.message}`);
     }
     throw err;
   }
@@ -14385,8 +14396,8 @@ async function probeDuration(filePath) {
 }
 
 // src/commands/canvas/run.ts
-import { readFile as readFile2 } from "fs/promises";
-import path4 from "path";
+import { readFile as readFile3 } from "fs/promises";
+import path6 from "path";
 import { defineCommand as defineCommand88 } from "citty";
 
 // src/commands/canvas/placeholders.ts
@@ -14430,9 +14441,290 @@ function isResolvableRelative(value) {
   return typeof value === "string" && value.length > 0 && !value.includes("[TODO") && !path2.isAbsolute(value);
 }
 
+// src/commands/canvas/run-record.ts
+import path3 from "path";
+var MAX_RUN_NODES = 200;
+var MAX_OUTPUTS_PER_NODE = 10;
+var MAX_FINAL_OUTPUTS = 10;
+var MAX_PARAMS_PREVIEW_LENGTH = 4e3;
+function paramsPreviewFromParams(params) {
+  if (params === void 0 || params === null) return void 0;
+  const text = humanParamText(params, "prompt") ?? humanParamText(params, "source") ?? compactJson(params);
+  if (!text) return void 0;
+  return text.length > MAX_PARAMS_PREVIEW_LENGTH ? `${text.slice(0, MAX_PARAMS_PREVIEW_LENGTH - 1)}\u2026` : text;
+}
+function humanParamText(params, key) {
+  const value = params[key];
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed && !trimmed.startsWith("$ref:") ? trimmed : void 0;
+}
+function compactJson(params) {
+  try {
+    const json = JSON.stringify(params);
+    return json && json !== "{}" ? json : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var MAX_CREATIVE_SLUG_LENGTH = 100;
+function creativeSlugFromCanvasPath(filePath) {
+  const normalized = filePath.split(path3.sep).join("/");
+  const match = normalized.match(/(?:^|\/)src\/creatives\/([a-z0-9](?:[a-z0-9-]*[a-z0-9])?)\//);
+  const slug = match?.[1] ?? null;
+  return slug && slug.length <= MAX_CREATIVE_SLUG_LENGTH ? slug : null;
+}
+var OUTPUT_KINDS = /* @__PURE__ */ new Set(["image", "video", "audio", "json", "text", "font"]);
+function toRecordOutput(slot, value) {
+  const refs = collectAssetRefLikes(value);
+  const ref = refs.length === 1 ? refs[0] : null;
+  if (!ref || !isPersistedAssetRef(ref)) return null;
+  const kind = typeof ref.kind === "string" && OUTPUT_KINDS.has(ref.kind) ? ref.kind : null;
+  if (!kind) return null;
+  return {
+    slot,
+    kind,
+    sha256: ref.sha256,
+    url: ref.url,
+    mime: ref.mime,
+    width: typeof ref.width === "number" ? ref.width : void 0,
+    height: typeof ref.height === "number" ? ref.height : void 0,
+    durationMs: typeof ref.duration_ms === "number" ? ref.duration_ms : void 0
+  };
+}
+function nodeOutputsToRecord(nodeOutputs) {
+  const out = [];
+  for (const [slot, value] of Object.entries(nodeOutputs)) {
+    if (Array.isArray(value)) {
+      value.forEach((item, i) => {
+        const rec = toRecordOutput(`${slot}#${i}`, item);
+        if (rec) out.push(rec);
+      });
+    } else {
+      const rec = toRecordOutput(slot, value);
+      if (rec) out.push(rec);
+    }
+  }
+  return out.slice(0, MAX_OUTPUTS_PER_NODE);
+}
+function finalOutputsToRecord(output) {
+  if (Array.isArray(output)) {
+    return output.map((item, i) => toRecordOutput(`final#${i}`, item)).filter((rec2) => rec2 !== null).slice(0, MAX_FINAL_OUTPUTS);
+  }
+  const rec = toRecordOutput("final", output);
+  return rec ? [rec] : [];
+}
+function buildRunRecord(result, meta, plan) {
+  const nodes = result.node_runs.slice(0, MAX_RUN_NODES).map((run) => {
+    const planned = plan?.get(run.node_id);
+    return {
+      nodeId: run.node_id,
+      nodeType: run.node_type,
+      cached: run.cached,
+      credits: run.credits,
+      durationMs: run.duration_ms,
+      outputs: nodeOutputsToRecord(result.outputs_by_node[run.node_id] ?? {}),
+      deps: planned?.deps,
+      status: plan ? "completed" : void 0,
+      paramsPreview: planned?.paramsPreview
+    };
+  });
+  const finalOutputs = finalOutputsToRecord(result.output);
+  return {
+    runId: result.run_id,
+    creativeSlug: meta.creativeSlug,
+    canvasPath: meta.canvasPath,
+    canvasSha: meta.canvasSha,
+    chatId: meta.chatId,
+    status: "completed",
+    stats: {
+      totalNodes: result.stats.total_nodes,
+      cachedNodes: result.stats.cached_nodes,
+      totalCredits: result.stats.total_credits,
+      durationMs: result.stats.duration_ms
+    },
+    nodes,
+    finalOutputs: finalOutputs.length > 0 ? finalOutputs : void 0
+  };
+}
+function buildFailedRunRecord(runId, errorMessage, meta) {
+  return {
+    runId,
+    creativeSlug: meta.creativeSlug,
+    canvasPath: meta.canvasPath,
+    canvasSha: meta.canvasSha,
+    chatId: meta.chatId,
+    status: "failed",
+    errorMessage: errorMessage.slice(0, 2e3),
+    stats: { totalNodes: 0, cachedNodes: 0, totalCredits: 0, durationMs: 0 },
+    nodes: []
+  };
+}
+
+// src/commands/canvas/run-progress.ts
+var RunProgressTracker = class {
+  runId;
+  meta;
+  startedAt;
+  nodes = /* @__PURE__ */ new Map();
+  planned = false;
+  constructor(runId, meta) {
+    this.runId = runId;
+    this.meta = meta;
+    this.startedAt = Date.now();
+  }
+  apply(event) {
+    if (event.kind === "plan") {
+      for (const node of event.nodes) {
+        this.nodes.set(node.node_id, {
+          nodeId: node.node_id,
+          nodeType: node.node_type,
+          cached: false,
+          credits: 0,
+          durationMs: 0,
+          outputs: [],
+          deps: node.deps,
+          status: "pending",
+          paramsPreview: paramsPreviewFromParams(node.params)
+        });
+      }
+      this.planned = true;
+      return;
+    }
+    if (event.kind === "node_start") {
+      this.patchNode(event.node_id, { status: "running" });
+      return;
+    }
+    if (event.kind === "node_settled") {
+      this.patchNode(event.run.node_id, {
+        status: "completed",
+        cached: event.run.cached,
+        credits: event.run.credits,
+        durationMs: event.run.duration_ms,
+        outputs: nodeOutputsToRecord(event.outputs)
+      });
+      return;
+    }
+    this.patchNode(event.node_id, { status: "failed" });
+  }
+  /** True once the plan event landed — before that there is nothing worth posting. */
+  hasPlan() {
+    return this.planned;
+  }
+  /** Plan facts (deps + params preview) for stamping the terminal record's nodes. */
+  planInfo() {
+    const info = /* @__PURE__ */ new Map();
+    for (const node of this.nodes.values()) {
+      info.set(node.nodeId, { deps: node.deps ?? [], paramsPreview: node.paramsPreview });
+    }
+    return info;
+  }
+  /** The current in-flight state as a postable full record. */
+  snapshot() {
+    const nodes = [...this.nodes.values()];
+    return {
+      runId: this.runId,
+      ...this.meta,
+      status: "running",
+      stats: {
+        totalNodes: nodes.length,
+        cachedNodes: nodes.filter((n) => n.cached).length,
+        totalCredits: nodes.reduce((sum, n) => sum + n.credits, 0),
+        durationMs: Date.now() - this.startedAt
+      },
+      nodes
+    };
+  }
+  /**
+   * Terminal record for a failed run, preserving what each node got to —
+   * completed nodes keep their outputs so the graph shows exactly where the
+   * run died instead of an empty husk.
+   */
+  failedSnapshot(errorMessage) {
+    const snapshot = this.snapshot();
+    return {
+      ...snapshot,
+      status: "failed",
+      errorMessage: errorMessage.slice(0, 2e3),
+      stats: { ...snapshot.stats, durationMs: Date.now() - this.startedAt }
+    };
+  }
+  patchNode(nodeId, patch) {
+    const existing = this.nodes.get(nodeId);
+    if (!existing) return;
+    this.nodes.set(nodeId, { ...existing, ...patch, status: patch.status ?? existing.status });
+  }
+};
+var RunRecordPoster = class {
+  post;
+  latest = null;
+  inflight = null;
+  warned = false;
+  keepaliveTimer = null;
+  constructor(post) {
+    this.post = post;
+  }
+  /** Queue a progress snapshot; returns immediately. */
+  enqueue(payload) {
+    this.latest = payload;
+    if (!this.inflight) this.inflight = this.pump();
+  }
+  /**
+   * Re-post the latest snapshot on an interval even with no new node events, so
+   * the backend's `canvasRuns.updatedAt` heartbeat stays fresh during a long
+   * single-clip poll (a video_generate clip can run minutes with no
+   * intervening node events). When this process dies the keepalive stops → the
+   * run's `updatedAt` goes stale → the backend reconciliation sweep force-fails
+   * it as interrupted and surfaces the clips that finished. `produce` returns
+   * null before the plan lands (nothing worth posting yet).
+   */
+  startKeepalive(produce, intervalMs = 6e4) {
+    if (this.keepaliveTimer) return;
+    this.keepaliveTimer = setInterval(() => {
+      const snapshot = produce();
+      if (snapshot) this.enqueue(snapshot);
+    }, intervalMs);
+    this.keepaliveTimer.unref?.();
+  }
+  stopKeepalive() {
+    if (this.keepaliveTimer) {
+      clearInterval(this.keepaliveTimer);
+      this.keepaliveTimer = null;
+    }
+  }
+  /**
+   * Post the terminal record (awaited, errors surfaced to the caller). Any
+   * queued progress snapshot is superseded — the terminal record is the full
+   * state — but an in-flight POST is awaited first so it can't land after.
+   */
+  async flush(terminal) {
+    this.stopKeepalive();
+    this.latest = null;
+    if (this.inflight) await this.inflight;
+    await this.post(terminal);
+  }
+  async pump() {
+    while (this.latest) {
+      const payload = this.latest;
+      this.latest = null;
+      try {
+        await this.post(payload);
+      } catch (e) {
+        if (!this.warned) {
+          this.warned = true;
+          const msg = e instanceof Error ? e.message : String(e);
+          process.stderr.write(`[warn] live run progress not streaming (${msg})
+`);
+        }
+      }
+    }
+    this.inflight = null;
+  }
+};
+
 // src/commands/canvas/run-retention.ts
 import { rm } from "fs/promises";
-import path3 from "path";
+import path4 from "path";
 function runDirsToPrune(entries, keep, currentRunId) {
   const runs = entries.filter((e) => /^r_[0-9A-Za-z]+$/.test(e) && e !== currentRunId).sort();
   if (keep <= 0) return runs;
@@ -14449,13 +14741,52 @@ async function pruneOldRuns(outputsDir, keep, currentRunId, log) {
   const toPrune = runDirsToPrune(entries, keep, currentRunId);
   if (toPrune.length === 0) return;
   for (const dir of toPrune) {
-    await rm(path3.join(outputsDir, dir), { recursive: true, force: true }).catch(
+    await rm(path4.join(outputsDir, dir), { recursive: true, force: true }).catch(
       (e) => log(`[prune   ] could not remove ${dir}: ${e.message}`)
     );
   }
   log(`[prune   ] removed ${toPrune.length} old run dir(s), kept the ${keep} newest`);
 }
 
+// src/commands/canvas/run-resume.ts
+import { mkdir, readFile as readFile2, rm as rm2, writeFile } from "fs/promises";
+import path5 from "path";
+function markerPath(outputsDir, canvasPath) {
+  const key = sha256Hex(Buffer.from(path5.resolve(canvasPath))).slice(0, 32);
+  return path5.join(outputsDir, ".inflight", `${key}.json`);
+}
+async function resolveRunId(opts) {
+  if (opts.explicitRunId) return { runId: opts.explicitRunId, resumed: false };
+  if (!opts.fresh) {
+    const existing = await readMarkerRunId(opts.outputsDir, opts.canvasPath);
+    if (existing) return { runId: existing, resumed: true };
+  }
+  return { runId: `r_${ulid()}`, resumed: false };
+}
+async function readMarkerRunId(outputsDir, canvasPath) {
+  try {
+    const raw = await readFile2(markerPath(outputsDir, canvasPath), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.runId === "string" && parsed.runId.length > 0 ? parsed.runId : null;
+  } catch {
+    return null;
+  }
+}
+async function markRunInFlight(outputsDir, canvasPath, runId) {
+  try {
+    const file = markerPath(outputsDir, canvasPath);
+    await mkdir(path5.dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify({ runId, canvasPath: path5.resolve(canvasPath), startedAt: Date.now() }));
+  } catch {
+  }
+}
+async function clearRunMarker(outputsDir, canvasPath) {
+  try {
+    await rm2(markerPath(outputsDir, canvasPath), { force: true });
+  } catch {
+  }
+}
+
 // src/commands/canvas/run.ts
 var runCommand = defineCommand88({
   meta: { name: "run", description: "Validate and execute a canvas JSON file." },
@@ -14463,8 +14794,17 @@ var runCommand = defineCommand88({
     file: { type: "positional", required: true, description: "Path to canvas JSON" },
     "cache-dir": { type: "string", description: "Cache root (default ./canvas/.cache)" },
     "outputs-dir": { type: "string", description: "Per-run outputs root (default ./canvas)" },
-    "run-id": { type: "string", description: "Override run id" },
+    "run-id": { type: "string", description: "Override run id (also resumes that run, re-attaching its in-flight jobs)" },
+    fresh: {
+      type: "boolean",
+      default: false,
+      description: "Ignore any interrupted-run marker and start a new run id instead of resuming"
+    },
     "cache-policy": { type: "string", description: "read_write | bypass | read_only" },
+    regenerate: {
+      type: "string",
+      description: "Comma-separated node ids to force fresh THIS run (e.g. --regenerate gen_4x5,gen_9x16), bypassing the content cache for just those nodes + everything downstream. For a persistent re-render, bump a node's `regenerate` field in the canvas JSON instead."
+    },
     concurrency: {
       type: "string",
       description: "Max nodes per layer in flight at once (default 5; env BAKER_CANVAS_CONCURRENCY)"
@@ -14476,11 +14816,23 @@ var runCommand = defineCommand88({
     "keep-runs": {
       type: "string",
       description: "After the run, prune old r_* run dirs, keeping the N newest (off by default)"
+    },
+    "remote-cache": {
+      type: "string",
+      description: "on | off \u2014 company-scoped remote cache + durable asset persistence (default on; env BAKER_CANVAS_REMOTE_CACHE)"
+    },
+    // citty consumes any `--no-<flag>` as a negation of `<flag>`, so the
+    // opt-out spelling `--no-record` requires the flag to be named `record`
+    // (a literal "no-record" arg would never receive a value).
+    record: {
+      type: "boolean",
+      default: true,
+      description: "Post the durable run-history record to Baker (disable with --no-record)"
     }
   },
   async run({ args }) {
-    const filePath = path4.resolve(String(args.file));
-    const raw = await readFile2(filePath, "utf8");
+    const filePath = path6.resolve(String(args.file));
+    const raw = await readFile3(filePath, "utf8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -14490,7 +14842,7 @@ var runCommand = defineCommand88({
 `);
       process.exit(2);
     }
-    parsed = resolveRelativeCanvasPaths(parsed, path4.dirname(filePath));
+    parsed = resolveRelativeCanvasPaths(parsed, path6.dirname(filePath));
     const pending = unsuppliedPlaceholderAssets(parsed);
     if (pending.length > 0) {
       process.stderr.write(
@@ -14510,26 +14862,86 @@ var runCommand = defineCommand88({
       );
       process.exit(2);
     }
+    let regenerate;
+    if (args.regenerate !== void 0) {
+      const requested = String(args.regenerate).split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+      const known = new Set(canvasNodeIds(parsed));
+      const unknown = requested.filter((id) => !known.has(id));
+      if (unknown.length > 0) {
+        process.stderr.write(
+          `${JSON.stringify(
+            {
+              ok: false,
+              error: {
+                code: "unknown_regenerate_node",
+                message: `--regenerate names node id(s) not in this canvas: ${unknown.join(", ")}. Known ids: ${[...known].join(", ")}`
+              }
+            },
+            null,
+            2
+          )}
+`
+        );
+        process.exit(2);
+      }
+      if (requested.length > 0) {
+        regenerate = new Set(requested);
+        process.stdout.write(`[regenerate] forcing fresh this run: ${[...regenerate].join(", ")} (+ downstream)
+`);
+      }
+    }
+    const remoteCache = args["remote-cache"] !== void 0 ? String(args["remote-cache"]) !== "off" : void 0;
     const engine = createEngineFromEnv({
       cacheDir: args["cache-dir"] ? String(args["cache-dir"]) : void 0,
       outputsDir: args["outputs-dir"] ? String(args["outputs-dir"]) : void 0,
       log: (line) => process.stdout.write(`${line}
-`)
+`),
+      remoteCache
+    });
+    const outputsDir = args["outputs-dir"] ? path6.resolve(String(args["outputs-dir"])) : path6.resolve("canvas");
+    const { runId, resumed } = await resolveRunId({
+      explicitRunId: args["run-id"] ? String(args["run-id"]) : void 0,
+      fresh: args.fresh === true,
+      outputsDir,
+      canvasPath: filePath
     });
+    if (resumed) {
+      process.stdout.write(`[resume] continuing interrupted run ${runId} \u2014 in-flight jobs re-attach, cached nodes skip
+`);
+    }
+    await markRunInFlight(outputsDir, filePath, runId);
+    const recordMeta = {
+      creativeSlug: creativeSlugFromCanvasPath(filePath) ?? void 0,
+      canvasPath: path6.relative(process.cwd(), filePath) || void 0,
+      canvasSha: sha256Hex(Buffer.from(raw)),
+      chatId: getEnv().BAKER_CHAT_ID || void 0
+    };
+    const record = args.record === false ? null : buildRecorder();
+    const progress = record ? new RunProgressTracker(runId, recordMeta) : null;
+    const poster = record ? new RunRecordPoster(record) : null;
+    if (progress && poster) {
+      poster.startKeepalive(() => progress.hasPlan() ? progress.snapshot() : null);
+    }
     try {
       const policy = args["cache-policy"] ?? "read_write";
       const result = await engine.run(parsed, {
-        run_id: args["run-id"] ? String(args["run-id"]) : void 0,
+        run_id: runId,
         cache_policy: policy,
         concurrency: resolveConcurrency(
           // --concurrency wins; --parallel is the discoverable alias for the same bound.
           (args.concurrency ?? args.parallel) !== void 0 ? String(args.concurrency ?? args.parallel) : void 0,
           process.env.BAKER_CANVAS_CONCURRENCY
-        )
+        ),
+        regenerate,
+        onProgress: progress && poster ? (event) => {
+          progress.apply(event);
+          if (progress.hasPlan()) poster.enqueue(progress.snapshot());
+        } : void 0
       });
+      await clearRunMarker(outputsDir, filePath);
+      if (poster) await poster.flush(buildRunRecord(result, recordMeta, progress?.planInfo()));
       const keepRuns = args["keep-runs"] !== void 0 ? Number(args["keep-runs"]) : void 0;
       if (keepRuns !== void 0 && Number.isFinite(keepRuns)) {
-        const outputsDir = args["outputs-dir"] ? path4.resolve(String(args["outputs-dir"])) : path4.resolve("canvas");
         await pruneOldRuns(outputsDir, keepRuns, result.run_id, (line) => process.stdout.write(`${line}
 `));
       }
@@ -14548,6 +14960,7 @@ var runCommand = defineCommand88({
 `
       );
     } catch (e) {
+      await clearRunMarker(outputsDir, filePath);
       if (e instanceof ValidationError) {
         process.stderr.write(
           `${JSON.stringify({ ok: false, error: { code: "validation", issues: e.issues } }, null, 2)}
@@ -14555,8 +14968,10 @@ var runCommand = defineCommand88({
         );
         process.exit(2);
       }
+      const failedPayload = (message) => progress?.hasPlan() ? progress.failedSnapshot(message) : buildFailedRunRecord(runId, message, recordMeta);
       if (e instanceof LayerExecutionError) {
         const failures = e.failures.map((f) => ({ node_id: f.nodeId, message: describeFailureReason(f.reason) }));
+        if (poster) await poster.flush(failedPayload(e.message));
         process.stderr.write(
           `${JSON.stringify({ ok: false, error: { code: "runtime", message: e.message, failures } }, null, 2)}
 `
@@ -14564,16 +14979,35 @@ var runCommand = defineCommand88({
         process.exit(1);
       }
       const msg = e instanceof Error ? e.message : String(e);
+      if (poster) await poster.flush(failedPayload(msg));
       process.stderr.write(`${JSON.stringify({ ok: false, error: { code: "runtime", message: msg } }, null, 2)}
 `);
       process.exit(1);
     }
   }
 });
+function canvasNodeIds(parsed) {
+  const nodes = parsed?.nodes;
+  if (!Array.isArray(nodes)) return [];
+  return nodes.map((node) => node?.id).filter((id) => typeof id === "string");
+}
+function buildRecorder() {
+  return async (payload) => {
+    try {
+      const creds = requireCredentialsFromEnv();
+      const client = new BackendClient({ baseUrl: creds.url, apiKey: creds.apiKey });
+      await client.recordRun(payload);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`[warn] run record not persisted (${msg})
+`);
+    }
+  };
+}
 
 // src/commands/canvas/scaffold-static-ad.ts
-import { readFile as readFile3, writeFile } from "fs/promises";
-import path6 from "path";
+import { access, mkdir as mkdir2, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
+import path9 from "path";
 import { defineCommand as defineCommand89 } from "citty";
 
 // src/engine/scaffold/staticAd.ts
@@ -14759,18 +15193,175 @@ function staticAdReport(input, elementsInput, opts) {
   };
 }
 
+// src/commands/canvas/creative-definition.ts
+import path7 from "path";
+var PLATFORM_VALUES = ["meta", "google", "linkedin", "tiktok", "youtube", "x", "other"];
+var FORMAT_VALUES = ["1:1", "4:5", "9:16", "16:9", "1.91:1"];
+function titleFromSlug(slug) {
+  const title = slug.split("-").filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  return title || slug;
+}
+function resolvePlatform(platform) {
+  const value = platform?.trim();
+  return value && PLATFORM_VALUES.includes(value) ? value : "meta";
+}
+function resolveFormats(aspect) {
+  const value = aspect?.trim();
+  return value && FORMAT_VALUES.includes(value) ? [value] : ["4:5"];
+}
+function referenceRelativePath(kind, ext) {
+  const name = kind === "video" ? "source" : "original";
+  return `references/${name}${ext}`;
+}
+function describeBlueprintIntent(blueprint) {
+  const intent = blueprint?.ad_intent;
+  if (typeof intent === "string" && intent.trim()) return intent.trim();
+  if (intent && typeof intent === "object") {
+    const summary = intent.summary ?? intent.feeling;
+    if (typeof summary === "string" && summary.trim()) return summary.trim();
+  }
+  return void 0;
+}
+function yamlScalar(value) {
+  return JSON.stringify(value);
+}
+function buildCreativeDefinition(input) {
+  const lines = ["---", `title: ${yamlScalar(input.title)}`, `kind: ${input.kind}`, `platform: ${input.platform}`];
+  lines.push(`formats: [${input.formats.map(yamlScalar).join(", ")}]`);
+  lines.push(`status: ${input.status ?? "draft"}`);
+  if (input.sourceReferenceUrl) lines.push(`sourceReferenceUrl: ${yamlScalar(input.sourceReferenceUrl)}`);
+  if (input.sourceAdvertiser) lines.push(`sourceAdvertiser: ${yamlScalar(input.sourceAdvertiser)}`);
+  if (input.sourceKind) lines.push(`sourceKind: ${input.sourceKind}`);
+  if (input.sourcePath) lines.push(`sourcePath: ${yamlScalar(input.sourcePath)}`);
+  lines.push("---", "");
+  lines.push(input.description?.trim() || `${input.title} \u2014 canvas-built ${input.kind} ad for ${input.platform}.`);
+  lines.push("");
+  return lines.join("\n");
+}
+
 // src/commands/canvas/scaffold-static-ad-paths.ts
-import path5 from "path";
-function resolveScaffoldStaticAdPaths(rawFile, out, cwd = process.cwd()) {
+import path8 from "path";
+function resolveScaffoldStaticAdPaths(rawFile, out, cwd = process.cwd(), slug) {
   const file = rawFile.trim();
   const imageIsUrl = /^https?:\/\//i.test(file);
-  const imageSource = imageIsUrl ? file : path5.resolve(cwd, file);
-  const outPath = out ? path5.resolve(cwd, out) : imageIsUrl ? path5.join(cwd, "static-ad.canvas.json") : path5.join(path5.dirname(imageSource), "static-ad.canvas.json");
-  const blueprintPath = path5.join(path5.dirname(outPath), "prompt.json");
-  return { imageIsUrl, imageSource, outPath, blueprintPath };
+  const imageSource = imageIsUrl ? file : path8.resolve(cwd, file);
+  const outPath = out ? path8.resolve(cwd, out) : slug ? path8.join(cwd, "src", "creatives", slug, `${slug}.canvas.json`) : imageIsUrl ? path8.join(cwd, "static-ad.canvas.json") : path8.join(path8.dirname(imageSource), "static-ad.canvas.json");
+  const blueprintPath = path8.join(path8.dirname(outPath), "prompt.json");
+  const creativeDir = slug ? path8.dirname(outPath) : null;
+  const definitionPath = creativeDir ? path8.join(creativeDir, "_definition.md") : null;
+  const referencesDir = creativeDir ? path8.join(creativeDir, "references") : null;
+  return { imageIsUrl, imageSource, outPath, blueprintPath, creativeDir, definitionPath, referencesDir };
+}
+var SCAFFOLD_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+var SCAFFOLD_SLUG_MAX_LENGTH = 100;
+function isValidScaffoldSlug(slug) {
+  return slug.length <= SCAFFOLD_SLUG_MAX_LENGTH && SCAFFOLD_SLUG_PATTERN.test(slug);
+}
+
+// src/commands/canvas/definition-graph.ts
+var MAX_NODES = 300;
+function walkStrings(value, cb) {
+  if (typeof value === "string") {
+    cb(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const v of value) walkStrings(v, cb);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const v of Object.values(value)) walkStrings(v, cb);
+  }
+}
+function canvasToDefinitionGraph(canvas) {
+  const rawNodes = canvas?.nodes;
+  if (!Array.isArray(rawNodes)) return null;
+  const parsed = [];
+  for (const raw of rawNodes) {
+    const id = raw?.id;
+    const type = raw?.type;
+    if (typeof id !== "string" || typeof type !== "string") continue;
+    parsed.push({ id, type, inputs: raw.inputs, params: raw.params });
+    if (parsed.length >= MAX_NODES) break;
+  }
+  if (parsed.length === 0) return null;
+  const ids = new Set(parsed.map((n) => n.id));
+  const nodes = parsed.map(({ id, type, inputs, params }) => {
+    const deps = /* @__PURE__ */ new Set();
+    const collect = (s) => {
+      if (!s.startsWith(REF_PREFIX)) return;
+      const expr = parseRefExpr(s);
+      if (expr && expr.nodeId !== id && ids.has(expr.nodeId)) deps.add(expr.nodeId);
+    };
+    walkStrings(inputs, collect);
+    walkStrings(params, collect);
+    return deps.size > 0 ? { id, type, deps: [...deps] } : { id, type };
+  });
+  const rawOutput = canvas?.output;
+  const outNode = rawOutput?.node;
+  const outSlot = rawOutput?.output;
+  const output = typeof outNode === "string" && typeof outSlot === "string" ? { node: outNode, output: outSlot } : void 0;
+  return { nodes, output };
+}
+
+// src/commands/canvas/sync-definition.ts
+async function syncCreativeDefinitionBestEffort(input) {
+  const chatId = process.env.BAKER_CHAT_ID;
+  if (!chatId) return;
+  const graph = canvasToDefinitionGraph(input.canvas);
+  if (!graph || graph.nodes.length === 0) return;
+  try {
+    const creds = requireCredentialsFromEnv();
+    const client = new BackendClient({ baseUrl: creds.url, apiKey: creds.apiKey });
+    await client.syncCreativeDefinition({
+      slug: input.slug,
+      title: input.title,
+      platform: input.platform,
+      formats: input.formats,
+      sourceReferenceUrl: input.sourceReferenceUrl,
+      graph,
+      chatId
+    });
+    process.stdout.write(`[definition] synced workflow graph (${graph.nodes.length} nodes) \u2014 view it in the dashboard
+`);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`[warn] workflow graph not synced (${msg})
+`);
+  }
 }
 
 // src/commands/canvas/scaffold-static-ad.ts
+async function fileExists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var MODEL_SAFE_EXT_BY_MIME = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/gif": ".gif",
+  "image/webp": ".webp"
+};
+async function copySourceIntoReferences(source, isUrl, referencesDir) {
+  await mkdir2(referencesDir, { recursive: true });
+  let bytes;
+  if (isUrl) {
+    const res = await fetch(source);
+    if (!res.ok) throw new Error(`failed to download source image (${res.status})`);
+    bytes = Buffer.from(await res.arrayBuffer());
+  } else {
+    bytes = await readFile4(source);
+  }
+  const safe = await toModelSafeImage(bytes);
+  const relPath = referenceRelativePath("image", MODEL_SAFE_EXT_BY_MIME[safe.mime] ?? ".png");
+  const dest = path9.join(referencesDir, path9.basename(relPath));
+  await writeFile2(dest, safe.bytes);
+  return relPath;
+}
 function resolveModel(kind, preferred) {
   const ids = Object.keys(MODEL_REGISTRY[kind]);
   return ids.includes(preferred) ? preferred : ids[0] ?? preferred;
@@ -14813,7 +15404,7 @@ DROP background extras, decorative props, generic scenery, and anything small or
 For each kept element return: { "type": one of logo|product|person|animal|badge, "label": a short UPPER_SNAKE_CASE name (e.g. LOGO, PRODUCT, HERO_DOG, TRUSTPILOT), "description": a concrete reusable description to source/shoot the real asset (include the exact expression for a living subject, and its castable attributes \u2014 breed/species for an animal, apparent age band, apparent origin/ethnicity, and wardrobe/setting for a person \u2014 so it can be recast to fit OUR audience/market), "expression": the facial expression for a living subject or null, "reason": why it is identity-critical, "locator": the blueprint entry this element came from as { "collection": one of "subjects" | "people" | "brands_logos", "index": its 0-based position in that array } (people -> people; logos/badges -> brands_logos; products/animals/objects -> subjects). Output ONLY the JSON object.`;
 async function loadAssetText(ref, label) {
   const r = ref;
-  if (typeof r?.path === "string") return readFile3(r.path, "utf8");
+  if (typeof r?.path === "string") return readFile4(r.path, "utf8");
   if (typeof r?.url === "string") {
     const res = await fetch(r.url);
     if (!res.ok) throw new Error(`failed to fetch ${label} (${res.status})`);
@@ -14930,6 +15521,16 @@ var scaffoldStaticAdCommand = defineCommand89({
     file: { type: "positional", required: true, description: "Path or http(s) URL to the source/inspiration image" },
     context: { type: "string", description: "Known provenance (advertiser, category, market) to ground the describe" },
     out: { type: "string", description: "Output canvas path (default <image-dir>/static-ad.canvas.json)" },
+    slug: {
+      type: "string",
+      description: "Creative slug \u2014 writes the canvas to src/creatives/<slug>/<slug>.canvas.json (repo convention)"
+    },
+    title: { type: "string", description: "Creative title for _definition.md (default: title-cased slug)" },
+    platform: {
+      type: "string",
+      description: "Ad platform for _definition.md (meta|google|linkedin|tiktok|youtube|x|other; default meta)"
+    },
+    advertiser: { type: "string", description: "Source advertiser recorded in _definition.md" },
     "describe-model": { type: "string", description: "Override the image_describe model id" },
     "select-model": { type: "string", description: "Override the text_generate model id for element selection" },
     "layout-model": { type: "string", description: "Override the text_generate model id for the layout pass" },
@@ -14938,10 +15539,21 @@ var scaffoldStaticAdCommand = defineCommand89({
     "skip-font": { type: "boolean", description: "Skip the brand-font \u2192 type-specimen slot" }
   },
   async run({ args }) {
-    const { imageIsUrl, imageSource, outPath, blueprintPath } = resolveScaffoldStaticAdPaths(
+    const slug = args.slug ? String(args.slug) : void 0;
+    if (slug && !isValidScaffoldSlug(slug)) {
+      process.stderr.write(
+        `${JSON.stringify({ ok: false, error: { code: "invalid_slug", message: "--slug must be lowercase kebab (a-z, 0-9, hyphens), max 100 chars" } }, null, 2)}
+`
+      );
+      process.exit(2);
+    }
+    const { imageIsUrl, imageSource, outPath, blueprintPath, definitionPath, referencesDir } = resolveScaffoldStaticAdPaths(
       String(args.file),
-      args.out ? String(args.out) : void 0
+      args.out ? String(args.out) : void 0,
+      process.cwd(),
+      slug
     );
+    await mkdir2(path9.dirname(outPath), { recursive: true });
     const { describeModel, selectModel, layoutModel, genModel } = resolveModels(args);
     const describeCanvas = buildDescribeCanvas(
       imageSource,
@@ -14956,13 +15568,23 @@ var scaffoldStaticAdCommand = defineCommand89({
     if (layout && annotated && typeof annotated === "object") {
       annotated.layout = layout;
     }
-    await writeFile(blueprintPath, `${JSON.stringify(annotated, null, 2)}
+    await writeFile2(blueprintPath, `${JSON.stringify(annotated, null, 2)}
 `, "utf8");
+    let canvasImagePath = imageSource;
+    let canvasImageIsUrl = imageIsUrl;
+    let canvasBlueprintPath = blueprintPath;
+    let sourceRelPath;
+    if (referencesDir) {
+      sourceRelPath = await copySourceIntoReferences(imageSource, imageIsUrl, referencesDir);
+      canvasImagePath = sourceRelPath;
+      canvasImageIsUrl = false;
+      canvasBlueprintPath = "./prompt.json";
+    }
     const opts = {
       genModel,
-      imagePath: imageSource,
-      imageIsUrl,
-      blueprintPath,
+      imagePath: canvasImagePath,
+      imageIsUrl: canvasImageIsUrl,
+      blueprintPath: canvasBlueprintPath,
       aspectRatio: args.aspect ? String(args.aspect) : void 0,
       includeFont: !args["skip-font"]
     };
@@ -14982,14 +15604,43 @@ var scaffoldStaticAdCommand = defineCommand89({
       );
       process.exit(2);
     }
-    await writeFile(outPath, `${JSON.stringify(canvas, null, 2)}
+    await writeFile2(outPath, `${JSON.stringify(canvas, null, 2)}
 `, "utf8");
+    if (definitionPath && !await fileExists(definitionPath)) {
+      await writeFile2(
+        definitionPath,
+        buildCreativeDefinition({
+          title: args.title ? String(args.title) : titleFromSlug(slug ?? ""),
+          kind: "static",
+          platform: resolvePlatform(args.platform ? String(args.platform) : void 0),
+          formats: resolveFormats(args.aspect ? String(args.aspect) : report.aspect_ratio),
+          sourceReferenceUrl: imageIsUrl ? imageSource : void 0,
+          sourceAdvertiser: args.advertiser ? String(args.advertiser) : args.context ? String(args.context) : void 0,
+          sourceKind: "image",
+          sourcePath: sourceRelPath,
+          description: describeBlueprintIntent(blueprint)
+        }),
+        "utf8"
+      );
+    }
+    if (slug) {
+      await syncCreativeDefinitionBestEffort({
+        slug,
+        title: args.title ? String(args.title) : titleFromSlug(slug),
+        platform: resolvePlatform(args.platform ? String(args.platform) : void 0),
+        formats: resolveFormats(args.aspect ? String(args.aspect) : report.aspect_ratio),
+        sourceReferenceUrl: imageIsUrl ? imageSource : void 0,
+        canvas
+      });
+    }
     process.stdout.write(
       `${JSON.stringify(
         {
           ok: true,
           canvas_path: outPath,
           prompt_path: blueprintPath,
+          definition_path: definitionPath ?? void 0,
+          source_reference: sourceRelPath ?? void 0,
           output: canvas.output,
           models: { describe: describeModel, select: selectModel, layout: layoutModel, gen: opts.genModel },
           aspect_ratio: report.aspect_ratio,
@@ -15000,10 +15651,10 @@ var scaffoldStaticAdCommand = defineCommand89({
             run_estimated_credits: validation.estimatedCredits
           },
           checklist: {
-            edit_prompt: `Edit ${path6.basename(blueprintPath)} \u2014 it is the blueprint generated from your image; rewrite it into the ad you want (palette, copy, claims, subjects). It feeds the generator directly.`,
+            edit_prompt: `Edit ${path9.basename(blueprintPath)} \u2014 it is the blueprint generated from your image; rewrite it into the ad you want (palette, copy, claims, subjects). It feeds the generator directly.`,
             assets_to_supply: report.elements,
             font_slot: report.includes_font ? "Drop a brand font at the [TODO] brandfont path, or delete the brandfont + type_ref nodes to skip it." : "skipped (--skip-font)",
-            note: "Replace every [TODO] ingest path with a real file, then `baker canvas validate` and `baker canvas run`. Running generates a billed image \u2014 it is not free."
+            note: "Populate as you go: for each [TODO] ingest slot, source its real asset and wire it into the slot right away \u2014 one at a time, not all sourced first then reconciled at the end. When every slot is filled, `baker canvas validate` then `baker canvas run`. Running generates a billed image \u2014 it is not free."
           }
         },
         null,
@@ -15015,13 +15666,14 @@ var scaffoldStaticAdCommand = defineCommand89({
 });
 
 // src/commands/canvas/scaffold-video.ts
-import { cp, mkdir, readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
-import path9 from "path";
+import { access as access2, cp, mkdir as mkdir3, readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import path12 from "path";
 import { defineCommand as defineCommand90 } from "citty";
 
 // src/engine/nodes/local/lib/sceneDetect.ts
 import { execFile as execFile2 } from "child_process";
-import { mkdtemp, readdir as readdir2, readFile as readFile4, rm as rm2 } from "fs/promises";
+import { mkdtemp, readdir as readdir2, readFile as readFile5, rm as rm3 } from "fs/promises";
 import { tmpdir } from "os";
 import { join as join2 } from "path";
 import { promisify as promisify2 } from "util";
@@ -15097,9 +15749,9 @@ async function runSceneDetectOnce(filePath, threshold, minSceneLenS, timeoutMs)
     );
     const csvName = (await readdir2(outDir)).find((f) => f.toLowerCase().endsWith(".csv"));
     if (!csvName) return [];
-    return parsePySceneDetectCsvCuts(await readFile4(join2(outDir, csvName), "utf-8"));
+    return parsePySceneDetectCsvCuts(await readFile5(join2(outDir, csvName), "utf-8"));
   } finally {
-    await rm2(outDir, { recursive: true, force: true });
+    await rm3(outDir, { recursive: true, force: true });
   }
 }
 async function detectSceneCutsPySceneDetect(filePath, opts = {}) {
@@ -15724,6 +16376,13 @@ function slimBlueprintForSelection(blueprintInput) {
   }
   return out;
 }
+function slimBlueprintForFrameStyle(blueprintInput) {
+  if (!blueprintInput || typeof blueprintInput !== "object" || Array.isArray(blueprintInput)) return blueprintInput;
+  const bp = blueprintInput;
+  const out = {};
+  for (const k of ["version", "source", "global", "reference_elements"]) if (k in bp) out[k] = bp[k];
+  return out;
+}
 function roleForType2(type) {
   switch (type.toLowerCase()) {
     case "logo":
@@ -15981,9 +16640,10 @@ function buildFrameRef(edge, url, framePrompt, present, ctx, nodes) {
     id: genId,
     type: "image_generate",
     // `params.prompt` is this frame's authoritative, edit-per-frame description.
-    // `target_blueprint` is the shared ad spec (cast identity, palette, brand, type)
-    // the frame must stay consistent with — editing one frame never touches another.
-    inputs: { target_blueprint: "$ref:prompt.asset", ...reference.length > 0 ? { reference } : {} },
+    // `target_blueprint` is the SLIM shared ad spec (global cast identity, palette, brand,
+    // type — no per-scene content) the frame must stay consistent with; editing one frame
+    // never touches another, and no image inlines the whole film to render one frame.
+    inputs: { target_blueprint: "$ref:prompt_style.asset", ...reference.length > 0 ? { reference } : {} },
     params: genParams
   });
   return `$ref:${genId}.images#0`;
@@ -16505,18 +17165,24 @@ function emitFlashHold(i, scene, slots, ctx, lengths, out, outAr, nodes, clips)
   });
   clips.push({ ref: `$ref:s${i}_clip.video`, scene_s: lengths.dur, out });
 }
-function emitScreenScene(i, scene, lengths, out, outAr, nodes, clips) {
-  const label = commentSafe((scene.summary || scene.start_frame_prompt || "the app screen").slice(0, 120));
-  const refId = `s${i}_screen_ref`;
-  nodes.push({
-    id: refId,
-    type: "ingest",
-    params: {
-      source: "path",
-      path: `[TODO: supply the REAL screen for "${label}" \u2014 NEVER AI-generate a UI. Capture a clean, text-free screenshot with \`baker images screenshot https://<brand-domain>/<path>\` (image-library skill); spoken/overlay text rides the overlay layer, not the screenshot]`,
-      expect: "image"
-    }
-  });
+function emitScreenScene(i, scene, lengths, out, outAr, surfaceIngests, nodes, clips) {
+  const regions = (scene.composition?.regions ?? []).filter((r) => Boolean(r) && typeof r === "object");
+  const surfaceId = regions.find((r) => r.surface_id)?.surface_id;
+  let refId = surfaceId ? surfaceIngests.get(surfaceId) : void 0;
+  if (!refId) {
+    const label = commentSafe((scene.summary || scene.start_frame_prompt || "the app screen").slice(0, 120));
+    refId = `s${i}_screen_ref`;
+    nodes.push({
+      id: refId,
+      type: "ingest",
+      params: {
+        source: "path",
+        path: `[TODO: supply the REAL screen for "${label}" \u2014 NEVER AI-generate a UI. Capture a clean, text-free screenshot with \`baker images screenshot https://<brand-domain>/<path>\` (image-library skill); spoken/overlay text rides the overlay layer, not the screenshot]`,
+        expect: "image"
+      }
+    });
+    if (surfaceId) surfaceIngests.set(surfaceId, refId);
+  }
   nodes.push({
     id: `s${i}_clip`,
     type: "ffmpeg",
@@ -16760,9 +17426,16 @@ function makePresenterPresent(slots, canonical, opts = {}) {
     return presence.has(sceneIndex);
   };
 }
-var PAUSE_GAP_S = 0.6;
 var SEEDANCE_SAFE_MAX_S = SEEDANCE_DURATIONS.find((d) => d >= 10) ?? 10;
 var PHRASE_MAX_S = SEEDANCE_SAFE_MAX_S;
+var PAUSE_GAP_S = 0.6;
+function isAdjacentShownCut(ln, lastShownScene, scenes) {
+  if (!ln.shown || lastShownScene === null) return false;
+  return ln.sceneIndex === lastShownScene + 1 && scenes[ln.sceneIndex]?.continues_previous !== true;
+}
+function breaksPhrase(cur, ln, lineCover, lineClipStart, scenes) {
+  return cur.speaker !== ln.speaker || ln.start - cur.end > PAUSE_GAP_S || isAdjacentShownCut(ln, cur.lastShownScene, scenes) || Math.max(cur.coverEnd, lineCover) - Math.min(cur.clipStart, lineClipStart) > PHRASE_MAX_S;
+}
 var JOIN_DEDUP_MAX_WORDS = 4;
 function joinKey(word) {
   return word.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
@@ -16805,10 +17478,7 @@ function collapseVoiceover(blueprint) {
   const presenter = [...presenters][0];
   return (speaker) => NARRATOR_SPEAKERS.has(speaker.toLowerCase()) ? presenter : speaker;
 }
-function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, presentStrict) {
-  const casts = castIdSet(blueprint);
-  const cameraOn = onCameraDialogue(blueprint);
-  const sceneEndS = (i) => blueprint.scenes[i]?.end_s ?? blueprint.scenes[i]?.start_s ?? 0;
+function multiSpeakerScenes(blueprint, casts, cameraOn, canonical, presentStrict) {
   const multiSpeaker = /* @__PURE__ */ new Set();
   blueprint.scenes.forEach((scene, i) => {
     const onCamAll = new Set(
@@ -16818,32 +17488,45 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
     const effective = onCamPresent.length > 0 ? new Set(onCamPresent) : onCamAll;
     if (effective.size >= 2) multiSpeaker.add(i);
   });
-  const lines = blueprint.scenes.flatMap(
-    (scene, sceneIndex) => compositeScenes.has(sceneIndex) ? [] : (scene.dialogue ?? []).filter((l) => Boolean(l.line?.trim())).map((l) => {
+  return multiSpeaker;
+}
+function lineClipWindow(ln, scenes) {
+  if (!ln.shown) return { cover: ln.end, clipStart: ln.start };
+  const sc = scenes[ln.sceneIndex];
+  const sceneEnd = sc?.end_s ?? sc?.start_s ?? 0;
+  return { cover: Math.max(ln.end, sceneEnd), clipStart: Math.min(ln.start, sc?.start_s ?? ln.start) };
+}
+function dialogueLines(blueprint, ctx) {
+  return blueprint.scenes.flatMap((scene, sceneIndex) => {
+    if (ctx.compositeScenes.has(sceneIndex)) return [];
+    return (scene.dialogue ?? []).filter((l) => Boolean(l.line?.trim())).map((l) => {
       const raw = l.speaker ?? "voiceover";
-      const sp = canonical(raw);
       const text = l.line.trim();
       const start = l.start_s ?? scene.start_s ?? 0;
+      const shown = l.on_camera !== false && !sceneIsAllGraphic(scene) && isOnCameraSpeaker(raw, ctx.casts, ctx.cameraOn) && !ctx.multiSpeaker.has(sceneIndex) && ctx.presenterPresent(ctx.canonical(raw), sceneIndex);
       return {
         sceneIndex,
-        speaker: sp,
-        // Shown = a cast member speaking AND their element is actually on screen
-        // here (not a cutaway). A b-roll cutaway mid-phrase fails this and gets
-        // its own clip while the phrase voice plays under it. An explicit
-        // deconstruct voiceover stamp (`on_camera: false`) wins over element
-        // presence — a speaker pictured in a photo is "present" but not talking.
-        // An all-graphic composition (no camera region) is voiceover by
-        // definition: nobody is on screen to lip-sync.
-        shown: l.on_camera !== false && !sceneIsAllGraphic(scene) && isOnCameraSpeaker(raw, casts, cameraOn) && !multiSpeaker.has(sceneIndex) && presenterPresent(sp, sceneIndex),
+        speaker: ctx.canonical(raw),
+        shown,
         start,
-        // Real speech end. When the deconstruct gives no end_s, estimate it from
-        // the words — NOT the scene end (which would fabricate continuity across
-        // a long silent b-roll gap and wrongly merge two separate phrases).
         end: l.end_s ?? start + estSpeechS(text),
         text
       };
-    })
-  ).sort((a, b) => a.start - b.start);
+    });
+  }).sort((a, b) => a.start - b.start);
+}
+function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, presentStrict) {
+  const casts = castIdSet(blueprint);
+  const cameraOn = onCameraDialogue(blueprint);
+  const multiSpeaker = multiSpeakerScenes(blueprint, casts, cameraOn, canonical, presentStrict);
+  const lines = dialogueLines(blueprint, {
+    compositeScenes,
+    multiSpeaker,
+    canonical,
+    casts,
+    cameraOn,
+    presenterPresent
+  });
   const phrases = [];
   let cur = null;
   const flush = () => {
@@ -16861,12 +17544,8 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
     cur = null;
   };
   for (const ln of lines) {
-    const lineCover = ln.shown ? Math.max(ln.end, sceneEndS(ln.sceneIndex)) : ln.end;
-    const lineClipStart = ln.shown ? Math.min(ln.start, blueprint.scenes[ln.sceneIndex]?.start_s ?? ln.start) : ln.start;
-    const breakRun = !cur || cur.speaker !== ln.speaker || ln.start - cur.end > PAUSE_GAP_S || // Cap by SCENE COVERAGE span, not line end — a presenter run whose sliced scenes span
-    // more than one Seedance clip splits into the next take here (at this scene's
-    // boundary, never mid-scene), so no segment ever reads past the generated clip.
-    Math.max(cur.coverEnd, lineCover) - Math.min(cur.clipStart, lineClipStart) > PHRASE_MAX_S;
+    const { cover: lineCover, clipStart: lineClipStart } = lineClipWindow(ln, blueprint.scenes);
+    const breakRun = !cur || breaksPhrase(cur, ln, lineCover, lineClipStart, blueprint.scenes);
     if (breakRun || !cur) {
       flush();
       cur = {
@@ -16877,6 +17556,7 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
         coverEnd: lineCover,
         clipStart: lineClipStart,
         texts: [ln.text],
+        lastShownScene: ln.shown ? ln.sceneIndex : null,
         shown: /* @__PURE__ */ new Set()
       };
     } else {
@@ -16884,6 +17564,7 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
       cur.end = Math.max(cur.end, ln.end);
       cur.coverEnd = Math.max(cur.coverEnd, lineCover);
       cur.clipStart = Math.min(cur.clipStart, lineClipStart);
+      if (ln.shown) cur.lastShownScene = ln.sceneIndex;
     }
     if (ln.shown) cur.shown.add(ln.sceneIndex);
   }
@@ -16991,19 +17672,12 @@ function emitPhraseClip(phrase, voiceNode, env, nodes, out) {
     inputs: { clip: clipRef },
     params: { args: audioExtractArgs(extractLen, speechOffset), outputs: { audio: { kind: "audio", ext: "mp3" } } }
   });
-  const convId = `s${anchor}_conv`;
-  nodes.push({
-    id: convId,
-    type: "audio_voice_convert",
-    inputs: { audio: `$ref:s${anchor}_voextract.audio`, voice_ref: `$ref:${voiceNode}.voice_id` },
-    params: { model: FIXED_VOICE_CONVERT_MODEL, voice: "{{voice_ref}}" }
-  });
-  out.voTracks.push({
-    slot: convId,
-    ref: `$ref:${convId}.audio`,
+  const convId = `${voiceNode}_conv`;
+  out.nativeSegments.push({
+    voiceNode,
+    ref: `$ref:s${anchor}_voextract.audio`,
     start_s: phrase.start_s,
-    end_s: phrase.end_s,
-    kind: "vo"
+    end_s: phrase.start_s + extractLen
   });
   out.voSegments.push({
     slot: convId,
@@ -17019,18 +17693,35 @@ function emitPhraseClip(phrase, voiceNode, env, nodes, out) {
     est_speech_s: Math.round(estSpeechWindowS(phrase.text, phrase.start_s, phrase.end_s) * 100) / 100,
     speech_words: wordCount(phrase.text)
   });
-  for (const s of phrase.shownScenes) {
-    const sc = env.blueprint.scenes[s];
-    if (!sc) continue;
-    const rawOffset = (sc.start_s ?? clipStart) - clipStart;
-    out.sceneSlice.set(s, {
+  registerMergedPhraseSlices(phrase, clipRef, clipStart, genDur, Boolean(chained), env, out);
+}
+function registerMergedPhraseSlices(phrase, clipRef, clipStart, genDur, chained, env, out) {
+  const shown = [...phrase.shownScenes].sort((a, b) => a - b);
+  let r = 0;
+  let firstRegistered = true;
+  while (r < shown.length) {
+    const first = shown[r];
+    let last = first;
+    while (r + 1 < shown.length && shown[r + 1] === last + 1) last = shown[++r];
+    r++;
+    const firstSc = env.blueprint.scenes[first];
+    if (!firstSc) continue;
+    const firstStart = firstSc.start_s ?? clipStart;
+    const rawOffset = firstStart - clipStart;
+    const runEnd = env.blueprint.scenes[last]?.end_s ?? firstStart + sceneDurationS(firstSc);
+    out.sceneSlice.set(first, {
       clipRef,
-      // Snap a sub-frame offset (line-start vs scene-start drift) to 0 so a single-scene
-      // phrase hits the whole-clip fast path instead of a needless re-encode + tiny shift.
+      // Snap a sub-frame offset (line-start vs scene-start drift) to 0 so a run that tiles
+      // the clip hits the whole-clip fast path instead of a needless re-encode + tiny shift.
       offset: rawOffset < 0.05 ? 0 : rawOffset,
-      len: sceneDurationS(sc),
-      clipDur: genDur
+      len: Math.max(0.5, runEnd - firstStart),
+      clipDur: genDur,
+      ...firstRegistered && chained ? { continuesFrame: true } : {}
     });
+    firstRegistered = false;
+    for (let s = first + 1; s <= last; s++) {
+      out.sceneSlice.set(s, { clipRef, offset: 0, len: 0, clipDur: genDur, skip: true });
+    }
   }
 }
 function emitPhraseTts(phrase, voiceNode, idx, used, nodes, out, languageCode) {
@@ -17173,7 +17864,7 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
     return void 0;
   }
   if (!env.reuse && sceneIsFullScreenUi(scene, present)) {
-    emitScreenScene(i, scene, lengths, lengths.out, env.outAr, nodes, out.clips);
+    emitScreenScene(i, scene, lengths, lengths.out, env.outAr, env.surfaceIngests, nodes, out.clips);
     return void 0;
   }
   const isCta = scene.narrative_role?.trim() === "cta" || isLast;
@@ -17185,7 +17876,8 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
     emitFlashHold(i, scene, env.slots, ctx, lengths, lengths.out, env.outAr, nodes, out.clips);
     return void 0;
   }
-  const first = scene.continues_previous && prevEndFrame ? prevEndFrame : buildFrameRef(
+  const sharesPrevFrame = Boolean(scene.continues_previous && prevEndFrame);
+  const first = sharesPrevFrame && prevEndFrame ? prevEndFrame : buildFrameRef(
     "start",
     scene.start_frame_asset?.url,
     scene.start_frame_prompt,
@@ -17233,9 +17925,26 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
       out.nativeSegments
     );
   }
-  out.clips.push(clip);
+  out.clips.push(sharesPrevFrame ? { ...clip, continuesFrame: true } : clip);
   return last;
 }
+function emitPresenterSliceClip(i, slice, env, nodes, out) {
+  if (slice.skip) return;
+  const cont = slice.continuesFrame ? { continuesFrame: true } : {};
+  const normDims = env.genAr !== env.outAr ? canvasDims(env.outAr) : void 0;
+  const whole = slice.offset === 0 && Math.abs(slice.len - slice.clipDur) <= 0.05 && !normDims;
+  if (whole) {
+    out.clips.push({ ref: slice.clipRef, scene_s: slice.len, out: null, ...cont });
+    return;
+  }
+  nodes.push({
+    id: `s${i}_seg`,
+    type: "ffmpeg",
+    inputs: { clip: slice.clipRef },
+    params: { args: trimArgs(slice.len, slice.offset, normDims), outputs: { video: { kind: "video", ext: "mp4" } } }
+  });
+  out.clips.push({ ref: `$ref:s${i}_seg.video`, scene_s: slice.len, out: null, ...cont });
+}
 function buildTimeline(blueprint, slots, opts, nodes) {
   const reuse = opts.frames === "reuse";
   const uiRouted = uiRoutedSceneSet(blueprint);
@@ -17308,22 +18017,7 @@ function buildTimeline(blueprint, slots, opts, nodes) {
     }
     const slice = out.sceneSlice.get(i);
     if (slice) {
-      const normDims = env.genAr !== env.outAr ? canvasDims(env.outAr) : void 0;
-      const whole = slice.offset === 0 && Math.abs(slice.len - slice.clipDur) <= 0.05 && !normDims;
-      if (whole) {
-        out.clips.push({ ref: slice.clipRef, scene_s: slice.len, out: null });
-      } else {
-        nodes.push({
-          id: `s${i}_seg`,
-          type: "ffmpeg",
-          inputs: { clip: slice.clipRef },
-          params: {
-            args: trimArgs(slice.len, slice.offset, normDims),
-            outputs: { video: { kind: "video", ext: "mp4" } }
-          }
-        });
-        out.clips.push({ ref: `$ref:s${i}_seg.video`, scene_s: slice.len, out: null });
-      }
+      emitPresenterSliceClip(i, slice, env, nodes, out);
       prevEndFrame = void 0;
       return;
     }
@@ -17609,25 +18303,40 @@ function lastSceneEnd(blueprint) {
   for (const s of blueprint.scenes) end = Math.max(end, s.end_s ?? 0);
   return end > 0 ? end : 8;
 }
-function concatArgs(count) {
+function seamDropOps(clips, i, seam) {
+  if (seam === "off") return null;
+  if (seam === "head" && i > 0 && clips[i]?.continuesFrame) return "trim=start_frame=1,setpts=PTS-STARTPTS";
+  if (seam === "tail" && clips[i + 1]?.continuesFrame) return "reverse,trim=start_frame=1,setpts=PTS-STARTPTS,reverse";
+  return null;
+}
+function concatArgs(clips, seam) {
   const inputs = [];
-  let labels = "";
-  for (let i = 0; i < count; i++) {
+  const pre = [];
+  const labels = [];
+  clips.forEach((_, i) => {
     inputs.push("-i", `{{in.c${i}}}`);
-    labels += `[${i}:v]`;
-  }
-  return [...inputs, "-filter_complex", `${labels}concat=n=${count}:v=1:a=0[v]`, "-map", "[v]", "{{out.video}}"];
+    const ops = seamDropOps(clips, i, seam);
+    if (ops) {
+      pre.push(`[${i}:v]${ops}[c${i}]`);
+      labels.push(`[c${i}]`);
+    } else {
+      labels.push(`[${i}:v]`);
+    }
+  });
+  const graph = [...pre, `${labels.join("")}concat=n=${clips.length}:v=1:a=0[v]`].join(";");
+  return [...inputs, "-filter_complex", graph, "-map", "[v]", "{{out.video}}"];
 }
 function clipInputLen(c) {
   return c.scene_s + (c.out?.dur ?? 0);
 }
-function xfadeSpineArgs(clips) {
+function xfadeSpineArgs(clips, seam) {
   const n = clips.length;
   const inputs = [];
   const filt = [];
   for (let i = 0; i < n; i++) {
     inputs.push("-i", `{{in.c${i}}}`);
-    filt.push(`[${i}:v]format=yuv420p,fps=30,setsar=1,settb=AVTB[c${i}]`);
+    const ops = seamDropOps(clips, i, seam);
+    filt.push(`[${i}:v]format=yuv420p,fps=30,setsar=1,settb=AVTB${ops ? `,${ops}` : ""}[c${i}]`);
   }
   let cur = "c0";
   let accLen = clipInputLen(clips[0]);
@@ -17649,13 +18358,13 @@ function xfadeSpineArgs(clips) {
   }
   return [...inputs, "-filter_complex", filt.join(";"), "-map", "[v]", "{{out.video}}"];
 }
-function buildSpine(clips, nodes) {
+function buildSpine(clips, seam, nodes) {
   const inputs = {};
   clips.forEach((c, i) => {
     inputs[`c${i}`] = c.ref;
   });
   const hasTransition = clips.length > 1 && clips.some((c) => c.out);
-  const args = hasTransition ? xfadeSpineArgs(clips) : concatArgs(clips.length);
+  const args = hasTransition ? xfadeSpineArgs(clips, seam) : concatArgs(clips, seam);
   nodes.push({
     id: "spine",
     type: "ffmpeg",
@@ -17664,16 +18373,24 @@ function buildSpine(clips, nodes) {
   });
   return "$ref:spine.video";
 }
-function scaffoldVideoCanvas(input, elementsInput, opts) {
-  const blueprint = VideoBlueprint.parse(input);
-  injectHookPhysicality(blueprint);
-  const elements = RecurringElements.parse(elementsInput);
-  const nodes = [];
+function emitBlueprintIngests(opts, nodes) {
   nodes.push({
     id: "prompt",
     type: "ingest",
     params: { source: "path", path: opts.blueprintPath ?? "./prompt.json", expect: "json" }
   });
+  nodes.push({
+    id: "prompt_style",
+    type: "ingest",
+    params: { source: "path", path: opts.blueprintStylePath ?? "./prompt.style.json", expect: "json" }
+  });
+}
+function scaffoldVideoCanvas(input, elementsInput, opts) {
+  const blueprint = VideoBlueprint.parse(input);
+  injectHookPhysicality(blueprint);
+  const elements = RecurringElements.parse(elementsInput);
+  const nodes = [];
+  emitBlueprintIngests(opts, nodes);
   const slots = buildElementSlots(elements);
   extendPresenceByPromptMentions(slots, blueprint);
   slots.forEach((slot, i) => {
@@ -17685,7 +18402,7 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
   });
   buildElementSheets(slots, nodes);
   const { clips, voTracks, vo_segments, talking_scenes } = buildTimeline(blueprint, slots, opts, nodes);
-  let videoRef = buildSpine(clips, nodes);
+  let videoRef = buildSpine(clips, opts.seamDedup ?? "head", nodes);
   let videoNode = "spine";
   const overlays = blueprint.scenes.flatMap((s) => s.overlays ?? []);
   const floating = blueprint.scenes.flatMap((s) => s.floating_elements ?? []);
@@ -17927,7 +18644,7 @@ function buildMotionBoard(blueprint) {
   });
 }
 var VIDEO_GUIDE = [
-  "Scaffolded by `baker canvas scaffold-video` \u2014 a runnable reproduction of your reference video, built like an editing timeline. The VOICE is cut at PAUSES, not at visual cuts: each continuous-speech PHRASE is ONE Seedance clip (native lip-sync + audio) re-voiced to one brand voice, so a sentence never breaks mid-word across a cut. Each scene's PICTURE is independent: a scene that SHOWS the speaker slices its window out of the phrase clip; a b-roll cutaway gets its own silent clip (or a still hold for a sub-2s flash) laid over the continuing voice; a pure-voiceover stretch is one ElevenLabs tts read. Every clip gets a CLEAN-PLATE start AND end keyframe (no baked text), RECAST to your dropped reference assets \u2014 Seedance interpolates real in-shot motion between them. Each frame grounds ONLY on its own extracted frame + el_* slots (never another generated frame), so all frames render in PARALLEL (no cross-frame cascade). A SPLIT-SCREEN / PICTURE-IN-PICTURE / KEYED-PRESENTER scene is reproduced as one clip PER REGION, stacked or overlaid (see `metadata.todo.composition`). On-screen text/graphics are a separate HTML overlay layer you paint; audio is the voice + SFX + a ducked music bed, normalized stereo. It is a STARTING POINT, not a locked render: add, delete, reorder, split, merge, or re-time scenes freely (a b-roll cutaway INSIDE a phrase lands at an approximate beat \u2014 nudge it) \u2014 see `metadata.todo.full_flexibility`.",
+  "Scaffolded by `baker canvas scaffold-video` \u2014 a runnable reproduction of your reference video, built like an editing timeline. It is a sequence of clear SHOTS separated at COMPLETE BREAKS (hard cuts): two adjacent presenter shots at a cut are TWO clips, never glued into one take. What stays continuous is the VOICE \u2014 a voiceover narration is ONE read across the b-roll it plays over, and a b-roll CUTAWAY between two on-camera moments leaves the presenter shot continuous with the insert sliced in \u2014 and each person keeps ONE brand voice (all their clips' native audio re-voiced in a single per-speaker pass), so timbre holds across the cuts. A presenter shot is ONE Seedance clip (native lip-sync + audio); a pure-voiceover stretch is one ElevenLabs tts read; a sub-2s flash is a still hold. A single shot too long for one clip splits into takes that share a boundary frame \u2014 the spine drops the duplicated frame (`--seam-dedup head|tail|off`). Every clip gets a CLEAN-PLATE start AND end keyframe (no baked text), RECAST to your dropped reference assets \u2014 Seedance interpolates real in-shot motion between them. Each frame grounds ONLY on its own extracted frame + el_* slots (never another generated frame), so all frames render in PARALLEL (no cross-frame cascade). A SPLIT-SCREEN / PICTURE-IN-PICTURE / KEYED-PRESENTER scene is reproduced as one clip PER REGION, stacked or overlaid (see `metadata.todo.composition`). On-screen text/graphics are a separate HTML overlay layer you paint; audio is the voice + SFX + a ducked music bed, normalized stereo. It is a STARTING POINT, not a locked render: add, delete, reorder, split, merge, or re-time scenes freely \u2014 see `metadata.todo.full_flexibility`.",
   "",
   "WHAT TO DO NEXT:",
   "0. RE-CRAFT THE SCRIPT FIRST (don't clone). This reference already won in-market, but copying a video is much harder than a static: the hook is targeting and may not transfer, and the message must become TRUE for our brand. Work the `metadata.todo.script_recraft` checklist \u2014 for each scene judge its role (hook/body/CTA), decide keep/cut/reorder/replace, and re-author every line for OUR customer's pain + OUR offer. See `references/script-craft.md` (hook/body/CTA framework) and the `meta-ads-playbook` skill. Most of the work lives here.",
@@ -18011,9 +18728,9 @@ function buildVideoTodo(report, overlayCount, floatingCount, opts, blueprint) {
       voice_description: d.voice_description,
       line: d.line
     })),
-    talking_head_note: "PHRASE-NATIVE: a continuous-speech phrase where the speaker is shown is ONE Seedance clip (the full phrase quoted in s<anchor>_clip's prompt + generate_audio) so lips+voice are generated together \u2014 no tts, no veed-lipsync. Scenes that show the speaker slice their window out of that clip (s<i>_seg); edit the phrase line in the s<anchor>_clip prompt to re-author it. A pure-voiceover phrase (speaker never shown) is one ElevenLabs tts read instead.",
-    voice_note: "ONE voice per person: a single voice_select is reused across all that person's phrases (on-camera AND off \u2014 the deconstruct's `voiceover` label folds into the sole presenter). Each presenter phrase's native audio is re-voiced to that brand voice via audio_voice_convert (eleven_multilingual_sts_v2, one convert per phrase, timing preserved so lips stay matched). Set voice_select.voice_id's gender/language to match the creator.",
-    native_timing: "The voice is cut at PAUSES, not at visual cuts, so a sentence spanning a cut stays one continuous read (no mid-word break). The clip is generated long enough for the estimated speech; if a line runs longer than its phrase window the voice continues a beat into the following pause (natural VO continuity). `metadata.video.talking_scenes` carries each phrase's scene_s vs est_speech_s. CAVEAT: a b-roll cutaway INSIDE a phrase lands at an approximate (proportional) time \u2014 Seedance exposes no word timing \u2014 so if a cutaway is off its beat, nudge the scene boundary (it's a starting point).",
+    talking_head_note: "SHOT-NATIVE: a presenter shot is ONE Seedance clip (its line quoted in s<anchor>_clip's prompt + generate_audio) so lips+voice are generated together \u2014 no tts, no veed-lipsync. Two adjacent presenter shots at a hard cut are SEPARATE clips; a cutaway phrase (the presenter on camera, cut to b-roll, back on camera) stays one clip and slices its on-camera windows (s<i>_seg). Edit the line in the s<anchor>_clip prompt to re-author it. A pure-voiceover phrase (speaker never shown) is one ElevenLabs tts read instead.",
+    voice_note: "ONE voice per person: a single voice_select is reused across all that person's shots (on-camera AND off \u2014 the deconstruct's `voiceover` label folds into the sole presenter). Every presenter clip's native audio is extracted and re-voiced to that brand voice through a SINGLE merged audio_voice_convert per speaker (<voice>_conv, eleven_multilingual_sts_v2, timing preserved so lips stay matched) \u2014 so timbre stays consistent across the separate shot clips. Set voice_select.voice_id's gender/language to match the creator.",
+    native_timing: "Clips separate at COMPLETE BREAKS between shots, but the VOICE stays continuous where it should: a voiceover narration is ONE read across the b-roll it plays over, and a cutaway leaves the presenter's read continuous under the insert. Each clip is generated long enough for its estimated speech. `metadata.video.talking_scenes` carries each shot's scene_s vs est_speech_s. CAVEAT: a b-roll cutaway INSIDE a phrase lands at an approximate (proportional) time \u2014 Seedance exposes no word timing \u2014 so if a cutaway is off its beat, nudge the scene boundary (it's a starting point).",
     craft: {
       note: "Production-craft principles that raise every clip's realism. Full rationale: references/video-craft.md (production craft); references/script-craft.md + meta-ads-playbook for the hook/message layer.",
       principles: [
@@ -18124,23 +18841,23 @@ function videoReport(input, elementsInput) {
 
 // src/commands/canvas/composition-path.ts
 import { existsSync as existsSync3 } from "fs";
-import path7 from "path";
+import path10 from "path";
 function resolveShippedCanvasDir(name, startDir, exists = existsSync3, maxDepth = 8) {
-  const rel = path7.join("canvas", name);
+  const rel = path10.join("canvas", name);
   let dir = startDir;
   for (let i = 0; i < maxDepth; i++) {
-    const candidate = path7.join(dir, rel);
-    if (exists(path7.join(candidate, "meta.json"))) return candidate;
-    const parent = path7.dirname(dir);
+    const candidate = path10.join(dir, rel);
+    if (exists(path10.join(candidate, "meta.json"))) return candidate;
+    const parent = path10.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return path7.resolve(startDir, "../../../", rel);
+  return path10.resolve(startDir, "../../../", rel);
 }
 
 // src/commands/canvas/gitignore.ts
-import { appendFile, readFile as readFile5 } from "fs/promises";
-import path8 from "path";
+import { appendFile, readFile as readFile6 } from "fs/promises";
+import path11 from "path";
 function missingGitignoreEntries(existing, entries) {
   const present = new Set(
     existing.split("\n").map((l) => l.trim().replace(/\/+$/, "")).filter((l) => l.length > 0 && !l.startsWith("#"))
@@ -18148,10 +18865,10 @@ function missingGitignoreEntries(existing, entries) {
   return entries.filter((e) => !present.has(e.trim().replace(/\/+$/, "")));
 }
 async function ensureGitignore(dir, entries) {
-  const file = path8.join(dir, ".gitignore");
+  const file = path11.join(dir, ".gitignore");
   let existing;
   try {
-    existing = await readFile5(file, "utf8");
+    existing = await readFile6(file, "utf8");
   } catch {
     return;
   }
@@ -18190,7 +18907,7 @@ ONE PERSON, MULTIPLE LOOKS: if a single individual plays MULTIPLE personas or wa
 For each kept element return: { "type": one of person|animal|product|logo|badge|location, "label": a short UPPER_SNAKE_CASE name (e.g. HERO, CREATOR_SKEPTIC, INSURANCE_CARD, LOGO), "description": a concrete reusable description to source/shoot the real asset \u2014 for a person/animal give a NEUTRAL castable role (e.g. "hero pet-owner, woman in her 30s" or "a small beagle"), NOT the original individual's literal face/identity: we RECAST with a FRESH person/animal, so never tell the agent to reuse the original. "expression": a living subject's typical expression or null, "cast_id": the global.cast id if it maps to one else null, "same_as": the label of another element this is the SAME individual as (different wardrobe/persona) else null, "scenes": the 0-based indices of ONLY the scenes where the element is ACTUALLY VISIBLE ON SCREEN \u2014 judged from that scene's start_frame_prompt / end_frame_prompt subjects and its action_detail, NOT from who is merely speaking. A narrator heard over b-roll is NOT present in that b-roll scene; a dog-running cutaway does NOT contain the couch creator just because she talks across it. Do NOT pad the list \u2014 an element wrongly listed in a scene makes the reproduction render the wrong subject there (e.g. the creator appearing in a pure-dog b-roll). When in doubt, leave a scene OUT. Output ONLY the JSON object.`;
 async function loadAssetText2(ref, label) {
   const r = ref;
-  if (typeof r?.path === "string") return readFile6(r.path, "utf8");
+  if (typeof r?.path === "string") return readFile7(r.path, "utf8");
   if (typeof r?.url === "string") {
     const res = await fetch(r.url);
     if (!res.ok) throw new Error(`failed to fetch ${label} (${res.status})`);
@@ -18209,7 +18926,7 @@ async function loadTranscriptBestEffort(ref) {
 async function stageCaptions(outDir, transcript) {
   const text = transcript?.trim();
   if (!text || text === "[]") return {};
-  const compositionPath = path9.join(outDir, "tiktok-captions-composition");
+  const compositionPath = path12.join(outDir, "tiktok-captions-composition");
   await cp(SHIPPED_CAPTIONS_DIR, compositionPath, { recursive: true });
   return { compositionPath };
 }
@@ -18227,12 +18944,12 @@ function patchCompositionHtml(html, dims) {
   return html.replace(/(<meta\s+name="viewport"\s+content="width=)\d+(,\s*height=)\d+(")/i, `$1${dims.w}$2${dims.h}$3`).replace(/(width:\s*)\d+(px;\s*height:\s*)\d+(px;)/i, `$1${dims.w}$2${dims.h}$3`).replace(/(data-width=")\d+(")/i, `$1${dims.w}$2`).replace(/(data-height=")\d+(")/i, `$1${dims.h}$2`);
 }
 async function stampCompositionDims(compositionDir, dims) {
-  const metaPath = path9.join(compositionDir, "meta.json");
-  const rawMeta = await readFile6(metaPath, "utf8");
-  await writeFile2(metaPath, patchCompositionMeta(rawMeta, dims), "utf8");
-  const htmlPath = path9.join(compositionDir, "index.html");
-  const rawHtml = await readFile6(htmlPath, "utf8");
-  await writeFile2(htmlPath, patchCompositionHtml(rawHtml, dims), "utf8");
+  const metaPath = path12.join(compositionDir, "meta.json");
+  const rawMeta = await readFile7(metaPath, "utf8");
+  await writeFile3(metaPath, patchCompositionMeta(rawMeta, dims), "utf8");
+  const htmlPath = path12.join(compositionDir, "index.html");
+  const rawHtml = await readFile7(htmlPath, "utf8");
+  await writeFile3(htmlPath, patchCompositionHtml(rawHtml, dims), "utf8");
 }
 function parseElements2(raw) {
   const parsed = JSON.parse(raw);
@@ -18272,6 +18989,62 @@ function fail2(code, message) {
 `);
   process.exit(2);
 }
+var VIDEO_EXT_BY_MIME = {
+  "video/mp4": ".mp4",
+  "video/quicktime": ".mov",
+  "video/webm": ".webm",
+  "video/x-matroska": ".mkv"
+};
+function referenceVideoExt(url, contentType) {
+  const fromPath = path12.extname(new URL(url).pathname).toLowerCase();
+  if (fromPath && fromPath.length <= 5) return fromPath;
+  const mime = (contentType ?? "").split(";")[0]?.trim().toLowerCase();
+  return mime && VIDEO_EXT_BY_MIME[mime] || ".mp4";
+}
+async function fileExists2(target) {
+  return access2(target).then(
+    () => true,
+    () => false
+  );
+}
+function videoSourceReference(blueprint, fileArg2) {
+  const bp = blueprint ?? {};
+  const durable = typeof bp.source?.url === "string" ? bp.source.url : void 0;
+  const original = /^https?:\/\//i.test(fileArg2) ? fileArg2 : void 0;
+  const brand = bp.global?.branding?.brand_name;
+  return { url: durable ?? original, advertiser: typeof brand === "string" && brand.trim() ? brand.trim() : void 0 };
+}
+function videoDefinitionDescription(blueprint) {
+  const g = (blueprint ?? {}).global ?? {};
+  const notes = g.reproduction_notes;
+  if (typeof notes === "string" && notes.trim()) return notes.trim();
+  const product = g.branding?.product;
+  return typeof product === "string" && product.trim() ? product.trim() : void 0;
+}
+async function materializeReferenceVideo(fileArg2) {
+  if (!/^https?:\/\//i.test(fileArg2)) return path12.resolve(fileArg2);
+  let res;
+  try {
+    res = await fetch(fileArg2);
+  } catch (e) {
+    throw new Error(`failed to download reference video: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!res.ok) throw new Error(`failed to download reference video (${res.status} ${res.statusText})`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (bytes.length === 0) throw new Error("reference video download was empty");
+  const dest = path12.join(
+    tmpdir2(),
+    `baker-ref-${sha256Hex(bytes).slice(0, 16)}${referenceVideoExt(fileArg2, res.headers.get("content-type"))}`
+  );
+  await writeFile3(dest, bytes);
+  return dest;
+}
+function resolveSeamDedup(raw) {
+  if (raw === void 0) return "head";
+  const v = String(raw);
+  if (v === "head" || v === "tail" || v === "off") return v;
+  throw new Error(`--seam-dedup must be "head", "tail", or "off" (got "${v}")`);
+}
 function resolveModels2(args) {
   const pick = (flag, kind, fallback) => args[flag] ? String(args[flag]) : resolveModel2(kind, fallback);
   return {
@@ -18368,13 +19141,25 @@ var scaffoldVideoCommand = defineCommand90({
     description: "Turn a reference video into a runnable reproduction canvas in one command. Runs billed passes \u2014 video_deconstruct (the full scene-by-scene blueprint + transcript, baked to prompt.json as the editable 'prompt') and an AI selection of the video's RECURRING identity elements (person/animal/product/logo) \u2014 then scaffolds a pipeline where every scene boundary is a static-ad-grade frame (the blueprint as target_blueprint, a reference legend, the real frame as anchor) and each recurring element gets ONE shared [TODO] ingest slot wired into every frame it appears in. The clips feed Seedance an ultra-detailed motion brief (action, camera, dialogue, transcript). Edit prompt.json, drop the real source images, then `baker canvas run`."
   },
   args: {
-    file: { type: "positional", required: true, description: "Path to the reference video" },
+    file: {
+      type: "positional",
+      required: true,
+      description: "Reference video \u2014 a local path OR an http(s) URL (e.g. a winning-ads link). A URL is downloaded for you; pass --slug or --out with it."
+    },
     out: { type: "string", description: "Output canvas path (default <video-dir>/<name>.video.canvas.json)" },
+    slug: {
+      type: "string",
+      description: "Creative slug \u2014 writes the canvas to src/creatives/<slug>/<slug>.canvas.json (repo convention)"
+    },
     frames: { type: "string", description: '"generate" (default, anchored regen) or "reuse" (wire real frames in)' },
     ambient: {
       type: "boolean",
       description: "Give silent b-roll scenes native diegetic ambient mixed deep under the music bed (off by default)"
     },
+    "seam-dedup": {
+      type: "string",
+      description: `How to dedup the frame two clips SHARE when a long shot is split for length: "head" (default, drop the second clip's first frame), "tail" (drop the first clip's last frame), or "off" (keep both).`
+    },
     "max-scenes": { type: "string", description: "Cap the number of scenes the deconstruct emits" },
     "shot-threshold": {
       type: "string",
@@ -18382,6 +19167,14 @@ var scaffoldVideoCommand = defineCommand90({
     },
     language: { type: "string", description: "Transcript/dialogue language hint (e.g. fr, en)" },
     focus: { type: "string", description: "Known provenance/emphasis to ground the deconstruct" },
+    advertiser: {
+      type: "string",
+      description: "Source advertiser recorded in _definition.md (default: the brand the deconstruct identified)"
+    },
+    platform: {
+      type: "string",
+      description: "Ad platform for _definition.md (meta|google|linkedin|tiktok|youtube|x|other; default meta)"
+    },
     "deconstruct-model": { type: "string", description: "Override the video_deconstruct model id" },
     "select-model": { type: "string", description: "Override the text_generate model id for element selection" },
     "image-model": { type: "string", description: "Override the image_generate model id for frames" },
@@ -18396,11 +19189,33 @@ var scaffoldVideoCommand = defineCommand90({
     }
   },
   async run({ args }) {
-    const videoPath = path9.resolve(String(args.file));
-    const base = path9.basename(videoPath, path9.extname(videoPath));
-    const outPath = args.out ? path9.resolve(String(args.out)) : path9.join(path9.dirname(videoPath), `${base}.video.canvas.json`);
-    const outDir = path9.dirname(outPath);
-    const blueprintPath = path9.join(outDir, "prompt.json");
+    const fileArg2 = String(args.file);
+    const slug = args.slug ? String(args.slug) : void 0;
+    if (slug && !isValidScaffoldSlug(slug)) {
+      process.stderr.write(
+        `${JSON.stringify({ ok: false, error: { code: "invalid_slug", message: "--slug must be lowercase kebab (a-z, 0-9, hyphens), max 100 chars" } }, null, 2)}
+`
+      );
+      process.exit(2);
+    }
+    const isUrl = /^https?:\/\//i.test(fileArg2);
+    if (isUrl && !slug && !args.out) {
+      return fail2(
+        "missing_output_target",
+        "When the reference is a URL, pass --slug (writes src/creatives/<slug>/) or --out <path> so the scaffolded canvas has a home in the repo."
+      );
+    }
+    let videoPath;
+    try {
+      videoPath = await materializeReferenceVideo(fileArg2);
+    } catch (e) {
+      return fail2("download", e instanceof Error ? e.message : String(e));
+    }
+    const base = path12.basename(videoPath, path12.extname(videoPath));
+    const outPath = args.out ? path12.resolve(String(args.out)) : slug ? path12.join(process.cwd(), "src", "creatives", slug, `${slug}.canvas.json`) : path12.join(path12.dirname(videoPath), `${base}.video.canvas.json`);
+    const outDir = path12.dirname(outPath);
+    const blueprintPath = path12.join(outDir, "prompt.json");
+    const blueprintStylePath = path12.join(outDir, "prompt.style.json");
     const frames = args.frames === "reuse" ? "reuse" : "generate";
     const maxScenes = args["max-scenes"] ? Number(args["max-scenes"]) : void 0;
     if (Number.isFinite(maxScenes)) {
@@ -18419,10 +19234,16 @@ var scaffoldVideoCommand = defineCommand90({
       shotCuts
     });
     const { blueprint, elements, transcript, creditsSpent } = await runAnalysisPasses(deconstructCanvas, selectModel);
-    await mkdir(outDir, { recursive: true });
+    await mkdir3(outDir, { recursive: true });
     const annotated = annotateBlueprintWithElements(blueprint, elements);
-    await writeFile2(blueprintPath, `${JSON.stringify(annotated, null, 2)}
+    await writeFile3(blueprintPath, `${JSON.stringify(annotated, null, 2)}
 `, "utf8");
+    await writeFile3(
+      blueprintStylePath,
+      `${JSON.stringify(slimBlueprintForFrameStyle(annotated), null, 2)}
+`,
+      "utf8"
+    );
     let aspect;
     try {
       aspect = resolveAspect(
@@ -18440,12 +19261,12 @@ var scaffoldVideoCommand = defineCommand90({
 `
       );
     }
-    const compositionDest = path9.join(outDir, "video-overlay-composition");
+    const compositionDest = path12.join(outDir, "video-overlay-composition");
     await cp(SHIPPED_COMPOSITION_DIR, compositionDest, { recursive: true });
     await stampCompositionDims(compositionDest, outDims);
-    const indexPath = path9.join(compositionDest, "index.html");
+    const indexPath = path12.join(compositionDest, "index.html");
     const overlayHtml = buildOverlayHtml(blueprint, { captionsActive: Boolean(transcript) });
-    const indexHtml = await readFile6(indexPath, "utf8");
+    const indexHtml = await readFile7(indexPath, "utf8");
     const injected = indexHtml.replace("<!--OVERLAYS-->", () => overlayHtml);
     if (injected === indexHtml && overlayHtml.trim()) {
       fail2(
@@ -18453,17 +19274,19 @@ var scaffoldVideoCommand = defineCommand90({
         `video-overlay-composition/index.html is missing the <!--OVERLAYS--> marker \u2014 cannot inject the overlay layer`
       );
     }
-    await writeFile2(indexPath, injected, "utf8");
+    await writeFile3(indexPath, injected, "utf8");
     const captions = await stageCaptions(outDir, transcript);
     if (captions.compositionPath) await stampCompositionDims(captions.compositionPath, outDims);
     const opts = {
       imageModel,
       videoModel,
-      overlayCompositionPath: path9.relative(outDir, compositionDest),
-      captionsCompositionPath: captions.compositionPath ? path9.relative(outDir, captions.compositionPath) : void 0,
-      blueprintPath: path9.relative(outDir, blueprintPath),
+      overlayCompositionPath: path12.relative(outDir, compositionDest),
+      captionsCompositionPath: captions.compositionPath ? path12.relative(outDir, captions.compositionPath) : void 0,
+      blueprintPath: path12.relative(outDir, blueprintPath),
+      blueprintStylePath: path12.relative(outDir, blueprintStylePath),
       frames,
       ambient: Boolean(args.ambient),
+      seamDedup: resolveSeamDedup(args["seam-dedup"]),
       ...args.aspect ? { aspect: String(args.aspect) } : {},
       ...args.resolution ? { resolution: String(args.resolution) } : {}
     };
@@ -18482,7 +19305,7 @@ var scaffoldVideoCommand = defineCommand90({
       todo.blocking_validation_issues = validation.issues;
       meta.todo = todo;
     }
-    await writeFile2(outPath, `${JSON.stringify(canvas, null, 2)}
+    await writeFile3(outPath, `${JSON.stringify(canvas, null, 2)}
 `, "utf8");
     if (!validation.ok) {
       process.stderr.write(
@@ -18502,12 +19325,42 @@ var scaffoldVideoCommand = defineCommand90({
       process.exit(2);
     }
     await ensureGitignore(process.cwd(), ["canvas/", ".context/"]);
+    const sourceRef = videoSourceReference(blueprint, fileArg2);
+    if (slug) {
+      const definitionPath = path12.join(outDir, "_definition.md");
+      if (!await fileExists2(definitionPath)) {
+        await writeFile3(
+          definitionPath,
+          buildCreativeDefinition({
+            title: titleFromSlug(slug),
+            kind: "video",
+            platform: resolvePlatform(args.platform ? String(args.platform) : void 0),
+            formats: resolveFormats(aspect.outAr),
+            sourceReferenceUrl: sourceRef.url,
+            sourceAdvertiser: args.advertiser ? String(args.advertiser) : sourceRef.advertiser,
+            sourceKind: "video",
+            description: videoDefinitionDescription(blueprint)
+          }),
+          "utf8"
+        );
+      }
+    }
+    if (slug) {
+      await syncCreativeDefinitionBestEffort({
+        slug,
+        title: titleFromSlug(slug),
+        formats: [aspect.outAr],
+        canvas,
+        sourceReferenceUrl: sourceRef.url
+      });
+    }
     process.stdout.write(
       `${JSON.stringify(
         {
           ok: true,
           canvas_path: outPath,
           prompt_path: blueprintPath,
+          source_reference: sourceRef.url,
           composition_dir: compositionDest,
           output: canvas.output,
           frames_mode: frames,
@@ -18519,7 +19372,7 @@ var scaffoldVideoCommand = defineCommand90({
             run_estimated_credits: validation.estimatedCredits
           },
           checklist: {
-            edit_prompt: `Edit ${path9.basename(blueprintPath)} \u2014 the blueprint deconstructed from your video; rewrite it into the ad you want (cast, palette, copy, claims). Every scene frame reads it via target_blueprint.`,
+            edit_prompt: `Edit ${path12.basename(blueprintPath)} \u2014 the blueprint deconstructed from your video; rewrite it into the ad you want (cast, palette, copy, claims). Every scene frame reads it via target_blueprint.`,
             recurring_elements_to_supply: report.elements,
             voices_to_confirm: report.dialogue.map((d) => ({
               scene: d.scene,
@@ -18533,6 +19386,13 @@ var scaffoldVideoCommand = defineCommand90({
             scenes_clamped_to_15s: report.clamped_scenes,
             oversize_scenes: report.oversize_scenes,
             overstuffed_scenes: report.overstuffed_scenes,
+            // A photoreal on-camera person/animal on Seedance can trip ByteDance's
+            // real-person-likeness filter (422 content_policy_blocked, NON-retryable — no
+            // prompt reframe clears it). Surface the escape BEFORE the billed run so a
+            // face-heavy ad isn't discovered broken mid-render.
+            ...report.elements.some((e) => e.type === "person" || e.type === "animal") && /seedance/i.test(videoModel) ? {
+              content_policy_risk: "This ad has a photoreal on-camera cast generating on Seedance. ByteDance's real-person-likeness filter can reject a photoreal AI face with a NON-retryable 422 (content_policy_blocked) \u2014 no prompt change clears it. If clips fail that way, regenerate on Veo (re-run with `--video-model google/veo-3.1-fast`) or make the frame less photoreal."
+            } : {},
             note: "Drop ONE real source image at each el_* [TODO] (reused across every frame that element appears in), confirm each voice_select casting, then `baker canvas validate` and `baker canvas run`. Running generates many billed image/video/audio assets \u2014 it is not free."
           }
         },
@@ -18545,8 +19405,8 @@ var scaffoldVideoCommand = defineCommand90({
 });
 
 // src/commands/canvas/set-prompt.ts
-import { readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
-import path10 from "path";
+import { readFile as readFile8, writeFile as writeFile4 } from "fs/promises";
+import path13 from "path";
 import { defineCommand as defineCommand91 } from "citty";
 function setNodePrompt(canvas, nodeId, text) {
   const nodes = canvas?.nodes;
@@ -18574,17 +19434,17 @@ var setPromptCommand = defineCommand91({
     "text-file": { type: "string", description: "Read the new prompt from a UTF-8 file (preserves accents/newlines)" }
   },
   async run({ args }) {
-    const filePath = path10.resolve(String(args.file));
+    const filePath = path13.resolve(String(args.file));
     let canvas;
     try {
-      canvas = JSON.parse(await readFile7(filePath, "utf8"));
+      canvas = JSON.parse(await readFile8(filePath, "utf8"));
     } catch (e) {
       process.stderr.write(`${JSON.stringify({ ok: false, error: { code: "parse", message: String(e) } }, null, 2)}
 `);
       process.exit(2);
     }
     let text;
-    if (args["text-file"]) text = await readFile7(path10.resolve(String(args["text-file"])), "utf8");
+    if (args["text-file"]) text = await readFile8(path13.resolve(String(args["text-file"])), "utf8");
     else if (args.text !== void 0) text = String(args.text);
     else {
       process.stderr.write(
@@ -18605,14 +19465,14 @@ var setPromptCommand = defineCommand91({
       process.exit(2);
       return;
     }
-    const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(updated, path10.dirname(filePath)), defaultRegistry());
+    const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(updated, path13.dirname(filePath)), defaultRegistry());
     if (!validation.ok) {
       process.stderr.write(`${JSON.stringify({ ok: false, error: { code: "validation", issues: validation.issues } }, null, 2)}
 `);
       process.exit(2);
       return;
     }
-    await writeFile3(filePath, `${JSON.stringify(updated, null, 2)}
+    await writeFile4(filePath, `${JSON.stringify(updated, null, 2)}
 `, "utf8");
     process.stdout.write(`${JSON.stringify({ ok: true, node: String(args.node), bytes: text.length }, null, 2)}
 `);
@@ -18620,8 +19480,8 @@ var setPromptCommand = defineCommand91({
 });
 
 // src/commands/canvas/validate.ts
-import { readFile as readFile8 } from "fs/promises";
-import path11 from "path";
+import { readFile as readFile9 } from "fs/promises";
+import path14 from "path";
 import { defineCommand as defineCommand92 } from "citty";
 var validateCommand = defineCommand92({
   meta: {
@@ -18630,8 +19490,8 @@ var validateCommand = defineCommand92({
   },
   args: { file: { type: "positional", required: true, description: "Path to canvas JSON" } },
   async run({ args }) {
-    const filePath = path11.resolve(String(args.file));
-    const raw = await readFile8(filePath, "utf8");
+    const filePath = path14.resolve(String(args.file));
+    const raw = await readFile9(filePath, "utf8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -18641,7 +19501,7 @@ var validateCommand = defineCommand92({
 `);
       process.exit(2);
     }
-    parsed = resolveRelativeCanvasPaths(parsed, path11.dirname(filePath));
+    parsed = resolveRelativeCanvasPaths(parsed, path14.dirname(filePath));
     const result = await validateCanvasDeep(parsed, defaultRegistry());
     if (!result.ok) {
       process.stderr.write(`${JSON.stringify({ ok: false, issues: result.issues }, null, 2)}
@@ -18700,7 +19560,7 @@ import { defineCommand as defineCommand95 } from "citty";
 import { defineCommand as defineCommand94 } from "citty";
 
 // src/commands/images/api.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { extname } from "path";
 var imageProcessingTimeoutMs = 18e4;
 var imageReadyPollIntervalMs = 2e3;
@@ -18714,7 +19574,7 @@ var mimeMap = {
   ".avif": "image/avif"
 };
 var defaultImageApiDeps = {
-  readFile: readFile9,
+  readFile: readFile10,
   post: apiPost,
   get: apiGet,
   sleep: (ms) => new Promise((resolve5) => setTimeout(resolve5, ms))
@@ -18778,6 +19638,16 @@ registerSchema({
       type: "string",
       description: "Optional URL of the original reference ad",
       required: false
+    },
+    slug: {
+      type: "string",
+      description: "Creative slug (src/creatives/<slug>/) \u2014 attaches the image to that creative's row",
+      required: false
+    },
+    runId: {
+      type: "string",
+      description: "Canvas run id (r_\u2026) of the approved generation to pin as published",
+      required: false
     }
   }
 });
@@ -18787,6 +19657,13 @@ function detectCreativeContentType(filePath) {
     unsupportedMessage: "Unsupported creative image extension. Use PNG, JPG, or WebP."
   });
 }
+function chatIdFromEnv() {
+  try {
+    return getEnv().BAKER_CHAT_ID || void 0;
+  } catch {
+    return void 0;
+  }
+}
 function parseOptionalUrl(value) {
   if (value === void 0 || value.trim() === "") {
     return void 0;
@@ -18817,7 +19694,11 @@ async function publishCreative(args, deps = defaultImageApiDeps) {
   return publishImageAsCreative(deps, {
     imageId: upload.imageId,
     title,
-    sourceReferenceUrl
+    sourceReferenceUrl,
+    slug: args.slug,
+    runId: args.runId,
+    // Attribute the publish to the driving chat (injected by the bridge).
+    chatId: chatIdFromEnv()
   });
 }
 var publishCommand = defineCommand94({
@@ -18833,6 +19714,16 @@ var publishCommand = defineCommand94({
       type: "string",
       description: "Optional URL of the original reference ad",
       required: false
+    },
+    slug: {
+      type: "string",
+      description: "Creative slug (src/creatives/<slug>/) \u2014 attaches the image to that creative's row",
+      required: false
+    },
+    runId: {
+      type: "string",
+      description: "Canvas run id (r_\u2026) of the approved generation to pin as published",
+      required: false
     }
   },
   run: async ({ args }) => {
@@ -18851,7 +19742,9 @@ var publishCommand = defineCommand94({
         file,
         title,
         context: args.context,
-        sourceReferenceUrl: args.sourceReferenceUrl
+        sourceReferenceUrl: args.sourceReferenceUrl,
+        slug: args.slug,
+        runId: args.runId
       });
       writeJson({ ok: true, data });
     } catch (err) {
@@ -19711,7 +20604,7 @@ function cropSprite(input, region) {
 
 // src/lib/image/io.ts
 import { randomBytes } from "crypto";
-import { glob as fsGlob, readFile as readFile10, rename, stat as stat2, writeFile as writeFile4 } from "fs/promises";
+import { glob as fsGlob, readFile as readFile11, rename, stat as stat2, writeFile as writeFile5 } from "fs/promises";
 import { dirname as dirname2, extname as extname2, join as join3, resolve as resolve4 } from "path";
 var REMOTE_RE = /^https?:\/\//i;
 var GLOB_RE = /[*?[\]{}]/;
@@ -19747,11 +20640,11 @@ async function readImageBuffer(pathOrUrl) {
     }
     return Buffer.from(await response.arrayBuffer());
   }
-  return readFile10(pathOrUrl);
+  return readFile11(pathOrUrl);
 }
-async function isDirectory(path12) {
+async function isDirectory(path15) {
   try {
-    const s = await stat2(path12);
+    const s = await stat2(path15);
     return s.isDirectory();
   } catch {
     return false;
@@ -19770,7 +20663,7 @@ async function atomicWrite(targetPath, data) {
   const absolute = resolve4(targetPath);
   const dir = dirname2(absolute);
   const tmp = join3(dir, `.baker-image-${randomBytes(8).toString("hex")}.tmp`);
-  await writeFile4(tmp, data);
+  await writeFile5(tmp, data);
   await rename(tmp, absolute);
 }
 
@@ -20113,7 +21006,7 @@ var findCommand = defineCommand108({
 });
 
 // src/commands/images/generate.ts
-import { readFile as readFile11 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 import { defineCommand as defineCommand109 } from "citty";
 import sharp2 from "sharp";
 var GENERATE_TIMEOUT_MS = 18e4;
@@ -20203,7 +21096,7 @@ async function resolveReferences(spec) {
     }
     let raw;
     try {
-      raw = await readFile11(entry);
+      raw = await readFile12(entry);
     } catch {
       throw new ApiError("VALIDATION_ERROR", `Reference file not found: ${entry}`);
     }
@@ -24230,7 +25123,7 @@ var searchCommand3 = defineCommand154({
 var tagsCommand4 = makeTagsCommand("videos", "video", "/api/videos/tags");
 
 // src/commands/videos/upload.ts
-import { readFile as readFile12, stat as stat3 } from "fs/promises";
+import { readFile as readFile13, stat as stat3 } from "fs/promises";
 import { extname as extname3 } from "path";
 import { defineCommand as defineCommand155 } from "citty";
 var MIME_MAP = {
@@ -24295,7 +25188,7 @@ var uploadCommand2 = defineCommand155({
         return;
       }
       const { uploadUrl, videoId } = await apiPost("/api/videos/upload", {});
-      const fileBuffer = await readFile12(filePath);
+      const fileBuffer = await readFile13(filePath);
       const uploadResponse = await fetch(uploadUrl, {
         method: "PUT",
         headers: { "Content-Type": contentType },