@koda-sl/baker-cli 0.361.0 → 0.363.0

package/dist/cli.js

@@ -34118,12 +34118,13 @@ function readFlowConversions2(slug, definitions) {
     endings: joinFlowConversions(flowEventKeys(tree, slug), definitions)
   };
 }
-function conversionsEnvelope(args5, definitions, candidates) {
+function conversionsEnvelope(args5, definitions, candidates, serverHints = []) {
   const flow = args5.flowSlug === void 0 ? null : readFlowConversions2(args5.flowSlug, definitions);
   const forms = flow === null ? readWorkspaceFlows() : [];
   const coverage = flowCoverage(forms, definitions);
   const page = pageCandidates(definitions, candidates, args5.candidates);
   const hints2 = [
+    ...serverHints,
     ...flow ? flowConversionHints(flow.slug, flow.endings, flow.noConversionReason) : [],
     ...flowCoverageHints(coverage),
     ...stagedHints(definitions),
@@ -34213,7 +34214,8 @@ var conversionsCommand3 = (() => {
         for (const eventKey of args6.eventKeys) refuseUnmatchableKey(eventKey);
         const before = await apiPost("/api/analytics/conversions", {});
         const write = conversionsWrite(args6, before.data.definitions);
-        const stored = write ? (await apiPost("/api/analytics/conversions", write)).data.definitions : before.data.definitions;
+        const answer = write ? await apiPost("/api/analytics/conversions", write) : before;
+        const stored = answer.data.definitions;
         const report = await apiPost("/api/analytics/query", {
           preset: "conversions",
           days: args6.days
@@ -34221,7 +34223,8 @@ var conversionsCommand3 = (() => {
         const envelope = conversionsEnvelope(
           args6,
           mergeStoredWithCounts(stored, report.data.conversions ?? []),
-          report.data.eventCatalog ?? []
+          report.data.eventCatalog ?? [],
+          answer.hints ?? []
         );
         if (format === "md") process.stdout.write(renderConversionsMarkdown(envelope));
         else writeJsonEnvelope(withFormatHint(envelope, format));
@@ -34541,9 +34544,9 @@ import { defineCommand as defineCommand105 } from "citty";
 import { defineCommand as defineCommand100 } from "citty";
 
 // src/commands/avatars/casting.ts
-var CAST_FLAG_RULE = "Cast with `--avatar <handle>` on `baker studio generate`, `baker studio animate` and `baker canvas scaffold-ad`. Do NOT hand-roll it by pasting `subjectDescription` into the prompt or by passing the sheet through `--reference` \u2014 both render something that merely resembles them. `--avatar` is also the ONLY thing that carries their ACCENT and delivery into a clip. An avatar has no pinned voice by design (ADR 0005): the video model renders the voice, and the region on their profile is the only thing steering it \u2014 without the flag the clip is performed flat, in whatever accent the model picks on its own.";
+var CAST_FLAG_RULE = "Cast with `--avatar <handle>` on `baker studio generate`, `baker studio animate`, `baker canvas scaffold-ad`, `baker canvas scaffold-static-ad` and `baker canvas scaffold-video`. Do NOT hand-roll it by pasting `subjectDescription` into the prompt or by passing the sheet through `--reference` \u2014 both render something that merely resembles them. `--avatar` is also the ONLY thing that carries their ACCENT and delivery into a clip. An avatar has no pinned voice by design (ADR 0005): the video model renders the voice, and the region on their profile is the only thing steering it \u2014 without the flag the clip is performed flat, in whatever accent the model picks on its own. `baker canvas scaffold-video` casts only their FACE: a reproduced video keeps the source ad's accent direction, so never tell the user it speaks in theirs.";
 var VERBATIM_RULE = "When you do write the description yourself \u2014 a hand-built canvas node, a landing image, anywhere `--avatar` does not exist \u2014 copy `subjectDescription` VERBATIM, word for word. Re-phrasing it per generation is the other reason a face drifts across a set.";
-var VIDEO_ROUTING = "In video, a photoreal presenter renders on `google/veo-3.1` (or `google/veo-3.1-fast`), never `bytedance/seedance-2.0` \u2014 it refuses photoreal human faces, AI-generated ones included. Scaffolding a video creative: `baker canvas scaffold-video \u2026 --real-face`.";
+var VIDEO_ROUTING = "In video, a photoreal presenter renders on `google/veo-3.1` (or `google/veo-3.1-fast`), never `bytedance/seedance-2.0` \u2014 it refuses photoreal human faces, AI-generated ones included. Reproducing a video the user gave you: `baker canvas scaffold-video \u2026 --avatar <handle> --real-face`.";
 function castingHints(avatar) {
   if (avatar.status === "generating" && avatar.needsFace) {
     return [
@@ -37023,6 +37026,21 @@ import { toCardinal as nwPl } from "n2words/pl-PL";
 import { toCardinal as nwPt } from "n2words/pt-PT";
 import { z as z41 } from "zod";
 
+// src/engine/scaffold/castAvatar.ts
+var SOURCE_IDENTITY_FIELDS = [
+  "perceived_age_band",
+  "perceived_gender_presentation",
+  "perceived_ethnicity_or_skin_tone",
+  "hair",
+  "facial_hair",
+  "build_body_type",
+  "distinguishing_features"
+];
+function recastPersonEntry(entry, avatarDescription) {
+  for (const field of SOURCE_IDENTITY_FIELDS) delete entry[field];
+  entry.description = avatarDescription;
+}
+
 // src/engine/scaffold/lib/shoot-modes.ts
 var SHOOT_MODES = [
   "ugc_selfie",
@@ -37577,6 +37595,30 @@ var RecurringElement = z41.object({
   appears_in: z41.array(AppearsItem).optional()
 }).loose();
 var RecurringElements = z41.array(RecurringElement);
+function castAvatarsOnElements(elementsInput, avatars) {
+  const elements = RecurringElements.parse(elementsInput);
+  const byLabel = /* @__PURE__ */ new Map();
+  let next = 0;
+  const cast = elements.map((el) => {
+    if (el.type.toLowerCase() !== "person" || el.same_as) return el;
+    const avatar = avatars[next];
+    if (!avatar) return el;
+    next += 1;
+    if (el.label) byLabel.set(el.label, avatar);
+    const description = avatar.subjectDescription?.trim();
+    return { ...el, ...description ? { description } : {}, source_image: avatar.sheetUrl, source_is_sheet: true };
+  });
+  return cast.map((el) => {
+    const avatar = el.same_as ? byLabel.get(el.same_as) : void 0;
+    return avatar ? { ...el, source_image: avatar.sheetUrl, source_is_sheet: true } : el;
+  });
+}
+function avatarsNotCast(elementsInput, handles) {
+  const people = RecurringElements.parse(elementsInput).filter(
+    (el) => el.type.toLowerCase() === "person" && !el.same_as
+  ).length;
+  return handles.slice(people);
+}
 function sanitizeId(raw, fallback) {
   const id = raw.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
   return /^[a-z]/.test(id) ? id : `${fallback}_${id}`.replace(/_+$/g, "") || fallback;
@@ -37629,6 +37671,12 @@ function genAspectsFor(videoModel) {
   if (/kling/.test(videoModel)) return ["1:1", "16:9", "9:16"];
   return SEEDANCE_GEN_ASPECTS;
 }
+function stampCastEntry(entry, el, label) {
+  entry.reference_image = label;
+  if (el.source_is_sheet && !el.same_as && el.type.toLowerCase() === "person" && el.description) {
+    recastPersonEntry(entry, el.description);
+  }
+}
 function annotateBlueprintWithElements(blueprintInput, elementsInput) {
   if (!blueprintInput || typeof blueprintInput !== "object") return blueprintInput;
   const elements = RecurringElements.parse(elementsInput);
@@ -37638,10 +37686,8 @@ function annotateBlueprintWithElements(blueprintInput, elementsInput) {
   for (const { el, label } of assignElementLabels(elements)) {
     const scenes = [...presenceOf(el).keys()].sort((a, b) => a - b);
     summary.push({ reference_image: label, type: el.type, description: el.description ?? null, scenes });
-    if (el.cast_id && Array.isArray(cast)) {
-      const entry = cast.find((c) => c?.id === el.cast_id);
-      if (entry && typeof entry === "object") entry.reference_image = label;
-    }
+    const entry = el.cast_id && Array.isArray(cast) ? cast.find((c) => c?.id === el.cast_id) : void 0;
+    if (entry && typeof entry === "object") stampCastEntry(entry, el, label);
   }
   clone.reference_elements = summary;
   return clone;
@@ -37715,8 +37761,11 @@ function todoPath(el, label) {
   const desc = el.description ? ` \u2014 ${el.description}` : "";
   const expr = el.expression ? `, with a ${el.expression} expression` : "";
   const t = el.type.toLowerCase();
-  const fresh = t === "person" || t === "animal" || t === "location" ? " [SOURCE FRESH \u2014 a DIFFERENT person/animal/set than the original ad; do not reuse the source's individual]" : "";
+  const fresh = t === "animal" || t === "location" ? " [SOURCE FRESH \u2014 a DIFFERENT animal/set than the original ad; do not reuse the source's]" : "";
   const same = el.same_as ? ` [SAME INDIVIDUAL as ${el.same_as} \u2014 a different wardrobe/look of the same person; reuse that cast person, change only the outfit]` : "";
+  if (t === "person") {
+    return `[TODO: cast a company Avatar as ${label} (person)${desc}${expr}${same} \u2014 re-run scaffold-video with \`--avatar <handle>\` (\`baker avatars list\`; \`baker avatars create\` invents a new face). NEVER a photo of a real person found on the web or taken from the source ad: the image model reproduces that face]`;
+  }
   return `[TODO: drop one real source image for ${label} (${el.type})${desc}${expr} \u2014 reused across every frame it appears in${fresh}${same}; use a path relative to this canvas file, never an absolute path]`;
 }
 function buildElementSlots(elements) {
@@ -37967,7 +38016,7 @@ function buildFrameRef(edge, url, framePrompt, present2, ctx, nodes) {
     const t = s.type.toLowerCase();
     return t === "person" || t === "animal";
   });
-  const useOriginalAnchor = Boolean(url) && castSlots.length === 0;
+  const useOriginalAnchor = Boolean(url) && castSlots.length === 0 && !ctx.sourceShowsPeople;
   const hasOriginal = useOriginalAnchor;
   const originalRef = useOriginalAnchor && url ? ingestFrameRef(url, edge, ctx, nodes) : void 0;
   const presentOrdered = orderSlotsByIdentity(present2);
@@ -38433,6 +38482,7 @@ function buildCompositeScene(layout, regions, comp, scene, i, present2, mode, na
       sceneIndex: i,
       genAr: opts.genAr,
       reuse: opts.reuse,
+      sourceShowsPeople: opts.sourceShowsPeople,
       imageModel: opts.imageModel,
       shootMode: mode,
       sceneStyle: sceneStyleOf(scene),
@@ -38708,6 +38758,9 @@ function onCameraDialogue(blueprint) {
   const mode = blueprint.global?.voiceover?.mode;
   return mode !== "voiceover" && mode !== "none";
 }
+function sourceShowsPeople(blueprint, slots) {
+  return (blueprint.global?.cast ?? []).length > 0 || slots.some((s) => s.type.toLowerCase() === "person");
+}
 var castIdSet = (blueprint) => new Set((blueprint.global?.cast ?? []).map((c) => c.id).filter((id) => Boolean(id)));
 var LANGUAGE_WORDS = [
   [/\b(french|fran[çc]ais|francaise)\b/, "french"],
@@ -39023,6 +39076,7 @@ function emitPhraseClip(phrase, voiceNode, env, nodes, out) {
     sceneIndex: anchor,
     genAr: env.genAr,
     reuse: env.reuse,
+    sourceShowsPeople: env.sourceShowsPeople,
     imageModel: env.opts.imageModel,
     shootMode: mode,
     sceneStyle: sceneStyleOf(anchorScene),
@@ -39217,6 +39271,7 @@ function emitCompositeInTimeline(composite, scene, i, isLast, env, canonical2, e
       outAr: env.outAr,
       genAr: env.genAr,
       reuse: env.reuse,
+      sourceShowsPeople: env.sourceShowsPeople,
       imageModel: env.opts.imageModel,
       videoModel: env.opts.videoModel,
       resolution: env.opts.resolution,
@@ -39313,6 +39368,7 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
     sceneIndex: i,
     genAr: env.genAr,
     reuse: env.reuse,
+    sourceShowsPeople: env.sourceShowsPeople,
     imageModel: env.opts.imageModel,
     shootMode: mode,
     sceneStyle: sceneStyleOf(scene),
@@ -39413,6 +39469,7 @@ function buildTimeline(blueprint, slots, opts, nodes) {
     outAr: aspect.outAr,
     genAr: aspect.genAr,
     reuse,
+    sourceShowsPeople: sourceShowsPeople(blueprint, slots),
     cameraOn: onCameraDialogue(blueprint),
     casts: castIdSet(blueprint),
     ingestCache: /* @__PURE__ */ new Map(),
@@ -39943,11 +40000,7 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
     nodes.push({
       id: slot.id,
       type: "ingest",
-      params: {
-        source: "path",
-        path: supplied || todoPath(element, slot.label),
-        expect: "image"
-      }
+      params: /^https?:\/\//i.test(supplied) ? { source: "url", url: supplied, expect: "image" } : { source: "path", path: supplied || todoPath(element, slot.label), expect: "image" }
     });
   });
   buildElementSheets(slots, nodes, opts.sheetModel);
@@ -40201,7 +40254,7 @@ var VIDEO_GUIDE = [
   "0. RE-CRAFT THE SCRIPT FIRST (don't clone). This reference already won in-market, but copying a video is much harder than a static: the hook is targeting and may not transfer, and the message must become TRUE for our brand. Work the `metadata.todo.script_recraft` checklist \u2014 for each scene judge its role (hook/body/CTA), decide keep/cut/reorder/replace, and re-author every line for OUR customer's pain + OUR offer. See `references/script-craft.md` (hook/body/CTA framework) and the `meta-ads-playbook` skill. Most of the work lives here.",
   "1. Edit each frame's prompt IN PLACE. Every `s<i>_start` keyframe 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. The frame is RECAST to the el_* reference images you drop (the source ad's people are never reused), so describe pose/action/framing here and let the references carry identity.",
   "1b. STORYBOARD FIRST \u2014 align the look on the cheap stills before clips bill. Each scene's keyframe IS your storyboard; `metadata.video.motion_board` lays out each scene's frame, time window, spoken line, and the graphics scheduled in it. Lock the keyframes + check each graphic lands on its spoken beat, THEN run the clips (images are cheap, videos aren't; the cache re-bills only what you change). See references/video-reproduce.md.",
-  "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.",
+  "2. Fill each `el_*` ingest `[TODO]` path. A PERSON is a company Avatar's identity sheet, cast by re-scaffolding with `--avatar <handle>` (a sheet URL pasted by hand would be sheeted again) \u2014 never a photo of a real person, whose face the image model would reproduce; every other element is ONE real source image. Each 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. Talking heads are NATIVE: a scene with one on-camera speaker is voiced by the video model itself (the line goes in the clip's prompt; models with a `generate_audio` toggle get it set, and the default model always renders audio), so lips and voice are generated together \u2014 no separate tts, no post-hoc lip-sync. Edit the line in the scene's `s<i>_clip` prompt to re-author the words TRUE for your brand. Off-camera narration scenes still use a sequenced `tts` per turn.",
   "4. Voice consistency: every native talking clip's audio is re-voiced to ONE brand voice via `audio_voice_convert` (timing preserved \u2192 lips stay matched). Confirm the `voice_select` casting (one per speaker) \u2014 its `voice_id` is the brand voice; set its gender/language so the voice matches the creator.",
   "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 source (`baker images icon/sticker/gif/logo`) and 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.",
@@ -40269,7 +40322,7 @@ function buildVideoTodo(report, overlayCount, floatingCount, opts, blueprint) {
     review_storyboard_before_clips: "STORYBOARD FIRST. Each scene's keyframe (s<i>_start) IS your storyboard \u2014 align the LOOK on it before clips bill. Images are cheap, videos aren't, and the content-addressed cache re-bills only changed nodes, so iterate prompts here first and let the storyboard lock before the video_generate clips run. `metadata.video.motion_board` lists each scene's keyframe, window, spoken line, and the graphics scheduled in it \u2014 walk it scene by scene.",
     motion_board: "`metadata.video.motion_board` maps which overlay/graphic fires on which spoken beat (per scene: window_s, spoken line, each graphic's at_s). Review it so every graphic lands on the word it punctuates \u2014 don't let an overlay drift off its beat. Adjust an overlay's data-start in video-overlay-composition/index.html (or appears_at_s in prompt.json) to retime it.",
     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.",
-    sourcing: 'Resolve each el_* [TODO]: (1) the client\'s OWN assets first \u2014 `baker images library "<subject>"` (e.g. the company owner as the actor) and `baker images logo <domain>` for the brand mark; (2) otherwise search a FRESH real reference \u2014 `baker images find "<subject>" --sources pinterest` (Pinterest is photo-real/candid, best for people & sets) or generate one with the image model. el_creator_* and el_location are [SOURCE FRESH]: cast a DIFFERENT person/animal/set than the original ad \u2014 never the source\'s individual.',
+    sourcing: 'Resolve each el_* [TODO]: a PERSON is a company Avatar \u2014 pass `--avatar <handle>` to scaffold-video (`baker avatars list`; `baker avatars create` for a new invented face) \u2014 re-scaffold rather than paste a sheet URL at the slot, which would be sheeted again; never a photo of a real person from the web or the source ad, because the image model reproduces that face. Everything else: the client\'s OWN assets first \u2014 `baker images library "<subject>"` and `baker images logo <domain>` for the brand mark; otherwise a FRESH real reference \u2014 `baker images find "<subject>" --sources pinterest` (photo-real/candid, best for pets, sets and objects) or generate one with the image model. el_location and animals are [SOURCE FRESH]: a DIFFERENT set/animal than the original ad.',
     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 audio. You don't manage it.",
@@ -40378,7 +40431,8 @@ function videoReport(input, elementsInput) {
       type: el.type,
       description: el.description ?? null,
       scenes: [...presenceOf(el).keys()].sort((a, b) => a - b),
-      asset_todo: todoPath(el, label)
+      asset_todo: el.source_image?.trim() ? null : todoPath(el, label),
+      ...el.source_image?.trim() ? { source_image: el.source_image.trim() } : {}
     })),
     dialogue,
     sfx_count: sfxCount,
@@ -42256,7 +42310,6 @@ import { z as z43 } from "zod";
 var GEN_ASPECT_RATIOS = /* @__PURE__ */ new Set(["1:1", "4:5", "9:16", "16:9", "4:3", "3:4", "2:3", "3:2", "21:9"]);
 var DEFAULT_ASPECT_RATIO = "9:16";
 var SHEET_SUBJECT_TYPE2 = {
-  person: "person",
   animal: "character"
 };
 var ACTOR_SHEET_MODEL2 = "google/gemini-3-pro-image-preview";
@@ -42266,7 +42319,8 @@ var ADAPT_IMAGE_SIZE = "2K";
 var ADAPT_GUIDANCE = "Keep the headline, logo, CTA, and hero subject fully visible in every ratio. Reproduce every text string verbatim \u2014 no dropped, added, or altered characters \u2014 and preserve the exact brand-color treatment (e.g. a black\u2192red word pivot), never flattening it.";
 var Blueprint = z43.object({
   meta: z43.object({ estimated_aspect_ratio: z43.string().optional() }).loose().optional(),
-  text_content: z43.array(z43.object({ text: z43.string().optional() }).loose()).optional()
+  text_content: z43.array(z43.object({ text: z43.string().optional() }).loose()).optional(),
+  people: z43.array(z43.unknown()).optional()
 }).loose();
 var ElementLocator = z43.object({
   collection: z43.enum(["subjects", "people", "brands_logos"]),
@@ -42282,6 +42336,24 @@ var MainElement = z43.object({
   locator: ElementLocator.optional()
 }).loose();
 var MainElements = z43.array(MainElement);
+var isPerson = (el) => el.type.toLowerCase() === "person";
+function castAvatarsOnStaticElements(elementsInput, avatars) {
+  let next = 0;
+  return MainElements.parse(elementsInput).map((el) => {
+    const avatar = isPerson(el) ? avatars[next] : void 0;
+    if (!avatar) return el;
+    next += 1;
+    const description = avatar.subjectDescription?.trim();
+    return { ...el, ...description ? { description } : {}, source_image: avatar.sheetUrl };
+  });
+}
+function staticAvatarsNotCast(elementsInput, handles) {
+  return handles.slice(MainElements.parse(elementsInput).filter(isPerson).length);
+}
+function suppliedImage(el) {
+  const url = typeof el.source_image === "string" ? el.source_image.trim() : "";
+  return /^https?:\/\//i.test(url) ? url : void 0;
+}
 function sanitizeId2(raw, fallback) {
   const id = raw.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
   return /^[a-z]/.test(id) ? id : `${fallback}_${id}`.replace(/_+$/g, "") || fallback;
@@ -42308,7 +42380,9 @@ function annotateBlueprintWithLabels(blueprintInput, elementsInput) {
     const collection = clone[loc.collection];
     const entry = Array.isArray(collection) ? collection[loc.index] : void 0;
     if (entry && typeof entry === "object") {
-      entry.reference_image = label;
+      const record = entry;
+      record.reference_image = label;
+      if (suppliedImage(el) && isPerson(el) && el.description) recastPersonEntry(record, el.description);
     }
   }
   return clone;
@@ -42322,6 +42396,7 @@ function roleForType2(type) {
     case "product":
       return "the showcased product; keep this exact product identity. Ignore any caption text printed on this reference.";
     case "person":
+      return "the emotional hero \u2014 the brand's cast person: a company Avatar's identity sheet, a multi-view turnaround of ONE person the brand may show. Keep this exact face, hair and build, and render them once in the pose, gaze, wardrobe and expression the blueprint specifies \u2014 never as a grid. Ignore the cell labels printed on the sheet.";
     case "animal":
       return "the emotional hero \u2014 the face/muzzle/eyes the viewer locks onto and exactly where AI artifacts (malformed mouths, teeth, foam, extra fingers) betray a fake. It MUST be grounded in this real reference, never invented from prose. Keep this identity AND the expression the blueprint specifies. Ignore any caption text printed on this reference.";
     default:
@@ -42332,7 +42407,10 @@ function todoPath2(el, label) {
   const desc = el.description ? ` \u2014 ${el.description}` : "";
   const expr = el.expression ? `, with a ${el.expression} expression` : "";
   const t = el.type.toLowerCase();
-  const lock = t === "person" || t === "animal" ? " \u2014 REQUIRED: this is the emotional hero; ground it in a real reference (image-library / video-library / Pinterest), do not delete this slot and free-generate" : "";
+  if (t === "person") {
+    return `[TODO: cast a company Avatar as ${label} (person)${desc}${expr} \u2014 REQUIRED: this is the emotional hero and the render keeps this face, so re-run scaffold-static-ad with \`--avatar <handle>\` (\`baker avatars list\`; \`baker avatars create\` invents a new face); never a found photo of a real person (web search, the source ad), who never agreed to appear in this ad]`;
+  }
+  const lock = t === "animal" ? " \u2014 REQUIRED: this is the emotional hero; ground it in a real reference (image-library / video-library / Pinterest), do not delete this slot and free-generate" : "";
   return `[TODO: drop a real image for ${label} (${el.type})${desc}${expr}${lock} \u2014 replace with a path relative to this canvas file, never an absolute path]`;
 }
 function sheetSubjectDescription(el) {
@@ -42372,6 +42450,9 @@ function textFidelityDirective(blueprint, hasFont) {
     "Keep all type crisp, legible, and large enough to read cleanly; no garbled, warped, or duplicated characters, and no unreadable microtext."
   ].join("\n");
 }
+function showsPerson(blueprint, elements) {
+  return (blueprint.people?.length ?? 0) > 0 || elements.some(isPerson);
+}
 function scaffoldStaticAd(input, elementsInput, opts) {
   const blueprint = Blueprint.parse(input);
   const elements = MainElements.parse(elementsInput);
@@ -42394,10 +42475,11 @@ function scaffoldStaticAd(input, elementsInput, opts) {
     let id = sanitizeId2(`el_${label}`, `el_${i}`);
     while (usedIds.has(id)) id = `${id}_${i}`;
     usedIds.add(id);
+    const supplied = suppliedImage(el);
     nodes.push({
       id,
       type: "ingest",
-      params: { source: "path", path: todoPath2(el, label), expect: "image" }
+      params: supplied ? { source: "url", url: supplied, expect: "image" } : { source: "path", path: todoPath2(el, label), expect: "image" }
     });
     let ref = `$ref:${id}.asset`;
     const subjectType = includeActorSheets ? SHEET_SUBJECT_TYPE2[el.type.toLowerCase()] : void 0;
@@ -42437,15 +42519,18 @@ function scaffoldStaticAd(input, elementsInput, opts) {
       params: { text: specimenText(blueprint), font_size: 72, line_height: 1.2, max_width: 1600 }
     });
   }
+  const originalAsReference = !showsPerson(blueprint, elements);
   const reference = [
     ...elementSlots.map((s) => s.ref),
     ...hasFont ? ["$ref:type_ref.image"] : [],
-    "$ref:original.asset"
+    ...originalAsReference ? ["$ref:original.asset"] : []
   ];
   const legend = [
     ...elementSlots.map((s) => `- ${s.label} \u2014 ${roleForType2(s.type)}`),
     ...hasFont ? ["- TYPE SPECIMEN \u2014 render every text string in this exact typeface; ignore its color and layout."] : [],
-    "- ORIGINAL \u2014 use ONLY for composition, layout, and proportions. IGNORE its text, its logo, its brand name, and its colors entirely \u2014 they belong to a different brand."
+    ...originalAsReference ? [
+      "- ORIGINAL \u2014 use ONLY for composition, layout, and proportions. IGNORE its text, its logo, its brand name, and its colors entirely \u2014 they belong to a different brand."
+    ] : []
   ].join("\n");
   const exclusionsLast = imageProfileFor(opts.genModel)?.constraintPlacement === "last";
   const exclusionsBlock = "Exclusions: no invented badges, icons, or seals; render exactly the subjects the blueprint names and no others; no competitor branding; no watermark.";
@@ -42454,9 +42539,11 @@ function scaffoldStaticAd(input, elementsInput, opts) {
     "",
     "Commit to ONE dominant capture/render treatment for the whole ad \u2014 do not stack conflicting camera, lens, lighting, or style specs; take the look from the blueprint.",
     "",
-    "REFERENCE IMAGES (in the order provided) \u2014 the blueprint refers to these by their reference_image label:",
-    legend,
-    "",
+    ...reference.length > 0 ? [
+      "REFERENCE IMAGES (in the order provided) \u2014 the blueprint refers to these by their reference_image label:",
+      legend,
+      ""
+    ] : [],
     "TEXT \u2014 RENDER THE COPY EXACTLY:",
     textFidelityDirective(blueprint, hasFont),
     "",
@@ -42472,7 +42559,9 @@ function scaffoldStaticAd(input, elementsInput, opts) {
   nodes.push({
     id: "gen",
     type: "image_generate",
-    inputs: { reference, target_blueprint: "$ref:prompt.asset" },
+    // An empty list fails the node's schema (`min(1)`): with nothing to ground on
+    // (no element, no font, a person in the original) the blueprint renders alone.
+    inputs: { ...reference.length > 0 ? { reference } : {}, target_blueprint: "$ref:prompt.asset" },
     params: {
       model: opts.genModel,
       // The hero renders at the closest ratio its model actually accepts; the
@@ -42509,7 +42598,7 @@ function scaffoldStaticAd(input, elementsInput, opts) {
     schema: "baker-canvas/1",
     metadata: {
       name: "static ad reproduction",
-      description: "Scaffolded by `baker canvas scaffold-static-ad`. Edit `prompt.json` (the blueprint generated from the source image) into the ad you want, drop a real asset at each [TODO] ingest path (logo/product/subject/badge + brand font), then `baker canvas run`. The original is wired for composition only."
+      description: "Scaffolded by `baker canvas scaffold-static-ad`. Edit `prompt.json` (the blueprint generated from the source image) into the ad you want, drop a real asset at each [TODO] ingest path (logo/product/subject/badge + brand font), then `baker canvas run`. The original is wired for composition only, and left out of the render when it shows a person, whose face the generator would copy."
     },
     nodes,
     output: fanOut ? { node: "adapt", output: "images" } : { node: "gen", output: "images" }
@@ -42525,7 +42614,7 @@ function staticAdReport(input, elementsInput, opts) {
       label,
       type: el.type,
       description: el.description ?? null,
-      asset_todo: todoPath2(el, label)
+      asset_todo: suppliedImage(el) ? "none \u2014 cast from a company Avatar's identity sheet" : todoPath2(el, label)
     })),
     includes_font: opts.includeFont !== false,
     actor_sheets: includeActorSheets ? assignElementLabels2(elements).filter(({ el }) => SHEET_SUBJECT_TYPE2[el.type.toLowerCase()]).map(({ label }) => label) : [],
@@ -42748,6 +42837,35 @@ var syncDefinitionCommand = defineCommand113({
   }
 });
 
+// src/commands/avatars/resolveCast.ts
+async function resolveCastAvatar(handle) {
+  try {
+    const avatar = await readAvatars("/api/avatars/get", { handle });
+    if (avatar.status && avatar.status !== "ready") {
+      return {
+        error: `Avatar \`${handle}\` is ${avatar.status}, not ready \u2014 \`baker avatars get ${handle} --wait\` returns the moment it is.`
+      };
+    }
+    if (!avatar.sheetUrl)
+      return { error: `Avatar \`${handle}\` has no identity sheet yet, so the ad cannot ground on their face.` };
+    return { sheetUrl: avatar.sheetUrl, subjectDescription: avatar.subjectDescription };
+  } catch (e) {
+    return {
+      error: `Could not read avatar \`${handle}\`: ${e instanceof Error ? e.message : String(e)}. \`baker avatars list\` shows who there is.`
+    };
+  }
+}
+async function resolveCastAvatars(flag) {
+  const handles = String(flag ?? "").split(",").map((h) => h.trim()).filter(Boolean);
+  const avatars = [];
+  for (const handle of handles) {
+    const resolved = await resolveCastAvatar(handle);
+    if ("error" in resolved) return resolved;
+    avatars.push(resolved);
+  }
+  return { handles, avatars };
+}
+
 // src/commands/canvas/scaffold-static-ad.ts
 async function fileExists(target2) {
   try {
@@ -42951,7 +43069,7 @@ async function runVisionPasses(canvas) {
 var scaffoldStaticAdCommand = defineCommand114({
   meta: {
     name: "scaffold-static-ad",
-    description: "Turn a source/inspiration image into a runnable static-ad canvas. Runs billed passes \u2014 image_describe (the blueprint, baked to prompt.json as the editable 'prompt'), an AI selection of the image's MAIN identity elements, and a structured global-layout pass (the column/row grid with per-region bounds and text sizes) \u2014 then scaffolds a canvas that wires one [TODO] ingest slot per element (logo/product/subject/badge + brand font) into image_generate. By default it also fans the hero out to the platform's placement ratios (via image_aspect_adapt \u2014 the hero ratio is free, the rest are billed AI recompositions); pass --placements none for a single base ad, or a preset to pick the set. Edit prompt.json and drop the real assets, then `baker canvas run` it."
+    description: "Turn a source/inspiration image into a runnable static-ad canvas. Runs billed passes \u2014 image_describe (the blueprint, baked to prompt.json as the editable 'prompt'), an AI selection of the image's MAIN identity elements, and a structured global-layout pass (the column/row grid with per-region bounds and text sizes) \u2014 then scaffolds a canvas that wires one [TODO] ingest slot per element (logo/product/subject/badge + brand font) into image_generate. By default it also fans the hero out to the platform's placement ratios (via image_aspect_adapt \u2014 the hero ratio is free, the rest are billed AI recompositions); pass --placements none for a single base ad, or a preset to pick the set. Edit prompt.json and drop the real assets, then `baker canvas run` it. Start here: `baker avatars list`, then pass `--avatar <handle>` when the image shows a person \u2014 the ad's people are played by the company's avatars, never by a photo of anyone real."
   },
   args: {
     file: { type: "positional", required: true, description: "Path or http(s) URL to the source/inspiration image" },
@@ -42979,7 +43097,11 @@ var scaffoldStaticAdCommand = defineCommand114({
     "skip-font": { type: "boolean", description: "Skip the brand-font \u2192 type-specimen slot" },
     "skip-actor-sheets": {
       type: "boolean",
-      description: "Ground each person/animal on its lone dropped photo instead of a generated multi-view sheet"
+      description: "Ground each animal hero on its lone dropped photo instead of a generated multi-view sheet (a person hero always grounds on the company Avatar sheet cast with --avatar)"
+    },
+    avatar: {
+      type: "string",
+      description: "Cast company avatars as the ad's people \u2014 pass this whenever the image has a person in it. One handle, or several comma-separated in the order the people were detected (`--avatar marta` / `--avatar marta,joan`). Each person slot grounds on that avatar's identity sheet and prompt.json describes them in the avatar's own words, so the ad shows the company's cast instead of the source ad's. `baker avatars list` shows who there is; checked before anything is billed."
     }
   },
   async run({ args: args5 }) {
@@ -42999,6 +43121,8 @@ var scaffoldStaticAdCommand = defineCommand114({
     );
     await mkdir6(path21.dirname(outPath), { recursive: true });
     const { describeModel, selectModel, layoutModel, genModel } = resolveModels(args5);
+    const cast = await resolveCastAvatars(args5.avatar);
+    if ("error" in cast) return fail3("avatar", cast.error);
     let durableSourceUrl;
     if (referencesDir) {
       const client = buildBackendClient();
@@ -43018,7 +43142,10 @@ var scaffoldStaticAdCommand = defineCommand114({
       layoutModel,
       args5.context ? String(args5.context) : void 0
     );
-    const { blueprint, elements, layout, creditsSpent } = await runVisionPasses(describeCanvas);
+    const vision = await runVisionPasses(describeCanvas);
+    const { blueprint, layout, creditsSpent } = vision;
+    const elements = castAvatarsOnStaticElements(vision.elements, cast.avatars);
+    const uncast = staticAvatarsNotCast(vision.elements, cast.handles);
     const annotated = annotateBlueprintWithLabels(blueprint, elements);
     if (layout && annotated && typeof annotated === "object") {
       annotated.layout = layout;
@@ -43106,6 +43233,11 @@ var scaffoldStaticAdCommand = defineCommand114({
           definition_path: definitionPath ?? void 0,
           source_reference: durableSourceUrl ?? void 0,
           output: canvas.output,
+          ...uncast.length ? {
+            hints: [
+              `NOT CAST: ${uncast.map((h) => `\`${h}\``).join(", ")} \u2014 the element selection found fewer people than avatars passed, so ${uncast.length === 1 ? "this avatar plays" : "these avatars play"} nobody in this ad. Tell the user who is cast and who is not.`
+            ]
+          } : {},
           models: { describe: describeModel, select: selectModel, layout: layoutModel, gen: opts.genModel },
           aspect_ratio: report.aspect_ratio,
           placements: report.placements,
@@ -43120,7 +43252,7 @@ var scaffoldStaticAdCommand = defineCommand114({
             edit_prompt: `Edit ${path21.basename(blueprintPath)} \u2014 it is the blueprint generated from your image; rewrite it into the ad you want (palette, copy, claims, subjects). It feeds the generator directly.`,
             assets_to_supply: report.elements,
             font_slot: report.includes_font ? "Drop a brand font at the [TODO] brandfont path (the describe pass recorded the ad's typefaces under `fonts` in prompt.json \u2014 match those). The font is wired into the render as a TYPE SPECIMEN reference so generated text takes the brand letterforms. Delete the brandfont + type_ref nodes to skip it." : "skipped (--skip-font)",
-            actor_sheets: report.actor_sheets.length > 0 ? `Each living hero (${report.actor_sheets.join(", ")}) is fused into a generated multi-view reference sheet (image_reference_sheet) that the render grounds on \u2014 so drop ONE clean photo at that hero's ingest and the sheet builds the consistent turnaround. Pass --skip-actor-sheets to ground on the lone photo instead.` : "none (no person/animal heroes detected, or --skip-actor-sheets)",
+            actor_sheets: report.actor_sheets.length > 0 ? `Each animal hero (${report.actor_sheets.join(", ")}) is fused into a generated multi-view reference sheet (image_reference_sheet) that the render grounds on \u2014 so drop ONE clean photo at that hero's ingest and the sheet builds the consistent turnaround. Pass --skip-actor-sheets to ground on the lone photo instead. A person hero is cast from a company Avatar (--avatar <handle>), never a found photo.` : "none (no animal heroes detected, or --skip-actor-sheets). A person hero is cast from a company Avatar (--avatar <handle>), never a found photo.",
             placements: report.placements === null ? `Single format (${report.aspect_ratio}). Pass --placements meta_feed_stories|meta_all|linkedin|\u2026 to auto-fan-out to a platform's set.` : `Auto-fans the approved hero out to ${report.placements} \u2192 ${report.output_formats.join(", ")}. The hero ratio (${report.aspect_ratio}) passes through free; each other ratio is a billed render, AI-recomposed (not cropped). Re-read the copy and confirm the brand-color treatment on EVERY ratio before publishing \u2014 adaptation re-generates and can silently mangle text or flatten a color device. Pass --placements none for a single base ad.`,
             note: "Populate as you go: for each [TODO] ingest slot, source its real asset and wire it into the slot right away \u2014 one at a time, not all sourced first then reconciled at the end. For any LOGO slot, use the company's committed brand logo from `src/brand/logos/` (per BRAND.md's Logos map) \u2014 do NOT re-fetch it with `baker images logo <domain>` when a brand logo exists, because the Brandfetch CDN often serves an OUTDATED mark and that is how an old logo ships on a live ad. When every slot is filled, `baker canvas validate` then `baker canvas run`. Running generates a billed image \u2014 it is not free."
           }
@@ -44987,7 +45119,7 @@ async function runAnalysisPasses(deconstructCanvas, selectModel) {
 var scaffoldVideoCommand = defineCommand116({
   meta: {
     name: "scaffold-video",
-    description: "Turn a reference video into a runnable reproduction canvas in one command. Runs billed passes \u2014 video_deconstruct (the full scene-by-scene blueprint + transcript, baked to a split, editable blueprint: a global prompt.json plus one small scenes/sNN.json per scene) and an AI selection of the video's RECURRING identity elements (person/animal/product/logo) \u2014 then scaffolds a pipeline where every scene boundary is a static-ad-grade frame (the blueprint as target_blueprint, a reference legend, the real frame as anchor) and each recurring element gets ONE shared [TODO] ingest slot wired into every frame it appears in. The clips feed Seedance an ultra-detailed motion brief (action, camera, dialogue, transcript). Edit a scene's scenes/sNN.json (or prompt.json for global cast/palette/brand), drop the real source images, then `baker canvas run`."
+    description: "Turn a reference video into a runnable reproduction canvas in one command. Runs billed passes \u2014 video_deconstruct (the full scene-by-scene blueprint + transcript, baked to a split, editable blueprint: a global prompt.json plus one small scenes/sNN.json per scene) and an AI selection of the video's RECURRING identity elements (person/animal/product/logo) \u2014 then scaffolds a pipeline where every scene boundary is a static-ad-grade frame (the blueprint as target_blueprint, a reference legend, the real frame as anchor) and each recurring element gets ONE shared [TODO] ingest slot wired into every frame it appears in. The clips feed Seedance an ultra-detailed motion brief (action, camera, dialogue, transcript). Edit a scene's scenes/sNN.json (or prompt.json for global cast/palette/brand), fill the remaining [TODO] images, then `baker canvas run`. Start here: `baker avatars list`, then pass `--avatar <handle>` when the video shows a person \u2014 the reference's people are played by the company's avatars, never by a photo of anyone real."
   },
   args: {
     file: {
@@ -45051,6 +45183,10 @@ var scaffoldVideoCommand = defineCommand116({
     resolution: {
       type: "string",
       description: `Output resolution for generated clips (e.g. "1080p"). Default 1080p \u2014 the highest the video model supports \u2014 so clips keep the keyframe sharpness instead of the model's low default.`
+    },
+    avatar: {
+      type: "string",
+      description: "Cast company avatars as the reference's people \u2014 pass this whenever the video has a person in it. One handle, or several comma-separated in the order the people appear (`--avatar marta` / `--avatar marta,joan`). Each recurring person grounds on that avatar's identity sheet, so the ad shows the company's own cast instead of the source ad's actors. `baker avatars list` shows who there is; checked before anything is billed."
     }
   },
   async run({ args: args5 }) {
@@ -45090,6 +45226,9 @@ var scaffoldVideoCommand = defineCommand116({
       );
     }
     const { deconstructModel, selectModel, imageModel } = resolveModels2(args5);
+    const cast = await resolveCastAvatars(args5.avatar);
+    if ("error" in cast) return fail4("avatar", cast.error);
+    const { handles: avatarHandles, avatars } = cast;
     const shotThreshold = args5["shot-threshold"] ? Number(args5["shot-threshold"]) : void 0;
     const shotCuts = await detectShotCutsBestEffort(videoPath, shotThreshold);
     const deconstructCanvas = buildDeconstructCanvas(videoPath, deconstructModel, {
@@ -45098,7 +45237,15 @@ var scaffoldVideoCommand = defineCommand116({
       focus: args5.focus ? String(args5.focus) : void 0,
       shotCuts
     });
-    const { blueprint, elements, transcript, creditsSpent } = await runAnalysisPasses(deconstructCanvas, selectModel);
+    const analysis = await runAnalysisPasses(deconstructCanvas, selectModel);
+    const { blueprint, transcript, creditsSpent } = analysis;
+    const elements = castAvatarsOnElements(analysis.elements, avatars);
+    const uncast = avatarsNotCast(analysis.elements, avatarHandles);
+    const uncastHint = uncast.length ? {
+      hints: [
+        `NOT CAST: ${uncast.map((h) => `\`${h}\``).join(", ")} \u2014 the element selection found no more recurring people than it cast, so ${uncast.length === 1 ? "this avatar plays" : "these avatars play"} nobody in this canvas. A person shown in only one scene is not a recurring element, so those frames render whoever their scene file describes \u2014 tell the user who is cast and who is not.`
+      ]
+    } : {};
     const { videoModel, videoRouteReason } = resolveVideoModel(args5, elements);
     if (videoRouteReason && !args5["video-model"] && !args5["real-face"] && hasPhotorealCast(elements)) {
       process.stderr.write(`\u{1F3AC} Photoreal on-camera cast detected \u2192 generating clips on ${videoModel} (dodges Seedance's real-person filter).
@@ -45188,7 +45335,8 @@ var scaffoldVideoCommand = defineCommand116({
             error: { code: "validation", issues: validation.issues },
             canvas_path: outPath,
             prompt_path: blueprintPath,
-            note: "The canvas WAS written despite the blocking issue(s) \u2014 fix them in place, then `baker canvas validate` before running."
+            note: "The canvas WAS written despite the blocking issue(s) \u2014 fix them in place, then `baker canvas validate` before running.",
+            ...uncastHint
           },
           null,
           2
@@ -45237,6 +45385,7 @@ var scaffoldVideoCommand = defineCommand116({
           source_reference: sourceRef.url,
           composition_dir: compositionDest,
           output: canvas.output,
+          ...uncastHint,
           frames_mode: frames,
           models: {
             deconstruct: deconstructModel,
@@ -45280,7 +45429,7 @@ var scaffoldVideoCommand = defineCommand116({
             ...report.elements.some((e) => e.type === "person" || e.type === "animal") && /seedance/i.test(videoModel) ? {
               content_policy_risk: "You FORCED Seedance (`--video-model bytedance/seedance-2.0`) on an ad with a photoreal on-camera cast. ByteDance's real-person filter will reject those clips (content_policy_blocked, E005) \u2014 no prompt change clears it. Each clip auto-recovers on Veo at render time so the run still completes, but you burn a wasted Seedance attempt per clip. Drop `--video-model` to let the scaffold route the cast to Veo up front, or make the frames less photorealistic."
             } : {},
-            note: "Drop ONE real source image at each el_* [TODO] (reused across every frame that element appears in), confirm each voice_select casting, then `baker canvas validate` and `baker canvas run`. Running generates many billed image/video/audio assets \u2014 it is not free."
+            note: "Fill each el_* [TODO] \u2014 a person with a company avatar's identity sheet (`--avatar <handle>`), never a photo of a real person; anything else with ONE real source image (reused across every frame that element appears in) \u2014 confirm each voice_select casting, then `baker canvas validate` and `baker canvas run`. Running generates many billed image/video/audio assets \u2014 it is not free."
           }
         },
         null,