@hubfluencer/mcp 0.7.1 → 0.8.2

package/src/index.ts

@@ -9,9 +9,11 @@
  *
  *   One-shot : make_video({ prompt })  → finished MP4 (create→start→poll→download)
  *   Shorts   : create_short → generate_short → wait_for_completion → download_result
+ *              (then iterate free: update_short → rerender_short, 0 credits)
  *   Editor   : create_editor_ad (creates + starts autopilot) → wait_for_completion → download_result
  *   Granular : create_editor_draft → generate_scenario|set_scenario → get_editor
- *              → set_scene_count → set_segment_prompt → generate_segment(s)
+ *              → apply_scenario (scenario → scene prompts) | set_scene_count + set_segment_prompt
+ *              → generate_segment(s) (+ regenerate_segment to re-roll a completed scene)
  *              → set_narration_script|generate_narration → generate_voice + generate_music
  *              → render → wait_for_completion → download_result
  */
@@ -500,7 +502,7 @@ const SERVER_INSTRUCTIONS = `Hubfluencer turns a prompt — or a whole product p
 
 MAKE ONE ASSET (simplest)
 - make_video({ prompt }) creates, generates, and returns a finished MP4 — it picks a single-clip short or a multi-scene editor ad from the prompt (override with kind:"short"|"editor"). create_short / create_editor_ad are the per-product one-shots; create_slider makes an image carousel; create_tracking_video burns a CV overlay onto a local clip.
-- Granular (full control): create a draft, then drive the pipeline step by step (create_editor_draft → generate_scenario → set_scene_count → set_segment_prompt → generate_segment(s) → generate_voice + generate_music → render). Poll with get_status / wait_for_completion; fetch with download_result (a slider has no MP4 — read its slides with get_slider).
+- Granular (full control): create a draft, then drive the pipeline step by step (create_editor_draft → generate_scenario → apply_scenario → review/edit prompts (set_segment_prompt) → generate_segment(s) → generate_voice + generate_music → render; regenerate_segment re-rolls a completed scene as a new version). Poll with get_status / wait_for_completion; fetch with download_result (a slider has no MP4 — read its slides with get_slider).
 
 DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 1. ONBOARD a product: extract_product_page(url) pulls facts + imagery (SSRF-hardened, 0cr); import_product_image saves its picture/logo. Persist identity once with create_product_profile + create_brand_profile so every later draft inherits it instead of re-describing the brand.
@@ -513,7 +515,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, 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 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/create_* report the estimate first — pass dry_run to preview, max_credits to cap.
 - 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.
 
@@ -637,12 +639,20 @@ registerTool(
 			"for simple/short ones; the chosen kind is reported back as kind_inferred. If it returns terminal=false " +
 			"the render is still running — call wait_for_completion with the returned slug to finish. " +
 			"BE PROACTIVE WITH BRANDING: pass headline (the on-screen TITLE) and subheadline (secondary title) plus " +
-			"music_vibe so a one-shot short isn't bare. creative_format + visual_language apply to BOTH kinds (editor and " +
+			"music_vibe so a one-shot short isn't bare. 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 for a " +
+			"deliberately bare clip. creative_format + visual_language apply to BOTH kinds (editor and " +
 			"shorts); headline/subheadline/music_vibe/text_* and the conversion graphics are SHORTS-only and ignored for " +
 			"editor; theme applies to editor (genre overlay) and is legacy-only for shorts (used when visual_language is unset). " +
 			"For richer branding — a product image, brand logo, or " +
 			"closing card — drive the granular path instead: create_short + set_short_product/set_short_poster, or " +
-			"create_editor_draft + set_product/set_logo/set_closing_image, then start_autopilot/generate_short.",
+			"create_editor_draft + set_product/set_logo/set_closing_image, then start_autopilot/generate_short. " +
+			"For a SHORT, iterating after the first render is FREE: update_short (copy/style/CTA/end-card) → " +
+			"rerender_short re-renders over the already-paid footage for 0 credits.",
 		// Schema kept intentionally flat (no .min/.max/.int chains) — the SDK's
 		// generic inference on registerTool hits TS2589 ("excessively deep") on
 		// larger schemas with chained validators. Ranges are enforced in code.
@@ -690,9 +700,11 @@ registerTool(
 				),
 			headline: z
 				.string()
+				.max(80)
 				.optional()
 				.describe(
-					"SHORTS only: the on-screen TITLE overlay (≤160). Set this so the short isn't bare.",
+					"SHORTS only: the on-screen TITLE overlay. ≈4 words; ≤40 chars hits hardest; hard cap 80 — " +
+						"longer hooks wrap past the safe area. Set this so the short isn't bare.",
 				),
 			subheadline: z
 				.string()
@@ -723,12 +735,15 @@ registerTool(
 			cta_text: z
 				.string()
 				.optional()
-				.describe("SHORTS only: optional CTA pill, e.g. Shop now (≤24 chars)"),
+				.describe(
+					"SHORTS only: CTA pill, e.g. Shop now (≤24 chars). Always set it — a short without a CTA doesn't convert.",
+				),
 			badge_text: z
 				.string()
 				.optional()
 				.describe(
-					"SHORTS only: optional badge stamp, e.g. BEST SELLER (≤24 chars)",
+					"SHORTS only: optional badge stamp, e.g. BEST SELLER (≤24 chars). Only badges you can " +
+						"substantiate — fabricated social proof is deceptive advertising.",
 				),
 			star_rating: z
 				.number()
@@ -737,7 +752,15 @@ registerTool(
 				.max(5)
 				.optional()
 				.describe(
-					"SHORTS only: optional 0..5 star rating under the subheadline",
+					"SHORTS only: optional 0..5 star rating under the subheadline. Only ratings you can " +
+						"substantiate — fabricated social proof is deceptive advertising.",
+				),
+			skip_auto_text: z
+				.boolean()
+				.optional()
+				.describe(
+					"SHORTS only: when headline/subheadline/text_beats are blank the server auto-writes the copy at " +
+						"generate time; pass true to skip that and render a deliberately bare clip (default false).",
 				),
 			text_position: z
 				.enum(["top", "center", "bottom"])
@@ -848,6 +871,7 @@ registerTool(
 				cta_text?: string;
 				badge_text?: string;
 				star_rating?: number;
+				skip_auto_text?: boolean;
 				text_position?: string;
 				text_animation?: string;
 				font_family?: string;
@@ -974,6 +998,7 @@ registerTool(
 						args.creative_format ?? "",
 						args.visual_language ?? "",
 						args.theme ?? "",
+						args.skip_auto_text ? "bare" : "auto-copy",
 					),
 				);
 				slug = created.data.slug;
@@ -1023,7 +1048,7 @@ registerTool(
 
 			const resume =
 				kind === "short"
-					? `generate_short({ slug: "${slug}" })`
+					? `generate_short({ slug: "${slug}"${args.skip_auto_text ? ", skip_auto_text: true" : ""} })`
 					: `start_autopilot({ slug: "${slug}" })`;
 			const affordable =
 				available_credits === null ||
@@ -1080,11 +1105,15 @@ registerTool(
 			if (kind === "short") {
 				await client.post(
 					`/shorts/${slug}/generate`,
-					undefined,
+					// Only send a body when the caller opts out of server auto-copy —
+					// the bare POST stays byte-identical to the pre-0.8.2 wire shape.
+					args.skip_auto_text ? { skip_auto_text: true } : undefined,
 					// gen-short:<slug> + the failure-state discriminator: a fresh/in-flight
 					// short reuses "gen-short:<slug>:start" (transport-retry dedupe), a
 					// re-run after a failed render gets a fresh key and re-renders.
-					`gen-short:${slug}:${startState}`,
+					// skip_auto_text is folded in so a bare-clip run never replays a
+					// cached auto-copy run's response (or vice versa) on the same slug.
+					`gen-short:${slug}:${startState}${args.skip_auto_text ? ":bare" : ""}`,
 				);
 			} else {
 				await client.post(
@@ -1281,10 +1310,19 @@ registerTool(
 		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 an end-card poster is set). Returns the slug, " +
-			"costs 0 credits. Follow with generate_short to render. " +
+			"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. To brand it further, attach a product image " +
+			"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.)",
 		inputSchema: {
@@ -1300,10 +1338,11 @@ registerTool(
 				),
 			headline: z
 				.string()
-				.max(160)
+				.max(80)
 				.optional()
 				.describe(
-					"The on-screen TITLE composited over the short (poster text overlay). ≤160 chars. Set this.",
+					"The on-screen TITLE composited over the short (poster text overlay). ≈4 words; ≤40 chars hits " +
+						"hardest; hard cap 80 — longer hooks wrap past the safe area. Set this.",
 				),
 			subheadline: z
 				.string()
@@ -1394,19 +1433,27 @@ registerTool(
 				.string()
 				.max(24)
 				.optional()
-				.describe('Optional CTA pill, e.g. "Shop now"'),
+				.describe(
+					'CTA pill, e.g. "Shop now". Always set it — a short without a CTA doesn\'t convert.',
+				),
 			badge_text: z
 				.string()
 				.max(24)
 				.optional()
-				.describe('Optional badge stamp, e.g. "BEST SELLER"'),
+				.describe(
+					'Optional badge stamp, e.g. "BEST SELLER". Only badges you can substantiate — fabricated social ' +
+						"proof is deceptive advertising.",
+				),
 			star_rating: z
 				.number()
 				.int()
 				.min(0)
 				.max(5)
 				.optional()
-				.describe("Optional 0..5 star rating under the subheadline"),
+				.describe(
+					"Optional 0..5 star rating under the subheadline. Only ratings you can substantiate — fabricated " +
+						"social proof is deceptive advertising.",
+				),
 			text_beats: z
 				.array(z.string().max(120))
 				.max(8)
@@ -1414,6 +1461,30 @@ registerTool(
 				.describe(
 					"Optional caption beats shown sequentially instead of the static subheadline.",
 				),
+			closing_claim: z
+				.string()
+				.max(80)
+				.optional()
+				.describe(
+					"End-card claim shown on the closing slate (≤80 chars) — a rephrase of the promise, not a new " +
+						"claim. Falls back to the headline when unset.",
+				),
+			brand_name: z
+				.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.",
+				),
+			end_card: z
+				.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).",
+				),
 			brand_profile_id: z
 				.number()
 				.int()
@@ -1450,6 +1521,9 @@ registerTool(
 				badge_text?: string;
 				star_rating?: number;
 				text_beats?: string[];
+				closing_claim?: string;
+				brand_name?: string;
+				end_card?: string;
 				brand_profile_id?: number;
 			},
 			client,
@@ -1486,6 +1560,10 @@ registerTool(
 			if (args.badge_text !== undefined) body.badge_text = args.badge_text;
 			if (args.star_rating !== undefined) body.star_rating = args.star_rating;
 			if (args.text_beats !== undefined) body.text_beats = args.text_beats;
+			if (args.closing_claim !== undefined)
+				body.closing_claim = args.closing_claim;
+			if (args.brand_name !== undefined) body.brand_name = args.brand_name;
+			if (args.end_card !== undefined) body.end_card = args.end_card;
 			if (args.brand_profile_id !== undefined)
 				body.brand_profile_id = args.brand_profile_id;
 			const res = await client.post<{ data: { slug: string } }>(
@@ -1513,13 +1591,16 @@ registerTool(
 					args.badge_text ?? "",
 					String(args.star_rating ?? ""),
 					JSON.stringify(args.text_beats ?? []),
+					args.closing_claim ?? "",
+					args.brand_name ?? "",
+					args.end_card ?? "",
 					String(args.brand_profile_id ?? ""),
 				),
 			);
 			return ok({
 				slug: res.data.slug,
 				kind: "short",
-				next: "set_short_product / set_short_poster (optional branding), then generate_short",
+				next: "set_short_product / set_short_poster (optional branding); generate_hook_variations to test hook angles before you spend; then generate_short. After that first render, hook/CTA/style iteration is free: update_short → rerender_short (0 credits).",
 			});
 		},
 	),
@@ -1531,8 +1612,19 @@ 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 (call generate_short afterwards to apply). Use this to edit the brief, copy, " +
+			"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 " +
@@ -1556,9 +1648,12 @@ registerTool(
 				),
 			headline: z
 				.string()
-				.max(160)
+				.max(80)
 				.optional()
-				.describe("On-screen TITLE overlay. ≤160 chars."),
+				.describe(
+					"On-screen TITLE overlay. ≈4 words; ≤40 chars hits hardest; hard cap 80 — longer hooks wrap " +
+						"past the safe area.",
+				),
 			subheadline: z
 				.string()
 				.max(200)
@@ -1644,13 +1739,16 @@ registerTool(
 				.string()
 				.max(24)
 				.optional()
-				.describe('CTA pill (opt-in), e.g. "Shop now". Pass "" to remove it.'),
+				.describe(
+					'CTA pill, e.g. "Shop now". Always set it — a short without a CTA doesn\'t convert. Pass "" to remove it.',
+				),
 			badge_text: z
 				.string()
 				.max(24)
 				.optional()
 				.describe(
-					'Badge stamp (opt-in), e.g. "BEST SELLER". Pass "" to remove it.',
+					'Badge stamp (opt-in), e.g. "BEST SELLER". Only badges you can substantiate — fabricated social ' +
+						'proof is deceptive advertising. Pass "" to remove it.',
 				),
 			star_rating: z
 				.number()
@@ -1659,7 +1757,8 @@ registerTool(
 				.max(5)
 				.optional()
 				.describe(
-					"0..5 star rating under the subheadline (opt-in). Pass 0 to remove it.",
+					"0..5 star rating under the subheadline (opt-in). Only ratings you can substantiate — fabricated " +
+						"social proof is deceptive advertising. Pass 0 to remove it.",
 				),
 			text_beats: z
 				.array(z.string().max(120))
@@ -1668,6 +1767,37 @@ registerTool(
 				.describe(
 					"Caption beats shown sequentially instead of the static subheadline. Pass [] to clear.",
 				),
+			closing_claim: z
+				.string()
+				.max(80)
+				.optional()
+				.describe(
+					"End-card claim shown on the closing slate (≤80 chars) — a rephrase of the promise, not a new " +
+						'claim. Falls back to the headline when unset. Pass "" to remove it.',
+				),
+			brand_name: z
+				.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: z
+				.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: z
+				.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).",
+				),
 			brand_profile_id: z
 				.number()
 				.int()
@@ -1709,6 +1839,10 @@ registerTool(
 				badge_text?: string;
 				star_rating?: number;
 				text_beats?: string[];
+				closing_claim?: string;
+				brand_name?: string;
+				end_card?: string;
+				poster_includes_lockup?: boolean;
 				brand_profile_id?: number;
 			},
 			client,
@@ -1749,6 +1883,12 @@ registerTool(
 			if (args.badge_text !== undefined) body.badge_text = args.badge_text;
 			if (args.star_rating !== undefined) body.star_rating = args.star_rating;
 			if (args.text_beats !== undefined) body.text_beats = args.text_beats;
+			if (args.closing_claim !== undefined)
+				body.closing_claim = args.closing_claim;
+			if (args.brand_name !== undefined) body.brand_name = args.brand_name;
+			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;
 			if (args.brand_profile_id !== undefined)
 				body.brand_profile_id = args.brand_profile_id;
 
@@ -1756,7 +1896,15 @@ registerTool(
 				`/shorts/${args.slug}`,
 				body,
 			);
-			return ok(asRecord(res).data ?? res);
+			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).",
+			});
 		},
 	),
 );
@@ -2132,16 +2280,30 @@ registerTool(
 	{
 		title: "Generate (render) a short",
 		description:
-			"Deducts 15 credits and starts the render pipeline for an existing short. Safe to call again: a " +
+			"Deducts 15 credits and starts the render pipeline for an existing short — this RE-ROLLS the footage " +
+			"and music (a fresh AI generation). For text/style/CTA/end-card tweaks on an already-generated short, " +
+			"use rerender_short instead: it re-applies the overlay over the existing footage for 0 credits. " +
+			"Safe to call again: a " +
 			"duplicate while a render is in flight is reported as in-progress (no double charge), and a failed " +
-			"short can be re-generated. Then poll with get_status or wait_for_completion (kind=short).",
-		inputSchema: { slug: z.string().describe("Short slug from create_short") },
+			"short can be re-generated. If the draft's headline/subheadline/text_beats are all blank the server " +
+			"auto-writes the headline + caption beats before rendering (pass skip_auto_text:true for a deliberately " +
+			"bare clip). Then poll with get_status or wait_for_completion (kind=short).",
+		inputSchema: {
+			slug: z.string().describe("Short slug from create_short"),
+			skip_auto_text: z
+				.boolean()
+				.optional()
+				.describe(
+					"When the draft has no headline/subheadline/text_beats the server auto-writes the copy; pass " +
+						"true to skip that and render a deliberately bare clip (default false).",
+				),
+		},
 		// Not idempotent: a repeat after a terminal (failed) render re-charges 15
 		// credits (the whole point of allowing a re-generation), so a blind retry is
 		// NOT free — only an in-flight duplicate dedupes (server 409). See below.
 		annotations: { title: "Generate short", ...WRITE },
 	},
-	tool(async (args: { slug: string }, client) => {
+	tool(async (args: { slug: string; skip_auto_text?: boolean }, client) => {
 		// No stable idempotency key (see generate_slider): a per-slug key would
 		// replay the first response for 24h and block an intentional re-generation
 		// of a failed short. Double-charge is prevented server-side — the batch
@@ -2150,6 +2312,9 @@ registerTool(
 		try {
 			const res = await client.post<{ data: unknown }>(
 				`/shorts/${args.slug}/generate`,
+				// Only send a body when the caller opts out of server auto-copy —
+				// the bare POST stays byte-identical to the pre-0.8.2 wire shape.
+				args.skip_auto_text ? { skip_auto_text: true } : undefined,
 			);
 			const status = normalizeStatus("short", args.slug, asRecord(res).data);
 			return ok(status);
@@ -2170,6 +2335,89 @@ registerTool(
 	}),
 );
 
+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; the pinned music bed is faded to fit rather than " +
+			"regenerated — for perfectly synced music after such a change, use generate_short. " +
+			"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: z.string().describe("Short slug (from create_short)"),
+		},
+		// Free, but not idempotent in the MCP sense: each call is a genuine new
+		// re-render of the short's CURRENT state — the whole point of the
+		// update_short → rerender_short loop (see the key note below).
+		annotations: { title: "Re-render short", ...WRITE, idempotentHint: false },
+	},
+	tool(async (args: { slug: string }, client) => {
+		try {
+			const res = await client.post<{ data: unknown }>(
+				`/shorts/${args.slug}/rerender`,
+				undefined,
+				// Each call is a genuine new re-render attempt (the core loop is
+				// update_short → rerender_short, repeated per variant). A per-invocation
+				// nonce keeps the server's 24h idempotency cache from replaying a PRIOR
+				// rerender's response on a deliberate re-application after an edit.
+				// (The client never auto-retries non-GETs, so the nonce buys no
+				// transport-retry protection — it exists purely to defeat the replay
+				// cache.) A concurrent duplicate is independently blocked server-side
+				// (409 while any work is active) — and the call is 0 credits, so there
+				// is no charge to protect. Mirrors start_autopilot's
+				// idemKey("autopilot", slug, randomUUID()).
+				idemKey("rerender-short", args.slug, randomUUID()),
+			);
+			const status = normalizeStatus("short", args.slug, asRecord(res).data);
+			return ok({
+				...status,
+				next: `wait_for_completion({ slug: "${args.slug}", kind: "short" }) — or poll get_status. A re-render is fast (no AI generation).`,
+			});
+		} catch (e) {
+			const he = e as { status?: number; code?: string };
+			if (he.status === 409) {
+				// A generation/render is already in flight — report in-progress
+				// (same shape as generate_short's 409 handling), never a hard error.
+				return ok({
+					kind: "short",
+					slug: args.slug,
+					stage: "processing",
+					terminal: false,
+					ready: false,
+					video_url: null,
+					error: null,
+					next: `A render is already running — wait_for_completion({ slug: "${args.slug}", kind: "short" }).`,
+				});
+			}
+			if (he.status === 422 && he.code === "short_not_ready") {
+				// Nothing rendered yet to re-render over: the free path needs the
+				// paid footage+music to exist first.
+				return fail(
+					"This short has no completed footage + music to re-render over (short_not_ready). " +
+						`Run generate_short({ slug: "${args.slug}" }) once (15 credits) — after that first render, every ` +
+						"text/style/CTA/end-card tweak re-renders free with rerender_short.",
+				);
+			}
+			if (he.status === 422 && he.code === "short_paid_regeneration_required") {
+				return fail(
+					"A footage or music input changed after the last paid render " +
+						"(short_paid_regeneration_required). The pinned assets no longer match the draft. " +
+						`Run generate_short({ slug: "${args.slug}" }) (15 credits) before using free re-renders again.`,
+				);
+			}
+			throw e;
+		}
+	}),
+);
+
 registerTool(
 	"generate_short_text",
 	{
@@ -2578,7 +2826,9 @@ registerTool(
 			"BRANDING: to attach the user's own product image, brand logo, or closing card, create the draft with " +
 			"create_editor_draft first, call set_product / set_logo / set_closing_image (all 0 credits), then " +
 			"start_autopilot — autopilot weaves them in. (Editor ads carry their copy in-scene/narration, not as a " +
-			"title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.)",
+			"title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.) " +
+			"For product_only or presenter_led cast modes, use create_editor_draft and configure the required " +
+			"product/presenter before start_autopilot; this one-shot tool intentionally uses automatic casting.",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -2826,7 +3076,8 @@ registerTool(
 // ad with full control (review the scenario, write its own prompts, etc.)
 // instead of one-shot autopilot (create_editor_ad / make_video).
 //   create_editor_draft → generate_scenario|set_scenario → get_editor (REVIEW)
-//   → set_scene_count → set_segment_prompt → generate_segment|generate_all_segments
+//   → apply_scenario (scenario → per-scene prompts) | set_scene_count + set_segment_prompt
+//   → generate_segment|generate_all_segments (+ regenerate_segment for completed scenes)
 //   → set_narration_script|generate_narration → generate_voice + generate_music
 //   → render → wait_for_completion(kind:"editor") → download_result.
 
@@ -2877,6 +3128,17 @@ registerTool(
 				.describe(
 					'Visual theme / genre overlay (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
 				),
+			cast_mode: z
+				.enum(["product_only", "presenter_led"])
+				.optional()
+				.describe(
+					"Who/what anchors every AI scene. product_only = a product-led ad with NO people; requires a " +
+						"product image (set_product) before generation and generates every scene from persistent product " +
+						"reference images — the best product fidelity. presenter_led = one locked presenter appears in " +
+						"every scene; requires a presenter to be configured first (in the app / REST presenter endpoints " +
+						"— no MCP tool yet), else generation fails with presenter_required. Omit for the default auto " +
+						"behavior.",
+				),
 			voice_id: z
 				.string()
 				.regex(/^[A-Za-z0-9_-]+$/)
@@ -2913,6 +3175,7 @@ registerTool(
 				creative_format?: string;
 				visual_language?: string;
 				theme?: string;
+				cast_mode?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
 				project_intent?: string;
@@ -2926,6 +3189,7 @@ registerTool(
 				creative_format: args.creative_format,
 				visual_language: args.visual_language,
 				theme: args.theme,
+				cast_mode: args.cast_mode,
 				voice_id: args.voice_id,
 				export_aspect_ratio: args.export_aspect_ratio,
 				project_intent: args.project_intent,
@@ -2948,12 +3212,13 @@ registerTool(
 					args.theme ?? "",
 					args.voice_id ?? "",
 					args.export_aspect_ratio ?? "",
+					args.cast_mode ?? "",
 				),
 			);
 			return ok({
 				slug: created.data.slug,
 				kind: "editor",
-				next: "generate_scenario | set_scenario, then get_editor to review",
+				next: "generate_scenario | set_scenario, then get_editor to review, then apply_scenario",
 			});
 		},
 	),
@@ -3011,7 +3276,10 @@ registerTool(
 			"(quota exhausted) either set auto_unlock:true to spend 1 credit for +10 assists and retry once, or " +
 			"write the scenario yourself with set_scenario. Server default segments_count is 5. " +
 			"Optionally pass creative_format / visual_language / theme to persist the project\u2019s creative style before " +
-			"generating (this is the granular path\u2019s way to set/change style; PATCH /scenario does not).",
+			"generating (this is the granular path\u2019s way to set/change style; PATCH /scenario does not). " +
+			"Generation is ASYNC: get_editor shows scenario_status generating \u2192 ready (a few seconds). NEXT STEP: " +
+			"once ready, review the scenario with get_editor, then call apply_scenario to turn it into per-scene " +
+			"segment prompts on the timeline.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			segments_count: z
@@ -3083,6 +3351,111 @@ registerTool(
 	),
 );
 
+registerTool(
+	"apply_scenario",
+	{
+		title: "Apply the scenario to the timeline (per-scene prompts)",
+		description:
+			"Turns the READY scenario into per-scene segment prompts on the timeline — the missing step between " +
+			"generate_scenario and generate_segment in the granular flow. Existing AI segments are REPLACED with " +
+			"freshly generated scene prompts (uploaded clips are preserved); segments_count 0 removes the AI scenes " +
+			"and keeps the scenario only. Free — no credits, no AI assist (rate limit 15/min). Requires " +
+			'scenario_status "ready" (422 scenario_not_ready otherwise): after generate_scenario wait until ' +
+			"get_editor shows ready (a few seconds); set_scenario is ready immediately. The apply itself runs async " +
+			"server-side — this tool polls get_editor (bounded ~2 min) until scenario_apply_status leaves " +
+			'"applying" and returns the materialized prompts; if it reports timed_out, keep polling get_editor ' +
+			"yourself. Then review/edit with set_segment_prompt and generate with generate_segment / " +
+			"generate_all_segments (or just render).",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segments_count: z
+				.union([z.literal(0), z.number().int().min(3).max(10)])
+				.optional()
+				.describe(
+					"How many AI scenes to create on the timeline — 0 or any integer from 3 to 10. Omit to use " +
+						"the scene count saved by generate_scenario (or 5 when none is stored). " +
+						"0 keeps the scenario only and preserves manual timeline control.",
+				),
+		},
+		annotations: { title: "Apply scenario", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (args: { slug: string; segments_count?: number }, client, extra) => {
+			const body: Record<string, unknown> = {};
+			if (args.segments_count !== undefined)
+				body.segments_count = args.segments_count;
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/apply-scenario`,
+				body,
+			);
+			const accepted = asRecord(asRecord(res).data);
+
+			// The 202 only STARTS the apply — the controller flips
+			// scenario_apply_status to "applying" before responding, and an async
+			// worker compiles the scenario into per-scene prompts. Poll the project
+			// until the status leaves "applying" ("idle" = success, "failed" =
+			// terminal) so the agent gets the materialized prompts back instead of
+			// having to poll itself. The budget is far below the render loops' 280s
+			// ceiling: an apply is a single LLM call (typically seconds).
+			const APPLY_BUDGET_MS = 120_000;
+			const APPLY_POLL_MS = 2_500;
+			const deadline = Date.now() + APPLY_BUDGET_MS;
+			const readEditor = async () => {
+				// Bound each poll GET's retries by the loop deadline (see fetchStatus).
+				const r = await client.get<{ data: unknown }>(
+					`/editor/${args.slug}`,
+					undefined,
+					deadline,
+				);
+				return asRecord(asRecord(r).data);
+			};
+			let n = 0;
+			let editor = await readEditor();
+			while (
+				editor.scenario_apply_status === "applying" &&
+				Date.now() + APPLY_POLL_MS <= deadline
+			) {
+				await reportProgress(extra, ++n, "applying scenario to timeline");
+				await sleep(APPLY_POLL_MS);
+				editor = await readEditor();
+			}
+
+			if (editor.scenario_apply_status === "applying") {
+				return ok({
+					slug: args.slug,
+					applied: false,
+					timed_out: true,
+					note: 'The apply is still running server-side. Poll get_editor until scenario_apply_status is no longer "applying", then review the scene prompts.',
+				});
+			}
+			if (editor.scenario_apply_status === "failed") {
+				return fail(
+					"Scenario apply failed server-side. Re-run apply_scenario to retry, or build the timeline yourself with set_scene_count + set_segment_prompt.",
+				);
+			}
+			const segments = Array.isArray(editor.segments)
+				? (editor.segments as Record<string, unknown>[])
+				: [];
+			return ok({
+				slug: args.slug,
+				applied: true,
+				ai_segments_replaced: accepted.ai_segments_replaced,
+				uploads_preserved: accepted.uploads_preserved,
+				target_ai_segments: accepted.target_ai_segments,
+				scene_count: segments.length,
+				segments: segments.map((s) => ({
+					id: s.id,
+					position: s.position,
+					source_type: s.source_type,
+					status: s.status,
+					prompt: s.prompt,
+				})),
+				next: "Review/edit prompts (set_segment_prompt), then generate_segment / generate_all_segments — or just render (it auto-charges ungenerated scenes at the batch rate)",
+			});
+		},
+	),
+);
+
 registerTool(
 	"set_scene_count",
 	{
@@ -3214,8 +3587,10 @@ registerTool(
 	{
 		title: "Generate one segment (5 credits)",
 		description:
-			"Renders the video for one scene. Each AI-generated scene is a fixed 8 seconds long. Costs 5 credits. " +
-			"Re-call to retry a failed scene or regenerate after a prompt edit — the server blocks regenerating one that's still processing, so no double-charge. Visual" +
+			"Renders the video for one PENDING or FAILED scene. Each AI-generated scene is a fixed 8 seconds long. " +
+			"Costs 5 credits. Re-call to retry a failed scene or after a prompt edit — the server blocks one that's " +
+			"still processing (editor_segment_busy), so no double-charge; a COMPLETED scene returns " +
+			"editor_segment_completed — re-roll those with regenerate_segment instead. Visual " +
 			"continuity is handled server-side (this scene uses the previous scene's last frame). 402 " +
 			"credits_insufficient fails cleanly. Generate scenes in position order for correct continuity.",
 		inputSchema: {
@@ -3236,6 +3611,54 @@ registerTool(
 	}),
 );
 
+registerTool(
+	"regenerate_segment",
+	{
+		title: "Regenerate a completed segment (new version, 4 credits)",
+		description:
+			"Re-rolls a COMPLETED scene as a NEW VERSION of that segment — the previous version is kept (switch back " +
+			"in the app). Costs 4 credits. Use generate_segment for pending/failed scenes; use THIS for a completed " +
+			"scene you want different — optionally with a new prompt (omit it to re-roll the current prompt). The new " +
+			"version starts rendering immediately; watch it with get_editor (status processing → completed|failed). " +
+			"KNOWN LIMITATION: scenes chain visual continuity off the previous scene's last frame, so regenerating a " +
+			"MID-TIMELINE scene can degrade the transition into the FOLLOWING scene (it was seeded from the old " +
+			"version's last frame). A scene still processing returns editor_segment_busy (no double charge); 402 " +
+			"credits_insufficient fails cleanly.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segment_id: z
+				.union([z.number(), z.string()])
+				.describe("Segment id (from get_editor)"),
+			prompt: z
+				.string()
+				.min(1)
+				.max(2000)
+				.optional()
+				.describe(
+					"Optional new scene prompt for the regenerated version (1–2000 chars); omit to reuse the current prompt",
+				),
+		},
+		annotations: {
+			title: "Regenerate segment",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: { slug: string; segment_id: number | string; prompt?: string },
+			client,
+		) => {
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/segments/${String(args.segment_id)}/regenerate`,
+				args.prompt !== undefined ? { prompt: args.prompt } : undefined,
+				undefined,
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
 registerTool(
 	"generate_all_segments",
 	{
@@ -4200,21 +4623,43 @@ registerTool(
 		inputSchema: {
 			slug: z.string().describe("Short slug (from create_short)"),
 			file_path: z.string().describe("Local poster image (.jpg/.jpeg/.png)"),
+			poster_includes_lockup: z
+				.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).",
+				),
 		},
 		annotations: { title: "Set short poster", ...WRITE, idempotentHint: false },
 	},
-	tool(async (args: { slug: string; file_path: string }, client) => {
-		const { s3_key } = await uploadShortPoster(
+	tool(
+		async (
+			args: {
+				slug: string;
+				file_path: string;
+				poster_includes_lockup?: boolean;
+			},
 			client,
-			args.slug,
-			args.file_path,
-		);
-		const res = await client.post<{ data: unknown }>(
-			`/shorts/${args.slug}/poster/confirm`,
-			{ s3_key },
-		);
-		return ok(asRecord(res).data ?? res);
-	}),
+		) => {
+			const { s3_key } = await uploadShortPoster(
+				client,
+				args.slug,
+				args.file_path,
+			);
+			const res = await client.post<{ data: unknown }>(
+				`/shorts/${args.slug}/poster/confirm`,
+				{
+					s3_key,
+					// A new poster replaces the old poster's content contract too:
+					// omission means the declared default (overlays enabled), not
+					// "preserve whatever the previous poster said".
+					poster_includes_lockup: args.poster_includes_lockup ?? false,
+				},
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
 );
 
 // ── Status / waiting ──────────────────────────────────────────────────────────