@hubfluencer/mcp 0.14.0 → 0.16.0

package/README.md

@@ -85,8 +85,8 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `cancel_short_generation` | Stop the caller-observed paid short attempt, fence late workers from publishing, preserve the draft, and restore its 15 credits idempotently. Requires `generation_attempt` from `get_status`; stale commands cannot cancel a newer run. | **full refund** |
 | `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. 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 |
+| `create_editor_ad` | Create an editor project, attach optional local product/logo/closing assets, and return the live autopilot quote. Pass `segments_count` (3–10) as the exact structural target. 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`; `segments_count` (3–10) overrides an older brief and is reflected in the matching quote. 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 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** |
 | `cancel_autopilot` | Stop a **running** Autopilot run: flips `autopilot_status` to `cancelled` so the chain (scenario → scenes → narration → voice → music → render) advances no further. Charged scenes stay charged and all completed work is kept; a step already enqueued may still finish. Idempotent — a no-op when Autopilot isn't running. (Use `cancel_editor_batch` for a non-Autopilot prepaid batch, `cancel_segment_generation` for one scene.) | **0 additional** |
@@ -111,9 +111,9 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `cancel_segment_generation` | Stop the caller-observed individually generated scene, fence its provider job from publishing, and restore any charged credits idempotently. Requires that scene's `generation_claim_token` from `get_editor`; stale commands cannot cancel a newer attempt. Batch/Autopilot scenes use their workflow-level controls. | **full refund** |
 | `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 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 |
+| `set_narration_script` / `generate_narration` | Write the exact words to read aloud (free)—never pass a production prompt, camera directions, or a creative brief as `script`—**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** |
+| `generate_music` | Generate background music (each call is a fresh take). Optional `instruments` is a string array (≤10 non-empty hints, ≤80 chars each), not a comma-separated string. | **5** |
 | `render` | Final MP4. Auto-charges and generates any pending or failed 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`, `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** |
@@ -137,19 +137,27 @@ images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
 | `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**. |
-| `set_short_logo` | Attach an exact deterministic logo overlay (JPEG/PNG, ≤5 MiB) to a **short**; choose its corner and `throughout`/`end_card`/`none` (hide) treatment. The logo is never sent to the video model. |
-| `set_short_poster` | Set a short's end-card poster (JPEG/PNG, ≤20 MiB; extends the render 12s → 14s). Pass `poster_includes_lockup:true` if the poster already carries brand name/CTA/badges — suppresses the overlaid claim/CTA so they don't collide. |
+| `set_short_logo` | Attach an exact deterministic logo overlay (JPEG/PNG, ≤5 MiB) to a **short**. The corner is preferred and Forge moves it away from text/CTA/chips. Omit treatment to auto-select: transparent marks use `throughout`, opaque square lockups use `end_card`; explicit `throughout`/`end_card`/`none` still wins. The logo is never sent to the video model. |
+| `set_short_poster` | Set a short's end-card poster (JPEG/PNG, ≤20 MiB; extends the render 12s → 14s). Phone-shaped portrait art is cover-cropped to 9:16; square, classic portrait, and landscape art is contained over a blurred backdrop. Pass `poster_includes_lockup:true` if the poster already carries brand name/CTA/badges — suppresses the overlaid claim/CTA and an end-card-only logo so they don't collide. |
 
 ### Status & delivery
 
 | Tool | What it does |
 |---|---|
-| `get_status` | Normalized `{stage, terminal, ready, video_url, error}` for a short / editor / tracking / slider. |
+| `get_status` | Normalized `{stage, terminal, ready, video_url, error}` for a short / editor / tracking / slider. While a paid short is rendering, also exposes `segments_completed`, `segments_total`, and `active_segment_positions`; `generation_attempt` is the cancellation fence. |
 | `wait_for_completion` | Block-poll until terminal (bounded ≤280s; returns `terminal:false` to re-call). `save_path` downloads the MP4 when ready. |
 | `download_result` | Get (or save, to `HUBFLUENCER_OUTPUT_DIR`) the finished MP4 URL. Not for sliders — use `get_slider`. |
-| `get_credits` / `list_voices` / `list_projects` | Credit balance; narration voices; recent projects (`include_completed:true` to recover a finished short's slug). |
+| `get_credits` / `list_voices` / `list_projects` | Credit balance; narration voices (including normalized verified `languages`); recent projects (`include_completed:true` to recover a finished short's slug). |
 | `get_ai_assists` / `unlock_ai_assists` | The free daily assist quota / spend 1 credit for +10. |
 
+### Creative export contract
+
+- Production prompts (`product_prompt`, `scenario_prompt`, and scene `prompt`) are visual directions. Narration scripts are read aloud verbatim, so `set_narration_script.script` must contain only the exact spoken words—never camera notes, prompt syntax, labels, or scene directions. Never copy a creative brief into `script`; prefer `generate_narration` or Autopilot unless the user supplied final voice-over copy.
+- Do not rely on the video model to spell essential brand names, UI, signs, prices, offers, or CTAs. Put exact copy in Hubfluencer overlays, narration, or supplied ending artwork.
+- `short_logo_position` is a preferred corner. Forge moves the logo away from headline, captions, CTA, offer, and badge areas. Omit treatment so transparent marks default to `throughout` and opaque square lockups default to `end_card`. Use a tight transparent wordmark; use square/full-bleed art as the poster. `end_card` logos are suppressed when `poster_includes_lockup:true` to avoid double branding.
+- Short posters fill the ending frame: phone-shaped portrait art is cover-cropped, while square, classic portrait, and landscape art is contained over a blurred backdrop. Editor closing images are always cover-cropped. Keep important content in the central 9:16 safe area. An Editor closing image gets no generic CTA, so put the CTA in the artwork or state it in the preceding narration/scene.
+- Each Editor AI scene is 8 seconds. Request 3 scenes (about 24 seconds) for a concise social ad unless the brief needs a longer story.
+
 For editor projects, `video_url` may remain the last delivered MP4 after the timeline changes.
 It is current only when `ready:true` and `stale:false`. `stale:true` means the delivered render
 does not match the live timeline; regenerate the reported stale scenes/audio and render again.

package/dist/index.js

@@ -29578,6 +29578,7 @@ function normalizeStatus(kind, slug, data) {
   const renderStale = latest.is_stale === true;
   const renderFresh = latest.is_stale === false;
   const stale = renderStale || staleSegments.length > 0 || audioStale;
+  const autopilotContractIncomplete = autopilot === "completed" && d.autopilot_contract_satisfied === false && !stale;
   const renderActive = renderStatus === "pending" || renderStatus === "rendering" || renderStatus === "processing";
   const scenarioActive = d.scenario_status === "generating" || d.scenario_apply_status === "pending" || d.scenario_apply_status === "applying";
   const narrationActive = d.narration_status === "generating";
@@ -29617,7 +29618,7 @@ function normalizeStatus(kind, slug, data) {
   const batchRecoveryActive = autopilotFailed && batchActive;
   const childFailureActionable = !batchRecoveryActive && (!autopilotActive || !childWorkActive && !autopilotResumeGraceActive);
   const workActive = autopilotActive || childWorkActive;
-  const deliveredArtifactSupersedesOrchestrationFailure = renderStatus === "completed" && Boolean(videoUrl) && renderFresh && !stale && !workActive && failedSegments.length === 0 && !audioFailed;
+  const deliveredArtifactSupersedesOrchestrationFailure = renderStatus === "completed" && Boolean(videoUrl) && renderFresh && !stale && !workActive && failedSegments.length === 0 && !audioFailed && !autopilotContractIncomplete;
   const ready = deliveredArtifactSupersedesOrchestrationFailure;
   const parentFailureActionable = autopilotFailed && !batchRecoveryActive;
   const renderFailed = renderStatus === "failed" && childFailureActionable;
@@ -29648,6 +29649,8 @@ function normalizeStatus(kind, slug, data) {
     stage = "audio_failed";
   else if (batchInsufficientCredits)
     stage = "insufficient_credits";
+  else if (autopilotContractIncomplete)
+    stage = "contract_incomplete";
   else if (activeSegments.length > 0)
     stage = "segment_processing";
   else if (batchActive)
@@ -29673,10 +29676,13 @@ 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 invoke the generation/render path again; retry_editor_batch only applies to paused_for_retry." : 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) ?? (autopilotContractIncomplete ? "Autopilot completed without every quoted deliverable. Resume Autopilot to repair the missing component." : 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")
+    stale_segment_ids: staleSegments.map((segment) => segment.id).filter((id) => typeof id === "number" || typeof id === "string"),
+    ...typeof d.autopilot_contract_satisfied === "boolean" ? {
+      autopilot_contract_satisfied: d.autopilot_contract_satisfied
+    } : {}
   };
 }
 function startStateDiscriminator(kind, data) {
@@ -29700,16 +29706,16 @@ function idemKey(...parts) {
   return createHash("sha256").update(parts.join("|")).digest("hex").slice(0, 32);
 }
 function makeVideoEditorCreateKey(a) {
-  return idemKey("make-editor", a.prompt, a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.aspect ?? "", a.voice_id ?? "", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "");
+  return idemKey("make-editor", a.prompt, a.segments_count === undefined ? "" : String(a.segments_count), a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.aspect ?? "", a.voice_id ?? "", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "");
 }
 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);
+  return idemKey("autopilot", slug, a.prompt, a.segments_count === undefined ? "" : String(a.segments_count), 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));
+  return idemKey("create-editor", a.product_prompt ?? "", a.segments_count === undefined ? "" : String(a.segments_count), 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.max_credits === undefined ? "" : String(a.max_credits));
+  return idemKey("autopilot", slug, a.product_prompt ?? "", a.segments_count === undefined ? "" : String(a.segments_count), 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 ?? "");
@@ -30266,7 +30272,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.14.0",
+  version: "0.16.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>",
@@ -30992,6 +30998,38 @@ function assetSubscriptionErrorText(status, code, message) {
   return `${message} The reusable asset catalog requires an ACTIVE SUBSCRIPTION; ` + "this is a billing gate, not a scope or credit issue, so retrying won't help — " + "subscribe in the app first. (Generating videos/carousels does not require this.)";
 }
 
+// src/polling.ts
+async function pollWithFinalReconciliation({
+  read,
+  isTerminal: isTerminal2,
+  budgetMs,
+  intervalMs,
+  onPoll,
+  now = Date.now,
+  sleep: sleep3 = (milliseconds) => new Promise((resolve2) => setTimeout(resolve2, milliseconds))
+}) {
+  const deadline = now() + budgetMs;
+  let value = await read(deadline);
+  let pollNumber = 0;
+  while (!isTerminal2(value)) {
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0)
+      break;
+    await onPoll?.(value, ++pollNumber);
+    await sleep3(Math.min(intervalMs, remainingMs));
+    if (now() >= deadline)
+      break;
+    value = await read(deadline);
+  }
+  if (!isTerminal2(value)) {
+    const finalReadDeadline = now() + Math.min(5000, Math.max(1000, intervalMs));
+    try {
+      value = await read(finalReadDeadline);
+    } catch {}
+  }
+  return value;
+}
+
 // src/series-calendar.ts
 var SERIES_FIELDS = [
   "brand_profile_id",
@@ -31590,6 +31628,8 @@ async function editorAutopilotQuote(client, slug, overrides = {}) {
       params.set("product_subject", overrides.product_subject);
     if (overrides.product_prompt !== undefined)
       params.set("product_prompt", overrides.product_prompt);
+    if (overrides.segments_count !== undefined)
+      params.set("segments_count", String(overrides.segments_count));
     if (overrides.restart)
       params.set("restart", "true");
     const query = params.toString();
@@ -31597,9 +31637,13 @@ async function editorAutopilotQuote(client, slug, overrides = {}) {
     const cost = asRecord(asRecord(response).data);
     const estimated_credits = typeof cost.total === "number" ? cost.total : null;
     const available_credits = typeof cost.available_credits === "number" ? cost.available_credits : null;
+    const scene_count = typeof cost.scene_count === "number" ? cost.scene_count : null;
+    const target_duration_seconds = typeof cost.target_duration_seconds === "number" ? cost.target_duration_seconds : null;
     return {
       estimated_credits,
       available_credits,
+      scene_count,
+      target_duration_seconds,
       affordable: estimated_credits !== null && available_credits !== null && available_credits >= estimated_credits
     };
   } catch (error2) {
@@ -31610,6 +31654,8 @@ async function editorAutopilotQuote(client, slug, overrides = {}) {
     return {
       estimated_credits: null,
       available_credits: null,
+      scene_count: null,
+      target_duration_seconds: null,
       affordable: false
     };
   }
@@ -31885,15 +31931,13 @@ AUTH: set HUBFLUENCER_API_TOKEN (Settings → Access tokens) or run \`npx -y @hu
 var server = new McpServer({ name: "hubfluencer", version: VERSION }, { instructions: SERVER_INSTRUCTIONS });
 var registerTool = server.registerTool.bind(server);
 async function pollToTerminal(client, kind, slug, extra, budgetMs, intervalMs) {
-  const deadline = Date.now() + budgetMs;
-  let status = await fetchStatus(client, kind, slug, deadline);
-  let n = 0;
-  while (!status.terminal && Date.now() + intervalMs <= deadline) {
-    await reportProgress(extra, ++n, `stage: ${status.stage}`);
-    await sleep4(intervalMs);
-    status = await fetchStatus(client, kind, slug, deadline);
-  }
-  return status;
+  return pollWithFinalReconciliation({
+    read: (deadline) => fetchStatus(client, kind, slug, deadline),
+    isTerminal: (status) => status.terminal,
+    budgetMs,
+    intervalMs,
+    onPoll: (status, pollNumber) => reportProgress(extra, pollNumber, `stage: ${status.stage}`)
+  });
 }
 async function pollSegmentToTerminal(client, slug, segmentId, extra, deadline, intervalMs) {
   const sid = String(segmentId);
@@ -31928,6 +31972,7 @@ registerTool("make_video", {
     kind: exports_external.string().optional().describe("'short' (fast, 1 clip), 'editor' (multi-scene), or 'auto' (default — inferred)"),
     product_subject: exports_external.string().max(300).optional().describe('EDITOR only: the concrete product / main subject the video must be about (e.g. "Bordeaux red ' + 'wine, dark green bottle"). Hard-grounds the AI so it cannot invent an unrelated product. ' + "Recommended for ads."),
     project_intent: exports_external.enum(["social_ad", "creative_story"]).optional().describe("EDITOR only: social_ad for promotional content (product focus + CTA) or creative_story (default)."),
+    segments_count: exports_external.number().int().min(3).max(10).optional().describe("EDITOR only: exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad."),
     language: exports_external.enum(LANGUAGES).optional().describe('Language (default "en"). Bare ISO-639-1 code only — no region/script subtag ' + '(use "pt", never "pt-BR"/"en-US"). Drives scenario, narration, voice, and captions.'),
     aspect: exports_external.string().optional().describe("Aspect ratio for editor: 9:16 (default), 16:9, or 1:1"),
     voice_id: exports_external.string().optional().describe("Preferred narration voice id for editor ads (see list_voices); shorts have no voiceover"),
@@ -31979,6 +32024,9 @@ registerTool("make_video", {
     return fail(kindErr);
   const requestedKind = args.kind === "short" || args.kind === "editor" ? args.kind : undefined;
   const kind = requestedKind ?? inferKind(args.prompt);
+  if (kind !== "editor" && args.segments_count !== undefined) {
+    return fail("segments_count is only supported for editor videos.");
+  }
   const waitSeconds = Math.min(280, Math.max(10, args.max_wait_seconds ?? 240));
   const budgetMs = waitSeconds * 1000;
   if (args.star_rating !== undefined && (args.star_rating < 0 || args.star_rating > 5)) {
@@ -32031,6 +32079,7 @@ registerTool("make_video", {
     const created = await client.post("/editor", {
       language: args.language ?? "en",
       product_prompt: args.prompt,
+      segments_count: args.segments_count,
       product_subject: args.product_subject,
       project_intent: args.project_intent,
       export_aspect_ratio: args.aspect,
@@ -32140,7 +32189,7 @@ registerTool("get_credits", {
 }));
 registerTool("list_voices", {
   title: "List voices",
-  description: "Lists available narration voices (id + name). Pass a voice id as voice_id to create_editor_ad / " + "make_video to pick the narration voice for an editor ad. Shorts have no voiceover.",
+  description: "Lists available narration voices with voice_id, preview metadata, and verified language codes. " + "Choose a voice whose languages includes the editor project's language, then pass its voice_id to " + "create_editor_ad / make_video / generate_voice. Shorts have no voiceover.",
   inputSchema: {},
   annotations: { title: "List voices", ...RO }
 }, tool(async (_args, client) => {
@@ -32337,7 +32386,7 @@ registerTool("update_short", {
     brand_name: exports_external.string().max(40).optional().describe("Brand/product display name (≤40 chars) shown big on the closing brand-lockup slate when no " + `poster is set. Server falls back to your brand profile's name when unset. Pass "" to remove it.`),
     end_card: exports_external.enum(["auto", "none"]).optional().describe('"auto" (default): end on the poster, or on a brand-lockup slate (brand_name + claim + CTA pill) ' + 'when no poster is set — a 14s render. "none": no end card at all (12s, for deliberate ' + "loop-style shorts)."),
     poster_includes_lockup: exports_external.boolean().optional().describe("Set true if your poster already contains brand name/CTA/badges — suppresses the overlaid " + "claim/CTA so they don't collide (default false)."),
-    short_logo_position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe("Corner for the deterministic brand-logo overlay (set the image with set_short_logo). Moving it is " + "a FREE re-render — logo fields never cost credits."),
+    short_logo_position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe("Preferred corner for the deterministic brand-logo overlay (set the image with set_short_logo). " + "Forge moves it to a clear rail when text/CTA/chips occupy that corner. Moving it is a FREE " + "re-render — logo fields never cost credits."),
     short_logo_treatment: exports_external.enum(["throughout", "end_card", "none"]).optional().describe('When the brand logo shows: "throughout" the footage, only on the "end_card", or "none" to hide it. ' + "FREE re-render."),
     brand_profile_id: exports_external.number().int().optional().describe("Seed brand defaults — colors/font/CTA — from a saved brand profile (id from " + "list_brand_profiles). Best set at create_short time (that path also freezes a brand snapshot); " + "on update it sets the linked profile. Must be one of your own profiles.")
   },
@@ -32553,19 +32602,21 @@ registerTool("create_tracking_video", {
 }));
 registerTool("generate_short", {
   title: "Generate (render) a short",
-  description: "Deducts 15 credits and starts the render pipeline for an existing short — this RE-ROLLS the footage " + "and music (a fresh AI generation). For text/style/CTA/end-card tweaks on an already-generated short, " + "use rerender_short instead: it re-applies the overlay over the existing footage for 0 credits. " + "Safe to call again: a " + "duplicate while a render is in flight is reported as in-progress (no double charge), and a failed " + "short can be re-generated. If the draft's headline/subheadline/text_beats are all blank the server " + "auto-writes the headline + caption beats before rendering (pass skip_auto_text:true for a deliberately " + "bare clip). Then poll with get_status or wait_for_completion (kind=short).",
+  description: "Deducts 15 credits and starts the render pipeline for an existing short — this RE-ROLLS the footage " + "and music (a fresh AI generation). For text/style/CTA/end-card tweaks on an already-generated short, " + "use rerender_short instead: it re-applies the overlay over the existing footage for 0 credits. " + "Safe to call again: a " + "duplicate while a render is in flight is reported as in-progress (no double charge), and a failed " + "short can be re-generated. If the draft's headline/subheadline/text_beats are all blank the server " + "auto-writes the headline + caption beats before rendering (pass skip_auto_text:true for a deliberately " + "bare clip). A transient 5xx is reconciled against the project state: accepted work is returned as " + "in-progress, while an unchanged draft is retried once. Then poll with get_status or " + "wait_for_completion (kind=short).",
   inputSchema: {
     slug: exports_external.string().describe("Short slug from create_short"),
     skip_auto_text: exports_external.boolean().optional().describe("When the draft has no headline/subheadline/text_beats the server auto-writes the copy; pass " + "true to skip that and render a deliberately bare clip (default false).")
   },
   annotations: { title: "Generate short", ...WRITE }
 }, tool(async (args, client) => {
+  const submit = () => client.post(`/shorts/${args.slug}/generate`, args.skip_auto_text ? { skip_auto_text: true } : undefined);
   try {
-    const res = await client.post(`/shorts/${args.slug}/generate`, args.skip_auto_text ? { skip_auto_text: true } : undefined);
+    const res = await submit();
     const status = normalizeStatus("short", args.slug, asRecord(res).data);
     return ok(status);
   } catch (e) {
-    if (e.status === 409) {
+    const statusCode = e.status;
+    if (statusCode === 409) {
       return ok({
         kind: "short",
         slug: args.slug,
@@ -32576,6 +32627,35 @@ registerTool("generate_short", {
         error: null
       });
     }
+    if (statusCode !== undefined && statusCode >= 500) {
+      let reconciled;
+      try {
+        reconciled = await fetchStatus(client, "short", args.slug);
+      } catch (_reconcileError) {
+        throw e;
+      }
+      if (reconciled.stage === "rendering")
+        return ok(reconciled);
+      if (reconciled.stage !== "draft")
+        throw e;
+      try {
+        const retried = await submit();
+        return ok(normalizeStatus("short", args.slug, asRecord(retried).data));
+      } catch (retryError) {
+        if (retryError.status === 409) {
+          return ok({
+            kind: "short",
+            slug: args.slug,
+            stage: "processing",
+            terminal: false,
+            ready: false,
+            video_url: null,
+            error: null
+          });
+        }
+        throw retryError;
+      }
+    }
     throw e;
   }
 }));
@@ -32847,9 +32927,9 @@ 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. " + "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.)",
+  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. Do not depend on the video model for exact readable " + "brand names, UI, signs, prices, or CTA copy; put essential copy in narration or deterministic Short/poster overlays. " + "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_prompt: exports_external.string().min(10).describe("Creative brief for the ad (min 10 chars), not literal voiceover copy. Autopilot uses it to draft " + "narration. For exact spoken words, use the granular editor path and pass only read-aloud text to " + "set_narration_script."),
     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."),
     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)."),
     language: exports_external.enum(LANGUAGES).optional().describe('Language (default "en"). Bare ISO-639-1 code only — no region/script subtag (use "es", not "es-MX"). ' + "Drives the WHOLE video: scenario, narration script, narration voice, and captions. " + "Ask the user / infer from their locale."),
@@ -32858,6 +32938,7 @@ registerTool("create_editor_ad", {
     theme: exports_external.enum(SCENARIO_THEMES).optional().describe('Optional visual theme / genre overlay (default "none", so scene prompts drive the look). One of: none, 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")'),
+    segments_count: exports_external.number().int().min(3).max(10).optional().describe("Exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad; omit to retain the server default."),
     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)."),
@@ -32902,6 +32983,7 @@ registerTool("create_editor_ad", {
     const created = await client.post("/editor", {
       language: args.language ?? "en",
       product_prompt: args.product_prompt,
+      segments_count: args.segments_count,
       product_subject: args.product_subject,
       project_intent: args.project_intent,
       creative_format: args.creative_format,
@@ -32948,7 +33030,9 @@ registerTool("create_editor_ad", {
       logoSettings.logo_duration_seconds = args.logo_duration_seconds;
     if (args.logo_path && Object.keys(logoSettings).length > 0)
       await client.patch(`/editor/${slug}/logo`, logoSettings);
-    const quote = await editorAutopilotQuote(client, slug);
+    const quote = await editorAutopilotQuote(client, slug, {
+      segments_count: args.segments_count
+    });
     const overCap = args.max_credits !== undefined && quote.estimated_credits !== null && quote.estimated_credits > args.max_credits;
     if (args.max_credits === undefined || quote.estimated_credits === null || overCap || !quote.affordable) {
       const note = args.max_credits === undefined ? `Free draft configured. Estimated ${quote.estimated_credits ?? "?"} credits (have ${quote.available_credits ?? "?"}); nothing charged. Relaunch with start_autopilot({ slug: "${slug}", max_credits: ${quote.estimated_credits ?? "<approved cap>"} }).` : quote.estimated_credits === null ? "Pricing is temporarily unavailable, so the paid pipeline was not started. Retry the quote later." : overCap ? `Estimated ${quote.estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged.` : `Not enough credits (needs ${quote.estimated_credits}, have ${quote.available_credits ?? "?"}); nothing charged.`;
@@ -32961,7 +33045,10 @@ registerTool("create_editor_ad", {
         next: "start_autopilot"
       });
     }
-    const started = await client.post(`/editor/${slug}/autopilot`, { max_credits: args.max_credits }, editorAdAutopilotKey(slug, args));
+    const started = await client.post(`/editor/${slug}/autopilot`, {
+      max_credits: args.max_credits,
+      segments_count: args.segments_count
+    }, editorAdAutopilotKey(slug, args));
     const status = normalizeStatus("editor", slug, asRecord(started).data);
     return ok({
       slug,
@@ -32986,6 +33073,7 @@ registerTool("start_autopilot", {
     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. 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."),
+    segments_count: exports_external.number().int().min(3).max(10).optional().describe("Optional exact number of 8-second AI scenes (3–10). Omit to keep the stored structural target."),
     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.")
   },
@@ -33006,6 +33094,8 @@ registerTool("start_autopilot", {
     overrides.product_subject = args.product_subject;
   if (args.product_prompt !== undefined)
     overrides.product_prompt = args.product_prompt;
+  if (args.segments_count !== undefined)
+    overrides.segments_count = args.segments_count;
   if (args.restart)
     overrides.restart = true;
   const quote = await editorAutopilotQuote(client, slug, overrides);
@@ -33628,7 +33718,7 @@ registerTool("generate_voice", {
 }));
 registerTool("generate_music", {
   title: "Generate the background music (5 credits)",
-  description: "Generates background music. Costs 5 credits. Each call produces a fresh take (music is non-deterministic) — call again for another. `description` is an optional" + "music-direction prompt (≤1200 chars; longer is silently truncated server-side). 402 fails cleanly.",
+  description: "Generates background music. Costs 5 credits. Each call produces a fresh take (music is non-deterministic) — call again for another. `description` is an optional" + " music-direction prompt (≤1200 chars; longer is silently truncated server-side). `instruments` is an " + "optional array of up to 10 non-empty hints (≤80 chars each), never a comma-separated string. 402 fails cleanly.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     description: exports_external.string().max(1200).optional().describe("Music direction prompt (≤1200 chars, truncated if longer)"),
@@ -33984,12 +34074,12 @@ registerTool("set_short_product", {
 }));
 registerTool("set_short_logo", {
   title: "Set a Short brand logo overlay (0 credits)",
-  description: "Uploads an exact brand logo for deterministic compositing over a Short. The image is never sent to the " + "AI video provider, so lettering is preserved. PNG/JPEG, ≤5 MiB, 0 credits. Choose a corner and whether " + "it appears throughout the footage or only on the end card.",
+  description: "Uploads an exact brand logo for deterministic compositing over a Short. The image is never sent to the " + "AI video provider, so lettering is preserved. PNG/JPEG, ≤5 MiB, 0 credits. Choose a corner and whether " + "it appears throughout the footage or only on the end card. The corner is a preference: Forge moves the " + "logo to a clear rail when headline/caption/CTA/chip overlays occupy it. Prefer a tight transparent PNG " + "wordmark; use square/full-bleed artwork as a poster instead of a watermark.",
   inputSchema: {
     slug: exports_external.string().describe("Short slug"),
     file_path: exports_external.string().describe("Local logo image (.png/.jpg/.jpeg)"),
-    position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe("Logo corner (default top-right)"),
-    treatment: exports_external.enum(["throughout", "end_card", "none"]).optional().describe("When the logo appears (default throughout)")
+    position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe("Preferred logo corner (default top-right; auto-relocated to avoid text)"),
+    treatment: exports_external.enum(["throughout", "end_card", "none"]).optional().describe("When the logo appears. Omit for automatic treatment: transparent wordmarks run throughout; opaque square artwork moves to the end card.")
   },
   annotations: { title: "Set Short logo", ...WRITE, idempotentHint: false }
 }, tool(async (args, client) => {
@@ -33997,7 +34087,7 @@ registerTool("set_short_logo", {
   const res = await client.post(`/shorts/${args.slug}/logo/confirm`, {
     s3_key,
     position: args.position ?? "top-right",
-    treatment: args.treatment ?? "throughout"
+    ...args.treatment ? { treatment: args.treatment } : {}
   });
   return ok(asRecord(res).data ?? res);
 }));
@@ -34020,7 +34110,7 @@ registerTool("set_short_poster", {
 }));
 registerTool("get_status", {
   title: "Get generation status",
-  description: "Returns a normalized status {stage, terminal, ready, video_url, error} for a short, editor, " + "tracking, or slider project. ready:true means the post-ready MP4 is at video_url — except for a " + "slider (a carousel of stills, not a video): its video_url is always null, ready:true means every " + "slide is composited, and you read the per-slide image URLs with get_slider.",
+  description: "Returns a normalized status {stage, terminal, ready, video_url, error} for a short, editor, " + "tracking, or slider project. ready:true means the post-ready MP4 is at video_url — except for a " + "slider (a carousel of stills, not a video): its video_url is always null, ready:true means every " + "slide is composited, and you read the per-slide image URLs with get_slider. During paid short " + "generation, segments_completed / segments_total and active_segment_positions report real clip progress.",
   inputSchema: { slug: exports_external.string(), kind: kindSchema },
   outputSchema: getStatusOutput,
   annotations: { title: "Get status", ...RO }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubfluencer/mcp",
-  "version": "0.14.0",
+  "version": "0.16.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

@@ -289,6 +289,8 @@ export interface NormalizedStatus {
 	active_segment_ids?: Array<number | string>;
 	/** Editor only: completed current scene ids invalidated by continuity edits. */
 	stale_segment_ids?: Array<number | string>;
+	/** Editor Autopilot only: server-verified quoted delivery contract. */
+	autopilot_contract_satisfied?: boolean;
 	/** Short only (additive, absent on older APIs): the newest render row is a free re-render. */
 	latest_render_free?: boolean;
 	/**
@@ -515,6 +517,21 @@ export function normalizeStatus(
 	// Legacy/null/omitted freshness is unknown and must never be promoted to ready.
 	const renderFresh = latest.is_stale === false;
 	const stale = renderStale || staleSegments.length > 0 || audioStale;
+	// A completed Autopilot run the API reports as NOT satisfying its delivery
+	// contract — gated on a FRESH timeline. The server recomputes
+	// autopilot_contract_satisfied LIVE for completed runs, folding in staleness,
+	// so any ordinary post-delivery edit (e.g. adding narration makes music stale)
+	// flips it false even though the run genuinely delivered. Gating on !stale
+	// keeps this signal to the real missing-component case — canonically a legacy
+	// "music-only" run where nothing is stale but voice/narration were never
+	// produced — and lets the stale/editing_required semantics win everywhere once
+	// an edit lands. Declared after `stale` (which it depends on); the raw
+	// autopilot_contract_satisfied wire field is still passed through verbatim
+	// below, only this derived stage/error signal is freshness-gated.
+	const autopilotContractIncomplete =
+		autopilot === "completed" &&
+		d.autopilot_contract_satisfied === false &&
+		!stale;
 	// A render in flight is active work too — fold it into workActive so the
 	// terminal computation below can never fire while a render is queued/running.
 	// "pending" here is NOT an idle default: a video_results row only exists once
@@ -638,7 +655,8 @@ export function normalizeStatus(
 		!stale &&
 		!workActive &&
 		failedSegments.length === 0 &&
-		!audioFailed;
+		!audioFailed &&
+		!autopilotContractIncomplete;
 	const ready = deliveredArtifactSupersedesOrchestrationFailure;
 	const parentFailureActionable = autopilotFailed && !batchRecoveryActive;
 	const renderFailed = renderStatus === "failed" && childFailureActionable;
@@ -698,6 +716,7 @@ export function normalizeStatus(
 		stage = "segment_failed";
 	else if (childFailureActionable && audioFailed) stage = "audio_failed";
 	else if (batchInsufficientCredits) stage = "insufficient_credits";
+	else if (autopilotContractIncomplete) stage = "contract_incomplete";
 	else if (activeSegments.length > 0) stage = "segment_processing";
 	else if (batchActive) stage = "segment_generation";
 	else if (autoRenderHandoffActive) stage = "rendering";
@@ -727,6 +746,13 @@ export function normalizeStatus(
 		terminal,
 		ready,
 		video_url: videoUrl,
+		// Mirror the stage chain's precedence EXACTLY so the error text always
+		// matches the stage the caller sees. batch-retry, then the actionable
+		// parent/child failures, then insufficient-credits, and only last the
+		// contract-incomplete message — because a completed-autopilot editor with a
+		// later paused manual batch reports stage "batch_retry_required", so it must
+		// read the retry guidance, not "Resume Autopilot" (the one action
+		// start_autopilot refuses while a batch is paused).
 		error: ready
 			? null
 			: batchRetryRequired
@@ -737,6 +763,9 @@ export function normalizeStatus(
 					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) ??
+					(autopilotContractIncomplete
+						? "Autopilot completed without every quoted deliverable. Resume Autopilot to repair the missing component."
 						: null)),
 		stale,
 		active_segment_ids: activeSegments
@@ -751,6 +780,12 @@ export function normalizeStatus(
 				(id): id is number | string =>
 					typeof id === "number" || typeof id === "string",
 			),
+		...(typeof d.autopilot_contract_satisfied === "boolean"
+			? {
+					autopilot_contract_satisfied:
+						d.autopilot_contract_satisfied as boolean,
+				}
+			: {}),
 	};
 }
 
@@ -817,6 +852,7 @@ export function idemKey(...parts: string[]): string {
 /** make_video's editor draft-create key (`POST /editor`). */
 export interface MakeVideoEditorCreateArgs {
 	prompt: string;
+	segments_count?: number;
 	product_subject?: string;
 	project_intent?: string;
 	language?: string;
@@ -831,6 +867,7 @@ export function makeVideoEditorCreateKey(a: MakeVideoEditorCreateArgs): string {
 	return idemKey(
 		"make-editor",
 		a.prompt,
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -857,6 +894,7 @@ export function makeVideoAutopilotKey(
 		"autopilot",
 		slug,
 		a.prompt,
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -872,6 +910,7 @@ export function makeVideoAutopilotKey(
 /** create_editor_ad's draft-create and autopilot-start key argument set. */
 export interface EditorAdKeyArgs {
 	product_prompt?: string;
+	segments_count?: number;
 	product_subject?: string;
 	project_intent?: string;
 	language?: string;
@@ -906,6 +945,7 @@ export function editorAdCreateKey(a: EditorAdKeyArgs): string {
 	return idemKey(
 		"create-editor",
 		a.product_prompt ?? "",
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -943,6 +983,7 @@ export function editorAdAutopilotKey(slug: string, a: EditorAdKeyArgs): string {
 		"autopilot",
 		slug,
 		a.product_prompt ?? "",
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",

package/src/index.ts

@@ -101,6 +101,7 @@ import {
 	validatePerformanceMetrics,
 	validateReviewOutput,
 } from "./perf-review-assets.js";
+import { pollWithFinalReconciliation } from "./polling.js";
 import {
 	buildScheduledPostBody,
 	calendarScopeErrorText,
@@ -161,11 +162,14 @@ async function editorAutopilotQuote(
 		language?: string;
 		product_subject?: string;
 		product_prompt?: string;
+		segments_count?: number;
 		restart?: boolean;
 	} = {},
 ): Promise<{
 	estimated_credits: number | null;
 	available_credits: number | null;
+	scene_count: number | null;
+	target_duration_seconds: number | null;
 	affordable: boolean;
 }> {
 	try {
@@ -175,6 +179,8 @@ async function editorAutopilotQuote(
 			params.set("product_subject", overrides.product_subject);
 		if (overrides.product_prompt !== undefined)
 			params.set("product_prompt", overrides.product_prompt);
+		if (overrides.segments_count !== undefined)
+			params.set("segments_count", String(overrides.segments_count));
 		if (overrides.restart) params.set("restart", "true");
 		const query = params.toString();
 		const response = await client.get<{ data: unknown }>(
@@ -187,9 +193,17 @@ async function editorAutopilotQuote(
 			typeof cost.available_credits === "number"
 				? cost.available_credits
 				: null;
+		const scene_count =
+			typeof cost.scene_count === "number" ? cost.scene_count : null;
+		const target_duration_seconds =
+			typeof cost.target_duration_seconds === "number"
+				? cost.target_duration_seconds
+				: null;
 		return {
 			estimated_credits,
 			available_credits,
+			scene_count,
+			target_duration_seconds,
 			affordable:
 				estimated_credits !== null &&
 				available_credits !== null &&
@@ -213,6 +227,8 @@ async function editorAutopilotQuote(
 		return {
 			estimated_credits: null,
 			available_credits: null,
+			scene_count: null,
+			target_duration_seconds: null,
 			affordable: false,
 		};
 	}
@@ -674,15 +690,14 @@ async function pollToTerminal(
 	budgetMs: number,
 	intervalMs: number,
 ): Promise<NormalizedStatus> {
-	const deadline = Date.now() + budgetMs;
-	let status = await fetchStatus(client, kind, slug, deadline);
-	let n = 0;
-	while (!status.terminal && Date.now() + intervalMs <= deadline) {
-		await reportProgress(extra, ++n, `stage: ${status.stage}`);
-		await sleep(intervalMs);
-		status = await fetchStatus(client, kind, slug, deadline);
-	}
-	return status;
+	return pollWithFinalReconciliation({
+		read: (deadline) => fetchStatus(client, kind, slug, deadline),
+		isTerminal: (status) => status.terminal,
+		budgetMs,
+		intervalMs,
+		onPoll: (status, pollNumber) =>
+			reportProgress(extra, pollNumber, `stage: ${status.stage}`),
+	});
 }
 
 /**
@@ -799,6 +814,15 @@ registerTool(
 				.describe(
 					"EDITOR only: social_ad for promotional content (product focus + CTA) or creative_story (default).",
 				),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe(
+					"EDITOR only: exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad.",
+				),
 			language: z
 				.enum(LANGUAGES)
 				.optional()
@@ -978,6 +1002,7 @@ registerTool(
 				kind?: string;
 				product_subject?: string;
 				project_intent?: string;
+				segments_count?: number;
 				language?: string;
 				aspect?: string;
 				voice_id?: string;
@@ -1022,6 +1047,9 @@ registerTool(
 			const requestedKind =
 				args.kind === "short" || args.kind === "editor" ? args.kind : undefined;
 			const kind: Kind = requestedKind ?? inferKind(args.prompt);
+			if (kind !== "editor" && args.segments_count !== undefined) {
+				return fail("segments_count is only supported for editor videos.");
+			}
 			const waitSeconds = Math.min(
 				280,
 				Math.max(10, args.max_wait_seconds ?? 240),
@@ -1128,6 +1156,7 @@ registerTool(
 					{
 						language: args.language ?? "en",
 						product_prompt: args.prompt,
+						segments_count: args.segments_count,
 						product_subject: args.product_subject,
 						project_intent: args.project_intent,
 						export_aspect_ratio: args.aspect,
@@ -1412,8 +1441,9 @@ registerTool(
 	{
 		title: "List voices",
 		description:
-			"Lists available narration voices (id + name). Pass a voice id as voice_id to create_editor_ad / " +
-			"make_video to pick the narration voice for an editor ad. Shorts have no voiceover.",
+			"Lists available narration voices with voice_id, preview metadata, and verified language codes. " +
+			"Choose a voice whose languages includes the editor project's language, then pass its voice_id to " +
+			"create_editor_ad / make_video / generate_voice. Shorts have no voiceover.",
 		inputSchema: {},
 		annotations: { title: "List voices", ...RO },
 	},
@@ -2023,8 +2053,9 @@ registerTool(
 				.enum(["top-left", "top-right", "bottom-left", "bottom-right"])
 				.optional()
 				.describe(
-					"Corner for the deterministic brand-logo overlay (set the image with set_short_logo). Moving it is " +
-						"a FREE re-render — logo fields never cost credits.",
+					"Preferred corner for the deterministic brand-logo overlay (set the image with set_short_logo). " +
+						"Forge moves it to a clear rail when text/CTA/chips occupy that corner. Moving it is a FREE " +
+						"re-render — logo fields never cost credits.",
 				),
 			short_logo_treatment: z
 				.enum(["throughout", "end_card", "none"])
@@ -2541,7 +2572,9 @@ registerTool(
 			"duplicate while a render is in flight is reported as in-progress (no double charge), and a failed " +
 			"short can be re-generated. If the draft's headline/subheadline/text_beats are all blank the server " +
 			"auto-writes the headline + caption beats before rendering (pass skip_auto_text:true for a deliberately " +
-			"bare clip). Then poll with get_status or wait_for_completion (kind=short).",
+			"bare clip). A transient 5xx is reconciled against the project state: accepted work is returned as " +
+			"in-progress, while an unchanged draft is retried once. Then poll with get_status or " +
+			"wait_for_completion (kind=short).",
 		inputSchema: {
 			slug: z.string().describe("Short slug from create_short"),
 			skip_auto_text: z
@@ -2563,17 +2596,21 @@ registerTool(
 		// of a failed short. Double-charge is prevented server-side — the batch
 		// claim's conditional update rolls back the losing transaction's credit
 		// deduction — and a 409 means a render is already running.
-		try {
-			const res = await client.post<{ data: unknown }>(
+		const submit = () =>
+			client.post<{ data: unknown }>(
 				`/shorts/${args.slug}/generate`,
 				// Only send a body when the caller opts out of server auto-copy —
 				// the bare POST stays byte-identical to the pre-0.8.2 wire shape.
 				args.skip_auto_text ? { skip_auto_text: true } : undefined,
 			);
+
+		try {
+			const res = await submit();
 			const status = normalizeStatus("short", args.slug, asRecord(res).data);
 			return ok(status);
 		} catch (e) {
-			if ((e as { status?: number }).status === 409) {
+			const statusCode = (e as { status?: number }).status;
+			if (statusCode === 409) {
 				return ok({
 					kind: "short",
 					slug: args.slug,
@@ -2584,6 +2621,47 @@ registerTool(
 					error: null,
 				});
 			}
+
+			if (statusCode !== undefined && statusCode >= 500) {
+				let reconciled: NormalizedStatus;
+				try {
+					reconciled = await fetchStatus(client, "short", args.slug);
+				} catch (_reconcileError) {
+					// Preserve the original POST failure when the read-side check also
+					// fails; the client must never blind-retry a possibly accepted debit.
+					throw e;
+				}
+
+				// Only the active render stage proves this POST crossed the paid
+				// launch transaction. A previous completed/failed result can still be
+				// visible after an early 5xx; returning it here would masquerade stale
+				// work as the newly accepted generation.
+				if (reconciled.stage === "rendering") return ok(reconciled);
+				if (reconciled.stage !== "draft") throw e;
+
+				// A Short launch changes the durable factory out of draft in the
+				// same transaction as the debit. Still-draft therefore proves the
+				// failed response accepted no paid work, so one retry is safe.
+				try {
+					const retried = await submit();
+					return ok(
+						normalizeStatus("short", args.slug, asRecord(retried).data),
+					);
+				} catch (retryError) {
+					if ((retryError as { status?: number }).status === 409) {
+						return ok({
+							kind: "short",
+							slug: args.slug,
+							stage: "processing",
+							terminal: false,
+							ready: false,
+							video_url: null,
+							error: null,
+						});
+					}
+					throw retryError;
+				}
+			}
 			throw e;
 		}
 	}),
@@ -3131,7 +3209,9 @@ registerTool(
 			"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, " +
+			"was authored; generated fine label text can still vary. Do not depend on the video model for exact readable " +
+			"brand names, UI, signs, prices, or CTA copy; put essential copy in narration or deterministic Short/poster overlays. " +
+			"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.)",
@@ -3139,7 +3219,11 @@ registerTool(
 			product_prompt: z
 				.string()
 				.min(10)
-				.describe("Brief for the ad (min 10 chars)"),
+				.describe(
+					"Creative brief for the ad (min 10 chars), not literal voiceover copy. Autopilot uses it to draft " +
+						"narration. For exact spoken words, use the granular editor path and pass only read-aloud text to " +
+						"set_narration_script.",
+				),
 			product_subject: z
 				.string()
 				.max(300)
@@ -3190,6 +3274,15 @@ registerTool(
 				.enum(["9:16", "16:9", "1:1"])
 				.optional()
 				.describe('Aspect ratio (default "9:16")'),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe(
+					"Exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad; omit to retain the server default.",
+				),
 			product_image_path: z
 				.string()
 				.optional()
@@ -3255,6 +3348,7 @@ registerTool(
 				theme?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
+				segments_count?: number;
 				product_image_path?: string;
 				product_description?: string;
 				closing_image_path?: string;
@@ -3331,6 +3425,7 @@ registerTool(
 					{
 						language: args.language ?? "en",
 						product_prompt: args.product_prompt,
+						segments_count: args.segments_count,
 						product_subject: args.product_subject,
 						project_intent: args.project_intent,
 						creative_format: args.creative_format,
@@ -3409,7 +3504,9 @@ registerTool(
 				if (args.logo_path && Object.keys(logoSettings).length > 0)
 					await client.patch(`/editor/${slug}/logo`, logoSettings);
 
-				const quote = await editorAutopilotQuote(client, slug);
+				const quote = await editorAutopilotQuote(client, slug, {
+					segments_count: args.segments_count,
+				});
 				const overCap =
 					args.max_credits !== undefined &&
 					quote.estimated_credits !== null &&
@@ -3440,7 +3537,10 @@ registerTool(
 
 				const started = await client.post<{ data: unknown }>(
 					`/editor/${slug}/autopilot`,
-					{ max_credits: args.max_credits },
+					{
+						max_credits: args.max_credits,
+						segments_count: args.segments_count,
+					},
 					// Fold the create-affecting params into the start key so it tracks
 					// inputs, not just the slug. Self-consistent per-tool only: this key
 					// is compared against retries of *this* tool on *this* slug. The
@@ -3506,6 +3606,15 @@ registerTool(
 				.describe(
 					"Optional freeform brief to set/replace before launch. Omit to keep the stored brief; send blank to clear it.",
 				),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe(
+					"Optional exact number of 8-second AI scenes (3–10). Omit to keep the stored structural target.",
+				),
 			max_credits: z
 				.number()
 				.int()
@@ -3531,6 +3640,7 @@ registerTool(
 				language?: string;
 				product_subject?: string;
 				product_prompt?: string;
+				segments_count?: number;
 				max_credits?: number;
 				restart?: boolean;
 			},
@@ -3546,6 +3656,7 @@ registerTool(
 				language?: string;
 				product_subject?: string;
 				product_prompt?: string;
+				segments_count?: number;
 				restart?: boolean;
 			} = {};
 			if (args.language !== undefined) overrides.language = args.language;
@@ -3553,6 +3664,8 @@ registerTool(
 				overrides.product_subject = args.product_subject;
 			if (args.product_prompt !== undefined)
 				overrides.product_prompt = args.product_prompt;
+			if (args.segments_count !== undefined)
+				overrides.segments_count = args.segments_count;
 			if (args.restart) overrides.restart = true;
 
 			const quote = await editorAutopilotQuote(client, slug, overrides);
@@ -4806,7 +4919,8 @@ registerTool(
 		title: "Generate the background music (5 credits)",
 		description:
 			"Generates background music. Costs 5 credits. Each call produces a fresh take (music is non-deterministic) — call again for another. `description` is an optional" +
-			"music-direction prompt (≤1200 chars; longer is silently truncated server-side). 402 fails cleanly.",
+			" music-direction prompt (≤1200 chars; longer is silently truncated server-side). `instruments` is an " +
+			"optional array of up to 10 non-empty hints (≤80 chars each), never a comma-separated string. 402 fails cleanly.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			description: z
@@ -5594,18 +5708,24 @@ registerTool(
 		description:
 			"Uploads an exact brand logo for deterministic compositing over a Short. The image is never sent to the " +
 			"AI video provider, so lettering is preserved. PNG/JPEG, ≤5 MiB, 0 credits. Choose a corner and whether " +
-			"it appears throughout the footage or only on the end card.",
+			"it appears throughout the footage or only on the end card. The corner is a preference: Forge moves the " +
+			"logo to a clear rail when headline/caption/CTA/chip overlays occupy it. Prefer a tight transparent PNG " +
+			"wordmark; use square/full-bleed artwork as a poster instead of a watermark.",
 		inputSchema: {
 			slug: z.string().describe("Short slug"),
 			file_path: z.string().describe("Local logo image (.png/.jpg/.jpeg)"),
 			position: z
 				.enum(["top-left", "top-right", "bottom-left", "bottom-right"])
 				.optional()
-				.describe("Logo corner (default top-right)"),
+				.describe(
+					"Preferred logo corner (default top-right; auto-relocated to avoid text)",
+				),
 			treatment: z
 				.enum(["throughout", "end_card", "none"])
 				.optional()
-				.describe("When the logo appears (default throughout)"),
+				.describe(
+					"When the logo appears. Omit for automatic treatment: transparent wordmarks run throughout; opaque square artwork moves to the end card.",
+				),
 		},
 		annotations: { title: "Set Short logo", ...WRITE, idempotentHint: false },
 	},
@@ -5630,7 +5750,7 @@ registerTool(
 				{
 					s3_key,
 					position: args.position ?? "top-right",
-					treatment: args.treatment ?? "throughout",
+					...(args.treatment ? { treatment: args.treatment } : {}),
 				},
 			);
 			return ok(asRecord(res).data ?? res);
@@ -5700,7 +5820,8 @@ registerTool(
 			"Returns a normalized status {stage, terminal, ready, video_url, error} for a short, editor, " +
 			"tracking, or slider project. ready:true means the post-ready MP4 is at video_url — except for a " +
 			"slider (a carousel of stills, not a video): its video_url is always null, ready:true means every " +
-			"slide is composited, and you read the per-slide image URLs with get_slider.",
+			"slide is composited, and you read the per-slide image URLs with get_slider. During paid short " +
+			"generation, segments_completed / segments_total and active_segment_positions report real clip progress.",
 		inputSchema: { slug: z.string(), kind: kindSchema },
 		outputSchema: getStatusOutput,
 		annotations: { title: "Get status", ...RO },

package/src/polling.ts

@@ -0,0 +1,51 @@
+export interface PollOptions<T> {
+	read: (deadline: number) => Promise<T>;
+	isTerminal: (value: T) => boolean;
+	budgetMs: number;
+	intervalMs: number;
+	onPoll?: (value: T, pollNumber: number) => Promise<void>;
+	now?: () => number;
+	sleep?: (milliseconds: number) => Promise<void>;
+}
+
+/**
+ * Poll within a fixed budget, then perform one separately bounded
+ * reconciliation read. The final read closes the common race where work
+ * finishes during the last partial interval and the caller otherwise returns
+ * the stale pre-completion snapshot.
+ */
+export async function pollWithFinalReconciliation<T>({
+	read,
+	isTerminal,
+	budgetMs,
+	intervalMs,
+	onPoll,
+	now = Date.now,
+	sleep = (milliseconds) =>
+		new Promise<void>((resolve) => setTimeout(resolve, milliseconds)),
+}: PollOptions<T>): Promise<T> {
+	const deadline = now() + budgetMs;
+	let value = await read(deadline);
+	let pollNumber = 0;
+
+	while (!isTerminal(value)) {
+		const remainingMs = deadline - now();
+		if (remainingMs <= 0) break;
+		await onPoll?.(value, ++pollNumber);
+		await sleep(Math.min(intervalMs, remainingMs));
+		if (now() >= deadline) break;
+		value = await read(deadline);
+	}
+
+	if (!isTerminal(value)) {
+		const finalReadDeadline =
+			now() + Math.min(5_000, Math.max(1_000, intervalMs));
+		try {
+			value = await read(finalReadDeadline);
+		} catch {
+			// The normal timeout/resume contract uses the last successful state.
+		}
+	}
+
+	return value;
+}