@hubfluencer/mcp 0.2.0 → 0.4.0

package/src/index.ts

@@ -39,6 +39,7 @@ import { runLogin } from "./login.js";
 import {
 	IMAGE_EXTS,
 	uploadImageFile,
+	uploadShortPoster,
 	uploadVideoFile,
 	VIDEO_EXTS,
 } from "./uploads.js";
@@ -323,7 +324,7 @@ const WRITE = {
 	openWorldHint: true,
 };
 
-const server = new McpServer({ name: "hubfluencer", version: "0.2.0" });
+const server = new McpServer({ name: "hubfluencer", version: "0.3.0" });
 
 // The SDK's `registerTool` is generic over the Zod input shape; with this many
 // tools its conditional types hit TS2589 ("excessively deep"). Inputs are still
@@ -424,7 +425,12 @@ registerTool(
 			"WITHOUT charging (returns {estimated_credits, available_credits, slug}); pass max_credits to cap the " +
 			"spend. kind defaults to 'auto' — a multi-scene editor ad for ad/promo/story briefs, a single-clip short " +
 			"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.",
+			"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/visual_language so a one-shot short isn't bare — these apply to SHORTS (music_vibe/headline/subheadline " +
+			"are ignored for editor; theme applies to editor and is legacy-only for shorts). 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.",
 		// 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.
@@ -452,6 +458,115 @@ registerTool(
 				.describe(
 					"Preferred narration voice id for editor ads (see list_voices); shorts have no voiceover",
 				),
+			headline: z
+				.string()
+				.optional()
+				.describe(
+					"SHORTS only: the on-screen TITLE overlay (≤160). Set this so the short isn't bare.",
+				),
+			subheadline: z
+				.string()
+				.optional()
+				.describe("SHORTS only: the secondary title / supporting line (≤200)"),
+			text_beats: z
+				.array(z.string())
+				.optional()
+				.describe(
+					"SHORTS only: caption beats shown sequentially instead of a static subheadline (≤8, each ≤120 chars).",
+				),
+			headline_color: z
+				.string()
+				.optional()
+				.describe("SHORTS only: headline hex color, e.g. #ffffff"),
+			subheadline_color: z
+				.string()
+				.optional()
+				.describe("SHORTS only: subheadline hex color, e.g. #ffffff"),
+			accent_color: z
+				.string()
+				.optional()
+				.describe("SHORTS only: 6-digit brand accent hex color, e.g. #09EFBE"),
+			offer_text: z
+				.string()
+				.optional()
+				.describe("SHORTS only: optional offer chip, e.g. -40% (≤16 chars)"),
+			cta_text: z
+				.string()
+				.optional()
+				.describe("SHORTS only: optional CTA pill, e.g. Shop now (≤24 chars)"),
+			badge_text: z
+				.string()
+				.optional()
+				.describe(
+					"SHORTS only: optional badge stamp, e.g. BEST SELLER (≤24 chars)",
+				),
+			star_rating: z
+				.number()
+				.optional()
+				.describe(
+					"SHORTS only: optional 0..5 star rating under the subheadline",
+				),
+			text_position: z
+				.enum(["top", "center", "bottom"])
+				.optional()
+				.describe("SHORTS only: title overlay position (default bottom)"),
+			text_animation: z
+				.enum([
+					"reveal",
+					"typewriter",
+					"fade_in",
+					"pop",
+					"bounce",
+					"word_stagger",
+					"word_spotlight",
+				])
+				.optional()
+				.describe("SHORTS only: title overlay animation (default fade_in)"),
+			font_family: z
+				.string()
+				.optional()
+				.describe(
+					"SHORTS only: overlay font family, e.g. ShortFontSpaceGrotesk",
+				),
+			music_vibe: z
+				.string()
+				.optional()
+				.describe(
+					"SHORTS only: music mood — Upbeat (default), Cinematic, Minimal, Luxury, Playful, Jazz",
+				),
+			creative_format: z
+				.enum([
+					"problem_solution",
+					"mistake_fix",
+					"myth_vs_reality",
+					"before_after",
+					"proof_demo",
+					"product_reveal",
+				])
+				.optional()
+				.describe("SHORTS only: segment structure. Omit for Auto/generic."),
+			visual_language: z
+				.enum([
+					"kinetic_creator",
+					"premium_editorial",
+					"cinematic_product",
+					"ugc_realism",
+					"startup_explainer",
+					"luxury_minimal",
+				])
+				.optional()
+				.describe(
+					"SHORTS only: visual style direction and render look. Default app choice is kinetic_creator.",
+				),
+			theme: z
+				.string()
+				.optional()
+				.describe(
+					"Visual theme: editor style, and legacy shorts fallback only when visual_language is unset. " +
+						"none (literal — no imposed style), realistic (default), cinematic, " +
+						"anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, " +
+						"minimalist, cyberpunk",
+				),
 			save_path: z
 				.string()
 				.optional()
@@ -486,6 +601,23 @@ registerTool(
 				language?: string;
 				aspect?: string;
 				voice_id?: string;
+				headline?: string;
+				subheadline?: string;
+				text_beats?: string[];
+				headline_color?: string;
+				subheadline_color?: string;
+				accent_color?: string;
+				offer_text?: string;
+				cta_text?: string;
+				badge_text?: string;
+				star_rating?: number;
+				text_position?: string;
+				text_animation?: string;
+				font_family?: string;
+				music_vibe?: string;
+				creative_format?: string;
+				visual_language?: string;
+				theme?: string;
 				save_path?: string;
 				max_wait_seconds?: number;
 				dry_run?: boolean;
@@ -515,13 +647,57 @@ registerTool(
 			//    make_video (or a dry_run then a real run) reuses this same draft.
 			let slug: string;
 			if (kind === "short") {
+				// Carry the creative fields inline so a one-shot short can be titled
+				// and branded (headline/subheadline/music_vibe are short-only; theme
+				// applies to both kinds).
 				const created = await client.post<{ data: { slug: string } }>(
 					"/shorts",
-					{ product_prompt: args.prompt, language: args.language },
+					{
+						product_prompt: args.prompt,
+						language: args.language,
+						headline: args.headline,
+						subheadline: args.subheadline,
+						text_beats: args.text_beats,
+						headline_color: args.headline_color,
+						subheadline_color: args.subheadline_color,
+						accent_color: args.accent_color,
+						offer_text: args.offer_text,
+						cta_text: args.cta_text,
+						badge_text: args.badge_text,
+						star_rating: args.star_rating,
+						short_text_position: args.text_position,
+						short_text_animation: args.text_animation,
+						short_font_family: args.font_family,
+						music_vibe: args.music_vibe,
+						creative_format: args.creative_format,
+						visual_language: args.visual_language,
+						theme: args.theme,
+					},
 					// Fold every create-affecting param into the key: two calls that
-					// differ only in language must NOT dedup to the same draft, and a
-					// transport retry of an identical call must reuse it.
-					idemKey("make-short", args.prompt, args.language ?? ""),
+					// differ only in a creative field must NOT dedup to the same draft,
+					// and a transport retry of an identical call must reuse it.
+					idemKey(
+						"make-short",
+						args.prompt,
+						args.language ?? "",
+						args.headline ?? "",
+						args.subheadline ?? "",
+						JSON.stringify(args.text_beats ?? []),
+						args.headline_color ?? "",
+						args.subheadline_color ?? "",
+						args.accent_color ?? "",
+						args.offer_text ?? "",
+						args.cta_text ?? "",
+						args.badge_text ?? "",
+						String(args.star_rating ?? ""),
+						args.text_position ?? "",
+						args.text_animation ?? "",
+						args.font_family ?? "",
+						args.music_vibe ?? "",
+						args.creative_format ?? "",
+						args.visual_language ?? "",
+						args.theme ?? "",
+					),
 				);
 				slug = created.data.slug;
 			} else {
@@ -532,6 +708,7 @@ registerTool(
 						product_prompt: args.prompt,
 						export_aspect_ratio: args.aspect,
 						voice_id: args.voice_id,
+						theme: args.theme,
 					},
 					idemKey(
 						"make-editor",
@@ -539,6 +716,7 @@ registerTool(
 						args.language ?? "en",
 						args.aspect ?? "",
 						args.voice_id ?? "",
+						args.theme ?? "",
 					),
 				);
 				slug = created.data.slug;
@@ -677,7 +855,23 @@ registerTool(
 		inputSchema: {},
 		annotations: { title: "Get credits", ...RO },
 	},
-	tool(async (_args, client) => ok(await client.get("/studio/credits"))),
+	tool(async (_args, client) => {
+		const res = await client.get<{ data: unknown }>("/studio/credits");
+		const d = asRecord(asRecord(res).data);
+		// Whitelist generation-relevant fields only. Deliberately DROP
+		// `first_editor_video_pack_available`: it's a purchase-funnel flag for the
+		// PAID one-time starter pack (33 credits — not free), and this server has
+		// no billing scope, so it can't act on it. Passing it through only invited
+		// the agent to misread `true` as "your first video may be free", which
+		// contradicts the product (the first video is never free).
+		return ok({
+			credits: d.credits,
+			spendable_credits: d.spendable_credits,
+			reserved_credits: d.reserved_credits,
+			remaining_reserved_credits: d.remaining_reserved_credits,
+			message: d.message,
+		});
+	}),
 );
 
 // ── Voices ────────────────────────────────────────────────────────────────
@@ -770,8 +964,13 @@ registerTool(
 	{
 		title: "Create a short (draft)",
 		description:
-			"Creates a short draft from a product prompt (min 10 chars). Returns the slug. Costs 0 credits. " +
-			"Follow with generate_short to render. Prefer make_video for the one-shot path.",
+			"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. " +
+			"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 " +
+			"(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: {
 			product_prompt: z
 				.string()
@@ -781,21 +980,222 @@ registerTool(
 				.string()
 				.optional()
 				.describe('Language code, e.g. "en" (default)'),
-			theme: z.string().optional(),
-			headline: z.string().optional(),
-			subheadline: z.string().optional(),
-			music_vibe: z.string().optional(),
+			headline: z
+				.string()
+				.max(160)
+				.optional()
+				.describe(
+					"The on-screen TITLE composited over the short (poster text overlay). ≤160 chars. Set this.",
+				),
+			subheadline: z
+				.string()
+				.max(200)
+				.optional()
+				.describe(
+					"The SECONDARY title / supporting line under the headline. ≤200 chars.",
+				),
+			creative_format: z
+				.enum([
+					"problem_solution",
+					"mistake_fix",
+					"myth_vs_reality",
+					"before_after",
+					"proof_demo",
+					"product_reveal",
+				])
+				.optional()
+				.describe(
+					"Optional structure: problem_solution, mistake_fix, myth_vs_reality, before_after, proof_demo, product_reveal. Omit for Auto.",
+				),
+			visual_language: z
+				.enum([
+					"kinetic_creator",
+					"premium_editorial",
+					"cinematic_product",
+					"ugc_realism",
+					"startup_explainer",
+					"luxury_minimal",
+				])
+				.optional()
+				.describe(
+					"Visual language for Veo direction and render styling. Good default: kinetic_creator.",
+				),
+			theme: z
+				.string()
+				.optional()
+				.describe(
+					"Deprecated for shorts: legacy visual theme used only when visual_language is unset.",
+				),
+			music_vibe: z
+				.string()
+				.optional()
+				.describe(
+					"Background-music mood. Recognized: Upbeat (default), Cinematic, Minimal, Luxury, Playful, Jazz.",
+				),
+			music_instruments: z
+				.array(z.string())
+				.optional()
+				.describe('Optional instrument hints, e.g. ["piano", "strings"]'),
+			text_position: z
+				.enum(["top", "center", "bottom"])
+				.optional()
+				.describe("Where the title overlay sits (default bottom)"),
+			text_animation: z
+				.enum([
+					"reveal",
+					"typewriter",
+					"fade_in",
+					"pop",
+					"bounce",
+					"word_stagger",
+					"word_spotlight",
+				])
+				.optional()
+				.describe("Title overlay animation (default fade_in)"),
+			font_family: z
+				.string()
+				.optional()
+				.describe(
+					"Overlay font (default ShortFontSpaceGrotesk). One of: ShortFontSpaceGrotesk, ShortFontMontserrat, " +
+						"ShortFontTheBold, ShortFontImpact, ShortFontLato, ShortFontAnton, " +
+						"ShortFontBebasNeue, ShortFontOswald, ShortFontArchivoBlack, ShortFontPoppins, ShortFontInter, " +
+						"ShortFontTikTokSans, ShortFontBangers, ShortFontDMSerif, ShortFontPermanentMarker.",
+				),
+			headline_color: z
+				.string()
+				.optional()
+				.describe("Headline hex color, e.g. #ffffff"),
+			subheadline_color: z
+				.string()
+				.optional()
+				.describe("Subheadline hex color, e.g. #ffffff"),
+			accent_color: z
+				.string()
+				.optional()
+				.describe("6-digit brand accent hex color, e.g. #09EFBE"),
+			offer_text: z
+				.string()
+				.max(16)
+				.optional()
+				.describe('Optional offer chip, e.g. "-40%" or "2 FOR 1"'),
+			cta_text: z
+				.string()
+				.max(24)
+				.optional()
+				.describe('Optional CTA pill, e.g. "Shop now"'),
+			badge_text: z
+				.string()
+				.max(24)
+				.optional()
+				.describe('Optional badge stamp, e.g. "BEST SELLER"'),
+			star_rating: z
+				.number()
+				.min(0)
+				.max(5)
+				.optional()
+				.describe("Optional 0..5 star rating under the subheadline"),
+			text_beats: z
+				.array(z.string().max(120))
+				.max(8)
+				.optional()
+				.describe(
+					"Optional caption beats shown sequentially instead of the static subheadline.",
+				),
 		},
 		annotations: { title: "Create short", ...WRITE, idempotentHint: true },
 	},
-	tool(async (args: Record<string, unknown>, client) => {
-		const res = await client.post<{ data: { slug: string } }>(
-			"/shorts",
-			args,
-			idemKey("create-short", String(args.product_prompt ?? "")),
-		);
-		return ok({ slug: res.data.slug, kind: "short", next: "generate_short" });
-	}),
+	tool(
+		async (
+			args: {
+				product_prompt: string;
+				language?: string;
+				headline?: string;
+				subheadline?: string;
+				creative_format?: string;
+				visual_language?: string;
+				theme?: string;
+				music_vibe?: string;
+				music_instruments?: string[];
+				text_position?: string;
+				text_animation?: string;
+				font_family?: string;
+				headline_color?: string;
+				subheadline_color?: string;
+				accent_color?: string;
+				offer_text?: string;
+				cta_text?: string;
+				badge_text?: string;
+				star_rating?: number;
+				text_beats?: string[];
+			},
+			client,
+		) => {
+			// Map the agent-friendly field names onto the API's short_* params.
+			const body: Record<string, unknown> = {
+				product_prompt: args.product_prompt,
+			};
+			if (args.language !== undefined) body.language = args.language;
+			if (args.headline !== undefined) body.headline = args.headline;
+			if (args.subheadline !== undefined) body.subheadline = args.subheadline;
+			if (args.creative_format !== undefined)
+				body.creative_format = args.creative_format;
+			if (args.visual_language !== undefined)
+				body.visual_language = args.visual_language;
+			if (args.theme !== undefined) body.theme = args.theme;
+			if (args.music_vibe !== undefined) body.music_vibe = args.music_vibe;
+			if (args.music_instruments !== undefined)
+				body.music_instruments = args.music_instruments;
+			if (args.text_position !== undefined)
+				body.short_text_position = args.text_position;
+			if (args.text_animation !== undefined)
+				body.short_text_animation = args.text_animation;
+			if (args.font_family !== undefined)
+				body.short_font_family = args.font_family;
+			if (args.headline_color !== undefined)
+				body.headline_color = args.headline_color;
+			if (args.subheadline_color !== undefined)
+				body.subheadline_color = args.subheadline_color;
+			if (args.accent_color !== undefined)
+				body.accent_color = args.accent_color;
+			if (args.offer_text !== undefined) body.offer_text = args.offer_text;
+			if (args.cta_text !== undefined) body.cta_text = args.cta_text;
+			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;
+			const res = await client.post<{ data: { slug: string } }>(
+				"/shorts",
+				body,
+				idemKey(
+					"create-short",
+					args.product_prompt,
+					args.language ?? "",
+					args.headline ?? "",
+					args.subheadline ?? "",
+					args.creative_format ?? "",
+					args.visual_language ?? "",
+					args.theme ?? "",
+					args.music_vibe ?? "",
+					JSON.stringify(args.music_instruments ?? []),
+					args.text_position ?? "",
+					args.text_animation ?? "",
+					args.font_family ?? "",
+					args.headline_color ?? "",
+					args.subheadline_color ?? "",
+					args.accent_color ?? "",
+					args.offer_text ?? "",
+					args.cta_text ?? "",
+					args.badge_text ?? "",
+					String(args.star_rating ?? ""),
+					JSON.stringify(args.text_beats ?? []),
+				),
+			);
+			return ok({
+				slug: res.data.slug,
+				kind: "short",
+				next: "set_short_product / set_short_poster (optional branding), then generate_short",
+			});
+		},
+	),
 );
 
 registerTool(
@@ -803,22 +1203,431 @@ registerTool(
 	{
 		title: "Generate (render) a short",
 		description:
-			"Deducts 15 credits and starts the render pipeline for an existing short. Idempotent per slug " +
-			"(safe to retry). Then poll with get_status or wait_for_completion (kind=short).",
+			"Deducts 15 credits and starts the render pipeline for an existing short. 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") },
 		annotations: { title: "Generate short", ...WRITE, idempotentHint: true },
 	},
 	tool(async (args: { slug: string }, client) => {
-		const res = await client.post<{ data: unknown }>(
-			`/shorts/${args.slug}/generate`,
-			undefined,
-			`gen-short:${args.slug}`,
+		// 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
+		// claim's conditional update rolls back the losing transaction's credit
+		// deduction — and a 409 means a render is already running.
+		try {
+			const res = await client.post<{ data: unknown }>(
+				`/shorts/${args.slug}/generate`,
+			);
+			const status = normalizeStatus("short", args.slug, asRecord(res).data);
+			return ok(status);
+		} catch (e) {
+			if ((e as { status?: number }).status === 409) {
+				return ok({
+					kind: "short",
+					slug: args.slug,
+					stage: "processing",
+					terminal: false,
+					ready: false,
+					video_url: null,
+					error: null,
+				});
+			}
+			throw e;
+		}
+	}),
+);
+
+registerTool(
+	"generate_short_text",
+	{
+		title: "Generate short overlay text (AI assist)",
+		description:
+			"Generates editable headline, subheadline, and caption beats for an existing short draft. " +
+			"CONSUMES 1 AI ASSIST (free daily quota) and spends no video credits. The server reads the saved " +
+			"short fields, so update/create the draft with the current product prompt, creative_format, visual_language, " +
+			"language, and seed copy first. On 429 set auto_unlock:true (1 credit -> +10 assists, retried once) or write the text yourself.",
+		inputSchema: {
+			slug: z.string().describe("Short slug from create_short"),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: {
+			title: "Generate short text",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { slug: string; auto_unlock?: boolean }, client) => {
+		const res = await withAssist(client, args.auto_unlock ?? false, () =>
+			client.post<{ data: unknown }>(`/shorts/${args.slug}/text/generate`),
 		);
-		const status = normalizeStatus("short", args.slug, asRecord(res).data);
-		return ok(status);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+// ── Sliders (image carousels) ────────────────────────────────────────────────
+
+registerTool(
+	"create_slider",
+	{
+		title: "Create an image slider / carousel (draft)",
+		description:
+			"Creates a carousel draft from a prompt (min 10 chars). One prompt produces N still slides (an AI " +
+			"background + a composited headline/body + optional logo) PLUS a ready-to-post caption and hashtags. " +
+			"Returns the slug, costs 0 credits. Follow with generate_slider to render, then get_slider to read the " +
+			"slide image URLs + caption. mode 'creative' tells a story; 'ad_driven' lists product facts/benefits.",
+		inputSchema: {
+			prompt: z.string().min(10).describe("What the carousel is about"),
+			mode: z
+				.enum(["creative", "ad_driven"])
+				.optional()
+				.describe(
+					"'creative' (storytelling) or 'ad_driven' (facts about the product). Default creative.",
+				),
+			template: z
+				.enum([
+					"boldStatement",
+					"editorialStory",
+					"scrapbook",
+					"featureGrid",
+					"offerCard",
+					"comparison",
+				])
+				.optional()
+				.describe(
+					"Composition preset. boldStatement/editorialStory/scrapbook are creative; " +
+						"featureGrid/offerCard/comparison are ad-driven. Defaults to the mode default.",
+				),
+			slide_count: z
+				.number()
+				.optional()
+				.describe("Number of slides, integer 3–10 (default 5)"),
+			aspect_ratio: z
+				.enum(["4:5", "1:1", "9:16"])
+				.optional()
+				.describe(
+					"Canvas ratio (default 4:5, the highest-reach carousel ratio)",
+				),
+			accent_color: z
+				.string()
+				.regex(/^#[0-9a-fA-F]{6}$/)
+				.optional()
+				.describe(
+					"Brand accent: must start with #, exactly 6 hex digits, e.g. #09EFBE",
+				),
+			text_position: z
+				.enum(["top", "middle", "bottom"])
+				.optional()
+				.describe(
+					"Vertical placement of the on-image copy across all slides. Omit for the template's natural placement.",
+				),
+		},
+		annotations: { title: "Create slider", ...WRITE, idempotentHint: true },
+	},
+	tool(
+		async (
+			args: {
+				prompt: string;
+				mode?: string;
+				template?: string;
+				slide_count?: number;
+				aspect_ratio?: string;
+				accent_color?: string;
+				text_position?: string;
+			},
+			client,
+		) => {
+			// slide_count is a flat z.number() (see registerTool TS2589 note), so
+			// enforce the integer 3..10 range here, matching the server changeset.
+			if (args.slide_count !== undefined) {
+				if (
+					!Number.isInteger(args.slide_count) ||
+					args.slide_count < 3 ||
+					args.slide_count > 10
+				) {
+					return fail("slide_count must be an integer between 3 and 10");
+				}
+			}
+			const body: Record<string, unknown> = { prompt: args.prompt };
+			if (args.mode !== undefined) body.mode = args.mode;
+			if (args.template !== undefined) body.template = args.template;
+			if (args.slide_count !== undefined) body.slide_count = args.slide_count;
+			if (args.aspect_ratio !== undefined)
+				body.aspect_ratio = args.aspect_ratio;
+			if (args.accent_color !== undefined)
+				body.accent_color = args.accent_color;
+			if (args.text_position !== undefined)
+				body.text_position = args.text_position;
+			const res = await client.post<{ data: { slug: string } }>(
+				"/sliders",
+				body,
+				idemKey(
+					"create-slider",
+					args.prompt,
+					args.mode ?? "",
+					args.template ?? "",
+				),
+			);
+			return ok({
+				slug: res.data.slug,
+				kind: "slider",
+				next: "generate_slider, then get_slider to read the slide URLs + caption",
+			});
+		},
+	),
+);
+
+registerTool(
+	"generate_slider",
+	{
+		title: "Generate (render) a carousel",
+		description:
+			"Deducts 1 credit per slide (3–10 slides) and starts the pipeline (copy → AI backgrounds → composite) for an existing " +
+			"carousel. Safe to call again: a duplicate while a render is already in flight is reported as still " +
+			"processing (no double charge), and a failed carousel can be re-generated. Then poll with get_slider " +
+			"until status is 'completed' or 'failed'.",
+		inputSchema: {
+			slug: z.string().describe("Slider slug from create_slider"),
+		},
+		annotations: { title: "Generate slider", ...WRITE, idempotentHint: true },
+	},
+	tool(async (args: { slug: string }, client) => {
+		// No stable idempotency key on purpose: a per-slug key would replay the
+		// first response for 24h and silently block an intentional re-generation
+		// (e.g. retrying a failed render). Double-charge is prevented server-side
+		// by the atomic generation claim, which returns 409 when a render is
+		// already running — surface that as "still processing" rather than an error.
+		try {
+			const res = await client.post<{ data: Record<string, unknown> }>(
+				`/sliders/${args.slug}/generate`,
+			);
+			const data = asRecord(asRecord(res).data);
+			return ok({
+				slug: args.slug,
+				kind: "slider",
+				status: data.status ?? "processing",
+			});
+		} catch (e) {
+			if ((e as { status?: number }).status === 409) {
+				return ok({ slug: args.slug, kind: "slider", status: "processing" });
+			}
+			throw e;
+		}
 	}),
 );
 
+registerTool(
+	"get_slider",
+	{
+		title: "Get carousel status + deliverable",
+		description:
+			"Returns the carousel's status and, when completed, the per-slide image URLs (download these), the " +
+			"per-slide headline/body/kicker, the caption, and the hashtags. status flows draft → processing → " +
+			"completed | failed. completed:true means every slide image_url is ready to save. Once completed you " +
+			"can restyle_slider (new template/accent) or edit_slider_slide (one slide's text) for free.",
+		inputSchema: { slug: z.string().describe("Slider slug") },
+		annotations: { title: "Get slider", ...RO },
+	},
+	tool(async (args: { slug: string }, client) => {
+		const res = await client.get<{ data: Record<string, unknown> }>(
+			`/sliders/${args.slug}`,
+		);
+		const data = asRecord(asRecord(res).data);
+		const slides = Array.isArray(data.slides)
+			? (data.slides as Record<string, unknown>[])
+			: [];
+		const status = (data.status as string) ?? "unknown";
+		return ok({
+			slug: args.slug,
+			kind: "slider",
+			status,
+			stage: status,
+			terminal: status === "completed" || status === "failed",
+			// Trust the server's terminal status. The API completes a slider in one
+			// transaction that writes every rendered key, so "completed" always implies
+			// all slides[].image_url are ready — re-deriving it here only created an
+			// ambiguous terminal:true / completed:false dead-end on an edge response.
+			completed: status === "completed",
+			error: (data.error_message as string) ?? null,
+			caption: (data.caption as string) ?? null,
+			hashtags: Array.isArray(data.hashtags) ? data.hashtags : [],
+			slides: slides.map((s) => ({
+				position: s.position,
+				image_url: s.image_url ?? null,
+				headline: s.headline ?? null,
+				body: s.body ?? null,
+				kicker: s.kicker ?? null,
+				status: s.status ?? null,
+			})),
+		});
+	}),
+);
+
+registerTool(
+	"restyle_slider",
+	{
+		title: "Restyle a carousel (free re-composite of every slide)",
+		description:
+			"Re-composites ALL slides of a completed carousel under a new template, accent color and/or text " +
+			"position — for FREE (0 credits). Reuses the already-generated AI backgrounds, so no new images are paid for. The " +
+			"carousel must already be 'completed' (generate it first); a draft/processing carousel returns a " +
+			"409 conflict. Runs async: it marks every slide processing, so poll get_slider until status is back " +
+			"to 'completed' (or 'failed'). Omit a field to leave it unchanged.",
+		inputSchema: {
+			slug: z.string().describe("Slider slug from create_slider"),
+			template: z
+				.enum([
+					"boldStatement",
+					"editorialStory",
+					"scrapbook",
+					"featureGrid",
+					"offerCard",
+					"comparison",
+				])
+				.optional()
+				.describe(
+					"New composition preset. boldStatement/editorialStory/scrapbook are creative; " +
+						"featureGrid/offerCard/comparison are ad-driven.",
+				),
+			accent_color: z
+				.string()
+				.regex(/^#[0-9a-fA-F]{6}$/)
+				.optional()
+				.describe(
+					"New brand accent: must start with #, exactly 6 hex digits, e.g. #09EFBE",
+				),
+			text_position: z
+				.enum(["top", "middle", "bottom"])
+				.optional()
+				.describe(
+					"New vertical placement of the on-image copy across all slides.",
+				),
+		},
+		annotations: { title: "Restyle slider", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				template?: string;
+				accent_color?: string;
+				text_position?: string;
+			},
+			client,
+		) => {
+			const body: Record<string, unknown> = {};
+			if (args.template !== undefined) body.template = args.template;
+			if (args.accent_color !== undefined)
+				body.accent_color = args.accent_color;
+			if (args.text_position !== undefined)
+				body.text_position = args.text_position;
+			try {
+				const res = await client.post<{ data: Record<string, unknown> }>(
+					`/sliders/${args.slug}/restyle`,
+					body,
+				);
+				const data = asRecord(asRecord(res).data);
+				return ok({
+					slug: args.slug,
+					kind: "slider",
+					status: data.status ?? "processing",
+					next: "poll get_slider until status is 'completed' (free re-composite, 0 credits)",
+				});
+			} catch (e) {
+				// 409 = carousel not completed yet, or a re-composite already running.
+				if ((e as { status?: number }).status === 409) {
+					return ok({ slug: args.slug, kind: "slider", status: "processing" });
+				}
+				throw e;
+			}
+		},
+	),
+);
+
+registerTool(
+	"edit_slider_slide",
+	{
+		title: "Edit one carousel slide's on-image text (free re-composite)",
+		description:
+			"Rewrites the on-image copy of a SINGLE slide (by position) and re-composites just that slide — for " +
+			"FREE (0 credits). Reuses the slide's existing AI background, so no new image is paid for. The " +
+			"carousel must already be 'completed' (a draft/processing carousel returns a 409 conflict). Runs " +
+			"async: the slide goes back to processing, so poll get_slider until its status is 'completed'. Pass " +
+			"only the fields you want to change. kicker = the small eyebrow/label line above the headline.",
+		inputSchema: {
+			slug: z.string().describe("Slider slug from create_slider"),
+			position: z
+				.number()
+				.int()
+				.min(1)
+				.describe("1-based slide position (from get_slider)"),
+			headline: z
+				.string()
+				.max(120)
+				.optional()
+				.describe("Slide headline, ≤120 chars"),
+			body: z.string().max(600).optional().describe("Slide body, ≤600 chars"),
+			kicker: z
+				.string()
+				.max(40)
+				.optional()
+				.describe("Small eyebrow/label line above the headline, ≤40 chars"),
+		},
+		annotations: {
+			title: "Edit slider slide",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				position: number;
+				headline?: string;
+				body?: string;
+				kicker?: string;
+			},
+			client,
+		) => {
+			const body: Record<string, unknown> = {};
+			if (args.headline !== undefined) body.headline = args.headline;
+			if (args.body !== undefined) body.body = args.body;
+			if (args.kicker !== undefined) body.kicker = args.kicker;
+			try {
+				const res = await client.patch<{ data: Record<string, unknown> }>(
+					`/sliders/${args.slug}/slides/${args.position}`,
+					body,
+				);
+				const data = asRecord(asRecord(res).data);
+				return ok({
+					slug: args.slug,
+					kind: "slider",
+					position: args.position,
+					status: data.status ?? "processing",
+					next: "poll get_slider until the slide's status is 'completed' (free re-composite, 0 credits)",
+				});
+			} catch (e) {
+				// 409 = carousel not completed yet, or a re-composite already running.
+				if ((e as { status?: number }).status === 409) {
+					return ok({
+						slug: args.slug,
+						kind: "slider",
+						position: args.position,
+						status: "processing",
+					});
+				}
+				throw e;
+			}
+		},
+	),
+);
+
 // ── Editor ───────────────────────────────────────────────────────────────────
 
 registerTool(
@@ -829,7 +1638,11 @@ registerTool(
 			"Creates an editor project from a product prompt and starts 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.",
+			"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 " +
+			"title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.)",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -842,7 +1655,9 @@ registerTool(
 			theme: z
 				.string()
 				.optional()
-				.describe('Visual theme (default "realistic")'),
+				.describe(
+					'Visual theme (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.',
+				),
 			voice_id: z
 				.string()
 				.optional()
@@ -987,7 +1802,9 @@ registerTool(
 			theme: z
 				.string()
 				.optional()
-				.describe('Visual theme (default "realistic")'),
+				.describe(
+					'Visual theme (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.',
+				),
 			voice_id: z
 				.string()
 				.regex(/^[A-Za-z0-9_-]+$/)
@@ -2159,6 +2976,89 @@ registerTool(
 	),
 );
 
+// ── Shorts: branding images (product + end-card poster) ──────────────────────
+//
+// The editor branding tools above hit /editor/...; these hit /shorts/... A short
+// has no logo overlay (editor-only), but it CAN feature a product image woven
+// into the footage and a closing end-card poster. Both are 0 credits.
+
+registerTool(
+	"set_short_product",
+	{
+		title: "Attach a product image to a short (0 credits)",
+		description:
+			"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 " +
+			"(≤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: {
+			slug: z.string().describe("Short slug (from create_short)"),
+			file_path: z
+				.string()
+				.describe("Local product image path (.jpg/.jpeg/.png)"),
+			description: z
+				.string()
+				.max(500)
+				.optional()
+				.describe("Product description (≤500 chars)"),
+		},
+		annotations: {
+			title: "Set short product",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: { slug: string; file_path: string; description?: string },
+			client,
+		) => {
+			const { s3_key } = await uploadImageFile(
+				client,
+				`/shorts/${args.slug}/product/presign`,
+				args.file_path,
+			);
+			const res = await client.post<{ data: unknown }>(
+				`/shorts/${args.slug}/product/confirm`,
+				{ s3_key, product_description: args.description },
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"set_short_poster",
+	{
+		title: "Set a short's end-card poster image (0 credits)",
+		description:
+			"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 " +
+			"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)"),
+		},
+		annotations: { title: "Set short poster", ...WRITE, idempotentHint: false },
+	},
+	tool(async (args: { slug: string; file_path: string }, client) => {
+		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 },
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
 // ── Status / waiting ──────────────────────────────────────────────────────────
 
 registerTool(