@hubfluencer/mcp 0.10.0 → 0.12.0

package/README.md

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