@koda-sl/baker-cli 0.102.0 → 0.104.0

package/README.md

@@ -4279,6 +4279,11 @@ This CLI is designed for AI agent consumption. Key patterns:
 10. **Parse the JSON envelope** — check `ok` field before accessing `data`
 11. **Always check `query_context`** in keyword/research responses — it shows the actual location and language used. If `defaults_warning` is present, the query used US/English defaults. Always pass `--location` and `--language` explicitly when targeting a specific market.
 
+## Internal Notes
+
+- **0.103.0**: `baker actions ...` commands now type their `/api/actions/...` request/response payloads from the shared `@baker/api` contract package (also consumed by the backend) instead of hand-written local interfaces. No command, flag, or output-shape changes.
+- **0.104.0**: `baker actions tags ...` commands now type their `/api/actions/tags...` request/response payloads from the shared `@baker/api` contract package instead of hand-written local interfaces. No command, flag, or output-shape changes.
+
 ## Publishing
 
 ### Auto-publish (CI)

package/dist/cli.js

@@ -632,11 +632,11 @@ registerSchema({
 async function recommendSkills(actionId) {
   const skills = readSkillCatalog(process.cwd());
   if (skills.length === 0) return [];
-  const response = await apiPost(
-    "/api/actions/recommend-skills",
-    { actionId, skills }
-  );
-  return response.data?.recommendations ?? [];
+  const response = await apiPost("/api/actions/recommend-skills", {
+    actionId,
+    skills
+  });
+  return response.data.recommendations;
 }
 function buildHints(recommendations) {
   if (recommendations.length === 0) {
@@ -684,9 +684,259 @@ var claimCommand = defineCommand({
   }
 });
 
+// ../api/src/actions.ts
+import { z as z2 } from "zod";
+var actionStatusSchema = z2.enum(["pending", "in_progress", "completed", "discarded"]);
+var actionPrioritySchema = z2.enum(["urgent", "high", "medium", "low"]);
+var actionRefResolutionStatusSchema = z2.union([actionStatusSchema, z2.enum(["draft", "not_found"])]);
+var actionDocSchema = z2.object({
+  _id: z2.string(),
+  _creationTime: z2.number(),
+  companyId: z2.string(),
+  name: z2.string(),
+  description: z2.string(),
+  status: actionStatusSchema,
+  priority: actionPrioritySchema.optional(),
+  requiresHuman: z2.boolean().optional(),
+  tags: z2.array(z2.string()).optional(),
+  createdByType: z2.enum(["user", "chat", "schedule"]),
+  createdByUserId: z2.string().optional(),
+  createdByChatId: z2.string().optional(),
+  createdByScheduleId: z2.string().optional(),
+  createdFromTempId: z2.string().optional(),
+  scheduledActionTrigger: z2.enum(["scheduled", "manual"]).optional(),
+  scheduledActionTriggerChatId: z2.string().optional(),
+  scheduledActionTriggerActorType: z2.enum(["user", "api", "system"]).optional(),
+  scheduledActionTriggerActorUserId: z2.string().optional(),
+  assigneeUserId: z2.string().optional(),
+  activeChatId: z2.string().optional(),
+  activeClaimedAt: z2.number().optional(),
+  completedAt: z2.number().optional(),
+  completedByType: z2.enum(["user", "chat"]).optional(),
+  completedByChatId: z2.string().optional(),
+  completedNote: z2.string().optional(),
+  discardedAt: z2.number().optional(),
+  discardedReason: z2.string().optional(),
+  createdAt: z2.number(),
+  updatedAt: z2.number(),
+  searchText: z2.string().optional()
+});
+var actionAssigneeSchema = z2.object({
+  userId: z2.string(),
+  name: z2.string(),
+  image: z2.string().optional()
+});
+var actionDepRefSchema = z2.object({
+  id: z2.string(),
+  name: z2.string(),
+  status: actionStatusSchema
+});
+var actionWithMetaSchema = z2.object({
+  action: actionDocSchema,
+  blockerCount: z2.number(),
+  openBlockerCount: z2.number(),
+  isBlocked: z2.boolean(),
+  openBlockingCount: z2.number(),
+  blockers: z2.array(actionDepRefSchema),
+  blocking: z2.array(actionDepRefSchema),
+  assignee: actionAssigneeSchema.nullable()
+});
+var actionBucketEntrySchema = z2.object({
+  id: z2.string(),
+  name: z2.string(),
+  description: z2.string(),
+  status: actionStatusSchema,
+  hint: z2.string(),
+  blockedBy: z2.array(z2.object({ id: z2.string(), name: z2.string() })).optional(),
+  claimedByChat: z2.object({ id: z2.string(), title: z2.string() }).optional(),
+  draftStatus: z2.enum(["in-progress", "completing", "discarding", "updating"]).optional()
+});
+var draftActionEntrySchema = z2.object({
+  tempId: z2.string(),
+  name: z2.string(),
+  description: z2.string(),
+  tags: z2.array(z2.string()),
+  hint: z2.string(),
+  draftStatus: z2.literal("creating")
+});
+var actionBucketsSchema = z2.object({
+  claimable: z2.array(actionBucketEntrySchema),
+  myClaims: z2.array(actionBucketEntrySchema),
+  blocked: z2.array(actionBucketEntrySchema),
+  claimedByOthers: z2.array(actionBucketEntrySchema),
+  completed: z2.array(actionBucketEntrySchema),
+  discarded: z2.array(actionBucketEntrySchema),
+  draftCreates: z2.array(draftActionEntrySchema)
+});
+var actionRefStatusResultSchema = z2.object({
+  ref: z2.string(),
+  status: actionRefResolutionStatusSchema,
+  actionId: z2.string().optional(),
+  name: z2.string().optional(),
+  hint: z2.string().optional()
+});
+var actionDetailSchema = z2.object({
+  action: actionDocSchema,
+  blockers: z2.array(actionDocSchema),
+  blocked: z2.array(actionDocSchema),
+  activeChat: z2.object({ _id: z2.string(), title: z2.string() }).nullable()
+});
+var actionDraftOpKindSchema = z2.enum(["create", "update", "complete", "discard", "link", "unlink"]);
+var chatActionDraftOpViewSchema = z2.object({
+  kind: actionDraftOpKindSchema,
+  targetName: z2.string(),
+  targetActionId: z2.string().optional(),
+  tempId: z2.string().optional(),
+  tags: z2.array(z2.string()).optional(),
+  reason: z2.string().optional(),
+  note: z2.string().optional(),
+  name: z2.string().optional(),
+  description: z2.string().optional(),
+  blockerName: z2.string().optional(),
+  blockerActionId: z2.string().optional(),
+  blockerTempId: z2.string().optional()
+});
+var chatDraftViewSchema = z2.object({
+  status: z2.enum(["active", "publishing", "discarded", "applied", "none"]),
+  count: z2.number(),
+  ops: z2.array(chatActionDraftOpViewSchema),
+  warnings: z2.array(z2.object({ tempId: z2.string(), name: z2.string() }))
+});
+var actionsClaimDataSchema = z2.object({
+  id: z2.string(),
+  name: z2.string(),
+  description: z2.string(),
+  tags: z2.array(z2.string())
+});
+var skillRecommendationSchema = z2.object({
+  name: z2.string(),
+  reason: z2.string()
+});
+var removeDraftOpTargetSchema = z2.discriminatedUnion("kind", [
+  z2.object({ kind: z2.literal("tempId"), tempId: z2.string() }),
+  z2.object({
+    kind: z2.literal("actionId"),
+    actionId: z2.string(),
+    opKind: z2.enum(["update", "complete", "discard"])
+  })
+]);
+function okResponse(data) {
+  return z2.object({ ok: z2.literal(true), data });
+}
+function okOnlySchema() {
+  return z2.object({ ok: z2.literal(true) });
+}
+var actionsCreateRequestSchema = z2.object({
+  chatId: z2.string(),
+  tempId: z2.string(),
+  name: z2.string().min(1),
+  description: z2.string(),
+  tags: z2.array(z2.string()).optional(),
+  priority: actionPrioritySchema.optional()
+});
+var actionsCreateResponseSchema = okResponse(z2.object({ tempId: z2.string() }));
+var actionsGetRequestSchema = z2.object({ actionId: z2.string().min(1) });
+var actionsGetResponseSchema = okResponse(actionDetailSchema.nullable());
+var actionsListRequestSchema = z2.object({
+  chatId: z2.string().optional(),
+  status: actionStatusSchema.optional(),
+  bucketed: z2.boolean().optional(),
+  q: z2.string().optional(),
+  sort: z2.enum(["recent", "priority"]).optional()
+});
+var actionsListResponseSchema = okResponse(z2.union([actionBucketsSchema, z2.array(actionWithMetaSchema)]));
+var actionsStatusRequestSchema = z2.object({
+  refs: z2.array(z2.string().min(1)).max(50),
+  chatId: z2.string().min(1).optional()
+});
+var actionsStatusResponseSchema = okResponse(z2.array(actionRefStatusResultSchema));
+var actionsUpdateRequestSchema = z2.object({
+  chatId: z2.string(),
+  actionId: z2.string(),
+  name: z2.string().optional(),
+  description: z2.string().optional(),
+  tags: z2.array(z2.string()).optional(),
+  priority: actionPrioritySchema.nullable().optional()
+});
+var actionsUpdateResponseSchema = okOnlySchema();
+var ACTION_COMPLETE_NOTE_MIN = 20;
+var actionsCompleteNoteMessage = `A completion note (\u2265${ACTION_COMPLETE_NOTE_MIN} chars) describing what was done is required: what changed, where, and the outcome.`;
+var actionsCompleteRequestSchema = z2.object({
+  chatId: z2.string(),
+  actionRef: z2.string().min(1, "actionRef is required"),
+  note: z2.string().optional()
+}).transform((body) => ({ ...body, note: (body.note ?? "").trim() })).refine((body) => body.note.length >= ACTION_COMPLETE_NOTE_MIN, {
+  message: actionsCompleteNoteMessage,
+  path: ["note"]
+});
+var actionsCompleteResponseSchema = okOnlySchema();
+var actionsDiscardRequestSchema = z2.object({
+  chatId: z2.string(),
+  actionId: z2.string(),
+  reason: z2.string().optional()
+});
+var actionsDiscardResponseSchema = okOnlySchema();
+var actionsLinkRequestSchema = z2.object({
+  chatId: z2.string(),
+  blockerRef: z2.string(),
+  blockedRef: z2.string()
+});
+var actionsLinkResponseSchema = okOnlySchema();
+var actionsUnlinkRequestSchema = z2.object({
+  chatId: z2.string(),
+  blockerId: z2.string(),
+  blockedId: z2.string()
+});
+var actionsUnlinkResponseSchema = okOnlySchema();
+var actionsClaimRequestSchema = z2.object({
+  actionId: z2.string(),
+  chatId: z2.string()
+});
+var actionsClaimResponseSchema = okResponse(actionsClaimDataSchema.nullable());
+var actionsReleaseRequestSchema = z2.object({
+  actionId: z2.string(),
+  chatId: z2.string()
+});
+var actionsReleaseResponseSchema = okOnlySchema();
+var actionsRecommendSkillsRequestSchema = z2.object({
+  actionId: z2.string().min(1),
+  // Bounds track what the CLI actually sends (descriptions truncated to ~600 chars); they
+  // cap the prompt size a direct API-key caller can push into the billed LLM call.
+  skills: z2.array(
+    z2.object({
+      name: z2.string().min(1).max(120),
+      description: z2.string().max(800)
+    })
+  ).max(80)
+});
+var actionsRecommendSkillsResponseSchema = okResponse(
+  z2.object({ recommendations: z2.array(skillRecommendationSchema) })
+);
+var actionsLogRequestSchema = z2.object({
+  fromMs: z2.number(),
+  toMs: z2.number()
+});
+var actionsLogResponseSchema = okResponse(z2.array(actionWithMetaSchema));
+var actionsDraftRequestSchema = z2.object({ chatId: z2.string() });
+var actionsDraftResponseSchema = okResponse(chatDraftViewSchema);
+var actionsDraftClearRequestSchema = z2.object({ chatId: z2.string() });
+var actionsDraftClearResponseSchema = okOnlySchema();
+var actionsRemoveDraftOpRequestSchema = z2.object({
+  chatId: z2.string(),
+  target: removeDraftOpTargetSchema
+});
+var actionsRemoveDraftOpResponseSchema = okOnlySchema();
+var actionsTagsListResponseSchema = z2.object({ markdown: z2.string() });
+var actionsTagsCreateRequestSchema = z2.object({
+  name: z2.string(),
+  description: z2.string().optional()
+});
+var actionsTagsCreateResponseSchema = okResponse(z2.object({ tagId: z2.string() }));
+var actionsTagsDeleteRequestSchema = z2.object({ name: z2.string() });
+var actionsTagsDeleteResponseSchema = okOnlySchema();
+
 // src/commands/actions/complete.ts
 import { defineCommand as defineCommand2 } from "citty";
-var COMPLETE_NOTE_MIN = 20;
 registerSchema({
   command: "actions.complete",
   description: "Stage completion of an action (it was DONE). Accepts a real action ID (must be claimed) or a temp ID from the same draft. The action becomes completed when the chat is published. --note is REQUIRED and must describe what you actually did to resolve it (what changed, where, and the outcome) \u2014 it is the client-facing record surfaced by `baker actions log`. Do NOT use this to drop an action you no longer want \u2014 to remove a staged op use `actions draft remove`, to close an unwanted published action use `actions discard`.",
@@ -723,9 +973,9 @@ var completeCommand = defineCommand2({
         validateConvexId(id);
       }
       const note = args.note?.trim() ?? "";
-      if (note.length < COMPLETE_NOTE_MIN) {
+      if (note.length < ACTION_COMPLETE_NOTE_MIN) {
         failValidation(
-          `--note is required and must describe what you did (\u2265${COMPLETE_NOTE_MIN} chars): what changed, where, and the outcome. This becomes the client-facing record surfaced by \`baker actions log\`.`
+          `--note is required and must describe what you did (\u2265${ACTION_COMPLETE_NOTE_MIN} chars): what changed, where, and the outcome. This becomes the client-facing record surfaced by \`baker actions log\`.`
         );
       }
       const chatId = requireChatId();
@@ -8559,27 +8809,27 @@ import path5 from "path";
 import { defineCommand as defineCommand82 } from "citty";
 
 // src/engine/scaffold/staticAd.ts
-import { z as z2 } from "zod";
+import { z as z3 } 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 Blueprint = z2.object({
-  meta: z2.object({ estimated_aspect_ratio: z2.string().optional() }).loose().optional(),
-  text_content: z2.array(z2.object({ text: z2.string().optional() }).loose()).optional()
+var Blueprint = z3.object({
+  meta: z3.object({ estimated_aspect_ratio: z3.string().optional() }).loose().optional(),
+  text_content: z3.array(z3.object({ text: z3.string().optional() }).loose()).optional()
 }).loose();
-var ElementLocator = z2.object({
-  collection: z2.enum(["subjects", "people", "brands_logos"]),
-  index: z2.number().int().nonnegative()
+var ElementLocator = z3.object({
+  collection: z3.enum(["subjects", "people", "brands_logos"]),
+  index: z3.number().int().nonnegative()
 }).loose();
-var MainElement = z2.object({
+var MainElement = z3.object({
   // logo | product | person | animal | badge | other
-  type: z2.string(),
-  label: z2.string().optional(),
-  description: z2.string().optional(),
-  expression: z2.string().nullable().optional(),
-  reason: z2.string().optional(),
+  type: z3.string(),
+  label: z3.string().optional(),
+  description: z3.string().optional(),
+  expression: z3.string().nullable().optional(),
+  reason: z3.string().optional(),
   locator: ElementLocator.optional()
 }).loose();
-var MainElements = z2.array(MainElement);
+var MainElements = z3.array(MainElement);
 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;
@@ -9074,7 +9324,7 @@ import { toCardinal as nwKo } from "n2words/ko-KR";
 import { toCardinal as nwNl } from "n2words/nl-NL";
 import { toCardinal as nwPl } from "n2words/pl-PL";
 import { toCardinal as nwPt } from "n2words/pt-PT";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/engine/scaffold/lib/shoot-modes.ts
 var SHOOT_MODES = [
@@ -9331,49 +9581,49 @@ function trimArgs(durationS, offsetS = 0) {
     "{{out.video}}"
   ];
 }
-var FrameAsset = z3.object({ url: z3.string().optional() }).loose().optional();
-var DialogueLine = z3.object({
-  speaker: z3.string().optional(),
-  line: z3.string().optional(),
+var FrameAsset = z4.object({ url: z4.string().optional() }).loose().optional();
+var DialogueLine = z4.object({
+  speaker: z4.string().optional(),
+  line: z4.string().optional(),
   // Absolute seconds on the source timeline (the deconstruct emits both).
-  start_s: z3.number().optional(),
-  end_s: z3.number().optional(),
-  delivery: z3.string().optional(),
-  voice_description: z3.string().optional()
+  start_s: z4.number().optional(),
+  end_s: z4.number().optional(),
+  delivery: z4.string().optional(),
+  voice_description: z4.string().optional()
 }).loose();
-var Sfx = z3.object({
-  at_s: z3.number().optional(),
-  duration_s: z3.number().optional(),
-  sound_effect_prompt: z3.string().optional(),
-  description: z3.string().optional()
+var Sfx = z4.object({
+  at_s: z4.number().optional(),
+  duration_s: z4.number().optional(),
+  sound_effect_prompt: z4.string().optional(),
+  description: z4.string().optional()
 }).loose();
-var CompositionRegion = z3.object({
+var CompositionRegion = z4.object({
   // full | top | bottom | left | right | inset
-  panel: z3.string().optional(),
+  panel: z4.string().optional(),
   // 9-grid anchor for an `inset` presenter box.
-  position: z3.string().optional(),
-  is_presenter: z3.boolean().optional(),
+  position: z4.string().optional(),
+  is_presenter: z4.boolean().optional(),
   // The cast id shown/speaking in this region (routes lip-sync + element refs).
-  cast_ref: z3.string().optional(),
-  summary: z3.string().optional(),
-  frame_prompt: z3.string().optional(),
-  motion_prompt: z3.string().optional()
+  cast_ref: z4.string().optional(),
+  summary: z4.string().optional(),
+  frame_prompt: z4.string().optional(),
+  motion_prompt: z4.string().optional()
 }).loose();
-var SceneComposition = z3.object({
+var SceneComposition = z4.object({
   // full_frame (default) | split_screen | pip | keyed_overlay
-  layout: z3.string().optional(),
+  layout: z4.string().optional(),
   // split_screen only: vertical (top/bottom) | horizontal (left/right).
-  split_axis: z3.string().optional(),
-  regions: z3.array(CompositionRegion).optional()
+  split_axis: z4.string().optional(),
+  regions: z4.array(CompositionRegion).optional()
 }).loose();
-var CameraMotion = z3.object({ movement: z3.string().optional(), detail: z3.string().optional() }).loose();
-var TranscriptWord = z3.object({ text: z3.string().optional() }).loose();
-var Scene = z3.object({
-  start_s: z3.number().optional(),
-  end_s: z3.number().optional(),
-  duration_s: z3.number().optional(),
-  summary: z3.string().optional(),
-  action_detail: z3.string().optional(),
+var CameraMotion = z4.object({ movement: z4.string().optional(), detail: z4.string().optional() }).loose();
+var TranscriptWord = z4.object({ text: z4.string().optional() }).loose();
+var Scene = z4.object({
+  start_s: z4.number().optional(),
+  end_s: z4.number().optional(),
+  duration_s: z4.number().optional(),
+  summary: z4.string().optional(),
+  action_detail: z4.string().optional(),
   // The scene's spatial layout. Absent/full_frame ⇒ one uncut shot (default path).
   // A layered layout (split_screen/pip/keyed_overlay) with regions ⇒ the scaffold
   // builds one clip per region and stacks/overlays them into the scene picture.
@@ -9381,77 +9631,77 @@ var Scene = z3.object({
   // The capture "look" for this scene — selected from the ad-native shoot-mode
   // grammar (see lib/shoot-modes.ts). When absent the scaffold auto-derives a
   // UGC/product mode; a human can override per scene by setting this.
-  shoot_mode: z3.string().optional(),
+  shoot_mode: z4.string().optional(),
   // Diegetic ambient the clip's native audio should carry (no music). When
   // absent the scene falls back to its shoot mode's default ambience.
-  ambient: z3.string().optional(),
+  ambient: z4.string().optional(),
   camera_motion: CameraMotion.optional(),
-  start_frame_prompt: z3.string().optional(),
-  end_frame_prompt: z3.string().optional(),
-  motion_prompt: z3.string().optional(),
+  start_frame_prompt: z4.string().optional(),
+  end_frame_prompt: z4.string().optional(),
+  motion_prompt: z4.string().optional(),
   // The scene's role in the ad's persuasion arc (DECON-supplied); drives the
   // script re-craft checklist. Inferred from position when absent.
-  narrative_role: z3.string().optional(),
+  narrative_role: z4.string().optional(),
   // DECON-supplied on the HOOK scene: the engineered physical/emotional state that
   // makes the first frame stop the scroll (sweaty/breathless/urgent …). Injected
   // into the hook's start-frame description so the generator renders that state,
   // not a calm influencer (CCA-11).
-  hook_mechanic: z3.object({ mechanic: z3.string().optional(), why_it_stops_scroll: z3.string().optional() }).loose().optional(),
+  hook_mechanic: z4.object({ mechanic: z4.string().optional(), why_it_stops_scroll: z4.string().optional() }).loose().optional(),
   // DECON-supplied per-scene location (so a gym hook isn't flattened to "home").
-  scene_setting: z3.string().optional(),
+  scene_setting: z4.string().optional(),
   // How this scene cuts to the next (DECON-supplied). A recognized non-cut type
   // (fade/whip/zoom/dissolve/swipe) is reproduced as an ffmpeg xfade at the
   // boundary; cut/match_cut/none/other stay hard cuts. The last scene's value is
   // ignored (nothing follows it).
-  transition_out: z3.object({ type: z3.string().optional(), description: z3.string().optional() }).loose().optional(),
-  dialogue: z3.array(DialogueLine).optional(),
-  sfx: z3.array(Sfx).optional(),
-  overlays: z3.array(z3.unknown()).optional(),
-  floating_elements: z3.array(z3.unknown()).optional(),
-  transcript_slice: z3.array(TranscriptWord).optional(),
+  transition_out: z4.object({ type: z4.string().optional(), description: z4.string().optional() }).loose().optional(),
+  dialogue: z4.array(DialogueLine).optional(),
+  sfx: z4.array(Sfx).optional(),
+  overlays: z4.array(z4.unknown()).optional(),
+  floating_elements: z4.array(z4.unknown()).optional(),
+  transcript_slice: z4.array(TranscriptWord).optional(),
   start_frame_asset: FrameAsset,
   end_frame_asset: FrameAsset,
   // DECON-supplied: true when this scene is a length-split CONTINUATION of the
   // previous one (the SAME physical shot, broken up only because it exceeded the
   // clip ceiling). The scaffold then shares the splice keyframe — this scene's
   // start frame IS the previous scene's end frame — so the join is seamless.
-  continues_previous: z3.boolean().optional()
+  continues_previous: z4.boolean().optional()
 }).loose();
-var VideoBlueprint = z3.object({
-  source: z3.object({ aspect_ratio: z3.string().optional(), duration_s: z3.number().optional() }).loose().optional(),
-  global: z3.object({
-    music: z3.object({
-      present: z3.boolean().optional(),
-      music_prompt: z3.string().optional(),
+var VideoBlueprint = z4.object({
+  source: z4.object({ aspect_ratio: z4.string().optional(), duration_s: z4.number().optional() }).loose().optional(),
+  global: z4.object({
+    music: z4.object({
+      present: z4.boolean().optional(),
+      music_prompt: z4.string().optional(),
       // Absolute second the music enters in the reference (the bed often
       // kicks in mid-ad, after the hook). We start the regenerated track here
       // instead of at 0 so the timing matches.
-      starts_at_s: z3.number().optional(),
+      starts_at_s: z4.number().optional(),
       // Populated by the deconstruct when AudD (Shazam-style) recognizes the
       // reference track. We never reuse it — only style the regenerated bed.
-      identified_track: z3.object({ title: z3.string().optional(), artist: z3.string().optional() }).loose().nullish()
+      identified_track: z4.object({ title: z4.string().optional(), artist: z4.string().optional() }).loose().nullish()
     }).loose().optional(),
-    cast: z3.array(
-      z3.object({
-        id: z3.string().optional(),
-        description: z3.string().optional(),
+    cast: z4.array(
+      z4.object({
+        id: z4.string().optional(),
+        description: z4.string().optional(),
         // The deconstruct's note on the target-market localization (e.g. "native
         // French speaker") — read to derive the spoken-track language code.
-        market_localization_note: z3.string().optional()
+        market_localization_note: z4.string().optional()
       }).loose()
     ).optional(),
-    voiceover: z3.object({
+    voiceover: z4.object({
       // on_camera | mixed → mouths are on screen (lip-sync candidates);
       // voiceover | none → narration over the picture (no lip-sync).
-      mode: z3.string().optional(),
-      voice_description: z3.string().optional(),
-      persona: z3.string().optional()
+      mode: z4.string().optional(),
+      voice_description: z4.string().optional(),
+      persona: z4.string().optional()
     }).loose().optional(),
     // Visual palette — read only to colour a clean brand-card/CTA plate (the
     // first hex is the dominant brand colour); never to drive frame generation.
-    style: z3.object({ palette: z3.array(z3.object({ hex: z3.string().optional() }).loose()).optional() }).loose().optional()
+    style: z4.object({ palette: z4.array(z4.object({ hex: z4.string().optional() }).loose()).optional() }).loose().optional()
   }).loose().optional(),
-  scenes: z3.array(Scene).min(1)
+  scenes: z4.array(Scene).min(1)
 }).loose();
 function injectHookPhysicality(blueprint) {
   for (const scene of blueprint.scenes) {
@@ -9461,26 +9711,26 @@ function injectHookPhysicality(blueprint) {
     scene.start_frame_prompt = `${prompt} The subject's physical state IS the scroll-stopper \u2014 render it explicitly, not a calm pose: ${why}.`;
   }
 }
-var AppearsItem = z3.union([z3.number(), z3.object({ scene: z3.number(), edge: z3.string().optional() }).loose()]);
-var RecurringElement = z3.object({
+var AppearsItem = z4.union([z4.number(), z4.object({ scene: z4.number(), edge: z4.string().optional() }).loose()]);
+var RecurringElement = z4.object({
   // person | animal | product | logo | badge | other
-  type: z3.string(),
-  label: z3.string().optional(),
-  description: z3.string().optional(),
-  expression: z3.string().nullable().optional(),
+  type: z4.string(),
+  label: z4.string().optional(),
+  description: z4.string().optional(),
+  expression: z4.string().nullable().optional(),
   // When the element maps to a global cast entry, its stable id (for annotation).
-  cast_id: z3.string().nullable().optional(),
+  cast_id: z4.string().nullable().optional(),
   // The label of another element that is the SAME individual as this one, shown
   // in a DIFFERENT wardrobe/persona/state (e.g. one creator playing skeptic in a
   // pink shirt and believer in a white shirt). Each look gets its own reference
   // slot, but the face/identity must stay identical across them.
-  same_as: z3.string().nullable().optional(),
+  same_as: z4.string().nullable().optional(),
   // Scenes the element appears in. Either a bare list of scene indices (both
   // edges) or per-{scene,edge} entries. Both forms are accepted and merged.
-  scenes: z3.array(z3.number()).optional(),
-  appears_in: z3.array(AppearsItem).optional()
+  scenes: z4.array(z4.number()).optional(),
+  appears_in: z4.array(AppearsItem).optional()
 }).loose();
-var RecurringElements = z3.array(RecurringElement);
+var RecurringElements = z4.array(RecurringElement);
 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;
@@ -10943,25 +11193,25 @@ function buildSfxMusic(blueprint, nodes) {
   }
   return tracks;
 }
-var OverlayStyle = z3.object({ color_hex: z3.string().optional(), background: z3.string().optional(), size: z3.string().optional() }).loose();
-var Overlay = z3.object({
-  text: z3.string().optional(),
-  appears_at_s: z3.number().optional(),
-  duration_s: z3.number().optional(),
-  position: z3.string().optional(),
-  role: z3.string().optional(),
-  animation: z3.string().optional(),
-  animation_detail: z3.string().optional(),
+var OverlayStyle = z4.object({ color_hex: z4.string().optional(), background: z4.string().optional(), size: z4.string().optional() }).loose();
+var Overlay = z4.object({
+  text: z4.string().optional(),
+  appears_at_s: z4.number().optional(),
+  duration_s: z4.number().optional(),
+  position: z4.string().optional(),
+  role: z4.string().optional(),
+  animation: z4.string().optional(),
+  animation_detail: z4.string().optional(),
   style: OverlayStyle.optional()
 }).loose();
-var FloatingElement = z3.object({
-  kind: z3.string().optional(),
-  description: z3.string().optional(),
-  brand_name: z3.string().nullish(),
-  what_it_represents: z3.string().optional(),
-  appears_at_s: z3.number().optional(),
-  duration_s: z3.number().optional(),
-  position: z3.string().optional()
+var FloatingElement = z4.object({
+  kind: z4.string().optional(),
+  description: z4.string().optional(),
+  brand_name: z4.string().nullish(),
+  what_it_represents: z4.string().optional(),
+  appears_at_s: z4.number().optional(),
+  duration_s: z4.number().optional(),
+  position: z4.string().optional()
 }).loose();
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -10993,7 +11243,7 @@ function positionClass(position) {
 function collectCaptions(blueprint) {
   return blueprint.scenes.flatMap((scene) => {
     const sceneStart = scene.start_s ?? 0;
-    const overlays = z3.array(Overlay).safeParse(scene.overlays ?? []);
+    const overlays = z4.array(Overlay).safeParse(scene.overlays ?? []);
     return overlays.success ? overlays.data.filter((ov) => Boolean(ov.text?.trim())).map((ov) => {
       const at = ov.appears_at_s ?? sceneStart;
       return { text: ov.text.trim(), at, end: at + (ov.duration_s ?? 2.5), ov };
@@ -11102,7 +11352,7 @@ function buildOverlayHtml(input) {
   if (ovParts.length > 0) blocks.push(ovParts.join("\n"));
   for (const scene of blueprint.scenes) {
     const sceneStart = scene.start_s ?? 0;
-    const floats = z3.array(FloatingElement).safeParse(scene.floating_elements ?? []);
+    const floats = z4.array(FloatingElement).safeParse(scene.floating_elements ?? []);
     const parts = (floats.success ? floats.data.map((fe) => floatingStub(fe, sceneStart)) : []).filter(Boolean);
     const pip = uiPipStub(scene);
     if (pip) parts.push(pip);
@@ -11359,8 +11609,8 @@ function buildMotionBoard(blueprint) {
     const end_s = scene.end_s ?? start_s + sceneDurationS(scene);
     cursor = end_s;
     const spoken = sceneSpokenText(scene);
-    const overlays = z3.array(Overlay).safeParse(scene.overlays ?? []);
-    const floats = z3.array(FloatingElement).safeParse(scene.floating_elements ?? []);
+    const overlays = z4.array(Overlay).safeParse(scene.overlays ?? []);
+    const floats = z4.array(FloatingElement).safeParse(scene.floating_elements ?? []);
     const graphics = [
       ...(overlays.success ? overlays.data : []).filter((ov) => ov.text?.trim()).map((ov) => ({
         kind: "text",