@koda-sl/baker-cli 0.354.0-dev.9b7066502 → 0.354.0-dev.c60462bb7

package/README.md

@@ -958,7 +958,7 @@ Status changes are `pause|resume|archive` subcommands on `campaigns`/`adsets`/`a
 - Identity columns (`campaign_name`, `ad_name`, etc.) appended automatically per `--level` so rows are self-describing.
 - Auto-async when the query is heavy (level=ad with breakdowns over an account, >2 breakdowns, >90-day range). Pass `--async` to force it or `--no-async` to refuse fallback.
 
-**Listings (`campaigns`/`adsets`/`ads`)** default to `effective_status=ACTIVE` — pass `--all-statuses` to widen, or `--effective-status ACTIVE,PAUSED` for a custom set. An empty filtered list carries a `hints` entry naming the filter and `--all-statuses`, so "nothing active" is never read as "nothing there".
+**Listings (`campaigns`/`adsets`/`ads`)** default to `effective_status=ACTIVE` — pass `--all-statuses` to widen, or `--effective-status ACTIVE,PAUSED` for a custom set.
 
 **Pagination** is auto-drained (no manual cursor handling).
 
@@ -5392,7 +5392,7 @@ Before the deconstruct it runs a **local shot-cut pass** on the source file with
 
 A shot longer than the video model's per-clip ceiling (Seedance's 15s, passed as `video_deconstruct`'s `max_clip_s`) is split into equal **continuation sub-scenes** that share their splice boundary exactly — so a long shot is reproduced in **full** (no truncation) and joins seamlessly. Each sub-scene carries `continues_previous`.
 
-It then scaffolds the full pipeline like an **editing timeline**: each clip gets a **static-ad-grade start AND end keyframe** (`image_generate`, each with its **own `params.prompt`** regenerated from that scene's `scenes/sNN.json` — edit the scene file to change that frame, never the node prompt by hand; the slim `prompt.style.json` wired as the **shared `target_blueprint`** style reference, plus a per-element reference legend). Each keyframe is **fully recast** to the dropped `el_*` reference images. The original extracted frame is kept LAST as a **pure composition anchor** (framing / camera angle / shot size / pose) whenever identity is safely locked — i.e. a frame with no person/animal, OR every cast member present is **sheet-backed** (a multi-view turnaround owns identity, so the anchor can reproduce the source's framing without dictating the face). Since every base element is now sheet-backed by default, cast frames keep their framing anchor too — this is what reproduces the source's composition (a side-profile stays a side-profile, the camera angle holds scene to scene) instead of drifting to a fresh guess. The anchor's legend forbids taking identity/text/palette from it. It is dropped only when a cast member rests on a weak lone-snapshot reference (e.g. a `same_as` second-look slot), where the original frame could re-leak the source actor. Both keyframes feed `video_generate` (`first_frame`+`last_frame`, so Seedance interpolates real in-shot motion; ultra-detailed motion brief; duration snapped to the nearest allowed clip length). Every keyframe grounds **only on its own extracted frame + `el_*` slots** — no reference to any other generated frame — so all images render **in parallel** (no cascade). Source-frame URLs are **deduped** (each ingested once). `--frames reuse` wires the real source frame straight in.
+It then scaffolds the full pipeline like an **editing timeline**: each clip gets a **static-ad-grade start AND end keyframe** (`image_generate`, each with its **own `params.prompt`** regenerated from that scene's `scenes/sNN.json` — edit the scene file to change that frame, never the node prompt by hand; the slim `prompt.style.json` wired as the **shared `target_blueprint`** style reference, plus a per-element reference legend). Each keyframe is **fully recast** to the dropped `el_*` reference images. The original extracted frame is kept LAST as a **pure composition anchor** (framing / camera angle / shot size / pose) only in an ad with **nobody in it** — no deconstructed cast and no recurring person. In any ad with people, no generated frame takes a source frame as a reference: an image model copies the face of whoever is in its references, whatever the prompt says, and which scenes a person is in is itself a model's guess — so framing is carried by the frame prompt instead. **People are cast from company avatars** (`--avatar <handle>`): each recurring person grounds on that avatar's identity sheet, used as-is (no sheet is built from it); a person with no avatar gets a `[TODO]` asking for one, never for a found photo. Both keyframes feed `video_generate` (`first_frame`+`last_frame`, so Seedance interpolates real in-shot motion; ultra-detailed motion brief; duration snapped to the nearest allowed clip length). Every keyframe grounds **only on its own extracted frame + `el_*` slots** — no reference to any other generated frame — so all images render **in parallel** (no cascade). Source-frame URLs are **deduped** (each ingested once). `--frames reuse` wires the real source frame straight in.
 
 **Composited scenes (split-screen / picture-in-picture / keyed presenter).** Real ads aren't always one full-frame shot — a frame can be **persistently divided** (b-roll on top, a presenter talking on the bottom) or **layer a presenter** over background footage (boxed in a corner, or green-screen keyed). The deconstruct now reports this per scene as `scene.composition` (`layout: split_screen | pip | keyed_overlay`, with one `region` per stream — each its own clean-plate frame + motion brief, the talking-head region flagged `is_presenter`). The scaffold reproduces a composited scene by building **one clip per region** (`s<i>_r0_*`, `s<i>_r1_*`, …) and compositing them with ffmpeg: a split-screen `vstack`/`hstack` (stack direction read from the region **panels**, so a top/bottom split always stacks vertically), or a picture-in-picture `overlay` of the presenter inset at its corner. A **keyed** presenter is first cut to transparency by `video_background_remove` (`s<i>_key`), then overlaid. The presenter region carries the native lip-synced voice; b-roll/render panels stay silent. To change a layout, edit `composition` in that scene's `scenes/sNN.json` and re-scaffold, or hand-edit the `s<i>_composite` ffmpeg args. Plain full-frame scenes (the default) are unaffected.
 
@@ -5437,7 +5437,7 @@ The emitted canvas is validated (`validateCanvasDeep`) before it's written, so i
 ```bash
 baker canvas scaffold-video ./reference-ad.mp4 --focus "competitor UGC ad for <brand>"
 # → writes ./reference-ad.video.canvas.json + ./prompt.json (global) + ./scenes/sNN.json (per scene) + ./prompt.rebuild.json (+ video-overlay-composition/)
-# edit each frame's own params.prompt + drop ONE real source image at each el_* [TODO], confirm voices, then:
+# cast the reference's people with --avatar <handle> (baker avatars list); edit scene files, fill every other el_* [TODO], confirm voices, then:
 baker canvas validate ./reference-ad.video.canvas.json
 baker canvas run ./reference-ad.video.canvas.json
 ```
@@ -5460,6 +5460,7 @@ baker canvas run ./reference-ad.video.canvas.json
 | `--motion-transfer` | off | Motion driven from a reference / hyper-dynamic → the router picks Kling. |
 | `--identity` | off | Same character/product across clips → the router picks the Seedance workhorse. |
 | `--budget <tier>` | `standard` | Router cost posture: `economy` (cheap Veo-fast tier) / `standard` / `premium`. |
+| `--avatar <handles>` | — | Cast company avatars as the reference's people, comma-separated in the order they appear (`marta` or `marta,joan`). Each recurring person grounds on that avatar's identity sheet and takes its subject description; a `same_as` look of them uses the same sheet. Resolved before anything is billed — a handle that is not `ready` fails the command. |
 | `--resolution <res>` | `1080p` | Output resolution for every generated clip (`480p`/`720p`/`1080p` for Seedance). The model defaults to a LOW tier when unset, which downscales the 2K keyframes — pinning the top tier keeps the clip as sharp as its frames. |
 
 **Scored model router.** When `--video-model` is omitted, a small weighted scorer picks from the curated

package/dist/{chunk-WJ5MYLLV.js → chunk-NA5CPMUA.js}

@@ -97,17 +97,6 @@ function resolveEffectiveStatus(args) {
   }
   return "ACTIVE";
 }
-function statusFilterHints(rows, effectiveStatus, noun) {
-  if (rows.length > 0 || effectiveStatus === void 0) return [];
-  if (effectiveStatus === "ACTIVE") {
-    return [
-      `No ACTIVE ${noun}. The ACTIVE filter hides paused, archived and in-review ones (under a paused campaign or ad set that is all of them), so this does NOT mean none exist. Re-run with --all-statuses before concluding there are none.`
-    ];
-  }
-  return [
-    `No ${noun} with effective_status ${effectiveStatus}. Re-run with --all-statuses to see every status before concluding there are none.`
-  ];
-}
 
 export {
   metaForbiddenFix,
@@ -117,7 +106,6 @@ export {
   todayIso,
   daysAgoIso,
   csvOrJson,
-  resolveEffectiveStatus,
-  statusFilterHints
+  resolveEffectiveStatus
 };
-//# sourceMappingURL=chunk-WJ5MYLLV.js.map
+//# sourceMappingURL=chunk-NA5CPMUA.js.map

package/dist/{chunk-WJ5MYLLV.js.map → chunk-NA5CPMUA.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/commands/ads/meta/shared.ts"],"sourcesContent":["import { ApiError } from \"../../../client.ts\";\nimport { getEnv } from \"../../../env.ts\";\nimport { handleConnectionError, needsConnectionFix } from \"../../../error-handler.ts\";\nimport { writeAdsJson } from \"../output.ts\";\nimport type { AdsErrorEnvelope, QueryFix } from \"../types.ts\";\n\nconst DAY_MS = 86_400_000;\n\n/**\n * Meta answers a permission refusal (Graph codes 200/10/294) with a bare\n * \"Permissions error\" that covers two causes needing opposite remedies: a\n * consent grant the connection never got — nothing validates Meta's granted\n * scopes after connect, unlike HubSpot's `requireCapability` — or a role the\n * user lacks on one asset, since a Pixel/Dataset, Page or catalog lives in a\n * Business and is assigned separately from the ad account. Only the blast radius\n * separates them, so hand the agent that test rather than a verdict: guessing\n * \"reconnect\" wastes the user's time on an unassigned asset, and ruling it out\n * strands a connection that really is short a scope.\n */\nexport function metaForbiddenFix(message: string): QueryFix {\n  return {\n    action: \"reject\",\n    explanation: [\n      message,\n      \"This is a permission refusal, not a dead connection, and Meta returns the same code for two causes with opposite remedies. Tell them apart by how much else works before you answer.\",\n      \"If other reads on this account are ALSO refused (campaigns, ad sets, insights), the connection is short a permission it was never granted. Only the user can widen it, by reconnecting Meta from the dashboard.\",\n      \"If those reads work and only this object is refused, the asset (pixel/dataset, Page, or catalog) belongs to a Business the connected user holds no role in. Ad-account access does not carry asset access and reconnecting cannot grant it — the client assigns that asset to the connected user or partner in Meta Business settings, under the asset's own section (Data sources → Datasets for a pixel).\",\n      \"Either way do not retry the same call, and do not abort the wider job. Continue with what you can read, and state in your answer that this specific check could not run and why — never present the task as verified when this step was skipped.\",\n    ].join(\"\\n\\n\"),\n  };\n}\n\nexport function handleMetaError(err: unknown): never {\n  if (err instanceof ApiError) {\n    if (needsConnectionFix(err.code, err.message)) {\n      handleConnectionError(\"meta_ads\", err.message);\n    }\n    const envelope: AdsErrorEnvelope = {\n      ok: false,\n      error: {\n        code: err.code,\n        message: err.message,\n        fix: err.code === \"FORBIDDEN\" ? metaForbiddenFix(err.message) : { action: \"reject\", explanation: err.message },\n        retryable: err.code === \"RATE_LIMITED\" || err.code === \"INTERNAL_ERROR\",\n      },\n    };\n    writeAdsJson(envelope);\n    process.exit(1);\n  }\n  const message = err instanceof Error ? err.message : \"Unexpected error\";\n  writeAdsJson({ ok: false, error: { code: \"NETWORK_ERROR\", message } });\n  process.exit(1);\n}\n\nconst ACCOUNT_ID_RE = /^(act_)?[0-9]+$/;\n\n/** Pull the default Meta ad account ID from `--account-id` arg or `BAKER_META_AD_ACCOUNT_ID` env. */\nexport function resolveAccountIdArg(args: Record<string, unknown>): string {\n  const fromArgs = args[\"account-id\"] as string | undefined;\n  const id = fromArgs || getEnv().BAKER_META_AD_ACCOUNT_ID;\n  if (!id) {\n    writeAdsJson({\n      ok: false,\n      error: {\n        code: \"MISSING_ACCOUNT_ID\",\n        message: \"Pass --account-id or set BAKER_META_AD_ACCOUNT_ID. Run `baker ads meta accounts` to find IDs.\",\n      },\n    });\n    process.exit(1);\n  }\n  if (!ACCOUNT_ID_RE.test(id)) {\n    writeAdsJson({\n      ok: false,\n      error: {\n        code: \"INVALID_ACCOUNT_ID\",\n        message: `Invalid account ID \"${id}\". Expected numeric ID, optionally prefixed with \"act_\".`,\n      },\n    });\n    process.exit(1);\n  }\n  return id.startsWith(\"act_\") ? id : `act_${id}`;\n}\n\nexport function getDateRange(args: Record<string, unknown>): { datePreset?: string; since?: string; until?: string } {\n  const datePreset = args[\"date-preset\"] as string | undefined;\n  const since = args.since as string | undefined;\n  const until = args.until as string | undefined;\n  if (since && until) return { since, until };\n  return { datePreset: datePreset ?? \"last_7d\" };\n}\n\nexport function todayIso(): string {\n  return new Date().toISOString().slice(0, 10);\n}\n\nexport function daysAgoIso(days: number): string {\n  return new Date(Date.now() - days * DAY_MS).toISOString().slice(0, 10);\n}\n\nexport function csvOrJson(args: Record<string, unknown>): string {\n  return (args.output as string | undefined) ?? \"json\";\n}\n\n/**\n * Default to ACTIVE-only on listings — that's almost always what an AI agent or\n * a human glance wants. Pass `--effective-status ACTIVE,PAUSED` to override, or\n * `--all-statuses` to drop the filter entirely.\n */\nexport function resolveEffectiveStatus(args: Record<string, unknown>): string | undefined {\n  if (args[\"all-statuses\"]) {\n    return undefined;\n  }\n  const explicit = args[\"effective-status\"] as string | undefined;\n  if (explicit) {\n    return explicit;\n  }\n  return \"ACTIVE\";\n}\n\n/**\n * An empty listing under a status filter reads exactly like \"nothing exists\":\n * a paused campaign's ad sets are CAMPAIGN_PAUSED, so the ACTIVE default hides\n * every one of them. Say which filter produced the empty list and how to widen it.\n */\nexport function statusFilterHints(\n  rows: ReadonlyArray<unknown>,\n  effectiveStatus: string | undefined,\n  noun: string,\n): string[] {\n  if (rows.length > 0 || effectiveStatus === undefined) return [];\n  if (effectiveStatus === \"ACTIVE\") {\n    return [\n      `No ACTIVE ${noun}. The ACTIVE filter hides paused, archived and in-review ones (under a paused campaign or ad set that is all of them), so this does NOT mean none exist. Re-run with --all-statuses before concluding there are none.`,\n    ];\n  }\n  return [\n    `No ${noun} with effective_status ${effectiveStatus}. Re-run with --all-statuses to see every status before concluding there are none.`,\n  ];\n}\n"],"mappings":";;;;;;;;;;;;;AAMA,IAAM,SAAS;AAaR,SAAS,iBAAiB,SAA2B;AAC1D,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,aAAa;AAAA,MACX;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,EAAE,KAAK,MAAM;AAAA,EACf;AACF;AAEO,SAAS,gBAAgB,KAAqB;AACnD,MAAI,eAAe,UAAU;AAC3B,QAAI,mBAAmB,IAAI,MAAM,IAAI,OAAO,GAAG;AAC7C,4BAAsB,YAAY,IAAI,OAAO;AAAA,IAC/C;AACA,UAAM,WAA6B;AAAA,MACjC,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM,IAAI;AAAA,QACV,SAAS,IAAI;AAAA,QACb,KAAK,IAAI,SAAS,cAAc,iBAAiB,IAAI,OAAO,IAAI,EAAE,QAAQ,UAAU,aAAa,IAAI,QAAQ;AAAA,QAC7G,WAAW,IAAI,SAAS,kBAAkB,IAAI,SAAS;AAAA,MACzD;AAAA,IACF;AACA,iBAAa,QAAQ;AACrB,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,QAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,eAAa,EAAE,IAAI,OAAO,OAAO,EAAE,MAAM,iBAAiB,QAAQ,EAAE,CAAC;AACrE,UAAQ,KAAK,CAAC;AAChB;AAEA,IAAM,gBAAgB;AAGf,SAAS,oBAAoB,MAAuC;AACzE,QAAM,WAAW,KAAK,YAAY;AAClC,QAAM,KAAK,YAAY,OAAO,EAAE;AAChC,MAAI,CAAC,IAAI;AACP,iBAAa;AAAA,MACX,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS;AAAA,MACX;AAAA,IACF,CAAC;AACD,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,MAAI,CAAC,cAAc,KAAK,EAAE,GAAG;AAC3B,iBAAa;AAAA,MACX,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS,uBAAuB,EAAE;AAAA,MACpC;AAAA,IACF,CAAC;AACD,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,SAAO,GAAG,WAAW,MAAM,IAAI,KAAK,OAAO,EAAE;AAC/C;AAEO,SAAS,aAAa,MAAwF;AACnH,QAAM,aAAa,KAAK,aAAa;AACrC,QAAM,QAAQ,KAAK;AACnB,QAAM,QAAQ,KAAK;AACnB,MAAI,SAAS,MAAO,QAAO,EAAE,OAAO,MAAM;AAC1C,SAAO,EAAE,YAAY,cAAc,UAAU;AAC/C;AAEO,SAAS,WAAmB;AACjC,UAAO,oBAAI,KAAK,GAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AAC7C;AAEO,SAAS,WAAW,MAAsB;AAC/C,SAAO,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AACvE;AAEO,SAAS,UAAU,MAAuC;AAC/D,SAAQ,KAAK,UAAiC;AAChD;AAOO,SAAS,uBAAuB,MAAmD;AACxF,MAAI,KAAK,cAAc,GAAG;AACxB,WAAO;AAAA,EACT;AACA,QAAM,WAAW,KAAK,kBAAkB;AACxC,MAAI,UAAU;AACZ,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAOO,SAAS,kBACd,MACA,iBACA,MACU;AACV,MAAI,KAAK,SAAS,KAAK,oBAAoB,OAAW,QAAO,CAAC;AAC9D,MAAI,oBAAoB,UAAU;AAChC,WAAO;AAAA,MACL,aAAa,IAAI;AAAA,IACnB;AAAA,EACF;AACA,SAAO;AAAA,IACL,MAAM,IAAI,0BAA0B,eAAe;AAAA,EACrD;AACF;","names":[]}
+{"version":3,"sources":["../src/commands/ads/meta/shared.ts"],"sourcesContent":["import { ApiError } from \"../../../client.ts\";\nimport { getEnv } from \"../../../env.ts\";\nimport { handleConnectionError, needsConnectionFix } from \"../../../error-handler.ts\";\nimport { writeAdsJson } from \"../output.ts\";\nimport type { AdsErrorEnvelope, QueryFix } from \"../types.ts\";\n\nconst DAY_MS = 86_400_000;\n\n/**\n * Meta answers a permission refusal (Graph codes 200/10/294) with a bare\n * \"Permissions error\" that covers two causes needing opposite remedies: a\n * consent grant the connection never got — nothing validates Meta's granted\n * scopes after connect, unlike HubSpot's `requireCapability` — or a role the\n * user lacks on one asset, since a Pixel/Dataset, Page or catalog lives in a\n * Business and is assigned separately from the ad account. Only the blast radius\n * separates them, so hand the agent that test rather than a verdict: guessing\n * \"reconnect\" wastes the user's time on an unassigned asset, and ruling it out\n * strands a connection that really is short a scope.\n */\nexport function metaForbiddenFix(message: string): QueryFix {\n  return {\n    action: \"reject\",\n    explanation: [\n      message,\n      \"This is a permission refusal, not a dead connection, and Meta returns the same code for two causes with opposite remedies. Tell them apart by how much else works before you answer.\",\n      \"If other reads on this account are ALSO refused (campaigns, ad sets, insights), the connection is short a permission it was never granted. Only the user can widen it, by reconnecting Meta from the dashboard.\",\n      \"If those reads work and only this object is refused, the asset (pixel/dataset, Page, or catalog) belongs to a Business the connected user holds no role in. Ad-account access does not carry asset access and reconnecting cannot grant it — the client assigns that asset to the connected user or partner in Meta Business settings, under the asset's own section (Data sources → Datasets for a pixel).\",\n      \"Either way do not retry the same call, and do not abort the wider job. Continue with what you can read, and state in your answer that this specific check could not run and why — never present the task as verified when this step was skipped.\",\n    ].join(\"\\n\\n\"),\n  };\n}\n\nexport function handleMetaError(err: unknown): never {\n  if (err instanceof ApiError) {\n    if (needsConnectionFix(err.code, err.message)) {\n      handleConnectionError(\"meta_ads\", err.message);\n    }\n    const envelope: AdsErrorEnvelope = {\n      ok: false,\n      error: {\n        code: err.code,\n        message: err.message,\n        fix: err.code === \"FORBIDDEN\" ? metaForbiddenFix(err.message) : { action: \"reject\", explanation: err.message },\n        retryable: err.code === \"RATE_LIMITED\" || err.code === \"INTERNAL_ERROR\",\n      },\n    };\n    writeAdsJson(envelope);\n    process.exit(1);\n  }\n  const message = err instanceof Error ? err.message : \"Unexpected error\";\n  writeAdsJson({ ok: false, error: { code: \"NETWORK_ERROR\", message } });\n  process.exit(1);\n}\n\nconst ACCOUNT_ID_RE = /^(act_)?[0-9]+$/;\n\n/** Pull the default Meta ad account ID from `--account-id` arg or `BAKER_META_AD_ACCOUNT_ID` env. */\nexport function resolveAccountIdArg(args: Record<string, unknown>): string {\n  const fromArgs = args[\"account-id\"] as string | undefined;\n  const id = fromArgs || getEnv().BAKER_META_AD_ACCOUNT_ID;\n  if (!id) {\n    writeAdsJson({\n      ok: false,\n      error: {\n        code: \"MISSING_ACCOUNT_ID\",\n        message: \"Pass --account-id or set BAKER_META_AD_ACCOUNT_ID. Run `baker ads meta accounts` to find IDs.\",\n      },\n    });\n    process.exit(1);\n  }\n  if (!ACCOUNT_ID_RE.test(id)) {\n    writeAdsJson({\n      ok: false,\n      error: {\n        code: \"INVALID_ACCOUNT_ID\",\n        message: `Invalid account ID \"${id}\". Expected numeric ID, optionally prefixed with \"act_\".`,\n      },\n    });\n    process.exit(1);\n  }\n  return id.startsWith(\"act_\") ? id : `act_${id}`;\n}\n\nexport function getDateRange(args: Record<string, unknown>): { datePreset?: string; since?: string; until?: string } {\n  const datePreset = args[\"date-preset\"] as string | undefined;\n  const since = args.since as string | undefined;\n  const until = args.until as string | undefined;\n  if (since && until) return { since, until };\n  return { datePreset: datePreset ?? \"last_7d\" };\n}\n\nexport function todayIso(): string {\n  return new Date().toISOString().slice(0, 10);\n}\n\nexport function daysAgoIso(days: number): string {\n  return new Date(Date.now() - days * DAY_MS).toISOString().slice(0, 10);\n}\n\nexport function csvOrJson(args: Record<string, unknown>): string {\n  return (args.output as string | undefined) ?? \"json\";\n}\n\n/**\n * Default to ACTIVE-only on listings — that's almost always what an AI agent or\n * a human glance wants. Pass `--effective-status ACTIVE,PAUSED` to override, or\n * `--all-statuses` to drop the filter entirely.\n */\nexport function resolveEffectiveStatus(args: Record<string, unknown>): string | undefined {\n  if (args[\"all-statuses\"]) {\n    return undefined;\n  }\n  const explicit = args[\"effective-status\"] as string | undefined;\n  if (explicit) {\n    return explicit;\n  }\n  return \"ACTIVE\";\n}\n"],"mappings":";;;;;;;;;;;;;AAMA,IAAM,SAAS;AAaR,SAAS,iBAAiB,SAA2B;AAC1D,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,aAAa;AAAA,MACX;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,EAAE,KAAK,MAAM;AAAA,EACf;AACF;AAEO,SAAS,gBAAgB,KAAqB;AACnD,MAAI,eAAe,UAAU;AAC3B,QAAI,mBAAmB,IAAI,MAAM,IAAI,OAAO,GAAG;AAC7C,4BAAsB,YAAY,IAAI,OAAO;AAAA,IAC/C;AACA,UAAM,WAA6B;AAAA,MACjC,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM,IAAI;AAAA,QACV,SAAS,IAAI;AAAA,QACb,KAAK,IAAI,SAAS,cAAc,iBAAiB,IAAI,OAAO,IAAI,EAAE,QAAQ,UAAU,aAAa,IAAI,QAAQ;AAAA,QAC7G,WAAW,IAAI,SAAS,kBAAkB,IAAI,SAAS;AAAA,MACzD;AAAA,IACF;AACA,iBAAa,QAAQ;AACrB,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,QAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,eAAa,EAAE,IAAI,OAAO,OAAO,EAAE,MAAM,iBAAiB,QAAQ,EAAE,CAAC;AACrE,UAAQ,KAAK,CAAC;AAChB;AAEA,IAAM,gBAAgB;AAGf,SAAS,oBAAoB,MAAuC;AACzE,QAAM,WAAW,KAAK,YAAY;AAClC,QAAM,KAAK,YAAY,OAAO,EAAE;AAChC,MAAI,CAAC,IAAI;AACP,iBAAa;AAAA,MACX,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS;AAAA,MACX;AAAA,IACF,CAAC;AACD,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,MAAI,CAAC,cAAc,KAAK,EAAE,GAAG;AAC3B,iBAAa;AAAA,MACX,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS,uBAAuB,EAAE;AAAA,MACpC;AAAA,IACF,CAAC;AACD,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,SAAO,GAAG,WAAW,MAAM,IAAI,KAAK,OAAO,EAAE;AAC/C;AAEO,SAAS,aAAa,MAAwF;AACnH,QAAM,aAAa,KAAK,aAAa;AACrC,QAAM,QAAQ,KAAK;AACnB,QAAM,QAAQ,KAAK;AACnB,MAAI,SAAS,MAAO,QAAO,EAAE,OAAO,MAAM;AAC1C,SAAO,EAAE,YAAY,cAAc,UAAU;AAC/C;AAEO,SAAS,WAAmB;AACjC,UAAO,oBAAI,KAAK,GAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AAC7C;AAEO,SAAS,WAAW,MAAsB;AAC/C,SAAO,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AACvE;AAEO,SAAS,UAAU,MAAuC;AAC/D,SAAQ,KAAK,UAAiC;AAChD;AAOO,SAAS,uBAAuB,MAAmD;AACxF,MAAI,KAAK,cAAc,GAAG;AACxB,WAAO;AAAA,EACT;AACA,QAAM,WAAW,KAAK,kBAAkB;AACxC,MAAI,UAAU;AACZ,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}

package/dist/cli.js

@@ -76,9 +76,8 @@ import {
   handleMetaError,
   resolveAccountIdArg,
   resolveEffectiveStatus,
-  statusFilterHints,
   todayIso
-} from "./chunk-WJ5MYLLV.js";
+} from "./chunk-NA5CPMUA.js";
 import {
   buildQueryCacheKey,
   cacheGet,
@@ -25467,7 +25466,7 @@ Example: baker ads meta ads retag 120252158038400247 --url-tags "utm_source={{si
     const { apiPost: apiPost2 } = await import("./client-ODCNYCP4.js");
     const { requireChatId: requireChatId2 } = await import("./env-BSG7TY5Y.js");
     const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-2XBCYF7L.js");
-    const { handleMetaError: handleMetaError2 } = await import("./shared-4FS6FXCM.js");
+    const { handleMetaError: handleMetaError2 } = await import("./shared-RYAF7Y7H.js");
     try {
       const accountId = bareAccountId2(args5);
       const urlTags = typeof args5["url-tags"] === "string" ? args5["url-tags"] : void 0;
@@ -25615,7 +25614,7 @@ function duplicateCommand2(entity, label) {
       const { apiPost: apiPost2 } = await import("./client-ODCNYCP4.js");
       const { requireChatId: requireChatId2 } = await import("./env-BSG7TY5Y.js");
       const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-2XBCYF7L.js");
-      const { handleMetaError: handleMetaError2 } = await import("./shared-4FS6FXCM.js");
+      const { handleMetaError: handleMetaError2 } = await import("./shared-RYAF7Y7H.js");
       try {
         const accountId = bareAccountId2(args5);
         const chatId = requireChatId2();
@@ -25680,8 +25679,7 @@ var listCommand4 = defineCommand58({
         writeAdsOutput(data, fmt);
         return;
       }
-      const hints2 = statusFilterHints(data, effectiveStatus, "ads");
-      writeJsonEnvelope(hints2.length > 0 ? { ok: true, data, hints: hints2 } : { ok: true, data });
+      writeAdsJson({ ok: true, data });
     } catch (err) {
       handleMetaError(err);
     }
@@ -25752,8 +25750,7 @@ var listCommand5 = defineCommand59({
         writeAdsOutput(data, fmt);
         return;
       }
-      const hints2 = statusFilterHints(data, effectiveStatus, "ad sets");
-      writeJsonEnvelope(hints2.length > 0 ? { ok: true, data, hints: hints2 } : { ok: true, data });
+      writeAdsJson({ ok: true, data });
     } catch (err) {
       handleMetaError(err);
     }
@@ -25903,8 +25900,7 @@ var listCommand7 = defineCommand62({
         writeAdsOutput(data, fmt);
         return;
       }
-      const hints2 = statusFilterHints(data, effectiveStatus, "campaigns");
-      writeJsonEnvelope(hints2.length > 0 ? { ok: true, data, hints: hints2 } : { ok: true, data });
+      writeAdsJson({ ok: true, data });
     } catch (err) {
       handleMetaError(err);
     }
@@ -33633,9 +33629,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` 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 [
@@ -36653,6 +36649,30 @@ var RecurringElement = z38.object({
   appears_in: z38.array(AppearsItem).optional()
 }).loose();
 var RecurringElements = z38.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;
@@ -36791,8 +36811,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) {
@@ -37043,7 +37066,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);
@@ -37509,6 +37532,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),
@@ -37784,6 +37808,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"],
@@ -38099,6 +38126,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),
@@ -38293,6 +38321,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,
@@ -38389,6 +38418,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),
@@ -38489,6 +38519,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(),
@@ -39019,11 +39050,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);
@@ -39277,7 +39304,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.",
@@ -39345,7 +39372,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.",
@@ -39454,7 +39481,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,
@@ -43884,6 +43912,20 @@ async function detectShotCutsBestEffort(videoPath, threshold) {
     return void 0;
   }
 }
+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 video 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.`
+    };
+  }
+}
 function fail4(code, message) {
   process.stderr.write(`${JSON.stringify({ ok: false, error: { code, message } }, null, 2)}
 `);
@@ -44065,7 +44107,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: {
@@ -44129,6 +44171,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 }) {
@@ -44168,6 +44214,13 @@ var scaffoldVideoCommand = defineCommand116({
       );
     }
     const { deconstructModel, selectModel, imageModel } = resolveModels2(args5);
+    const avatars = [];
+    const avatarHandles = String(args5.avatar ?? "").split(",").map((h) => h.trim()).filter(Boolean);
+    for (const handle of avatarHandles) {
+      const resolved = await resolveCastAvatar(handle);
+      if ("error" in resolved) return fail4("avatar", resolved.error);
+      avatars.push(resolved);
+    }
     const shotThreshold = args5["shot-threshold"] ? Number(args5["shot-threshold"]) : void 0;
     const shotCuts = await detectShotCutsBestEffort(videoPath, shotThreshold);
     const deconstructCanvas = buildDeconstructCanvas(videoPath, deconstructModel, {
@@ -44176,7 +44229,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).
@@ -44266,7 +44327,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
@@ -44315,6 +44377,7 @@ var scaffoldVideoCommand = defineCommand116({
           source_reference: sourceRef.url,
           composition_dir: compositionDest,
           output: canvas.output,
+          ...uncastHint,
           frames_mode: frames,
           models: {
             deconstruct: deconstructModel,
@@ -44358,7 +44421,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,