@koda-sl/baker-cli 0.114.0-dev.249eaa8ed → 0.115.0-dev.3bcc79f9c

package/dist/cli.js

@@ -1,18 +1,24 @@
 #!/usr/bin/env node
 import {
+  BackendClient,
   ELEVENLABS_MAX_MUSIC_LENGTH_MS,
   IMAGE_GENERATE_MODELS,
   LayerExecutionError,
   MODEL_REGISTRY,
   SEEDANCE_DURATIONS,
   ValidationError,
+  collectAssetRefLikes,
   createEngineFromEnv,
   defaultRegistry,
   describeFailureReason,
   generateCatalog,
+  isPersistedAssetRef,
+  requireCredentialsFromEnv,
   resolveConcurrency,
+  sha256Hex,
+  ulid,
   validateCanvasDeep
-} from "./chunk-5AWO4BHJ.js";
+} from "./chunk-OCMOQOIJ.js";
 
 // src/cli.ts
 import { defineCommand as defineCommand157, runMain } from "citty";
@@ -151,9 +157,9 @@ async function handleResponse(response) {
     throw new ApiError("INTERNAL_ERROR", "Failed to parse API response as JSON");
   }
 }
-async function apiGet(path12, params) {
+async function apiGet(path14, params) {
   const env = getEnv();
-  const url = new URL(path12, env.BAKER_API_URL);
+  const url = new URL(path14, env.BAKER_API_URL);
   if (params) {
     const clean = sanitizeParams(params);
     for (const [key, value] of Object.entries(clean)) {
@@ -178,12 +184,12 @@ async function apiGet(path12, params) {
   }
   return handleResponse(response);
 }
-async function apiPost(path12, body, opts) {
+async function apiPost(path14, body, opts) {
   const env = getEnv();
   const timeoutMs = opts?.timeoutMs ?? 6e4;
   let response;
   try {
-    response = await fetchWithRateLimitRetry(new URL(path12, env.BAKER_API_URL).toString(), {
+    response = await fetchWithRateLimitRetry(new URL(path14, env.BAKER_API_URL).toString(), {
       method: "POST",
       headers: {
         Authorization: `Bearer ${env.BAKER_API_KEY}`,
@@ -2875,31 +2881,31 @@ function cachePath(category, key) {
   return join2(dir, `${hashKey(key)}.json`);
 }
 function cacheGet(category, key) {
-  const path12 = cachePath(category, key);
-  if (!existsSync2(path12)) {
+  const path14 = cachePath(category, key);
+  if (!existsSync2(path14)) {
     return null;
   }
   try {
-    const raw = readFileSync2(path12, "utf-8");
+    const raw = readFileSync2(path14, "utf-8");
     const entry = JSON.parse(raw);
     if (entry.expiresAt < Date.now()) {
-      rmSync(path12, { force: true });
+      rmSync(path14, { force: true });
       return null;
     }
     return entry;
   } catch {
-    rmSync(path12, { force: true });
+    rmSync(path14, { force: true });
     return null;
   }
 }
 function cacheSet(category, key, data, ttlMs, fields) {
-  const path12 = cachePath(category, key);
+  const path14 = cachePath(category, key);
   const entry = {
     expiresAt: Date.now() + ttlMs,
     data,
     fields
   };
-  writeFileSync(path12, JSON.stringify(entry), "utf-8");
+  writeFileSync(path14, JSON.stringify(entry), "utf-8");
 }
 var HOUR = 60 * 60 * 1e3;
 var MINUTE = 60 * 1e3;
@@ -4226,7 +4232,11 @@ var responsiveDisplayAdSchema = z8.object({
   longHeadline: z8.object({ text: z8.string().min(1).max(GOOGLE_ADS_LIMITS.responsiveDisplayAd.longHeadlineTextMax) }),
   descriptions: z8.array(z8.object({ text: z8.string().min(1).max(GOOGLE_ADS_LIMITS.responsiveDisplayAd.descriptionTextMax) })).min(1).max(5),
   businessName: z8.string().min(1).max(GOOGLE_ADS_LIMITS.responsiveDisplayAd.businessNameMax),
+  // A Responsive Display Ad's images are fields on the ad's own content (never campaign-level
+  // asset links). Google requires ≥1 landscape marketing image (1.91:1) AND ≥1 square marketing
+  // image (1:1) to serve; the logo images are optional.
   marketingImageAssets: z8.array(refSchema).optional(),
+  squareMarketingImageAssets: z8.array(refSchema).optional(),
   logoImageAssets: z8.array(refSchema).optional(),
   finalUrls: z8.array(httpsUrlSchema2).min(1)
 });
@@ -4411,7 +4421,11 @@ var adScheduleCriterionSchema = z8.object({
 var deviceCriterionSchema = z8.object({
   criterionType: z8.literal("device"),
   device: z8.enum(DEVICE_TYPES),
-  bidModifier: z8.number().min(0.1).max(10).optional()
+  // Google's `CampaignCriterion.bid_modifier`: "The modifier must be in the range 0.1 - 10.0. Use 0
+  // to opt out of a Device type." So 0 (exclude the device) and 0.1–10.0 are valid; the (0, 0.1) gap is not.
+  bidModifier: z8.number().min(0).max(10).optional().refine((v) => v === void 0 || v === 0 || v >= 0.1, {
+    message: "bid modifier must be 0 (exclude the device) or between 0.1 and 10.0"
+  })
 });
 var campaignCriterionAddSchema = z8.object({
   campaign: refSchema,
@@ -4422,6 +4436,15 @@ var campaignCriterionAddSchema = z8.object({
     adScheduleCriterionSchema,
     deviceCriterionSchema
   ])
+}).superRefine((val, ctx) => {
+  const c = val.criterion;
+  if (c.criterionType === "adSchedule" && c.endHour === 24 && c.endMinute !== "ZERO") {
+    ctx.addIssue({
+      code: z8.ZodIssueCode.custom,
+      message: "endHour 24 (midnight) cannot have a non-zero endMinute",
+      path: ["criterion", "endMinute"]
+    });
+  }
 });
 var GOOGLE_DRAFT_OP_KINDS = [
   "google.budget.create",
@@ -4595,7 +4618,8 @@ var googleDraftStatusNodeSchema = z9.lazy(
     operation: googleDraftChangeOperationSchema.optional(),
     existing: z9.boolean(),
     collections: z9.array(googleDraftStatusCollectionSchema),
-    children: z9.array(googleDraftStatusNodeSchema)
+    children: z9.array(googleDraftStatusNodeSchema),
+    warnings: z9.array(z9.string()).optional()
   })
 );
 var googleDraftListResponseSchema = z9.object({
@@ -4663,6 +4687,9 @@ function collectionLine(collection) {
 function renderNode(node, depth, lines) {
   const indent = "  ".repeat(depth);
   lines.push(`${indent}\u2022 ${node.name} \xB7 ${badge(node)}`);
+  for (const warning of node.warnings ?? []) {
+    lines.push(`${indent}    \u26A0 ${warning}`);
+  }
   for (const collection of node.collections) {
     const line = collectionLine(collection);
     if (line) {
@@ -4791,11 +4818,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(path14) {
+  if (typeof path14 !== "string" || path14.length === 0) {
     return [];
   }
-  return readFileSync3(path12, "utf8").split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"));
+  return readFileSync3(path14, "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;
@@ -4818,19 +4845,19 @@ function keywordEntries(args) {
   }
   return entries;
 }
-function loadJsonFileArg(path12) {
-  if (typeof path12 !== "string" || path12.length === 0) {
+function loadJsonFileArg(path14) {
+  if (typeof path14 !== "string" || path14.length === 0) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync3(path12, "utf8"));
+    const parsed = JSON.parse(readFileSync3(path14, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      failWriteValidation(`${path12} must contain a JSON object`);
+      failWriteValidation(`${path14} must contain a JSON object`);
     }
     return parsed;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      failWriteValidation(`${path12} is not valid JSON: ${err.message}`);
+      failWriteValidation(`${path14} is not valid JSON: ${err.message}`);
     }
     throw err;
   }
@@ -4919,10 +4946,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(path14, body) {
   try {
     const chatId = requireChatId();
-    const response = await apiPost(path12, { chatId, ...body });
+    const response = await apiPost(path14, { chatId, ...body });
     writeJsonEnvelope(response);
   } catch (err) {
     handleGoogleError(err);
@@ -5798,8 +5825,9 @@ function applyAutoFixes(query, limit) {
   if (/FROM\s+campaign_budget\b/i.test(corrected)) {
     const whereClause = corrected.split(/\bWHERE\b/i)[1] ?? "";
     const selectClause = corrected.split(/\bFROM\b/i)[0] ?? "";
+    const selectFields = new Set(selectClause.match(/campaign\.[\w.]+/g) ?? []);
     const missing = [...new Set(whereClause.match(/campaign\.[\w.]+/g) ?? [])].filter(
-      (field) => !selectClause.includes(field)
+      (field) => !selectFields.has(field)
     );
     if (missing.length > 0) {
       corrected = corrected.replace(/SELECT\s+/i, `SELECT ${missing.join(", ")}, `);
@@ -6654,6 +6682,52 @@ function rsaContentFromFlags(args) {
     finalUrls
   };
 }
+function rdaContentFromFlags(args, base) {
+  const content = {
+    format: "responsiveDisplay",
+    ...base !== null && typeof base === "object" && !Array.isArray(base) ? base : {}
+  };
+  const headlines = listFlag(args.headlines);
+  if (headlines) {
+    content.headlines = headlines.map((text) => ({ text }));
+  }
+  const descriptions = listFlag(args.descriptions);
+  if (descriptions) {
+    content.descriptions = descriptions.map((text) => ({ text }));
+  }
+  if (typeof args["long-headline"] === "string") {
+    content.longHeadline = { text: args["long-headline"] };
+  }
+  if (typeof args["business-name"] === "string") {
+    content.businessName = args["business-name"];
+  }
+  const finalUrls = listFlag(args["final-url"]);
+  if (finalUrls) {
+    content.finalUrls = finalUrls;
+  }
+  const marketing = listFlag(args["marketing-images"]);
+  if (marketing) {
+    content.marketingImageAssets = marketing;
+  }
+  const square = listFlag(args["square-marketing-images"]);
+  if (square) {
+    content.squareMarketingImageAssets = square;
+  }
+  const logos = listFlag(args["logo-images"]);
+  if (logos) {
+    content.logoImageAssets = logos;
+  }
+  return content;
+}
+function adContentFromFlags(args, format, fileContent) {
+  if (format === "responsiveSearch") {
+    return fileContent ?? rsaContentFromFlags(args);
+  }
+  if (format === "responsiveDisplay") {
+    return rdaContentFromFlags(args, fileContent);
+  }
+  return fileContent ?? failWriteValidation(`--format ${format} needs --file with the ad content`);
+}
 var adsCommand = defineCommand30({
   meta: { name: "ads", description: "Stage ad create/update/pause/resume/remove" },
   subCommands: {
@@ -6670,10 +6744,21 @@ var adsCommand = defineCommand30({
           type: "string",
           description: "responsiveSearch (default) | responsiveDisplay | performanceMaxAssetGroup | call | app | video | demandGen"
         },
-        headlines: { type: "string", description: "Comma-separated headlines (RSA)" },
-        descriptions: { type: "string", description: "Comma-separated descriptions (RSA)" },
+        headlines: { type: "string", description: "Comma-separated headlines (RSA/RDA)" },
+        descriptions: { type: "string", description: "Comma-separated descriptions (RSA/RDA)" },
         path1: { type: "string" },
         path2: { type: "string" },
+        "long-headline": { type: "string", description: "Long headline (responsiveDisplay)" },
+        "business-name": { type: "string", description: "Business name (responsiveDisplay)" },
+        "marketing-images": {
+          type: "string",
+          description: "Comma-separated marketing image asset refs (responsiveDisplay)"
+        },
+        "square-marketing-images": {
+          type: "string",
+          description: "Comma-separated square marketing image asset refs (responsiveDisplay)"
+        },
+        "logo-images": { type: "string", description: "Comma-separated logo image asset refs (responsiveDisplay)" },
         "final-url": { type: "string", description: "Comma-separated final URLs" },
         status: { type: "string" }
       },
@@ -6681,7 +6766,7 @@ var adsCommand = defineCommand30({
         const customerId = requireCustomerId(args);
         const file = loadJsonFileArg(args.file);
         const format = args.format ?? "responsiveSearch";
-        const content = file.content ?? (format === "responsiveSearch" ? rsaContentFromFlags(args) : failWriteValidation(`--format ${format} needs --file with the ad content`));
+        const content = adContentFromFlags(args, format, file.content);
         await stageCreate("google.ad.create", customerId, {
           adGroup: requireStringFlag(args["ad-group-ref"] ?? file.adGroup, "--ad-group-ref"),
           status: args.status ?? file.status,
@@ -8405,19 +8490,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(path14) {
+  if (typeof path14 !== "string" || path14.length === 0) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync7(path12, "utf8"));
+    const parsed = JSON.parse(readFileSync7(path14, "utf8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      failWriteValidation2(`${path12} must contain a JSON object`);
+      failWriteValidation2(`${path14} must contain a JSON object`);
     }
     return parsed;
   } catch (err) {
     if (err instanceof SyntaxError) {
-      failWriteValidation2(`${path12} is not valid JSON: ${err.message}`);
+      failWriteValidation2(`${path14} is not valid JSON: ${err.message}`);
     }
     throw err;
   }
@@ -8480,15 +8565,15 @@ function parseLocaleFlag(value) {
   }
   return { language: match[1], country: match[2].toUpperCase() };
 }
-function loadTargetingFileArg(path12) {
-  if (typeof path12 !== "string" || path12.length === 0) {
+function loadTargetingFileArg(path14) {
+  if (typeof path14 !== "string" || path14.length === 0) {
     return void 0;
   }
-  const parsed = loadJsonFileArg2(path12);
+  const parsed = loadJsonFileArg2(path14);
   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)`
+      `${path14} must contain targeting criteria with an "include" block (see baker schema ads.linkedin.campaigns.create)`
     );
   }
   return criteria;
@@ -8523,14 +8608,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(path14, maxRows) {
+  if (typeof path14 !== "string" || path14.length === 0) {
     return void 0;
   }
-  const raw = readFileSync7(path12, "utf8");
+  const raw = readFileSync7(path14, "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(`${path14} needs a header row and at least one data row`);
   }
   const columns = parseCsvLine(lines[0]).map((column) => column.trim());
   const rows = [];
@@ -8549,7 +8634,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(`${path14} has ${rows.length} rows \u2014 the inline limit is ${maxRows}. Split the list.`);
   }
   return { columns, rows };
 }
@@ -12752,7 +12837,7 @@ async function probeDuration(filePath) {
 
 // src/commands/canvas/run.ts
 import { readFile as readFile2 } from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 import { defineCommand as defineCommand85 } from "citty";
 
 // src/commands/canvas/placeholders.ts
@@ -12796,9 +12881,102 @@ 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_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) {
+  const nodes = result.node_runs.slice(0, MAX_RUN_NODES).map((run) => ({
+    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] ?? {})
+  }));
+  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-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;
@@ -12815,7 +12993,7 @@ 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}`)
     );
   }
@@ -12835,13 +13013,29 @@ var runCommand = defineCommand85({
       type: "string",
       description: "Max nodes per layer in flight at once (default 5; env BAKER_CANVAS_CONCURRENCY)"
     },
+    parallel: {
+      type: "string",
+      description: "Alias for --concurrency: independent clips (and every other same-layer node) already fan out in parallel up to this bound"
+    },
     "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 filePath = path5.resolve(String(args.file));
     const raw = await readFile2(filePath, "utf8");
     let parsed;
     try {
@@ -12852,7 +13046,7 @@ var runCommand = defineCommand85({
 `);
       process.exit(2);
     }
-    parsed = resolveRelativeCanvasPaths(parsed, path4.dirname(filePath));
+    parsed = resolveRelativeCanvasPaths(parsed, path5.dirname(filePath));
     const pending = unsuppliedPlaceholderAssets(parsed);
     if (pending.length > 0) {
       process.stderr.write(
@@ -12872,25 +13066,37 @@ var runCommand = defineCommand85({
       );
       process.exit(2);
     }
+    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 runId = args["run-id"] ? String(args["run-id"]) : `r_${ulid()}`;
+    const recordMeta = {
+      creativeSlug: creativeSlugFromCanvasPath(filePath) ?? void 0,
+      canvasPath: path5.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();
     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(
-          args.concurrency !== void 0 ? String(args.concurrency) : void 0,
+          // --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
         )
       });
+      if (record) await record(buildRunRecord(result, recordMeta));
       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");
+        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}
 `));
       }
@@ -12918,6 +13124,7 @@ var runCommand = defineCommand85({
       }
       if (e instanceof LayerExecutionError) {
         const failures = e.failures.map((f) => ({ node_id: f.nodeId, message: describeFailureReason(f.reason) }));
+        if (record) await record(buildFailedRunRecord(runId, e.message, recordMeta));
         process.stderr.write(
           `${JSON.stringify({ ok: false, error: { code: "runtime", message: e.message, failures } }, null, 2)}
 `
@@ -12925,16 +13132,30 @@ var runCommand = defineCommand85({
         process.exit(1);
       }
       const msg = e instanceof Error ? e.message : String(e);
+      if (record) await record(buildFailedRunRecord(runId, msg, recordMeta));
       process.stderr.write(`${JSON.stringify({ ok: false, error: { code: "runtime", message: msg } }, null, 2)}
 `);
       process.exit(1);
     }
   }
 });
+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, cp, mkdir, readFile as readFile3, writeFile } from "fs/promises";
+import path8 from "path";
 import { defineCommand as defineCommand86 } from "citty";
 
 // src/engine/scaffold/staticAd.ts
@@ -13120,18 +13341,106 @@ function staticAdReport(input, elementsInput, opts) {
   };
 }
 
+// src/commands/canvas/creative-definition.ts
+import path6 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 sourceExtension(source, isUrl, kind) {
+  const raw = isUrl ? urlPathname(source) : source;
+  const ext = path6.extname(raw).toLowerCase();
+  if (/^\.[a-z0-9]{1,5}$/.test(ext)) return ext;
+  return kind === "video" ? ".mp4" : ".jpg";
+}
+function urlPathname(source) {
+  try {
+    return new URL(source).pathname;
+  } catch {
+    return source;
+  }
+}
+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 path7 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 : 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;
+  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/scaffold-static-ad.ts
+async function fileExists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function copySourceIntoReferences(source, isUrl, referencesDir) {
+  await mkdir(referencesDir, { recursive: true });
+  const relPath = referenceRelativePath("image", sourceExtension(source, isUrl, "image"));
+  const dest = path8.join(referencesDir, path8.basename(relPath));
+  if (isUrl) {
+    const res = await fetch(source);
+    if (!res.ok) throw new Error(`failed to download source image (${res.status})`);
+    await writeFile(dest, Buffer.from(await res.arrayBuffer()));
+  } else {
+    await cp(source, dest);
+  }
+  return relPath;
+}
 function resolveModel(kind, preferred) {
   const ids = Object.keys(MODEL_REGISTRY[kind]);
   return ids.includes(preferred) ? preferred : ids[0] ?? preferred;
@@ -13291,6 +13600,16 @@ var scaffoldStaticAdCommand = defineCommand86({
     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" },
@@ -13299,10 +13618,21 @@ var scaffoldStaticAdCommand = defineCommand86({
     "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 mkdir(path8.dirname(outPath), { recursive: true });
     const { describeModel, selectModel, layoutModel, genModel } = resolveModels(args);
     const describeCanvas = buildDescribeCanvas(
       imageSource,
@@ -13319,11 +13649,21 @@ var scaffoldStaticAdCommand = defineCommand86({
     }
     await writeFile(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"]
     };
@@ -13345,12 +13685,31 @@ var scaffoldStaticAdCommand = defineCommand86({
     }
     await writeFile(outPath, `${JSON.stringify(canvas, null, 2)}
 `, "utf8");
+    if (definitionPath && !await fileExists(definitionPath)) {
+      await writeFile(
+        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"
+      );
+    }
     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,
@@ -13361,7 +13720,7 @@ var scaffoldStaticAdCommand = defineCommand86({
             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 ${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.`,
             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."
@@ -13376,8 +13735,8 @@ var scaffoldStaticAdCommand = defineCommand86({
 });
 
 // src/commands/canvas/scaffold-video.ts
-import { cp, mkdir, readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
-import path9 from "path";
+import { cp as cp2, mkdir as mkdir2, readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
+import path11 from "path";
 import { defineCommand as defineCommand87 } from "citty";
 
 // src/engine/nodes/local/lib/sceneDetect.ts
@@ -15844,7 +16203,8 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
   }
   const todo = {
     ...buildVideoTodo(videoReport(input, elementsInput), overlays.length, floating.length, opts, blueprint),
-    ...aspectRemapTodo(resolveAspect(blueprint.source?.aspect_ratio, opts.aspect, genAspectsFor(opts.videoModel)))
+    ...aspectRemapTodo(resolveAspect(blueprint.source?.aspect_ratio, opts.aspect, genAspectsFor(opts.videoModel))),
+    model_constraints: buildModelConstraints()
   };
   return {
     schema: "baker-canvas/1",
@@ -15855,21 +16215,58 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
       // The timing plan `baker canvas validate` checks before any billed render:
       // sequenced voiceover turns (no overlap), audio ≈ video length, and which
       // scenes must be lip-synced.
-      video: buildVideoMeta(blueprint, { vo_segments, talking_scenes })
+      video: buildVideoMeta(blueprint, { vo_segments, talking_scenes }, slots, nodes)
     },
     nodes,
     output: { node: videoNode, output: "video" }
   };
 }
-function buildVideoMeta(blueprint, meta) {
+function buildVideoMeta(blueprint, meta, slots, nodes) {
   return {
     duration_s: blueprint.source?.duration_s ?? lastSceneEnd(blueprint),
     vo_segments: [...meta.vo_segments].sort((a, b) => a.start_s - b.start_s),
     talking_scenes: meta.talking_scenes,
     lip_sync_caution: buildLipSyncCaution(meta.vo_segments),
-    motion_board: buildMotionBoard(blueprint)
+    motion_board: buildMotionBoard(blueprint),
+    // The wired recurring-element registry (the reference-completeness check reads
+    // `ref`/`label`/`type` to warn when a frame describes an element it doesn't wire).
+    elements: slots.map((s) => ({
+      ref: s.ref,
+      label: s.label,
+      type: s.type,
+      ...s.description ? { description: s.description } : {}
+    })),
+    clip_spans: buildClipSpans(blueprint, nodes)
   };
 }
+function buildModelConstraints() {
+  const models = {};
+  for (const [id, spec] of Object.entries(MODEL_REGISTRY.video_generate)) {
+    const p = spec.params;
+    models[id] = {
+      label: spec.label,
+      aspect_ratios: p.aspect_ratio?.enum ?? null,
+      durations_s: p.duration?.enum ?? null,
+      person_generation: p.person_generation?.enum ?? null
+    };
+  }
+  return {
+    note: "Switching a clip's video model has cross-node constraints. ALL video_generate nodes in one canvas MUST share ONE aspect_ratio (the composite silently crops otherwise). Each model's `duration` is a hard enum and differs per model \u2014 a scene longer than the model's max must be split. `person_generation` differs (Veo requires \"allow_all\"). `baker canvas validate` gates duration, aspect agreement, per-model params, AND a scene-span-vs-model-max advisory before any billed run \u2014 run it after every model edit.",
+    models
+  };
+}
+function buildClipSpans(blueprint, nodes) {
+  const spans = [];
+  for (const n of nodes) {
+    if (n.type !== "video_generate") continue;
+    const m = n.id.match(/^s(\d+)/);
+    const idx = m ? Number(m[1]) : Number.NaN;
+    const scene = Number.isInteger(idx) ? blueprint.scenes[idx] : void 0;
+    if (!scene) continue;
+    spans.push({ node: n.id, span_s: Math.round(sceneDurationS(scene) * 100) / 100 });
+  }
+  return spans;
+}
 function buildLipSyncCaution(segments) {
   const out = [];
   const byScene = /* @__PURE__ */ new Map();
@@ -16123,23 +16520,23 @@ function videoReport(input, elementsInput) {
 
 // src/commands/canvas/composition-path.ts
 import { existsSync as existsSync4 } from "fs";
-import path7 from "path";
+import path9 from "path";
 function resolveShippedCanvasDir(name, startDir, exists = existsSync4, maxDepth = 8) {
-  const rel = path7.join("canvas", name);
+  const rel = path9.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 = path9.join(dir, rel);
+    if (exists(path9.join(candidate, "meta.json"))) return candidate;
+    const parent = path9.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return path7.resolve(startDir, "../../../", rel);
+  return path9.resolve(startDir, "../../../", rel);
 }
 
 // src/commands/canvas/gitignore.ts
 import { appendFile, readFile as readFile5 } from "fs/promises";
-import path8 from "path";
+import path10 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("#"))
@@ -16147,7 +16544,7 @@ 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 = path10.join(dir, ".gitignore");
   let existing;
   try {
     existing = await readFile5(file, "utf8");
@@ -16208,8 +16605,8 @@ 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");
-  await cp(SHIPPED_CAPTIONS_DIR, compositionPath, { recursive: true });
+  const compositionPath = path11.join(outDir, "tiktok-captions-composition");
+  await cp2(SHIPPED_CAPTIONS_DIR, compositionPath, { recursive: true });
   return { compositionPath };
 }
 function patchCompositionMeta(metaJson, dims) {
@@ -16226,10 +16623,10 @@ 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 metaPath = path11.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 htmlPath = path11.join(compositionDir, "index.html");
   const rawHtml = await readFile6(htmlPath, "utf8");
   await writeFile2(htmlPath, patchCompositionHtml(rawHtml, dims), "utf8");
 }
@@ -16369,6 +16766,10 @@ var scaffoldVideoCommand = defineCommand87({
   args: {
     file: { type: "positional", required: true, description: "Path to the reference video" },
     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",
@@ -16395,11 +16796,19 @@ var scaffoldVideoCommand = defineCommand87({
     }
   },
   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 videoPath = path11.resolve(String(args.file));
+    const base = path11.basename(videoPath, path11.extname(videoPath));
+    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 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 frames = args.frames === "reuse" ? "reuse" : "generate";
     const maxScenes = args["max-scenes"] ? Number(args["max-scenes"]) : void 0;
     if (Number.isFinite(maxScenes)) {
@@ -16418,7 +16827,7 @@ var scaffoldVideoCommand = defineCommand87({
       shotCuts
     });
     const { blueprint, elements, transcript, creditsSpent } = await runAnalysisPasses(deconstructCanvas, selectModel);
-    await mkdir(outDir, { recursive: true });
+    await mkdir2(outDir, { recursive: true });
     const annotated = annotateBlueprintWithElements(blueprint, elements);
     await writeFile2(blueprintPath, `${JSON.stringify(annotated, null, 2)}
 `, "utf8");
@@ -16439,10 +16848,10 @@ var scaffoldVideoCommand = defineCommand87({
 `
       );
     }
-    const compositionDest = path9.join(outDir, "video-overlay-composition");
-    await cp(SHIPPED_COMPOSITION_DIR, compositionDest, { recursive: true });
+    const compositionDest = path11.join(outDir, "video-overlay-composition");
+    await cp2(SHIPPED_COMPOSITION_DIR, compositionDest, { recursive: true });
     await stampCompositionDims(compositionDest, outDims);
-    const indexPath = path9.join(compositionDest, "index.html");
+    const indexPath = path11.join(compositionDest, "index.html");
     const overlayHtml = buildOverlayHtml(blueprint);
     const indexHtml = await readFile6(indexPath, "utf8");
     const injected = indexHtml.replace("<!--OVERLAYS-->", () => overlayHtml);
@@ -16458,9 +16867,9 @@ var scaffoldVideoCommand = defineCommand87({
     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: path11.relative(outDir, compositionDest),
+      captionsCompositionPath: captions.compositionPath ? path11.relative(outDir, captions.compositionPath) : void 0,
+      blueprintPath: path11.relative(outDir, blueprintPath),
       frames,
       ambient: Boolean(args.ambient),
       ...args.aspect ? { aspect: String(args.aspect) } : {},
@@ -16502,7 +16911,7 @@ var scaffoldVideoCommand = defineCommand87({
             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 ${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.`,
             recurring_elements_to_supply: report.elements,
             voices_to_confirm: report.dialogue.map((d) => ({
               scene: d.scene,
@@ -16529,7 +16938,7 @@ var scaffoldVideoCommand = defineCommand87({
 
 // src/commands/canvas/set-prompt.ts
 import { readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
-import path10 from "path";
+import path12 from "path";
 import { defineCommand as defineCommand88 } from "citty";
 function setNodePrompt(canvas, nodeId, text) {
   const nodes = canvas?.nodes;
@@ -16557,7 +16966,7 @@ var setPromptCommand = defineCommand88({
     "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 = path12.resolve(String(args.file));
     let canvas;
     try {
       canvas = JSON.parse(await readFile7(filePath, "utf8"));
@@ -16567,7 +16976,7 @@ var setPromptCommand = defineCommand88({
       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 readFile7(path12.resolve(String(args["text-file"])), "utf8");
     else if (args.text !== void 0) text = String(args.text);
     else {
       process.stderr.write(
@@ -16588,7 +16997,7 @@ var setPromptCommand = defineCommand88({
       process.exit(2);
       return;
     }
-    const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(updated, path10.dirname(filePath)), defaultRegistry());
+    const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(updated, path12.dirname(filePath)), defaultRegistry());
     if (!validation.ok) {
       process.stderr.write(`${JSON.stringify({ ok: false, error: { code: "validation", issues: validation.issues } }, null, 2)}
 `);
@@ -16604,7 +17013,7 @@ var setPromptCommand = defineCommand88({
 
 // src/commands/canvas/validate.ts
 import { readFile as readFile8 } from "fs/promises";
-import path11 from "path";
+import path13 from "path";
 import { defineCommand as defineCommand89 } from "citty";
 var validateCommand = defineCommand89({
   meta: {
@@ -16613,7 +17022,7 @@ var validateCommand = defineCommand89({
   },
   args: { file: { type: "positional", required: true, description: "Path to canvas JSON" } },
   async run({ args }) {
-    const filePath = path11.resolve(String(args.file));
+    const filePath = path13.resolve(String(args.file));
     const raw = await readFile8(filePath, "utf8");
     let parsed;
     try {
@@ -16624,7 +17033,7 @@ var validateCommand = defineCommand89({
 `);
       process.exit(2);
     }
-    parsed = resolveRelativeCanvasPaths(parsed, path11.dirname(filePath));
+    parsed = resolveRelativeCanvasPaths(parsed, path13.dirname(filePath));
     const result = await validateCanvasDeep(parsed, defaultRegistry());
     if (!result.ok) {
       process.stderr.write(`${JSON.stringify({ ok: false, issues: result.issues }, null, 2)}
@@ -16638,7 +17047,8 @@ var validateCommand = defineCommand89({
           ok: true,
           total_nodes: result.canvas.nodes.length,
           estimated_credits: result.estimatedCredits,
-          cost_preview: result.perNodeCredits ?? []
+          cost_preview: result.perNodeCredits ?? [],
+          warnings: result.warnings ?? []
         },
         null,
         2
@@ -16760,6 +17170,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
     }
   }
 });
@@ -16769,6 +17189,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;
@@ -16799,7 +17226,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 = defineCommand91({
@@ -16815,6 +17246,16 @@ var publishCommand = defineCommand91({
       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 }) => {
@@ -16833,7 +17274,9 @@ var publishCommand = defineCommand91({
         file,
         title,
         context: args.context,
-        sourceReferenceUrl: args.sourceReferenceUrl
+        sourceReferenceUrl: args.sourceReferenceUrl,
+        slug: args.slug,
+        runId: args.runId
       });
       writeJson({ ok: true, data });
     } catch (err) {
@@ -17731,9 +18174,9 @@ async function readImageBuffer(pathOrUrl) {
   }
   return readFile10(pathOrUrl);
 }
-async function isDirectory(path12) {
+async function isDirectory(path14) {
   try {
-    const s = await stat2(path12);
+    const s = await stat2(path14);
     return s.isDirectory();
   } catch {
     return false;