@hubfluencer/mcp 0.7.1 → 0.8.1

package/README.md

@@ -68,7 +68,7 @@ claude mcp add hubfluencer --env HUBFLUENCER_API_TOKEN=YOUR_TOKEN -- npx -y @hub
 
 ## Tools
 
-89 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
+91 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
 below are the ground truth. **"$0" means it spends no video credits**; planning/AI-helper tools
 instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_assists`: 1 credit
 → +10). Reads need the `video:read` scope; writes need `video:generate`. Nothing here needs
@@ -83,7 +83,7 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `update_short` | Patch an existing short draft — brief (`product_prompt`), copy, styling, or the opt-in conversion graphics; only the fields you pass change. Clear one with `""` (`[]` for `text_beats`, `0` for `star_rating`). Re-run `generate_short` to apply. | **0** |
 | `generate_short` | Render an existing short. Safe to re-call (in-flight = reported, no double charge; a failed short can re-generate). | **15** |
 | `generate_short_text` | AI-draft editable headline / subheadline / caption beats for a short. | 1 assist |
-| `create_editor_ad` | Create an editor project **and** run autopilot end-to-end. Style it with `creative_format` + `visual_language` + `theme`. | credits (est. first) |
+| `create_editor_ad` | Create an editor project **and** run autopilot end-to-end. Style it with `creative_format` + `visual_language` + `theme`. Cast modes need prerequisite assets, so configure them through `create_editor_draft` instead. | credits (est. first) |
 | `start_autopilot` | Run autopilot on an **existing** editor draft (resume a `make_video` `dry_run`, or after a top-up). | credits |
 | `create_slider` | Create an image-carousel draft: one prompt → N still slides + a ready-to-post caption + hashtags. `mode` `creative` (story) or `ad_driven` (facts). | **0** |
 | `generate_slider` | Render a carousel (copy → AI backgrounds → composite). Poll `get_slider` until `completed`. | **1 / slide** (3–10) |
@@ -96,12 +96,14 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 
 | Tool | What it does | Cost |
 |---|---|---|
-| `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme`. | **0** |
+| `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme` / `cast_mode` (`product_only` needs `set_product` before generation; `presenter_led` needs a configured presenter). | **0** |
 | `get_editor` | Full project state (scenario, segments, narration, music, latest render, quota) — the review step. | **0** |
 | `set_scenario` / `generate_scenario` | Write your own scenario (free) **or** AI-draft it. `generate_scenario` can also persist `creative_format` / `visual_language` / `theme`. | free / 1 assist |
+| `apply_scenario` | Compile the **ready** scenario into per-scene prompts on the timeline (`segments_count` 0 or 3..10; omitted uses the generated scenario count, then 5; AI scenes replaced, uploads preserved). Polls until applied (~2 min budget). | **0** |
 | `set_scene_count` | Grow/shrink to N scenes (1–20); deletes only trailing un-generated scenes. Each AI scene is a fixed 8s. | **0** |
 | `set_segment_prompt` | Write one scene's prompt (1–2000 chars), identified by segment id. | **0** |
-| `generate_segment` | Render one scene (re-call to retry a failed one). | **5** |
+| `generate_segment` | Render one **pending/failed** scene (re-call to retry a failed one). | **5** |
+| `regenerate_segment` | Re-roll a **completed** scene as a new version (optional new `prompt`). Mid-timeline: the next scene's transition can degrade because it was seeded from the old version's last frame. | **4** |
 | `generate_all_segments` | Render every not-yet-completed scene in order (continuity preserved); capped ~280s → re-run to continue. | **5 / segment** |
 | `set_narration_script` / `generate_narration` | Write your own voiceover script (free) **or** AI-draft it. | free / 1 assist |
 | `generate_voice` | Synthesize the voiceover. `voice_id` required (see `list_voices`). | **3** |
@@ -220,6 +222,7 @@ edit are **0 credits** — you only pay to generate/render.
 | Any draft create / edit / reorder | 0 |
 | Short render | **15** |
 | Editor AI scene (`generate_segment`) | **5** (4 each in a batch of ≥3) |
+| Editor scene re-roll (`regenerate_segment`, new version of a completed scene) | **4** |
 | Editor voice | **3** |
 | Editor music | **5** |
 | Editor render | **0** (auto-charges only still-ungenerated scenes) |

package/dist/index.js

@@ -30120,7 +30120,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.7.1",
+  version: "0.8.1",
   description: "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   license: "MIT",
   author: "Monocursive <contact@monocursive.com>",
@@ -31454,7 +31454,7 @@ var SERVER_INSTRUCTIONS = `Hubfluencer turns a prompt — or a whole product pag
 
 MAKE ONE ASSET (simplest)
 - make_video({ prompt }) creates, generates, and returns a finished MP4 — it picks a single-clip short or a multi-scene editor ad from the prompt (override with kind:"short"|"editor"). create_short / create_editor_ad are the per-product one-shots; create_slider makes an image carousel; create_tracking_video burns a CV overlay onto a local clip.
-- Granular (full control): create a draft, then drive the pipeline step by step (create_editor_draft → generate_scenario → set_scene_count → set_segment_prompt → generate_segment(s) → generate_voice + generate_music → render). Poll with get_status / wait_for_completion; fetch with download_result (a slider has no MP4 — read its slides with get_slider).
+- Granular (full control): create a draft, then drive the pipeline step by step (create_editor_draft → generate_scenario → apply_scenario → review/edit prompts (set_segment_prompt) → generate_segment(s) → generate_voice + generate_music → render; regenerate_segment re-rolls a completed scene as a new version). Poll with get_status / wait_for_completion; fetch with download_result (a slider has no MP4 — read its slides with get_slider).
 
 DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 1. ONBOARD a product: extract_product_page(url) pulls facts + imagery (SSRF-hardened, 0cr); import_product_image saves its picture/logo. Persist identity once with create_product_profile + create_brand_profile so every later draft inherits it instead of re-describing the brand.
@@ -32294,7 +32294,7 @@ registerTool("edit_slider_slide", {
 }));
 registerTool("create_editor_ad", {
   title: "Create a multi-scene editor ad (autopilot)",
-  description: "Creates an editor project from a product prompt and starts autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Returns the slug. Costs credits. Then poll with get_status / wait_for_completion (kind=editor). Prefer " + "make_video for the one-shot path. " + "BRANDING: to attach the user's own product image, brand logo, or closing card, create the draft with " + "create_editor_draft first, call set_product / set_logo / set_closing_image (all 0 credits), then " + "start_autopilot — autopilot weaves them in. (Editor ads carry their copy in-scene/narration, not as a " + "title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.)",
+  description: "Creates an editor project from a product prompt and starts autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Returns the slug. Costs credits. Then poll with get_status / wait_for_completion (kind=editor). Prefer " + "make_video for the one-shot path. " + "BRANDING: to attach the user's own product image, brand logo, or closing card, create the draft with " + "create_editor_draft first, call set_product / set_logo / set_closing_image (all 0 credits), then " + "start_autopilot — autopilot weaves them in. (Editor ads carry their copy in-scene/narration, not as a " + "title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.) " + "For product_only or presenter_led cast modes, use create_editor_draft and configure the required " + "product/presenter before start_autopilot; this one-shot tool intentionally uses automatic casting.",
   inputSchema: {
     product_prompt: exports_external.string().min(10).describe("Brief for the ad (min 10 chars)"),
     product_subject: exports_external.string().max(300).optional().describe('The concrete product or main subject the video must be about (e.g. "Bordeaux red wine, dark green ' + 'bottle with a gold label"). Distinct from the freeform brief: hard-grounds the AI scenario + narration ' + "so it cannot invent an unrelated product. Strongly recommended for ads."),
@@ -32391,6 +32391,7 @@ registerTool("create_editor_draft", {
     creative_format: exports_external.enum(CREATIVE_FORMATS).optional().describe("Narrative arc / segment structure. Omit for Auto/generic."),
     visual_language: exports_external.enum(VISUAL_LANGUAGES).optional().describe("Visual style direction and render look. Good default: kinetic_creator. When set it drives the look and a theme of 'none' is ignored."),
     theme: exports_external.string().optional().describe('Visual theme / genre overlay (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.'),
+    cast_mode: exports_external.enum(["product_only", "presenter_led"]).optional().describe("Who/what anchors every AI scene. product_only = a product-led ad with NO people; requires a " + "product image (set_product) before generation and generates every scene from persistent product " + "reference images — the best product fidelity. presenter_led = one locked presenter appears in " + "every scene; requires a presenter to be configured first (in the app / REST presenter endpoints " + "— no MCP tool yet), else generation fails with presenter_required. Omit for the default auto " + "behavior."),
     voice_id: exports_external.string().regex(/^[A-Za-z0-9_-]+$/).max(64).optional().describe("Preferred narration voice id (see list_voices); ≤64 chars, [A-Za-z0-9_-] only"),
     export_aspect_ratio: exports_external.enum(["9:16", "16:9", "1:1"]).optional().describe('Aspect ratio (default "9:16")'),
     project_intent: exports_external.enum(["social_ad", "creative_story"]).optional().describe("social_ad for promotional/ad content (product focus + CTA), creative_story for brand " + "narratives (default).")
@@ -32409,17 +32410,18 @@ registerTool("create_editor_draft", {
     creative_format: args.creative_format,
     visual_language: args.visual_language,
     theme: args.theme,
+    cast_mode: args.cast_mode,
     voice_id: args.voice_id,
     export_aspect_ratio: args.export_aspect_ratio,
     project_intent: args.project_intent
   };
   if (prompt)
     body.product_prompt = prompt;
-  const created = await client.post("/editor", body, idemKey("create-editor-draft", prompt ?? "", args.product_subject ?? "", args.project_intent ?? "", args.language ?? "en", args.creative_format ?? "", args.visual_language ?? "", args.theme ?? "", args.voice_id ?? "", args.export_aspect_ratio ?? ""));
+  const created = await client.post("/editor", body, idemKey("create-editor-draft", prompt ?? "", args.product_subject ?? "", args.project_intent ?? "", args.language ?? "en", args.creative_format ?? "", args.visual_language ?? "", args.theme ?? "", args.voice_id ?? "", args.export_aspect_ratio ?? "", args.cast_mode ?? ""));
   return ok({
     slug: created.data.slug,
     kind: "editor",
-    next: "generate_scenario | set_scenario, then get_editor to review"
+    next: "generate_scenario | set_scenario, then get_editor to review, then apply_scenario"
   });
 }));
 registerTool("get_editor", {
@@ -32445,7 +32447,7 @@ registerTool("set_scenario", {
 }));
 registerTool("generate_scenario", {
   title: "Generate the editor scenario (AI assist)",
-  description: "Generates a scenario with AI. CONSUMES 1 AI ASSIST (free daily quota; check get_ai_assists). On 429 " + "(quota exhausted) either set auto_unlock:true to spend 1 credit for +10 assists and retry once, or " + "write the scenario yourself with set_scenario. Server default segments_count is 5. " + "Optionally pass creative_format / visual_language / theme to persist the project’s creative style before " + "generating (this is the granular path’s way to set/change style; PATCH /scenario does not).",
+  description: "Generates a scenario with AI. CONSUMES 1 AI ASSIST (free daily quota; check get_ai_assists). On 429 " + "(quota exhausted) either set auto_unlock:true to spend 1 credit for +10 assists and retry once, or " + "write the scenario yourself with set_scenario. Server default segments_count is 5. " + "Optionally pass creative_format / visual_language / theme to persist the project’s creative style before " + "generating (this is the granular path’s way to set/change style; PATCH /scenario does not). " + "Generation is ASYNC: get_editor shows scenario_status generating → ready (a few seconds). NEXT STEP: " + "once ready, review the scenario with get_editor, then call apply_scenario to turn it into per-scene " + "segment prompts on the timeline.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     segments_count: exports_external.number().int().min(3).max(10).optional().describe("How many scenes (3–10, server default 5)"),
@@ -32472,6 +32474,63 @@ registerTool("generate_scenario", {
   const res = await withAssist(client, args.auto_unlock ?? false, () => client.post(`/editor/${args.slug}/generate-scenario`, body));
   return ok(asRecord(res).data ?? res);
 }));
+registerTool("apply_scenario", {
+  title: "Apply the scenario to the timeline (per-scene prompts)",
+  description: "Turns the READY scenario into per-scene segment prompts on the timeline — the missing step between " + "generate_scenario and generate_segment in the granular flow. Existing AI segments are REPLACED with " + "freshly generated scene prompts (uploaded clips are preserved); segments_count 0 removes the AI scenes " + "and keeps the scenario only. Free — no credits, no AI assist (rate limit 15/min). Requires " + 'scenario_status "ready" (422 scenario_not_ready otherwise): after generate_scenario wait until ' + "get_editor shows ready (a few seconds); set_scenario is ready immediately. The apply itself runs async " + "server-side — this tool polls get_editor (bounded ~2 min) until scenario_apply_status leaves " + '"applying" and returns the materialized prompts; if it reports timed_out, keep polling get_editor ' + "yourself. Then review/edit with set_segment_prompt and generate with generate_segment / " + "generate_all_segments (or just render).",
+  inputSchema: {
+    slug: exports_external.string().describe("Editor project slug"),
+    segments_count: exports_external.union([exports_external.literal(0), exports_external.number().int().min(3).max(10)]).optional().describe("How many AI scenes to create on the timeline — 0 or any integer from 3 to 10. Omit to use " + "the scene count saved by generate_scenario (or 5 when none is stored). " + "0 keeps the scenario only and preserves manual timeline control.")
+  },
+  annotations: { title: "Apply scenario", ...WRITE, idempotentHint: false }
+}, tool(async (args, client, extra) => {
+  const body = {};
+  if (args.segments_count !== undefined)
+    body.segments_count = args.segments_count;
+  const res = await client.post(`/editor/${args.slug}/apply-scenario`, body);
+  const accepted = asRecord(asRecord(res).data);
+  const APPLY_BUDGET_MS = 120000;
+  const APPLY_POLL_MS = 2500;
+  const deadline = Date.now() + APPLY_BUDGET_MS;
+  const readEditor = async () => {
+    const r = await client.get(`/editor/${args.slug}`, undefined, deadline);
+    return asRecord(asRecord(r).data);
+  };
+  let n = 0;
+  let editor = await readEditor();
+  while (editor.scenario_apply_status === "applying" && Date.now() + APPLY_POLL_MS <= deadline) {
+    await reportProgress(extra, ++n, "applying scenario to timeline");
+    await sleep4(APPLY_POLL_MS);
+    editor = await readEditor();
+  }
+  if (editor.scenario_apply_status === "applying") {
+    return ok({
+      slug: args.slug,
+      applied: false,
+      timed_out: true,
+      note: 'The apply is still running server-side. Poll get_editor until scenario_apply_status is no longer "applying", then review the scene prompts.'
+    });
+  }
+  if (editor.scenario_apply_status === "failed") {
+    return fail("Scenario apply failed server-side. Re-run apply_scenario to retry, or build the timeline yourself with set_scene_count + set_segment_prompt.");
+  }
+  const segments = Array.isArray(editor.segments) ? editor.segments : [];
+  return ok({
+    slug: args.slug,
+    applied: true,
+    ai_segments_replaced: accepted.ai_segments_replaced,
+    uploads_preserved: accepted.uploads_preserved,
+    target_ai_segments: accepted.target_ai_segments,
+    scene_count: segments.length,
+    segments: segments.map((s) => ({
+      id: s.id,
+      position: s.position,
+      source_type: s.source_type,
+      status: s.status,
+      prompt: s.prompt
+    })),
+    next: "Review/edit prompts (set_segment_prompt), then generate_segment / generate_all_segments — or just render (it auto-charges ungenerated scenes at the batch rate)"
+  });
+}));
 registerTool("set_scene_count", {
   title: "Set the number of scenes",
   description: "Adjusts the editor to exactly `count` scenes (1–20) by adding pending segments to grow, or deleting " + "only TRAILING un-generated (pending or failed) segments to shrink. Never deletes completed/processing segments — " + "if a shrink would require that, it stops and reports. Free (no credits, no assist). Each AI-generated " + "scene is a fixed 8 seconds, so `count` scenes ≈ count×8s of AI footage (uploaded clips keep their own length).",
@@ -32539,7 +32598,7 @@ registerTool("set_segment_prompt", {
 }));
 registerTool("generate_segment", {
   title: "Generate one segment (5 credits)",
-  description: "Renders the video for one scene. Each AI-generated scene is a fixed 8 seconds long. Costs 5 credits. " + "Re-call to retry a failed scene or regenerate after a prompt edit — the server blocks regenerating one that's still processing, so no double-charge. Visual" + "continuity is handled server-side (this scene uses the previous scene's last frame). 402 " + "credits_insufficient fails cleanly. Generate scenes in position order for correct continuity.",
+  description: "Renders the video for one PENDING or FAILED scene. Each AI-generated scene is a fixed 8 seconds long. " + "Costs 5 credits. Re-call to retry a failed scene or after a prompt edit — the server blocks one that's " + "still processing (editor_segment_busy), so no double-charge; a COMPLETED scene returns " + "editor_segment_completed — re-roll those with regenerate_segment instead. Visual " + "continuity is handled server-side (this scene uses the previous scene's last frame). 402 " + "credits_insufficient fails cleanly. Generate scenes in position order for correct continuity.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     segment_id: exports_external.union([exports_external.number(), exports_external.string()]).describe("Segment id (from get_editor)")
@@ -32549,6 +32608,23 @@ registerTool("generate_segment", {
   const res = await client.post(`/editor/${args.slug}/segments/${String(args.segment_id)}/generate`, undefined, undefined);
   return ok(asRecord(res).data ?? res);
 }));
+registerTool("regenerate_segment", {
+  title: "Regenerate a completed segment (new version, 4 credits)",
+  description: "Re-rolls a COMPLETED scene as a NEW VERSION of that segment — the previous version is kept (switch back " + "in the app). Costs 4 credits. Use generate_segment for pending/failed scenes; use THIS for a completed " + "scene you want different — optionally with a new prompt (omit it to re-roll the current prompt). The new " + "version starts rendering immediately; watch it with get_editor (status processing → completed|failed). " + "KNOWN LIMITATION: scenes chain visual continuity off the previous scene's last frame, so regenerating a " + "MID-TIMELINE scene can degrade the transition into the FOLLOWING scene (it was seeded from the old " + "version's last frame). A scene still processing returns editor_segment_busy (no double charge); 402 " + "credits_insufficient fails cleanly.",
+  inputSchema: {
+    slug: exports_external.string().describe("Editor project slug"),
+    segment_id: exports_external.union([exports_external.number(), exports_external.string()]).describe("Segment id (from get_editor)"),
+    prompt: exports_external.string().min(1).max(2000).optional().describe("Optional new scene prompt for the regenerated version (1–2000 chars); omit to reuse the current prompt")
+  },
+  annotations: {
+    title: "Regenerate segment",
+    ...WRITE,
+    idempotentHint: false
+  }
+}, tool(async (args, client) => {
+  const res = await client.post(`/editor/${args.slug}/segments/${String(args.segment_id)}/regenerate`, args.prompt !== undefined ? { prompt: args.prompt } : undefined, undefined);
+  return ok(asRecord(res).data ?? res);
+}));
 registerTool("generate_all_segments", {
   title: "Generate all pending segments (sequential)",
   description: "Generates every not-yet-completed scene (pending or previously failed) in position order, waiting for each to finish before starting" + "the next (preserves visual continuity). Each AI-generated scene is a fixed 8 seconds, so N scenes ≈ N×8s of footage. Costs 5 credits per segment generated. Stops and reports what " + "completed if a scene errors on submit (e.g. 402 credits_insufficient) or fails while rendering; if a " + "scene is still rendering past the budget it returns timed_out so you can re-run to continue (completed " + "scenes are skipped). The whole call is capped at ~280s: on a project with many scenes it processes as " + "many as fit, returns timed_out, and you re-run to continue (it picks up the remaining pending scenes). " + "Tip: to generate everything at lowest cost, skip this and just call render — it auto-generates any ungenerated scenes at the batch rate (4 credits/scene for ≥3); use this tool when you want to review or stop per scene. May take several minutes.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubfluencer/mcp",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   "license": "MIT",
   "author": "Monocursive <contact@monocursive.com>",

package/src/index.ts

@@ -11,7 +11,8 @@
  *   Shorts   : create_short → generate_short → wait_for_completion → download_result
  *   Editor   : create_editor_ad (creates + starts autopilot) → wait_for_completion → download_result
  *   Granular : create_editor_draft → generate_scenario|set_scenario → get_editor
- *              → set_scene_count → set_segment_prompt → generate_segment(s)
+ *              → apply_scenario (scenario → scene prompts) | set_scene_count + set_segment_prompt
+ *              → generate_segment(s) (+ regenerate_segment to re-roll a completed scene)
  *              → set_narration_script|generate_narration → generate_voice + generate_music
  *              → render → wait_for_completion → download_result
  */
@@ -500,7 +501,7 @@ const SERVER_INSTRUCTIONS = `Hubfluencer turns a prompt — or a whole product p
 
 MAKE ONE ASSET (simplest)
 - make_video({ prompt }) creates, generates, and returns a finished MP4 — it picks a single-clip short or a multi-scene editor ad from the prompt (override with kind:"short"|"editor"). create_short / create_editor_ad are the per-product one-shots; create_slider makes an image carousel; create_tracking_video burns a CV overlay onto a local clip.
-- Granular (full control): create a draft, then drive the pipeline step by step (create_editor_draft → generate_scenario → set_scene_count → set_segment_prompt → generate_segment(s) → generate_voice + generate_music → render). Poll with get_status / wait_for_completion; fetch with download_result (a slider has no MP4 — read its slides with get_slider).
+- Granular (full control): create a draft, then drive the pipeline step by step (create_editor_draft → generate_scenario → apply_scenario → review/edit prompts (set_segment_prompt) → generate_segment(s) → generate_voice + generate_music → render; regenerate_segment re-rolls a completed scene as a new version). Poll with get_status / wait_for_completion; fetch with download_result (a slider has no MP4 — read its slides with get_slider).
 
 DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 1. ONBOARD a product: extract_product_page(url) pulls facts + imagery (SSRF-hardened, 0cr); import_product_image saves its picture/logo. Persist identity once with create_product_profile + create_brand_profile so every later draft inherits it instead of re-describing the brand.
@@ -2578,7 +2579,9 @@ registerTool(
 			"BRANDING: to attach the user's own product image, brand logo, or closing card, create the draft with " +
 			"create_editor_draft first, call set_product / set_logo / set_closing_image (all 0 credits), then " +
 			"start_autopilot — autopilot weaves them in. (Editor ads carry their copy in-scene/narration, not as a " +
-			"title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.)",
+			"title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.) " +
+			"For product_only or presenter_led cast modes, use create_editor_draft and configure the required " +
+			"product/presenter before start_autopilot; this one-shot tool intentionally uses automatic casting.",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -2826,7 +2829,8 @@ registerTool(
 // ad with full control (review the scenario, write its own prompts, etc.)
 // instead of one-shot autopilot (create_editor_ad / make_video).
 //   create_editor_draft → generate_scenario|set_scenario → get_editor (REVIEW)
-//   → set_scene_count → set_segment_prompt → generate_segment|generate_all_segments
+//   → apply_scenario (scenario → per-scene prompts) | set_scene_count + set_segment_prompt
+//   → generate_segment|generate_all_segments (+ regenerate_segment for completed scenes)
 //   → set_narration_script|generate_narration → generate_voice + generate_music
 //   → render → wait_for_completion(kind:"editor") → download_result.
 
@@ -2877,6 +2881,17 @@ registerTool(
 				.describe(
 					'Visual theme / genre overlay (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
 				),
+			cast_mode: z
+				.enum(["product_only", "presenter_led"])
+				.optional()
+				.describe(
+					"Who/what anchors every AI scene. product_only = a product-led ad with NO people; requires a " +
+						"product image (set_product) before generation and generates every scene from persistent product " +
+						"reference images — the best product fidelity. presenter_led = one locked presenter appears in " +
+						"every scene; requires a presenter to be configured first (in the app / REST presenter endpoints " +
+						"— no MCP tool yet), else generation fails with presenter_required. Omit for the default auto " +
+						"behavior.",
+				),
 			voice_id: z
 				.string()
 				.regex(/^[A-Za-z0-9_-]+$/)
@@ -2913,6 +2928,7 @@ registerTool(
 				creative_format?: string;
 				visual_language?: string;
 				theme?: string;
+				cast_mode?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
 				project_intent?: string;
@@ -2926,6 +2942,7 @@ registerTool(
 				creative_format: args.creative_format,
 				visual_language: args.visual_language,
 				theme: args.theme,
+				cast_mode: args.cast_mode,
 				voice_id: args.voice_id,
 				export_aspect_ratio: args.export_aspect_ratio,
 				project_intent: args.project_intent,
@@ -2948,12 +2965,13 @@ registerTool(
 					args.theme ?? "",
 					args.voice_id ?? "",
 					args.export_aspect_ratio ?? "",
+					args.cast_mode ?? "",
 				),
 			);
 			return ok({
 				slug: created.data.slug,
 				kind: "editor",
-				next: "generate_scenario | set_scenario, then get_editor to review",
+				next: "generate_scenario | set_scenario, then get_editor to review, then apply_scenario",
 			});
 		},
 	),
@@ -3011,7 +3029,10 @@ registerTool(
 			"(quota exhausted) either set auto_unlock:true to spend 1 credit for +10 assists and retry once, or " +
 			"write the scenario yourself with set_scenario. Server default segments_count is 5. " +
 			"Optionally pass creative_format / visual_language / theme to persist the project\u2019s creative style before " +
-			"generating (this is the granular path\u2019s way to set/change style; PATCH /scenario does not).",
+			"generating (this is the granular path\u2019s way to set/change style; PATCH /scenario does not). " +
+			"Generation is ASYNC: get_editor shows scenario_status generating \u2192 ready (a few seconds). NEXT STEP: " +
+			"once ready, review the scenario with get_editor, then call apply_scenario to turn it into per-scene " +
+			"segment prompts on the timeline.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			segments_count: z
@@ -3083,6 +3104,111 @@ registerTool(
 	),
 );
 
+registerTool(
+	"apply_scenario",
+	{
+		title: "Apply the scenario to the timeline (per-scene prompts)",
+		description:
+			"Turns the READY scenario into per-scene segment prompts on the timeline — the missing step between " +
+			"generate_scenario and generate_segment in the granular flow. Existing AI segments are REPLACED with " +
+			"freshly generated scene prompts (uploaded clips are preserved); segments_count 0 removes the AI scenes " +
+			"and keeps the scenario only. Free — no credits, no AI assist (rate limit 15/min). Requires " +
+			'scenario_status "ready" (422 scenario_not_ready otherwise): after generate_scenario wait until ' +
+			"get_editor shows ready (a few seconds); set_scenario is ready immediately. The apply itself runs async " +
+			"server-side — this tool polls get_editor (bounded ~2 min) until scenario_apply_status leaves " +
+			'"applying" and returns the materialized prompts; if it reports timed_out, keep polling get_editor ' +
+			"yourself. Then review/edit with set_segment_prompt and generate with generate_segment / " +
+			"generate_all_segments (or just render).",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segments_count: z
+				.union([z.literal(0), z.number().int().min(3).max(10)])
+				.optional()
+				.describe(
+					"How many AI scenes to create on the timeline — 0 or any integer from 3 to 10. Omit to use " +
+						"the scene count saved by generate_scenario (or 5 when none is stored). " +
+						"0 keeps the scenario only and preserves manual timeline control.",
+				),
+		},
+		annotations: { title: "Apply scenario", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (args: { slug: string; segments_count?: number }, client, extra) => {
+			const body: Record<string, unknown> = {};
+			if (args.segments_count !== undefined)
+				body.segments_count = args.segments_count;
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/apply-scenario`,
+				body,
+			);
+			const accepted = asRecord(asRecord(res).data);
+
+			// The 202 only STARTS the apply — the controller flips
+			// scenario_apply_status to "applying" before responding, and an async
+			// worker compiles the scenario into per-scene prompts. Poll the project
+			// until the status leaves "applying" ("idle" = success, "failed" =
+			// terminal) so the agent gets the materialized prompts back instead of
+			// having to poll itself. The budget is far below the render loops' 280s
+			// ceiling: an apply is a single LLM call (typically seconds).
+			const APPLY_BUDGET_MS = 120_000;
+			const APPLY_POLL_MS = 2_500;
+			const deadline = Date.now() + APPLY_BUDGET_MS;
+			const readEditor = async () => {
+				// Bound each poll GET's retries by the loop deadline (see fetchStatus).
+				const r = await client.get<{ data: unknown }>(
+					`/editor/${args.slug}`,
+					undefined,
+					deadline,
+				);
+				return asRecord(asRecord(r).data);
+			};
+			let n = 0;
+			let editor = await readEditor();
+			while (
+				editor.scenario_apply_status === "applying" &&
+				Date.now() + APPLY_POLL_MS <= deadline
+			) {
+				await reportProgress(extra, ++n, "applying scenario to timeline");
+				await sleep(APPLY_POLL_MS);
+				editor = await readEditor();
+			}
+
+			if (editor.scenario_apply_status === "applying") {
+				return ok({
+					slug: args.slug,
+					applied: false,
+					timed_out: true,
+					note: 'The apply is still running server-side. Poll get_editor until scenario_apply_status is no longer "applying", then review the scene prompts.',
+				});
+			}
+			if (editor.scenario_apply_status === "failed") {
+				return fail(
+					"Scenario apply failed server-side. Re-run apply_scenario to retry, or build the timeline yourself with set_scene_count + set_segment_prompt.",
+				);
+			}
+			const segments = Array.isArray(editor.segments)
+				? (editor.segments as Record<string, unknown>[])
+				: [];
+			return ok({
+				slug: args.slug,
+				applied: true,
+				ai_segments_replaced: accepted.ai_segments_replaced,
+				uploads_preserved: accepted.uploads_preserved,
+				target_ai_segments: accepted.target_ai_segments,
+				scene_count: segments.length,
+				segments: segments.map((s) => ({
+					id: s.id,
+					position: s.position,
+					source_type: s.source_type,
+					status: s.status,
+					prompt: s.prompt,
+				})),
+				next: "Review/edit prompts (set_segment_prompt), then generate_segment / generate_all_segments — or just render (it auto-charges ungenerated scenes at the batch rate)",
+			});
+		},
+	),
+);
+
 registerTool(
 	"set_scene_count",
 	{
@@ -3214,8 +3340,10 @@ registerTool(
 	{
 		title: "Generate one segment (5 credits)",
 		description:
-			"Renders the video for one scene. Each AI-generated scene is a fixed 8 seconds long. Costs 5 credits. " +
-			"Re-call to retry a failed scene or regenerate after a prompt edit — the server blocks regenerating one that's still processing, so no double-charge. Visual" +
+			"Renders the video for one PENDING or FAILED scene. Each AI-generated scene is a fixed 8 seconds long. " +
+			"Costs 5 credits. Re-call to retry a failed scene or after a prompt edit — the server blocks one that's " +
+			"still processing (editor_segment_busy), so no double-charge; a COMPLETED scene returns " +
+			"editor_segment_completed — re-roll those with regenerate_segment instead. Visual " +
 			"continuity is handled server-side (this scene uses the previous scene's last frame). 402 " +
 			"credits_insufficient fails cleanly. Generate scenes in position order for correct continuity.",
 		inputSchema: {
@@ -3236,6 +3364,54 @@ registerTool(
 	}),
 );
 
+registerTool(
+	"regenerate_segment",
+	{
+		title: "Regenerate a completed segment (new version, 4 credits)",
+		description:
+			"Re-rolls a COMPLETED scene as a NEW VERSION of that segment — the previous version is kept (switch back " +
+			"in the app). Costs 4 credits. Use generate_segment for pending/failed scenes; use THIS for a completed " +
+			"scene you want different — optionally with a new prompt (omit it to re-roll the current prompt). The new " +
+			"version starts rendering immediately; watch it with get_editor (status processing → completed|failed). " +
+			"KNOWN LIMITATION: scenes chain visual continuity off the previous scene's last frame, so regenerating a " +
+			"MID-TIMELINE scene can degrade the transition into the FOLLOWING scene (it was seeded from the old " +
+			"version's last frame). A scene still processing returns editor_segment_busy (no double charge); 402 " +
+			"credits_insufficient fails cleanly.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segment_id: z
+				.union([z.number(), z.string()])
+				.describe("Segment id (from get_editor)"),
+			prompt: z
+				.string()
+				.min(1)
+				.max(2000)
+				.optional()
+				.describe(
+					"Optional new scene prompt for the regenerated version (1–2000 chars); omit to reuse the current prompt",
+				),
+		},
+		annotations: {
+			title: "Regenerate segment",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: { slug: string; segment_id: number | string; prompt?: string },
+			client,
+		) => {
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/segments/${String(args.segment_id)}/regenerate`,
+				args.prompt !== undefined ? { prompt: args.prompt } : undefined,
+				undefined,
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
 registerTool(
 	"generate_all_segments",
 	{