@hubfluencer/mcp 0.8.1 → 0.9.0

package/src/index.ts

@@ -9,7 +9,8 @@
  *
  *   One-shot : make_video({ prompt })  → finished MP4 (create→start→poll→download)
  *   Shorts   : create_short → generate_short → wait_for_completion → download_result
- *   Editor   : create_editor_ad (creates + starts autopilot) → wait_for_completion → download_result
+ *              (then iterate free: update_short → rerender_short, 0 credits)
+ *   Editor   : create_editor_ad (create + assets + quote; max_credits launches) → wait_for_completion → download_result
  *   Granular : create_editor_draft → generate_scenario|set_scenario → get_editor
  *              → apply_scenario (scenario → scene prompts) | set_scene_count + set_segment_prompt
  *              → generate_segment(s) (+ regenerate_segment to re-roll a completed scene)
@@ -115,7 +116,14 @@ import {
 } from "./series-calendar.js";
 import {
 	CATALOG_ASSET_EXTS,
+	closePreparedUploadFile,
 	IMAGE_EXTS,
+	MAX_CLOSING_IMAGE_BYTES,
+	MAX_LOGO_BYTES,
+	MAX_PRODUCT_IMAGE_BYTES,
+	type PreparedUploadFile,
+	preparedUploadIdentity,
+	prepareImageUpload,
 	resolveVideoReadPath,
 	uploadCatalogAsset,
 	uploadImageFile,
@@ -145,6 +153,68 @@ async function fetchStatus(
 	return normalizeStatus(kind, slug, asRecord(res).data);
 }
 
+async function editorAutopilotQuote(
+	client: HubfluencerClient,
+	slug: string,
+	overrides: {
+		language?: string;
+		product_subject?: string;
+		product_prompt?: string;
+	} = {},
+): Promise<{
+	estimated_credits: number | null;
+	available_credits: number | null;
+	affordable: boolean;
+}> {
+	try {
+		const params = new URLSearchParams();
+		if (overrides.language) params.set("language", overrides.language);
+		if (overrides.product_subject)
+			params.set("product_subject", overrides.product_subject);
+		if (overrides.product_prompt)
+			params.set("product_prompt", overrides.product_prompt);
+		const query = params.toString();
+		const response = await client.get<{ data: unknown }>(
+			`/editor/${slug}/autopilot/cost${query ? `?${query}` : ""}`,
+		);
+		const cost = asRecord(asRecord(response).data);
+		const estimated_credits =
+			typeof cost.total === "number" ? cost.total : null;
+		const available_credits =
+			typeof cost.available_credits === "number"
+				? cost.available_credits
+				: null;
+		return {
+			estimated_credits,
+			available_credits,
+			affordable:
+				estimated_credits !== null &&
+				available_credits !== null &&
+				available_credits >= estimated_credits,
+		};
+	} catch (error) {
+		const apiError = error as Partial<HubfluencerError>;
+		if (
+			typeof apiError.status === "number" &&
+			apiError.status >= 400 &&
+			apiError.status < 500 &&
+			apiError.status !== 429
+		) {
+			// Authentication, scope, validation, and unknown-slug errors are stable
+			// and actionable. Preserve them rather than disguising them as a pricing
+			// outage. Only transient/network/server failures use the fail-closed quote.
+			throw error;
+		}
+		// A spend cap cannot be enforced without a live price. Fail closed: callers
+		// receive a free draft/quote response and can retry the preflight later.
+		return {
+			estimated_credits: null,
+			available_credits: null,
+			affordable: false,
+		};
+	}
+}
+
 function isRecompositeInProgressConflict(e: unknown): boolean {
 	const err = e as Partial<HubfluencerError>;
 	if (err?.status !== 409) return false;
@@ -500,26 +570,26 @@ const WRITE = {
 const SERVER_INSTRUCTIONS = `Hubfluencer turns a prompt — or a whole product page — into finished, post-ready vertical videos and image carousels, and can run the surrounding content operation (plan → draft → review → schedule → measure → repeat).
 
 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.
+- 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_editor_ad creates/configures/prices an editor and launches only with max_credits; create_short creates a short draft; 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 → 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.
 2. PLAN ($0, free quota — not credits): plan_campaign proposes angles/formats + a per-item credit estimate; generate_hook_variations writes hook options. create_campaign(url | product_profile_id) does 1-2 end-to-end and returns a pack of editable DRAFTS.
 3. PACK & MATERIALIZE ($0): create_campaign_pack / add_pack_variations assemble items; materialize_pack_item turns each into a 0-credit draft (editor_ad/short → a video project, carousel → a slider). list_campaign_packs lists packs; get_campaign_pack({ id }) shows every item's draft slug + credit estimate.
-4. GENERATE per draft (CREDITS — a separate, explicit step): run start_autopilot/generate_short/generate_slider on each draft slug. Nothing above this line spends video credits.
+4. GENERATE per draft (CREDITS — a separate, explicit step): start_autopilot({slug}) quotes free; after approval, start_autopilot({slug,max_credits:approved_cap}) launches. Run generate_short/generate_slider for approved short/carousel drafts. Nothing above this line spends video credits.
 5. REVIEW: create_review_link mints a no-login page where a human approves/comments (list_review_links / revoke_review_link manage them). Gate spend or posting on approval.
 6. CALENDAR (reminder-only): schedule_post / list_scheduled_posts / reschedule_post / cancel_scheduled_post stage a calendar that pushes REMINDERS to the user — it does NOT auto-publish (posting to TikTok/IG stays a human step in the app). After the user posts the presigned export, call mark_scheduled_posted.
 7. MEASURE → DOUBLE DOWN: record_performance logs views/engagement (tag creatives via set_item_attributes); get_recommendations gives a CAUTIOUS, non-causal read of your own best hook/format (present its confidence + note as-is, never upgrade them); make_more_like_winner spins fresh hooks from a proven item — feed a winner back into add_pack_variations → step 4.
 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.
-- 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.
+- 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 supports dry_run/max_credits; create_editor_ad/start_autopilot require max_credits before launching.
 - 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.
 
 WAITING & RESUMING
-- Renders run async and can take minutes. wait_for_completion polls a budget capped at 280s; if it returns terminal=false / timed_out, just CALL IT AGAIN with the same slug. make_video returns the slug + a resume hint on timeout.
+- Renders run async and can take minutes. wait_for_completion polls a budget capped at 280s; if it returns terminal=false / timed_out, just CALL IT AGAIN with the same slug. make_video returns the slug + a resume hint on timeout. A terminal result is not always ready: an editor can go terminal in a needs-action stage (editing_required = stale after edits, regenerate the flagged scenes/audio; insufficient_credits = batch parked, top up / reduce scope; idle = draft with nothing generating, start generation first) — act on those instead of re-polling.
 - Creates and charged actions are idempotency-keyed: a transport retry is safe; a genuine re-run after a terminal FAILURE restarts rather than replaying the dead attempt.
 
 LOCAL FILES (sandboxed)
@@ -638,12 +708,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.
@@ -691,9 +769,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()
@@ -724,12 +804,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()
@@ -738,7 +821,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"])
@@ -821,6 +912,8 @@ registerTool(
 				),
 			max_credits: z
 				.number()
+				.int()
+				.nonnegative()
 				.optional()
 				.describe(
 					"Spend cap: refuse to start (no charge) if the priced estimate exceeds this. Returns the estimate.",
@@ -849,6 +942,7 @@ registerTool(
 				cta_text?: string;
 				badge_text?: string;
 				star_rating?: number;
+				skip_auto_text?: boolean;
 				text_position?: string;
 				text_animation?: string;
 				font_family?: string;
@@ -975,6 +1069,7 @@ registerTool(
 						args.creative_format ?? "",
 						args.visual_language ?? "",
 						args.theme ?? "",
+						args.skip_auto_text ? "bare" : "auto-copy",
 					),
 				);
 				slug = created.data.slug;
@@ -1000,9 +1095,9 @@ registerTool(
 				slug = created.data.slug;
 			}
 
-			// 2) Preflight cost vs the live balance BEFORE charging. Best-effort: if
-			//    pricing can't be read we proceed (the charge itself still 402s
-			//    cleanly), surfacing nulls rather than blocking on a transient error.
+			// 2) Preflight cost vs the live balance BEFORE charging. Shorts retain
+			//    their fixed-price compatibility behavior, but an editor without a
+			//    readable quote must never fall through to the API's uncapped launch.
 			const costPath =
 				kind === "short"
 					? `/shorts/${slug}/cost`
@@ -1019,13 +1114,14 @@ registerTool(
 						? cost.available_credits
 						: null;
 			} catch {
-				// pricing unavailable — fall through (do not block an affordable run)
+				// The editor branch below fails closed unless the caller supplied an
+				// explicit cap that the launch endpoint can enforce independently.
 			}
 
 			const resume =
 				kind === "short"
-					? `generate_short({ slug: "${slug}" })`
-					: `start_autopilot({ slug: "${slug}" })`;
+					? `generate_short({ slug: "${slug}"${args.skip_auto_text ? ", skip_auto_text: true" : ""} })`
+					: `start_autopilot({ slug: "${slug}", max_credits: ${estimated_credits ?? "<approved cap>"} })`;
 			const affordable =
 				available_credits === null ||
 				estimated_credits === null ||
@@ -1034,17 +1130,28 @@ registerTool(
 				args.max_credits != null &&
 				estimated_credits != null &&
 				estimated_credits > args.max_credits;
-
-			// 3) Stop BEFORE charging on dry_run, an over-cap estimate, or a balance
-			//    we already know is too low. The free draft is returned so the caller
-			//    can top up / raise the cap and resume — no wasted charge, no orphan
-			//    on retry (the create idempotency key reuses this slug).
-			if (args.dry_run || overCap || !affordable) {
+			const editorPriceUnavailableWithoutCap =
+				kind === "editor" &&
+				estimated_credits === null &&
+				args.max_credits == null;
+
+			// 3) Stop BEFORE charging on dry_run, an uncapped editor with no live
+			//    quote, an over-cap estimate, or a balance we already know is too
+			//    low. The free draft is returned so the caller can retry the quote,
+			//    top up, or raise the cap without an orphan or surprise charge.
+			if (
+				args.dry_run ||
+				editorPriceUnavailableWithoutCap ||
+				overCap ||
+				!affordable
+			) {
 				const note = args.dry_run
 					? `Dry run — created a free draft and priced it (${estimated_credits ?? "?"} credits, have ${available_credits ?? "?"}). To run it: ${resume}.`
-					: overCap
-						? `Estimated ${estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged. Raise max_credits, or run ${resume}.`
-						: `Not enough credits (needs ${estimated_credits ?? "?"}, have ${available_credits ?? "?"}); nothing charged. Top up, then run ${resume}.`;
+					: editorPriceUnavailableWithoutCap
+						? `Pricing is temporarily unavailable, so the editor was left as a free draft and nothing was charged. Retry the quote, then run start_autopilot({ slug: "${slug}", max_credits: <approved cap> }).`
+						: overCap
+							? `Estimated ${estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged. Raise max_credits, or run ${resume}.`
+							: `Not enough credits (needs ${estimated_credits ?? "?"}, have ${available_credits ?? "?"}); nothing charged. Top up, then run ${resume}.`;
 				return ok({
 					slug,
 					kind,
@@ -1081,16 +1188,31 @@ 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 {
+				const approvedCap = args.max_credits ?? estimated_credits;
+				if (approvedCap === null) {
+					// Belt-and-suspenders invariant behind the fail-closed branch above:
+					// never let a future condition refactor revive an uncapped editor POST.
+					throw new Error(
+						"Editor autopilot launch requires max_credits or a live quote",
+					);
+				}
 				await client.post(
 					`/editor/${slug}/autopilot`,
-					undefined,
+					// Use the caller's explicit cap when given, otherwise the live
+					// estimate. The API recomputes under its launch lock and rejects a
+					// price increase before any state change or charge.
+					{ max_credits: approvedCap },
 					// Fold the create-affecting params AND the failure-state discriminator
 					// into the start key so it tracks the inputs + current state, not just
 					// the slug. This key is only compared against a retry of *this* tool on
@@ -1282,10 +1404,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: {
@@ -1301,10 +1432,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()
@@ -1395,19 +1527,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)
@@ -1415,6 +1555,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()
@@ -1451,6 +1615,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,
@@ -1487,6 +1654,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 } }>(
@@ -1514,13 +1685,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).",
 			});
 		},
 	),
@@ -1532,8 +1706,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 " +
@@ -1557,9 +1742,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)
@@ -1645,13 +1833,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()
@@ -1660,7 +1851,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))
@@ -1669,6 +1861,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()
@@ -1710,6 +1933,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,
@@ -1750,6 +1977,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;
 
@@ -1757,7 +1990,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).",
+			});
 		},
 	),
 );
@@ -2133,16 +2374,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
@@ -2151,6 +2406,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);
@@ -2171,6 +2429,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; when the pinned music bed is shorter than the " +
+			"export it crossfades into a repeated continuation, then fades at the export end, without regeneration. " +
+			"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",
 	{
@@ -2570,18 +2911,20 @@ registerTool(
 registerTool(
 	"create_editor_ad",
 	{
-		title: "Create a multi-scene editor ad (autopilot)",
+		title: "Create, configure, and price a multi-scene editor ad",
 		description:
-			"Creates an editor project from a product prompt and starts autopilot (server-orchestrated " +
+			"Creates an editor project, attaches any supplied local product/logo/closing assets BEFORE generation, " +
+			"and prices autopilot (server-orchestrated " +
 			"scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " +
-			"Returns the slug. Costs credits. Then poll with get_status / wait_for_completion (kind=editor). Prefer " +
-			"make_video for the one-shot path. " +
-			"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 " +
+			"Without max_credits it STOPS after the free draft/configuration and returns the live estimate. It starts " +
+			"the paid pipeline only when max_credits is supplied and covers the estimate. Then poll with get_status / " +
+			"wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " +
+			"Supplying assets here is safer than adding them after autopilot because the scenario and scenes are grounded " +
+			"in the real product from the start. (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.) " +
-			"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.",
+			"For a mascot or hero product that must stay visually identical with no human presenter, set " +
+			"cast_mode:'product_only' together with product_image_path. Presenter-led casting still belongs on " +
+			"create_editor_draft because it requires a separately configured presenter.",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -2637,6 +2980,61 @@ registerTool(
 				.enum(["9:16", "16:9", "1:1"])
 				.optional()
 				.describe('Aspect ratio (default "9:16")'),
+			product_image_path: z
+				.string()
+				.optional()
+				.describe(
+					"Local product image (.jpg/.jpeg/.png, ≤8 MiB) to attach before autopilot.",
+				),
+			product_description: z
+				.string()
+				.max(500)
+				.optional()
+				.describe(
+					"Exact product/character description used with product_image_path.",
+				),
+			closing_image_path: z
+				.string()
+				.optional()
+				.describe("Local closing-card image (.jpg/.jpeg/.png, ≤20 MiB)."),
+			logo_path: z
+				.string()
+				.optional()
+				.describe("Local logo (.jpg/.jpeg/.png, ≤1 MiB) to overlay."),
+			logo_treatment: z
+				.enum(["intro", "outro", "both", "none"])
+				.optional()
+				.describe(
+					'When the logo bumper plays: "intro", "outro", "both" (default), or "none". Requires logo_path.',
+				),
+			logo_position: z
+				.enum(["top-left", "top-right", "bottom-left", "bottom-right"])
+				.optional()
+				.describe(
+					'Logo corner: "top-left", "top-right" (default), "bottom-left", or "bottom-right". Requires logo_path.',
+				),
+			logo_duration_seconds: z
+				.number()
+				.min(0.5)
+				.max(3)
+				.optional()
+				.describe(
+					"Logo bumper duration in seconds, 0.5–3 (default 1.5). Requires logo_path.",
+				),
+			cast_mode: z
+				.literal("product_only")
+				.optional()
+				.describe(
+					"Lock every AI scene to the supplied product/mascot reference with no people. Requires product_image_path.",
+				),
+			max_credits: z
+				.number()
+				.int()
+				.nonnegative()
+				.optional()
+				.describe(
+					"Explicit spend cap. Omit to create/configure/price only; no credits are charged.",
+				),
 		},
 		outputSchema: createEditorOutput,
 		annotations: { title: "Create editor ad", ...WRITE, idempotentHint: true },
@@ -2653,47 +3051,219 @@ registerTool(
 				theme?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
+				product_image_path?: string;
+				product_description?: string;
+				closing_image_path?: string;
+				logo_path?: string;
+				logo_treatment?: "intro" | "outro" | "both" | "none";
+				logo_position?:
+					| "top-left"
+					| "top-right"
+					| "bottom-left"
+					| "bottom-right";
+				logo_duration_seconds?: number;
+				cast_mode?: "product_only";
+				max_credits?: number;
 			},
 			client,
 		) => {
-			const langErr = validateLanguage(args.language);
-			if (langErr) return fail(langErr);
-			const promptErr = validateProductPrompt(args.product_prompt);
-			if (promptErr) return fail(promptErr);
+			const prepared: PreparedUploadFile[] = [];
+			let productImage: PreparedUploadFile | undefined;
+			let closingImage: PreparedUploadFile | undefined;
+			let logo: PreparedUploadFile | undefined;
+			try {
+				const langErr = validateLanguage(args.language);
+				if (langErr) return fail(langErr);
+				const promptErr = validateProductPrompt(args.product_prompt);
+				if (promptErr) return fail(promptErr);
+				if (args.cast_mode === "product_only" && !args.product_image_path) {
+					return fail(
+						"cast_mode product_only requires product_image_path so identity can be locked before generation.",
+					);
+				}
+				// Fail fast on settings that would otherwise be silently dropped: the
+				// logo PATCH is gated on logo_path and the product_description is only
+				// sent with product_image_path, so a logo_* / product_description passed
+				// without its asset is a caller mistake. Reject BEFORE creating even a
+				// free draft (consistent with the asset validation just below), rather
+				// than accepting the call and ignoring the field.
+				if (
+					(args.logo_treatment !== undefined ||
+						args.logo_position !== undefined ||
+						args.logo_duration_seconds !== undefined) &&
+					!args.logo_path
+				) {
+					return fail(
+						"logo_treatment/logo_position/logo_duration_seconds require logo_path (the logo image they style). Provide logo_path or drop these settings.",
+					);
+				}
+				if (
+					args.product_description !== undefined &&
+					!args.product_image_path
+				) {
+					return fail(
+						"product_description requires product_image_path (the product image it describes). Provide product_image_path or drop product_description.",
+					);
+				}
 
-			const created = await client.post<{ data: { slug: string } }>(
-				"/editor",
-				{
-					language: args.language ?? "en",
-					product_prompt: args.product_prompt,
-					product_subject: args.product_subject,
-					project_intent: args.project_intent,
-					creative_format: args.creative_format,
-					visual_language: args.visual_language,
-					theme: args.theme,
-					voice_id: args.voice_id,
-					export_aspect_ratio: args.export_aspect_ratio,
-				},
-				// Fold every create-affecting param into the key so two calls that
-				// differ only by style/theme/voice/aspect get distinct drafts.
-				// Composition lives in core.ts, shared with the golden-pin test.
-				editorAdCreateKey(args),
-			);
-			const slug = created.data.slug;
-			const started = await client.post<{ data: unknown }>(
-				`/editor/${slug}/autopilot`,
-				undefined,
-				// Fold the create-affecting params into the start key so it tracks
-				// inputs, not just the slug. Self-consistent per-tool only: this key
-				// is compared against retries of *this* tool on *this* slug. The
-				// field set/order differs from make_video / start_autopilot on
-				// purpose (server cache is path+key scoped, slug is unique per
-				// draft), so the keys are not interchangeable across tools.
-				// Composition lives in core.ts, shared with the golden-pin test.
-				editorAdAutopilotKey(slug, args),
-			);
-			const status = normalizeStatus("editor", slug, asRecord(started).data);
-			return ok({ slug, kind: "editor", status, next: "wait_for_completion" });
+				// Validate every local asset before creating even a free draft, so a typo,
+				// traversal attempt, bad extension, or oversized logo cannot leave an
+				// orphaned project behind.
+				if (args.product_image_path) {
+					productImage = await prepareImageUpload(
+						args.product_image_path,
+						MAX_PRODUCT_IMAGE_BYTES,
+					);
+					prepared.push(productImage);
+				}
+				if (args.closing_image_path) {
+					closingImage = await prepareImageUpload(
+						args.closing_image_path,
+						MAX_CLOSING_IMAGE_BYTES,
+					);
+					prepared.push(closingImage);
+				}
+				if (args.logo_path) {
+					logo = await prepareImageUpload(args.logo_path, MAX_LOGO_BYTES);
+					prepared.push(logo);
+				}
+
+				const created = await client.post<{ data: { slug: string } }>(
+					"/editor",
+					{
+						language: args.language ?? "en",
+						product_prompt: args.product_prompt,
+						product_subject: args.product_subject,
+						project_intent: args.project_intent,
+						creative_format: args.creative_format,
+						visual_language: args.visual_language,
+						theme: args.theme,
+						voice_id: args.voice_id,
+						export_aspect_ratio: args.export_aspect_ratio,
+						cast_mode: args.cast_mode,
+					},
+					// Fold every create-affecting param into the key so two calls that
+					// differ only by style/theme/voice/aspect get distinct drafts.
+					// Composition lives in core.ts, shared with the golden-pin test.
+					editorAdCreateKey({
+						...args,
+						product_image_identity: productImage
+							? preparedUploadIdentity(productImage)
+							: undefined,
+						closing_image_identity: closingImage
+							? preparedUploadIdentity(closingImage)
+							: undefined,
+						logo_identity: logo ? preparedUploadIdentity(logo) : undefined,
+					}),
+				);
+				const slug = created.data.slug;
+				let configured = {} as Record<string, unknown>;
+				if (
+					args.product_image_path ||
+					args.closing_image_path ||
+					args.logo_path
+				) {
+					const current = await client.get<{ data: unknown }>(
+						`/editor/${slug}`,
+					);
+					configured = asRecord(asRecord(current).data);
+				}
+
+				if (productImage && !configured.product_url) {
+					const { s3_key } = await uploadImageFile(
+						client,
+						`/editor/${slug}/product/presign`,
+						productImage,
+						MAX_PRODUCT_IMAGE_BYTES,
+					);
+					await client.post(`/editor/${slug}/product/confirm`, {
+						s3_key,
+						product_description: args.product_description,
+					});
+				}
+				if (closingImage && !configured.closing_image_url) {
+					const { s3_key } = await uploadImageFile(
+						client,
+						`/editor/${slug}/closing-image/presign`,
+						closingImage,
+						MAX_CLOSING_IMAGE_BYTES,
+					);
+					await client.post(`/editor/${slug}/closing-image/confirm`, {
+						s3_key,
+					});
+				}
+				if (logo && !configured.logo_url) {
+					const { s3_key } = await uploadImageFile(
+						client,
+						`/editor/${slug}/logo/presign`,
+						logo,
+						MAX_LOGO_BYTES,
+					);
+					await client.post(`/editor/${slug}/logo/confirm`, { s3_key });
+				}
+				const logoSettings: Record<string, unknown> = {};
+				if (args.logo_treatment !== undefined)
+					logoSettings.logo_treatment = args.logo_treatment;
+				if (args.logo_position !== undefined)
+					logoSettings.logo_position = args.logo_position;
+				if (args.logo_duration_seconds !== undefined)
+					logoSettings.logo_duration_seconds = args.logo_duration_seconds;
+				if (args.logo_path && Object.keys(logoSettings).length > 0)
+					await client.patch(`/editor/${slug}/logo`, logoSettings);
+
+				const quote = await editorAutopilotQuote(client, slug);
+				const overCap =
+					args.max_credits !== undefined &&
+					quote.estimated_credits !== null &&
+					quote.estimated_credits > args.max_credits;
+				if (
+					args.max_credits === undefined ||
+					quote.estimated_credits === null ||
+					overCap ||
+					!quote.affordable
+				) {
+					const note =
+						args.max_credits === undefined
+							? `Free draft configured. Estimated ${quote.estimated_credits ?? "?"} credits (have ${quote.available_credits ?? "?"}); nothing charged. Relaunch with start_autopilot({ slug: "${slug}", max_credits: ${quote.estimated_credits ?? "<approved cap>"} }).`
+							: quote.estimated_credits === null
+								? "Pricing is temporarily unavailable, so the paid pipeline was not started. Retry the quote later."
+								: overCap
+									? `Estimated ${quote.estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged.`
+									: `Not enough credits (needs ${quote.estimated_credits}, have ${quote.available_credits ?? "?"}); nothing charged.`;
+					return ok({
+						slug,
+						kind: "editor",
+						...quote,
+						charged: false,
+						note,
+						next: "start_autopilot",
+					});
+				}
+
+				const started = await client.post<{ data: unknown }>(
+					`/editor/${slug}/autopilot`,
+					{ max_credits: args.max_credits },
+					// Fold the create-affecting params into the start key so it tracks
+					// inputs, not just the slug. Self-consistent per-tool only: this key
+					// is compared against retries of *this* tool on *this* slug. The
+					// field set/order differs from make_video / start_autopilot on
+					// purpose (server cache is path+key scoped, slug is unique per
+					// draft), so the keys are not interchangeable across tools.
+					// Composition lives in core.ts, shared with the golden-pin test.
+					editorAdAutopilotKey(slug, args),
+				);
+				const status = normalizeStatus("editor", slug, asRecord(started).data);
+				return ok({
+					slug,
+					kind: "editor",
+					status,
+					...quote,
+					charged: true,
+					next: "wait_for_completion",
+				});
+			} finally {
+				await Promise.all(prepared.map(closePreparedUploadFile));
+			}
 		},
 	),
 );
@@ -2704,8 +3274,9 @@ registerTool(
 		title: "Start autopilot on an existing editor draft",
 		description:
 			"Starts server-orchestrated autopilot (scenario → segments → narration → voice → music → render) on an " +
-			"EXISTING editor project/draft. Spends credits — preview the estimate first with the autopilot/cost endpoint " +
-			"or make_video({ dry_run:true }). Each call is a genuine start attempt (like tapping Launch in the app): " +
+			"EXISTING editor project/draft. Without max_credits it returns the live quote and charges nothing. Supply an " +
+			"explicit max_credits cap to authorize launch; the tool refuses if pricing is unavailable, the estimate exceeds " +
+			"the cap, or the balance is insufficient. Each authorized call is a genuine start attempt (like tapping Launch in the app): " +
 			"if a run is already in progress for this slug the server returns already_running — it never double-starts " +
 			"or double-charges. Once finished, failed, or cancelled, calling again relaunches it (resume after a top-up, raising your spend cap, or a mid-pipeline failure). Then poll with " +
 			'wait_for_completion({ slug, kind: "editor" }).',
@@ -2730,7 +3301,16 @@ registerTool(
 				.string()
 				.optional()
 				.describe("Optional freeform brief to set/replace before launch."),
+			max_credits: z
+				.number()
+				.int()
+				.nonnegative()
+				.optional()
+				.describe(
+					"Explicit spend cap. Omit to quote only; no credits are charged.",
+				),
 		},
+		outputSchema: createEditorOutput,
 		annotations: { title: "Start autopilot", ...WRITE, idempotentHint: false },
 	},
 	tool(
@@ -2740,6 +3320,7 @@ registerTool(
 				language?: string;
 				product_subject?: string;
 				product_prompt?: string;
+				max_credits?: number;
 			},
 			client,
 		) => {
@@ -2749,16 +3330,47 @@ registerTool(
 			if (promptErr) return fail(promptErr);
 
 			const slug = args.slug;
-			const overrides: Record<string, unknown> = {};
+			const overrides: {
+				language?: string;
+				product_subject?: string;
+				product_prompt?: string;
+			} = {};
 			if (args.language !== undefined) overrides.language = args.language;
 			if (args.product_subject !== undefined)
 				overrides.product_subject = args.product_subject;
 			if (args.product_prompt !== undefined)
 				overrides.product_prompt = args.product_prompt;
 
+			const quote = await editorAutopilotQuote(client, slug, overrides);
+			const overCap =
+				args.max_credits !== undefined &&
+				quote.estimated_credits !== null &&
+				quote.estimated_credits > args.max_credits;
+			if (
+				args.max_credits === undefined ||
+				quote.estimated_credits === null ||
+				overCap ||
+				!quote.affordable
+			) {
+				return ok({
+					slug,
+					kind: "editor",
+					...quote,
+					charged: false,
+					note:
+						args.max_credits === undefined
+							? `Quote only: estimated ${quote.estimated_credits ?? "?"} credits (have ${quote.available_credits ?? "?"}). Pass max_credits to authorize launch.`
+							: quote.estimated_credits === null
+								? "Pricing is unavailable; launch refused because the spend cap cannot be enforced."
+								: overCap
+									? `Estimated ${quote.estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged.`
+									: `Not enough credits (needs ${quote.estimated_credits}, have ${quote.available_credits ?? "?"}); nothing charged.`,
+				});
+			}
+
 			const started = await client.post<{ data: unknown }>(
 				`/editor/${slug}/autopilot`,
-				Object.keys(overrides).length > 0 ? overrides : undefined,
+				{ ...overrides, max_credits: args.max_credits },
 				// Each call is a genuine new start attempt (matching the in-app Launch
 				// button). A per-invocation nonce makes the idempotency key unique so the
 				// server's 24h idempotency cache can't replay a PRIOR start's response on
@@ -2773,6 +3385,8 @@ registerTool(
 				slug,
 				kind: "editor",
 				status,
+				...quote,
+				charged: true,
 				next: "wait_for_completion",
 			});
 		},
@@ -2840,7 +3454,7 @@ registerTool(
 		title: "Create an editor draft (no autopilot)",
 		description:
 			"Creates an editor project from a product prompt and stops (NO autopilot). Costs 0 credits. Returns the " +
-			"slug. Use this to drive the pipeline step by step (vs create_editor_ad which runs autopilot end to end). " +
+			"slug. Use this to drive the pipeline step by step (vs create_editor_ad which configures, quotes, and can launch autopilot with a spend cap). " +
 			"Each AI-generated scene renders to a fixed 8 seconds (uploaded clips keep their own length). " +
 			"product_prompt is optional content: send 10–5000 chars, or omit it entirely (empty is treated as omit).",
 		inputSchema: {
@@ -3921,7 +4535,7 @@ registerTool(
 			"duration. Runs presign → PUT (resumable multipart for large files) → confirm, then polls until the " +
 			"upload is processed (ready). file_path is a LOCAL path confined to HUBFLUENCER_INPUT_DIR (or cwd). Accepted: " +
 			VIDEO_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤500 MB, ≤5 min). Costs 0 credits. If add_to_timeline is false (default true) the clip is uploaded but not " +
+			" (≤500 MB decimal = 500,000,000 bytes, ≤5 min). Costs 0 credits. If add_to_timeline is false (default true) the clip is uploaded but not " +
 			"placed — call add_segment_from_upload later.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
@@ -4068,7 +4682,8 @@ registerTool(
 		description:
 			"Sets a specific scene's video from an existing asset — either a ready upload (upload_id) OR a completed scene " +
 			"in the same project (source_segment_id). Provide EXACTLY ONE. 0 credits. Use it to reuse one uploaded clip " +
-			"across scenes, or to swap a generated scene for your own footage.",
+			"across scenes, or to swap a generated scene for your own footage. The response includes continuity impact and " +
+			"current narration/voice/music staleness. If the replacement duration differs, regenerate stale audio before render.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			segment_id: z
@@ -4111,7 +4726,58 @@ registerTool(
 				`/editor/${args.slug}/segments/${String(args.segment_id)}/use-asset`,
 				body,
 			);
-			return ok(asRecord(res).data ?? res);
+			const segment = asRecord(asRecord(res).data ?? res);
+			const impact = asRecord(segment.impact);
+			const staleSegmentIds = Array.isArray(impact.stale_video_segment_ids)
+				? impact.stale_video_segment_ids
+				: [];
+			const requiresRegeneration =
+				impact.requires_regeneration === true || staleSegmentIds.length > 0;
+			// The swap has already SUCCEEDED (the POST above returned). The follow-up
+			// GET only enriches the response with project-level audio staleness — a
+			// transient failure on that read must NOT turn a successful swap into a
+			// thrown error, or the agent would believe the swap failed and retry it,
+			// minting a redundant segment version. Guard it: on failure return success
+			// with the mutation's own impact data and audio-staleness marked unknown
+			// (null) rather than propagating.
+			let timeline: Record<string, unknown>;
+			try {
+				const current = await client.get<{ data: unknown }>(
+					`/editor/${args.slug}`,
+				);
+				const editor = asRecord(asRecord(current).data);
+				timeline = {
+					narration_stale: editor.narration_stale === true,
+					voice_stale: editor.voice_stale === true,
+					music_stale: editor.music_stale === true,
+					stale_segment_ids: staleSegmentIds,
+					requires_regeneration: requiresRegeneration,
+				};
+			} catch {
+				timeline = {
+					// Enrichment GET failed after a successful swap — audio staleness is
+					// unknown (null, not false) so the agent doesn't assume "not stale".
+					narration_stale: null,
+					voice_stale: null,
+					music_stale: null,
+					stale_segment_ids: staleSegmentIds,
+					requires_regeneration: requiresRegeneration,
+					enrichment_unavailable: true,
+				};
+			}
+			return ok({
+				...segment,
+				timeline,
+				next:
+					timeline.requires_regeneration ||
+					timeline.narration_stale ||
+					timeline.voice_stale ||
+					timeline.music_stale
+						? "Regenerate the reported stale scenes/audio before render."
+						: timeline.enrichment_unavailable
+							? "Scene swap succeeded, but audio staleness could not be verified (enrichment fetch failed) — call get_status before render to confirm."
+							: "Timeline is current and can be rendered.",
+			});
 		},
 	),
 );
@@ -4123,7 +4789,7 @@ registerTool(
 		description:
 			"Uploads a local product image and attaches it to the project as the product. Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤20 MB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. The FIRST product added " +
+			" (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. The FIRST product added " +
 			"defaults every pending AI scene to feature it 'throughout' (change with set_product_placement). Optional " +
 			"description (≤500 chars) guides how it's woven into scenes.",
 		inputSchema: {
@@ -4148,6 +4814,7 @@ registerTool(
 				client,
 				`/editor/${args.slug}/product/presign`,
 				args.file_path,
+				MAX_PRODUCT_IMAGE_BYTES,
 			);
 			const res = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/product/confirm`,
@@ -4190,7 +4857,7 @@ registerTool(
 	{
 		title: "Set the closing-card image (0 credits)",
 		description:
-			"Sets the optional ~2s end-card image. Either upload a local file (file_path; .jpg/.jpeg/.png ≤20 MB, confined " +
+			"Sets the optional ~2s end-card image. Either upload a local file (file_path; .jpg/.jpeg/.png ≤20 MiB, confined " +
 			"to HUBFLUENCER_INPUT_DIR/cwd) OR reuse the project's product image (from_product:true — a 0-credit server-side " +
 			"copy, no upload). If a closing image already exists, pass overwrite:true to replace it (else " +
 			"editor_closing_image_exists).",
@@ -4241,6 +4908,7 @@ registerTool(
 				client,
 				`/editor/${args.slug}/closing-image/presign`,
 				args.file_path,
+				MAX_CLOSING_IMAGE_BYTES,
 			);
 			const res = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/closing-image/confirm`,
@@ -4256,7 +4924,7 @@ registerTool(
 	{
 		title: "Set a brand logo overlay (0 credits)",
 		description:
-			"Uploads a local brand logo and overlays it on the video. Accepted: .png/.jpg/.jpeg (≤20 MB; PNG keeps " +
+			"Uploads a local brand logo and overlays it on the video. Accepted: .png/.jpg/.jpeg (≤1 MiB; PNG keeps " +
 			"transparency), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. Optional placement controls: treatment, " +
 			"position, duration_seconds.",
 		inputSchema: {
@@ -4286,6 +4954,7 @@ registerTool(
 				client,
 				`/editor/${args.slug}/logo/presign`,
 				args.file_path,
+				MAX_LOGO_BYTES,
 			);
 			const confirmed = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/logo/confirm`,
@@ -4324,7 +4993,7 @@ registerTool(
 			"Uploads a local product image and attaches it to a SHORT so the product is woven into the footage. " +
 			"Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤20 MB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Optional description " +
+			" (≤20 MiB = 20,971,520 bytes), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Optional description " +
 			"(≤500 chars) guides how it's featured. Attach BEFORE generate_short so the product is part of the scenes. " +
 			"(This is the shorts equivalent of set_product for editor projects.)",
 		inputSchema: {
@@ -4371,26 +5040,48 @@ registerTool(
 			"Uploads a local image as the SHORT's end-card poster — a closing still shown at the end (extends the " +
 			"render from 12s to 14s). Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤20 MB), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " +
+			" (≤20 MiB = 20,971,520 bytes), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " +
 			"again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
 		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 ──────────────────────────────────────────────────────────
@@ -4419,8 +5110,13 @@ registerTool(
 	{
 		title: "Wait for a render to finish",
 		description:
-			"Polls status (emitting progress) until terminal (ready/failed) or the wait budget is exhausted. " +
+			"Polls status (emitting progress) until terminal or the wait budget is exhausted. " +
 			"Generation can take several minutes; if it returns terminal=false, call again to keep waiting. " +
+			"terminal=true does NOT always mean ready=true: an editor can go terminal in a needs-action stage " +
+			'(stage "editing_required" — a delivered render is stale after edits, regenerate the reported scenes/audio; ' +
+			'stage "insufficient_credits" — a batch is parked, top up or reduce scope; ' +
+			'stage "idle" — a draft with nothing generating, start generation first) that only a further tool call ' +
+			"can advance — do NOT just re-poll those. " +
 			"Pass save_path to download the finished MP4 when it's ready (e.g. to resume a make_video that timed out mid-render). " +
 			'Works for kind:"slider" too, but a carousel has no MP4 — it just goes terminal when composited; read the slide ' +
 			"images with get_slider (save_path is ignored for sliders).",
@@ -5796,7 +6492,7 @@ registerTool(
 		return ok({
 			...episode,
 			next: episode.draft_slug
-				? "Generate this draft EXPLICITLY (a separate, PAID step): editor_ad/short → start_autopilot({ slug }); carousel → generate_slider({ slug })."
+				? "Price this draft with start_autopilot({ slug }); after approval launch it with start_autopilot({ slug, max_credits: approved_cap }). Carousel generation remains a separate paid generate_slider call."
 				: "Draft created — review it with list_series_episodes.",
 		});
 	}),
@@ -6603,7 +7299,7 @@ registerTool(
 		title: "Upload a local file to your reusable asset catalog",
 		description:
 			"Uploads a local IMAGE or VIDEO into your reusable asset catalog so it can be reused across projects. " +
-			`Allowed types: ${CATALOG_ASSET_EXTS.map((e) => `.${e}`).join(", ")} — images ≤20 MiB, videos ≤500 MB. ` +
+			`Allowed types: ${CATALOG_ASSET_EXTS.map((e) => `.${e}`).join(", ")} — images ≤20 MiB (20,971,520 bytes), videos ≤500 MB decimal (500,000,000 bytes). ` +
 			"Runs presign → PUT → confirm; the confirm HEADs the object and validates size/type, so a mismatch 422s. " +
 			"For a VIDEO you MUST pass duration_seconds (≤60; the server rejects a video with no/over-long duration). " +
 			"Spends 0 credits. Scope: video:generate. Rate limit: 30/min. Requires an ACTIVE SUBSCRIPTION (402 " +