@hubfluencer/mcp 0.9.1 → 0.11.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
+95 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,14 @@ 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 |
+| `retry_editor_batch` | Recover `batch_retry_required` by atomically re-queueing the failed scene and resuming its prepaid batch. If the parent Autopilot run is terminal, quote/relaunch it separately afterward. | **0 additional** |
+| `cancel_editor_batch` | Cancel an awaiting/running/paused editor batch. Destructive after scene dispatch: prepaid credits are not refunded (an awaiting-preview batch is refunded server-side). | **0 additional** |
 | `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** |
@@ -98,7 +100,7 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | Tool | What it does | Cost |
 |---|---|---|
 | `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme` / `cast_mode` (`product_only` needs `set_product` before generation; `presenter_led` needs a configured presenter). | **0** |
-| `get_editor` | Full project state (scenario, segments, narration, music, latest render, quota) — the review step. | **0** |
+| `get_editor` | Full project state by default for compatibility; pass `response_format:"concise"` for a smaller review projection. | **0** |
 | `set_scenario` / `generate_scenario` | Write your own scenario (free) **or** AI-draft it. `generate_scenario` can also persist `creative_format` / `visual_language` / `theme`. | free / 1 assist |
 | `apply_scenario` | Compile the **ready** scenario into per-scene prompts on the timeline (`segments_count` 0 or 3..10; omitted uses the generated scenario count, then 5; AI scenes replaced, uploads preserved). Polls until applied (~2 min budget). | **0** |
 | `set_scene_count` | Grow/shrink to N scenes (1–20); deletes only trailing un-generated scenes. Each AI scene is a fixed 8s. | **0** |
@@ -120,7 +122,7 @@ Reads are confined to `HUBFLUENCER_INPUT_DIR`. All $0.
 
 Size units are exact: videos are capped at **500 MB decimal (500,000,000 bytes)**; product
 images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
-(20,971,520 bytes)**; logos at **1 MiB (1,048,576 bytes)**. Editor video multipart starts at
+(20,971,520 bytes)**; logos at **5 MiB (5,242,880 bytes)**. Editor video multipart starts at
 **50 MiB (52,428,800 bytes)**.
 
 | Tool | What it does |
@@ -131,8 +133,9 @@ images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
 | `set_product` | Upload an editor product image (JPEG/PNG, ≤8 MiB) and attach it as the project product. |
 | `set_product_placement` | Set where the product appears on pending AI scenes: `throughout` or `end`. |
 | `set_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_logo` | Upload a brand logo overlay (JPEG/PNG, ≤5 MiB; editor only; optional treatment/position/duration). |
 | `set_short_product` | Attach a product image (JPEG/PNG, ≤20 MiB) to a **short**. |
+| `set_short_logo` | Attach an exact deterministic logo overlay (JPEG/PNG, ≤5 MiB) to a **short**; choose its corner and `throughout`/`end_card`/`none` (hide) treatment. The logo is never sent to the video model. |
 | `set_short_poster` | Set a short's end-card poster (JPEG/PNG, ≤20 MiB; extends the render 12s → 14s). Pass `poster_includes_lockup:true` if the poster already carries brand name/CTA/badges — suppresses the overlaid claim/CTA so they don't collide. |
 
 ### Status & delivery
@@ -233,7 +236,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** |
@@ -250,17 +253,22 @@ edit are **0 credits** — you only pay to generate/render.
 
 **One shot (recommended):**
 `make_video({ prompt: "an ad for…", save_path: "ad.mp4" })` → returns `{ ready, video_url, saved_to, estimated_credits, available_credits }`.
-It prices the job and only charges if it's affordable (and within `max_credits` if you set one); otherwise it returns
-`charged:false` with the estimate and a free draft slug. Preview first with `make_video({ prompt, dry_run:true })`.
+It prices the job and only launches if it's affordable (and within `max_credits` if you set one); otherwise it returns
+`charged:false` with the estimate and a free draft slug. Shorts charge at launch. Editors return the authorized cap and
+observed incremental spend (`authorized_credits`, `credits_spent`) instead of treating authorization as a charge.
+Preview first with `make_video({ prompt, dry_run:true })`.
 If it returns `terminal:false`, the render is still going — call `wait_for_completion` with the returned slug.
 
 **Granular (control/recovery):**
 `create_short` → optional `generate_hook_variations` (test hook angles free) / `generate_short_text` → `generate_short` → `wait_for_completion {kind:"short"}` → `download_result`, or
 `create_editor_ad` (free configure + quote) → obtain spend approval → `start_autopilot {slug, max_credits}` → `wait_for_completion {kind:"editor"}` → `download_result`.
 
+If waiting returns `stage:"batch_retry_required"`, call `retry_editor_batch` to continue the prepaid failed scene, or `cancel_editor_batch` to abandon the batch. Resolve that child batch before calling `start_autopilot` again; a retry does not itself authorize a new parent Autopilot run.
+
 **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