@hubfluencer/mcp 0.9.0 → 0.10.0

package/README.md

@@ -68,7 +68,7 @@ claude mcp add hubfluencer --env HUBFLUENCER_API_TOKEN=YOUR_TOKEN -- npx -y @hub
 
 ## Tools
 
-92 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
+93 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
 below are the ground truth. **"$0" means it spends no video credits**; planning/AI-helper tools
 instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_assists`: 1 credit
 → +10). Reads need the `video:read` scope; writes need `video:generate`. Nothing here needs
@@ -80,12 +80,12 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 |---|---|---|
 | **`make_video`** | **One shot: prompt → finished MP4** (create → **price** → start → poll → download). `kind:"auto"` picks a multi-scene editor ad for ad/promo/story briefs, a short for simple ones (reported as `kind_inferred`). Pass `dry_run:true` to preview the cost without spending, or `max_credits` to cap it. | short **15**, editor ~**28** (`dry_run`/`max_credits` gate it) |
 | `create_short` | Create a short draft (12s vertical: two 6s AI segments + title overlay + music; 14s when it ends on a poster or brand-lockup end card). Set `headline` (≈4 words, ≤40 chars), `subheadline`, `music_vibe`, and an explicit `visual_language` (`kinetic_creator` is a strong default) — and **always `cta_text`** (a short without a CTA doesn't convert; blank `cta_text` → the server renders a neutral localized ask, e.g. "Learn more" — a truly CTA-less short is not currently supported). End-card fields: `closing_claim` (≤80), `brand_name` (≤40), `end_card` (`"auto"`\|`"none"`). Other opt-in conversion graphics: `offer_text`/`badge_text`/`star_rating` — only what you can substantiate. | **0** |
-| `update_short` | Patch an existing short draft — brief (`product_prompt`), copy, styling, end-card fields (`closing_claim`/`brand_name`/`poster_includes_lockup`/`end_card`), or the opt-in conversion graphics; only the fields you pass change. Clear one with `""` (`[]` for `text_beats`, `0` for `star_rating`). Apply text/style/CTA/end-card edits to a generated short free with `rerender_short`; footage/music edits need `generate_short`. | **0** |
+| `update_short` | Patch an existing short draft — brief (`product_prompt`), copy, styling, end-card fields (`closing_claim`/`brand_name`/`poster_includes_lockup`/`end_card`), logo overlay placement (`short_logo_position`/`short_logo_treatment`), or the opt-in conversion graphics; only the fields you pass change. Clear one with `""` (`[]` for `text_beats`, `0` for `star_rating`). Apply text/style/CTA/end-card/logo edits to a generated short free with `rerender_short`; footage/music edits need `generate_short`. | **0** |
 | `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 state over the already-paid footage + music. Use after `update_short` for copy/style/CTA tweaks; 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** |
+| `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 |
-| `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. | **0** quote; credits on 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_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** |
@@ -133,6 +133,7 @@ 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, ≤1 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. |
 
 ### Status & delivery
@@ -233,7 +234,7 @@ edit are **0 credits** — you only pay to generate/render.
 |---|---|
 | Any draft create / edit / reorder | 0 |
 | Short render | **15** |
-| Short re-render (`rerender_short` — text/style/CTA/end-card over existing footage) | **0** |
+| Short re-render (`rerender_short` — text/style/CTA/end-card/logo over existing footage) | **0** |
 | Editor AI scene (`generate_segment`) | **5** (4 each in a batch of ≥3) |
 | Editor scene re-roll (`regenerate_segment`, new version of a completed scene) | **4** |
 | Editor voice | **3** |
@@ -259,8 +260,9 @@ If it returns `terminal:false`, the render is still going — call `wait_for_com
 `create_editor_ad` (free configure + quote) → obtain spend approval → `start_autopilot {slug, max_credits}` → `wait_for_completion {kind:"editor"}` → `download_result`.
 
 **Iterate a short for free (never re-roll):** the first `generate_short` (15 credits) buys the footage +
-music; after that, every text/style/CTA/end-card tweak re-renders over them for **0 credits** —
-`update_short` (new hook/CTA/style) → `rerender_short` → compare → repeat → keep the winner. Only
+music; after that, every text/style/CTA/end-card/logo tweak re-renders over them for **0 credits** —
+`update_short` (new hook/CTA/style) → `rerender_short` → compare → repeat → keep the winner. Logo
+placement (`set_short_logo`, or `short_logo_position`/`short_logo_treatment`) is free too. Only
 footage/music-affecting edits (`product_prompt`, product image, `creative_format`, `visual_language`,
 `theme`, `music_vibe`, `music_instruments`, `language`) need another `generate_short`. Edits that
 add/remove the end card (poster, `end_card`) can shift the video between 12s and 14s; the pinned music

package/dist/index.js

@@ -29498,6 +29498,16 @@ function normalizeStatus(kind, slug, data) {
       video_url: videoUrl,
       error: d.error_message ?? null
     };
+    if (typeof d.failed_stage === "string")
+      status.failed_stage = d.failed_stage;
+    if (typeof d.failure_code === "string")
+      status.failure_code = d.failure_code;
+    if (d.failure_details && typeof d.failure_details === "object")
+      status.failure_details = d.failure_details;
+    if (typeof d.failure_source === "string")
+      status.failure_source = d.failure_source;
+    if (typeof d.failure_attempt === "number")
+      status.failure_attempt = d.failure_attempt;
     if (typeof d.latest_render_free === "boolean") {
       status.latest_render_free = d.latest_render_free;
     }
@@ -29558,7 +29568,7 @@ function normalizeStatus(kind, slug, data) {
   const renderFresh = latest.is_stale === false;
   const stale = renderStale || staleSegments.length > 0 || audioStale;
   const renderActive = renderStatus === "pending" || renderStatus === "rendering" || renderStatus === "processing";
-  const scenarioActive = d.scenario_status === "generating" || d.scenario_apply_status === "applying";
+  const scenarioActive = d.scenario_status === "generating" || d.scenario_apply_status === "pending" || d.scenario_apply_status === "applying";
   const narrationActive = d.narration_status === "generating";
   const scenarioFailed = d.scenario_status === "failed";
   const scenarioApplyFailed = d.scenario_apply_status === "failed";
@@ -29589,13 +29599,16 @@ function normalizeStatus(kind, slug, data) {
   ].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 workActive = autopilotActive || batchActive || renderActive || scenarioActive || narrationActive || audioActive || activeSegments.length > 0;
-  const ready = renderStatus === "completed" && Boolean(videoUrl) && renderFresh && !stale && !workActive && failedSegments.length === 0 && !audioFailed && !scenarioFailed && !scenarioApplyFailed && !narrationFailed && !batchFailed;
+  const deliveredArtifactSupersedesOrchestrationFailure = renderStatus === "completed" && Boolean(videoUrl) && renderFresh && !stale && !workActive && failedSegments.length === 0 && !audioFailed;
+  const ready = deliveredArtifactSupersedesOrchestrationFailure;
   const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
   const renderFailed = renderStatus === "failed";
-  const failed = autopilotFailed || renderFailed || scenarioApplyFailed || scenarioFailed || narrationFailed || batchFailed || failedSegments.length > 0 || audioFailed;
+  const failed = autopilotFailed && !deliveredArtifactSupersedesOrchestrationFailure || renderFailed || scenarioApplyFailed && !deliveredArtifactSupersedesOrchestrationFailure || scenarioFailed && !deliveredArtifactSupersedesOrchestrationFailure || narrationFailed && !deliveredArtifactSupersedesOrchestrationFailure || batchFailed && !deliveredArtifactSupersedesOrchestrationFailure || failedSegments.length > 0 || audioFailed;
   const terminal = ready || failed || batchInsufficientCredits || !workActive;
   let stage = autopilot;
-  if (autopilot === "failed")
+  if (ready)
+    stage = "completed";
+  else if (autopilot === "failed")
     stage = "failed";
   else if (autopilot === "cancelled")
     stage = "cancelled";
@@ -29629,8 +29642,6 @@ function normalizeStatus(kind, slug, data) {
     stage = "audio_processing";
   else if (!workActive && stale)
     stage = "editing_required";
-  else if (ready)
-    stage = "completed";
   const segmentError = failedSegments.map((segment) => segment.error_message).find((value) => typeof value === "string" && value.length > 0);
   return {
     kind,
@@ -29639,7 +29650,7 @@ function normalizeStatus(kind, slug, data) {
     terminal,
     ready,
     video_url: videoUrl,
-    error: d.autopilot_error_message ?? latest.error_message ?? d.scenario_apply_error_message ?? d.scenario_error_message ?? d.narration_error_message ?? d.batch_generation_error_message ?? segmentError ?? audioError ?? (batchInsufficientCredits ? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then resume." : null),
+    error: ready ? null : d.autopilot_error_message ?? latest.error_message ?? d.scenario_apply_error_message ?? d.scenario_error_message ?? d.narration_error_message ?? d.batch_generation_error_message ?? segmentError ?? audioError ?? (batchInsufficientCredits ? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then resume." : 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")
@@ -30232,7 +30243,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.9.0",
+  version: "0.10.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>",
@@ -30545,6 +30556,11 @@ var getStatusOutput = exports_external.object({
   stale: exports_external.boolean().optional(),
   active_segment_ids: exports_external.array(exports_external.union([exports_external.number(), exports_external.string()])).optional(),
   stale_segment_ids: exports_external.array(exports_external.union([exports_external.number(), exports_external.string()])).optional(),
+  failed_stage: exports_external.string().optional().describe("Short only: exact API failure phase behind a terminal failure."),
+  failure_code: exports_external.string().optional().describe("Short only: stable machine-readable failure classification."),
+  failure_details: exports_external.record(exports_external.string(), exports_external.unknown()).optional().describe("Short only: structured provider/QC details for recovery."),
+  failure_source: exports_external.string().optional().describe("Short only: worker/recovery layer that finalized the failure."),
+  failure_attempt: exports_external.number().optional().describe("Short only: paid generation attempt number that failed."),
   latest_render_free: exports_external.boolean().optional(),
   last_free_rerender_failed: exports_external.boolean().optional()
 }).passthrough();
@@ -30559,6 +30575,11 @@ var waitForCompletionOutput = exports_external.object({
   stale: exports_external.boolean().optional(),
   active_segment_ids: exports_external.array(exports_external.union([exports_external.number(), exports_external.string()])).optional(),
   stale_segment_ids: exports_external.array(exports_external.union([exports_external.number(), exports_external.string()])).optional(),
+  failed_stage: exports_external.string().optional().describe("Short only: exact API failure phase behind a terminal failure."),
+  failure_code: exports_external.string().optional().describe("Short only: stable machine-readable failure classification."),
+  failure_details: exports_external.record(exports_external.string(), exports_external.unknown()).optional().describe("Short only: structured provider/QC details for recovery."),
+  failure_source: exports_external.string().optional().describe("Short only: worker/recovery layer that finalized the failure."),
+  failure_attempt: exports_external.number().optional().describe("Short only: paid generation attempt number that failed."),
   latest_render_free: exports_external.boolean().optional(),
   last_free_rerender_failed: exports_external.boolean().optional(),
   saved_to: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
@@ -31102,6 +31123,7 @@ var MAX_VIDEO_BYTES = 500000000;
 var MAX_IMAGE_BYTES = 20 * 1024 * 1024;
 var MAX_PRODUCT_IMAGE_BYTES = 8 * 1024 * 1024;
 var MAX_LOGO_BYTES = 1 * 1024 * 1024;
+var MAX_SHORT_LOGO_BYTES = 5 * 1024 * 1024;
 var MAX_CLOSING_IMAGE_BYTES = 20 * 1024 * 1024;
 var MULTIPART_THRESHOLD = 50 * 1024 * 1024;
 var MAX_CATALOG_VIDEO_DURATION_SECONDS = 60;
@@ -31531,6 +31553,8 @@ async function editorAutopilotQuote(client, slug, overrides = {}) {
       params.set("product_subject", overrides.product_subject);
     if (overrides.product_prompt)
       params.set("product_prompt", overrides.product_prompt);
+    if (overrides.restart)
+      params.set("restart", "true");
     const query = params.toString();
     const response = await client.get(`/editor/${slug}/autopilot/cost${query ? `?${query}` : ""}`);
     const cost = asRecord(asRecord(response).data);
@@ -31553,6 +31577,26 @@ async function editorAutopilotQuote(client, slug, overrides = {}) {
     };
   }
 }
+async function editorChargeReceipt(client, slug, action, listPriceCredits) {
+  try {
+    const response = await client.get(`/editor/${slug}`);
+    const editor = asRecord(asRecord(response).data);
+    return {
+      action,
+      list_price_credits: listPriceCredits,
+      project_spend: editor.project_spend ?? null,
+      approved_cap: editor.autopilot_max_credits ?? null,
+      approved_run_spend: editor.autopilot_credits_spent ?? null
+    };
+  } catch {
+    return {
+      action,
+      list_price_credits: listPriceCredits,
+      project_spend: null,
+      enrichment_unavailable: true
+    };
+  }
+}
 function isRecompositeInProgressConflict(e) {
   const err = e;
   if (err?.status !== 409)
@@ -31772,7 +31816,7 @@ DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 8. RECURRING: create_series + plan_series_episodes → materialize_episode drafts each episode; get_series_dashboard shows upcoming/drafted/published lanes; mark_episode_posted closes a recurring show's loop.
 
 CREDITS (spent server-side; each tool prices before charging — see its description)
-- Free (0 credits): every draft create/edit, reorder, all slider re-composites, short re-renders (rerender_short — applies text/style/CTA/end-card edits over a short's already-paid footage), and the whole onboard/plan/pack/materialize path (steps 1-3). get_credits shows the balance.
+- Free (0 credits): every draft create/edit, reorder, all slider re-composites, short re-renders (rerender_short — applies text/style/CTA/end-card/logo edits over a short's already-paid footage), and the whole onboard/plan/pack/materialize path (steps 1-3). get_credits shows the balance.
 - Charged: short render 15; editor AI scene 5 (4 in a batch of ≥3); voice 3; music 5; editor render 0 (auto-charges ungenerated scenes); slider 1/slide; tracking render 1 (refunded on failure). make_video supports dry_run/max_credits; create_editor_ad/start_autopilot require max_credits before launching.
 - AI ASSISTS (all generate_*/enhance/suggest/plan/hook tools) draw a FREE daily quota (20/day), NOT credits. On 429, set auto_unlock:true to spend 1 credit for +10 assists (retried once), or write the copy yourself and use the set_* tools.
 
@@ -32065,7 +32109,7 @@ registerTool("list_projects", {
 }));
 registerTool("create_short", {
   title: "Create a short (draft)",
-  description: "Creates a short draft from a product prompt (min 10 chars). A short is a 12s vertical (two 6s AI " + "segments + an on-screen title overlay + music; 14s when it ends on a poster or brand-lockup end card). " + "Returns the slug, costs 0 credits. Follow with generate_short to render. Iteration is FREE after that " + "first generate: the 15 credits bought the footage + music, and every later text/style/CTA/end-card " + "tweak re-renders over them for 0 credits (update_short → rerender_short). " + "BE PROACTIVE: don't ship a bare clip — set a headline (the on-screen TITLE) and subheadline (secondary " + "title), and pick a music_vibe plus visual_language that fit the brand. " + "Always set cta_text — a short without a CTA doesn't convert (plus offer_text only if there's a real " + "deal). Note: blank cta_text → the server renders a neutral localized ask (e.g. 'Learn more'); a truly " + "CTA-less short is not currently supported. " + "Keep headline ≈4 words (≤40 chars). Set visual_language explicitly (kinetic_creator is a strong " + "default). If headline/subheadline/text_beats are left blank, the server auto-writes the headline + " + "caption beats at generate time (pass skip_auto_text:true to generate_short for a deliberately bare clip). " + "To brand it further, attach a product image " + "(set_short_product) or an end-card poster (set_short_poster) before generate_short. (Shorts have no logo " + "overlay — that's an editor-only feature; use create_editor_ad for logo branding.)",
+  description: "Creates a short draft from a product prompt (min 10 chars). A short is a 12s vertical (two 6s AI " + "segments + an on-screen title overlay + music; 14s when it ends on a poster or brand-lockup end card). " + "Returns the slug, costs 0 credits. Follow with generate_short to render. Iteration is FREE after that " + "first generate: the 15 credits bought the footage + music, and every later text/style/CTA/end-card/logo " + "tweak re-renders over them for 0 credits (update_short → rerender_short). " + "BE PROACTIVE: don't ship a bare clip — set a headline (the on-screen TITLE) and subheadline (secondary " + "title), and pick a music_vibe plus visual_language that fit the brand. " + "Always set cta_text — a short without a CTA doesn't convert (plus offer_text only if there's a real " + "deal). Note: blank cta_text → the server renders a neutral localized ask (e.g. 'Learn more'); a truly " + "CTA-less short is not currently supported. " + "Keep headline ≈4 words (≤40 chars). Set visual_language explicitly (kinetic_creator is a strong " + "default). If headline/subheadline/text_beats are left blank, the server auto-writes the headline + " + "caption beats at generate time (pass skip_auto_text:true to generate_short for a deliberately bare clip). " + "To brand it further, attach a product image " + "(set_short_product), a deterministic brand logo (set_short_logo), or an end-card poster " + "(set_short_poster) before generate_short.",
   inputSchema: {
     product_prompt: exports_external.string().min(10).describe("What the short should be about"),
     language: exports_external.enum(LANGUAGES).optional().describe('Language code, e.g. "en" (default). Bare ISO-639-1 code only — no region/script subtag like "en-US".'),
@@ -32162,7 +32206,7 @@ registerTool("create_short", {
 }));
 registerTool("update_short", {
   title: "Update a short draft (0 credits)",
-  description: "Patches an existing short draft — only the fields you pass change; omitted fields are left untouched. " + "0 credits, no re-render by itself. APPLYING the edit: changed only text/style/CTA/end-card fields " + "(headline, subheadline, text_beats, cta_text, offer_text, badge_text, star_rating, colors, font, " + "position, animation, closing_claim, brand_name, poster_includes_lockup, end_card) on an " + "already-generated short? " + "rerender_short applies them for 0 credits. Footage/music-affecting edits (product_prompt, product " + "image, creative_format, visual_language, theme, music_vibe, music_instruments, language) need " + "generate_short (15 credits) again. Use this to edit the brief, copy, " + "styling, or the optional conversion graphics after create_short. " + "Always set cta_text — a short without a CTA doesn't convert (plus offer_text only if there's a real " + "deal). Note: blank cta_text → the server renders a neutral localized ask (e.g. 'Learn more'); a truly " + "CTA-less short is not currently supported. " + "Keep headline ≈4 words (≤40 chars). Set visual_language explicitly (kinetic_creator is a strong " + "default). " + "CLEARING a field: the conversion graphics (offer_text, cta_text, badge_text, star_rating) and " + 'text_beats are OPT-IN and OFF by default — pass "" (or 0 for star_rating, [] for text_beats) to REMOVE ' + "one that was set. The four conversion graphics are user-supplied only and never written by the AI copy " + "assist; text_beats (like headline/subheadline) IS rewritten by generate_short_text, so hand-crafted " + "beats don't survive a later assist call. " + "404 for an unknown/foreign slug.",
+  description: "Patches an existing short draft — only the fields you pass change; omitted fields are left untouched. " + "0 credits, no re-render by itself. APPLYING the edit: changed only text/style/CTA/end-card/logo fields " + "(headline, subheadline, text_beats, cta_text, offer_text, badge_text, star_rating, colors, font, " + "position, animation, closing_claim, brand_name, poster_includes_lockup, end_card, short_logo_position, " + "short_logo_treatment) on an " + "already-generated short? " + "rerender_short applies them for 0 credits. Footage/music-affecting edits (product_prompt, product " + "image, creative_format, visual_language, theme, music_vibe, music_instruments, language) need " + "generate_short (15 credits) again. Use this to edit the brief, copy, " + "styling, or the optional conversion graphics after create_short. " + "Always set cta_text — a short without a CTA doesn't convert (plus offer_text only if there's a real " + "deal). Note: blank cta_text → the server renders a neutral localized ask (e.g. 'Learn more'); a truly " + "CTA-less short is not currently supported. " + "Keep headline ≈4 words (≤40 chars). Set visual_language explicitly (kinetic_creator is a strong " + "default). " + "CLEARING a field: the conversion graphics (offer_text, cta_text, badge_text, star_rating) and " + 'text_beats are OPT-IN and OFF by default — pass "" (or 0 for star_rating, [] for text_beats) to REMOVE ' + "one that was set. The four conversion graphics are user-supplied only and never written by the AI copy " + "assist; text_beats (like headline/subheadline) IS rewritten by generate_short_text, so hand-crafted " + "beats don't survive a later assist call. " + "404 for an unknown/foreign slug.",
   inputSchema: {
     slug: exports_external.string().describe("Short slug (from create_short)"),
     product_prompt: exports_external.string().min(10).optional().describe("Rewrite the brief (what the short is about, ≥10 chars); drives the next generate_short."),
@@ -32198,6 +32242,8 @@ 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_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.")
   },
   annotations: {
@@ -32255,13 +32301,17 @@ registerTool("update_short", {
     body.end_card = args.end_card;
   if (args.poster_includes_lockup !== undefined)
     body.poster_includes_lockup = args.poster_includes_lockup;
+  if (args.short_logo_position !== undefined)
+    body.short_logo_position = args.short_logo_position;
+  if (args.short_logo_treatment !== undefined)
+    body.short_logo_treatment = args.short_logo_treatment;
   if (args.brand_profile_id !== undefined)
     body.brand_profile_id = args.brand_profile_id;
   const res = await client.patch(`/shorts/${args.slug}`, body);
   const data = asRecord(res).data ?? res;
   return ok({
     ...asRecord(data),
-    next: "Saved. Only text/style/CTA/end-card changed on an already-generated short? " + `rerender_short({ slug: "${args.slug}" }) applies it for 0 credits. Footage/music edits ` + "(prompt, product image, format, visual_language, theme, music_*, language) need " + "generate_short (15 credits)."
+    next: "Saved. Only text/style/CTA/end-card/logo changed on an already-generated short? " + `rerender_short({ slug: "${args.slug}" }) applies it for 0 credits. Footage/music edits ` + "(prompt, product image, format, visual_language, theme, music_*, language) need " + "generate_short (15 credits)."
   });
 }));
 async function getTracking(client, slug, deadline) {
@@ -32430,7 +32480,7 @@ registerTool("generate_short", {
 }));
 registerTool("rerender_short", {
   title: "Re-render a short (FREE — 0 credits)",
-  description: "FREE re-render: applies the short's current text/style/CTA/end-card state over the already-paid " + "footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks. Footage or music " + "changes need generate_short (15 credits) instead. Edits that add/remove the end card (poster, " + "end_card) can shift the video between 12s and 14s; when the pinned music bed is shorter than the " + "export it crossfades into a repeated continuation, then fades at the export end, without regeneration. " + "Requires a completed generation to re-render over " + "(422 short_not_ready otherwise — run generate_short once first); while any generation/render is in " + "flight it reports in-progress (409) rather than duplicating. Then poll with get_status or " + "wait_for_completion (kind=short). A failed free re-render leaves the delivered video intact — retry " + "rerender_short, it stays free (the status fields latest_render_free / last_free_rerender_failed " + "report this when the server sends them).",
+  description: "FREE re-render: applies the short's current text/style/CTA/end-card/logo state over the already-paid " + "footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks, or after a logo change " + "(set_short_logo, or short_logo_position/short_logo_treatment via update_short). Footage or music " + "changes need generate_short (15 credits) instead. Edits that add/remove the end card (poster, " + "end_card) can shift the video between 12s and 14s; when the pinned music bed is shorter than the " + "export it crossfades into a repeated continuation, then fades at the export end, without regeneration. " + "Requires a completed generation to re-render over " + "(422 short_not_ready otherwise — run generate_short once first); while any generation/render is in " + "flight it reports in-progress (409) rather than duplicating. Then poll with get_status or " + "wait_for_completion (kind=short). A failed free re-render leaves the delivered video intact — retry " + "rerender_short, it stays free (the status fields latest_render_free / last_free_rerender_failed " + "report this when the server sends them).",
   inputSchema: {
     slug: exports_external.string().describe("Short slug (from create_short)")
   },
@@ -32805,13 +32855,14 @@ registerTool("create_editor_ad", {
 }));
 registerTool("start_autopilot", {
   title: "Start autopilot on an existing editor draft",
-  description: "Starts server-orchestrated autopilot (scenario → segments → narration → voice → music → render) on an " + "EXISTING editor project/draft. Without max_credits it returns the live quote and charges nothing. Supply an " + "explicit max_credits cap to authorize launch; the tool refuses if pricing is unavailable, the estimate exceeds " + "the cap, or the balance is insufficient. Each authorized call is a genuine start attempt (like tapping Launch in the app): " + "if a run is already in progress for this slug the server returns already_running — it never double-starts " + "or double-charges. Once finished, failed, or cancelled, calling again relaunches it (resume after a top-up, raising your spend cap, or a mid-pipeline failure). Then poll with " + 'wait_for_completion({ slug, kind: "editor" }).',
+  description: "Starts server-orchestrated autopilot (scenario → segments → narration → voice → music → render) on an " + "EXISTING editor project/draft. Without max_credits it returns the live quote and charges nothing. Supply an " + "explicit max_credits cap to authorize launch; the tool refuses if pricing is unavailable, the estimate exceeds " + "the cap, or the balance is insufficient. Each authorized call is a genuine start attempt (like tapping Launch in the app): " + "if a run is already in progress for this slug the server returns already_running — it never double-starts " + "or double-charges. Failed or cancelled runs resume normally. For a completed project, set restart:true to quote and build a fresh creative run; omitting it only resumes pending edits. Then poll with " + 'wait_for_completion({ slug, kind: "editor" }).',
   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."),
-    max_credits: exports_external.number().int().nonnegative().optional().describe("Explicit spend cap. Omit to quote only; no credits are charged.")
+    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.")
   },
   outputSchema: createEditorOutput,
   annotations: { title: "Start autopilot", ...WRITE, idempotentHint: false }
@@ -32830,6 +32881,8 @@ registerTool("start_autopilot", {
     overrides.product_subject = args.product_subject;
   if (args.product_prompt !== undefined)
     overrides.product_prompt = args.product_prompt;
+  if (args.restart)
+    overrides.restart = true;
   const quote = await editorAutopilotQuote(client, slug, overrides);
   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) {
@@ -33110,7 +33163,10 @@ registerTool("regenerate_segment", {
   }
 }, tool(async (args, client) => {
   const res = await client.post(`/editor/${args.slug}/segments/${String(args.segment_id)}/regenerate`, args.prompt !== undefined ? { prompt: args.prompt } : undefined, undefined);
-  return ok(asRecord(res).data ?? res);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    charge_receipt: await editorChargeReceipt(client, args.slug, "scene_regeneration", 4)
+  });
 }));
 registerTool("generate_all_segments", {
   title: "Generate all pending segments (sequential)",
@@ -33227,7 +33283,10 @@ registerTool("generate_voice", {
   annotations: { title: "Generate voice", ...WRITE, idempotentHint: true }
 }, tool(async (args, client) => {
   const res = await client.post(`/editor/${args.slug}/generate-voice`, { voice_id: args.voice_id }, await voiceKey(client, args.slug, args.voice_id));
-  return ok(asRecord(res).data ?? res);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    charge_receipt: await editorChargeReceipt(client, args.slug, "voice_generation", 3)
+  });
 }));
 registerTool("generate_music", {
   title: "Generate the background music (5 credits)",
@@ -33254,11 +33313,14 @@ registerTool("generate_music", {
   if (args.instruments !== undefined)
     body.instruments = args.instruments;
   const res = await client.post(`/editor/${args.slug}/generate-music`, body, undefined);
-  return ok(asRecord(res).data ?? res);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    charge_receipt: await editorChargeReceipt(client, args.slug, "music_generation", 5)
+  });
 }));
 registerTool("render", {
   title: "Render the final editor video (0 credits)",
-  description: "Renders the final MP4 from the generated segments + voice + music. Costs 0 credits (any still-ungenerated " + "segments are auto-charged at generation cost first). Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " + 'pair with wait_for_completion({ slug, kind: "editor" }) then download_result. ' + "STALENESS: editing the scenario or narration AFTER generating voice/music marks those audio tracks stale, and render then 422s with editor_narration_stale / editor_voice_stale / editor_music_stale — regenerate the named track (generate_narration → generate_voice, and/or generate_music) before rendering.",
+  description: "Renders the final MP4 from the generated segments + voice + music. Costs 0 credits (any still-ungenerated " + "segments are auto-charged at generation cost first). Render NEVER generates or charges for voice/music; a new " + "music charge comes only from generate_music or an already-running autopilot child job. Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " + 'pair with wait_for_completion({ slug, kind: "editor" }) then download_result. ' + "STALENESS: editing the scenario or narration AFTER generating voice/music marks those audio tracks stale, and render then 422s with editor_narration_stale / editor_voice_stale / editor_music_stale — regenerate the named track (generate_narration → generate_voice, and/or generate_music) before rendering.",
   inputSchema: { slug: exports_external.string().describe("Editor project slug") },
   annotations: { title: "Render", ...WRITE, idempotentHint: false }
 }, tool(async (args, client) => {
@@ -33598,9 +33660,28 @@ registerTool("set_short_product", {
   const res = await client.post(`/shorts/${args.slug}/product/confirm`, { s3_key, product_description: args.description });
   return ok(asRecord(res).data ?? res);
 }));
+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.",
+  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)")
+  },
+  annotations: { title: "Set Short logo", ...WRITE, idempotentHint: false }
+}, tool(async (args, client) => {
+  const { s3_key } = await uploadImageFile(client, `/shorts/${args.slug}/logo/presign`, args.file_path, MAX_SHORT_LOGO_BYTES);
+  const res = await client.post(`/shorts/${args.slug}/logo/confirm`, {
+    s3_key,
+    position: args.position ?? "top-right",
+    treatment: args.treatment ?? "throughout"
+  });
+  return ok(asRecord(res).data ?? res);
+}));
 registerTool("set_short_poster", {
   title: "Set a short's end-card poster image (0 credits)",
-  description: "Uploads a local image as the SHORT's end-card poster — a closing still shown at the end (extends the " + "render from 12s to 14s). Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤20 MiB = 20,971,520 bytes), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " + "again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
+  description: "Uploads a local image as the SHORT's end-card poster — a closing still shown at the end (extends the " + "render from 12s to 14s). Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤20 MiB = 20,971,520 bytes), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " + "again replaces it. Use set_short_logo for an exact, non-generative brand overlay.",
   inputSchema: {
     slug: exports_external.string().describe("Short slug (from create_short)"),
     file_path: exports_external.string().describe("Local poster image (.jpg/.jpeg/.png)"),

package/package.json

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

@@ -265,6 +265,16 @@ export interface NormalizedStatus {
 	ready: boolean;
 	video_url: string | null;
 	error: string | null;
+	/** Short only: exact API failure phase instead of a collapsed terminal state. */
+	failed_stage?: string;
+	/** Short only: stable machine-readable terminal failure classification. */
+	failure_code?: string;
+	/** Short only: structured provider/QC details for recovery decisions. */
+	failure_details?: Record<string, unknown>;
+	/** Short only: worker/recovery layer that finalized the failed attempt. */
+	failure_source?: string;
+	/** Short only: paid generation attempt number that failed. */
+	failure_attempt?: number;
 	/** Editor only: the newest delivered render no longer matches the live project. */
 	stale?: boolean;
 	/** Editor only: current scene ids that are still generating. */
@@ -341,6 +351,16 @@ export function normalizeStatus(
 			video_url: videoUrl,
 			error: (d.error_message as string) ?? null,
 		};
+		if (typeof d.failed_stage === "string")
+			status.failed_stage = d.failed_stage;
+		if (typeof d.failure_code === "string")
+			status.failure_code = d.failure_code;
+		if (d.failure_details && typeof d.failure_details === "object")
+			status.failure_details = d.failure_details as Record<string, unknown>;
+		if (typeof d.failure_source === "string")
+			status.failure_source = d.failure_source;
+		if (typeof d.failure_attempt === "number")
+			status.failure_attempt = d.failure_attempt;
 		// Additive free-re-render bookkeeping (2026-07 API): surfaced only when
 		// the server actually sends the booleans, so older payloads normalize
 		// byte-identically. A failed free re-render does NOT flip stage to
@@ -477,10 +497,11 @@ export function normalizeStatus(
 		renderStatus === "processing";
 	// Scenario text generation / scenario apply run as async workers too
 	// (scenario_status: none|generating|ready|failed; scenario_apply_status:
-	// idle|applying|failed) — count them as active so a wait right after
+	// idle|pending|applying|failed) — count them as active so a wait right after
 	// generate_scenario/apply_scenario doesn't bail out as an "idle" draft.
 	const scenarioActive =
 		d.scenario_status === "generating" ||
+		d.scenario_apply_status === "pending" ||
 		d.scenario_apply_status === "applying";
 	// Narration generation is a distinct async worker that runs before an
 	// AudioVersion exists. Without this gate, a project with an older completed
@@ -553,27 +574,27 @@ export function normalizeStatus(
 		narrationActive ||
 		audioActive ||
 		activeSegments.length > 0;
-	const ready =
+	// Orchestration failures are historical once a repaired timeline has a fresh,
+	// completed MP4. Keeping them terminal would permanently block download_result
+	// after a successful granular recovery.
+	const deliveredArtifactSupersedesOrchestrationFailure =
 		renderStatus === "completed" &&
 		Boolean(videoUrl) &&
 		renderFresh &&
 		!stale &&
 		!workActive &&
 		failedSegments.length === 0 &&
-		!audioFailed &&
-		!scenarioFailed &&
-		!scenarioApplyFailed &&
-		!narrationFailed &&
-		!batchFailed;
+		!audioFailed;
+	const ready = deliveredArtifactSupersedesOrchestrationFailure;
 	const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
 	const renderFailed = renderStatus === "failed";
 	const failed =
-		autopilotFailed ||
+		(autopilotFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
 		renderFailed ||
-		scenarioApplyFailed ||
-		scenarioFailed ||
-		narrationFailed ||
-		batchFailed ||
+		(scenarioApplyFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
+		(scenarioFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
+		(narrationFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
+		(batchFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
 		failedSegments.length > 0 ||
 		audioFailed;
 	// Terminal = control should return to the agent because nothing will progress
@@ -589,7 +610,8 @@ export function normalizeStatus(
 	// Failure always wins over an unrelated active flag. Workers can leave an
 	// outer autopilot/batch state active after a child stage has failed; reporting
 	// the active stage would make agents poll forever instead of taking action.
-	if (autopilot === "failed") stage = "failed";
+	if (ready) stage = "completed";
+	else if (autopilot === "failed") stage = "failed";
 	else if (autopilot === "cancelled") stage = "cancelled";
 	else if (renderFailed) stage = "render_failed";
 	else if (scenarioApplyFailed) stage = "scenario_apply_failed";
@@ -606,7 +628,6 @@ export function normalizeStatus(
 	else if (narrationActive) stage = "narration_processing";
 	else if (audioActive) stage = "audio_processing";
 	else if (!workActive && stale) stage = "editing_required";
-	else if (ready) stage = "completed";
 	const segmentError = failedSegments
 		.map((segment) => segment.error_message)
 		.find(
@@ -619,18 +640,19 @@ export function normalizeStatus(
 		terminal,
 		ready,
 		video_url: videoUrl,
-		error:
-			(d.autopilot_error_message as string) ??
-			(latest.error_message as string) ??
-			(d.scenario_apply_error_message as string) ??
-			(d.scenario_error_message as string) ??
-			(d.narration_error_message as string) ??
-			(d.batch_generation_error_message as string) ??
-			segmentError ??
-			audioError ??
-			(batchInsufficientCredits
-				? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then resume."
-				: null),
+		error: ready
+			? null
+			: ((d.autopilot_error_message as string) ??
+				(latest.error_message as string) ??
+				(d.scenario_apply_error_message as string) ??
+				(d.scenario_error_message as string) ??
+				(d.narration_error_message as string) ??
+				(d.batch_generation_error_message as string) ??
+				segmentError ??
+				audioError ??
+				(batchInsufficientCredits
+					? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then resume."
+					: null)),
 		stale,
 		active_segment_ids: activeSegments
 			.map((segment) => segment.id)

package/src/index.ts

@@ -121,6 +121,7 @@ import {
 	MAX_CLOSING_IMAGE_BYTES,
 	MAX_LOGO_BYTES,
 	MAX_PRODUCT_IMAGE_BYTES,
+	MAX_SHORT_LOGO_BYTES,
 	type PreparedUploadFile,
 	preparedUploadIdentity,
 	prepareImageUpload,
@@ -160,6 +161,7 @@ async function editorAutopilotQuote(
 		language?: string;
 		product_subject?: string;
 		product_prompt?: string;
+		restart?: boolean;
 	} = {},
 ): Promise<{
 	estimated_credits: number | null;
@@ -173,6 +175,7 @@ async function editorAutopilotQuote(
 			params.set("product_subject", overrides.product_subject);
 		if (overrides.product_prompt)
 			params.set("product_prompt", overrides.product_prompt);
+		if (overrides.restart) params.set("restart", "true");
 		const query = params.toString();
 		const response = await client.get<{ data: unknown }>(
 			`/editor/${slug}/autopilot/cost${query ? `?${query}` : ""}`,
@@ -215,6 +218,34 @@ async function editorAutopilotQuote(
 	}
 }
 
+async function editorChargeReceipt(
+	client: HubfluencerClient,
+	slug: string,
+	action: "scene_regeneration" | "voice_generation" | "music_generation",
+	listPriceCredits: number,
+): Promise<Record<string, unknown>> {
+	try {
+		const response = await client.get<{ data: unknown }>(`/editor/${slug}`);
+		const editor = asRecord(asRecord(response).data);
+		return {
+			action,
+			list_price_credits: listPriceCredits,
+			project_spend: editor.project_spend ?? null,
+			approved_cap: editor.autopilot_max_credits ?? null,
+			approved_run_spend: editor.autopilot_credits_spent ?? null,
+		};
+	} catch {
+		// The paid mutation already succeeded. Never make a receipt-enrichment GET
+		// look like a failed charge that an agent should retry.
+		return {
+			action,
+			list_price_credits: listPriceCredits,
+			project_spend: null,
+			enrichment_unavailable: true,
+		};
+	}
+}
+
 function isRecompositeInProgressConflict(e: unknown): boolean {
 	const err = e as Partial<HubfluencerError>;
 	if (err?.status !== 409) return false;
@@ -584,7 +615,7 @@ DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 8. RECURRING: create_series + plan_series_episodes → materialize_episode drafts each episode; get_series_dashboard shows upcoming/drafted/published lanes; mark_episode_posted closes a recurring show's loop.
 
 CREDITS (spent server-side; each tool prices before charging — see its description)
-- Free (0 credits): every draft create/edit, reorder, all slider re-composites, short re-renders (rerender_short — applies text/style/CTA/end-card edits over a short's already-paid footage), and the whole onboard/plan/pack/materialize path (steps 1-3). get_credits shows the balance.
+- Free (0 credits): every draft create/edit, reorder, all slider re-composites, short re-renders (rerender_short — applies text/style/CTA/end-card/logo edits over a short's already-paid footage), and the whole onboard/plan/pack/materialize path (steps 1-3). get_credits shows the balance.
 - Charged: short render 15; editor AI scene 5 (4 in a batch of ≥3); voice 3; music 5; editor render 0 (auto-charges ungenerated scenes); slider 1/slide; tracking render 1 (refunded on failure). make_video supports dry_run/max_credits; create_editor_ad/start_autopilot require max_credits before launching.
 - AI ASSISTS (all generate_*/enhance/suggest/plan/hook tools) draw a FREE daily quota (20/day), NOT credits. On 429, set auto_unlock:true to spend 1 credit for +10 assists (retried once), or write the copy yourself and use the set_* tools.
 
@@ -1406,7 +1437,7 @@ registerTool(
 			"Creates a short draft from a product prompt (min 10 chars). A short is a 12s vertical (two 6s AI " +
 			"segments + an on-screen title overlay + music; 14s when it ends on a poster or brand-lockup end card). " +
 			"Returns the slug, costs 0 credits. Follow with generate_short to render. Iteration is FREE after that " +
-			"first generate: the 15 credits bought the footage + music, and every later text/style/CTA/end-card " +
+			"first generate: the 15 credits bought the footage + music, and every later text/style/CTA/end-card/logo " +
 			"tweak re-renders over them for 0 credits (update_short → rerender_short). " +
 			"BE PROACTIVE: don't ship a bare clip — set a headline (the on-screen TITLE) and subheadline (secondary " +
 			"title), and pick a music_vibe plus visual_language that fit the brand. " +
@@ -1417,8 +1448,8 @@ registerTool(
 			"default). If headline/subheadline/text_beats are left blank, the server auto-writes the headline + " +
 			"caption beats at generate time (pass skip_auto_text:true to generate_short for a deliberately bare clip). " +
 			"To brand it further, attach a product image " +
-			"(set_short_product) or an end-card poster (set_short_poster) before generate_short. (Shorts have no logo " +
-			"overlay — that's an editor-only feature; use create_editor_ad for logo branding.)",
+			"(set_short_product), a deterministic brand logo (set_short_logo), or an end-card poster " +
+			"(set_short_poster) before generate_short.",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -1706,9 +1737,10 @@ registerTool(
 		title: "Update a short draft (0 credits)",
 		description:
 			"Patches an existing short draft — only the fields you pass change; omitted fields are left untouched. " +
-			"0 credits, no re-render by itself. APPLYING the edit: changed only text/style/CTA/end-card fields " +
+			"0 credits, no re-render by itself. APPLYING the edit: changed only text/style/CTA/end-card/logo fields " +
 			"(headline, subheadline, text_beats, cta_text, offer_text, badge_text, star_rating, colors, font, " +
-			"position, animation, closing_claim, brand_name, poster_includes_lockup, end_card) on an " +
+			"position, animation, closing_claim, brand_name, poster_includes_lockup, end_card, short_logo_position, " +
+			"short_logo_treatment) on an " +
 			"already-generated short? " +
 			"rerender_short applies them for 0 credits. Footage/music-affecting edits (product_prompt, product " +
 			"image, creative_format, visual_language, theme, music_vibe, music_instruments, language) need " +
@@ -1892,6 +1924,20 @@ registerTool(
 					"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: z
+				.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_treatment: z
+				.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: z
 				.number()
 				.int()
@@ -1937,6 +1983,12 @@ registerTool(
 				brand_name?: string;
 				end_card?: string;
 				poster_includes_lockup?: boolean;
+				short_logo_position?:
+					| "top-left"
+					| "top-right"
+					| "bottom-left"
+					| "bottom-right";
+				short_logo_treatment?: "throughout" | "end_card" | "none";
 				brand_profile_id?: number;
 			},
 			client,
@@ -1983,6 +2035,13 @@ registerTool(
 			if (args.end_card !== undefined) body.end_card = args.end_card;
 			if (args.poster_includes_lockup !== undefined)
 				body.poster_includes_lockup = args.poster_includes_lockup;
+			// Logo overlay placement — the API maps these body keys straight onto the
+			// factory (short_logo_position/short_logo_treatment). They're excluded from
+			// the paid-inputs snapshot, so a corner/treatment change is a FREE re-render.
+			if (args.short_logo_position !== undefined)
+				body.short_logo_position = args.short_logo_position;
+			if (args.short_logo_treatment !== undefined)
+				body.short_logo_treatment = args.short_logo_treatment;
 			if (args.brand_profile_id !== undefined)
 				body.brand_profile_id = args.brand_profile_id;
 
@@ -1994,7 +2053,7 @@ registerTool(
 			return ok({
 				...asRecord(data),
 				next:
-					"Saved. Only text/style/CTA/end-card changed on an already-generated short? " +
+					"Saved. Only text/style/CTA/end-card/logo changed on an already-generated short? " +
 					`rerender_short({ slug: "${args.slug}" }) applies it for 0 credits. Footage/music edits ` +
 					"(prompt, product image, format, visual_language, theme, music_*, language) need " +
 					"generate_short (15 credits).",
@@ -2434,8 +2493,9 @@ registerTool(
 	{
 		title: "Re-render a short (FREE — 0 credits)",
 		description:
-			"FREE re-render: applies the short's current text/style/CTA/end-card state over the already-paid " +
-			"footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks. Footage or music " +
+			"FREE re-render: applies the short's current text/style/CTA/end-card/logo state over the already-paid " +
+			"footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks, or after a logo change " +
+			"(set_short_logo, or short_logo_position/short_logo_treatment via update_short). Footage or music " +
 			"changes need generate_short (15 credits) instead. Edits that add/remove the end card (poster, " +
 			"end_card) can shift the video between 12s and 14s; when the pinned music bed is shorter than the " +
 			"export it crossfades into a repeated continuation, then fades at the export end, without regeneration. " +
@@ -3278,7 +3338,7 @@ registerTool(
 			"explicit max_credits cap to authorize launch; the tool refuses if pricing is unavailable, the estimate exceeds " +
 			"the cap, or the balance is insufficient. Each authorized call is a genuine start attempt (like tapping Launch in the app): " +
 			"if a run is already in progress for this slug the server returns already_running — it never double-starts " +
-			"or double-charges. Once finished, failed, or cancelled, calling again relaunches it (resume after a top-up, raising your spend cap, or a mid-pipeline failure). Then poll with " +
+			"or double-charges. Failed or cancelled runs resume normally. For a completed project, set restart:true to quote and build a fresh creative run; omitting it only resumes pending edits. Then poll with " +
 			'wait_for_completion({ slug, kind: "editor" }).',
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
@@ -3309,6 +3369,12 @@ registerTool(
 				.describe(
 					"Explicit spend cap. Omit to quote only; no credits are charged.",
 				),
+			restart: z
+				.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.",
+				),
 		},
 		outputSchema: createEditorOutput,
 		annotations: { title: "Start autopilot", ...WRITE, idempotentHint: false },
@@ -3321,6 +3387,7 @@ registerTool(
 				product_subject?: string;
 				product_prompt?: string;
 				max_credits?: number;
+				restart?: boolean;
 			},
 			client,
 		) => {
@@ -3334,12 +3401,14 @@ registerTool(
 				language?: string;
 				product_subject?: string;
 				product_prompt?: string;
+				restart?: boolean;
 			} = {};
 			if (args.language !== undefined) overrides.language = args.language;
 			if (args.product_subject !== undefined)
 				overrides.product_subject = args.product_subject;
 			if (args.product_prompt !== undefined)
 				overrides.product_prompt = args.product_prompt;
+			if (args.restart) overrides.restart = true;
 
 			const quote = await editorAutopilotQuote(client, slug, overrides);
 			const overCap =
@@ -4021,7 +4090,15 @@ registerTool(
 				args.prompt !== undefined ? { prompt: args.prompt } : undefined,
 				undefined,
 			);
-			return ok(asRecord(res).data ?? res);
+			return ok({
+				...asRecord(asRecord(res).data ?? res),
+				charge_receipt: await editorChargeReceipt(
+					client,
+					args.slug,
+					"scene_regeneration",
+					4,
+				),
+			});
 		},
 	),
 );
@@ -4230,7 +4307,15 @@ registerTool(
 			{ voice_id: args.voice_id },
 			await voiceKey(client, args.slug, args.voice_id),
 		);
-		return ok(asRecord(res).data ?? res);
+		return ok({
+			...asRecord(asRecord(res).data ?? res),
+			charge_receipt: await editorChargeReceipt(
+				client,
+				args.slug,
+				"voice_generation",
+				3,
+			),
+		});
 	}),
 );
 
@@ -4278,7 +4363,15 @@ registerTool(
 				body,
 				undefined,
 			);
-			return ok(asRecord(res).data ?? res);
+			return ok({
+				...asRecord(asRecord(res).data ?? res),
+				charge_receipt: await editorChargeReceipt(
+					client,
+					args.slug,
+					"music_generation",
+					5,
+				),
+			});
 		},
 	),
 );
@@ -4289,7 +4382,8 @@ registerTool(
 		title: "Render the final editor video (0 credits)",
 		description:
 			"Renders the final MP4 from the generated segments + voice + music. Costs 0 credits (any still-ungenerated " +
-			"segments are auto-charged at generation cost first). Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " +
+			"segments are auto-charged at generation cost first). Render NEVER generates or charges for voice/music; a new " +
+			"music charge comes only from generate_music or an already-running autopilot child job. Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " +
 			'pair with wait_for_completion({ slug, kind: "editor" }) then download_result. ' +
 			"STALENESS: editing the scenario or narration AFTER generating voice/music marks those audio tracks stale, and render then 422s with editor_narration_stale / editor_voice_stale / editor_music_stale — regenerate the named track (generate_narration → generate_voice, and/or generate_music) before rendering.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
@@ -4979,11 +5073,11 @@ registerTool(
 	),
 );
 
-// ── Shorts: branding images (product + end-card poster) ──────────────────────
+// ── Shorts: branding images (product + logo + end-card poster) ───────────────
 //
 // The editor branding tools above hit /editor/...; these hit /shorts/... A short
-// has no logo overlay (editor-only), but it CAN feature a product image woven
-// into the footage and a closing end-card poster. Both are 0 credits.
+// Product images are woven into AI footage; logos are deterministic Forge
+// overlays; posters are closing cards. All are 0 credits.
 
 registerTool(
 	"set_short_product",
@@ -5032,6 +5126,57 @@ registerTool(
 	),
 );
 
+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.",
+		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)"),
+			treatment: z
+				.enum(["throughout", "end_card", "none"])
+				.optional()
+				.describe("When the logo appears (default throughout)"),
+		},
+		annotations: { title: "Set Short logo", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				file_path: string;
+				position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+				treatment?: "throughout" | "end_card" | "none";
+			},
+			client,
+		) => {
+			const { s3_key } = await uploadImageFile(
+				client,
+				`/shorts/${args.slug}/logo/presign`,
+				args.file_path,
+				MAX_SHORT_LOGO_BYTES,
+			);
+			const res = await client.post<{ data: unknown }>(
+				`/shorts/${args.slug}/logo/confirm`,
+				{
+					s3_key,
+					position: args.position ?? "top-right",
+					treatment: args.treatment ?? "throughout",
+				},
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
 registerTool(
 	"set_short_poster",
 	{
@@ -5041,7 +5186,7 @@ registerTool(
 			"render from 12s to 14s). Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
 			" (≤20 MiB = 20,971,520 bytes), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " +
-			"again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
+			"again replaces it. Use set_short_logo for an exact, non-generative brand overlay.",
 		inputSchema: {
 			slug: z.string().describe("Short slug (from create_short)"),
 			file_path: z.string().describe("Local poster image (.jpg/.jpeg/.png)"),

package/src/output-schemas.ts

@@ -65,8 +65,32 @@ export const getStatusOutput = z
 		stale: z.boolean().optional(),
 		active_segment_ids: z.array(z.union([z.number(), z.string()])).optional(),
 		stale_segment_ids: z.array(z.union([z.number(), z.string()])).optional(),
-		// Short only, additive (normalizeStatus forwards them gated on typeof
-		// boolean, so the precise type can never reject a payload).
+		// Short only, additive (normalizeStatus forwards each gated on its typeof,
+		// so the precise type can never reject a payload).
+		failed_stage: z
+			.string()
+			.optional()
+			.describe(
+				"Short only: exact API failure phase behind a terminal failure.",
+			),
+		failure_code: z
+			.string()
+			.optional()
+			.describe("Short only: stable machine-readable failure classification."),
+		failure_details: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe("Short only: structured provider/QC details for recovery."),
+		failure_source: z
+			.string()
+			.optional()
+			.describe(
+				"Short only: worker/recovery layer that finalized the failure.",
+			),
+		failure_attempt: z
+			.number()
+			.optional()
+			.describe("Short only: paid generation attempt number that failed."),
 		latest_render_free: z.boolean().optional(),
 		last_free_rerender_failed: z.boolean().optional(),
 	})
@@ -85,6 +109,31 @@ export const waitForCompletionOutput = z
 		stale: z.boolean().optional(),
 		active_segment_ids: z.array(z.union([z.number(), z.string()])).optional(),
 		stale_segment_ids: z.array(z.union([z.number(), z.string()])).optional(),
+		// Short only, additive — mirrors getStatusOutput (see there).
+		failed_stage: z
+			.string()
+			.optional()
+			.describe(
+				"Short only: exact API failure phase behind a terminal failure.",
+			),
+		failure_code: z
+			.string()
+			.optional()
+			.describe("Short only: stable machine-readable failure classification."),
+		failure_details: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe("Short only: structured provider/QC details for recovery."),
+		failure_source: z
+			.string()
+			.optional()
+			.describe(
+				"Short only: worker/recovery layer that finalized the failure.",
+			),
+		failure_attempt: z
+			.number()
+			.optional()
+			.describe("Short only: paid generation attempt number that failed."),
 		latest_render_free: z.boolean().optional(),
 		last_free_rerender_failed: z.boolean().optional(),
 		saved_to: z.union([z.string(), z.null()]).optional(),

package/src/uploads.ts

@@ -64,6 +64,7 @@ const MAX_VIDEO_BYTES = 500_000_000; // EditorUpload.@max_upload_bytes
 const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
 export const MAX_PRODUCT_IMAGE_BYTES = 8 * 1024 * 1024;
 export const MAX_LOGO_BYTES = 1 * 1024 * 1024; // Editor.Logo.@max_logo_bytes
+export const MAX_SHORT_LOGO_BYTES = 5 * 1024 * 1024;
 export const MAX_CLOSING_IMAGE_BYTES = 20 * 1024 * 1024;
 const MULTIPART_THRESHOLD = 50 * 1024 * 1024; // @multipart_min_size — at/above this, use multipart
 const MAX_CATALOG_VIDEO_DURATION_SECONDS = 60; // CatalogAsset video validator