@koda-sl/baker-cli 0.362.0 → 0.364.0-dev.18349e66a

package/dist/cli.js

@@ -69,7 +69,7 @@ import {
   validateCanvasDeep,
   withoutCastName,
   ytDlpBlockSignal
-} from "./chunk-AI4HWQVN.js";
+} from "./chunk-K2IKLMCM.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -22933,9 +22933,49 @@ Subcommands:
 
 // src/commands/ads/linkedin/creatives.ts
 import { defineCommand as defineCommand44 } from "citty";
+
+// src/commands/ads/list-rows.ts
 function asRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
 }
+function readPath2(row, path48) {
+  let current = row;
+  for (const segment of path48.split(".")) {
+    const record = asRecord(current);
+    if (!record) return void 0;
+    current = record[segment];
+  }
+  return current;
+}
+function projectFields(rows, paths) {
+  return rows.map((row) => {
+    const projected = {};
+    for (const path48 of paths) {
+      const value = readPath2(row, path48);
+      if (value !== void 0) {
+        projected[path48] = value;
+      }
+    }
+    return projected;
+  });
+}
+function shapeListRows(rows, args5, compact3) {
+  const raw = rows;
+  const fields = typeof args5.fields === "string" ? args5.fields : void 0;
+  if (fields) {
+    const paths = fields.split(",").map((field) => field.trim()).filter((field) => field.length > 0);
+    if (paths.length > 0) {
+      return { rows: projectFields(raw, paths), fields: paths };
+    }
+  }
+  if (args5.full) return { rows: raw };
+  return { rows: rows.map(compact3.row), fields: [...compact3.columns] };
+}
+
+// src/commands/ads/linkedin/creatives.ts
+function asRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
 function asString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
@@ -22943,12 +22983,12 @@ function creativeDestination(content) {
   if (!content) return { format: "unknown" };
   const reference = asString(content.reference);
   if (reference) return { format: "post", postUrn: reference };
-  const textAd = asRecord(content.textAd);
+  const textAd = asRecord2(content.textAd);
   if (textAd) return { format: "text", landingUrl: asString(textAd.landingPage) };
-  const spotlight = asRecord(content.spotlight);
+  const spotlight = asRecord2(content.spotlight);
   if (spotlight) return { format: "spotlight", landingUrl: asString(spotlight.landingPage) };
-  if (asRecord(content.follower)) return { format: "follower" };
-  if (asRecord(content.jobs)) return { format: "jobs" };
+  if (asRecord2(content.follower)) return { format: "follower" };
+  if (asRecord2(content.jobs)) return { format: "jobs" };
   return { format: "unknown" };
 }
 var COMPACT_COLUMNS = [
@@ -22976,27 +23016,6 @@ function compactRow(row) {
     ...destination.postUrn ? { postUrn: destination.postUrn } : {}
   };
 }
-function readPath2(row, path48) {
-  let current = row;
-  for (const segment of path48.split(".")) {
-    const record = asRecord(current);
-    if (!record) return void 0;
-    current = record[segment];
-  }
-  return current;
-}
-function projectFields(rows, paths) {
-  return rows.map((row) => {
-    const projected = {};
-    for (const path48 of paths) {
-      const value = readPath2(row, path48);
-      if (value !== void 0) {
-        projected[path48] = value;
-      }
-    }
-    return projected;
-  });
-}
 function unmappedShapeWarnings(rows, rawContentReturned) {
   const unmapped = rows.filter((row) => row.content && creativeDestination(row.content).format === "unknown");
   if (unmapped.length === 0) return [];
@@ -23008,18 +23027,6 @@ function unmappedShapeWarnings(rows, rawContentReturned) {
     }
   ];
 }
-function shapeRows(rows, args5) {
-  const raw = rows;
-  const fields = typeof args5.fields === "string" ? args5.fields : void 0;
-  if (fields) {
-    const paths = fields.split(",").map((field) => field.trim()).filter((field) => field.length > 0);
-    if (paths.length > 0) {
-      return { rows: projectFields(raw, paths), fields: paths };
-    }
-  }
-  if (args5.full) return { rows: raw };
-  return { rows: rows.map(compactRow), fields: [...COMPACT_COLUMNS] };
-}
 var listArgs3 = {
   "account-id": { type: "string", description: "Numeric account ID or urn:li:sponsoredAccount:N" },
   "account-urn": { type: "string", description: "Alias for --account-id" },
@@ -23051,7 +23058,10 @@ var creativesListCommand = defineCommand44({
       if (args5.limit) params.limit = String(args5.limit);
       if (args5["no-cache"]) params["skip-cache"] = "true";
       const data = await apiGet("/api/ads/linkedin/creatives", params);
-      const shaped = shapeRows(data, args5);
+      const shaped = shapeListRows(data, args5, {
+        row: compactRow,
+        columns: COMPACT_COLUMNS
+      });
       const fmt = csvOrJson2(args5);
       if (fmt !== "json") {
         writeAdsOutput(shaped.rows, fmt, shaped.fields);
@@ -24069,22 +24079,178 @@ Examples:
 
 // src/commands/ads/meta/activities.ts
 import { defineCommand as defineCommand56 } from "citty";
+
+// src/commands/ads/meta/list-rows.ts
+function pick(row, keys) {
+  const picked = {};
+  for (const key of keys) {
+    if (row[key] !== void 0) picked[key] = row[key];
+  }
+  return picked;
+}
+function asRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+var CAMPAIGN_COLUMNS = [
+  "id",
+  "name",
+  "effective_status",
+  "objective",
+  "daily_budget",
+  "lifetime_budget",
+  "bid_strategy",
+  "special_ad_categories",
+  "stop_time",
+  "created_time"
+];
+var ADSET_KEYS = [
+  "id",
+  "name",
+  "campaign_id",
+  "effective_status",
+  "optimization_goal",
+  "billing_event",
+  "bid_strategy",
+  "daily_budget",
+  "lifetime_budget",
+  "destination_type"
+];
+var ADSET_COLUMNS = [...ADSET_KEYS, "learning_stage", "end_time", "created_time"];
+function compactAdSet(row) {
+  const learning = asRecord3(row.learning_stage_info)?.status;
+  return {
+    ...pick(row, ADSET_KEYS),
+    ...typeof learning === "string" ? { learning_stage: learning } : {},
+    ...pick(row, ["end_time", "created_time"])
+  };
+}
+var AD_COLUMNS = [
+  "id",
+  "name",
+  "adset_id",
+  "campaign_id",
+  "effective_status",
+  "creative_id",
+  "issues",
+  "created_time"
+];
+function adIssues(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const issue = asRecord3(entry);
+    const text2 = issue?.error_summary ?? issue?.error_message;
+    return typeof text2 === "string" && text2 ? [text2] : [];
+  });
+}
+function compactAd(row) {
+  const creativeId = asRecord3(row.creative)?.id;
+  const issues = adIssues(row.issues_info);
+  return {
+    ...pick(row, ["id", "name", "adset_id", "campaign_id", "effective_status"]),
+    ...creativeId !== void 0 ? { creative_id: creativeId } : {},
+    ...issues.length > 0 ? { issues } : {},
+    ...pick(row, ["created_time"])
+  };
+}
+var ACTIVITY_COLUMNS = [
+  "event_time",
+  "event_type",
+  "actor_name",
+  "object_type",
+  "object_name",
+  "object_id",
+  "change"
+];
+function isScalar(value) {
+  return value === null || typeof value === "string" || typeof value === "number";
+}
+function activityChange(extraData) {
+  if (typeof extraData !== "string") return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(extraData);
+  } catch {
+    return void 0;
+  }
+  const data = asRecord3(parsed);
+  if (!data || !("new_value" in data) || !isScalar(data.new_value) || !isScalar(data.old_value ?? null)) {
+    return void 0;
+  }
+  const show = (value) => value === null || value === void 0 ? "(none)" : String(value);
+  return `${show(data.old_value)} \u2192 ${show(data.new_value)}`;
+}
+function compactActivity(row) {
+  const change = activityChange(row.extra_data);
+  return {
+    ...pick(row, ["event_time", "event_type", "actor_name", "object_type", "object_name", "object_id"]),
+    ...change !== void 0 ? { change } : {}
+  };
+}
+var PROJECTIONS = {
+  campaigns: { row: (row) => pick(row, CAMPAIGN_COLUMNS), columns: CAMPAIGN_COLUMNS },
+  adsets: { row: compactAdSet, columns: ADSET_COLUMNS },
+  ads: { row: compactAd, columns: AD_COLUMNS },
+  activities: { row: compactActivity, columns: ACTIVITY_COLUMNS }
+};
+function shapeMetaListRows(kind, rows, args5) {
+  return shapeListRows(rows, args5, PROJECTIONS[kind]);
+}
+var META_LIST_SHAPE_ARGS = {
+  fields: {
+    type: "string",
+    description: "CSV of dotted paths to return instead of the compact row, e.g. id,name,targeting.geo_locations"
+  },
+  full: { type: "boolean", description: "Return every field Meta sent (targeting, tracking specs, raw extra_data)" },
+  output: { type: "string", description: "json|csv|jsonl|md \u2014 md prints a table of the compact row", default: "json" }
+};
+function registerMetaListSchema(kind, description, args5) {
+  registerSchema({
+    command: `ads.meta.${kind}`,
+    description,
+    args: Object.fromEntries(
+      Object.entries(args5).map(([name, def]) => [
+        name,
+        {
+          type: def.type,
+          description: def.description ?? "",
+          required: false,
+          ...def.default !== void 0 ? { default: def.default } : {}
+        }
+      ])
+    )
+  });
+}
+
+// src/commands/ads/meta/activities.ts
+var listArgs4 = {
+  "account-id": { type: "string", description: "Meta ad account ID" },
+  days: { type: "string", description: "Lookback days (default 7)" },
+  limit: { type: "string", description: "Max rows" },
+  "no-cache": NO_CACHE_ARG,
+  ...META_LIST_SHAPE_ARGS
+};
+registerMetaListSchema(
+  "activities",
+  "Account change log. Compact by default, one row per event: event_time, event_type, actor_name, object_type, object_name, object_id, and change ('old \u2192 new' when the change is a single value). Start here: baker ads meta activities --account-id act_123 --days 2 --output md. --fields event_time,object_name,extra_data or --full for the raw change payload.",
+  listArgs4
+);
 var activitiesCommand = defineCommand56({
   meta: {
     name: "activities",
     description: `Audit log of recent ad-account changes (created, paused, edited). Default lookback 7 days,
 ~90 day retention server-side.
 
+Compact by default, one row per event: event_time, event_type, actor_name, object_type,
+object_name, object_id, and change ("old \u2192 new" when the change is a single value: status,
+name, budget, goal). --fields takes dotted paths (extra_data holds the raw change); --full returns
+every field Meta sent.
+
 Examples:
-  baker ads meta activities --account-id act_123 --days 14`
-  },
-  args: {
-    "account-id": { type: "string", description: "Meta ad account ID" },
-    days: { type: "string", description: "Lookback days (default 7)" },
-    limit: { type: "string", description: "Max rows" },
-    "no-cache": NO_CACHE_ARG,
-    output: { type: "string", description: "Output format", default: "json" }
+  baker ads meta activities --account-id act_123 --days 14
+  baker ads meta activities --account-id act_123 --days 2 --output md
+  baker ads meta activities --account-id act_123 --fields event_time,object_name,extra_data`
   },
+  args: listArgs4,
   run: async ({ args: args5 }) => {
     const accountId = resolveAccountIdArg(args5);
     try {
@@ -24093,12 +24259,13 @@ Examples:
       if (args5.limit) params.limit = args5.limit;
       if (args5["no-cache"]) params["skip-cache"] = "true";
       const data = await apiGet("/api/ads/meta/activities", params);
+      const shaped = shapeMetaListRows("activities", data, args5);
       const fmt = csvOrJson(args5);
       if (fmt !== "json") {
-        writeAdsOutput(data, fmt);
+        writeAdsOutput(shaped.rows, fmt, shaped.fields);
         return;
       }
-      writeAdsJson({ ok: true, data });
+      writeAdsJson({ ok: true, data: shaped.rows });
     } catch (err) {
       handleMetaError(err);
     }
@@ -26541,7 +26708,7 @@ var adsArchiveCommand = statusCommand3("archive", "ad.update", "ad");
 var adsDuplicateCommand = duplicateCommand2("ad", "ad");
 
 // src/commands/ads/meta/ads.ts
-var listArgs4 = {
+var listArgs5 = {
   "account-id": { type: "string", description: "Meta ad account ID" },
   "adset-id": { type: "string", description: "Filter to one adset" },
   "campaign-id": { type: "string", description: "Filter to one campaign" },
@@ -26549,14 +26716,19 @@ var listArgs4 = {
   "all-statuses": { type: "boolean", description: "Drop the default ACTIVE filter" },
   limit: { type: "string", description: "Max rows (default 1000)" },
   "no-cache": NO_CACHE_ARG,
-  output: { type: "string", description: "Output format", default: "json" }
+  ...META_LIST_SHAPE_ARGS
 };
+registerMetaListSchema(
+  "ads",
+  "List ads in a Meta ad account. Compact by default: id, name, adset_id, campaign_id, effective_status, creative_id, issues (why an ad is WITH_ISSUES), created_time. Start here: baker ads meta ads --adset-id 6123 --output md. --fields takes dotted paths (e.g. id,tracking_specs); --full returns every field Meta sent.",
+  listArgs5
+);
 var listCommand4 = defineCommand58({
   meta: {
     name: "list",
     description: "List ads in a Meta ad account. Runs by default when no subcommand is given. Example: baker ads meta ads --account-id act_123"
   },
-  args: listArgs4,
+  args: listArgs5,
   run: async ({ args: args5 }) => {
     const accountId = resolveAccountIdArg(args5);
     const effectiveStatus = resolveEffectiveStatus(args5);
@@ -26568,12 +26740,13 @@ var listCommand4 = defineCommand58({
       if (args5.limit) params.limit = args5.limit;
       if (args5["no-cache"]) params["skip-cache"] = "true";
       const data = await apiGet("/api/ads/meta/ads", params);
+      const shaped = shapeMetaListRows("ads", data, args5);
       const fmt = csvOrJson(args5);
       if (fmt !== "json") {
-        writeAdsOutput(data, fmt);
+        writeAdsOutput(shaped.rows, fmt, shaped.fields);
         return;
       }
-      writeAdsJson({ ok: true, data });
+      writeAdsJson({ ok: true, data: shaped.rows });
     } catch (err) {
       handleMetaError(err);
     }
@@ -26587,9 +26760,14 @@ Defaults to ACTIVE only \u2014 pass --all-statuses to widen. Write subcommands s
 
 The dashboard shows effective_status (e.g. WITH_ISSUES, PENDING_REVIEW, DISAPPROVED, ADSET_PAUSED), not status.
 
+Listing rows are compact: id, name, adset_id, campaign_id, effective_status, creative_id, issues
+(why an ad is WITH_ISSUES), created_time. --fields takes dotted paths (e.g. tracking_specs,
+preview_shareable_link); --full returns every field.
+
 Examples:
   baker ads meta ads --account-id act_123
   baker ads meta ads --adset-id 6123
+  baker ads meta ads --adset-id 6123 --fields id,name,preview_shareable_link
   baker ads meta ads create --name "Ad 1" --adset meta_temp_as01 --creative meta_temp_cr01
   baker ads meta ads pause 6123 --account-id act_123
   baker ads meta ads retag 6123 --set "utm_medium=paid-social"      \u2014 fix tracking on a LIVE ad, keeping everything else`
@@ -26608,27 +26786,32 @@ Examples:
   // subcommand name using THIS command's arg defs, so without them `--account-id act_1`
   // would read `act_1` as a subcommand. `default` (not `run`) dispatches the bare
   // invocation — citty falls through to `run` after a subcommand, double-executing it.
-  args: listArgs4,
+  args: listArgs5,
   default: "list"
 });
 
 // src/commands/ads/meta/adsets.ts
 import { defineCommand as defineCommand59 } from "citty";
-var listArgs5 = {
+var listArgs6 = {
   "account-id": { type: "string", description: "Meta ad account ID" },
   "campaign-id": { type: "string", description: "Filter to one campaign" },
   "effective-status": { type: "string", description: "Comma-separated effective_status filter (overrides default)" },
   "all-statuses": { type: "boolean", description: "Drop the default ACTIVE filter" },
   limit: { type: "string", description: "Max rows (default 1000)" },
   "no-cache": NO_CACHE_ARG,
-  output: { type: "string", description: "Output format", default: "json" }
+  ...META_LIST_SHAPE_ARGS
 };
+registerMetaListSchema(
+  "adsets",
+  "List ad sets in a Meta ad account. Compact by default: id, name, campaign_id, effective_status, optimization_goal, billing_event, bid_strategy, budgets, destination_type, learning_stage, end_time, created_time. Targeting is not in the compact row \u2014 ask for it with --fields id,name,targeting (or --full). Start here: baker ads meta adsets --campaign-id 6123 --all-statuses.",
+  listArgs6
+);
 var listCommand5 = defineCommand59({
   meta: {
     name: "list",
     description: "List ad sets in a Meta ad account. Runs by default when no subcommand is given. Example: baker ads meta adsets --account-id act_123"
   },
-  args: listArgs5,
+  args: listArgs6,
   run: async ({ args: args5 }) => {
     const accountId = resolveAccountIdArg(args5);
     const effectiveStatus = resolveEffectiveStatus(args5);
@@ -26639,12 +26822,13 @@ var listCommand5 = defineCommand59({
       if (args5.limit) params.limit = args5.limit;
       if (args5["no-cache"]) params["skip-cache"] = "true";
       const data = await apiGet("/api/ads/meta/adsets", params);
+      const shaped = shapeMetaListRows("adsets", data, args5);
       const fmt = csvOrJson(args5);
       if (fmt !== "json") {
-        writeAdsOutput(data, fmt);
+        writeAdsOutput(shaped.rows, fmt, shaped.fields);
         return;
       }
-      writeAdsJson({ ok: true, data });
+      writeAdsJson({ ok: true, data: shaped.rows });
     } catch (err) {
       handleMetaError(err);
     }
@@ -26656,9 +26840,14 @@ var adsetsCommand = defineCommand59({
     description: `List ad sets in a Meta ad account, or stage writes (create/update/pause/resume/archive/duplicate).
 Defaults to ACTIVE only. Write subcommands stage ops on this chat's draft.
 
+Listing rows are compact: id, name, campaign_id, effective_status, optimization_goal, billing_event,
+bid_strategy, budgets, destination_type, learning_stage, end_time, created_time. Targeting is not in
+the compact row \u2014 ask for it with --fields (dotted paths) or --full.
+
 Examples:
   baker ads meta adsets --account-id act_123
   baker ads meta adsets --campaign-id 6123456789
+  baker ads meta adsets --campaign-id 6123456789 --fields id,name,targeting.geo_locations
   baker ads meta adsets create --campaign meta_temp_ab12 --name "US 25-54" --optimization-goal LINK_CLICKS --billing-event IMPRESSIONS --daily-budget 50 --targeting-file t.json`
   },
   subCommands: {
@@ -26674,13 +26863,13 @@ Examples:
   // subcommand name using THIS command's arg defs, so without them `--account-id act_1`
   // would read `act_1` as a subcommand. `default` (not `run`) dispatches the bare
   // invocation — citty falls through to `run` after a subcommand, double-executing it.
-  args: listArgs5,
+  args: listArgs6,
   default: "list"
 });
 
 // src/commands/ads/meta/audiences.ts
 import { defineCommand as defineCommand60 } from "citty";
-var listArgs6 = {
+var listArgs7 = {
   "account-id": { type: "string", description: "Meta ad account ID" },
   limit: { type: "string", description: "Max rows" },
   "no-cache": NO_CACHE_ARG,
@@ -26691,7 +26880,7 @@ var listCommand6 = defineCommand60({
     name: "list",
     description: "List custom audiences. Runs by default when no subcommand is given. Example: baker ads meta audiences --account-id act_123"
   },
-  args: listArgs6,
+  args: listArgs7,
   run: async ({ args: args5 }) => {
     const accountId = resolveAccountIdArg(args5);
     try {
@@ -26729,7 +26918,7 @@ Examples:
   // subcommand name using THIS command's arg defs, so without them `--account-id act_1`
   // would read `act_1` as a subcommand. `default` (not `run`) dispatches the bare
   // invocation — citty falls through to `run` after a subcommand, double-executing it.
-  args: listArgs6,
+  args: listArgs7,
   default: "list"
 });
 
@@ -26766,20 +26955,25 @@ Examples:
 
 // src/commands/ads/meta/campaigns.ts
 import { defineCommand as defineCommand62 } from "citty";
-var listArgs7 = {
+var listArgs8 = {
   "account-id": { type: "string", description: "Meta ad account ID" },
   "effective-status": { type: "string", description: "Comma-separated effective_status filter (overrides default)" },
   "all-statuses": { type: "boolean", description: "Drop the default ACTIVE filter and return everything" },
   limit: { type: "string", description: "Max rows (default 1000)" },
   "no-cache": NO_CACHE_ARG,
-  output: { type: "string", description: "Output format", default: "json" }
+  ...META_LIST_SHAPE_ARGS
 };
+registerMetaListSchema(
+  "campaigns",
+  "List campaigns in a Meta ad account. Compact by default: id, name, effective_status, objective, budgets, bid_strategy, special_ad_categories, stop_time, created_time. ACTIVE only unless --all-statuses. Start here: baker ads meta campaigns --account-id act_123 --all-statuses --output md. --fields takes dotted paths for anything else; --full returns every field Meta sent.",
+  listArgs8
+);
 var listCommand7 = defineCommand62({
   meta: {
     name: "list",
     description: "List campaigns for a Meta ad account. Runs by default when no subcommand is given. Example: baker ads meta campaigns --account-id act_123"
   },
-  args: listArgs7,
+  args: listArgs8,
   run: async ({ args: args5 }) => {
     const accountId = resolveAccountIdArg(args5);
     const effectiveStatus = resolveEffectiveStatus(args5);
@@ -26789,12 +26983,13 @@ var listCommand7 = defineCommand62({
       if (args5.limit) params.limit = args5.limit;
       if (args5["no-cache"]) params["skip-cache"] = "true";
       const data = await apiGet("/api/ads/meta/campaigns", params);
+      const shaped = shapeMetaListRows("campaigns", data, args5);
       const fmt = csvOrJson(args5);
       if (fmt !== "json") {
-        writeAdsOutput(data, fmt);
+        writeAdsOutput(shaped.rows, fmt, shaped.fields);
         return;
       }
-      writeAdsJson({ ok: true, data });
+      writeAdsJson({ ok: true, data: shaped.rows });
     } catch (err) {
       handleMetaError(err);
     }
@@ -26810,9 +27005,14 @@ apply only when the chat is published.
 In Meta's API "campaign" is the top-of-tree object (what marketers usually call a campaign group).
 The dashboard shows effective_status: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES, etc.
 
+Listing rows are compact: id, name, effective_status, objective, daily/lifetime budget, bid_strategy,
+special_ad_categories, stop_time, created_time. --fields takes dotted paths for anything else; --full returns every field.
+
 Examples:
   baker ads meta campaigns --account-id act_123                                   # ACTIVE only
   baker ads meta campaigns --account-id act_123 --all-statuses                    # everything
+  baker ads meta campaigns --account-id act_123 --all-statuses --output md        # as a table
+  baker ads meta campaigns --account-id act_123 --fields id,name,budget_remaining,start_time
   baker ads meta campaigns create --account-id act_123 --name "Q3" --objective OUTCOME_LEADS --daily-budget 50
   baker ads meta campaigns pause 6123 --account-id act_123`
   },
@@ -26829,13 +27029,13 @@ Examples:
   // subcommand name using THIS command's arg defs, so without them `--account-id act_1`
   // would read `act_1` as a subcommand. `default` (not `run`) dispatches the bare
   // invocation — citty falls through to `run` after a subcommand, double-executing it.
-  args: listArgs7,
+  args: listArgs8,
   default: "list"
 });
 
 // src/commands/ads/meta/creatives.ts
 import { defineCommand as defineCommand63 } from "citty";
-var listArgs8 = {
+var listArgs9 = {
   "account-id": { type: "string", description: "Meta ad account ID (required if no --creative-id)" },
   "creative-id": { type: "string", description: "Single creative ID" },
   limit: { type: "string", description: "Max rows (default 500)" },
@@ -26847,7 +27047,7 @@ var listCommand8 = defineCommand63({
     name: "list",
     description: "List ad creatives, or fetch one by ID. Runs by default when no subcommand is given. Example: baker ads meta creatives --account-id act_123"
   },
-  args: listArgs8,
+  args: listArgs9,
   run: async ({ args: args5 }) => {
     try {
       const params = {};
@@ -26893,7 +27093,7 @@ Examples:
   // subcommand name using THIS command's arg defs, so without them `--account-id act_1`
   // would read `act_1` as a subcommand. `default` (not `run`) dispatches the bare
   // invocation — citty falls through to `run` after a subcommand, double-executing it.
-  args: listArgs8,
+  args: listArgs9,
   default: "list"
 });
 
@@ -26941,7 +27141,7 @@ registerSchema({
     output: { type: "string", description: "json|csv", required: false, default: "json" }
   }
 });
-var listArgs9 = {
+var listArgs10 = {
   "account-id": { type: "string", description: "Meta ad account ID" },
   full: { type: "boolean", description: "Include the raw rule JSON, retention and creation times" },
   limit: { type: "string", description: "Max rows" },
@@ -26953,7 +27153,7 @@ var listCommand9 = defineCommand64({
     name: "list",
     description: "List custom conversions. Runs by default when no subcommand is given. Example: baker ads meta custom-conversions --account-id act_123"
   },
-  args: listArgs9,
+  args: listArgs10,
   run: async ({ args: args5 }) => {
     const accountId = resolveAccountIdArg(args5);
     try {
@@ -26991,7 +27191,7 @@ Examples:
   // `args` stays even though the parent has no `run`: citty scans rawArgs for
   // the subcommand name using THIS command's arg defs. `default` (not `run`)
   // dispatches the bare invocation.
-  args: listArgs9,
+  args: listArgs10,
   default: "list"
 });
 
@@ -28703,7 +28903,7 @@ registerSchema({
     output: { type: "string", description: "Format: json|csv|md", required: false, default: "json" }
   }
 });
-var listArgs10 = {
+var listArgs11 = {
   "account-id": { type: "string", description: "X Ads account ID" },
   "funding-instrument-ids": { type: "string", description: "CSV of funding instrument IDs" },
   "campaign-ids": { type: "string", description: "CSV of campaign IDs" },
@@ -28773,7 +28973,7 @@ Examples:
   },
   // A parent must never declare `run`: citty falls through to it AFTER the
   // matched subcommand, so every write would also trigger a full live list.
-  args: listArgs10,
+  args: listArgs11,
   default: "list"
 });
 
@@ -34544,9 +34744,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 [
@@ -37026,6 +37226,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",
@@ -37580,6 +37795,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;
@@ -37632,6 +37871,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);
@@ -37641,10 +37886,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;
@@ -37718,8 +37961,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) {
@@ -37970,7 +38216,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);
@@ -38436,6 +38682,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),
@@ -38711,6 +38958,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"],
@@ -39026,6 +39276,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),
@@ -39220,6 +39471,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,
@@ -39316,6 +39568,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),
@@ -39416,6 +39669,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(),
@@ -39946,11 +40200,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);
@@ -40204,7 +40454,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.",
@@ -40272,7 +40522,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.",
@@ -40381,7 +40631,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,
@@ -42259,7 +42510,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";
@@ -42269,7 +42519,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"]),
@@ -42285,6 +42536,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;
@@ -42311,7 +42580,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;
@@ -42325,6 +42596,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:
@@ -42335,7 +42607,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) {
@@ -42375,6 +42650,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);
@@ -42397,10 +42675,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;
@@ -42440,15 +42719,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.";
@@ -42457,9 +42739,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),
     "",
@@ -42475,7 +42759,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
@@ -42512,7 +42798,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" }
@@ -42528,7 +42814,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) : [],
@@ -42751,6 +43037,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 {
@@ -42854,12 +43169,12 @@ function fail3(code, message) {
   process.exit(2);
 }
 function resolveModels(args5) {
-  const pick = (flag, kind, fallback) => args5[flag] ? String(args5[flag]) : resolveModel(kind, fallback);
+  const pick2 = (flag, kind, fallback) => args5[flag] ? String(args5[flag]) : resolveModel(kind, fallback);
   return {
-    describeModel: pick("describe-model", "image_describe", "~google/gemini-pro-latest"),
-    selectModel: pick("select-model", "text_generate", "~google/gemini-flash-latest"),
-    layoutModel: pick("layout-model", "text_generate", "~google/gemini-flash-latest"),
-    genModel: pick("gen-model", "image_generate", "openai/gpt-image-2")
+    describeModel: pick2("describe-model", "image_describe", "~google/gemini-pro-latest"),
+    selectModel: pick2("select-model", "text_generate", "~google/gemini-flash-latest"),
+    layoutModel: pick2("layout-model", "text_generate", "~google/gemini-flash-latest"),
+    genModel: pick2("gen-model", "image_generate", "openai/gpt-image-2")
   };
 }
 var PLATFORM_PLACEMENTS = {
@@ -42954,7 +43269,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" },
@@ -42982,7 +43297,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 }) {
@@ -43002,6 +43321,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();
@@ -43021,7 +43342,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;
@@ -43109,6 +43433,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,
@@ -43123,7 +43452,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."
           }
@@ -44879,18 +45208,18 @@ function parseBudget(raw) {
   throw new Error(`--budget must be one of ${VIDEO_BUDGETS.join(", ")} (got "${v}")`);
 }
 function resolveModels2(args5) {
-  const pick = (flag, kind, fallback) => args5[flag] ? String(args5[flag]) : resolveModel2(kind, fallback);
+  const pick2 = (flag, kind, fallback) => args5[flag] ? String(args5[flag]) : resolveModel2(kind, fallback);
   return {
     // Flash by default: ~2-3× faster per call than Pro, which keeps each
     // per-scene deconstruct step well inside the action time budget and turns a
     // ~9 min run into ~3-4 min. Override with --deconstruct-model
     // ~google/gemini-pro-latest for the densest extraction when speed matters less.
-    deconstructModel: pick("deconstruct-model", "video_deconstruct", "~google/gemini-flash-latest"),
-    selectModel: pick("select-model", "text_generate", "~google/gemini-flash-latest"),
+    deconstructModel: pick2("deconstruct-model", "video_deconstruct", "~google/gemini-flash-latest"),
+    selectModel: pick2("select-model", "text_generate", "~google/gemini-flash-latest"),
     // Default to the strongest image model (matches the static-ad scaffold); the
     // frame generators need the most faithful text/identity reproduction. Override
     // with --image-model for a cheaper/faster pass.
-    imageModel: pick("image-model", "image_generate", "openai/gpt-image-2.5-sunburst")
+    imageModel: pick2("image-model", "image_generate", "openai/gpt-image-2.5-sunburst")
   };
 }
 function hasPhotorealCast(elements) {
@@ -44990,7 +45319,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: {
@@ -45054,6 +45383,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 }) {
@@ -45093,6 +45426,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, {
@@ -45101,7 +45437,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).
@@ -45191,7 +45535,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
@@ -45240,6 +45585,7 @@ var scaffoldVideoCommand = defineCommand116({
           source_reference: sourceRef.url,
           composition_dir: compositionDest,
           output: canvas.output,
+          ...uncastHint,
           frames_mode: frames,
           models: {
             deconstruct: deconstructModel,
@@ -45283,7 +45629,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,
@@ -53962,7 +54308,7 @@ var extractCommand = defineCommand149({
 import { defineCommand as defineCommand150 } from "citty";
 
 // src/commands/images/providerHits.ts
-function asRecord2(value) {
+function asRecord4(value) {
   return value && typeof value === "object" ? value : {};
 }
 function str(value) {
@@ -53987,7 +54333,7 @@ function providerHitNormalizer(record, full) {
   if (!full) {
     return compact3;
   }
-  const group = asRecord2(record.group);
+  const group = asRecord4(record.group);
   return {
     ...compact3,
     externalUrl: str(record.externalUrl),
@@ -66250,7 +66596,7 @@ async function listTags(json) {
     failApi3(err);
   }
 }
-var listArgs11 = {
+var listArgs12 = {
   json: { type: "boolean", description: "Print the raw JSON envelope instead of the readable list" }
 };
 var listCommand19 = defineCommand222({
@@ -66258,7 +66604,7 @@ var listCommand19 = defineCommand222({
     name: "list",
     description: "Effective tags for this chat (production + staged), with each tag's full readable config (secrets excluded) \u2014 reuse a stored value to pre-fill a change rather than asking the user. Refs printed here are what flow side-effect tagIds should use. Example: baker tags list"
   },
-  args: listArgs11,
+  args: listArgs12,
   run: async ({ args: args5 }) => {
     await listTags(args5.json === true);
   }
@@ -66306,7 +66652,7 @@ Full guide: __tooling__/docs/tools/baker/tags.md`
   // command's flags when it scans rawArgs for a subcommand name, and `default` (not
   // `run`) dispatches the bare invocation — citty falls through to `run` after a
   // subcommand, so a `run` here would also list on every `baker tags draft`.
-  args: listArgs11,
+  args: listArgs12,
   default: "list"
 });