@hubfluencer/mcp 0.9.1 → 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,9 +80,9 @@ 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. 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 |
@@ -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;
     }
@@ -30233,7 +30243,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.9.1",
+  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>",
@@ -30546,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();
@@ -30560,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(),
@@ -31103,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;
@@ -31795,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.
 
@@ -32088,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".'),
@@ -32185,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."),
@@ -32221,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: {
@@ -32278,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) {
@@ -32453,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)")
   },
@@ -33633,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.1",
+  "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

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,
@@ -614,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.
 
@@ -1436,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. " +
@@ -1447,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()
@@ -1736,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 " +
@@ -1922,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()
@@ -1967,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,
@@ -2013,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;
 
@@ -2024,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).",
@@ -2464,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. " +
@@ -5043,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",
@@ -5096,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",
 	{
@@ -5105,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