@hubfluencer/mcp 0.11.0 → 0.13.0

package/src/index.ts

@@ -171,9 +171,9 @@ async function editorAutopilotQuote(
 	try {
 		const params = new URLSearchParams();
 		if (overrides.language) params.set("language", overrides.language);
-		if (overrides.product_subject)
+		if (overrides.product_subject !== undefined)
 			params.set("product_subject", overrides.product_subject);
-		if (overrides.product_prompt)
+		if (overrides.product_prompt !== undefined)
 			params.set("product_prompt", overrides.product_prompt);
 		if (overrides.restart) params.set("restart", "true");
 		const query = params.toString();
@@ -565,6 +565,25 @@ const VISUAL_LANGUAGES = [
 	"startup_explainer",
 	"luxury_minimal",
 ] as const;
+// Closed API enum from VideoFactories.ScenarioThemes. Keeping this explicit in
+// MCP prevents an agent typo from spending a round trip on an avoidable 422.
+const SCENARIO_THEMES = [
+	"none",
+	"realistic",
+	"cinematic",
+	"anime",
+	"sci_fi",
+	"fantasy",
+	"noir",
+	"superhero",
+	"horror",
+	"mockumentary",
+	"sports",
+	"gaming",
+	"retro_80s",
+	"minimalist",
+	"cyberpunk",
+] as const;
 // The languages the API's VideoFactory.language accepts (video_factory.ex
 // @supported_languages, validate_inclusion at create + autopilot). It's a CLOSED
 // set of bare ISO-639-1 codes — the server rejects region/script subtags ("en",
@@ -914,12 +933,12 @@ registerTool(
 					"SHORTS + EDITOR: visual style direction and render look. Default app choice is kinetic_creator.",
 				),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
 					"Visual theme: editor genre overlay, and legacy shorts fallback only when visual_language is unset. " +
-						"For editor, when visual_language is set it drives the look and 'none' is ignored. " +
-						"none (literal — no imposed style), realistic (default), cinematic, " +
+						"For editor, visual_language drives the look when present; make_video defaults theme to none " +
+						"(literal — no imposed genre style). Options: none, realistic, cinematic, " +
 						"anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, " +
 						"minimalist, cyberpunk",
 				),
@@ -1115,12 +1134,14 @@ registerTool(
 						voice_id: args.voice_id,
 						creative_format: args.creative_format,
 						visual_language: args.visual_language,
-						theme: args.theme,
+						// Prompt-first default: do not silently inject the API's legacy
+						// realistic/neutral art direction when the caller authored a look.
+						theme: args.theme ?? "none",
 					},
 					// Fold every create-affecting param into the key so two calls that
 					// differ only by style/theme/voice/aspect get distinct drafts (shared
 					// with the golden-pin test via core.ts).
-					makeVideoEditorCreateKey(args),
+					makeVideoEditorCreateKey({ ...args, theme: args.theme ?? "none" }),
 				);
 				slug = created.data.slug;
 			}
@@ -1530,7 +1551,7 @@ registerTool(
 					"Visual language for Veo direction and render styling. Good default: kinetic_creator.",
 				),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
 					"Deprecated for shorts: legacy visual theme used only when visual_language is unset.",
@@ -1837,7 +1858,7 @@ registerTool(
 				.optional()
 				.describe("Visual language for Veo direction and render styling."),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
 					"Deprecated for shorts: legacy visual theme used only when visual_language is unset.",
@@ -2529,6 +2550,55 @@ registerTool(
 	}),
 );
 
+registerTool(
+	"cancel_short_generation",
+	{
+		title: "Cancel a running short generation",
+		description:
+			"Stops the caller-observed paid Short attempt, fences late provider callbacks, and refunds the 15-credit " +
+			"generation exactly once. Pass generation_attempt from get_status so a delayed command cannot cancel a " +
+			"newer run on the same draft. The draft is preserved for editing and regeneration. Safe to repeat with " +
+			"the same attempt after a successful cancellation. Scope: video:generate.",
+		inputSchema: {
+			slug: z.string().describe("Slug of the processing short"),
+			generation_attempt: z
+				.number()
+				.int()
+				.min(0)
+				.describe("generation_attempt from the latest get_status response"),
+		},
+		annotations: {
+			title: "Cancel short generation",
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true,
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { slug: string; generation_attempt: number }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/shorts/${args.slug}/cancel`,
+			{ generation_attempt: args.generation_attempt },
+			undefined,
+		);
+		const data = asRecord(asRecord(res).data ?? res);
+		return ok({
+			...data,
+			slug: args.slug,
+			charged: false,
+			// The cancel endpoint returns the short's STATE, not a refund receipt,
+			// so don't assert refunded:true on every call — a repeat cancel is a
+			// no-op that mints no new credits. Echo the server's own flag if it ever
+			// sends one; otherwise describe the honest idempotent settlement.
+			refund:
+				"refunded" in data
+					? data.refunded
+					: "settled (idempotent — no new credits minted on repeat)",
+			next: "Edit the preserved draft, then call generate_short when ready.",
+		});
+	}),
+);
+
 registerTool(
 	"rerender_short",
 	{
@@ -3020,12 +3090,12 @@ registerTool(
 			"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 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.",
+			"A product image is analyzed into semantic project context and sent as a product-identity reference to every " +
+			"generated Editor scene. The exact photo is also linked as the closing image unless a separate closing image " +
+			"was authored; generated fine label text can still vary. Scene prompts are the complete content contract: describe any people, " +
+			"products, visual continuity, absences, and composition directly in the brief. (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.)",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -3066,10 +3136,10 @@ registerTool(
 					"Visual style direction and render look. Good default: kinetic_creator. When set it drives the look and a theme of 'none' is ignored.",
 				),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.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.',
+					'Optional visual theme / genre overlay (default "none", so scene prompts drive the look). One of: none, realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
 				),
 			voice_id: z
 				.string()
@@ -3085,14 +3155,14 @@ registerTool(
 				.string()
 				.optional()
 				.describe(
-					"Local product image (.jpg/.jpeg/.png, ≤8 MiB) to attach before autopilot.",
+					"Local product image (.jpg/.jpeg/.png, ≤8 MiB) used as the product-identity reference for every generated Editor scene and linked as the exact closing image unless one was already authored.",
 				),
 			product_description: z
 				.string()
 				.max(500)
 				.optional()
 				.describe(
-					"Exact product/character description used with product_image_path.",
+					"Product description used to ground the scenario and narration when product_image_path is supplied.",
 				),
 			closing_image_path: z
 				.string()
@@ -3122,12 +3192,6 @@ registerTool(
 				.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()
@@ -3163,7 +3227,6 @@ registerTool(
 					| "bottom-left"
 					| "bottom-right";
 				logo_duration_seconds?: number;
-				cast_mode?: "product_only";
 				max_credits?: number;
 			},
 			client,
@@ -3177,11 +3240,6 @@ registerTool(
 				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
@@ -3238,16 +3296,16 @@ registerTool(
 						project_intent: args.project_intent,
 						creative_format: args.creative_format,
 						visual_language: args.visual_language,
-						theme: args.theme,
+						theme: args.theme ?? "none",
 						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,
+						theme: args.theme ?? "none",
 						product_image_identity: productImage
 							? preparedUploadIdentity(productImage)
 							: undefined,
@@ -3401,12 +3459,14 @@ registerTool(
 				.optional()
 				.describe(
 					"Optional locked product / main subject applied before launch so the AI cannot invent an " +
-						"unrelated product.",
+						"unrelated product. Omit to keep the stored subject; send blank to clear it.",
 				),
 			product_prompt: z
 				.string()
 				.optional()
-				.describe("Optional freeform brief to set/replace before launch."),
+				.describe(
+					"Optional freeform brief to set/replace before launch. Omit to keep the stored brief; send blank to clear it.",
+				),
 			max_credits: z
 				.number()
 				.int()
@@ -3518,7 +3578,12 @@ registerTool(
 		description:
 			"Recovers an editor whose normalized status is batch_retry_required by atomically re-queueing the failed " +
 			"scene and resuming its prepaid batch. This spends 0 additional credits: the batch generation was already " +
-			"paid. It does not authorize or restart a failed parent Autopilot run; after retrying, wait for the batch " +
+			"paid. Before retrying you may REPAIR the one failed scene: while paused_for_retry, set_segment_prompt can " +
+			"edit that scene's prompt (and use_previous_frame) — but only for the exact failed position the server " +
+			"names in batch_generation_failed_position (from get_editor); the rest of the paused batch stays " +
+			"mutation-locked. Explicit paused retries are capped — once the failure code is free_retries_exhausted a " +
+			"further retry is rejected (start a fresh run instead). It does not authorize or restart a failed parent " +
+			"Autopilot run; after retrying, wait for the batch " +
 			"to settle. If the parent is then terminal, call start_autopilot without max_credits for a fresh quote and " +
 			"relaunch only with an approved cap. A batch parked on " +
 			"insufficient_credits needs a top-up/scope change instead. Scope: video:generate.",
@@ -3530,8 +3595,12 @@ registerTool(
 		},
 	},
 	tool(async (args: { slug: string }, client) => {
+		const command = await observedEditorBatchCommand(client, args.slug, [
+			"paused_for_retry",
+		]);
 		const res = await client.post<{ data: unknown }>(
 			`/video-factories/${args.slug}/retry-batch-segment`,
+			command,
 		);
 		return ok({
 			...asRecord(asRecord(res).data ?? res),
@@ -3548,9 +3617,9 @@ registerTool(
 	{
 		title: "Cancel an editor batch",
 		description:
-			"Cancels an editor batch in awaiting_previews, running, or paused_for_retry so the project can be edited or " +
-			"Autopilot can be started again. Cancellation is destructive: dispatched scene work is stopped and its prepaid " +
-			"credits are not refunded; only an awaiting_previews batch (before dispatch) is refunded by the server. Spends " +
+			"Cancels an editor batch only while it is preparing or paused_for_retry so the project can be edited or " +
+			"Autopilot can be started again. Preparing cancellation releases the uncharged preflight. Cancelling a paused " +
+			"batch is destructive: dispatched scene work is stopped and its prepaid credits are not refunded. Spends " +
 			"0 additional credits. Scope: video:generate.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
 		annotations: {
@@ -3562,8 +3631,13 @@ registerTool(
 		},
 	},
 	tool(async (args: { slug: string }, client) => {
+		const command = await observedEditorBatchCommand(client, args.slug, [
+			"preparing",
+			"paused_for_retry",
+		]);
 		const res = await client.post<{ data: unknown }>(
 			`/video-factories/${args.slug}/cancel-batch`,
+			command,
 		);
 		return ok({
 			...asRecord(asRecord(res).data ?? res),
@@ -3574,6 +3648,50 @@ registerTool(
 	}),
 );
 
+type EditorBatchCommandStatus = "preparing" | "paused_for_retry";
+
+/**
+ * Reads the exact Editor batch ownership token immediately before issuing a
+ * recovery command. The API validates both fields under the factory row lock,
+ * so a replacement run or phase transition between this GET and the POST is a
+ * safe `batch_command_stale` conflict rather than acting on newer work.
+ */
+async function observedEditorBatchCommand(
+	client: HubfluencerClient,
+	slug: string,
+	allowedStatuses: readonly EditorBatchCommandStatus[],
+): Promise<{
+	expected_batch_run_id: string | null;
+	expected_batch_status: EditorBatchCommandStatus;
+}> {
+	const response = await client.get<{ data: unknown }>(`/editor/${slug}`);
+	const state = asRecord(asRecord(response).data);
+	const status = state.batch_generation_status;
+	if (
+		typeof status !== "string" ||
+		!allowedStatuses.includes(status as EditorBatchCommandStatus)
+	) {
+		throw new Error(
+			`Editor batch is not in an allowed phase (${allowedStatuses.join(" or ")}); refresh status before retrying.`,
+		);
+	}
+
+	const runId = state.batch_generation_run_id;
+	if (
+		runId !== null &&
+		(typeof runId !== "string" || runId.trim().length === 0)
+	) {
+		throw new Error(
+			"Editor state did not include a valid batch_generation_run_id; refresh status before retrying.",
+		);
+	}
+
+	return {
+		expected_batch_run_id: runId,
+		expected_batch_status: status as EditorBatchCommandStatus,
+	};
+}
+
 // ── AI assists (free daily quota) ───────────────────────────────────────────
 
 registerTool(
@@ -3671,21 +3789,10 @@ registerTool(
 					"Visual style direction and render look. Good default: kinetic_creator. When set it drives the look and a theme of 'none' is ignored.",
 				),
 			theme: z
-				.string()
-				.optional()
-				.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"])
+				.enum(SCENARIO_THEMES)
 				.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.",
+					'Optional visual theme / genre overlay (default "none", so scene prompts drive the look). One of: none, realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
 				),
 			voice_id: z
 				.string()
@@ -3723,7 +3830,6 @@ registerTool(
 				creative_format?: string;
 				visual_language?: string;
 				theme?: string;
-				cast_mode?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
 				project_intent?: string;
@@ -3736,8 +3842,7 @@ registerTool(
 				product_subject: args.product_subject,
 				creative_format: args.creative_format,
 				visual_language: args.visual_language,
-				theme: args.theme,
-				cast_mode: args.cast_mode,
+				theme: args.theme ?? "none",
 				voice_id: args.voice_id,
 				export_aspect_ratio: args.export_aspect_ratio,
 				project_intent: args.project_intent,
@@ -3757,10 +3862,9 @@ registerTool(
 					args.language ?? "en",
 					args.creative_format ?? "",
 					args.visual_language ?? "",
-					args.theme ?? "",
+					args.theme ?? "none",
 					args.voice_id ?? "",
 					args.export_aspect_ratio ?? "",
-					args.cast_mode ?? "",
 				),
 			);
 			return ok({
@@ -3788,6 +3892,9 @@ function conciseEditorState(value: unknown): Record<string, unknown> {
 		"scenario_apply_status",
 		"scenario_prompt",
 		"batch_generation_status",
+		"batch_generation_run_id",
+		"batch_generation_failed_position",
+		"auto_render_after_batch",
 		"narration_status",
 		"narration_script",
 		"narration_stale",
@@ -3811,9 +3918,8 @@ function conciseEditorState(value: unknown): Record<string, unknown> {
 				prompt: segment.prompt,
 				status: segment.status,
 				source_type: segment.source_type,
+				generation_claim_token: segment.generation_claim_token,
 				use_previous_frame: segment.use_previous_frame,
-				protagonist_presence: segment.protagonist_presence,
-				cast_mode_snapshot: segment.cast_mode_snapshot,
 				video_stale: segment.video_stale,
 				error_code: segment.error_code,
 				error_message: segment.error_message,
@@ -3828,7 +3934,7 @@ registerTool(
 	{
 		title: "Get editor state (review step)",
 		description:
-			"Returns the full editor state by default for backward compatibility. Pass response_format:'concise' for a smaller review projection containing orchestration, scenario, scene prompts/status, narration, audio, render, spend, and quota.",
+			"Returns the full editor state by default for backward compatibility. Pass response_format:'concise' for a smaller review projection containing orchestration, scenario, scene prompts/status, narration_status, current_audio, current_music, latest_render, batch_generation_status, spend, and quota.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			response_format: z.enum(["concise", "full"]).default("full"),
@@ -3898,19 +4004,19 @@ registerTool(
 				.optional()
 				.describe("How many scenes (3–10, server default 5)"),
 			creative_format: z
-				.enum(CREATIVE_FORMATS)
+				.union([z.enum(CREATIVE_FORMATS), z.literal("")])
 				.optional()
 				.describe(
 					"Persist the narrative arc / segment structure before generating. Omit to leave it unchanged; pass an empty string to clear.",
 				),
 			visual_language: z
-				.enum(VISUAL_LANGUAGES)
+				.union([z.enum(VISUAL_LANGUAGES), z.literal("")])
 				.optional()
 				.describe(
-					"Persist the visual style / render look before generating. When set it drives the look and a theme of 'none' is ignored.",
+					"Persist the visual style / render look before generating. Omit to leave it unchanged; pass an empty string to clear. When set it drives the look and a theme of 'none' is ignored.",
 				),
 			theme: z
-				.string()
+				.enum(SCENARIO_THEMES)
 				.optional()
 				.describe(
 					"Persist the genre overlay / theme before generating (e.g. realistic, cinematic, anime, none).",
@@ -4219,6 +4325,96 @@ registerTool(
 	}),
 );
 
+registerTool(
+	"cancel_segment_generation",
+	{
+		title: "Cancel one editor scene generation",
+		description:
+			"Stops one caller-observed, individually processing Editor scene; its generation_claim_token fence " +
+			"prevents a delayed command from cancelling a newer attempt. The token is returned by get_editor. " +
+			"Refunds that scene's charge idempotently (a free retry creates no refund). Use cancel_editor_batch or " +
+			"cancel_autopilot for workflow-owned scenes. After cancellation, edit the prompt if needed and call " +
+			"generate_segment again. Scope: video:generate.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segment_id: z
+				.union([z.number(), z.string()])
+				.describe("Processing segment id (from get_editor)"),
+			generation_claim_token: z
+				.string()
+				.nullable()
+				.describe("generation_claim_token from that processing segment"),
+		},
+		annotations: {
+			title: "Cancel segment generation",
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true,
+			idempotentHint: true,
+		},
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				segment_id: number | string;
+				generation_claim_token: string | null;
+			},
+			client,
+		) => {
+			const res = await client.post<{ data: unknown }>(
+				`/editor/${args.slug}/segments/${String(args.segment_id)}/cancel`,
+				{ expected_generation_claim_token: args.generation_claim_token },
+				undefined,
+			);
+			return ok({
+				...asRecord(asRecord(res).data ?? res),
+				slug: args.slug,
+				charged: false,
+				next: "set_segment_prompt or generate_segment",
+			});
+		},
+	),
+);
+
+registerTool(
+	"cancel_autopilot",
+	{
+		title: "Cancel a running Autopilot run",
+		description:
+			"Stops an in-flight Autopilot run on an editor project: sets autopilot_status to cancelled so the " +
+			"orchestration chain (scenario → scenes → narration → voice → music → render) advances no further. Use " +
+			"this when Autopilot is still running and you want to halt it. Any scenes already charged stay charged and " +
+			"all completed work (generated scenes, voice, music, a finished render) is kept — a step already enqueued " +
+			"may still finish, but nothing new is started. Idempotent: a no-op that returns the project unchanged when " +
+			"Autopilot is not running (already completed, failed, cancelled, or never launched), so it is safe to " +
+			"repeat. It does NOT itself refund or re-run anything. For a non-Autopilot prepaid batch " +
+			"(batch_generation_status preparing / paused_for_retry) use cancel_editor_batch; to stop one " +
+			"individually-generated scene use cancel_segment_generation. Scope: video:generate.",
+		inputSchema: { slug: z.string().describe("Editor project slug") },
+		annotations: {
+			title: "Cancel autopilot",
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true,
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { slug: string }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/editor/${args.slug}/autopilot/cancel`,
+			undefined,
+			undefined,
+		);
+		return ok({
+			...asRecord(asRecord(res).data ?? res),
+			slug: args.slug,
+			charged: false,
+			next: "get_status",
+		});
+	}),
+);
+
 registerTool(
 	"regenerate_segment",
 	{
@@ -4280,7 +4476,7 @@ registerTool(
 	{
 		title: "Generate all pending segments (sequential)",
 		description:
-			"Generates every not-yet-completed scene (pending or previously failed) in position order, waiting for each to finish before starting" +
+			"Generates every not-yet-completed scene (pending or previously failed) in position order, waiting for each to finish before starting " +
 			"the next (preserves visual continuity). Each AI-generated scene is a fixed 8 seconds, so N scenes ≈ N×8s of footage. Costs 5 credits per segment generated. Stops and reports what " +
 			"completed if a scene errors on submit (e.g. 402 credits_insufficient) or fails while rendering; if a " +
 			"scene is still rendering past the budget it returns timed_out so you can re-run to continue (completed " +
@@ -4479,15 +4675,15 @@ registerTool(
 	{
 		title: "Set the narration script",
 		description:
-			"Writes your own narration script (1–12000 chars) instead of generating one. Free — no credits, no AI " +
+			"Writes your own narration script (1–10000 chars) instead of generating one. Free — no credits, no AI " +
 			"assist. Use this in place of generate_narration when you want to control the voiceover text. Changing the narration after generating voice/music marks them stale — regenerate (generate_voice / generate_music) before render.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			script: z
 				.string()
 				.min(1)
-				.max(12000)
-				.describe("Narration / voiceover text (1–12000 chars)"),
+				.max(10000)
+				.describe("Narration / voiceover text (1–10000 chars)"),
 		},
 		annotations: { title: "Set narration", ...WRITE, idempotentHint: true },
 	},
@@ -4504,7 +4700,7 @@ registerTool(
 	{
 		title: "Generate the narration (AI assist)",
 		description:
-			"Generates the narration script with AI from the timeline. CONSUMES 1 AI ASSIST (free daily quota) — " +
+			"Generates one coherent narration script with AI from the complete timeline. Every current scene must be completed with a known positive duration, and at least one scene must not keep original upload audio. CONSUMES 1 AI ASSIST (free daily quota) only when a fresh job is queued; an exact retry is deduplicated without consuming another assist — " +
 			"it is free of CREDITS but NOT free of quota. On 429 set auto_unlock:true (1 credit → +10 assists, " +
 			"retried once) or write the script yourself with set_narration_script.",
 		inputSchema: {
@@ -4536,7 +4732,7 @@ registerTool(
 		title: "Generate the voiceover (3 credits)",
 		description:
 			"Synthesizes the voiceover from the narration script. Costs 3 credits. Safe to retry; re-call after changing the narration or voice to regenerate." +
-			"voice_id is REQUIRED — pick one from list_voices (≤64 chars, [A-Za-z0-9_-] only). 402 fails cleanly. Editing the scenario/narration/timeline after this marks the voice stale, and render will 422 (editor_voice_stale) until you re-run generate_voice.",
+			" All current scenes must be completed with known durations first. voice_id is REQUIRED — pick one from list_voices (≤64 chars, [A-Za-z0-9_-] only). 402 fails cleanly. Editing the scenario/narration/timeline after this marks the voice stale, and render will 422 (editor_voice_stale) until you re-run generate_voice.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			voice_id: z
@@ -4627,8 +4823,8 @@ registerTool(
 	{
 		title: "Render the final editor video (0 credits)",
 		description:
-			"Renders the final MP4 from the generated segments + voice + music. Costs 0 credits (any still-ungenerated " +
-			"segments are auto-charged at generation cost first). Render NEVER generates or charges for voice/music; a new " +
+			"Renders the final MP4 from the generated segments + voice + music. Costs 0 credits. Pending or previously " +
+			"failed AI scenes are generated first and charged as a new batch. Render NEVER generates or charges for voice/music; a new " +
 			"music charge comes only from generate_music or an already-running autopilot child job. Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " +
 			'pair with wait_for_completion({ slug, kind: "editor" }) then download_result. ' +
 			"STALENESS: editing the scenario or narration AFTER generating voice/music marks those audio tracks stale, and render then 422s with editor_narration_stale / editor_voice_stale / editor_music_stale — regenerate the named track (generate_narration → generate_voice, and/or generate_music) before rendering.",
@@ -4775,9 +4971,10 @@ registerTool(
 	{
 		title: "List renders for an editor project",
 		description:
-			"Lists every render version for an editor project: {id, version, status, video_url, duration_seconds, " +
-			"error_message, inserted_at}. Use it to find a FAILED render to retry, or to recover a finished video_url " +
-			"(presigned, ~24h). Read-only.",
+			"Lists every render version for an editor project: {id, version, status, video_url, thumbnail_url, " +
+			"duration_seconds, error_message, retryable, combination_hash, is_stale, inserted_at}. Use it to find a " +
+			"FAILED render to retry, or to recover a finished video_url (presigned, ~24h). status is pending | " +
+			"processing | completed | failed; is_stale null means unknown, not current. Read-only.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
 		annotations: { title: "List renders", ...RO },
 	},
@@ -5129,9 +5326,11 @@ registerTool(
 		description:
 			"Uploads a local product image and attaches it to the project as the product. Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
-			" (≤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.",
+			" (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Its pixels guide product identity " +
+			"in every generated Editor scene and its confirmed description grounds scenario and narration. The exact photo " +
+			"is linked as the closing image unless a separate closing image was authored; generated fine label text can still vary. " +
+			"WARNING: replacing the product photo on a project that already has generated AI scenes invalidates their product " +
+			"identity — those scenes were built from the old photo and must be regenerated to match the new one.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			file_path: z
@@ -5165,33 +5364,6 @@ registerTool(
 	),
 );
 
-registerTool(
-	"set_product_placement",
-	{
-		title: "Set default product placement on pending scenes (0 credits)",
-		description:
-			"Sets where the product appears across pending (never-generated) AI scenes. mode is 'throughout' (every scene) " +
-			"or 'end' (closing scene only; requires a first+last-frame capable model). 0 credits. Add a product first with " +
-			"set_product. (There is no 'none' — to remove the product, that's a separate action.)",
-		inputSchema: {
-			slug: z.string().describe("Editor project slug"),
-			mode: z.enum(["throughout", "end"]).describe("'throughout' or 'end'"),
-		},
-		annotations: {
-			title: "Set product placement",
-			...WRITE,
-			idempotentHint: true,
-		},
-	},
-	tool(async (args: { slug: string; mode: "throughout" | "end" }, client) => {
-		const res = await client.post<{ data: unknown }>(
-			`/editor/${args.slug}/product/apply-default-placement`,
-			{ placement: args.mode },
-		);
-		return ok(asRecord(res).data ?? res);
-	}),
-);
-
 registerTool(
 	"set_closing_image",
 	{