@koda-sl/baker-cli 0.68.0 → 0.71.2

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   ELEVENLABS_MAX_MUSIC_LENGTH_MS,
+  IMAGE_GENERATE_MODELS,
   MODEL_REGISTRY,
   SEEDANCE_DURATIONS,
   ValidationError,
@@ -8,10 +9,10 @@ import {
   defaultRegistry,
   generateCatalog,
   validateCanvasDeep
-} from "./chunk-K6LHXCKD.js";
+} from "./chunk-JIDZ37KG.js";
 
 // src/cli.ts
-import { defineCommand as defineCommand136, runMain } from "citty";
+import { defineCommand as defineCommand138, runMain } from "citty";
 
 // src/commands/actions/index.ts
 import { defineCommand as defineCommand12 } from "citty";
@@ -146,9 +147,9 @@ async function handleResponse(response) {
     throw new ApiError("INTERNAL_ERROR", "Failed to parse API response as JSON");
   }
 }
-async function apiGet(path6, params) {
+async function apiGet(path7, params) {
   const env = getEnv();
-  const url = new URL(path6, env.BAKER_API_URL);
+  const url = new URL(path7, env.BAKER_API_URL);
   if (params) {
     const clean = sanitizeParams(params);
     for (const [key, value] of Object.entries(clean)) {
@@ -173,12 +174,12 @@ async function apiGet(path6, params) {
   }
   return handleResponse(response);
 }
-async function apiPost(path6, body, opts) {
+async function apiPost(path7, body, opts) {
   const env = getEnv();
   const timeoutMs = opts?.timeoutMs ?? 6e4;
   let response;
   try {
-    response = await fetchWithRateLimitRetry(new URL(path6, env.BAKER_API_URL).toString(), {
+    response = await fetchWithRateLimitRetry(new URL(path7, env.BAKER_API_URL).toString(), {
       method: "POST",
       headers: {
         Authorization: `Bearer ${env.BAKER_API_KEY}`,
@@ -917,31 +918,31 @@ function cachePath(category, key) {
   return join(dir, `${hashKey(key)}.json`);
 }
 function cacheGet(category, key) {
-  const path6 = cachePath(category, key);
-  if (!existsSync(path6)) {
+  const path7 = cachePath(category, key);
+  if (!existsSync(path7)) {
     return null;
   }
   try {
-    const raw = readFileSync(path6, "utf-8");
+    const raw = readFileSync(path7, "utf-8");
     const entry = JSON.parse(raw);
     if (entry.expiresAt < Date.now()) {
-      rmSync(path6, { force: true });
+      rmSync(path7, { force: true });
       return null;
     }
     return entry;
   } catch {
-    rmSync(path6, { force: true });
+    rmSync(path7, { force: true });
     return null;
   }
 }
 function cacheSet(category, key, data, ttlMs, fields) {
-  const path6 = cachePath(category, key);
+  const path7 = cachePath(category, key);
   const entry = {
     expiresAt: Date.now() + ttlMs,
     data,
     fields
   };
-  writeFileSync(path6, JSON.stringify(entry), "utf-8");
+  writeFileSync(path7, JSON.stringify(entry), "utf-8");
 }
 var HOUR = 60 * 60 * 1e3;
 var MINUTE = 60 * 1e3;
@@ -7713,6 +7714,24 @@ async function probeDuration(filePath) {
 import { readFile as readFile2 } from "fs/promises";
 import path2 from "path";
 import { defineCommand as defineCommand74 } from "citty";
+
+// src/commands/canvas/placeholders.ts
+function unsuppliedPlaceholderAssets(canvas) {
+  const nodes = canvas?.nodes;
+  if (!Array.isArray(nodes)) return [];
+  const out = [];
+  for (const n of nodes) {
+    const node = n;
+    if (node?.type !== "ingest") continue;
+    const params = node.params;
+    if (params?.source === "path" && typeof params.path === "string" && params.path.includes("[TODO")) {
+      out.push({ node: String(node.id ?? "?"), placeholder: params.path });
+    }
+  }
+  return out;
+}
+
+// src/commands/canvas/run.ts
 var runCommand = defineCommand74({
   meta: { name: "run", description: "Validate and execute a canvas JSON file." },
   args: {
@@ -7734,6 +7753,25 @@ var runCommand = defineCommand74({
 `);
       process.exit(2);
     }
+    const pending = unsuppliedPlaceholderAssets(parsed);
+    if (pending.length > 0) {
+      process.stderr.write(
+        `${JSON.stringify(
+          {
+            ok: false,
+            error: {
+              code: "unsupplied_assets",
+              message: "This canvas still has placeholder asset slots \u2014 supply a real image (or video) at each before running. Each `el_*` ingest is a [TODO] you fill with the real logo/subject/product, then re-run.",
+              assets: pending
+            }
+          },
+          null,
+          2
+        )}
+`
+      );
+      process.exit(2);
+    }
     const engine = createEngineFromEnv({
       cacheDir: args["cache-dir"] ? String(args["cache-dir"]) : void 0,
       outputsDir: args["outputs-dir"] ? String(args["outputs-dir"]) : void 0,
@@ -8191,7 +8229,7 @@ var scaffoldStaticAdCommand = defineCommand75({
 
 // src/commands/canvas/scaffold-video.ts
 import { cp, mkdir, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 import { defineCommand as defineCommand76 } from "citty";
 
 // src/engine/scaffold/video.ts
@@ -8199,7 +8237,19 @@ import { z as z3 } from "zod";
 var FIXED_TTS_MODEL = "elevenlabs/eleven_v3";
 var FIXED_SFX_MODEL = "elevenlabs/eleven_text_to_sound_v2";
 var FIXED_MUSIC_MODEL = "elevenlabs/music-v1";
+var FIXED_LIPSYNC_MODEL = "fal/veed-lipsync";
 var MUSIC_BED_GAIN_DB = -12;
+var NARRATOR_SPEAKERS = /* @__PURE__ */ new Set([
+  "voiceover",
+  "voice_over",
+  "narrator",
+  "narration",
+  "vo",
+  "announcer",
+  "off_screen",
+  "offscreen",
+  "off-screen"
+]);
 var SHARED_ASPECT_RATIOS = /* @__PURE__ */ new Set(["1:1", "16:9", "9:16", "4:3", "3:4", "21:9"]);
 var EDGES = ["start", "end"];
 function snapToSeedance(durationS) {
@@ -8215,11 +8265,39 @@ function snapToSeedance(durationS) {
   }
   return best;
 }
+function ceilToSeedance(durationS) {
+  const max = SEEDANCE_DURATIONS[SEEDANCE_DURATIONS.length - 1];
+  if (!Number.isFinite(durationS) || durationS <= 0) return SEEDANCE_DURATIONS[0];
+  for (const d of SEEDANCE_DURATIONS) if (d >= durationS) return d;
+  return max;
+}
+function sceneDurationS(scene) {
+  const raw = scene.duration_s ?? (scene.end_s != null && scene.start_s != null ? scene.end_s - scene.start_s : 5);
+  const max = SEEDANCE_DURATIONS[SEEDANCE_DURATIONS.length - 1];
+  return Math.min(Math.max(raw, 0.5), max);
+}
+function trimArgs(durationS) {
+  return [
+    "-i",
+    "{{in.clip}}",
+    "-t",
+    durationS.toFixed(3),
+    "-an",
+    "-c:v",
+    "libx264",
+    "-pix_fmt",
+    "yuv420p",
+    "{{out.video}}"
+  ];
+}
 var FrameAsset = z3.object({ url: z3.string().optional() }).loose().optional();
 var DialogueLine = z3.object({
   speaker: z3.string().optional(),
   line: z3.string().optional(),
+  // Absolute seconds on the source timeline (the deconstruct emits both).
   start_s: z3.number().optional(),
+  end_s: z3.number().optional(),
+  delivery: z3.string().optional(),
   voice_description: z3.string().optional()
 }).loose();
 var Sfx = z3.object({
@@ -8259,7 +8337,12 @@ var VideoBlueprint = z3.object({
       identified_track: z3.object({ title: z3.string().optional(), artist: z3.string().optional() }).loose().nullish()
     }).loose().optional(),
     cast: z3.array(z3.object({ id: z3.string().optional(), description: z3.string().optional() }).loose()).optional(),
-    voiceover: z3.object({ voice_description: z3.string().optional() }).loose().optional()
+    voiceover: z3.object({
+      // on_camera | mixed → mouths are on screen (lip-sync candidates);
+      // voiceover | none → narration over the picture (no lip-sync).
+      mode: z3.string().optional(),
+      voice_description: z3.string().optional()
+    }).loose().optional()
   }).loose().optional(),
   scenes: z3.array(Scene).min(1)
 }).loose();
@@ -8391,7 +8474,17 @@ function buildFramePrompt(edge, sceneIndex, framePrompt, present, hasAnchor) {
   ].join("\n");
   const description = framePrompt?.trim() || `the ${edge} frame of scene ${sceneIndex + 1} \u2014 describe the full composition, subjects, setting, action, lighting, and palette here. (Edit this line to change ONLY this frame.)`;
   return [
-    `Render the ${EDGE} frame of scene ${sceneIndex + 1} as a single still image. This prompt is self-contained and edit-per-frame: change the FRAME DESCRIPTION below to alter ONLY this frame. EXCLUDE all overlay text, captions, stickers, and watermarks \u2014 they are composited on top later.`,
+    `Render the ${EDGE} frame of scene ${sceneIndex + 1} as a single still image. This prompt is self-contained and edit-per-frame: change the FRAME DESCRIPTION below to alter ONLY this frame.`,
+    "",
+    "CRITICAL \u2014 RENDER A CLEAN PLATE WITH ZERO TEXT OR GRAPHICS:",
+    "This frame is a background plate. ALL words, captions, headlines, lower-third bars,",
+    "news tickers/crawls, chyrons, on-screen logos/wordmarks, station bugs, watermarks,",
+    "subtitles, UI and numbers are added afterwards as a separate HTML layer. Render NONE",
+    "of them \u2014 no legible text anywhere in the image, not even in the background, on the",
+    "news desk, on screens, or as part of a 'broadcast look'. If a reference image (a logo,",
+    "a desk, a studio) contains any text or graphics, DO NOT reproduce that text \u2014 render",
+    "the subject/scene only, with blank surfaces where text would be. Imperfect/garbled",
+    "letterforms are the worst outcome; leave those areas clean.",
     "",
     "REFERENCE IMAGES (in the order provided):",
     legend,
@@ -8399,7 +8492,7 @@ function buildFramePrompt(edge, sceneIndex, framePrompt, present, hasAnchor) {
     "FRAME DESCRIPTION (this frame's editable prompt):",
     description,
     "",
-    "Keep every recurring element identical to its reference image across all frames. Use the GLOBAL STYLE REFERENCE only for shared cast identity, palette, typography mood, and aspect ratio \u2014 do NOT copy another scene's composition from it; this frame's content is the FRAME DESCRIPTION above.",
+    "Keep every recurring element identical to its reference image across all frames. Use the GLOBAL STYLE REFERENCE only for shared cast identity, palette, typography mood, and aspect ratio \u2014 do NOT copy another scene's composition from it; this frame's content is the FRAME DESCRIPTION above. Again: NO rendered text or graphic overlays \u2014 clean plate only.",
     "",
     "GLOBAL STYLE REFERENCE (shared across frames; not this frame's content):",
     "{{target_blueprint}}"
@@ -8450,7 +8543,7 @@ function buildSeedancePrompt(scene, sceneIndex, present) {
   if (transcript) parts.push(`Transcript: ${transcript}`);
   return parts.join("\n");
 }
-function buildSceneVisuals(blueprint, slots, opts, nodes) {
+function buildSceneVisuals(blueprint, slots, opts, nodes, sceneTurns) {
   const ar = aspectRatioParam(blueprint);
   const reuse = opts.frames === "reuse";
   const clipRefs = [];
@@ -8472,10 +8565,11 @@ function buildSceneVisuals(blueprint, slots, opts, nodes) {
       ctx,
       nodes
     );
+    const dur = sceneDurationS(scene);
     const clipParams = {
       model: opts.videoModel,
       prompt: buildSeedancePrompt(scene, i, slotsForScene(slots, i)),
-      duration: snapToSeedance(scene.duration_s ?? 5)
+      duration: ceilToSeedance(dur)
     };
     if (ar) clipParams.aspect_ratio = ar;
     nodes.push({
@@ -8484,7 +8578,29 @@ function buildSceneVisuals(blueprint, slots, opts, nodes) {
       inputs: { first_frame: firstFrame, last_frame: lastFrame },
       params: clipParams
     });
-    clipRefs.push(`$ref:s${i}_clip.video`);
+    let base = `$ref:s${i}_clip.video`;
+    const onCam = (sceneTurns.get(i) ?? []).filter((t) => t.onCamera);
+    const solo = onCam.length === 1 ? onCam[0] : void 0;
+    if (solo) {
+      nodes.push({
+        id: `s${i}_lipsync`,
+        type: "video_lipsync",
+        inputs: { video: base, audio: solo.audioRef },
+        params: { model: FIXED_LIPSYNC_MODEL }
+      });
+      base = `$ref:s${i}_lipsync.video`;
+    }
+    if (ceilToSeedance(dur) === dur) {
+      clipRefs.push(base);
+    } else {
+      nodes.push({
+        id: `s${i}_trim`,
+        type: "ffmpeg",
+        inputs: { clip: base },
+        params: { args: trimArgs(dur), outputs: { video: { kind: "video", ext: "mp4" } } }
+      });
+      clipRefs.push(`$ref:s${i}_trim.video`);
+    }
   });
   return clipRefs;
 }
@@ -8497,8 +8613,21 @@ function musicBedPrompt(blueprint, musicPrompt) {
 
 Reference vibe: the original used "${title}"${by} (identified via AudD). Match its mood, tempo, and energy with ORIGINAL music \u2014 do not reproduce the track.`;
 }
-function buildAudio(blueprint, nodes) {
+function onCameraDialogue(blueprint) {
+  const mode = blueprint.global?.voiceover?.mode;
+  return mode !== "voiceover" && mode !== "none";
+}
+var castIdSet = (blueprint) => new Set((blueprint.global?.cast ?? []).map((c) => c.id).filter((id) => Boolean(id)));
+function isOnCameraSpeaker(speaker, casts, cameraOn) {
+  if (!cameraOn) return false;
+  if (NARRATOR_SPEAKERS.has(speaker.toLowerCase())) return false;
+  return casts.has(speaker);
+}
+function buildDialogue(blueprint, nodes) {
   const tracks = [];
+  const sceneTurns = /* @__PURE__ */ new Map();
+  const casts = castIdSet(blueprint);
+  const cameraOn = onCameraDialogue(blueprint);
   const voiceNodeBySpeaker = /* @__PURE__ */ new Map();
   const speakerDescription = (speaker) => {
     for (const scene of blueprint.scenes) {
@@ -8517,41 +8646,62 @@ function buildAudio(blueprint, nodes) {
     voiceNodeBySpeaker.set(speaker, id);
     return id;
   };
-  const scriptBySpeaker = /* @__PURE__ */ new Map();
-  const orderedSpeakers = [];
-  for (const scene of blueprint.scenes) {
-    for (const line of scene.dialogue ?? []) {
-      if (!line.line) continue;
-      const speaker = line.speaker ?? "voiceover";
-      const start = line.start_s ?? scene.start_s ?? 0;
-      const existing = scriptBySpeaker.get(speaker);
-      if (existing) {
-        existing.lines.push(line.line);
-        existing.start = Math.min(existing.start, start);
-      } else {
-        scriptBySpeaker.set(speaker, { lines: [line.line], start });
-        orderedSpeakers.push(speaker);
-      }
-    }
-  }
   const usedVoIds = /* @__PURE__ */ new Set();
-  orderedSpeakers.forEach((speaker, idx) => {
-    const script = scriptBySpeaker.get(speaker);
-    if (!script) return;
-    const voiceNode = ensureVoiceNode(speaker);
-    let id = sanitizeId2(`vo_${speaker}`, `vo_${idx}`);
-    while (usedVoIds.has(id)) id = `${id}_${idx}`;
-    usedVoIds.add(id);
-    nodes.push({
-      id,
-      type: "tts",
-      inputs: { voice_ref: `$ref:${voiceNode}.voice_id` },
-      // Join lines with a space: each line keeps its own terminal punctuation, so
-      // sentence boundaries (and the pauses they imply) survive into one read.
-      params: { model: FIXED_TTS_MODEL, text: script.lines.join(" "), voice: "{{voice_ref}}" }
+  blueprint.scenes.forEach((scene, sceneIndex) => {
+    const lines = (scene.dialogue ?? []).filter((l) => Boolean(l.line?.trim())).slice().sort((a, b) => (a.start_s ?? 0) - (b.start_s ?? 0));
+    if (lines.length === 0) return;
+    const groups = [];
+    for (const line of lines) {
+      const speaker = line.speaker ?? "voiceover";
+      const last = groups[groups.length - 1];
+      if (last && last.speaker === speaker) last.lines.push(line);
+      else groups.push({ speaker, lines: [line] });
+    }
+    const list = [];
+    groups.forEach((group, gi) => {
+      const first = group.lines[0];
+      const last = group.lines[group.lines.length - 1];
+      if (!first || !last) return;
+      const start = first.start_s ?? scene.start_s ?? 0;
+      const end = last.end_s ?? last.start_s ?? scene.end_s ?? start;
+      const voiceNode = ensureVoiceNode(group.speaker);
+      let id = sanitizeId2(`vo_s${sceneIndex}_${group.speaker}`, `vo_${sceneIndex}_${gi}`);
+      if (usedVoIds.has(id)) {
+        let n = 2;
+        while (usedVoIds.has(`${id}_${n}`)) n++;
+        id = `${id}_${n}`;
+      }
+      usedVoIds.add(id);
+      nodes.push({
+        id,
+        type: "tts",
+        inputs: { voice_ref: `$ref:${voiceNode}.voice_id` },
+        // Lines join with a space; each keeps its terminal punctuation so eleven_v3
+        // reads the sentence boundaries (and their pauses) within the one turn.
+        params: {
+          model: FIXED_TTS_MODEL,
+          text: group.lines.map((l) => l.line.trim()).join(" "),
+          voice: "{{voice_ref}}"
+        }
+      });
+      const turn = {
+        sceneIndex,
+        speaker: group.speaker,
+        onCamera: isOnCameraSpeaker(group.speaker, casts, cameraOn),
+        start_s: start,
+        end_s: end,
+        ttsId: id,
+        audioRef: `$ref:${id}.audio`
+      };
+      list.push(turn);
+      tracks.push({ slot: id, ref: turn.audioRef, start_s: start, end_s: end, kind: "vo" });
     });
-    tracks.push({ slot: id, ref: `$ref:${id}.audio`, start_s: script.start });
+    sceneTurns.set(sceneIndex, list);
   });
+  return { tracks, sceneTurns };
+}
+function buildSfxMusic(blueprint, nodes) {
+  const tracks = [];
   blueprint.scenes.forEach((scene, i) => {
     (scene.sfx ?? []).forEach((sfx, k) => {
       const text = sfx.sound_effect_prompt ?? sfx.description;
@@ -8560,7 +8710,12 @@ function buildAudio(blueprint, nodes) {
       const params = { model: FIXED_SFX_MODEL, text };
       if (typeof sfx.duration_s === "number") params.duration_seconds = Math.min(Math.max(sfx.duration_s, 0.5), 30);
       nodes.push({ id, type: "sound_effect", params });
-      tracks.push({ slot: `sfx_s${i}_${k}`, ref: `$ref:${id}.audio`, start_s: sfx.at_s ?? scene.start_s ?? 0 });
+      tracks.push({
+        slot: `sfx_s${i}_${k}`,
+        ref: `$ref:${id}.audio`,
+        start_s: sfx.at_s ?? scene.start_s ?? 0,
+        kind: "sfx"
+      });
     });
   });
   const musicPrompt = blueprint.global?.music?.music_prompt;
@@ -8572,10 +8727,90 @@ function buildAudio(blueprint, nodes) {
       type: "music",
       params: { model: FIXED_MUSIC_MODEL, prompt: musicBedPrompt(blueprint, musicPrompt), music_length_ms: musicMs }
     });
-    tracks.unshift({ slot: "music", ref: "$ref:music_bed.audio", start_s: 0, gain_db: MUSIC_BED_GAIN_DB });
+    tracks.push({ slot: "music", ref: "$ref:music_bed.audio", start_s: 0, gain_db: MUSIC_BED_GAIN_DB, kind: "music" });
   }
   return tracks;
 }
+var OverlayStyle = z3.object({ color_hex: z3.string().optional(), background: z3.string().optional(), size: z3.string().optional() }).loose();
+var Overlay = z3.object({
+  text: z3.string().optional(),
+  appears_at_s: z3.number().optional(),
+  duration_s: z3.number().optional(),
+  position: z3.string().optional(),
+  role: z3.string().optional(),
+  animation: z3.string().optional(),
+  animation_detail: z3.string().optional(),
+  style: OverlayStyle.optional()
+}).loose();
+var FloatingElement = z3.object({
+  kind: z3.string().optional(),
+  description: z3.string().optional(),
+  brand_name: z3.string().nullish(),
+  what_it_represents: z3.string().optional(),
+  appears_at_s: z3.number().optional(),
+  duration_s: z3.number().optional(),
+  position: z3.string().optional()
+}).loose();
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function commentSafe(s) {
+  return escapeHtml(s).replace(/-{2,}/g, "\u2013");
+}
+var SUPPORTED_ANIMS = /* @__PURE__ */ new Set(["fade", "slide_up", "slide_down", "pop"]);
+function normalizeAnim(animation) {
+  if (!animation || animation === "none") return void 0;
+  const mapped = animation === "slide" ? "slide_up" : animation;
+  return SUPPORTED_ANIMS.has(mapped) ? mapped : void 0;
+}
+function positionClass(position) {
+  const p = (position ?? "bottom_center").toLowerCase().replace(/[^a-z]+/g, "-");
+  return `pos-${p}`;
+}
+function overlayElement(ov, sceneStart) {
+  if (!ov.text?.trim()) return "";
+  const at = ov.appears_at_s ?? sceneStart;
+  const dur = ov.duration_s ?? 2.5;
+  const role = ov.role ? ` data-role="${escapeHtml(ov.role)}"` : "";
+  const normAnim = normalizeAnim(ov.animation);
+  const anim = normAnim ? ` data-anim="${normAnim}"` : "";
+  const detail = ov.animation_detail ? ` data-anim-detail="${escapeHtml(ov.animation_detail)}"` : "";
+  return `<div class="ov ${positionClass(ov.position)}" data-start="${at}" data-dur="${dur}"${role}${anim}${detail}>${escapeHtml(ov.text.trim())}</div>`;
+}
+function floatingStub(fe, sceneStart) {
+  const at = fe.appears_at_s ?? sceneStart;
+  const dur = fe.duration_s ?? 2.5;
+  const kind = commentSafe(fe.kind ?? "element");
+  const label = commentSafe(fe.brand_name || fe.what_it_represents || fe.description || fe.kind || "element");
+  const slug = (fe.kind ?? "element").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "element";
+  return [
+    `<!-- ${kind}: ${label} @ ${at}s for ${dur}s (${positionClass(fe.position)}). Drop an image in this dir and uncomment:`,
+    `<img class="ov ${positionClass(fe.position)}" src="your-${slug}.png" data-start="${at}" data-dur="${dur}" alt="" /> -->`
+  ].join("\n");
+}
+function buildOverlayHtml(input) {
+  const blueprint = VideoBlueprint.parse(input);
+  const blocks = [
+    [
+      "<!-- \u2B07 OVERLAY LAYER \u2014 this is YOUR HTML to paint. The reference's overlays are",
+      "     seeded below as plain elements (text + position class + data-start/data-dur).",
+      "     Restyle freely in <style>, regroup, animate, swap a logo placeholder for a",
+      "     real <img> you drop in this dir. The runtime only shows/hides by timestamp;",
+      "     it makes NO styling decisions. Positions: edit the .pos-* classes or add your own. -->"
+    ].join("\n")
+  ];
+  for (const scene of blueprint.scenes) {
+    const sceneStart = scene.start_s ?? 0;
+    const overlays = z3.array(Overlay).safeParse(scene.overlays ?? []);
+    const floats = z3.array(FloatingElement).safeParse(scene.floating_elements ?? []);
+    const parts = [
+      ...overlays.success ? overlays.data.map((ov) => overlayElement(ov, sceneStart)) : [],
+      ...floats.success ? floats.data.map((fe) => floatingStub(fe, sceneStart)) : []
+    ].filter(Boolean);
+    if (parts.length > 0) blocks.push(parts.join("\n"));
+  }
+  return blocks.join("\n\n");
+}
 function lastSceneEnd(blueprint) {
   let end = 0;
   for (const s of blueprint.scenes) end = Math.max(end, s.end_s ?? 0);
@@ -8607,7 +8842,8 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
       params: { source: "path", path: todoPath2(elements[i], slot.label), expect: "image" }
     });
   });
-  const clipRefs = buildSceneVisuals(blueprint, slots, opts, nodes);
+  const { tracks: voTracks, sceneTurns } = buildDialogue(blueprint, nodes);
+  const clipRefs = buildSceneVisuals(blueprint, slots, opts, nodes, sceneTurns);
   const concatInputs = {};
   clipRefs.forEach((ref, i) => {
     concatInputs[`c${i}`] = ref;
@@ -8627,12 +8863,12 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
       id: "overlaid",
       type: "hyperframe_render",
       inputs: { background: videoRef },
-      params: { composition: opts.overlayCompositionPath, overlays, floating_elements: floating }
+      params: { composition: opts.overlayCompositionPath }
     });
     videoRef = "$ref:overlaid.video";
     videoNode = "overlaid";
   }
-  const tracks = buildAudio(blueprint, nodes);
+  const tracks = [...voTracks, ...buildSfxMusic(blueprint, nodes)];
   if (tracks.length > 0) {
     const mixInputs = {};
     for (const t of tracks) mixInputs[t.slot] = t.ref;
@@ -8665,8 +8901,18 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
           "1:a:0",
           "-c:v",
           "copy",
+          // The raw mix is a quiet mono track (tts + ducked bed), which reads as
+          // "no sound" in casual players. Normalize integrated loudness to the
+          // social/broadcast target (-14 LUFS, -1.5 dBTP) and upmix to stereo so
+          // every rendered ad is loud and plays everywhere.
+          "-af",
+          "loudnorm=I=-14:TP=-1.5:LRA=11,aformat=channel_layouts=stereo",
           "-c:a",
           "aac",
+          "-b:a",
+          "192k",
+          "-ar",
+          "48000",
           "-shortest",
           "{{out.video}}"
         ],
@@ -8680,43 +8926,69 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
     metadata: {
       name: "video reproduction",
       description: VIDEO_GUIDE,
-      todo: buildVideoTodo(videoReport(input, elementsInput), overlays.length, floating.length, opts)
+      todo: buildVideoTodo(videoReport(input, elementsInput), overlays.length, floating.length, 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, sceneTurns)
     },
     nodes,
     output: { node: videoNode, output: "video" }
   };
 }
+function buildVideoMeta(blueprint, sceneTurns) {
+  const vo_segments = [];
+  const talking_scenes = [];
+  for (const [scene, turns] of [...sceneTurns.entries()].sort((a, b) => a[0] - b[0])) {
+    for (const t of turns) {
+      vo_segments.push({ slot: t.ttsId, start_s: t.start_s, end_s: t.end_s, scene, speaker: t.speaker });
+    }
+    if (turns.filter((t) => t.onCamera).length === 1) {
+      talking_scenes.push({ scene, lipsync_node: `s${scene}_lipsync` });
+    }
+  }
+  return {
+    duration_s: blueprint.source?.duration_s ?? lastSceneEnd(blueprint),
+    vo_segments,
+    talking_scenes
+  };
+}
 var VIDEO_GUIDE = [
-  "Scaffolded by `baker canvas scaffold-video` \u2014 a runnable reproduction of your reference video. Each scene is two AI-generated boundary frames (start/end) animated into a clip, concatenated, overlaid with timed text, and mixed with voiceover + SFX + music. Edit it, supply the real assets, then run.",
+  "Scaffolded by `baker canvas scaffold-video` \u2014 a runnable reproduction of your reference video. Per scene: two AI-generated CLEAN-PLATE frames (no baked text) \u2192 a clip \u2192 trimmed to the real scene length so the picture stays on the audio timeline \u2192 optional lip-sync \u2192 concatenated. On-screen text is a separate HTML layer you paint; audio is sequenced voiceover + SFX + a ducked music bed, normalized stereo. It is a DRAFT: edit it, supply the real assets, then validate and run.",
   "",
   "WHAT TO DO NEXT:",
   "1. Edit each frame's prompt IN PLACE. Every `s<i>_start` / `s<i>_end` node has its OWN self-contained `params.prompt` (the FRAME DESCRIPTION) \u2014 editing one changes only that frame. Rewrite the cast, product, claims, palette into the ad you want.",
-  "2. Drop ONE real source image at each `el_*` ingest `[TODO]` path. Each recurring element (person/product/logo) is reused across every frame it appears in, so the same identity stays consistent.",
-  "3. Confirm the `voice_select` casting (one per speaker). The voiceover is ONE continuous `tts` per speaker \u2014 punctuation, ALL-CAPS, and spacing are read verbatim by eleven_v3 for emphasis/pauses, so edit `params.text` to shape delivery.",
-  "4. Text overlays are composited on top (not baked into frames) by the `overlaid` node \u2014 edit the `overlays` array there. For on-brand type, drop `brand-bold.otf` / `brand-regular.otf` into the `video-overlay-composition/` dir (referenced via @font-face); otherwise a system font is used. You don't always need text \u2014 it's often cleaner to overlay it than bake it in.",
-  "5. `baker canvas validate` then `baker canvas run`. Running generates many billed image/video/audio assets \u2014 it is not free.",
+  "2. Drop ONE real source image at each `el_*` ingest `[TODO]` path. Each recurring element (person/product/logo) is reused across every frame it appears in, so the same identity stays consistent. `baker canvas run` REFUSES to start until every `[TODO]` slot holds a real source \u2014 so this is mandatory, not optional.",
+  "3. Confirm the `voice_select` casting (one per speaker). Voiceover is SEQUENCED: each contiguous same-speaker turn is its own `tts` placed at its real start, so dialogue alternates instead of stacking. Edit a turn's `params.text` (punctuation / ALL-CAPS / line breaks are read verbatim by eleven_v3 for emphasis and pauses) to shape delivery; re-author the words to be TRUE for your brand.",
+  "4. Lip-sync: scenes with a single on-camera speaker route their clip through `video_lipsync` (~20 cr each) so the mouth matches the line. Two-speaker scenes are left un-synced \u2014 split them or pick a primary speaker if you want sync. Drop the node to skip.",
+  "5. Overlays are REAL HTML you paint. Open `video-overlay-composition/index.html`: the reference's overlays are seeded inside `#overlay-root` as plain elements (text + a `.pos-*` class + `data-start`/`data-dur`). Restyle the CSS freely \u2014 build lower-thirds, a ticker, whatever the look needs \u2014 and replace a logo placeholder with a real `<img>` you drop in that dir. The runtime only shows/hides by timestamp; it makes no styling decisions. Drop `brand-bold.otf` / `brand-regular.otf` there for on-brand type.",
+  "6. `baker canvas validate` (proves audio/lip-sync timing for free) then `baker canvas run` (generates many billed image/video/audio assets \u2014 not free).",
   "",
   "Tip: `prompt.json` is the deconstruction provenance + the demoted GLOBAL STYLE REFERENCE each frame reads for shared palette/cast cohesion. It is NOT the per-frame editing surface \u2014 the frame nodes are."
 ].join("\n");
 function buildVideoTodo(report, overlayCount, floatingCount, opts) {
   return {
-    edit_frames_in_place: "Each s<i>_start / s<i>_end node has its own editable params.prompt (FRAME DESCRIPTION). Edit per frame; the blueprint is only a shared style reference.",
+    edit_frames_in_place: "Each s<i>_start / s<i>_end node has its own editable params.prompt (FRAME DESCRIPTION). Edit per frame; the blueprint is only a shared style reference. Frames are CLEAN PLATES \u2014 they render no on-screen text; all text is the overlay HTML layer.",
     frames_mode: opts.frames ?? "generate",
+    assets_required: "MANDATORY: drop a real image at every el_* [TODO] ingest before running \u2014 `baker canvas run` refuses to start (and bills nothing) until each placeholder holds a real source.",
     recurring_elements_to_supply: report.elements,
+    text_strategy: "Decide per ad: text is either baked by the generated creative OR painted via the overlay HTML \u2014 not both. Default here is clean text-free frames + the HTML overlay layer (video-overlay-composition/index.html) as the single text source, which you fully control.",
+    timeline: "Automatic: each clip is generated at >= its scene length then trimmed back to the real scene duration, so the concatenated picture stays on the same timeline as the absolute-timed audio (this is what makes the lips line up). You don't manage it.",
     voices_to_confirm: report.dialogue.map((d) => ({
       scene: d.scene,
       speaker: d.speaker,
       voice_description: d.voice_description,
       line: d.line
     })),
-    voiceover_note: "One continuous tts per speaker; same voice locked via voice_select.voice_id. Use punctuation / ALL CAPS / line breaks in params.text for emphasis and pacing (read verbatim).",
+    voiceover_note: "Sequenced: one tts per contiguous same-speaker TURN, placed at its real start_s so turns alternate (no parallel monologues); same voice locked via voice_select.voice_id. Edit a turn's params.text (punctuation / ALL CAPS / line breaks read verbatim) to shape delivery.",
+    lip_sync_note: "Scenes with a single on-camera speaker route their clip through video_lipsync (~20 cr each) so the mouth matches the line. Two-speaker scenes are left un-synced (one track can't drive two faces) \u2014 split or pick a primary. `baker canvas validate` checks every talking scene is synced.",
     text_overlays: {
       count: overlayCount,
-      note: "Composited by the `overlaid` node, animated per the blueprint (fade/pop/slide/typewriter/karaoke). Edit the `overlays` array. Drop brand-*.otf into video-overlay-composition/ for on-brand type."
+      note: "Seeded as editable HTML inside `#overlay-root` in video-overlay-composition/index.html (text + a .pos-* class + data-start/data-dur). PAINT it: restyle the CSS, build lower-thirds/tickers, drop brand-*.otf for on-brand type. The runtime only shows/hides by timestamp."
     },
     floating_elements: {
       count: floatingCount,
-      note: floatingCount > 0 ? "Rendered as labeled placeholders. Replace with the real logo/sticker/cutout art (recurring logos are better handled as an el_* element baked into frames)." : "none detected"
+      note: floatingCount > 0 ? "Seeded as labeled placeholders in index.html \u2014 replace each with a real <img> you drop into video-overlay-composition/. Recurring logos are also handled well as an el_* element baked into frames." : "none detected"
     },
     sound_effects: { count: report.sfx_count },
     music: {
@@ -8768,8 +9040,24 @@ function videoReport(input, elementsInput) {
   };
 }
 
+// src/commands/canvas/composition-path.ts
+import { existsSync as existsSync3 } from "fs";
+import path4 from "path";
+function resolveShippedCanvasDir(name, startDir, exists = existsSync3, maxDepth = 8) {
+  const rel = path4.join("canvas", name);
+  let dir = startDir;
+  for (let i = 0; i < maxDepth; i++) {
+    const candidate = path4.join(dir, rel);
+    if (exists(path4.join(candidate, "meta.json"))) return candidate;
+    const parent = path4.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path4.resolve(startDir, "../../../", rel);
+}
+
 // src/commands/canvas/scaffold-video.ts
-var SHIPPED_COMPOSITION_DIR = path4.resolve(import.meta.dirname, "../../../canvas/video-overlay-composition");
+var SHIPPED_COMPOSITION_DIR = resolveShippedCanvasDir("video-overlay-composition", import.meta.dirname);
 function resolveModel2(kind, preferred) {
   const ids = Object.keys(MODEL_REGISTRY[kind]);
   return ids.includes(preferred) ? preferred : ids[0] ?? preferred;
@@ -8890,13 +9178,19 @@ var scaffoldVideoCommand = defineCommand76({
     "video-model": { type: "string", description: "Override the video_generate model id for clips" }
   },
   async run({ args }) {
-    const videoPath = path4.resolve(String(args.file));
-    const base = path4.basename(videoPath, path4.extname(videoPath));
-    const outPath = args.out ? path4.resolve(String(args.out)) : path4.join(path4.dirname(videoPath), `${base}.video.canvas.json`);
-    const outDir = path4.dirname(outPath);
-    const blueprintPath = path4.join(outDir, "prompt.json");
+    const videoPath = path5.resolve(String(args.file));
+    const base = path5.basename(videoPath, path5.extname(videoPath));
+    const outPath = args.out ? path5.resolve(String(args.out)) : path5.join(path5.dirname(videoPath), `${base}.video.canvas.json`);
+    const outDir = path5.dirname(outPath);
+    const blueprintPath = path5.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)) {
+      process.stderr.write(
+        `\u26A0\uFE0F  --max-scenes ${maxScenes} caps the deconstruct: any scenes beyond ${maxScenes} are MERGED away, reducing fidelity (fewer cuts, lost beats). Omit it to reproduce every scene.
+`
+      );
+    }
     const { deconstructModel, selectModel, imageModel, videoModel } = resolveModels2(args);
     const analysisCanvas = buildAnalysisCanvas(videoPath, deconstructModel, selectModel, {
       maxScenes: Number.isFinite(maxScenes) ? maxScenes : void 0,
@@ -8908,8 +9202,19 @@ var scaffoldVideoCommand = defineCommand76({
     const annotated = annotateBlueprintWithElements(blueprint, elements);
     await writeFile2(blueprintPath, `${JSON.stringify(annotated, null, 2)}
 `, "utf8");
-    const compositionDest = path4.join(outDir, "video-overlay-composition");
+    const compositionDest = path5.join(outDir, "video-overlay-composition");
     await cp(SHIPPED_COMPOSITION_DIR, compositionDest, { recursive: true });
+    const indexPath = path5.join(compositionDest, "index.html");
+    const overlayHtml = buildOverlayHtml(blueprint);
+    const indexHtml = await readFile4(indexPath, "utf8");
+    const injected = indexHtml.replace("<!--OVERLAYS-->", () => overlayHtml);
+    if (injected === indexHtml && overlayHtml.trim()) {
+      fail2(
+        "composition_marker_missing",
+        `video-overlay-composition/index.html is missing the <!--OVERLAYS--> marker \u2014 cannot inject the overlay layer`
+      );
+    }
+    await writeFile2(indexPath, injected, "utf8");
     const opts = {
       imageModel,
       videoModel,
@@ -8952,7 +9257,7 @@ var scaffoldVideoCommand = defineCommand76({
             run_estimated_credits: validation.estimatedCredits
           },
           checklist: {
-            edit_prompt: `Edit ${path4.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 ${path5.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,
@@ -8977,7 +9282,7 @@ var scaffoldVideoCommand = defineCommand76({
 
 // src/commands/canvas/validate.ts
 import { readFile as readFile5 } from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 import { defineCommand as defineCommand77 } from "citty";
 var validateCommand = defineCommand77({
   meta: {
@@ -8986,7 +9291,7 @@ var validateCommand = defineCommand77({
   },
   args: { file: { type: "positional", required: true, description: "Path to canvas JSON" } },
   async run({ args }) {
-    const filePath = path5.resolve(String(args.file));
+    const filePath = path6.resolve(String(args.file));
     const raw = await readFile5(filePath, "utf8");
     let parsed;
     try {
@@ -9221,7 +9526,7 @@ Examples:
 });
 
 // src/commands/ga4/query.ts
-import { appendFileSync as appendFileSync2, existsSync as existsSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import { appendFileSync as appendFileSync2, existsSync as existsSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
 import { resolve as resolve2 } from "path";
 import { defineCommand as defineCommand81 } from "citty";
 
@@ -9295,7 +9600,7 @@ function writeRowsToFile2(filePath, rows, append) {
   const fields = extractFields2(rows);
   const ext = filePath.split(".").pop()?.toLowerCase();
   if (ext === "csv") {
-    if (!append || !existsSync3(filePath)) {
+    if (!append || !existsSync4(filePath)) {
       writeFileSync4(filePath, `${toCsvRow(fields)}
 `, "utf-8");
     }
@@ -9306,12 +9611,12 @@ function writeRowsToFile2(filePath, rows, append) {
     const lines = rows.map((row) => JSON.stringify(row));
     const content = `${lines.join("\n")}
 `;
-    if (append && existsSync3(filePath)) {
+    if (append && existsSync4(filePath)) {
       appendFileSync2(filePath, content, "utf-8");
     } else {
       writeFileSync4(filePath, content, "utf-8");
     }
-  } else if (append && existsSync3(filePath)) {
+  } else if (append && existsSync4(filePath)) {
     const existing = JSON.parse(readFileSync6(filePath, "utf-8"));
     writeFileSync4(filePath, JSON.stringify([...existing, ...rows], null, 2), "utf-8");
   } else {
@@ -9452,7 +9757,7 @@ Examples:
 import { defineCommand as defineCommand86 } from "citty";
 
 // src/commands/gsc/query.ts
-import { appendFileSync as appendFileSync3, existsSync as existsSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
+import { appendFileSync as appendFileSync3, existsSync as existsSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
 import { resolve as resolve3 } from "path";
 import { defineCommand as defineCommand83 } from "citty";
 
@@ -9581,7 +9886,7 @@ function writeRowsToFile3(filePath, rows, append) {
   const fields = extractFields3(rows);
   const ext = filePath.split(".").pop()?.toLowerCase();
   if (ext === "csv") {
-    if (!append || !existsSync4(filePath)) {
+    if (!append || !existsSync5(filePath)) {
       writeFileSync5(filePath, `${toCsvRow(fields)}
 `, "utf-8");
     }
@@ -9591,12 +9896,12 @@ function writeRowsToFile3(filePath, rows, append) {
   } else if (ext === "jsonl") {
     const content = `${rows.map((row) => JSON.stringify(row)).join("\n")}
 `;
-    if (append && existsSync4(filePath)) {
+    if (append && existsSync5(filePath)) {
       appendFileSync3(filePath, content, "utf-8");
     } else {
       writeFileSync5(filePath, content, "utf-8");
     }
-  } else if (append && existsSync4(filePath)) {
+  } else if (append && existsSync5(filePath)) {
     const existing = JSON.parse(readFileSync7(filePath, "utf-8"));
     writeFileSync5(filePath, JSON.stringify([...existing, ...rows], null, 2), "utf-8");
   } else {
@@ -9858,7 +10163,7 @@ Examples:
 });
 
 // src/commands/images/index.ts
-import { defineCommand as defineCommand107 } from "citty";
+import { defineCommand as defineCommand109 } from "citty";
 
 // src/commands/images/crop.ts
 import { defineCommand as defineCommand87 } from "citty";
@@ -9914,9 +10219,9 @@ async function readImageBuffer(pathOrUrl) {
   }
   return readFile6(pathOrUrl);
 }
-async function isDirectory(path6) {
+async function isDirectory(path7) {
   try {
-    const s = await stat2(path6);
+    const s = await stat2(path7);
     return s.isDirectory();
   } catch {
     return false;
@@ -10275,8 +10580,157 @@ var findCommand = defineCommand91({
   }
 });
 
-// src/commands/images/get.ts
+// src/commands/images/generate.ts
+import { readFile as readFile7 } from "fs/promises";
 import { defineCommand as defineCommand92 } from "citty";
+import sharp2 from "sharp";
+var GENERATE_TIMEOUT_MS = 18e4;
+var REFERENCE_MAX_EDGE = 1536;
+var MODEL_LIST = [...IMAGE_GENERATE_MODELS];
+registerSchema({
+  command: "images.generate",
+  description: "Generate an image with AI (OpenRouter image models) and ingest it into the library. Default model openai/gpt-5.4-image-2 \u2014 photo-realistic, cleanest text rendering. Pass --reference with image URLs AND/OR local file paths (brand logo, product shot, Pinterest pin, cropped photo) to ground the generation on real imagery for on-brand, realistic output.",
+  args: {
+    prompt: { type: "string", description: "What to generate", required: true },
+    model: {
+      type: "string",
+      description: `Model (default openai/gpt-5.4-image-2). One of: ${MODEL_LIST.join(", ")}`,
+      required: false,
+      enum: MODEL_LIST
+    },
+    "aspect-ratio": {
+      type: "string",
+      description: "Aspect ratio, e.g. 1:1 (default), 16:9, 9:16, 4:5, 3:2 (Gemini flash also supports 1:4/8:1)",
+      required: false
+    },
+    "image-size": {
+      type: "string",
+      description: "Output resolution: 1K (default) | 2K | 4K (Gemini flash also 0.5K)",
+      required: false
+    },
+    reference: {
+      type: "string",
+      description: "Comma-separated visual references \u2014 each is a public image URL OR a local file path (a sandbox image: brand logo, cropped photo, screenshot). Local files are downscaled and inlined automatically. Grounds output in real imagery; applied in order.",
+      required: false
+    },
+    strength: {
+      type: "number",
+      description: "Recraft v4.1 Pro Vector only: vectorization strength 0-1",
+      required: false
+    },
+    "rgb-colors": {
+      type: "string",
+      description: 'Recraft only: JSON array of [r,g,b] palette triples, e.g. "[[10,10,10],[255,80,0]]"',
+      required: false
+    },
+    "bg-rgb": {
+      type: "string",
+      description: 'Recraft only: JSON [r,g,b] background color, e.g. "[255,255,255]"',
+      required: false
+    },
+    context: {
+      type: "string",
+      description: "Description context hint for the ingested row (overrides the prompt as the describe hint)",
+      required: false
+    }
+  }
+});
+function parseJsonArg(raw, flag) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new ApiError("VALIDATION_ERROR", `--${flag} must be valid JSON (got: ${raw})`);
+  }
+}
+function buildGenerateBody(args, prompt) {
+  const body = { prompt };
+  if (args.model) body.model = args.model;
+  if (args["aspect-ratio"]) body.aspectRatio = args["aspect-ratio"];
+  if (args["image-size"]) body.imageSize = args["image-size"];
+  if (args.strength !== void 0) body.strength = Number(args.strength);
+  if (args["rgb-colors"]) body.rgbColors = parseJsonArg(args["rgb-colors"], "rgb-colors");
+  if (args["bg-rgb"]) body.backgroundRgbColor = parseJsonArg(args["bg-rgb"], "bg-rgb");
+  if (args.context) body.descriptionContext = args.context;
+  return body;
+}
+async function resolveReferences(spec) {
+  const trimmed = spec.trim();
+  const entries = trimmed.startsWith("data:") ? [trimmed] : trimmed.split(",").map((s) => s.trim()).filter(Boolean);
+  const out = [];
+  for (const entry of entries) {
+    if (isRemoteUrl(entry) || entry.startsWith("data:")) {
+      out.push(entry);
+      continue;
+    }
+    let raw;
+    try {
+      raw = await readFile7(entry);
+    } catch {
+      throw new ApiError("VALIDATION_ERROR", `Reference file not found: ${entry}`);
+    }
+    let webp;
+    try {
+      webp = await sharp2(raw).resize({ width: REFERENCE_MAX_EDGE, height: REFERENCE_MAX_EDGE, fit: "inside", withoutEnlargement: true }).webp({ quality: 82 }).toBuffer();
+    } catch {
+      throw new ApiError("VALIDATION_ERROR", `Reference is not a readable image: ${entry}`);
+    }
+    out.push(`data:image/webp;base64,${webp.toString("base64")}`);
+  }
+  return out;
+}
+var generateCommand = defineCommand92({
+  meta: {
+    name: "generate",
+    description: "Generate an image with AI and store it in the library (cost-tracked per request via OpenRouter usage). Models mirror the canvas: openai/gpt-5.4-image-2 (default \u2014 photoreal, cleanest text, best for ad/landing reproduction), google/gemini-3-pro-image-preview (Nano Banana Pro), google/gemini-3.5-flash & google/gemini-3.1-flash-image-preview (fast, extreme aspect ratios), recraft/recraft-v4.1-pro-vector (vector/SVG-style with palette control). The result is auto-ingested (describe + embed), so the next `baker images library` query finds it. Pass --reference with image URLs and/or local file paths (Pinterest, stock, brand assets, sandbox files) to ground generation in reality.\n\nExamples:\n  baker images generate 'a friendly golden retriever sitting in a bright modern living room' --aspect-ratio 16:9\n  baker images generate 'hero shot of a matte black water bottle on marble' --model google/gemini-3-pro-image-preview --image-size 2K\n  baker images generate 'lifestyle photo matching this mood' --reference 'https://\u2026/ref1.jpg,https://\u2026/ref2.jpg'\n  baker images generate 'put this product on a marble countertop, soft daylight' --reference './src/brand/logos/product.png,./refs/kitchen-mood.jpg'\n  baker images generate 'flat geometric mascot, brand palette' --model recraft/recraft-v4.1-pro-vector --rgb-colors '[[10,10,10],[255,80,0]]'"
+  },
+  args: {
+    prompt: { type: "positional", description: "What to generate", required: false },
+    model: { type: "string", description: "Model id (default openai/gpt-5.4-image-2)", required: false },
+    "aspect-ratio": { type: "string", description: "Aspect ratio (default 1:1)", required: false },
+    "image-size": { type: "string", description: "1K (default) | 2K | 4K | 0.5K", required: false },
+    reference: {
+      type: "string",
+      description: "Comma-separated reference image URLs and/or local file paths",
+      required: false
+    },
+    strength: { type: "string", description: "Recraft vectorization strength 0-1", required: false },
+    "rgb-colors": {
+      type: "string",
+      description: "Recraft palette JSON, e.g. [[10,10,10],[255,80,0]]",
+      required: false
+    },
+    "bg-rgb": { type: "string", description: "Recraft background JSON, e.g. [255,255,255]", required: false },
+    context: { type: "string", description: "Describe-hint override for the ingested row", required: false }
+  },
+  run: async ({ args }) => {
+    try {
+      const prompt = args.prompt;
+      if (!prompt) {
+        writeJson({ ok: false, error: { code: "VALIDATION_ERROR", message: "Prompt is required" } });
+        process.exit(1);
+      }
+      const body = buildGenerateBody(args, prompt);
+      if (args.reference) {
+        const refs = await resolveReferences(args.reference);
+        if (refs.length > 0) body.referenceUrls = refs;
+      }
+      const data = await apiPost("/api/images/generate", body, {
+        timeoutMs: GENERATE_TIMEOUT_MS
+      });
+      writeJson({ ok: true, data });
+    } catch (err) {
+      if (err instanceof ApiError) {
+        writeJson({ ok: false, error: { code: err.code, message: err.message } });
+        process.exit(1);
+      }
+      writeJson({ ok: false, error: { code: "INTERNAL_ERROR", message: "Unexpected error" } });
+      process.exit(1);
+    }
+  }
+});
+
+// src/commands/images/get.ts
+import { defineCommand as defineCommand93 } from "citty";
 registerSchema({
   command: "images.get",
   description: "Get a single image by ID",
@@ -10284,7 +10738,7 @@ registerSchema({
     id: { type: "string", description: "Image ID", required: true }
   }
 });
-var getCommand2 = defineCommand92({
+var getCommand2 = defineCommand93({
   meta: { name: "get", description: "Get a single image by ID. Example: baker images get j571abc123" },
   args: {
     id: { type: "positional", description: "Image ID", required: false },
@@ -10320,7 +10774,7 @@ var getCommand2 = defineCommand92({
 });
 
 // src/commands/images/gif.ts
-import { defineCommand as defineCommand93 } from "citty";
+import { defineCommand as defineCommand94 } from "citty";
 registerSchema({
   command: "images.gif",
   description: "Search Giphy for GIFs / reaction memes (paid social creative).",
@@ -10352,7 +10806,7 @@ registerSchema({
     }
   }
 });
-var gifCommand = defineCommand93({
+var gifCommand = defineCommand94({
   meta: {
     name: "gif",
     description: "Search Giphy for GIFs / reaction memes \u2014 built for paid-social creative (Meta, TikTok, LinkedIn, X). Free API. Each hit carries WebP + GIF + MP4 URLs in providerMeta so you can pick the right format per platform.\n\nExample: baker images gif 'this is fine' --limit 10\nExample: baker images gif 'office reaction' --rating pg --auto-ingest 2\nExample: baker images gif --trending --limit 25"
@@ -10399,7 +10853,7 @@ var gifCommand = defineCommand93({
 });
 
 // src/commands/images/google.ts
-import { defineCommand as defineCommand94 } from "citty";
+import { defineCommand as defineCommand95 } from "citty";
 registerSchema({
   command: "images.google",
   description: "Google Images search via the official Custom Search JSON API. Unverified source \u2014 inspect before placing.",
@@ -10435,7 +10889,7 @@ registerSchema({
     }
   }
 });
-var googleCommand2 = defineCommand94({
+var googleCommand2 = defineCommand95({
   meta: {
     name: "google",
     description: "Google Images via the official Custom Search JSON API ($0.005/query, free 100/day). \u26A0 Source unverified \u2014 watermarks, low-res, mislabeled results are common. Use as last resort. With --auto-ingest, ingested hits return Baker-owned URLs.\n\nExample: baker images google 'industrial workshop' --type photo --size large --limit 20"
@@ -10483,7 +10937,7 @@ var googleCommand2 = defineCommand94({
 });
 
 // src/commands/images/icon.ts
-import { defineCommand as defineCommand95 } from "citty";
+import { defineCommand as defineCommand96 } from "citty";
 registerSchema({
   command: "images.icon",
   description: "Icon lookup via Iconify (200+ icon sets, free CDN).",
@@ -10509,7 +10963,7 @@ registerSchema({
     }
   }
 });
-var iconCommand = defineCommand95({
+var iconCommand = defineCommand96({
   meta: {
     name: "icon",
     description: "Icon via Iconify (simple-icons, logos, lucide, devicon, heroicons, tabler, phosphor, material-symbols, \u2026). Free CDN, no API key.\n\nExample: baker images icon react --set devicon\nExample: baker images icon lucide:check --color '#0a0a0a'"
@@ -10549,7 +11003,7 @@ var iconCommand = defineCommand95({
 });
 
 // src/commands/images/ingest.ts
-import { defineCommand as defineCommand96 } from "citty";
+import { defineCommand as defineCommand97 } from "citty";
 registerSchema({
   command: "images.ingest",
   description: "Ingest a remote image URL into the library (full describe + embed).",
@@ -10561,7 +11015,7 @@ registerSchema({
     context: { type: "string", description: "Description context hint", required: false }
   }
 });
-var ingestCommand = defineCommand96({
+var ingestCommand = defineCommand97({
   meta: {
     name: "ingest",
     description: "Download a remote URL and store it in the library. Hash-deduped on bytes + externalId.\n\nExample: baker images ingest https://img.freepik.com/free-photo/xyz.jpg --source magnific --external-id 12345"
@@ -10603,7 +11057,7 @@ var ingestCommand = defineCommand96({
 });
 
 // src/commands/images/library.ts
-import { defineCommand as defineCommand97 } from "citty";
+import { defineCommand as defineCommand98 } from "citty";
 registerSchema({
   command: "images.library",
   description: "Search the company image library. Returns only ready images.",
@@ -10629,7 +11083,7 @@ registerSchema({
     }
   }
 });
-var libraryCommand = defineCommand97({
+var libraryCommand = defineCommand98({
   meta: {
     name: "library",
     description: "Search the company image library (hybrid BM25 + vector + Cohere rerank). Use this BEFORE any external provider.\n\nExample: baker images library 'hero banner' --aspect-ratio 16:9 --source magnific"
@@ -10686,7 +11140,7 @@ var libraryCommand = defineCommand97({
 });
 
 // src/commands/images/logo.ts
-import { defineCommand as defineCommand98 } from "citty";
+import { defineCommand as defineCommand99 } from "citty";
 registerSchema({
   command: "images.logo",
   description: "Brand logo lookup via Brandfetch CDN (fallback/404). Auto-ingests by default.",
@@ -10711,7 +11165,7 @@ registerSchema({
     }
   }
 });
-var logoCommand = defineCommand98({
+var logoCommand = defineCommand99({
   meta: {
     name: "logo",
     description: "Brand logo via Brandfetch CDN. Returns up to 5 variants (icon, light/dark logo, light/dark symbol). Auto-ingests the first variant.\n\nExample: baker images logo stripe.com --variant logo"
@@ -10749,7 +11203,7 @@ var logoCommand = defineCommand98({
 });
 
 // src/commands/images/normalize.ts
-import { defineCommand as defineCommand99 } from "citty";
+import { defineCommand as defineCommand100 } from "citty";
 
 // src/lib/image/color-changer.ts
 import quantize from "quantize";
@@ -11097,7 +11551,7 @@ function solidifyEdges(data, saturationBoost = 0.25) {
 }
 
 // src/lib/image/image-processor.ts
-import sharp2 from "sharp";
+import sharp3 from "sharp";
 function hasGradient(data) {
   const uniqueColors = /* @__PURE__ */ new Set();
   for (let i = 0; i < data.length; i += 4) {
@@ -11129,10 +11583,10 @@ function createSvgRecolorer(target, palette) {
 async function processGradient(data, info) {
   if (!hasGradient(data)) return { data, info };
   const solidified = solidifyEdges(data, 0.1);
-  const blurred = await sharp2(solidified, {
+  const blurred = await sharp3(solidified, {
     raw: { channels: 4, width: info.width, height: info.height }
   }).png().blur(0.3).toBuffer();
-  const result = await sharp2(blurred).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const result = await sharp3(blurred).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
   return { data: result.data, info: result.info };
 }
 function isSvgBuffer(buffer) {
@@ -11141,13 +11595,13 @@ function isSvgBuffer(buffer) {
 }
 async function processInternal(inputBuffer, isSVG, options) {
   const stages = [];
-  const metadata = await sharp2(inputBuffer).metadata();
+  const metadata = await sharp3(inputBuffer).metadata();
   let alreadyTransparent = false;
   if (metadata.hasAlpha) {
-    const { data: alphaData } = await sharp2(inputBuffer).raw().toBuffer({ resolveWithObject: true });
+    const { data: alphaData } = await sharp3(inputBuffer).raw().toBuffer({ resolveWithObject: true });
     alreadyTransparent = hasTransparency(alphaData, 0.05);
   }
-  let { data: processedData, info } = await sharp2(inputBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  let { data: processedData, info } = await sharp3(inputBuffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
   if (options.color) {
     stages.push("recolor");
     processedData = applyQuantization(processedData, 8);
@@ -11218,7 +11672,7 @@ async function processInternal(inputBuffer, isSVG, options) {
     processedData = result.data;
     info = result.info;
   }
-  let pipeline = sharp2(processedData, {
+  let pipeline = sharp3(processedData, {
     raw: { channels: 4, width: info.width, height: info.height }
   }).png();
   if (options.shrinkToContent) {
@@ -11231,12 +11685,12 @@ async function processInternal(inputBuffer, isSVG, options) {
 function applyResize(buffer, resize) {
   const transparent = { r: 0, g: 0, b: 0, alpha: 0 };
   if (resize.size) {
-    return sharp2(buffer).resize(resize.size.width, resize.size.height, {
+    return sharp3(buffer).resize(resize.size.width, resize.size.height, {
       fit: resize.fit ?? "contain",
       background: transparent
     }).toBuffer();
   }
-  return sharp2(buffer).resize(resize.width ?? null, resize.height ?? null, { fit: "inside", withoutEnlargement: false }).toBuffer();
+  return sharp3(buffer).resize(resize.width ?? null, resize.height ?? null, { fit: "inside", withoutEnlargement: false }).toBuffer();
 }
 async function processImage(inputBuffer, options = {}) {
   const stages = [];
@@ -11245,7 +11699,7 @@ async function processImage(inputBuffer, options = {}) {
     if (options.resize) {
       stages.push("resize");
       const resized = await applyResize(inputBuffer, options.resize);
-      const meta3 = await sharp2(resized).metadata();
+      const meta3 = await sharp3(resized).metadata();
       return {
         buffer: resized,
         format: "png",
@@ -11254,7 +11708,7 @@ async function processImage(inputBuffer, options = {}) {
         stages
       };
     }
-    const meta2 = await sharp2(inputBuffer).metadata();
+    const meta2 = await sharp3(inputBuffer).metadata();
     return {
       buffer: inputBuffer,
       format: "svg",
@@ -11266,7 +11720,7 @@ async function processImage(inputBuffer, options = {}) {
   let workingBuffer = inputBuffer;
   if (isSVG) {
     stages.push("rasterize-svg");
-    workingBuffer = await sharp2(inputBuffer).png({ compressionLevel: 0, force: true, palette: false, quality: 100 }).toBuffer();
+    workingBuffer = await sharp3(inputBuffer).png({ compressionLevel: 0, force: true, palette: false, quality: 100 }).toBuffer();
   }
   const pass = await processInternal(workingBuffer, isSVG, options);
   stages.push(...pass.stages);
@@ -11275,7 +11729,7 @@ async function processImage(inputBuffer, options = {}) {
     stages.push("resize");
     processed = await applyResize(processed, options.resize);
   }
-  const meta = await sharp2(processed).metadata();
+  const meta = await sharp3(processed).metadata();
   return {
     buffer: processed,
     format: "png",
@@ -11481,7 +11935,7 @@ function coerceRawArgs(args) {
     "dry-run": bool(args["dry-run"])
   };
 }
-var normalizeCommand = defineCommand99({
+var normalizeCommand = defineCommand100({
   meta: {
     name: "normalize",
     description: `Normalize logos / images: declarative recolor + bg removal + trim + resize. Operates on local files; writes in-place by default.
@@ -11535,8 +11989,68 @@ Examples:
   }
 });
 
+// src/commands/images/pinterest.ts
+import { defineCommand as defineCommand101 } from "citty";
+registerSchema({
+  command: "images.pinterest",
+  description: "Pinterest image search via ScrapeCreators. Reference-grade real-world photography, product styling, interiors, fashion, food, and aesthetic mood boards. Inspect before placing \u2014 Pinterest is unverified, trademark-bearing web content.",
+  args: {
+    query: { type: "string", description: "Search query", required: true },
+    limit: { type: "number", description: "Max results (1-20, default 5)", required: false, default: 5 },
+    "auto-ingest": {
+      type: "number",
+      description: "Auto-ingest top N and return Baker-owned URLs on ingested hits",
+      required: false,
+      default: 0
+    },
+    context: {
+      type: "string",
+      description: "Free-text hint applied to every auto-ingested hit (overrides the pin title)",
+      required: false
+    }
+  }
+});
+var pinterestCommand = defineCommand101({
+  meta: {
+    name: "pinterest",
+    description: "Pinterest image search via ScrapeCreators ($0.00188/request). Best for photo-realistic reference imagery \u2014 lifestyle, interiors, fashion, food, product styling, and mood boards to brief AI generation against. \u26A0 Unverified, trademark-bearing web content \u2014 inspect and respect rights before placing on a customer page. Browse first; auto-ingest only the pins you commit to.\n\nExamples:\n  baker images pinterest 'scandinavian living room'\n  baker images pinterest 'minimalist skincare product photography' --limit 20\n  baker images pinterest 'cozy coffee shop interior' --auto-ingest 2 --context 'Mood reference for hero photography'"
+  },
+  args: {
+    query: { type: "positional", description: "Search query", required: false },
+    limit: { type: "string", description: "Max results (1-20)", required: false },
+    "auto-ingest": {
+      type: "string",
+      description: "Auto-ingest top N and return Baker-owned URLs on ingested hits",
+      required: false
+    },
+    context: { type: "string", description: "Description context hint applied to auto-ingested hits", required: false }
+  },
+  run: async ({ args }) => {
+    try {
+      const query = args.query;
+      if (!query) {
+        writeJson({ ok: false, error: { code: "VALIDATION_ERROR", message: "Query is required" } });
+        process.exit(1);
+      }
+      const body = { query };
+      if (args.limit) body.limit = Number(args.limit);
+      if (args["auto-ingest"]) body.autoIngest = Number(args["auto-ingest"]);
+      if (args.context) body.descriptionContext = args.context;
+      const data = await apiPost("/api/images/pinterest", body);
+      writeJson({ ok: true, data });
+    } catch (err) {
+      if (err instanceof ApiError) {
+        writeJson({ ok: false, error: { code: err.code, message: err.message } });
+        process.exit(1);
+      }
+      writeJson({ ok: false, error: { code: "INTERNAL_ERROR", message: "Unexpected error" } });
+      process.exit(1);
+    }
+  }
+});
+
 // src/commands/images/screenshot.ts
-import { defineCommand as defineCommand100 } from "citty";
+import { defineCommand as defineCommand102 } from "citty";
 registerSchema({
   command: "images.screenshot",
   description: "Capture a website screenshot via ScreenshotOne. Auto-ingests on success.",
@@ -11552,7 +12066,7 @@ registerSchema({
     }
   }
 });
-var screenshotCommand = defineCommand100({
+var screenshotCommand = defineCommand102({
   meta: {
     name: "screenshot",
     description: "Screenshot a URL via ScreenshotOne. $0.009/capture. Auto-ingests to library.\n\nExample: baker images screenshot https://stripe.com --full-page"
@@ -11602,7 +12116,7 @@ var screenshotCommand = defineCommand100({
 });
 
 // src/commands/images/search.ts
-import { defineCommand as defineCommand101 } from "citty";
+import { defineCommand as defineCommand103 } from "citty";
 registerSchema({
   command: "images.search",
   description: "Search images by text query. Only returns ready images.",
@@ -11618,7 +12132,7 @@ registerSchema({
     tags: { type: "string", description: "Comma-separated tags to filter by", required: false }
   }
 });
-var searchCommand = defineCommand101({
+var searchCommand = defineCommand103({
   meta: {
     name: "search",
     description: "Semantic search images by text query. Uses hybrid BM25 + vector + reranking. Example: baker images search 'hero banner' --aspect-ratio 16:9 --tags logo"
@@ -11678,7 +12192,7 @@ var searchCommand = defineCommand101({
 });
 
 // src/commands/images/sticker.ts
-import { defineCommand as defineCommand102 } from "citty";
+import { defineCommand as defineCommand104 } from "citty";
 registerSchema({
   command: "images.sticker",
   description: "Search Giphy stickers \u2014 transparent-background overlays for ad creative.",
@@ -11710,7 +12224,7 @@ registerSchema({
     }
   }
 });
-var stickerCommand = defineCommand102({
+var stickerCommand = defineCommand104({
   meta: {
     name: "sticker",
     description: "Search Giphy's sticker corpus \u2014 transparent-background WebPs / GIFs ideal for overlaying on ad creative (Meta, TikTok, Stories). Same Giphy free API as `baker images gif`; results carry WebP + GIF + MP4 URLs in providerMeta.\n\nExample: baker images sticker 'thumbs up' --limit 10\nExample: baker images sticker celebration --rating g --auto-ingest 3\nExample: baker images sticker --trending --limit 25"
@@ -11757,7 +12271,7 @@ var stickerCommand = defineCommand102({
 });
 
 // src/commands/images/stock.ts
-import { defineCommand as defineCommand103 } from "citty";
+import { defineCommand as defineCommand105 } from "citty";
 registerSchema({
   command: "images.stock",
   description: "Stock photo, vector illustration, icon-set, and PSD search via Magnific (Freepik's developer API).",
@@ -11815,7 +12329,7 @@ registerSchema({
     }
   }
 });
-var stockCommand = defineCommand103({
+var stockCommand = defineCommand105({
   meta: {
     name: "stock",
     description: "Stock search via Magnific \u2014 Freepik's developer API (~250M assets: photos, vectors, illustrations, icons, PSDs). $0.002/req. With --auto-ingest, ingested hits return Baker-owned URLs.\n\nExamples:\n  baker images stock 'minimalist office'\n  baker images stock 'flat office workers' --type vector\n  baker images stock 'hero photo of a kitchen' --type photo --orientation landscape --ai exclude\n  baker images stock 'brand pattern' --color '#0a0a0a' --license freemium --auto-ingest 2"
@@ -11871,9 +12385,9 @@ var stockCommand = defineCommand103({
 });
 
 // src/commands/images/upload.ts
-import { readFile as readFile7 } from "fs/promises";
+import { readFile as readFile8 } from "fs/promises";
 import { extname as extname2 } from "path";
-import { defineCommand as defineCommand104 } from "citty";
+import { defineCommand as defineCommand106 } from "citty";
 var MIME_MAP = {
   ".png": "image/png",
   ".jpg": "image/jpeg",
@@ -11928,7 +12442,7 @@ function detectContentType(filePath) {
   }
   return mime;
 }
-var uploadCommand = defineCommand104({
+var uploadCommand = defineCommand106({
   meta: {
     name: "upload",
     description: "Upload an image to the library \u2014 accepts a local file path OR a remote http(s) URL.\n\nLocal: reads bytes, sends to /api/images/upload, content-type auto-detected from extension.\nRemote: dispatches to /api/images/ingest with hash-dedup on bytes + externalId.\n\nExamples:\n  baker images upload ./logo.png --source uploaded\n  baker images upload ./cert.png --context 'ISO 27001 badge \u2014 enterprise tier'\n  baker images upload https://acme.com/hero.png --source firecrawl --context 'Acme competitor pricing hero'"
@@ -12011,7 +12525,7 @@ async function uploadLocal(target, args) {
     });
     return;
   }
-  const fileBuffer = await readFile7(target);
+  const fileBuffer = await readFile8(target);
   const base64 = fileBuffer.toString("base64");
   const body = { base64, contentType };
   if (args.source) body.source = args.source;
@@ -12021,7 +12535,7 @@ async function uploadLocal(target, args) {
 }
 
 // src/commands/images/upscale.ts
-import { defineCommand as defineCommand105 } from "citty";
+import { defineCommand as defineCommand107 } from "citty";
 registerSchema({
   command: "images.upscale",
   description: "Upscale a library image via the backend (Replicate, cost-tracked). Waits for completion by default. The image must be status 'ready' and raster (not SVG/AVIF).",
@@ -12036,7 +12550,7 @@ registerSchema({
   }
 });
 var POLL_INTERVAL_MS3 = 1500;
-var upscaleCommand = defineCommand105({
+var upscaleCommand = defineCommand107({
   meta: {
     name: "upscale",
     description: "Upscale a library image via the Convex backend (Replicate, cost-tracked at $0.05/image). Waits for completion by default.\n\nExample: baker images upscale j571abc123def\nExample: baker images upscale j571abc123def --max-wait 0   # fire-and-forget"
@@ -12091,7 +12605,7 @@ var upscaleCommand = defineCommand105({
 });
 
 // src/commands/images/use.ts
-import { defineCommand as defineCommand106 } from "citty";
+import { defineCommand as defineCommand108 } from "citty";
 registerSchema({
   command: "images.use",
   description: "Ingest a URL and wait for the library record to be ready.",
@@ -12107,7 +12621,7 @@ registerSchema({
   }
 });
 var POLL_INTERVAL_MS4 = 1500;
-var useCommand = defineCommand106({
+var useCommand = defineCommand108({
   meta: {
     name: "use",
     description: "Sugar over `ingest`: download \u2192 store \u2192 wait until describe + embed complete \u2192 return ready library record.\n\nExample: baker images use https://cdn.example.com/hero.png --source uploaded"
@@ -12153,7 +12667,7 @@ var useCommand = defineCommand106({
 });
 
 // src/commands/images/index.ts
-var imagesCommand = defineCommand107({
+var imagesCommand = defineCommand109({
   meta: {
     name: "images",
     description: `Find, source, and normalize images. Subcommands route by provider so cost + license are explicit.
@@ -12165,6 +12679,7 @@ Library + search:
 External providers:
   baker images stock <q> [--type photo|vector|psd]     Magnific (Freepik's dev API) \u2014 photos, vectors, illustrations, PSDs
   baker images google <q>                              Google Images via the official Custom Search API
+  baker images pinterest <q>                           Pinterest reference imagery via ScrapeCreators (photo-real mood boards)
   baker images logo <domain>                           Brand logo via Brandfetch CDN
   baker images icon <name> [--set \u2026]                   Iconify (200+ sets)
   baker images gif <q> [--trending]                    Giphy GIFs / reaction memes (paid-social creative)
@@ -12172,7 +12687,9 @@ External providers:
   baker images extract <url>                           Firecrawl page extract
   baker images screenshot <url>                        ScreenshotOne capture
 
-Ingest + management:
+AI generation (run on the Convex backend, cost-tracked):
+  baker images generate <prompt> [--model \u2026] [--aspect-ratio \u2026] [--reference url1,url2]
+                                                       Generate an image with AI (OpenRouter models) and ingest it
   baker images ingest <url> --source <enum>            Save remote URL to library
   baker images use <url>                               Ingest and wait for ready
   baker images upload ./file                           Upload local file
@@ -12195,6 +12712,8 @@ Paid transforms (run on the Convex backend, cost-tracked):
     find: findCommand,
     stock: stockCommand,
     google: googleCommand2,
+    pinterest: pinterestCommand,
+    generate: generateCommand,
     logo: logoCommand,
     icon: iconCommand,
     gif: gifCommand,
@@ -12214,10 +12733,10 @@ Paid transforms (run on the Convex backend, cost-tracked):
 });
 
 // src/commands/research/index.ts
-import { defineCommand as defineCommand118 } from "citty";
+import { defineCommand as defineCommand120 } from "citty";
 
 // src/commands/research/advertisers.ts
-import { defineCommand as defineCommand108 } from "citty";
+import { defineCommand as defineCommand110 } from "citty";
 
 // src/commands/research/output.ts
 var RESEARCH_DATA_NOTE = "Estimates based on third-party SERP data \u2014 not exact figures. Use for directional insights, not precise measurement.";
@@ -12330,7 +12849,7 @@ var FIELDS3 = {
   etv: "Estimated traffic value (USD)",
   visibility: "SERP visibility score (0-1)"
 };
-var advertisersCommand = defineCommand108({
+var advertisersCommand = defineCommand110({
   meta: {
     name: "advertisers",
     description: `Find domains competing for a keyword in Google SERPs.
@@ -12377,7 +12896,7 @@ Examples:
 });
 
 // src/commands/research/autocomplete.ts
-import { defineCommand as defineCommand109 } from "citty";
+import { defineCommand as defineCommand111 } from "citty";
 registerSchema({
   command: "research.autocomplete",
   description: "Get Google Autocomplete suggestions for a seed keyword. Useful for keyword expansion and discovering what people actually search for. IMPORTANT: If --location and --language are omitted, defaults to United States (us) and English (en).",
@@ -12400,7 +12919,7 @@ registerSchema({
 var FIELDS4 = {
   suggestion: "Autocomplete suggestion from Google"
 };
-var autocompleteCommand = defineCommand109({
+var autocompleteCommand = defineCommand111({
   meta: {
     name: "autocomplete",
     description: `Get Google Autocomplete suggestions for keyword expansion.
@@ -12446,7 +12965,7 @@ Examples:
 });
 
 // src/commands/research/countries.ts
-import { defineCommand as defineCommand110 } from "citty";
+import { defineCommand as defineCommand112 } from "citty";
 registerSchema({
   command: "research.countries",
   description: "List all supported country codes for --location flag in research commands.",
@@ -12503,7 +13022,7 @@ var FIELDS5 = {
   code: "Country code to pass as --location",
   name: "Country name"
 };
-var countriesCommand = defineCommand110({
+var countriesCommand = defineCommand112({
   meta: {
     name: "countries",
     description: "List all supported country codes for --location flag."
@@ -12514,7 +13033,7 @@ var countriesCommand = defineCommand110({
 });
 
 // src/commands/research/intent.ts
-import { defineCommand as defineCommand111 } from "citty";
+import { defineCommand as defineCommand113 } from "citty";
 registerSchema({
   command: "research.intent",
   description: "Classify Google Search intent for keywords. Determines if someone searching is looking to buy, research, or navigate. IMPORTANT: If --language is omitted, defaults to English (en). The response includes a query_context object showing which language was used.",
@@ -12537,7 +13056,7 @@ var FIELDS6 = {
   intent: "Primary Google Search intent: informational, navigational, commercial, transactional",
   probability: "Confidence score 0.0-1.0"
 };
-var intentCommand = defineCommand111({
+var intentCommand = defineCommand113({
   meta: {
     name: "intent",
     description: `Classify Google Search intent for keywords. Returns intent type and confidence.
@@ -12585,7 +13104,7 @@ Examples:
 });
 
 // src/commands/research/keyword-gap.ts
-import { defineCommand as defineCommand112 } from "citty";
+import { defineCommand as defineCommand114 } from "citty";
 registerSchema({
   command: "research.keyword-gap",
   description: "Find keywords a competitor ranks for (organic or paid) that you don't. Discovers expansion opportunities. IMPORTANT: If --location and --language are omitted, defaults to United States (us) and English (en). The response includes a query_context object showing which location/language were used.",
@@ -12614,7 +13133,7 @@ var FIELDS7 = {
   cpc: "Cost per click USD",
   their_position: "Competitor's ranking position"
 };
-var keywordGapCommand = defineCommand112({
+var keywordGapCommand = defineCommand114({
   meta: {
     name: "keyword-gap",
     description: `Find keywords a competitor has that you don't. Supports pagination via --offset.
@@ -12688,7 +13207,7 @@ Examples:
 });
 
 // src/commands/research/keywords-for-site.ts
-import { defineCommand as defineCommand113 } from "citty";
+import { defineCommand as defineCommand115 } from "citty";
 registerSchema({
   command: "research.keywords-for-site",
   description: "Get keywords a competitor targets in Google. Use --type paid to see only paid keywords, --type organic for organic only. IMPORTANT: If --location and --language are omitted, defaults to United States (us) and English (en). The response includes a query_context object showing which location/language were used.",
@@ -12721,7 +13240,7 @@ var FIELDS8 = {
   competition: "LOW, MEDIUM, or HIGH",
   competition_index: "Competition score 0-100"
 };
-var keywordsForSiteCommand = defineCommand113({
+var keywordsForSiteCommand = defineCommand115({
   meta: {
     name: "keywords-for-site",
     description: `Get keywords a competitor targets in Google. Use --type to filter paid/organic.
@@ -12774,7 +13293,7 @@ Examples:
 });
 
 // src/commands/research/languages.ts
-import { defineCommand as defineCommand114 } from "citty";
+import { defineCommand as defineCommand116 } from "citty";
 registerSchema({
   command: "research.languages",
   description: "List all supported language codes for --language flag in research commands.",
@@ -12804,7 +13323,7 @@ var FIELDS9 = {
   code: "Language code to pass as --language",
   name: "Language name (also accepted by --language)"
 };
-var languagesCommand2 = defineCommand114({
+var languagesCommand2 = defineCommand116({
   meta: {
     name: "languages",
     description: "List all supported language codes for --language flag."
@@ -12815,7 +13334,7 @@ var languagesCommand2 = defineCommand114({
 });
 
 // src/commands/research/lighthouse.ts
-import { defineCommand as defineCommand115 } from "citty";
+import { defineCommand as defineCommand117 } from "citty";
 registerSchema({
   command: "research.lighthouse",
   description: "Landing page performance audit. Returns metrics that affect Google Ads Quality Score and CPC.",
@@ -12834,7 +13353,7 @@ var FIELDS10 = {
   speed_index_ms: "Speed Index in ms (good: < 3400)",
   interactive_ms: "Time to Interactive in ms (good: < 3800)"
 };
-var lighthouseCommand = defineCommand115({
+var lighthouseCommand = defineCommand117({
   meta: {
     name: "lighthouse",
     description: `Landing page performance audit. Metrics affecting Google Ads Quality Score.
@@ -12872,7 +13391,7 @@ Examples:
 });
 
 // src/commands/research/relevant-pages.ts
-import { defineCommand as defineCommand116 } from "citty";
+import { defineCommand as defineCommand118 } from "citty";
 registerSchema({
   command: "research.relevant-pages",
   description: "Get the top pages of a competitor domain with organic traffic and ranking data. Shows which pages drive the most traffic. IMPORTANT: If --location and --language are omitted, defaults to United States (us) and English (en).",
@@ -12898,7 +13417,7 @@ var FIELDS11 = {
   keywords: "Total organic keywords the page ranks for",
   top_10: "Keywords in positions 1-10"
 };
-var relevantPagesCommand = defineCommand116({
+var relevantPagesCommand = defineCommand118({
   meta: {
     name: "relevant-pages",
     description: `Get the top pages of a competitor domain with traffic data.
@@ -12944,7 +13463,7 @@ Examples:
 });
 
 // src/commands/research/web.ts
-import { defineCommand as defineCommand117 } from "citty";
+import { defineCommand as defineCommand119 } from "citty";
 registerSchema({
   command: "research.web",
   description: "Search the web with AI to answer marketing questions \u2014 competitors, ICP, pricing, pain points, market trends. Three depth levels: medium (quick, default), high (thorough), xhigh (exhaustive deep research).",
@@ -12995,7 +13514,7 @@ async function runDeepResearch(question) {
   }
   throw new Error("Deep research timed out");
 }
-var webCommand = defineCommand117({
+var webCommand = defineCommand119({
   meta: {
     name: "web",
     description: `Search the web with AI to answer any open-ended marketing question. Uses live internet data via Google Search.
@@ -13055,7 +13574,7 @@ Examples:
 });
 
 // src/commands/research/index.ts
-var researchCommand = defineCommand118({
+var researchCommand = defineCommand120({
   meta: {
     name: "research",
     description: `Competitive intelligence and AI-powered research commands.
@@ -13095,10 +13614,10 @@ Examples:
 });
 
 // src/commands/scheduled-actions/index.ts
-import { defineCommand as defineCommand125 } from "citty";
+import { defineCommand as defineCommand127 } from "citty";
 
 // src/commands/scheduled-actions/create.ts
-import { defineCommand as defineCommand119 } from "citty";
+import { defineCommand as defineCommand121 } from "citty";
 
 // src/commands/scheduled-actions/shared.ts
 var TEMP_SCHEDULED_ACTION_PREFIX = "temp_sched_";
@@ -13203,7 +13722,7 @@ registerSchema({
     prompt: { type: "string", description: "Additional prompt instructions for the spawned agent", required: false }
   }
 });
-var createCommand2 = defineCommand119({
+var createCommand2 = defineCommand121({
   meta: {
     name: "create",
     description: 'Stage a scheduled action. Example: baker scheduled-actions create --name "Weekly report" --description "..." --cron "0 9 * * MON"'
@@ -13251,7 +13770,7 @@ var createCommand2 = defineCommand119({
 });
 
 // src/commands/scheduled-actions/delete.ts
-import { defineCommand as defineCommand120 } from "citty";
+import { defineCommand as defineCommand122 } from "citty";
 registerSchema({
   command: "scheduled-actions.delete",
   description: "Stage deletion of a published scheduled action or cancellation of a temp_sched_* draft creation.",
@@ -13259,7 +13778,7 @@ registerSchema({
     id: { type: "string", description: "Published scheduled action ID or temp_sched_* draft ID", required: true }
   }
 });
-var deleteCommand2 = defineCommand120({
+var deleteCommand2 = defineCommand122({
   meta: {
     name: "delete",
     description: "Stage scheduled action deletion. Example: baker scheduled-actions delete <id-or-temp_sched_id>"
@@ -13288,7 +13807,7 @@ var deleteCommand2 = defineCommand120({
 });
 
 // src/commands/scheduled-actions/get.ts
-import { defineCommand as defineCommand121 } from "citty";
+import { defineCommand as defineCommand123 } from "citty";
 registerSchema({
   command: "scheduled-actions.get",
   description: "Get a published scheduled action or a temp_sched_* draft-created scheduled action.",
@@ -13296,7 +13815,7 @@ registerSchema({
     id: { type: "string", description: "Published scheduled action ID or temp_sched_* draft ID", required: true }
   }
 });
-var getCommand3 = defineCommand121({
+var getCommand3 = defineCommand123({
   meta: {
     name: "get",
     description: "Get a scheduled action. Example: baker scheduled-actions get <id-or-temp_sched_id>"
@@ -13333,13 +13852,13 @@ var getCommand3 = defineCommand121({
 });
 
 // src/commands/scheduled-actions/list.ts
-import { defineCommand as defineCommand122 } from "citty";
+import { defineCommand as defineCommand124 } from "citty";
 registerSchema({
   command: "scheduled-actions.list",
   description: "List published scheduled actions. Includes draft state when BAKER_CHAT_ID is set.",
   args: {}
 });
-var listCommand2 = defineCommand122({
+var listCommand2 = defineCommand124({
   meta: {
     name: "list",
     description: "List scheduled actions. Includes staged draft ops when BAKER_CHAT_ID is set."
@@ -13360,7 +13879,7 @@ var listCommand2 = defineCommand122({
 });
 
 // src/commands/scheduled-actions/trigger.ts
-import { defineCommand as defineCommand123 } from "citty";
+import { defineCommand as defineCommand125 } from "citty";
 registerSchema({
   command: "scheduled-actions.trigger",
   description: "Immediately trigger a published scheduled action. Does not require BAKER_CHAT_ID and rejects temp_sched_* IDs.",
@@ -13368,7 +13887,7 @@ registerSchema({
     id: { type: "string", description: "Published scheduled action ID", required: true }
   }
 });
-var triggerCommand = defineCommand123({
+var triggerCommand = defineCommand125({
   meta: {
     name: "trigger",
     description: "Immediately trigger a published scheduled action. Example: baker scheduled-actions trigger <id>"
@@ -13405,7 +13924,7 @@ var triggerCommand = defineCommand123({
 });
 
 // src/commands/scheduled-actions/update.ts
-import { defineCommand as defineCommand124 } from "citty";
+import { defineCommand as defineCommand126 } from "citty";
 registerSchema({
   command: "scheduled-actions.update",
   description: "Stage an update to a published scheduled action or temp_sched_* draft-created scheduled action.",
@@ -13430,7 +13949,7 @@ registerSchema({
     prompt: { type: "string", description: "Replacement additional spawned-agent instructions", required: false }
   }
 });
-var updateCommand2 = defineCommand124({
+var updateCommand2 = defineCommand126({
   meta: {
     name: "update",
     description: "Stage a scheduled action update. Example: baker scheduled-actions update <id> --enabled false"
@@ -13500,7 +14019,7 @@ var updateCommand2 = defineCommand124({
 });
 
 // src/commands/scheduled-actions/index.ts
-var scheduledActionsCommand = defineCommand125({
+var scheduledActionsCommand = defineCommand127({
   meta: {
     name: "scheduled-actions",
     description: `Manage Scheduled Actions. Subcommands: list, get, create, update, delete, trigger.
@@ -13526,8 +14045,8 @@ Examples:
 });
 
 // src/commands/schema.ts
-import { defineCommand as defineCommand126 } from "citty";
-var schemaCommand = defineCommand126({
+import { defineCommand as defineCommand128 } from "citty";
+var schemaCommand = defineCommand128({
   meta: {
     name: "schema",
     description: "Inspect command argument schemas (for AI agent introspection). Lists all commands if no argument given. Example: baker schema images.search"
@@ -13563,10 +14082,10 @@ var schemaCommand = defineCommand126({
 });
 
 // src/commands/testimonials/index.ts
-import { defineCommand as defineCommand130 } from "citty";
+import { defineCommand as defineCommand132 } from "citty";
 
 // src/commands/testimonials/get.ts
-import { defineCommand as defineCommand127 } from "citty";
+import { defineCommand as defineCommand129 } from "citty";
 registerSchema({
   command: "testimonials.get",
   description: "Get a single testimonial by ID",
@@ -13574,7 +14093,7 @@ registerSchema({
     id: { type: "string", description: "Testimonial ID", required: true }
   }
 });
-var getCommand4 = defineCommand127({
+var getCommand4 = defineCommand129({
   meta: { name: "get", description: "Get a single testimonial by ID. Example: baker testimonials get j571abc123" },
   args: {
     id: { type: "positional", description: "Testimonial ID", required: false },
@@ -13611,7 +14130,7 @@ var getCommand4 = defineCommand127({
 });
 
 // src/commands/testimonials/list.ts
-import { defineCommand as defineCommand128 } from "citty";
+import { defineCommand as defineCommand130 } from "citty";
 registerSchema({
   command: "testimonials.list",
   description: "List testimonials with optional filters.",
@@ -13641,7 +14160,7 @@ registerSchema({
     limit: { type: "number", description: "Max results (default 50)", required: false, default: 50 }
   }
 });
-var listCommand3 = defineCommand128({
+var listCommand3 = defineCommand130({
   meta: {
     name: "list",
     description: "List testimonials with optional filters. Example: baker testimonials list --source google --sentiment positive"
@@ -13690,7 +14209,7 @@ var listCommand3 = defineCommand128({
 });
 
 // src/commands/testimonials/search.ts
-import { defineCommand as defineCommand129 } from "citty";
+import { defineCommand as defineCommand131 } from "citty";
 registerSchema({
   command: "testimonials.search",
   description: "Search testimonials by text query. Uses hybrid BM25 + vector + reranking.",
@@ -13721,7 +14240,7 @@ registerSchema({
     tags: { type: "string", description: "Comma-separated tags to filter by", required: false }
   }
 });
-var searchCommand2 = defineCommand129({
+var searchCommand2 = defineCommand131({
   meta: {
     name: "search",
     description: "Semantic search testimonials by text query. Uses hybrid BM25 + vector + reranking. Example: baker testimonials search 'great service' --rating-min 4"
@@ -13792,7 +14311,7 @@ var searchCommand2 = defineCommand129({
 });
 
 // src/commands/testimonials/index.ts
-var testimonialsCommand = defineCommand130({
+var testimonialsCommand = defineCommand132({
   meta: {
     name: "testimonials",
     description: `Find and browse testimonials in Baker. Subcommands: search, get, list.
@@ -13811,10 +14330,10 @@ Examples:
 });
 
 // src/commands/videos/index.ts
-import { defineCommand as defineCommand135 } from "citty";
+import { defineCommand as defineCommand137 } from "citty";
 
 // src/commands/videos/delete.ts
-import { defineCommand as defineCommand131 } from "citty";
+import { defineCommand as defineCommand133 } from "citty";
 registerSchema({
   command: "videos.delete",
   description: "Delete a video by ID",
@@ -13828,7 +14347,7 @@ registerSchema({
     }
   }
 });
-var deleteCommand3 = defineCommand131({
+var deleteCommand3 = defineCommand133({
   meta: {
     name: "delete",
     description: "Delete a video by ID. Use --dry-run to preview. Example: baker videos delete j571abc123 --dry-run"
@@ -13869,7 +14388,7 @@ var deleteCommand3 = defineCommand131({
 });
 
 // src/commands/videos/get.ts
-import { defineCommand as defineCommand132 } from "citty";
+import { defineCommand as defineCommand134 } from "citty";
 registerSchema({
   command: "videos.get",
   description: "Get a single video by ID",
@@ -13877,7 +14396,7 @@ registerSchema({
     id: { type: "string", description: "Video ID", required: true }
   }
 });
-var getCommand5 = defineCommand132({
+var getCommand5 = defineCommand134({
   meta: { name: "get", description: "Get a single video by ID. Example: baker videos get j571abc123" },
   args: {
     id: { type: "positional", description: "Video ID", required: false },
@@ -13914,7 +14433,7 @@ var getCommand5 = defineCommand132({
 });
 
 // src/commands/videos/search.ts
-import { defineCommand as defineCommand133 } from "citty";
+import { defineCommand as defineCommand135 } from "citty";
 registerSchema({
   command: "videos.search",
   description: "Search videos by text query. Only returns ready videos.",
@@ -13924,7 +14443,7 @@ registerSchema({
     tags: { type: "string", description: "Comma-separated tags to filter by", required: false }
   }
 });
-var searchCommand3 = defineCommand133({
+var searchCommand3 = defineCommand135({
   meta: {
     name: "search",
     description: "Semantic search videos by text query. Uses hybrid BM25 + vector + reranking. Example: baker videos search 'product demo' --tags tutorial"
@@ -13971,9 +14490,9 @@ var searchCommand3 = defineCommand133({
 });
 
 // src/commands/videos/upload.ts
-import { readFile as readFile8, stat as stat3 } from "fs/promises";
+import { readFile as readFile9, stat as stat3 } from "fs/promises";
 import { extname as extname3 } from "path";
-import { defineCommand as defineCommand134 } from "citty";
+import { defineCommand as defineCommand136 } from "citty";
 var MIME_MAP2 = {
   ".mp4": "video/mp4",
   ".mov": "video/quicktime",
@@ -14007,7 +14526,7 @@ function detectContentType2(filePath) {
   }
   return mime;
 }
-var uploadCommand2 = defineCommand134({
+var uploadCommand2 = defineCommand136({
   meta: {
     name: "upload",
     description: "Upload a video file to Baker via Mux direct upload. Auto-detects content type. Example: baker videos upload ./demo.mp4"
@@ -14036,7 +14555,7 @@ var uploadCommand2 = defineCommand134({
         return;
       }
       const { uploadUrl, videoId } = await apiPost("/api/videos/upload", {});
-      const fileBuffer = await readFile8(filePath);
+      const fileBuffer = await readFile9(filePath);
       const uploadResponse = await fetch(uploadUrl, {
         method: "PUT",
         headers: { "Content-Type": contentType },
@@ -14061,7 +14580,7 @@ var uploadCommand2 = defineCommand134({
 });
 
 // src/commands/videos/index.ts
-var videosCommand = defineCommand135({
+var videosCommand = defineCommand137({
   meta: {
     name: "videos",
     description: `Find and manage videos in Baker. Subcommands: search, get, upload, delete.
@@ -14098,7 +14617,7 @@ function getCliVersion() {
 }
 
 // src/cli.ts
-var main = defineCommand136({
+var main = defineCommand138({
   meta: {
     name: "baker",
     version: getCliVersion(),