@koda-sl/baker-cli 0.252.0-dev.e7a1a227e → 0.253.0

package/dist/cli.js

@@ -58,7 +58,7 @@ import {
   ulid,
   validateCanvasDeep,
   ytDlpBlockSignal
-} from "./chunk-VLNO5AUC.js";
+} from "./chunk-SJPRTSGY.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -3682,7 +3682,6 @@ var avatarProfileSchema = z7.object({
   subjectDescription: z7.string().trim().min(1).max(2e3),
   persona: z7.string().trim().max(2e3).optional(),
   speech: z7.string().trim().max(2e3).optional(),
-  accent: z7.string().trim().max(2e3).optional(),
   motion: z7.string().trim().max(2e3).optional(),
   wardrobe: z7.string().trim().max(2e3).optional(),
   setting: z7.string().trim().max(2e3).optional(),
@@ -3698,6 +3697,7 @@ var avatarSummarySchema = z7.object({
   /** The identity sheet to wire into `--reference`. Absent until the build settles. */
   sheetUrl: z7.string().optional(),
   coverUrl: z7.string().optional(),
+  hasVoice: z7.boolean(),
   errorMessage: z7.string().optional()
 });
 var avatarDetailSchema = avatarSummarySchema.extend({
@@ -4292,7 +4292,7 @@ var FLOW_NODE_CATALOG = [
         }
       }
     },
-    gotcha: "`fieldtype` is one of: checkbox, date_picker, date_time_range, email, hidden, input, multi_select, number, phone, select, textarea. `select`/`multi_select` need non-empty `options`; `phone` needs `defaultCountry`; a field rendered by your own code is declared `hidden`. A field your page validates itself (postal code against a service area, VAT number, order reference) also needs `testValue` \u2014 the Form's own checks invent `TestValue` otherwise and never get past that step.",
+    gotcha: "`fieldtype` is one of: checkbox, date_picker, date_time_range, email, hidden, input, multi_select, number, phone, select, textarea. `select`/`multi_select` need non-empty `options`; `phone` needs `defaultCountry`; a field rendered by your own code is declared `hidden`. A field your page validates itself (postal code against a service area, VAT number, order reference) also needs `testValue` \u2014 the Form's own checks invent `TestValue` otherwise and never get past that step. A field holding something that has no business on a dashboard the client's whole team can open \u2014 a date of birth, a policy or account number, a salary, anything medical or legal \u2014 takes `sensitive: true`: an email or phone is masked already, everything else is reported verbatim unless marked. A contact field that is not the visitor's own (a manager's address, the office number) takes `identity: \"none\"`, or two people are filed as one.",
     reference: NODE_REF("customForm")
   },
   {
@@ -7411,11 +7411,7 @@ registerSchema({
   command: "actions.status",
   description: "Resolve one or more Work Action refs by real action ID or temp_* ref in a single batch call. When BAKER_CHAT_ID is set, a temp_* ref still staged in THIS chat resolves to status 'draft' (not 'not_found') \u2014 staged ops only become published actions on chat publish.",
   args: {
-    ref: {
-      type: "positional",
-      description: "One or more action refs: real action IDs or temp_* refs (space-separated)",
-      required: true
-    }
+    refs: { type: "string", description: "One or more action refs: real action IDs or temp_* refs", required: true }
   }
 });
 var statusCommand = defineCommand11({
@@ -12320,10 +12316,10 @@ var analyticsPresetSchema = z24.enum([
    */
   "geo",
   /**
-   * Which machines are fetching this site, and whether they are genuine.
+   * Which machines are fetching this site.
    *
-   * Every other preset here ends "and exclude the bots", which is correct — a
-   * crawler is not an audience. The rows are kept, though, and this is what
+   * Every other preset here excludes them, which is correct — a crawler is not
+   * an audience — and a verify check now enforces that rather than trusting it. The rows are kept, though, and this is what
    * they are kept for: whether Google is still crawling a page that was
    * republished, whether Meta fetched the link preview before spend went
    * behind the URL, and how much of the traffic is now AI answer engines.
@@ -12993,12 +12989,6 @@ var analyticsBotRowSchema = z24.object({
   bot: z24.string(),
   /** `search` | `ai` | `social` | `seo` | `monitoring` | `tool` | `automation`. */
   category: z24.string(),
-  /**
-   * Cloudflare confirmed it by the network it came from, rather than believing
-   * its user agent. A page fetched only by unverified self-declared Googlebots
-   * was not crawled by Google.
-   */
-  verified: z24.boolean(),
   hits: z24.number().int().nonnegative(),
   pages: z24.number().int().nonnegative(),
   lastSeen: z24.string(),
@@ -19270,6 +19260,14 @@ var CTA_TYPES2 = [
   "BUY_TICKETS",
   "NO_BUTTON"
 ];
+var LEAD_FORM_CTA_TYPES = [
+  "APPLY_NOW",
+  "DOWNLOAD",
+  "GET_QUOTE",
+  "LEARN_MORE",
+  "SIGN_UP",
+  "SUBSCRIBE"
+];
 var AD_FORMATS2 = ["SINGLE_IMAGE", "CAROUSEL", "SINGLE_VIDEO"];
 var ENROLL_STATUSES = ["OPT_IN", "OPT_OUT"];
 var STAGEABLE_CREATE_STATUSES3 = ["ACTIVE", "PAUSED"];
@@ -19692,7 +19690,23 @@ var descriptionSchema = z25.string().min(1).max(META_LIMITS.creative.description
 var callToActionSchema = z25.object({
   type: z25.enum(CTA_TYPES2),
   /** Overrides the base link for the CTA button; defaults to the ad's link. */
-  link: httpsUrlSchema3.optional()
+  link: httpsUrlSchema3.optional(),
+  /**
+   * The instant form the button opens — Meta's `call_to_action.value.lead_gen_form_id`.
+   * This is the ONLY place an instant form is named: the ad set says leads open
+   * on the ad (`destination_type: ON_AD`), and the creative says which form.
+   * Without it Meta refuses every ad in that ad set with subcode 3390001,
+   * "Choose or create an instant form for your leads campaign".
+   */
+  lead_gen_form_id: z25.string().regex(NUMERIC_ID_REGEX3).optional()
+}).superRefine((p, ctx) => {
+  if (p.lead_gen_form_id && !LEAD_FORM_CTA_TYPES.some((allowed) => allowed === p.type)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["type"],
+      message: `${p.type} cannot open an instant form \u2014 Meta refuses it (subcode 1856030). Use one of ${LEAD_FORM_CTA_TYPES.join(", ")}, or drop lead_gen_form_id if this ad should go to the website.`
+    });
+  }
 });
 var creativeEnhancementsSchema = z25.object({
   standardEnhancements: z25.enum(ENROLL_STATUSES).optional(),
@@ -19790,6 +19804,19 @@ var carouselCreativeSchema2 = z25.object({
   link: httpsUrlSchema3.optional(),
   call_to_action: callToActionSchema.optional(),
   cards: z25.array(carouselCardSchema).min(META_LIMITS.creative.carouselCardsMin).max(META_LIMITS.creative.carouselCardsMax)
+}).superRefine((p, ctx) => {
+  const forms = new Set(
+    [p.call_to_action?.lead_gen_form_id, ...p.cards.map((card) => card.call_to_action?.lead_gen_form_id)].filter(
+      Boolean
+    )
+  );
+  if (forms.size > 1) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["cards"],
+      message: `every card of a carousel must open the SAME instant form \u2014 this one names ${[...forms].join(" and ")}`
+    });
+  }
 });
 var dynamicImageSchema = z25.object({ ...imageMediaFields }).refine((p) => countImageRefs(p) === 1, "each dynamic image needs exactly one reference");
 var dynamicVideoSchema = z25.object({
@@ -20296,7 +20323,10 @@ var adSetWriteArgs = {
   "daily-budget": { type: "string", description: "Daily budget (ABO; omit if the campaign uses CBO)" },
   "lifetime-budget": { type: "string", description: "Lifetime budget (needs --end)" },
   "bid-amount": { type: "string", description: "Bid amount (required for COST_CAP / bid-cap strategies)" },
-  "bid-strategy": { type: "string", description: "Bid strategy override" },
+  "bid-strategy": {
+    type: "string",
+    description: "LOWEST_COST_WITHOUT_CAP (auto-bid) | LOWEST_COST_WITH_BID_CAP | COST_CAP \u2014 needs --bid-amount. Omit and Baker sets auto-bid; never leave it to Meta, whose default is a bid cap that then fails without an amount."
+  },
   currency: { type: "string", description: "3-letter currency (defaults to the account currency)" },
   start: { type: "string", description: "Start time" },
   end: { type: "string", description: "End time" },
@@ -20363,7 +20393,7 @@ function creativePayloadFromFlags(args) {
     headline: args.headline,
     description: args.description,
     caption: args.caption,
-    call_to_action: args.cta ? { type: upper(args.cta) } : void 0,
+    call_to_action: creativeCta(args),
     imageHash: args["image-hash"],
     imageRef: args["image-ref"],
     videoId: args["video-id"],
@@ -20373,6 +20403,26 @@ function creativePayloadFromFlags(args) {
     enhancements
   };
 }
+function ctaPatchFromFlags(args) {
+  const patch = {
+    ...args.cta ? { type: String(upper(args.cta)) } : {},
+    ...args["lead-form"] === void 0 ? {} : { lead_gen_form_id: String(args["lead-form"]) }
+  };
+  return Object.keys(patch).length > 0 ? patch : void 0;
+}
+function creativeCta(args) {
+  const patch = ctaPatchFromFlags(args);
+  return patch ? { type: "SIGN_UP", ...patch } : void 0;
+}
+function creativeContentPatch2(file, args) {
+  const cta = ctaPatchFromFlags(args);
+  if (!cta) {
+    return void 0;
+  }
+  const fileContent = file.content ?? {};
+  const fileCta = fileContent.call_to_action ?? {};
+  return { ...fileContent, call_to_action: { ...fileCta, ...cta } };
+}
 function parseEnroll(value) {
   const raw = String(value).toLowerCase();
   if (raw === "on" || raw === "true" || raw === "opt_in") return "OPT_IN";
@@ -20399,6 +20449,10 @@ Example: baker ads meta creatives create --page 555 --message "Save now" --link
     description: { type: "string", description: "Description" },
     caption: { type: "string", description: "Display URL / caption" },
     cta: { type: "string", description: "Call-to-action type (SHOP_NOW|LEARN_MORE|SIGN_UP|\u2026)" },
+    "lead-form": {
+      type: "string",
+      description: "Instant form id the button opens \u2014 REQUIRED for an ad set that collects leads on the ad. List them with `baker ads meta lead-forms`. With a form, --cta must be APPLY_NOW|DOWNLOAD|GET_QUOTE|LEARN_MORE|SIGN_UP|SUBSCRIBE"
+    },
     "image-hash": { type: "string", description: "Meta ad-image hash (already uploaded)" },
     "image-ref": { type: "string", description: "meta_temp_* ref of a staged media upload" },
     "video-id": { type: "string", description: "Meta video id (already uploaded)" },
@@ -20432,6 +20486,11 @@ Amending a staged (meta_temp_*) creative merges fields into the create. Example:
     ...accountArgs2,
     name: { type: "string", description: "New name" },
     status: { type: "string", description: "ACTIVE|PAUSED|ARCHIVED" },
+    cta: { type: "string", description: "Call-to-action type (staged creatives only)" },
+    "lead-form": {
+      type: "string",
+      description: "Instant form id the button opens (staged creatives only) \u2014 `baker ads meta lead-forms` lists them"
+    },
     file: {
       type: "string",
       description: "JSON file with fields to change (content only merges into a staged creative)"
@@ -20439,7 +20498,15 @@ Amending a staged (meta_temp_*) creative merges fields into the create. Example:
   },
   run: async ({ args }) => {
     const accountId = bareAccountId2(args);
-    const payload = mergePayload3(loadJsonFileArg3(args.file), { name: args.name, status: upper(args.status) });
+    const file = loadJsonFileArg3(args.file);
+    const payload = mergePayload3(file, {
+      name: args.name,
+      status: upper(args.status),
+      // A creative's content is immutable on Meta, so this only ever lands on a
+      // creative still staged in this chat — which is exactly the fix path when
+      // staging an ad refuses it for naming no instant form.
+      content: creativeContentPatch2(file, args)
+    });
     await stageOp2({
       kind: "adCreative.update",
       accountId,
@@ -23629,7 +23696,7 @@ var ANALYTICS_PRESET_INFO = [
   },
   {
     name: "flow",
-    description: "One Form in depth: conversions counted at the node that produced them, step-to-step paths for a branching Form, the per-step table, every trigger raised, and each marked conversion by name. Read convertedSessions rather than submits \u2014 a Form whose scheduling widget sits mid-flow never emits a submit and reports zero on every other report. An empty `conversions` array means nobody has marked what this Form is for, so the numbers rest on a built-in guess; mark it in the Forms builder or with `conversions: [{ triggerId }]` on the node.",
+    description: "One Form in depth: conversions counted at the node that produced them, step-to-step paths for a branching Form, the per-step table, every trigger raised, and each marked conversion by name. Read convertedSessions rather than submits \u2014 a Form whose scheduling widget sits mid-flow never emits a submit and reports zero on every other report. An empty `conversions` array means nobody has marked what this Form is for, so the numbers rest on a built-in guess; mark it in the Forms builder or with `conversions: [{ triggerId }]` on the node. `flowDestinations` is the other half and is evidence rather than a count: which Forms demonstrably handed something over in this window. Read it against the scaffold's `flow-no-destination` warning before acting on one \u2014 the stored picture of a Form is only rewritten when it is published, so a destination added since then shows there and not in the tree.",
     playbook: "flow-builder \u2014 fix the branch or the step that loses people"
   },
   {
@@ -23664,7 +23731,7 @@ var ANALYTICS_PRESET_INFO = [
   },
   {
     name: "bots",
-    description: "Which machines fetch this site and whether they are genuine. Every other report here excludes them; this one reads them. Answers whether Google is still crawling a page after it was republished, whether Meta fetched a link preview before spend went behind the URL, and how much of the traffic is now AI answer engines.",
+    description: "Which machines fetch this site. Every other report here excludes them; this one reads them. Answers whether Google is still crawling a page after it was republished, whether Meta fetched a link preview before spend went behind the URL, and how much of the traffic is now AI answer engines.",
     playbook: "landing \u2014 a page that stopped being crawled stops ranking, weeks before the traffic shows it"
   },
   {
@@ -24108,7 +24175,7 @@ var funnelCommand = presetCommand({
 var flowCommand = presetCommand({
   name: "flow",
   preset: "flow",
-  description: "One Form in depth: how many people it converted, where they went between steps, the per-step table, and every trigger it raised. Every count is DISTINCT VISITS, so quote shares against `funnels[].visits` \u2014 the visits that opened the Form \u2014 and never against `starts`, which is only the visits that touched it. The gap between the two is people who read the Form and left, and on most Forms it is the largest loss there is. Read `flowSummary.convertedSessions`, not `submits` \u2014 a Form that books a call on a scheduling node in the MIDDLE of the flow never emits a submit, so it reports zero submits and every one of its real bookings as conversions. `flowPaths` is the flow as edges between steps, bracketed by __flow_start__, __flow_converted__ and __flow_exit__, which is how a branching Form is read at all: a per-step table cannot say that of the people who left step two, forty went to the booking branch and ninety went nowhere.",
+  description: "One Form in depth: how many people it converted, where they went between steps, the per-step table, and every trigger it raised. Every count is DISTINCT VISITS, so quote shares against `funnels[].visits` \u2014 the visits that opened the Form \u2014 and never against `starts`, which is only the visits that touched it. The gap between the two is people who read the Form and left, and on most Forms it is the largest loss there is. Read `flowSummary.convertedSessions`, not `submits` \u2014 a Form that books a call on a scheduling node in the MIDDLE of the flow never emits a submit, so it reports zero submits and every one of its real bookings as conversions. `flowPaths` is the flow as edges between steps, bracketed by __flow_start__, __flow_converted__ and __flow_exit__, which is how a branching Form is read at all: a per-step table cannot say that of the people who left step two, forty went to the booking branch and ninety went nowhere. `flowDestinations` is the other half and is evidence rather than a count: which Forms demonstrably handed something over in this window. Read it against the scaffold's `flow-no-destination` warning before acting on one \u2014 the stored picture of a Form is only rewritten when it is published, so a destination added since then shows there and not in the tree.",
   extraArgs: { flow: { type: "string", description: "Form slug (default: every Form)", required: false } },
   resolve: (args) => ({ preset: "flow", flowSlug: args.flow ? String(args.flow) : void 0 })
 });
@@ -24450,8 +24517,7 @@ import { defineCommand as defineCommand94 } from "citty";
 import { defineCommand as defineCommand89 } from "citty";
 
 // src/commands/avatars/casting.ts
-var CAST_FLAG_RULE = "Cast with `--avatar <handle>` on `baker studio generate` and `baker studio animate`. 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 pinned VOICE and how they speak into a clip; without it the video model invents a different voice, and no later step can put theirs back.";
-var VERBATIM_RULE = "When you do write the description yourself \u2014 a 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 VERBATIM_RULE = "Copy `subjectDescription` into the prompt VERBATIM, word for word. Re-phrasing it per generation is the other reason a face drifts across a set \u2014 treat it as an identifier that happens to read as prose.";
 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`.";
 function castingHints(avatar) {
   if (avatar.status === "generating") {
@@ -24475,8 +24541,7 @@ function castingHints(avatar) {
     ];
   }
   return [
-    `Ready to cast: \`baker studio generate "<your scene>" --avatar ${avatar.handle}\` for a still, \`baker studio animate "<the motion, and the line they say>" --avatar ${avatar.handle}\` for a clip.`,
-    CAST_FLAG_RULE,
+    `Ready to cast. Ground every render on the identity sheet, never on a source photo: \`baker images generate "<your scene>" --reference ${avatar.sheetUrl}\`.`,
     VERBATIM_RULE,
     VIDEO_ROUTING
   ];
@@ -24488,6 +24553,7 @@ function rosterRow(avatar) {
     status: avatar.status,
     likeness: avatar.likeness,
     sheetUrl: avatar.sheetUrl ?? null,
+    hasVoice: avatar.hasVoice,
     avatarId: avatar.avatarId,
     ...avatar.errorMessage ? { errorMessage: avatar.errorMessage } : {}
   };
@@ -24515,19 +24581,10 @@ function rosterHints(roster, statusFilter) {
   }
   return hints;
 }
-function thinProfileHint(profile, handle) {
-  const missing = ["motion", "persona", "speech", "accent", "wardrobe", "setting"].filter(
-    (field) => !profile?.[field]?.trim()
-  );
-  if (missing.length === 0) return null;
-  return `MISSING ${missing.map((field) => `--${field}`).join(" ")}. A bare subject description holds the face still and nothing else, so clips of @${handle} come out stiff and generic \u2014 measured, filling these in nearly doubled the movement in the same brief. --accent is the one nobody guesses and the only one that fails silently: it decides the accent the avatar SPEAKS with in every clip, so name the region the user is writing to you from ("Spanish from Spain, Madrid accent") \u2014 "Spanish" on its own renders as no accent at all. The user almost certainly told you how this person talks and carries themselves; put it in: \`baker avatars update ${handle} ${missing.map((field) => `--${field} "\u2026"`).join(" ")}\`.`;
-}
-function creationHints(created, profile) {
-  const thin = thinProfileHint(profile, created.handle);
+function creationHints(created) {
   const hints = [
-    ...thin ? [thin] : [],
     ...castingHints({ handle: created.handle, status: created.status }),
-    `Once it is ready, cast it with \`--avatar ${created.handle}\` on \`baker studio generate\` / \`baker studio animate\` \u2014 that flag is what grounds the render on its identity sheet and, for a clip, what makes it speak in this avatar's own voice.`
+    `Once it is ready, every render grounds on its identity sheet (\`--reference <sheetUrl>\`) and reuses the subject description you just wrote, word for word. Those two things are what keep the face identical across a set.`
   ];
   if (created.likeness === "licensed") {
     hints.push(
@@ -24613,7 +24670,6 @@ var TEXT_FIELDS = [
   ["subject", "subjectDescription"],
   ["persona", "persona"],
   ["speech", "speech"],
-  ["accent", "accent"],
   ["motion", "motion"],
   ["wardrobe", "wardrobe"],
   ["setting", "setting"]
@@ -24702,12 +24758,7 @@ registerSchema({
       required: true
     },
     persona: { type: "string", description: "Who they are on camera \u2014 role, attitude, energy", required: false },
-    speech: { type: "string", description: "How they speak \u2014 pace, register, verbal habits", required: false },
-    accent: {
-      type: "string",
-      description: "Where their voice is FROM, as a place: 'Spanish from Spain, Madrid accent', 'Mexican Spanish', 'British English, London'. Name the region \u2014 an adjective like 'clear Spanish accent' is read by the video model as NO accent, and the clip comes out sounding like nowhere. Set it whenever the avatar will speak; the user's own language is the default to assume, not English.",
-      required: false
-    },
+    speech: { type: "string", description: "How they speak \u2014 pace, register, accent, verbal habits", required: false },
     motion: { type: "string", description: "Body language and gesture in video", required: false },
     wardrobe: { type: "string", description: "Default outfit when the brief does not name one", required: false },
     setting: { type: "string", description: "Default surroundings when the brief leaves them open", required: false },
@@ -24741,11 +24792,6 @@ var createCommand2 = defineCommand89({
     subject: { type: "string", description: "The person, plainly described \u2014 reused verbatim", required: false },
     persona: { type: "string", description: "Who they are on camera", required: false },
     speech: { type: "string", description: "How they speak", required: false },
-    accent: {
-      type: "string",
-      description: "Where their voice is FROM \u2014 name the region, e.g. 'Spanish from Spain, Madrid accent'",
-      required: false
-    },
     motion: { type: "string", description: "Body language in video", required: false },
     wardrobe: { type: "string", description: "Default outfit", required: false },
     setting: { type: "string", description: "Default surroundings", required: false },
@@ -24808,7 +24854,7 @@ var createCommand2 = defineCommand89({
         ...chatIdFromEnv() ? { chatId: chatIdFromEnv() } : {}
       };
       const data = await writeAvatars("/api/avatars", body);
-      writeJson({ ok: true, data, hints: creationHints(data, body.profile) });
+      writeJson({ ok: true, data, hints: creationHints(data) });
     } catch (err) {
       failAvatarApi(err, handle);
     }
@@ -29940,7 +29986,7 @@ function buildVideoTodo(report, overlayCount, floatingCount, opts, blueprint) {
       ]
     },
     transitions: "Scene-to-scene cuts the deconstruct flagged as fade/whip/zoom/dissolve/swipe are reproduced as an ffmpeg xfade at the boundary (everything else stays a hard cut). The overlap is consumed from extra generated footage, so the picture stays exactly on the audio timeline. To change a transition, edit the scene's `transition_out.type` in prompt.json and re-scaffold, or hand-edit the `spine` node's ffmpeg args. For a richer HERO cut (whip-pan, glitch, light-leak, gravitational-lens\u2026), the overlay layer can run a Hyperframes shader/CSS transition instead \u2014 see references/hyperframes/blueprints-and-transitions.md (pick 2\u20133 transition types total; the motion IS the handoff).",
-    overlay_capabilities: 'The overlay layer (video-overlay-composition/index.html) is a REAL Hyperframes composition, not a plain text layer \u2014 our hyperframe_render node runs the genuine `npx hyperframes` renderer. So it can do far more than fade/slide/pop: (1) PULL a ready-made block \u2014 `npx hyperframes catalog --type block` then `npx hyperframes add <id>` into the composition dir, and nest it with a <div data-composition-src="compositions/<id>.html" data-start data-track-index data-width data-height> clip (~154 blocks: lower-thirds, social-proof cards, stat counters, charts, code, logo stings); (2) animate with the named GSAP motion-rule vocabulary (kinetic-beat-slam, svg-path-draw, counting-dynamic-scale, multi-phase-camera\u2026); (3) frame a talking head as a video-call/PIP/split. The whole engine + how to build new effects is documented in references/hyperframes/ (start at README.md \u2192 catalog.md, motion-rules.md). Reach for this whenever the reference\'s graphics are richer than plain text.',
+    overlay_capabilities: 'The overlay layer (video-overlay-composition/index.html) is a REAL Hyperframes composition, not a plain text layer \u2014 our hyperframe_render node runs the genuine `npx hyperframes` renderer. So it can do far more than fade/slide/pop: (1) PULL a ready-made block \u2014 `npx hyperframes catalog --type block` then `npx hyperframes add <id>` into the composition dir, and nest it with a <div data-composition-src="compositions/<id>.html" data-start data-track-index data-width data-height> clip (~97 blocks: lower-thirds, social-proof cards, stat counters, charts, code, logo stings); (2) animate with the named GSAP motion-rule vocabulary (kinetic-beat-slam, svg-path-draw, counting-dynamic-scale, multi-phase-camera\u2026); (3) frame a talking head as a video-call/PIP/split. The whole engine + how to build new effects is documented in references/hyperframes/ (start at README.md \u2192 catalog.md, motion-rules.md). Reach for this whenever the reference\'s graphics are richer than plain text.',
     caption_system: "Sound-off feed = burned-in captions carry the message. The deconstruct produced a word-level transcript \u2014 drive a real caption track off it (karaoke highlight \u2192 themed \u2192 kinetic), not hand-typed text. Floor: `npx hyperframes add caption-highlight` (TikTok karaoke); escalate by content register (caption-kinetic-slam for hype, caption-editorial-emphasis for premium, caption-neon-glow for AI/crypto). Group on meaning, sync within 80ms. Full ladder + transcript contract: references/hyperframes/captions-and-audio.md.",
     talking_head_overlay: "For a scene where a presenter shows something (screen-share, app demo, product, a 'video call' look), frame the talking-head clip in the overlay composition: presenter full-bleed \u2192 shrinks to a rounded corner PIP pill while a content card takes the stage (or split/stack/overlay-glass-card). The pattern, the #video-wrap\u2192corner-pill tween, the glass call card, and the corner-coord presets are in references/hyperframes/talking-head-and-overlays.md. A ready exemplar ships as the `video-call-composition` move \u2014 copy it next to your canvas, drop brand fonts in the dir, point a `hyperframe_render` at it with the presenter clip as its `background`.",
     text_overlays: {
@@ -48044,7 +48090,7 @@ registerSchema({
     },
     image: {
       type: "string",
-      description: "Comma-separated source images: library image ids, local file paths, and/or image URLs. Required unless --from text or --avatar (the avatar is the source). With the default --from frame this must be exactly ONE image (the opening frame) \u2014 several are refused rather than silently reduced to the first. With --from references, up to 9 on Seedance 2.0 and 30 on Seedance 2.5.",
+      description: "Comma-separated source images: library image ids, local file paths, and/or image URLs. Required unless --from text. With the default --from frame this must be exactly ONE image (the opening frame) \u2014 several are refused rather than silently reduced to the first. With --from references, up to 9 on Seedance 2.0 and 30 on Seedance 2.5.",
       required: false
     },
     from: {
@@ -48263,15 +48309,10 @@ function costHintsFor(body) {
 var animateCommand = defineCommand189({
   meta: {
     name: "animate",
-    description: "Render a clip. With an image the look is already fixed, so the prompt describes MOVEMENT \u2014 what the camera does, what the subject does, in what order. With --from text there is no image and the prompt is the whole shot.\n\nA rendered clip is NOT usable anywhere until you keep it: `baker studio keep <id> --slot N` is what puts it in the video library. Takes nobody keeps are never ingested, which is what makes a rejected batch cheap.\n\nFor anything longer than 15 seconds, or to build on footage that already exists, use --model bytedance/seedance-2.5: it renders 4-30s and is the only model that reads an existing clip or an existing soundtrack.\n\nExamples:\n  baker studio animate 'slow push in, model turns to camera and smiles' --image j57abc123def456ghi789\n  baker studio animate 'she looks to camera and says: \"Hola, soy Elena\"' --avatar elena --quality 720p --aspect-ratio 9:16\n  baker studio animate 'handheld drift right, steam rising from the cup' --image './out/hero.png' --duration 6 --quality 1080p\n  baker studio animate 'product rotates once on a turntable' --image j57abc\u2026,j57def\u2026 --from references\n  baker studio animate 'she keeps walking, camera stays with her, then she stops and looks up' --image j57abc\u2026 --from references --from-clip j57batch\u2026:0 --model bytedance/seedance-2.5 --duration 20\n  baker studio animate 'hold on the product, then a slow push-in' --from references --from-video j57vid\u2026 --model bytedance/seedance-2.5\n  baker studio animate 'slow drone pull-back over a solar farm at golden hour, no people' --from text --model bytedance/seedance-2.5 --duration 12"
+    description: "Render a clip. With an image the look is already fixed, so the prompt describes MOVEMENT \u2014 what the camera does, what the subject does, in what order. With --from text there is no image and the prompt is the whole shot.\n\nA rendered clip is NOT usable anywhere until you keep it: `baker studio keep <id> --slot N` is what puts it in the video library. Takes nobody keeps are never ingested, which is what makes a rejected batch cheap.\n\nFor anything longer than 15 seconds, or to build on footage that already exists, use --model bytedance/seedance-2.5: it renders 4-30s and is the only model that reads an existing clip or an existing soundtrack.\n\nExamples:\n  baker studio animate 'slow push in, model turns to camera and smiles' --image j57abc123def456ghi789\n  baker studio animate 'handheld drift right, steam rising from the cup' --image './out/hero.png' --duration 6 --quality 1080p\n  baker studio animate 'product rotates once on a turntable' --image j57abc\u2026,j57def\u2026 --from references\n  baker studio animate 'she keeps walking, camera stays with her, then she stops and looks up' --image j57abc\u2026 --from references --from-clip j57batch\u2026:0 --model bytedance/seedance-2.5 --duration 20\n  baker studio animate 'hold on the product, then a slow push-in' --from references --from-video j57vid\u2026 --model bytedance/seedance-2.5\n  baker studio animate 'slow drone pull-back over a solar farm at golden hour, no people' --from text --model bytedance/seedance-2.5 --duration 12"
   },
   args: {
     prompt: { type: "positional", description: "What MOVES", required: false },
-    avatar: {
-      type: "string",
-      description: "Cast an avatar by short name \u2014 grounds the clip on their identity sheet AND gives it their voice",
-      required: false
-    },
     image: {
       type: "string",
       description: "Comma-separated library image ids, local file paths, and/or image URLs",
@@ -48336,13 +48377,13 @@ var animateCommand = defineCommand189({
         writeJson({ ok: false, error: { code: "VALIDATION_ERROR", message: "A prompt is required" } });
         process.exit(1);
       }
-      if (!args.image && !args.avatar && args.from !== "text") {
+      if (!args.image && args.from !== "text") {
         writeJson({
           ok: false,
           error: {
             code: "VALIDATION_ERROR",
-            message: "--image is required unless you pass --from text or --avatar: a clip normally animates a still, so it needs the image to start from",
-            fix: "Pass --image <id|path|url>, --avatar <handle> to build the shot around one of your avatars, or --from text to render from the prompt alone."
+            message: "--image is required unless you pass --from text: a clip normally animates a still, so it needs the image to start from",
+            fix: "Pass --image <id|path|url>, or --from text to render from the prompt alone."
           }
         });
         process.exit(1);
@@ -48526,11 +48567,6 @@ var generateCommand = defineCommand190({
     description: "Start here to make an image. Renders 1-8 takes of one brief, ingests each into the media library as it lands, and shows the batch in the dashboard Studio next to the ones the client ran.\n\nModel choice: google/gemini-3.1-flash-image-preview (default \u2014 fast, best at editing a reference and at extreme ratios), google/gemini-3-pro-image-preview (highest fidelity, slower), openai/gpt-image-2 (photoreal and the cleanest in-image text \u2014 no --image-size, no 4:5 / 5:4), recraft/recraft-v4.1-pro-vector (vector/flat marks with palette control).\n\n--reference is the biggest quality lever there is: a real logo, product shot, Pinterest pin or sandbox screenshot beats any amount of adjectives.\n\nExamples:\n  baker studio generate 'matte black bottle on wet marble, hard studio light, 35mm' --aspect-ratio 3:2 --count 3\n  baker studio generate 'this bottle on a sunlit kitchen counter' --reference './src/brand/product.png,https://\u2026/kitchen.jpg'\n  baker studio generate 'founder-style selfie, kitchen background, natural light' --skill ugc-selfie-hook\n  baker studio generate 'flat geometric mascot, brand palette' --model recraft/recraft-v4.1-pro-vector --rgb-colors '[[10,10,10],[255,80,0]]'"
   },
   args: {
-    avatar: {
-      type: "string",
-      description: "Cast an avatar by short name \u2014 grounds the image on their identity sheet",
-      required: false
-    },
     prompt: { type: "positional", description: "What to generate", required: false },
     model: { type: "string", description: "Model id (default google/gemini-3.1-flash-image-preview)", required: false },
     "aspect-ratio": { type: "string", description: "Aspect ratio (default 1:1)", required: false },