@hubfluencer/mcp 0.11.0 → 0.12.0

package/README.md

@@ -84,10 +84,10 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `generate_short` | Render an existing short — re-rolls the footage + music (fresh AI generation). If headline/subheadline/beats are all blank the server auto-writes the copy first (`skip_auto_text:true` for a deliberately bare clip). Safe to re-call (in-flight = reported, no double charge; a failed short can re-generate). | **15** |
 | `rerender_short` | **FREE re-render** — applies the short's current text/style/CTA/end-card/logo state over the already-paid footage + music. Use after `update_short` for copy/style/CTA tweaks, or after a logo change (`set_short_logo`, or `short_logo_position`/`short_logo_treatment`); footage or music changes need `generate_short` instead. Needs one completed generation first (422 `short_not_ready` otherwise); changed footage/music inputs return 422 `short_paid_regeneration_required`. A failed free re-render leaves the delivered video intact — retry `rerender_short`, it stays free. | **0** |
 | `generate_short_text` | AI-draft editable headline / subheadline / caption beats for a short. | 1 assist |
-| `create_editor_ad` | Create an editor project, attach optional local product/logo/closing assets, and return the live autopilot quote. Omit `max_credits` to stop free; provide an approved cap to launch. For a mascot/hero product that must remain identical with no humans, pass `cast_mode:"product_only"` plus `product_image_path`. | **0** until capped launch |
+| `create_editor_ad` | Create an editor project, attach optional local product/logo/closing assets, and return the live autopilot quote. Omit `max_credits` to stop free; provide an approved cap to launch. Write every required person, product, object, and continuity decision directly in the prompt. | **0** until capped launch |
 | `start_autopilot` | Quote autopilot on an **existing** editor draft when called with only `slug`; launch only with an explicit `max_credits` that covers the estimate and an adequate balance. On a completed project, pass `restart:true` to quote and build a fresh creative run; omit it to resume pending edits. | **0** quote; credits on capped launch |
 | `retry_editor_batch` | Recover `batch_retry_required` by atomically re-queueing the failed scene and resuming its prepaid batch. If the parent Autopilot run is terminal, quote/relaunch it separately afterward. | **0 additional** |
-| `cancel_editor_batch` | Cancel an awaiting/running/paused editor batch. Destructive after scene dispatch: prepaid credits are not refunded (an awaiting-preview batch is refunded server-side). | **0 additional** |
+| `cancel_editor_batch` | Cancel an editor batch only while it is `preparing` or `paused_for_retry` (awaiting-previews/running batches are worker-owned and not cancellable). Preparing cancellation releases the uncharged preflight; paused cancellation is destructive — prepaid credits are not refunded. | **0 additional** |
 | `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) |
 | `get_slider` | Read a carousel's status and, when completed, the per-slide image URLs + caption + hashtags. | **0** |
@@ -99,7 +99,7 @@ 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` / `cast_mode` (`product_only` needs `set_product` before generation; `presenter_led` needs a configured presenter). | **0** |
+| `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme`; the prompt is the complete scene-content contract. | **0** |
 | `get_editor` | Full project state by default for compatibility; pass `response_format:"concise"` for a smaller review projection. | **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** |
@@ -108,11 +108,11 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `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 |
+| `set_narration_script` / `generate_narration` | Write your own voiceover script (free) **or** AI-draft one coherent script after every scene has completed with a known positive duration. AI drafting requires at least one scene without retained original audio and consumes an assist only when a fresh job is queued (exact retries dedupe for free). | free / 1 assist |
 | `generate_voice` | Synthesize the voiceover. `voice_id` required (see `list_voices`). | **3** |
 | `generate_music` | Generate background music (each call is a fresh take). | **5** |
 | `render` | Final MP4. Auto-charges any still-ungenerated scenes first (4/scene in a batch of ≥3). | **0** |
-| `list_renders` | List every render version for an editor project (id, version, status, video_url, error) — find a failed render or recover a finished URL. | **0** |
+| `list_renders` | List every render version for an editor project (`id`, `version`, `status`, `video_url`, `thumbnail_url`, `duration_seconds`, `error_message`, `retryable`, `combination_hash`, `is_stale`, `inserted_at`) — find a failed render or recover a finished URL. | **0** |
 | `retry_render` | Re-run a **failed** render from its exact saved snapshot (recovery without re-driving the pipeline). | **0** |
 | `enhance_prompt` / `suggest_next_scene` / `suggest_music_prompt` | AI helpers along the way. | 1 assist each |
 
@@ -130,8 +130,7 @@ images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
 | `upload_video` | Upload a local clip into an editor project (presign → PUT, resumable multipart for large files → confirm → poll to ready) and, by default, add it to the timeline. An uploaded clip keeps its native duration. |
 | `add_segment_from_upload` | Append a **ready** upload to the timeline as a new scene. |
 | `use_asset_for_segment` | Set a specific scene's video from a ready upload **or** a completed scene in the same project (pass exactly one). Returns downstream continuity impact plus narration/voice/music staleness that must be resolved before render. |
-| `set_product` | Upload an editor product image (JPEG/PNG, ≤8 MiB) and attach it as the project product. |
-| `set_product_placement` | Set where the product appears on pending AI scenes: `throughout` or `end`. |
+| `set_product` | Upload an editor product image (JPEG/PNG, ≤8 MiB). Its pixels guide product identity in every generated AI scene and its confirmed description grounds scenario/narration. The exact photo is also linked as the closing image unless a separate closing image was authored. Small generated label text can still vary. |
 | `set_closing_image` | Set the ~2s end-card image (JPEG/PNG, ≤20 MiB; upload a file, or reuse the product image with `from_product:true`). |
 | `set_logo` | Upload a brand logo overlay (JPEG/PNG, ≤5 MiB; editor only; optional treatment/position/duration). |
 | `set_short_product` | Attach a product image (JPEG/PNG, ≤20 MiB) to a **short**. |
@@ -154,6 +153,25 @@ does not match the live timeline; regenerate the reported stale scenes/audio and
 An absent/`null` server `is_stale` is **unknown** (for example a legacy render), not proof that
 the render is current. Failure stages take precedence over active stages and are terminal.
 
+Editor state uses `narration_status` (`none | generating | ready | failed`),
+`current_audio`, and `current_music` (selected version status `pending | processing |
+completed | failed`). Batch state is `idle | preparing | awaiting_previews | running |
+paused_for_retry | paused_insufficient_credits | completed | cancelled | failed`.
+Only `paused_for_retry` is resumed by `retry_editor_batch`; `cancel_editor_batch` works
+only while the batch is `preparing` or `paused_for_retry` — awaiting-previews/running
+batches are worker-owned and cannot be cancelled. Preparing cancellation releases the
+uncharged preflight (nothing was charged yet); paused cancellation is destructive and
+non-refundable. Both tools re-read the editor state and echo `expected_batch_run_id` +
+`expected_batch_status` with the REST command, so a phase change between poll and command
+is a safe 409 `batch_command_stale` (re-poll and retry) instead of acting on newer work;
+the REST endpoints reject editor commands that omit these fields with 409
+`batch_command_required` (client >= 0.12 sends them automatically). For
+`paused_insufficient_credits`, top up or reduce scope and invoke generation/render again.
+
+For raw REST Autopilot calls, reuse one `Idempotency-Key` only for transport retries of the
+same logical launch. Mint a fresh key for a deliberate resume, restart, or changed cap; a
+successful response is replayed for 24 hours under the old key.
+
 ### Campaign engine — onboard a product, plan, and draft (the delegation surface)
 
 Everything here is **$0** (draft creates + planning against the free assist quota). Generation

package/dist/index.js

@@ -29555,6 +29555,7 @@ function normalizeStatus(kind, slug, data) {
   const failedSegments = segments.filter((segment) => segment.status === "failed");
   const batchStatus = d.batch_generation_status ?? null;
   const batchActive = batchStatus === "running" || batchStatus === "preparing" || batchStatus === "awaiting_previews";
+  const autoRenderHandoffActive = batchStatus === "completed" && d.auto_render_after_batch === true;
   const batchRetryRequired = batchStatus === "paused_for_retry";
   const batchInsufficientCredits = batchStatus === "paused_insufficient_credits";
   const batchFailed = batchStatus === "failed";
@@ -29599,7 +29600,7 @@ function normalizeStatus(kind, slug, data) {
     currentMusic.error_message
   ].find((value) => typeof value === "string" && value.trim().length > 0);
   const audioActive = currentAudio.status === "pending" || currentAudio.status === "processing" || currentMusic.status === "pending" || currentMusic.status === "processing" || newerAudioVersions.some(versionActive) || newerMusicVersions.some(versionActive);
-  const childWorkActive = batchActive || renderActive || scenarioActive || narrationActive || audioActive || activeSegments.length > 0;
+  const childWorkActive = batchActive || autoRenderHandoffActive || renderActive || scenarioActive || narrationActive || audioActive || activeSegments.length > 0;
   const autopilotStartedAt = typeof d.autopilot_started_at === "string" ? Date.parse(d.autopilot_started_at) : Number.NaN;
   const now = Date.now();
   const autopilotResumeGraceActive = autopilotActive && Number.isFinite(autopilotStartedAt) && autopilotStartedAt <= now && now - autopilotStartedAt <= 120000;
@@ -29642,6 +29643,8 @@ function normalizeStatus(kind, slug, data) {
     stage = "segment_processing";
   else if (batchActive)
     stage = "segment_generation";
+  else if (autoRenderHandoffActive)
+    stage = "rendering";
   else if (renderActive)
     stage = "rendering";
   else if (scenarioActive)
@@ -29661,7 +29664,7 @@ function normalizeStatus(kind, slug, data) {
     terminal,
     ready,
     video_url: videoUrl,
-    error: ready ? null : batchRetryRequired ? "Batch generation is paused after a failed scene. Call retry_editor_batch or cancel_editor_batch before continuing." : (parentFailureActionable ? d.autopilot_error_message : null) ?? actionableChildError ?? (batchInsufficientCredits ? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then resume." : null),
+    error: ready ? null : batchRetryRequired ? "Batch generation is paused after a failed scene. Call retry_editor_batch or cancel_editor_batch before continuing." : (parentFailureActionable ? d.autopilot_error_message : null) ?? actionableChildError ?? (batchInsufficientCredits ? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then invoke the generation/render path again; retry_editor_batch only applies to paused_for_retry." : null),
     stale,
     active_segment_ids: activeSegments.map((segment) => segment.id).filter((id) => typeof id === "number" || typeof id === "string"),
     stale_segment_ids: staleSegments.map((segment) => segment.id).filter((id) => typeof id === "number" || typeof id === "string")
@@ -29694,10 +29697,10 @@ function makeVideoAutopilotKey(slug, a, startState) {
   return idemKey("autopilot", slug, a.prompt, a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.aspect ?? "", a.voice_id ?? "", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", startState);
 }
 function editorAdCreateKey(a) {
-  return idemKey("create-editor", a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_image_identity ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.closing_image_identity ?? "", a.logo_path ?? "", a.logo_identity ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds), a.cast_mode ?? "");
+  return idemKey("create-editor", a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_image_identity ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.closing_image_identity ?? "", a.logo_path ?? "", a.logo_identity ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds));
 }
 function editorAdAutopilotKey(slug, a) {
-  return idemKey("autopilot", slug, a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.logo_path ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds), a.cast_mode ?? "", a.max_credits === undefined ? "" : String(a.max_credits));
+  return idemKey("autopilot", slug, a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.logo_path ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds), a.max_credits === undefined ? "" : String(a.max_credits));
 }
 function sliderCreateKey(a) {
   return idemKey("create-slider", a.prompt, a.mode ?? "", a.template ?? "", a.slide_count === undefined ? "" : String(a.slide_count), a.aspect_ratio ?? "", a.accent_color ?? "", a.text_position ?? "");
@@ -30254,7 +30257,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.11.0",
+  version: "0.12.0",
   description: "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   license: "MIT",
   author: "Monocursive <contact@monocursive.com>",
@@ -31566,9 +31569,9 @@ async function editorAutopilotQuote(client, slug, overrides = {}) {
     const params = new URLSearchParams;
     if (overrides.language)
       params.set("language", overrides.language);
-    if (overrides.product_subject)
+    if (overrides.product_subject !== undefined)
       params.set("product_subject", overrides.product_subject);
-    if (overrides.product_prompt)
+    if (overrides.product_prompt !== undefined)
       params.set("product_prompt", overrides.product_prompt);
     if (overrides.restart)
       params.set("restart", "true");
@@ -32756,7 +32759,7 @@ registerTool("edit_slider_slide", {
 }));
 registerTool("create_editor_ad", {
   title: "Create, configure, and price a multi-scene editor ad",
-  description: "Creates an editor project, attaches any supplied local product/logo/closing assets BEFORE generation, " + "and prices autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Without max_credits it STOPS after the free draft/configuration and returns the live estimate. It starts " + "the paid pipeline only when max_credits is supplied and covers the estimate. Then poll with get_status / " + "wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " + "Supplying assets here is safer than adding them after autopilot because the scenario and scenes are grounded " + "in the real product from the start. (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 a mascot or hero product that must stay visually identical with no human presenter, set " + "cast_mode:'product_only' together with product_image_path. Presenter-led casting still belongs on " + "create_editor_draft because it requires a separately configured presenter.",
+  description: "Creates an editor project, attaches any supplied local product/logo/closing assets BEFORE generation, " + "and prices autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Without max_credits it STOPS after the free draft/configuration and returns the live estimate. It starts " + "the paid pipeline only when max_credits is supplied and covers the estimate. Then poll with get_status / " + "wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " + "A product image is analyzed into semantic project context and sent as a product-identity reference to every " + "generated Editor scene. The exact photo is also linked as the closing image unless a separate closing image " + "was authored; generated fine label text can still vary. Scene prompts are the complete content contract: describe any people, " + "products, visual continuity, absences, and composition directly in the brief. (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.)",
   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."),
@@ -32767,14 +32770,13 @@ registerTool("create_editor_ad", {
     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.'),
     voice_id: exports_external.string().optional().describe("Preferred narration voice id (see list_voices); omit for the default voice"),
     export_aspect_ratio: exports_external.enum(["9:16", "16:9", "1:1"]).optional().describe('Aspect ratio (default "9:16")'),
-    product_image_path: exports_external.string().optional().describe("Local product image (.jpg/.jpeg/.png, ≤8 MiB) to attach before autopilot."),
-    product_description: exports_external.string().max(500).optional().describe("Exact product/character description used with product_image_path."),
+    product_image_path: exports_external.string().optional().describe("Local product image (.jpg/.jpeg/.png, ≤8 MiB) used as the product-identity reference for every generated Editor scene and linked as the exact closing image unless one was already authored."),
+    product_description: exports_external.string().max(500).optional().describe("Product description used to ground the scenario and narration when product_image_path is supplied."),
     closing_image_path: exports_external.string().optional().describe("Local closing-card image (.jpg/.jpeg/.png, ≤20 MiB)."),
     logo_path: exports_external.string().optional().describe("Local logo (.jpg/.jpeg/.png, ≤5 MiB) to overlay."),
     logo_treatment: exports_external.enum(["intro", "outro", "both", "none"]).optional().describe('When the logo bumper plays: "intro", "outro", "both" (default), or "none". Requires logo_path.'),
     logo_position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe('Logo corner: "top-left", "top-right" (default), "bottom-left", or "bottom-right". Requires logo_path.'),
     logo_duration_seconds: exports_external.number().min(0.5).max(3).optional().describe("Logo bumper duration in seconds, 0.5–3 (default 1.5). Requires logo_path."),
-    cast_mode: exports_external.literal("product_only").optional().describe("Lock every AI scene to the supplied product/mascot reference with no people. Requires product_image_path."),
     max_credits: exports_external.number().int().nonnegative().optional().describe("Explicit spend cap. Omit to create/configure/price only; no credits are charged.")
   },
   outputSchema: createEditorOutput,
@@ -32791,9 +32793,6 @@ registerTool("create_editor_ad", {
     const promptErr = validateProductPrompt(args.product_prompt);
     if (promptErr)
       return fail(promptErr);
-    if (args.cast_mode === "product_only" && !args.product_image_path) {
-      return fail("cast_mode product_only requires product_image_path so identity can be locked before generation.");
-    }
     if ((args.logo_treatment !== undefined || args.logo_position !== undefined || args.logo_duration_seconds !== undefined) && !args.logo_path) {
       return fail("logo_treatment/logo_position/logo_duration_seconds require logo_path (the logo image they style). Provide logo_path or drop these settings.");
     }
@@ -32821,8 +32820,7 @@ registerTool("create_editor_ad", {
       visual_language: args.visual_language,
       theme: args.theme,
       voice_id: args.voice_id,
-      export_aspect_ratio: args.export_aspect_ratio,
-      cast_mode: args.cast_mode
+      export_aspect_ratio: args.export_aspect_ratio
     }, editorAdCreateKey({
       ...args,
       product_image_identity: productImage ? preparedUploadIdentity(productImage) : undefined,
@@ -32897,8 +32895,8 @@ registerTool("start_autopilot", {
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     language: exports_external.enum(LANGUAGES).optional().describe('Optional language override applied before launch. Bare ISO-639-1 code only, e.g. "fr" — no ' + "region/script subtag. Drives scenario, narration, voice, and captions."),
-    product_subject: exports_external.string().max(300).optional().describe("Optional locked product / main subject applied before launch so the AI cannot invent an " + "unrelated product."),
-    product_prompt: exports_external.string().optional().describe("Optional freeform brief to set/replace before launch."),
+    product_subject: exports_external.string().max(300).optional().describe("Optional locked product / main subject applied before launch so the AI cannot invent an " + "unrelated product. Omit to keep the stored subject; send blank to clear it."),
+    product_prompt: exports_external.string().optional().describe("Optional freeform brief to set/replace before launch. Omit to keep the stored brief; send blank to clear it."),
     max_credits: exports_external.number().int().nonnegative().optional().describe("Explicit spend cap. Omit to quote only; no credits are charged."),
     restart: exports_external.boolean().optional().describe("Set true only on a completed project to quote/build a fresh creative run. The delivered timeline stays available until replacement apply.")
   },
@@ -32956,7 +32954,10 @@ registerTool("retry_editor_batch", {
     idempotentHint: false
   }
 }, tool(async (args, client) => {
-  const res = await client.post(`/video-factories/${args.slug}/retry-batch-segment`);
+  const command = await observedEditorBatchCommand(client, args.slug, [
+    "paused_for_retry"
+  ]);
+  const res = await client.post(`/video-factories/${args.slug}/retry-batch-segment`, command);
   return ok({
     ...asRecord(asRecord(res).data ?? res),
     slug: args.slug,
@@ -32967,7 +32968,7 @@ registerTool("retry_editor_batch", {
 }));
 registerTool("cancel_editor_batch", {
   title: "Cancel an editor batch",
-  description: "Cancels an editor batch in awaiting_previews, running, or paused_for_retry so the project can be edited or " + "Autopilot can be started again. Cancellation is destructive: dispatched scene work is stopped and its prepaid " + "credits are not refunded; only an awaiting_previews batch (before dispatch) is refunded by the server. Spends " + "0 additional credits. Scope: video:generate.",
+  description: "Cancels an editor batch only while it is preparing or paused_for_retry so the project can be edited or " + "Autopilot can be started again. Preparing cancellation releases the uncharged preflight. Cancelling a paused " + "batch is destructive: dispatched scene work is stopped and its prepaid credits are not refunded. Spends " + "0 additional credits. Scope: video:generate.",
   inputSchema: { slug: exports_external.string().describe("Editor project slug") },
   annotations: {
     title: "Cancel editor batch",
@@ -32977,7 +32978,11 @@ registerTool("cancel_editor_batch", {
     idempotentHint: false
   }
 }, tool(async (args, client) => {
-  const res = await client.post(`/video-factories/${args.slug}/cancel-batch`);
+  const command = await observedEditorBatchCommand(client, args.slug, [
+    "preparing",
+    "paused_for_retry"
+  ]);
+  const res = await client.post(`/video-factories/${args.slug}/cancel-batch`, command);
   return ok({
     ...asRecord(asRecord(res).data ?? res),
     slug: args.slug,
@@ -32985,6 +32990,22 @@ registerTool("cancel_editor_batch", {
     next: "get_status"
   });
 }));
+async function observedEditorBatchCommand(client, slug, allowedStatuses) {
+  const response = await client.get(`/editor/${slug}`);
+  const state = asRecord(asRecord(response).data);
+  const status = state.batch_generation_status;
+  if (typeof status !== "string" || !allowedStatuses.includes(status)) {
+    throw new Error(`Editor batch is not in an allowed phase (${allowedStatuses.join(" or ")}); refresh status before retrying.`);
+  }
+  const runId = state.batch_generation_run_id;
+  if (runId !== null && (typeof runId !== "string" || runId.trim().length === 0)) {
+    throw new Error("Editor state did not include a valid batch_generation_run_id; refresh status before retrying.");
+  }
+  return {
+    expected_batch_run_id: runId,
+    expected_batch_status: status
+  };
+}
 registerTool("get_ai_assists", {
   title: "Get AI assist quota",
   description: "Returns the free daily AI-assist quota {used, limit, bonus, remaining, resets_at, unlock_cost, " + "unlock_batch_size}. AI assists power helper calls (generate_scenario, generate_narration, " + "enhance_prompt, suggest_next_scene, suggest_music_prompt). Default limit is 20/day. When remaining " + "hits 0 those helpers return 429 — either unlock_ai_assists (1 credit → +10) or write the content " + "yourself with set_scenario / set_narration_script / set_segment_prompt (those are free, no quota).",
@@ -33011,7 +33032,6 @@ 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).")
@@ -33030,14 +33050,13 @@ 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 ?? "", args.cast_mode ?? ""));
+  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 ?? ""));
   return ok({
     slug: created.data.slug,
     kind: "editor",
@@ -33060,6 +33079,8 @@ function conciseEditorState(value) {
     "scenario_apply_status",
     "scenario_prompt",
     "batch_generation_status",
+    "batch_generation_run_id",
+    "auto_render_after_batch",
     "narration_status",
     "narration_script",
     "narration_stale",
@@ -33084,8 +33105,6 @@ function conciseEditorState(value) {
     status: segment.status,
     source_type: segment.source_type,
     use_previous_frame: segment.use_previous_frame,
-    protagonist_presence: segment.protagonist_presence,
-    cast_mode_snapshot: segment.cast_mode_snapshot,
     video_stale: segment.video_stale,
     error_code: segment.error_code,
     error_message: segment.error_message,
@@ -33095,7 +33114,7 @@ function conciseEditorState(value) {
 }
 registerTool("get_editor", {
   title: "Get editor state (review step)",
-  description: "Returns the full editor state by default for backward compatibility. Pass response_format:'concise' for a smaller review projection containing orchestration, scenario, scene prompts/status, narration, audio, render, spend, and quota.",
+  description: "Returns the full editor state by default for backward compatibility. Pass response_format:'concise' for a smaller review projection containing orchestration, scenario, scene prompts/status, narration_status, current_audio, current_music, latest_render, batch_generation_status, spend, and quota.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     response_format: exports_external.enum(["concise", "full"]).default("full")
@@ -33124,8 +33143,8 @@ registerTool("generate_scenario", {
   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)"),
-    creative_format: exports_external.enum(CREATIVE_FORMATS).optional().describe("Persist the narrative arc / segment structure before generating. Omit to leave it unchanged; pass an empty string to clear."),
-    visual_language: exports_external.enum(VISUAL_LANGUAGES).optional().describe("Persist the visual style / render look before generating. When set it drives the look and a theme of 'none' is ignored."),
+    creative_format: exports_external.union([exports_external.enum(CREATIVE_FORMATS), exports_external.literal("")]).optional().describe("Persist the narrative arc / segment structure before generating. Omit to leave it unchanged; pass an empty string to clear."),
+    visual_language: exports_external.union([exports_external.enum(VISUAL_LANGUAGES), exports_external.literal("")]).optional().describe("Persist the visual style / render look before generating. Omit to leave it unchanged; pass an empty string to clear. When set it drives the look and a theme of 'none' is ignored."),
     theme: exports_external.string().optional().describe("Persist the genre overlay / theme before generating (e.g. realistic, cinematic, anime, none)."),
     auto_unlock: exports_external.boolean().optional().describe("On 429, spend 1 credit to unlock +10 assists and retry once (default false)")
   },
@@ -33429,10 +33448,10 @@ registerTool("generate_all_segments", {
 }));
 registerTool("set_narration_script", {
   title: "Set the narration script",
-  description: "Writes your own narration script (1–12000 chars) instead of generating one. Free — no credits, no AI " + "assist. Use this in place of generate_narration when you want to control the voiceover text. Changing the narration after generating voice/music marks them stale — regenerate (generate_voice / generate_music) before render.",
+  description: "Writes your own narration script (1–10000 chars) instead of generating one. Free — no credits, no AI " + "assist. Use this in place of generate_narration when you want to control the voiceover text. Changing the narration after generating voice/music marks them stale — regenerate (generate_voice / generate_music) before render.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
-    script: exports_external.string().min(1).max(12000).describe("Narration / voiceover text (1–12000 chars)")
+    script: exports_external.string().min(1).max(1e4).describe("Narration / voiceover text (1–10000 chars)")
   },
   annotations: { title: "Set narration", ...WRITE, idempotentHint: true }
 }, tool(async (args, client) => {
@@ -33443,7 +33462,7 @@ registerTool("set_narration_script", {
 }));
 registerTool("generate_narration", {
   title: "Generate the narration (AI assist)",
-  description: "Generates the narration script with AI from the timeline. CONSUMES 1 AI ASSIST (free daily quota) — " + "it is free of CREDITS but NOT free of quota. On 429 set auto_unlock:true (1 credit → +10 assists, " + "retried once) or write the script yourself with set_narration_script.",
+  description: "Generates one coherent narration script with AI from the complete timeline. Every current scene must be completed with a known positive duration, and at least one scene must not keep original upload audio. CONSUMES 1 AI ASSIST (free daily quota) only when a fresh job is queued; an exact retry is deduplicated without consuming another assist — " + "it is free of CREDITS but NOT free of quota. On 429 set auto_unlock:true (1 credit → +10 assists, " + "retried once) or write the script yourself with set_narration_script.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     auto_unlock: exports_external.boolean().optional().describe("On 429, spend 1 credit to unlock +10 assists and retry once (default false)")
@@ -33459,7 +33478,7 @@ registerTool("generate_narration", {
 }));
 registerTool("generate_voice", {
   title: "Generate the voiceover (3 credits)",
-  description: "Synthesizes the voiceover from the narration script. Costs 3 credits. Safe to retry; re-call after changing the narration or voice to regenerate." + "voice_id is REQUIRED — pick one from list_voices (≤64 chars, [A-Za-z0-9_-] only). 402 fails cleanly. Editing the scenario/narration/timeline after this marks the voice stale, and render will 422 (editor_voice_stale) until you re-run generate_voice.",
+  description: "Synthesizes the voiceover from the narration script. Costs 3 credits. Safe to retry; re-call after changing the narration or voice to regenerate." + " All current scenes must be completed with known durations first. voice_id is REQUIRED — pick one from list_voices (≤64 chars, [A-Za-z0-9_-] only). 402 fails cleanly. Editing the scenario/narration/timeline after this marks the voice stale, and render will 422 (editor_voice_stale) until you re-run generate_voice.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     voice_id: exports_external.string().regex(/^[A-Za-z0-9_-]+$/).max(64).describe("Narration voice id from list_voices (required)")
@@ -33571,7 +33590,7 @@ registerTool("suggest_music_prompt", {
 }));
 registerTool("list_renders", {
   title: "List renders for an editor project",
-  description: "Lists every render version for an editor project: {id, version, status, video_url, duration_seconds, " + "error_message, inserted_at}. Use it to find a FAILED render to retry, or to recover a finished video_url " + "(presigned, ~24h). Read-only.",
+  description: "Lists every render version for an editor project: {id, version, status, video_url, thumbnail_url, " + "duration_seconds, error_message, retryable, combination_hash, is_stale, inserted_at}. Use it to find a " + "FAILED render to retry, or to recover a finished video_url (presigned, ~24h). status is pending | " + "processing | completed | failed; is_stale null means unknown, not current. Read-only.",
   inputSchema: { slug: exports_external.string().describe("Editor project slug") },
   annotations: { title: "List renders", ...RO }
 }, tool(async (args, client) => {
@@ -33744,7 +33763,7 @@ registerTool("use_asset_for_segment", {
 }));
 registerTool("set_product", {
   title: "Attach a product image (from a local file)",
-  description: "Uploads a local product image and attaches it to the project as the product. Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. The FIRST product added " + "defaults every pending AI scene to feature it 'throughout' (change with set_product_placement). Optional " + "description (≤500 chars) guides how it's woven into scenes.",
+  description: "Uploads a local product image and attaches it to the project as the product. Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Its pixels guide product identity " + "in every generated Editor scene and its confirmed description grounds scenario and narration. The exact photo " + "is linked as the closing image unless a separate closing image was authored; generated fine label text can still vary.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     file_path: exports_external.string().describe("Local product image path (.jpg/.jpeg/.png)"),
@@ -33756,22 +33775,6 @@ registerTool("set_product", {
   const res = await client.post(`/editor/${args.slug}/product/confirm`, { s3_key, product_description: args.description });
   return ok(asRecord(res).data ?? res);
 }));
-registerTool("set_product_placement", {
-  title: "Set default product placement on pending scenes (0 credits)",
-  description: "Sets where the product appears across pending (never-generated) AI scenes. mode is 'throughout' (every scene) " + "or 'end' (closing scene only; requires a first+last-frame capable model). 0 credits. Add a product first with " + "set_product. (There is no 'none' — to remove the product, that's a separate action.)",
-  inputSchema: {
-    slug: exports_external.string().describe("Editor project slug"),
-    mode: exports_external.enum(["throughout", "end"]).describe("'throughout' or 'end'")
-  },
-  annotations: {
-    title: "Set product placement",
-    ...WRITE,
-    idempotentHint: true
-  }
-}, tool(async (args, client) => {
-  const res = await client.post(`/editor/${args.slug}/product/apply-default-placement`, { placement: args.mode });
-  return ok(asRecord(res).data ?? res);
-}));
 registerTool("set_closing_image", {
   title: "Set the closing-card image (0 credits)",
   description: "Sets the optional ~2s end-card image. Either upload a local file (file_path; .jpg/.jpeg/.png ≤20 MiB, confined " + "to HUBFLUENCER_INPUT_DIR/cwd) OR reuse the project's product image (from_product:true — a 0-credit server-side " + "copy, no upload). If a closing image already exists, pass overwrite:true to replace it (else " + "editor_closing_image_exists).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubfluencer/mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "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/core.ts

@@ -464,6 +464,13 @@ export function normalizeStatus(
 		batchStatus === "running" ||
 		batchStatus === "preparing" ||
 		batchStatus === "awaiting_previews";
+	// The scene batch commits `completed` before the durable auto-render handoff
+	// creates its VideoResult row. While the persisted intent remains armed, the
+	// server still owns the project and a reconciler may create the render at any
+	// moment. Treat that narrow gap as active work so wait_for_completion cannot
+	// return an idle/terminal result just before the render appears.
+	const autoRenderHandoffActive =
+		batchStatus === "completed" && d.auto_render_after_batch === true;
 	const batchRetryRequired = batchStatus === "paused_for_retry";
 	// A parked batch that ran out of credits: it cannot progress without the user
 	// topping up or reducing scope, so it is a needs-user-action TERMINAL state
@@ -567,6 +574,7 @@ export function normalizeStatus(
 		newerMusicVersions.some(versionActive);
 	const childWorkActive =
 		batchActive ||
+		autoRenderHandoffActive ||
 		renderActive ||
 		scenarioActive ||
 		narrationActive ||
@@ -670,6 +678,7 @@ export function normalizeStatus(
 	else if (batchInsufficientCredits) stage = "insufficient_credits";
 	else if (activeSegments.length > 0) stage = "segment_processing";
 	else if (batchActive) stage = "segment_generation";
+	else if (autoRenderHandoffActive) stage = "rendering";
 	else if (renderActive) stage = "rendering";
 	else if (scenarioActive) stage = "scenario_processing";
 	else if (narrationActive) stage = "narration_processing";
@@ -705,7 +714,7 @@ export function normalizeStatus(
 						: null) ??
 					actionableChildError ??
 					(batchInsufficientCredits
-						? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then resume."
+						? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then invoke the generation/render path again; retry_editor_batch only applies to paused_for_retry."
 						: null)),
 		stale,
 		active_segment_ids: activeSegments
@@ -856,7 +865,6 @@ export interface EditorAdKeyArgs {
 	logo_treatment?: string;
 	logo_position?: string;
 	logo_duration_seconds?: number;
-	cast_mode?: string;
 	/** Identities of the retained, pre-create asset byte snapshots. */
 	product_image_identity?: string;
 	closing_image_identity?: string;
@@ -896,7 +904,6 @@ export function editorAdCreateKey(a: EditorAdKeyArgs): string {
 		a.logo_duration_seconds === undefined
 			? ""
 			: String(a.logo_duration_seconds),
-		a.cast_mode ?? "",
 	);
 }
 
@@ -931,7 +938,6 @@ export function editorAdAutopilotKey(slug: string, a: EditorAdKeyArgs): string {
 		a.logo_duration_seconds === undefined
 			? ""
 			: String(a.logo_duration_seconds),
-		a.cast_mode ?? "",
 		a.max_credits === undefined ? "" : String(a.max_credits),
 	);
 }
@@ -1076,10 +1082,9 @@ export function validateLanguage(language: string | undefined): string | null {
 export function validateProductPrompt(
 	prompt: string | undefined,
 ): string | null {
-	// A trimmed-empty string is a no-op on every path the server exposes:
-	// pre-launch override handling drops blank values (leave the stored value
-	// untouched) and the editor prompt is valid when blank, so treat "" the same
-	// as undefined. Still reject 1–9 non-blank chars (too short to be a brief).
+	// Empty is valid but its meaning is endpoint-specific: draft creation omits
+	// it, while Autopilot treats an explicitly present blank as an atomic clear.
+	// Still reject 1–9 non-blank chars (too short to be a brief).
 	if (prompt === undefined) return null;
 	const len = prompt.trim().length;
 	if (len === 0) return null;

package/src/index.ts

@@ -171,9 +171,9 @@ async function editorAutopilotQuote(
 	try {
 		const params = new URLSearchParams();
 		if (overrides.language) params.set("language", overrides.language);
-		if (overrides.product_subject)
+		if (overrides.product_subject !== undefined)
 			params.set("product_subject", overrides.product_subject);
-		if (overrides.product_prompt)
+		if (overrides.product_prompt !== undefined)
 			params.set("product_prompt", overrides.product_prompt);
 		if (overrides.restart) params.set("restart", "true");
 		const query = params.toString();
@@ -3020,12 +3020,12 @@ registerTool(
 			"Without max_credits it STOPS after the free draft/configuration and returns the live estimate. It starts " +
 			"the paid pipeline only when max_credits is supplied and covers the estimate. Then poll with get_status / " +
 			"wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " +
-			"Supplying assets here is safer than adding them after autopilot because the scenario and scenes are grounded " +
-			"in the real product from the start. (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 a mascot or hero product that must stay visually identical with no human presenter, set " +
-			"cast_mode:'product_only' together with product_image_path. Presenter-led casting still belongs on " +
-			"create_editor_draft because it requires a separately configured presenter.",
+			"A product image is analyzed into semantic project context and sent as a product-identity reference to every " +
+			"generated Editor scene. The exact photo is also linked as the closing image unless a separate closing image " +
+			"was authored; generated fine label text can still vary. Scene prompts are the complete content contract: describe any people, " +
+			"products, visual continuity, absences, and composition directly in the brief. (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.)",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -3085,14 +3085,14 @@ registerTool(
 				.string()
 				.optional()
 				.describe(
-					"Local product image (.jpg/.jpeg/.png, ≤8 MiB) to attach before autopilot.",
+					"Local product image (.jpg/.jpeg/.png, ≤8 MiB) used as the product-identity reference for every generated Editor scene and linked as the exact closing image unless one was already authored.",
 				),
 			product_description: z
 				.string()
 				.max(500)
 				.optional()
 				.describe(
-					"Exact product/character description used with product_image_path.",
+					"Product description used to ground the scenario and narration when product_image_path is supplied.",
 				),
 			closing_image_path: z
 				.string()
@@ -3122,12 +3122,6 @@ registerTool(
 				.describe(
 					"Logo bumper duration in seconds, 0.5–3 (default 1.5). Requires logo_path.",
 				),
-			cast_mode: z
-				.literal("product_only")
-				.optional()
-				.describe(
-					"Lock every AI scene to the supplied product/mascot reference with no people. Requires product_image_path.",
-				),
 			max_credits: z
 				.number()
 				.int()
@@ -3163,7 +3157,6 @@ registerTool(
 					| "bottom-left"
 					| "bottom-right";
 				logo_duration_seconds?: number;
-				cast_mode?: "product_only";
 				max_credits?: number;
 			},
 			client,
@@ -3177,11 +3170,6 @@ registerTool(
 				if (langErr) return fail(langErr);
 				const promptErr = validateProductPrompt(args.product_prompt);
 				if (promptErr) return fail(promptErr);
-				if (args.cast_mode === "product_only" && !args.product_image_path) {
-					return fail(
-						"cast_mode product_only requires product_image_path so identity can be locked before generation.",
-					);
-				}
 				// Fail fast on settings that would otherwise be silently dropped: the
 				// logo PATCH is gated on logo_path and the product_description is only
 				// sent with product_image_path, so a logo_* / product_description passed
@@ -3241,7 +3229,6 @@ registerTool(
 						theme: args.theme,
 						voice_id: args.voice_id,
 						export_aspect_ratio: args.export_aspect_ratio,
-						cast_mode: args.cast_mode,
 					},
 					// Fold every create-affecting param into the key so two calls that
 					// differ only by style/theme/voice/aspect get distinct drafts.
@@ -3401,12 +3388,14 @@ registerTool(
 				.optional()
 				.describe(
 					"Optional locked product / main subject applied before launch so the AI cannot invent an " +
-						"unrelated product.",
+						"unrelated product. Omit to keep the stored subject; send blank to clear it.",
 				),
 			product_prompt: z
 				.string()
 				.optional()
-				.describe("Optional freeform brief to set/replace before launch."),
+				.describe(
+					"Optional freeform brief to set/replace before launch. Omit to keep the stored brief; send blank to clear it.",
+				),
 			max_credits: z
 				.number()
 				.int()
@@ -3530,8 +3519,12 @@ registerTool(
 		},
 	},
 	tool(async (args: { slug: string }, client) => {
+		const command = await observedEditorBatchCommand(client, args.slug, [
+			"paused_for_retry",
+		]);
 		const res = await client.post<{ data: unknown }>(
 			`/video-factories/${args.slug}/retry-batch-segment`,
+			command,
 		);
 		return ok({
 			...asRecord(asRecord(res).data ?? res),
@@ -3548,9 +3541,9 @@ registerTool(
 	{
 		title: "Cancel an editor batch",
 		description:
-			"Cancels an editor batch in awaiting_previews, running, or paused_for_retry so the project can be edited or " +
-			"Autopilot can be started again. Cancellation is destructive: dispatched scene work is stopped and its prepaid " +
-			"credits are not refunded; only an awaiting_previews batch (before dispatch) is refunded by the server. Spends " +
+			"Cancels an editor batch only while it is preparing or paused_for_retry so the project can be edited or " +
+			"Autopilot can be started again. Preparing cancellation releases the uncharged preflight. Cancelling a paused " +
+			"batch is destructive: dispatched scene work is stopped and its prepaid credits are not refunded. Spends " +
 			"0 additional credits. Scope: video:generate.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
 		annotations: {
@@ -3562,8 +3555,13 @@ registerTool(
 		},
 	},
 	tool(async (args: { slug: string }, client) => {
+		const command = await observedEditorBatchCommand(client, args.slug, [
+			"preparing",
+			"paused_for_retry",
+		]);
 		const res = await client.post<{ data: unknown }>(
 			`/video-factories/${args.slug}/cancel-batch`,
+			command,
 		);
 		return ok({
 			...asRecord(asRecord(res).data ?? res),
@@ -3574,6 +3572,50 @@ registerTool(
 	}),
 );
 
+type EditorBatchCommandStatus = "preparing" | "paused_for_retry";
+
+/**
+ * Reads the exact Editor batch ownership token immediately before issuing a
+ * recovery command. The API validates both fields under the factory row lock,
+ * so a replacement run or phase transition between this GET and the POST is a
+ * safe `batch_command_stale` conflict rather than acting on newer work.
+ */
+async function observedEditorBatchCommand(
+	client: HubfluencerClient,
+	slug: string,
+	allowedStatuses: readonly EditorBatchCommandStatus[],
+): Promise<{
+	expected_batch_run_id: string | null;
+	expected_batch_status: EditorBatchCommandStatus;
+}> {
+	const response = await client.get<{ data: unknown }>(`/editor/${slug}`);
+	const state = asRecord(asRecord(response).data);
+	const status = state.batch_generation_status;
+	if (
+		typeof status !== "string" ||
+		!allowedStatuses.includes(status as EditorBatchCommandStatus)
+	) {
+		throw new Error(
+			`Editor batch is not in an allowed phase (${allowedStatuses.join(" or ")}); refresh status before retrying.`,
+		);
+	}
+
+	const runId = state.batch_generation_run_id;
+	if (
+		runId !== null &&
+		(typeof runId !== "string" || runId.trim().length === 0)
+	) {
+		throw new Error(
+			"Editor state did not include a valid batch_generation_run_id; refresh status before retrying.",
+		);
+	}
+
+	return {
+		expected_batch_run_id: runId,
+		expected_batch_status: status as EditorBatchCommandStatus,
+	};
+}
+
 // ── AI assists (free daily quota) ───────────────────────────────────────────
 
 registerTool(
@@ -3676,17 +3718,6 @@ 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_-]+$/)
@@ -3723,7 +3754,6 @@ registerTool(
 				creative_format?: string;
 				visual_language?: string;
 				theme?: string;
-				cast_mode?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
 				project_intent?: string;
@@ -3737,7 +3767,6 @@ 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,
@@ -3760,7 +3789,6 @@ registerTool(
 					args.theme ?? "",
 					args.voice_id ?? "",
 					args.export_aspect_ratio ?? "",
-					args.cast_mode ?? "",
 				),
 			);
 			return ok({
@@ -3788,6 +3816,8 @@ function conciseEditorState(value: unknown): Record<string, unknown> {
 		"scenario_apply_status",
 		"scenario_prompt",
 		"batch_generation_status",
+		"batch_generation_run_id",
+		"auto_render_after_batch",
 		"narration_status",
 		"narration_script",
 		"narration_stale",
@@ -3812,8 +3842,6 @@ function conciseEditorState(value: unknown): Record<string, unknown> {
 				status: segment.status,
 				source_type: segment.source_type,
 				use_previous_frame: segment.use_previous_frame,
-				protagonist_presence: segment.protagonist_presence,
-				cast_mode_snapshot: segment.cast_mode_snapshot,
 				video_stale: segment.video_stale,
 				error_code: segment.error_code,
 				error_message: segment.error_message,
@@ -3828,7 +3856,7 @@ registerTool(
 	{
 		title: "Get editor state (review step)",
 		description:
-			"Returns the full editor state by default for backward compatibility. Pass response_format:'concise' for a smaller review projection containing orchestration, scenario, scene prompts/status, narration, audio, render, spend, and quota.",
+			"Returns the full editor state by default for backward compatibility. Pass response_format:'concise' for a smaller review projection containing orchestration, scenario, scene prompts/status, narration_status, current_audio, current_music, latest_render, batch_generation_status, spend, and quota.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			response_format: z.enum(["concise", "full"]).default("full"),
@@ -3898,16 +3926,16 @@ registerTool(
 				.optional()
 				.describe("How many scenes (3–10, server default 5)"),
 			creative_format: z
-				.enum(CREATIVE_FORMATS)
+				.union([z.enum(CREATIVE_FORMATS), z.literal("")])
 				.optional()
 				.describe(
 					"Persist the narrative arc / segment structure before generating. Omit to leave it unchanged; pass an empty string to clear.",
 				),
 			visual_language: z
-				.enum(VISUAL_LANGUAGES)
+				.union([z.enum(VISUAL_LANGUAGES), z.literal("")])
 				.optional()
 				.describe(
-					"Persist the visual style / render look before generating. When set it drives the look and a theme of 'none' is ignored.",
+					"Persist the visual style / render look before generating. Omit to leave it unchanged; pass an empty string to clear. When set it drives the look and a theme of 'none' is ignored.",
 				),
 			theme: z
 				.string()
@@ -4479,15 +4507,15 @@ registerTool(
 	{
 		title: "Set the narration script",
 		description:
-			"Writes your own narration script (1–12000 chars) instead of generating one. Free — no credits, no AI " +
+			"Writes your own narration script (1–10000 chars) instead of generating one. Free — no credits, no AI " +
 			"assist. Use this in place of generate_narration when you want to control the voiceover text. Changing the narration after generating voice/music marks them stale — regenerate (generate_voice / generate_music) before render.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			script: z
 				.string()
 				.min(1)
-				.max(12000)
-				.describe("Narration / voiceover text (1–12000 chars)"),
+				.max(10000)
+				.describe("Narration / voiceover text (1–10000 chars)"),
 		},
 		annotations: { title: "Set narration", ...WRITE, idempotentHint: true },
 	},
@@ -4504,7 +4532,7 @@ registerTool(
 	{
 		title: "Generate the narration (AI assist)",
 		description:
-			"Generates the narration script with AI from the timeline. CONSUMES 1 AI ASSIST (free daily quota) — " +
+			"Generates one coherent narration script with AI from the complete timeline. Every current scene must be completed with a known positive duration, and at least one scene must not keep original upload audio. CONSUMES 1 AI ASSIST (free daily quota) only when a fresh job is queued; an exact retry is deduplicated without consuming another assist — " +
 			"it is free of CREDITS but NOT free of quota. On 429 set auto_unlock:true (1 credit → +10 assists, " +
 			"retried once) or write the script yourself with set_narration_script.",
 		inputSchema: {
@@ -4536,7 +4564,7 @@ registerTool(
 		title: "Generate the voiceover (3 credits)",
 		description:
 			"Synthesizes the voiceover from the narration script. Costs 3 credits. Safe to retry; re-call after changing the narration or voice to regenerate." +
-			"voice_id is REQUIRED — pick one from list_voices (≤64 chars, [A-Za-z0-9_-] only). 402 fails cleanly. Editing the scenario/narration/timeline after this marks the voice stale, and render will 422 (editor_voice_stale) until you re-run generate_voice.",
+			" All current scenes must be completed with known durations first. voice_id is REQUIRED — pick one from list_voices (≤64 chars, [A-Za-z0-9_-] only). 402 fails cleanly. Editing the scenario/narration/timeline after this marks the voice stale, and render will 422 (editor_voice_stale) until you re-run generate_voice.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			voice_id: z
@@ -4775,9 +4803,10 @@ registerTool(
 	{
 		title: "List renders for an editor project",
 		description:
-			"Lists every render version for an editor project: {id, version, status, video_url, duration_seconds, " +
-			"error_message, inserted_at}. Use it to find a FAILED render to retry, or to recover a finished video_url " +
-			"(presigned, ~24h). Read-only.",
+			"Lists every render version for an editor project: {id, version, status, video_url, thumbnail_url, " +
+			"duration_seconds, error_message, retryable, combination_hash, is_stale, inserted_at}. Use it to find a " +
+			"FAILED render to retry, or to recover a finished video_url (presigned, ~24h). status is pending | " +
+			"processing | completed | failed; is_stale null means unknown, not current. Read-only.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
 		annotations: { title: "List renders", ...RO },
 	},
@@ -5129,9 +5158,9 @@ registerTool(
 		description:
 			"Uploads a local product image and attaches it to the project as the product. Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. The FIRST product added " +
-			"defaults every pending AI scene to feature it 'throughout' (change with set_product_placement). Optional " +
-			"description (≤500 chars) guides how it's woven into scenes.",
+			" (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Its pixels guide product identity " +
+			"in every generated Editor scene and its confirmed description grounds scenario and narration. The exact photo " +
+			"is linked as the closing image unless a separate closing image was authored; generated fine label text can still vary.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			file_path: z
@@ -5165,33 +5194,6 @@ registerTool(
 	),
 );
 
-registerTool(
-	"set_product_placement",
-	{
-		title: "Set default product placement on pending scenes (0 credits)",
-		description:
-			"Sets where the product appears across pending (never-generated) AI scenes. mode is 'throughout' (every scene) " +
-			"or 'end' (closing scene only; requires a first+last-frame capable model). 0 credits. Add a product first with " +
-			"set_product. (There is no 'none' — to remove the product, that's a separate action.)",
-		inputSchema: {
-			slug: z.string().describe("Editor project slug"),
-			mode: z.enum(["throughout", "end"]).describe("'throughout' or 'end'"),
-		},
-		annotations: {
-			title: "Set product placement",
-			...WRITE,
-			idempotentHint: true,
-		},
-	},
-	tool(async (args: { slug: string; mode: "throughout" | "end" }, client) => {
-		const res = await client.post<{ data: unknown }>(
-			`/editor/${args.slug}/product/apply-default-placement`,
-			{ placement: args.mode },
-		);
-		return ok(asRecord(res).data ?? res);
-	}),
-);
-
 registerTool(
 	"set_closing_image",
 	{