@hubfluencer/mcp 0.8.1 → 0.9.0

package/README.md

@@ -68,7 +68,7 @@ claude mcp add hubfluencer --env HUBFLUENCER_API_TOKEN=YOUR_TOKEN -- npx -y @hub
 
 ## Tools
 
-91 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
+92 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
@@ -79,12 +79,13 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | Tool | What it does | Cost |
 |---|---|---|
 | **`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 with an end-card poster). Set `headline`/`subheadline`/`music_vibe`/`visual_language` so it isn't bare. Optional opt-in conversion graphics: `offer_text`/`cta_text`/`badge_text`/`star_rating` (off unless you set them). | **0** |
-| `update_short` | Patch an existing short draft — brief (`product_prompt`), copy, styling, or the opt-in conversion graphics; only the fields you pass change. Clear one with `""` (`[]` for `text_beats`, `0` for `star_rating`). Re-run `generate_short` to apply. | **0** |
-| `generate_short` | Render an existing short. Safe to re-call (in-flight = reported, no double charge; a failed short can re-generate). | **15** |
+| `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** |
+| `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** |
@@ -117,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). |
+| `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
 
@@ -139,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
@@ -210,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)
 
@@ -221,6 +233,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** |
 | 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** |
@@ -242,8 +255,17 @@ It prices the job and only charges if it's affordable (and within `max_credits`
 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_short_text` → `generate_short` → `wait_for_completion {kind:"short"}` → `download_result`, or
-`create_editor_ad` → `wait_for_completion {kind:"editor"}` → `download_result`.
+`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`.
+
+**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
+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 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` →
@@ -274,6 +296,11 @@ start a NEW project (omit `slug`, pass `video_path`).
 > Result URLs are presigned and expire (~24h). Download promptly. Publishing to
 > TikTok/Instagram requires a human-linked social account and is out of scope —
 > return the MP4 + a suggested caption instead.
+>
+> **Label synthetic media.** These videos are AI-generated: TikTok requires an
+> AI-generated content label (and attaches C2PA credentials since 2025), and Meta
+> requires disclosure for AI-generated content in paid ads. Remind the user to
+> enable the platform's AI label when posting.
 
 ## Troubleshooting