@hubfluencer/mcp 0.8.2 → 0.9.0

package/README.md

@@ -84,8 +84,8 @@ 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 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** |
 | `generate_short_text` | AI-draft editable headline / subheadline / caption beats for a short. | 1 assist |
-| `create_editor_ad` | Create an editor project **and** run autopilot end-to-end. Style it with `creative_format` + `visual_language` + `theme`. Cast modes need prerequisite assets, so configure them through `create_editor_draft` instead. | credits (est. first) |
-| `start_autopilot` | Run autopilot on an **existing** editor draft (resume a `make_video` `dry_run`, or after a top-up). | credits |
+| `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 |
 | `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** |
@@ -118,17 +118,22 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 
 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
+**50 MiB (52,428,800 bytes)**.
+
 | Tool | What it does |
 |---|---|
 | `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). |
-| `set_product` | Upload a local product image and attach it as the project product. |
+| `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_closing_image` | Set the ~2s end-card image (upload a file, or reuse the product image with `from_product:true`). |
-| `set_logo` | Upload a brand logo overlay (editor only; optional treatment/position/duration). |
-| `set_short_product` | Attach a product image to a **short**. |
-| `set_short_poster` | Set a short's end-card poster (extends the render 12s → 14s). Pass `poster_includes_lockup:true` if the poster already carries brand name/CTA/badges — suppresses the overlaid claim/CTA so they don't collide. |
+| `set_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_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
 
@@ -140,6 +145,12 @@ Reads are confined to `HUBFLUENCER_INPUT_DIR`. All $0.
 | `get_credits` / `list_voices` / `list_projects` | Credit balance; narration voices; recent projects (`include_completed:true` to recover a finished short's slug). |
 | `get_ai_assists` / `unlock_ai_assists` | The free daily assist quota / spend 1 credit for +10. |
 
+For editor projects, `video_url` may remain the last delivered MP4 after the timeline changes.
+It is current only when `ready:true` and `stale:false`. `stale:true` means the delivered render
+does not match the live timeline; regenerate the reported stale scenes/audio and render again.
+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.
+
 ### Campaign engine — onboard a product, plan, and draft (the delegation surface)
 
 Everything here is **$0** (draft creates + planning against the free assist quota). Generation
@@ -211,7 +222,7 @@ Subscription-gated (a 402 `subscription_required` means the account needs an act
 |---|---|
 | `list_assets` | Your reusable asset catalog (images + videos) with presigned URLs + your storage quota; page with `limit`/`offset`. |
 | `get_asset_quota` | Your catalog storage quota (limit / used / pending / reserved / remaining bytes). |
-| `upload_asset` | Upload a local image (≤20 MiB) or video (≤500 MB; `duration_seconds` required, ≤60) into the catalog so it can be reused across projects. Reads confined to `HUBFLUENCER_INPUT_DIR`. Rate limit 30/min. |
+| `upload_asset` | Upload a local image (≤20 MiB = 20,971,520 bytes) or video (≤500 MB decimal = 500,000,000 bytes; `duration_seconds` required, ≤60) into the catalog so it can be reused across projects. Reads confined to `HUBFLUENCER_INPUT_DIR`. Rate limit 30/min. |
 
 ### Credit prices (reference)
 
@@ -245,7 +256,7 @@ If it returns `terminal:false`, the render is still going — call `wait_for_com
 
 **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` → `wait_for_completion {kind:"editor"}` → `download_result`.
+`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** —
@@ -253,8 +264,8 @@ music; after that, every text/style/CTA/end-card tweak re-renders over them for
 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
-bed is faded to fit rather than regenerated — for perfectly synced music after such a change, use
-`generate_short`.
+bed loops through the added CTA window and fades at export end rather than leaving a silent card.
+For a newly composed bed timed specifically to the longer cut, use `generate_short`.
 
 **Image carousel:**
 `create_slider({ prompt: "5 tips for…", mode: "ad_driven", slide_count: 5 })` → `generate_slider` →