@koda-sl/baker-cli 0.122.1-dev.57a9836c5 → 0.123.0-dev.4a85b9f30

package/dist/cli.js

@@ -5,6 +5,7 @@ import {
   IMAGE_GENERATE_MODELS,
   LayerExecutionError,
   MODEL_REGISTRY,
+  REF_PREFIX,
   SEEDANCE_DURATIONS,
   ValidationError,
   collectAssetRefLikes,
@@ -14,13 +15,14 @@ import {
   elementMentionKeywords,
   generateCatalog,
   isPersistedAssetRef,
+  parseRefExpr,
   requireCredentialsFromEnv,
   resolveConcurrency,
   sha256Hex,
   toModelSafeImage,
   ulid,
   validateCanvasDeep
-} from "./chunk-T6HBTZOO.js";
+} from "./chunk-43KBQLP5.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -4671,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(path14) {
-  if (typeof path14 !== "string" || path14.length === 0) {
+function rawFileEntries(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return [];
   }
-  return readFileSync2(path14, "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;
@@ -4698,19 +4700,19 @@ function keywordEntries(args) {
   }
   return entries;
 }
-function loadJsonFileArg(path14) {
-  if (typeof path14 !== "string" || path14.length === 0) {
+function loadJsonFileArg(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync2(path14, "utf8"));
+    const parsed = JSON.parse(readFileSync2(path15, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      failWriteValidation(`${path14} must contain a JSON object`);
+      failWriteValidation(`${path15} must contain a JSON object`);
     }
     return parsed;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      failWriteValidation(`${path14} is not valid JSON: ${err.message}`);
+      failWriteValidation(`${path15} is not valid JSON: ${err.message}`);
     }
     throw err;
   }
@@ -4821,10 +4823,10 @@ async function stageUpdate(kind, customerId, target, payload) {
 async function stageTarget(kind, customerId, target) {
   await stageGoogleOp({ kind, customerId, target });
 }
-async function draftAction(path14, body) {
+async function draftAction(path15, body) {
   try {
     const chatId = requireChatId();
-    const response = await apiPost(path14, { chatId, ...body });
+    const response = await apiPost(path15, { chatId, ...body });
     writeJsonEnvelope(response);
   } catch (err) {
     handleGoogleError(err);
@@ -8579,19 +8581,19 @@ function failWriteValidation2(message) {
   writeJsonEnvelope({ ok: false, error: { code: "VALIDATION_ERROR", message } });
   process.exit(1);
 }
-function loadJsonFileArg2(path14) {
-  if (typeof path14 !== "string" || path14.length === 0) {
+function loadJsonFileArg2(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync6(path14, "utf8"));
+    const parsed = JSON.parse(readFileSync6(path15, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      failWriteValidation2(`${path14} must contain a JSON object`);
+      failWriteValidation2(`${path15} must contain a JSON object`);
     }
     return parsed;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      failWriteValidation2(`${path14} is not valid JSON: ${err.message}`);
+      failWriteValidation2(`${path15} is not valid JSON: ${err.message}`);
     }
     throw err;
   }
@@ -8676,15 +8678,15 @@ function parseLocaleFlag(value) {
   }
   return { language: match[1], country: match[2].toUpperCase() };
 }
-function loadTargetingFileArg(path14) {
-  if (typeof path14 !== "string" || path14.length === 0) {
+function loadTargetingFileArg(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return void 0;
   }
-  const parsed = loadJsonFileArg2(path14);
+  const parsed = loadJsonFileArg2(path15);
   const criteria = parsed.targetingCriteria ?? parsed;
   if (!criteria.include) {
     failWriteValidation2(
-      `${path14} 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;
@@ -8719,14 +8721,14 @@ function parseCsvLine(line) {
   cells.push(current);
   return cells.map((cell) => cell.trim());
 }
-function parseListFileArg(path14, maxRows) {
-  if (typeof path14 !== "string" || path14.length === 0) {
+function parseListFileArg(path15, maxRows) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return void 0;
   }
-  const raw = readFileSync6(path14, "utf8");
+  const raw = readFileSync6(path15, "utf8");
   const lines = raw.split(/\r?\n/).filter((line) => line.trim().length > 0);
   if (lines.length < 2) {
-    failWriteValidation2(`${path14} 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 = [];
@@ -8745,7 +8747,7 @@ function parseListFileArg(path14, maxRows) {
     }
   }
   if (rows.length > maxRows) {
-    failWriteValidation2(`${path14} 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 };
 }
@@ -10828,11 +10830,11 @@ var updateStatusSchema = z9.enum(UPDATE_STATUSES);
 function currencyMinimums2(currencyCode) {
   return CURRENCY_MINIMUMS2[currencyCode] ?? DEFAULT_CURRENCY_MINIMUM2;
 }
-function validateDailyBudgetFloor(money, ctx, path14) {
+function validateDailyBudgetFloor(money, ctx, path15) {
   if (money?.currencyCode) {
     const min = currencyMinimums2(money.currencyCode).dailyBudgetMin;
     if (Number(money.amount) < min) {
-      ctx.addIssue({ code: "custom", path: path14, message: `below the ${min} ${money.currencyCode} daily minimum` });
+      ctx.addIssue({ code: "custom", path: path15, message: `below the ${min} ${money.currencyCode} daily minimum` });
     }
   }
 }
@@ -11320,19 +11322,19 @@ function failWriteValidation3(message) {
   writeJsonEnvelope({ ok: false, error: { code: "VALIDATION_ERROR", message } });
   process.exit(1);
 }
-function loadJsonFileArg3(path14) {
-  if (typeof path14 !== "string" || path14.length === 0) {
+function loadJsonFileArg3(path15) {
+  if (typeof path15 !== "string" || path15.length === 0) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync8(path14, "utf8"));
+    const parsed = JSON.parse(readFileSync8(path15, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      failWriteValidation3(`${path14} must contain a JSON object`);
+      failWriteValidation3(`${path15} must contain a JSON object`);
     }
     return parsed;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      failWriteValidation3(`${path14} is not valid JSON: ${err.message}`);
+      failWriteValidation3(`${path15} is not valid JSON: ${err.message}`);
     }
     throw err;
   }
@@ -14394,8 +14396,8 @@ async function probeDuration(filePath) {
 }
 
 // src/commands/canvas/run.ts
-import { readFile as readFile2 } from "fs/promises";
-import path5 from "path";
+import { readFile as readFile3 } from "fs/promises";
+import path6 from "path";
 import { defineCommand as defineCommand88 } from "citty";
 
 // src/commands/canvas/placeholders.ts
@@ -14658,6 +14660,7 @@ var RunRecordPoster = class {
   latest = null;
   inflight = null;
   warned = false;
+  keepaliveTimer = null;
   constructor(post) {
     this.post = post;
   }
@@ -14666,12 +14669,36 @@ var RunRecordPoster = class {
     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);
@@ -14721,6 +14748,45 @@ async function pruneOldRuns(outputsDir, keep, currentRunId, log) {
   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." },
@@ -14728,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)"
@@ -14756,8 +14831,8 @@ var runCommand = defineCommand88({
     }
   },
   async run({ args }) {
-    const filePath = path5.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);
@@ -14767,7 +14842,7 @@ var runCommand = defineCommand88({
 `);
       process.exit(2);
     }
-    parsed = resolveRelativeCanvasPaths(parsed, path5.dirname(filePath));
+    parsed = resolveRelativeCanvasPaths(parsed, path6.dirname(filePath));
     const pending = unsuppliedPlaceholderAssets(parsed);
     if (pending.length > 0) {
       process.stderr.write(
@@ -14787,6 +14862,34 @@ 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,
@@ -14795,16 +14898,30 @@ var runCommand = defineCommand88({
 `),
       remoteCache
     });
-    const runId = args["run-id"] ? String(args["run-id"]) : `r_${ulid()}`;
+    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: path5.relative(process.cwd(), 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, {
@@ -14815,15 +14932,16 @@ var runCommand = defineCommand88({
           (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"] ? path5.resolve(String(args["outputs-dir"])) : path5.resolve("canvas");
         await pruneOldRuns(outputsDir, keepRuns, result.run_id, (line) => process.stdout.write(`${line}
 `));
       }
@@ -14842,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)}
@@ -14867,6 +14986,11 @@ var runCommand = defineCommand88({
     }
   }
 });
+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 {
@@ -14882,8 +15006,8 @@ function buildRecorder() {
 }
 
 // src/commands/canvas/scaffold-static-ad.ts
-import { access, mkdir, readFile as readFile3, writeFile } from "fs/promises";
-import path8 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
@@ -15070,7 +15194,7 @@ function staticAdReport(input, elementsInput, opts) {
 }
 
 // src/commands/canvas/creative-definition.ts
-import path6 from "path";
+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) {
@@ -15116,16 +15240,16 @@ function buildCreativeDefinition(input) {
 }
 
 // src/commands/canvas/scaffold-static-ad-paths.ts
-import path7 from "path";
+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 : path7.resolve(cwd, file);
-  const outPath = out ? path7.resolve(cwd, out) : slug ? path7.join(cwd, "src", "creatives", slug, `${slug}.canvas.json`) : imageIsUrl ? path7.join(cwd, "static-ad.canvas.json") : path7.join(path7.dirname(imageSource), "static-ad.canvas.json");
-  const blueprintPath = path7.join(path7.dirname(outPath), "prompt.json");
-  const creativeDir = slug ? path7.dirname(outPath) : null;
-  const definitionPath = creativeDir ? path7.join(creativeDir, "_definition.md") : null;
-  const referencesDir = creativeDir ? path7.join(creativeDir, "references") : null;
+  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])?$/;
@@ -15134,6 +15258,79 @@ 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 {
@@ -15150,19 +15347,19 @@ var MODEL_SAFE_EXT_BY_MIME = {
   "image/webp": ".webp"
 };
 async function copySourceIntoReferences(source, isUrl, referencesDir) {
-  await mkdir(referencesDir, { recursive: true });
+  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 readFile3(source);
+    bytes = await readFile4(source);
   }
   const safe = await toModelSafeImage(bytes);
   const relPath = referenceRelativePath("image", MODEL_SAFE_EXT_BY_MIME[safe.mime] ?? ".png");
-  const dest = path8.join(referencesDir, path8.basename(relPath));
-  await writeFile(dest, safe.bytes);
+  const dest = path9.join(referencesDir, path9.basename(relPath));
+  await writeFile2(dest, safe.bytes);
   return relPath;
 }
 function resolveModel(kind, preferred) {
@@ -15207,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})`);
@@ -15356,7 +15553,7 @@ var scaffoldStaticAdCommand = defineCommand89({
       process.cwd(),
       slug
     );
-    await mkdir(path8.dirname(outPath), { recursive: true });
+    await mkdir2(path9.dirname(outPath), { recursive: true });
     const { describeModel, selectModel, layoutModel, genModel } = resolveModels(args);
     const describeCanvas = buildDescribeCanvas(
       imageSource,
@@ -15371,7 +15568,7 @@ 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;
@@ -15407,10 +15604,10 @@ 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 writeFile(
+      await writeFile2(
         definitionPath,
         buildCreativeDefinition({
           title: args.title ? String(args.title) : titleFromSlug(slug ?? ""),
@@ -15426,6 +15623,16 @@ var scaffoldStaticAdCommand = defineCommand89({
         "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(
         {
@@ -15444,10 +15651,10 @@ var scaffoldStaticAdCommand = defineCommand89({
             run_estimated_credits: validation.estimatedCredits
           },
           checklist: {
-            edit_prompt: `Edit ${path8.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,
@@ -15459,13 +15666,14 @@ var scaffoldStaticAdCommand = defineCommand89({
 });
 
 // src/commands/canvas/scaffold-video.ts
-import { cp, mkdir as mkdir2, readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
-import path11 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";
@@ -15541,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 = {}) {
@@ -16168,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":
@@ -16425,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`;
@@ -16949,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",
@@ -17207,6 +17429,7 @@ function makePresenterPresent(slots, canonical, opts = {}) {
 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 SEEDANCE_MAX_WORDS_PER_TAKE = 16;
 var JOIN_DEDUP_MAX_WORDS = 4;
 function joinKey(word) {
   return word.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
@@ -17310,7 +17533,11 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
     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;
+    Math.max(cur.coverEnd, lineCover) - Math.min(cur.clipStart, lineClipStart) > PHRASE_MAX_S || // Cap by SPOKEN WORDS too: a dense read that fits the time ceiling can still cram a
+    // monologue Seedance can't lip-sync cleanly. Break before this line pushes the run
+    // past the word cap (a fresh run always accepts its own first line, so one long line
+    // is never blocked — it just can't be sub-split without a mid-word cut).
+    cur.words + wordCount(ln.text) > SEEDANCE_MAX_WORDS_PER_TAKE;
     if (breakRun || !cur) {
       flush();
       cur = {
@@ -17321,6 +17548,7 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
         coverEnd: lineCover,
         clipStart: lineClipStart,
         texts: [ln.text],
+        words: wordCount(ln.text),
         shown: /* @__PURE__ */ new Set()
       };
     } else {
@@ -17328,6 +17556,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);
+      cur.words += wordCount(ln.text);
     }
     if (ln.shown) cur.shown.add(ln.sceneIndex);
   }
@@ -17435,19 +17664,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,
@@ -17463,18 +17685,32 @@ 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, env, out);
+}
+function registerMergedPhraseSlices(phrase, clipRef, clipStart, genDur, env, out) {
+  const shown = [...phrase.shownScenes].sort((a, b) => a - b);
+  let r = 0;
+  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),
+      len: Math.max(0.5, runEnd - firstStart),
       clipDur: genDur
     });
+    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) {
@@ -17617,7 +17853,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;
@@ -17680,6 +17916,22 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
   out.clips.push(clip);
   return last;
 }
+function emitPresenterSliceClip(i, slice, env, nodes, out) {
+  if (slice.skip) return;
+  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 });
+    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 });
+}
 function buildTimeline(blueprint, slots, opts, nodes) {
   const reuse = opts.frames === "reuse";
   const uiRouted = uiRoutedSceneSet(blueprint);
@@ -17752,22 +18004,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;
     }
@@ -18108,16 +18345,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) => {
@@ -18568,23 +18813,23 @@ function videoReport(input, elementsInput) {
 
 // src/commands/canvas/composition-path.ts
 import { existsSync as existsSync3 } from "fs";
-import path9 from "path";
+import path10 from "path";
 function resolveShippedCanvasDir(name, startDir, exists = existsSync3, maxDepth = 8) {
-  const rel = path9.join("canvas", name);
+  const rel = path10.join("canvas", name);
   let dir = startDir;
   for (let i = 0; i < maxDepth; i++) {
-    const candidate = path9.join(dir, rel);
-    if (exists(path9.join(candidate, "meta.json"))) return candidate;
-    const parent = path9.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 path9.resolve(startDir, "../../../", rel);
+  return path10.resolve(startDir, "../../../", rel);
 }
 
 // src/commands/canvas/gitignore.ts
-import { appendFile, readFile as readFile5 } from "fs/promises";
-import path10 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("#"))
@@ -18592,10 +18837,10 @@ function missingGitignoreEntries(existing, entries) {
   return entries.filter((e) => !present.has(e.trim().replace(/\/+$/, "")));
 }
 async function ensureGitignore(dir, entries) {
-  const file = path10.join(dir, ".gitignore");
+  const file = path11.join(dir, ".gitignore");
   let existing;
   try {
-    existing = await readFile5(file, "utf8");
+    existing = await readFile6(file, "utf8");
   } catch {
     return;
   }
@@ -18634,7 +18879,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})`);
@@ -18653,7 +18898,7 @@ async function loadTranscriptBestEffort(ref) {
 async function stageCaptions(outDir, transcript) {
   const text = transcript?.trim();
   if (!text || text === "[]") return {};
-  const compositionPath = path11.join(outDir, "tiktok-captions-composition");
+  const compositionPath = path12.join(outDir, "tiktok-captions-composition");
   await cp(SHIPPED_CAPTIONS_DIR, compositionPath, { recursive: true });
   return { compositionPath };
 }
@@ -18671,12 +18916,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 = path11.join(compositionDir, "meta.json");
-  const rawMeta = await readFile6(metaPath, "utf8");
-  await writeFile2(metaPath, patchCompositionMeta(rawMeta, dims), "utf8");
-  const htmlPath = path11.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);
@@ -18716,6 +18961,56 @@ 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 resolveModels2(args) {
   const pick = (flag, kind, fallback) => args[flag] ? String(args[flag]) : resolveModel2(kind, fallback);
   return {
@@ -18812,7 +19107,11 @@ 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",
@@ -18830,6 +19129,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" },
@@ -18844,8 +19151,7 @@ var scaffoldVideoCommand = defineCommand90({
     }
   },
   async run({ args }) {
-    const videoPath = path11.resolve(String(args.file));
-    const base = path11.basename(videoPath, path11.extname(videoPath));
+    const fileArg2 = String(args.file);
     const slug = args.slug ? String(args.slug) : void 0;
     if (slug && !isValidScaffoldSlug(slug)) {
       process.stderr.write(
@@ -18854,9 +19160,24 @@ var scaffoldVideoCommand = defineCommand90({
       );
       process.exit(2);
     }
-    const outPath = args.out ? path11.resolve(String(args.out)) : slug ? path11.join(process.cwd(), "src", "creatives", slug, `${slug}.canvas.json`) : path11.join(path11.dirname(videoPath), `${base}.video.canvas.json`);
-    const outDir = path11.dirname(outPath);
-    const blueprintPath = path11.join(outDir, "prompt.json");
+    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)) {
@@ -18875,10 +19196,16 @@ var scaffoldVideoCommand = defineCommand90({
       shotCuts
     });
     const { blueprint, elements, transcript, creditsSpent } = await runAnalysisPasses(deconstructCanvas, selectModel);
-    await mkdir2(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(
@@ -18896,12 +19223,12 @@ var scaffoldVideoCommand = defineCommand90({
 `
       );
     }
-    const compositionDest = path11.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 = path11.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(
@@ -18909,15 +19236,16 @@ 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: path11.relative(outDir, compositionDest),
-      captionsCompositionPath: captions.compositionPath ? path11.relative(outDir, captions.compositionPath) : void 0,
-      blueprintPath: path11.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),
       ...args.aspect ? { aspect: String(args.aspect) } : {},
@@ -18938,7 +19266,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(
@@ -18958,12 +19286,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,
@@ -18975,7 +19333,7 @@ var scaffoldVideoCommand = defineCommand90({
             run_estimated_credits: validation.estimatedCredits
           },
           checklist: {
-            edit_prompt: `Edit ${path11.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,
@@ -18989,6 +19347,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."
           }
         },
@@ -19001,8 +19366,8 @@ var scaffoldVideoCommand = defineCommand90({
 });
 
 // src/commands/canvas/set-prompt.ts
-import { readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
-import path12 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;
@@ -19030,17 +19395,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 = path12.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(path12.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(
@@ -19061,14 +19426,14 @@ var setPromptCommand = defineCommand91({
       process.exit(2);
       return;
     }
-    const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(updated, path12.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)}
 `);
@@ -19076,8 +19441,8 @@ var setPromptCommand = defineCommand91({
 });
 
 // src/commands/canvas/validate.ts
-import { readFile as readFile8 } from "fs/promises";
-import path13 from "path";
+import { readFile as readFile9 } from "fs/promises";
+import path14 from "path";
 import { defineCommand as defineCommand92 } from "citty";
 var validateCommand = defineCommand92({
   meta: {
@@ -19086,8 +19451,8 @@ var validateCommand = defineCommand92({
   },
   args: { file: { type: "positional", required: true, description: "Path to canvas JSON" } },
   async run({ args }) {
-    const filePath = path13.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);
@@ -19097,7 +19462,7 @@ var validateCommand = defineCommand92({
 `);
       process.exit(2);
     }
-    parsed = resolveRelativeCanvasPaths(parsed, path13.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)}
@@ -19156,7 +19521,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;
@@ -19170,7 +19535,7 @@ var mimeMap = {
   ".avif": "image/avif"
 };
 var defaultImageApiDeps = {
-  readFile: readFile9,
+  readFile: readFile10,
   post: apiPost,
   get: apiGet,
   sleep: (ms) => new Promise((resolve5) => setTimeout(resolve5, ms))
@@ -20200,7 +20565,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 = /[*?[\]{}]/;
@@ -20236,11 +20601,11 @@ async function readImageBuffer(pathOrUrl) {
     }
     return Buffer.from(await response.arrayBuffer());
   }
-  return readFile10(pathOrUrl);
+  return readFile11(pathOrUrl);
 }
-async function isDirectory(path14) {
+async function isDirectory(path15) {
   try {
-    const s = await stat2(path14);
+    const s = await stat2(path15);
     return s.isDirectory();
   } catch {
     return false;
@@ -20259,7 +20624,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);
 }
 
@@ -20602,7 +20967,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;
@@ -20692,7 +21057,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}`);
     }
@@ -24719,7 +25084,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 = {
@@ -24784,7 +25149,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 },