@hubfluencer/mcp 0.5.0 → 0.6.0

package/src/index.ts

@@ -16,44 +16,165 @@
  *              → render → wait_for_completion → download_result
  */
 
-import { writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import {
+	buildPlanBody,
+	type CreateCampaignArgs,
+	pickBrandProfileFields,
+	pickProductProfileFields,
+	runCreateCampaign,
+	summarizePack,
+	summarizePackItem,
+	summarizePackListEntry,
+	validatePlanSource,
+	validateVariationsBatch,
+} from "./campaign.js";
 import {
 	clientFromEnv,
 	type HubfluencerClient,
 	type HubfluencerError,
 } from "./client.js";
 import {
+	addSegmentKey,
 	asRecord,
 	assertSafeFetchUrl,
+	decideTrackingPlan,
+	editorAdAutopilotKey,
+	editorAdCreateKey,
+	formatApiErrorMessage,
 	idemKey,
 	inferKind,
 	type Kind,
+	makeVideoAutopilotKey,
+	makeVideoEditorCreateKey,
 	type NormalizedStatus,
 	normalizeStatus,
 	resolveSavePath,
+	sliderCreateKey,
+	startStateDiscriminator,
+	type TrackingSnapshot,
+	validateKind,
+	validateLanguage,
+	validateProductPrompt,
 } from "./core.js";
 import { runLogin } from "./login.js";
 import {
+	createCampaignOutput,
+	createDraftOutput,
+	createEditorOutput,
+	downloadResultOutput,
+	getCampaignPackOutput,
+	getCreditsOutput,
+	getRecommendationsOutput,
+	getSeriesDashboardOutput,
+	getSliderOutput,
+	getStatusOutput,
+	listProjectsOutput,
+	listScheduledPostsOutput,
+	makeVideoOutput,
+	waitForCompletionOutput,
+} from "./output-schemas.js";
+import {
+	assetSubscriptionErrorText,
+	buildPerformanceBody,
+	buildReviewLinkBody,
+	type CreateReviewLinkResult,
+	PERFORMANCE_PLATFORMS,
+	PERFORMANCE_SOURCES,
+	pickCreativeAttributeFields,
+	REVIEW_LINK_MAX_EXPIRES_IN_HOURS,
+	REVIEW_LINK_MIN_EXPIRES_IN_HOURS,
+	type RecordPerformanceArgs,
+	reviewWebOrigin,
+	shapeCreateReviewLink,
+	summarizeAssetQuota,
+	summarizeCatalogAsset,
+	summarizePerformance,
+	summarizeReviewLink,
+	validatePerformanceMetrics,
+	validateReviewOutput,
+} from "./perf-review-assets.js";
+import {
+	buildScheduledPostBody,
+	calendarScopeErrorText,
+	MAX_PENDING_SCHEDULED_POSTS,
+	pickSeriesFields,
+	SCHEDULED_POST_PLATFORMS,
+	SCHEDULED_POST_STATUSES,
+	summarizeDashboard,
+	summarizeEpisode,
+	summarizeScheduledPost,
+	summarizeSeries,
+	validateScheduledPostCopy,
+} from "./series-calendar.js";
+import {
+	CATALOG_ASSET_EXTS,
 	IMAGE_EXTS,
+	resolveVideoReadPath,
+	uploadCatalogAsset,
 	uploadImageFile,
 	uploadShortPoster,
 	uploadVideoFile,
 	VIDEO_EXTS,
 } from "./uploads.js";
+import { USER_AGENT, VERSION } from "./version.js";
 
 async function fetchStatus(
 	client: HubfluencerClient,
 	kind: Kind,
 	slug: string,
+	deadline?: number,
 ): Promise<NormalizedStatus> {
-	const path = kind === "short" ? `/shorts/${slug}` : `/editor/${slug}`;
-	const res = await client.get<{ data: unknown }>(path);
+	const path =
+		kind === "short"
+			? `/shorts/${slug}`
+			: kind === "tracking"
+				? `/tracking/${slug}`
+				: kind === "slider"
+					? `/sliders/${slug}`
+					: `/editor/${slug}`;
+	// On the poll path the caller passes the loop deadline so this GET's retry
+	// sequence can't overrun the wait budget (see client.request `deadline`).
+	const res = await client.get<{ data: unknown }>(path, undefined, deadline);
 	return normalizeStatus(kind, slug, asRecord(res).data);
 }
 
+function isRecompositeInProgressConflict(e: unknown): boolean {
+	const err = e as Partial<HubfluencerError>;
+	if (err?.status !== 409) return false;
+	const texts: string[] = [];
+	if (typeof err.code === "string") texts.push(err.code);
+	if (typeof err.message === "string") texts.push(err.message);
+	const body = err.body;
+	if (body && typeof body === "object") {
+		const record = body as Record<string, unknown>;
+		if (typeof record.error === "string") texts.push(record.error);
+		if (typeof record.message === "string") texts.push(record.message);
+		const nested = record.error;
+		if (nested && typeof nested === "object") {
+			const nestedRecord = nested as Record<string, unknown>;
+			if (typeof nestedRecord.code === "string") texts.push(nestedRecord.code);
+			if (typeof nestedRecord.message === "string")
+				texts.push(nestedRecord.message);
+		}
+	}
+	return texts.some((text) => {
+		const normalized = text.toLowerCase();
+		return (
+			normalized === "recomposite_in_progress" ||
+			/\bre-?composit(?:e|ing|ion)\b.*\balready\b.*\b(progress|running)\b/.test(
+				normalized,
+			) ||
+			/\bcarousel\b.*\bre-?render\b.*\balready\b.*\bprogress\b/.test(normalized)
+		);
+	});
+}
+
 // The video_url comes back in API JSON — allow loopback http only when the API
 // base itself is local (dev), mirroring uploads.ts and the base-URL exception.
 const ALLOW_LOOPBACK_FETCH =
@@ -72,7 +193,10 @@ async function downloadTo(
 	// Bound the download: a presigned URL could in theory hang or point at
 	// something huge, so cap both time and size instead of buffering blindly.
 	const MAX_BYTES = 1024 * 1024 * 1024; // 1 GB — generous for a short ad
-	const resp = await fetch(videoUrl, { signal: AbortSignal.timeout(120_000) });
+	const resp = await fetch(videoUrl, {
+		headers: { "user-agent": USER_AGENT },
+		signal: AbortSignal.timeout(120_000),
+	});
 	if (!resp.ok)
 		throw new Error(`Failed to download video (HTTP ${resp.status}).`);
 	// Fast path: trust a present content-length to reject an oversize body before
@@ -106,6 +230,10 @@ async function downloadTo(
 		await reader.cancel().catch(() => {});
 	}
 	const buf = Buffer.concat(chunks, total);
+	// resolveSavePath accepts a nested target (e.g. "clips/out.mp4"), so create
+	// the parent chain before writing — otherwise a full spend + download lands on
+	// an ENOENT at the final writeFile. Recursive mkdir is a no-op when it exists.
+	await mkdir(dirname(target), { recursive: true });
 	await writeFile(target, buf);
 	return { saved_to: target, bytes: buf.length };
 }
@@ -158,19 +286,15 @@ function fail(message: string) {
 function errMessage(e: unknown): string {
 	const he = e as HubfluencerError;
 	if (he && typeof he.status === "number") {
-		const base = `API error (HTTP ${he.status}${he.code ? `, ${he.code}` : ""}): ${he.message}`;
-		// Surface the structured credit fields the server attaches to 402s so the
-		// agent can report exactly how short it is instead of a bare sentence.
-		const body = he.body as Record<string, unknown> | undefined;
-		if (
-			body &&
-			(body.required_credits != null || body.available_credits != null)
-		) {
-			const req = body.required_credits;
-			const have = body.available_credits;
-			return `${base} (needs ${req ?? "?"} credits, have ${have ?? "?"}).`;
-		}
-		return base;
+		// Delegate the formatting (incl. the 402 credit-shortfall parsing) to the
+		// pure, unit-tested helper in core.ts — index.ts can't be imported from a
+		// test (it boots a live stdio server at module load).
+		return formatApiErrorMessage({
+			status: he.status,
+			code: he.code,
+			message: he.message,
+			body: he.body,
+		});
 	}
 	return e instanceof Error ? e.message : String(e);
 }
@@ -315,7 +439,9 @@ function tool<A>(
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
-const kindSchema = z.enum(["short", "editor"]).describe("Project kind");
+const kindSchema = z
+	.enum(["short", "editor", "tracking", "slider"])
+	.describe("Project kind");
 
 // Creative-style value lists shared by SHORTS and EDITOR (single source of
 // truth, mirroring the API's VideoFactory.creative_formats/0 +
@@ -345,7 +471,45 @@ const WRITE = {
 	openWorldHint: true,
 };
 
-const server = new McpServer({ name: "hubfluencer", version: "0.5.0" });
+// Server-level instructions surfaced to the client during the MCP handshake — a
+// single place for the cross-tool conventions an agent needs before its first
+// call (the per-tool `description`s carry the specifics). Kept concise: the two
+// altitudes (one-shot asset vs. the full delegate-my-content-operation loop),
+// money, how waiting/resuming works, and the local-file sandbox.
+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.
+- Granular (full control): create a draft, then drive the pipeline step by step (create_editor_draft → generate_scenario → set_scene_count → set_segment_prompt → generate_segment(s) → generate_voice + generate_music → render). Poll with get_status / wait_for_completion; fetch with download_result (a slider has no MP4 — read its slides with get_slider).
+
+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.
+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.
+- 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.
+- 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)
+- Reads (upload_video / product / logo / closing / poster) are confined to HUBFLUENCER_INPUT_DIR (default: cwd); writes (save_path on wait_for_completion / download_result) are confined to HUBFLUENCER_OUTPUT_DIR (default: cwd), .mp4 only. Paths outside the base are refused.
+
+AUTH: set HUBFLUENCER_API_TOKEN (Settings → Access tokens) or run \`npx -y @hubfluencer/mcp login\`. HUBFLUENCER_BASE_URL overrides the API host; HUBFLUENCER_CREDENTIALS overrides the device-link credentials path.`;
+
+const server = new McpServer(
+	{ name: "hubfluencer", version: VERSION },
+	{ instructions: SERVER_INSTRUCTIONS },
+);
 
 // 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
@@ -370,12 +534,12 @@ async function pollToTerminal(
 	intervalMs: number,
 ): Promise<NormalizedStatus> {
 	const deadline = Date.now() + budgetMs;
-	let status = await fetchStatus(client, kind, slug);
+	let status = await fetchStatus(client, kind, slug, deadline);
 	let n = 0;
 	while (!status.terminal && Date.now() + intervalMs <= deadline) {
 		await reportProgress(extra, ++n, `stage: ${status.stage}`);
 		await sleep(intervalMs);
-		status = await fetchStatus(client, kind, slug);
+		status = await fetchStatus(client, kind, slug, deadline);
 	}
 	return status;
 }
@@ -403,7 +567,12 @@ async function pollSegmentToTerminal(
 	const deadline = Date.now() + budgetMs;
 	const sid = String(segmentId);
 	const read = async (): Promise<{ status: string; error: string | null }> => {
-		const res = await client.get<{ data: unknown }>(`/editor/${slug}`);
+		// Bound each poll GET's retries by the loop deadline (see fetchStatus).
+		const res = await client.get<{ data: unknown }>(
+			`/editor/${slug}`,
+			undefined,
+			deadline,
+		);
 		const data = asRecord(asRecord(res).data);
 		const segments = Array.isArray(data.segments)
 			? (data.segments as Record<string, unknown>[])
@@ -467,10 +636,27 @@ registerTool(
 				.describe(
 					"'short' (fast, 1 clip), 'editor' (multi-scene), or 'auto' (default — inferred)",
 				),
+			product_subject: z
+				.string()
+				.max(300)
+				.optional()
+				.describe(
+					'EDITOR only: the concrete product / main subject the video must be about (e.g. "Bordeaux red ' +
+						'wine, dark green bottle"). Hard-grounds the AI so it cannot invent an unrelated product. ' +
+						"Recommended for ads.",
+				),
+			project_intent: z
+				.enum(["social_ad", "creative_story"])
+				.optional()
+				.describe(
+					"EDITOR only: social_ad for promotional content (product focus + CTA) or creative_story (default).",
+				),
 			language: z
 				.string()
 				.optional()
-				.describe('Language code, e.g. "en" (default)'),
+				.describe(
+					'Language code, e.g. "en" (default), "fr". Drives scenario, narration, voice, and captions.',
+				),
 			aspect: z
 				.string()
 				.optional()
@@ -603,6 +789,7 @@ registerTool(
 					"Spend cap: refuse to start (no charge) if the priced estimate exceeds this. Returns the estimate.",
 				),
 		},
+		outputSchema: makeVideoOutput,
 		annotations: { title: "Make a video", ...WRITE, idempotentHint: false },
 	},
 	tool(
@@ -610,6 +797,8 @@ registerTool(
 			args: {
 				prompt: string;
 				kind?: string;
+				product_subject?: string;
+				project_intent?: string;
 				language?: string;
 				aspect?: string;
 				voice_id?: string;
@@ -638,9 +827,17 @@ registerTool(
 			client,
 			extra,
 		) => {
-			if (!args.prompt || args.prompt.trim().length < 10) {
-				return fail("prompt must be at least 10 characters.");
+			const promptLen = args.prompt?.trim().length ?? 0;
+			if (promptLen < 10 || promptLen > 5000) {
+				return fail("prompt must be 10–5000 characters.");
 			}
+			const langErr = validateLanguage(args.language);
+			if (langErr) return fail(langErr);
+			// kind is a flat z.string() (TS2589), so validate it in code the same way
+			// slide_count is — reject anything other than the documented values instead
+			// of silently inferring a wrong-product spend (see validateKind).
+			const kindErr = validateKind(args.kind);
+			if (kindErr) return fail(kindErr);
 			const requestedKind =
 				args.kind === "short" || args.kind === "editor" ? args.kind : undefined;
 			const kind: Kind = requestedKind ?? inferKind(args.prompt);
@@ -650,6 +847,25 @@ registerTool(
 			);
 			const budgetMs = waitSeconds * 1000;
 
+			// star_rating / text_beats are flat here (see the schema note on TS2589)
+			// but create_short bounds them with Zod (0..5; ≤8 beats, each ≤120). Apply
+			// the SAME bounds in code so a one-shot short can't slip past make_video an
+			// out-of-range value that create_short would have rejected.
+			if (
+				args.star_rating !== undefined &&
+				(args.star_rating < 0 || args.star_rating > 5)
+			) {
+				return fail("star_rating must be between 0 and 5.");
+			}
+			if (args.text_beats !== undefined) {
+				if (args.text_beats.length > 8) {
+					return fail("text_beats must have at most 8 entries.");
+				}
+				if (args.text_beats.some((b) => b.length > 120)) {
+					return fail("each text_beats entry must be at most 120 characters.");
+				}
+			}
+
 			// Validate the save_path up front so we fail before spending credits.
 			if (args.save_path) resolveSavePath(args.save_path);
 
@@ -718,22 +934,18 @@ registerTool(
 					{
 						language: args.language ?? "en",
 						product_prompt: args.prompt,
+						product_subject: args.product_subject,
+						project_intent: args.project_intent,
 						export_aspect_ratio: args.aspect,
 						voice_id: args.voice_id,
 						creative_format: args.creative_format,
 						visual_language: args.visual_language,
 						theme: args.theme,
 					},
-					idemKey(
-						"make-editor",
-						args.prompt,
-						args.language ?? "en",
-						args.aspect ?? "",
-						args.voice_id ?? "",
-						args.creative_format ?? "",
-						args.visual_language ?? "",
-						args.theme ?? "",
-					),
+					// 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),
 				);
 				slug = created.data.slug;
 			}
@@ -795,18 +1007,49 @@ registerTool(
 				});
 			}
 
-			// 4) Affordable and authorized — start the charging pipeline.
+			// 4) Affordable and authorized — start the charging pipeline. Read the
+			//    project's current state first and fold an anti-replay discriminator
+			//    into the start key: on a re-run AFTER a terminal failure the server's
+			//    24h idempotency cache would otherwise replay the failed run's cached
+			//    202 and never restart (the exact trap generate_short warns about).
+			//    startStateDiscriminator returns a STABLE "start" for a fresh/in-flight
+			//    project (so a transport double-send still dedupes — and the server's
+			//    already-running / 409 gate independently blocks a double charge) but a
+			//    per-attempt signature once terminally failed, so a genuine re-run mints
+			//    a fresh key and re-enqueues. Best-effort: if the read fails we fall
+			//    back to the stable "start" (the server gate remains the real guard).
+			let startState = "start";
+			try {
+				const cur = await client.get<{ data: unknown }>(
+					kind === "short" ? `/shorts/${slug}` : `/editor/${slug}`,
+				);
+				startState = startStateDiscriminator(kind, asRecord(cur).data);
+			} catch {
+				// status unreadable — keep the stable token (the server gate still holds)
+			}
+
 			if (kind === "short") {
 				await client.post(
 					`/shorts/${slug}/generate`,
 					undefined,
-					`gen-short:${slug}`,
+					// 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}`,
 				);
 			} else {
 				await client.post(
 					`/editor/${slug}/autopilot`,
 					undefined,
-					`autopilot:${slug}`,
+					// 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
+					// *this* slug; the other autopilot entry points use a different field
+					// set/order on purpose (the server idempotency cache is scoped to
+					// path+key, and the slug — already in the path — is unique per draft),
+					// so the shapes are not meant to be interchangeable across tools.
+					// Composition lives in core.ts, shared with the golden-pin test.
+					makeVideoAutopilotKey(slug, args, startState),
 				);
 			}
 
@@ -851,7 +1094,13 @@ registerTool(
 					note: status.ready
 						? "Done. Presigned ~24h URL — download promptly."
 						: status.terminal
-							? `Terminal (${status.stage}). ${status.error ?? ""}`.trim()
+							? // A terminal-but-not-ready make_video is a failed/cancelled run.
+								// Point at a restart: re-running make_video now genuinely restarts
+								// (the start key folds the failure state, so it no longer replays the
+								// dead 202), or resume the pipeline directly. Fix the cause (often
+								// credits) first.
+								`Terminal (${status.stage}). ${status.error ?? ""}`.trim() +
+								` To restart, fix the cause (often credits) then re-run make_video, or resume with ${resume}.`
 							: `Still rendering — call wait_for_completion(${resumeArgs}).`,
 				},
 				links,
@@ -869,6 +1118,7 @@ registerTool(
 		description:
 			"Returns the authenticated account's credit balance. A short costs 15 credits.",
 		inputSchema: {},
+		outputSchema: getCreditsOutput,
 		annotations: { title: "Get credits", ...RO },
 	},
 	tool(async (_args, client) => {
@@ -926,6 +1176,7 @@ registerTool(
 				.optional()
 				.describe("Max items per kind (default 25, capped at 100)"),
 		},
+		outputSchema: listProjectsOutput,
 		annotations: { title: "List projects", ...RO },
 	},
 	tool(
@@ -1104,6 +1355,7 @@ registerTool(
 					"Optional caption beats shown sequentially instead of the static subheadline.",
 				),
 		},
+		outputSchema: createDraftOutput,
 		annotations: { title: "Create short", ...WRITE, idempotentHint: true },
 	},
 	tool(
@@ -1200,6 +1452,372 @@ registerTool(
 	),
 );
 
+interface TrackingData {
+	slug: string;
+	status: string;
+	source: { status: string } | null;
+	result: { id?: number; status: string; video_url: string | null } | null;
+}
+
+async function getTracking(
+	client: HubfluencerClient,
+	slug: string,
+	deadline?: number,
+): Promise<TrackingData> {
+	// On a poll loop the caller passes the loop deadline so this GET's retry
+	// sequence stays inside the wait budget (see client.request `deadline`).
+	const res = await client.get<{ data: TrackingData }>(
+		`/tracking/${slug}`,
+		undefined,
+		deadline,
+	);
+	return res.data;
+}
+
+// Poll until the uploaded source clip finishes server-side processing.
+//
+// Returns "ready" when the source is usable, "failed" when the server-side
+// processing FAILED (the API now surfaces failed sources — see the latest_source
+// contract), and "timeout" when the budget elapsed while it was still in flight.
+// Short-circuiting on "failed" matters: a failed source is not progressing, so
+// spinning the full budget and then telling the agent it is "still processing"
+// would be both slow and wrong.
+async function waitForTrackingSource(
+	client: HubfluencerClient,
+	slug: string,
+	extra: ToolExtra,
+	budgetMs = 120_000,
+	intervalMs = 3_000,
+): Promise<"ready" | "failed" | "timeout"> {
+	const deadline = Date.now() + budgetMs;
+	let n = 0;
+	while (Date.now() + intervalMs <= deadline) {
+		const t = await getTracking(client, slug, deadline);
+		if (t.source?.status === "ready") return "ready";
+		if (t.source?.status === "failed") return "failed";
+		await reportProgress(extra, ++n, "processing source clip");
+		await sleep(intervalMs);
+	}
+	return "timeout";
+}
+
+// Poll the render until the result reaches a terminal state. The budget is
+// generous (default 15 min) because the production Replicate Cog can cold-start a
+// GPU before the burn-in even begins, and worst-case 60s/1080p sources may spend
+// several additional minutes in Mask R-CNN + CPU x264 encode. A short budget
+// would routinely time the agent out mid-render even on a job that ultimately succeeds.
+async function pollTrackingComplete(
+	client: HubfluencerClient,
+	slug: string,
+	extra: ToolExtra,
+	budgetMs = 900_000,
+	intervalMs = 4_000,
+): Promise<TrackingData> {
+	const deadline = Date.now() + budgetMs;
+	let n = 0;
+	let t = await getTracking(client, slug, deadline);
+	while (
+		t.result?.status !== "completed" &&
+		t.result?.status !== "failed" &&
+		Date.now() + intervalMs <= deadline
+	) {
+		await reportProgress(extra, ++n, "applying tracking overlay");
+		await sleep(intervalMs);
+		t = await getTracking(client, slug, deadline);
+	}
+	return t;
+}
+
+registerTool(
+	"create_tracking_video",
+	{
+		title: "Create a tracking-overlay video",
+		description:
+			"One-shot: upload a local video and burn the computer-vision 'object tracking' overlay on top " +
+			"(white convex-hull polygons hugging each moving subject, HUD corner brackets, a centroid crosshair, " +
+			"and per-subject telemetry), then download the result. Costs 1 credit on render. The source clip must " +
+			"be ≤60s and ≤1080p. This creates the project, uploads the clip, waits for it to be ready, renders, " +
+			"polls to completion, and (when save_path is given) downloads the finished MP4. " +
+			"RESUMING: if the call returns terminal=false (slow upload or a render still cold-starting on the GPU), " +
+			"call this tool AGAIN with the returned slug to resume — it reuses the in-flight upload (it only (re)uploads " +
+			"when no source exists yet or the prior upload failed) and never re-charges (a render in flight is reported, " +
+			"not duplicated). Resuming a slug whose render already COMPLETED just returns the finished video: a " +
+			"completed project is FINAL. The source clip is deleted on successful completion, so you cannot re-render it " +
+			"with a different overlay: for a variant (different classes/color) start a NEW project (omit slug, pass " +
+			"video_path). Re-uploading even the identical clip charges a fresh 1-credit render (the dedup keys on the new " +
+			"upload). Once the project " +
+			"exists you can also poll/download it with get_status / download_result / wait_for_completion using " +
+			'kind:"tracking" and that slug.',
+		inputSchema: {
+			video_path: z
+				.string()
+				.optional()
+				.describe(
+					"Local path to the source video (mp4/mov/webm/mkv), inside HUBFLUENCER_INPUT_DIR or cwd. " +
+						"Required on a fresh call; optional when resuming with slug (the clip is already uploaded).",
+				),
+			slug: z
+				.string()
+				.optional()
+				.describe(
+					"Resume an existing tracking project (from a prior timeout/partial-failure payload): skips create " +
+						"and reuses the in-flight upload (only re-uploads when no source exists yet or the prior upload failed). " +
+						"Resuming a project whose render already COMPLETED just returns the finished video: a completed project " +
+						"is final (its source clip was deleted on completion), so you cannot re-render it with a different overlay. " +
+						"For a variant, start a fresh project (omit slug, pass video_path). Pass this back to continue an in-flight " +
+						"project rather than forking a new one; omit it to start a fresh project.",
+				),
+			classes: z
+				.array(z.number().int().min(0).max(79))
+				.optional()
+				.describe(
+					"COCO-80 class ids (0-79) to track (e.g. [0]=person, [16]=dog). Omit to track all subjects.",
+				),
+			color: z
+				.array(z.number().int().min(0).max(255))
+				.min(3)
+				.max(4)
+				.optional()
+				.describe(
+					"Optional overlay color as RGB [r,g,b] or RGBA [r,g,b,a] (each 0–255). Omit for the default white overlay.",
+				),
+			save_path: z
+				.string()
+				.optional()
+				.describe(
+					"Optional .mp4 path to download the finished video to (inside HUBFLUENCER_OUTPUT_DIR or cwd).",
+				),
+		},
+		annotations: {
+			title: "Create tracking video",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				video_path?: string;
+				slug?: string;
+				classes?: number[];
+				color?: number[];
+				save_path?: string;
+			},
+			client,
+			extra,
+		) => {
+			// Validate the save_path up front so we fail before spending a credit.
+			if (args.save_path) resolveSavePath(args.save_path);
+
+			// 1. Resolve the project: resume an existing slug, or create a fresh one
+			//    (0 credits). On a resume we first read the current project so the
+			//    orchestration plan can reason about its source/result state.
+			const existing: TrackingData | null = args.slug
+				? await getTracking(client, args.slug)
+				: null;
+
+			// Compute the whole orchestration plan — pure, side-effect-free (see
+			// decideTrackingPlan in core.ts, which is where this branching is unit
+			// tested). It yields the create/resume idempotency anchor, whether the
+			// source is already live (do-NOT-reupload), whether to (re)submit a render,
+			// and the safety-critical render key. On a FRESH call the anchor folds in a
+			// per-invocation random nonce so two runs over the SAME local clip path
+			// within the 24h idempotency window fork distinct projects instead of the
+			// second replaying the first's cached 201 (then appending an upload+render
+			// to the stale project). Mirrors start_autopilot's
+			// idemKey("autopilot", slug, randomUUID()). The render key is derived from
+			// the anchor PLUS a per-attempt/config discriminator, never the anchor
+			// verbatim, or a retry-after-failure would replay the cached 202 forever
+			// and never re-enqueue the worker.
+			const plan = decideTrackingPlan(
+				existing as TrackingSnapshot | null,
+				args,
+				randomUUID(),
+			);
+
+			let slug: string;
+			if (args.slug) {
+				slug = args.slug;
+			} else {
+				if (!args.video_path) {
+					return fail("video_path is required to start a new tracking video.");
+				}
+				// Validate the read path up front (ext allowlist, input-dir
+				// confinement, exists/non-empty/size cap) BEFORE creating the project,
+				// so a present-but-invalid path fails fast instead of orphaning an
+				// empty draft. uploadVideoFile re-resolves the same path below.
+				await resolveVideoReadPath(args.video_path);
+				const created = await client.post<{ data: { slug: string } }>(
+					"/tracking",
+					{},
+					plan.idemBase,
+				);
+				slug = created.data.slug;
+			}
+
+			// Resume of an already-FINISHED render: the project is final. On a
+			// successful completion the API deletes the source upload (it has served
+			// its purpose — the burned-in output is the only artifact the user keeps;
+			// tracking.ex delete_source_after_completion), so a completed resume carries
+			// source:null. We must therefore return the finished video HERE, before the
+			// source gate below — otherwise hasLiveSource is false and that gate wrongly
+			// reports "source not uploaded" on a paid, completed project. A different
+			// overlay is NOT a resume: combination_hash keys on the source's s3_key,
+			// which is gone, so any re-upload (even of the identical clip) gets a fresh
+			// key, misses the dedup, and charges a new render — so the honest guidance
+			// is "start a new tracking project", never "resume with new classes/color".
+			if (existing?.result?.status === "completed") {
+				const videoUrl = existing.result.video_url ?? null;
+				let saved_to: string | undefined;
+				if (videoUrl && args.save_path) {
+					saved_to = (await downloadTo(videoUrl, args.save_path)).saved_to;
+				}
+				const variantNote = plan.configSupplied
+					? " A different overlay needs a NEW tracking project (omit slug, pass video_path): the finished project's source clip was deleted on completion, so re-running can't re-render it, and re-uploading even the same clip charges a fresh 1-credit render."
+					: "";
+				return ok(
+					{
+						slug,
+						kind: "tracking",
+						status: "completed",
+						terminal: true,
+						video_url: videoUrl,
+						...(saved_to ? { saved_to } : {}),
+						note: `Already completed — the project is final. Presigned ~24h URL, download promptly.${variantNote}`,
+					},
+					videoUrl ? [mp4Link(videoUrl, slug)] : [],
+				);
+			}
+
+			// 2. Upload the source clip — reuses the editor upload routes, which the
+			//    tracking factory is authorised for (single-PUT or resumable multipart).
+			//    Only (re)upload when there is NO usable source row: a fresh project has
+			//    none, and a prior upload that ended `failed` is dead. Crucially, do NOT
+			//    re-upload for pending/processing — that is exactly the state during the
+			//    waitForTrackingSource timeout window the resume note points the agent at,
+			//    and a second uploadVideoFile would fork a duplicate EditorUpload (orphan
+			//    the in-flight one, double-consume the per-user live-upload ceiling, and
+			//    let the render pick the wrong/latest source). EditorUpload statuses are
+			//    pending|processing|ready|failed; only `failed` is unusable, the rest are
+			//    progressing toward ready, so we just wait on them below.
+			// The source is "live" (do NOT re-upload) when it exists and is not failed.
+			// The API now surfaces pending/processing sources too, so an in-flight upload
+			// is observed here and routed to wait-not-reupload rather than forking a
+			// duplicate EditorUpload (which would orphan the in-flight one, double-consume
+			// the per-user live-upload ceiling, and let the render pick the wrong source).
+			if (!plan.hasLiveSource) {
+				if (!args.video_path) {
+					return fail(
+						`Source for ${slug} is not uploaded yet (or the prior upload failed) and no ` +
+							"video_path was given to (re)upload. Pass video_path to upload, or wait and " +
+							"resume with the slug if an upload is already in flight.",
+					);
+				}
+				await uploadVideoFile(client, slug, args.video_path, {
+					onProgress: (completed, total, message) =>
+						reportProgress(extra, completed, message, total),
+				});
+			}
+
+			// 3. Wait for the upload to finish processing before charging a render.
+			//    Three outcomes: ready (proceed), failed (the server-side processing
+			//    failed — re-running with the slug alone would just re-observe the same
+			//    dead source and loop, so tell the agent to re-run WITH video_path to
+			//    re-upload), or timeout (still in flight — resume on the slug to keep
+			//    waiting; no re-upload, no re-charge).
+			const sourceState = await waitForTrackingSource(client, slug, extra);
+			if (sourceState === "failed") {
+				return ok({
+					slug,
+					kind: "tracking",
+					status: "failed",
+					terminal: true,
+					note: `Source upload failed for ${slug} — re-run create_tracking_video with slug:"${slug}" and video_path to re-upload the clip.`,
+				});
+			}
+			if (sourceState === "timeout") {
+				return ok({
+					slug,
+					kind: "tracking",
+					status: "processing",
+					terminal: false,
+					note: `Source still processing — call create_tracking_video again with slug:"${slug}" to resume (no re-upload, no re-charge).`,
+				});
+			}
+
+			// 4. Render (1 credit). Decide whether to (re)submit the render POST:
+			//    - no result yet, or the last one failed+refunded → render.
+			//    - a result is in flight (pending/processing) → never re-render
+			//      mid-flight (a poll-timeout resume); the server's 409 guard backs
+			//      this up anyway. Fall through to polling.
+			//    - a `completed` result already returned above (the source is deleted on
+			//      completion, so a completed project is final; a different overlay must
+			//      be a brand-new tracking project, never a resume with new config).
+			// A completed result already short-circuited above, so reaching here means
+			// the result is null / failed / in-flight — plan.shouldRender is true only
+			// for "no result yet" or "failed+refunded" (a re-render of a completed
+			// project is impossible now the source is deleted), and an in-flight render
+			// is left to the poll below (the server's 409 guard backs this up).
+			if (plan.shouldRender) {
+				const body: Record<string, unknown> = {};
+				if (args.classes !== undefined) body.classes = args.classes;
+				if (args.color !== undefined) body.color = args.color;
+
+				// plan.renderKey is the anti-replay-of-a-dead-202 key (derived in
+				// decideTrackingPlan, unit-tested in core.test.ts): a transport retry of
+				// THIS attempt replays the cached 202, but a retry AFTER a fail+refund
+				// mints a fresh key (the per-attempt discriminator diverges), so the
+				// worker re-enqueues instead of replaying the dead 202 forever.
+				try {
+					await client.post(`/tracking/${slug}/render`, body, plan.renderKey);
+				} catch (e) {
+					// A 409 (tracking_render_in_progress) means a render is already
+					// active — a race with another caller (e.g. the front-end) or a
+					// resume where `existing.result` was momentarily null at poll time.
+					// The render is fine; fall through to polling instead of surfacing a
+					// hard error. Mirrors generate_short's 409 handling.
+					if ((e as { status?: number }).status !== 409) throw e;
+				}
+			}
+
+			// 5. Poll to completion and (optionally) download.
+			const final = await pollTrackingComplete(client, slug, extra);
+			const status = final.result?.status ?? final.status;
+			const videoUrl = final.result?.video_url ?? null;
+			const terminal = status === "completed" || status === "failed";
+			let saved_to: string | undefined;
+			if (videoUrl && args.save_path) {
+				saved_to = (await downloadTo(videoUrl, args.save_path)).saved_to;
+			}
+
+			// Don't overstate success: a finished poll only means the result reached a
+			// terminal state OR the budget ran out. A still-running render may yet
+			// fail+refund server-side, so point the agent back at the slug either way.
+			const note =
+				status === "completed"
+					? "Done. Presigned ~24h URL — download promptly."
+					: status === "failed"
+						? "Render failed — the 1 credit was refunded. Retry with the same slug."
+						: `Still rendering — resume with create_tracking_video({ slug: "${slug}"${
+								args.save_path ? `, save_path: "${args.save_path}"` : ""
+							} }), or poll wait_for_completion({ slug: "${slug}", kind: "tracking" }). It may still fail+refund.`;
+
+			return ok(
+				{
+					slug,
+					kind: "tracking",
+					status,
+					terminal,
+					video_url: videoUrl,
+					...(saved_to ? { saved_to } : {}),
+					note,
+				},
+				videoUrl ? [mp4Link(videoUrl, slug)] : [],
+			);
+		},
+	),
+);
+
 registerTool(
 	"generate_short",
 	{
@@ -1209,7 +1827,10 @@ registerTool(
 			"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 },
+		// 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) => {
 		// No stable idempotency key (see generate_slider): a per-slug key would
@@ -1329,6 +1950,7 @@ registerTool(
 					"Vertical placement of the on-image copy across all slides. Omit for the template's natural placement.",
 				),
 		},
+		outputSchema: createDraftOutput,
 		annotations: { title: "Create slider", ...WRITE, idempotentHint: true },
 	},
 	tool(
@@ -1368,12 +1990,7 @@ registerTool(
 			const res = await client.post<{ data: { slug: string } }>(
 				"/sliders",
 				body,
-				idemKey(
-					"create-slider",
-					args.prompt,
-					args.mode ?? "",
-					args.template ?? "",
-				),
+				sliderCreateKey(args),
 			);
 			return ok({
 				slug: res.data.slug,
@@ -1396,7 +2013,10 @@ registerTool(
 		inputSchema: {
 			slug: z.string().describe("Slider slug from create_slider"),
 		},
-		annotations: { title: "Generate slider", ...WRITE, idempotentHint: true },
+		// Not idempotent: a repeat after a terminal render re-charges 1 credit/slide
+		// (a failed carousel can be re-generated), so a blind retry is not free —
+		// only an in-flight duplicate dedupes (server 409). See below.
+		annotations: { title: "Generate slider", ...WRITE },
 	},
 	tool(async (args: { slug: string }, client) => {
 		// No stable idempotency key on purpose: a per-slug key would replay the
@@ -1433,6 +2053,7 @@ registerTool(
 			"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") },
+		outputSchema: getSliderOutput,
 		annotations: { title: "Get slider", ...RO },
 	},
 	tool(async (args: { slug: string }, client) => {
@@ -1541,8 +2162,10 @@ registerTool(
 					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) {
+				// Only the active free re-composite race is idempotent from the MCP
+				// client's perspective. A 409 saying the slider must be completed is an
+				// actionable user error and must surface as one.
+				if (isRecompositeInProgressConflict(e)) {
 					return ok({ slug: args.slug, kind: "slider", status: "processing" });
 				}
 				throw e;
@@ -1615,8 +2238,10 @@ registerTool(
 					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) {
+				// Only the active free re-composite race is idempotent from the MCP
+				// client's perspective. A 409 saying the slider must be completed is an
+				// actionable user error and must surface as one.
+				if (isRecompositeInProgressConflict(e)) {
 					return ok({
 						slug: args.slug,
 						kind: "slider",
@@ -1650,10 +2275,29 @@ registerTool(
 				.string()
 				.min(10)
 				.describe("Brief for the ad (min 10 chars)"),
+			product_subject: z
+				.string()
+				.max(300)
+				.optional()
+				.describe(
+					'The concrete product or main subject the video must be about (e.g. "Bordeaux red wine, dark green ' +
+						'bottle with a gold label"). Distinct from the freeform brief: hard-grounds the AI scenario + narration ' +
+						"so it cannot invent an unrelated product. Strongly recommended for ads.",
+				),
+			project_intent: z
+				.enum(["social_ad", "creative_story"])
+				.optional()
+				.describe(
+					"social_ad for promotional/ad content (product focus + CTA), creative_story for brand narratives " +
+						"(default).",
+				),
 			language: z
 				.string()
 				.optional()
-				.describe('Language code, e.g. "en" (default)'),
+				.describe(
+					'Language code, e.g. "en" (default), "fr", "es". Drives the WHOLE video: scenario, narration script, ' +
+						"narration voice, and captions. Ask the user / infer from their locale.",
+				),
 			creative_format: z
 				.enum(CREATIVE_FORMATS)
 				.optional()
@@ -1681,42 +2325,64 @@ registerTool(
 				.optional()
 				.describe('Aspect ratio (default "9:16")'),
 		},
+		outputSchema: createEditorOutput,
 		annotations: { title: "Create editor ad", ...WRITE, idempotentHint: true },
 	},
-	tool(async (args: Record<string, unknown>, client) => {
-		const created = await client.post<{ data: { slug: string } }>(
-			"/editor",
-			{
-				language: args.language ?? "en",
-				product_prompt: args.product_prompt,
-				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,
+	tool(
+		async (
+			args: {
+				product_prompt: string;
+				product_subject?: string;
+				project_intent?: string;
+				language?: string;
+				creative_format?: string;
+				visual_language?: string;
+				theme?: string;
+				voice_id?: string;
+				export_aspect_ratio?: string;
 			},
-			// Fold every create-affecting param into the key so two calls that
-			// differ only by style/theme/voice/aspect get distinct drafts.
-			idemKey(
-				"create-editor",
-				String(args.product_prompt ?? ""),
-				String(args.language ?? "en"),
-				String(args.creative_format ?? ""),
-				String(args.visual_language ?? ""),
-				String(args.theme ?? ""),
-				String(args.voice_id ?? ""),
-				String(args.export_aspect_ratio ?? ""),
-			),
-		);
-		const slug = created.data.slug;
-		const started = await client.post<{ data: unknown }>(
-			`/editor/${slug}/autopilot`,
-			undefined,
-			`autopilot:${slug}`,
-		);
-		const status = normalizeStatus("editor", slug, asRecord(started).data);
-		return ok({ slug, kind: "editor", status, next: "wait_for_completion" });
-	}),
+			client,
+		) => {
+			const langErr = validateLanguage(args.language);
+			if (langErr) return fail(langErr);
+			const promptErr = validateProductPrompt(args.product_prompt);
+			if (promptErr) return fail(promptErr);
+
+			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" });
+		},
+	),
 );
 
 registerTool(
@@ -1726,31 +2392,83 @@ registerTool(
 		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 }). Idempotent per slug (safe to retry). Use this to run a draft created by " +
-			"make_video dry_run, or to resume after topping up / raising your spend cap. Then poll with " +
+			"or make_video({ dry_run:true }). Each 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" }).',
-		inputSchema: { slug: z.string().describe("Editor project slug") },
-		annotations: { title: "Start autopilot", ...WRITE, idempotentHint: true },
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			language: z
+				.string()
+				.optional()
+				.describe(
+					'Optional language override applied before launch (ISO 639-1, e.g. "fr"). Drives scenario, ' +
+						"narration, voice, and captions.",
+				),
+			product_subject: z
+				.string()
+				.max(300)
+				.optional()
+				.describe(
+					"Optional locked product / main subject applied before launch so the AI cannot invent an " +
+						"unrelated product.",
+				),
+			product_prompt: z
+				.string()
+				.optional()
+				.describe("Optional freeform brief to set/replace before launch."),
+		},
+		annotations: { title: "Start autopilot", ...WRITE, idempotentHint: false },
 	},
-	tool(async (args: { slug: string }, client) => {
-		const started = await client.post<{ data: unknown }>(
-			`/editor/${args.slug}/autopilot`,
-			undefined,
-			`autopilot:${args.slug}`,
-		);
-		const status = normalizeStatus("editor", args.slug, asRecord(started).data);
-		return ok({
-			slug: args.slug,
-			kind: "editor",
-			status,
-			next: "wait_for_completion",
-		});
-	}),
-);
+	tool(
+		async (
+			args: {
+				slug: string;
+				language?: string;
+				product_subject?: string;
+				product_prompt?: string;
+			},
+			client,
+		) => {
+			const langErr = validateLanguage(args.language);
+			if (langErr) return fail(langErr);
+			const promptErr = validateProductPrompt(args.product_prompt);
+			if (promptErr) return fail(promptErr);
 
-// ── AI assists (free daily quota) ───────────────────────────────────────────
+			const slug = args.slug;
+			const overrides: Record<string, unknown> = {};
+			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;
 
-registerTool(
+			const started = await client.post<{ data: unknown }>(
+				`/editor/${slug}/autopilot`,
+				Object.keys(overrides).length > 0 ? overrides : undefined,
+				// 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
+				// a deliberate relaunch (resume after a failure / top-up). Transport-level
+				// retries of THIS call reuse this one computed key, so an accidental
+				// double-send is still deduped; a genuine double-start is independently
+				// prevented server-side by the already-running gate.
+				idemKey("autopilot", slug, randomUUID()),
+			);
+			const status = normalizeStatus("editor", slug, asRecord(started).data);
+			return ok({
+				slug,
+				kind: "editor",
+				status,
+				next: "wait_for_completion",
+			});
+		},
+	),
+);
+
+// ── AI assists (free daily quota) ───────────────────────────────────────────
+
+registerTool(
 	"get_ai_assists",
 	{
 		title: "Get AI assist quota",
@@ -1818,12 +2536,22 @@ registerTool(
 				.max(5000)
 				.optional()
 				.describe("Brief for the ad — 10–5000 chars, or omit entirely"),
+			product_subject: z
+				.string()
+				.max(300)
+				.optional()
+				.describe(
+					"The concrete product / main subject the video must be about. Hard-grounds the AI so it cannot " +
+						"invent an unrelated product. Recommended for ads.",
+				),
 			language: z
 				.string()
 				.min(2)
 				.max(10)
 				.optional()
-				.describe('Language code, e.g. "en" (default)'),
+				.describe(
+					'Language code, e.g. "en" (default). Drives scenario, narration, voice, and captions.',
+				),
 			creative_format: z
 				.enum(CREATIVE_FORMATS)
 				.optional()
@@ -1855,8 +2583,12 @@ registerTool(
 			project_intent: z
 				.enum(["social_ad", "creative_story"])
 				.optional()
-				.describe("Project intent (optional)"),
+				.describe(
+					"social_ad for promotional/ad content (product focus + CTA), creative_story for brand " +
+						"narratives (default).",
+				),
 		},
+		outputSchema: createEditorOutput,
 		annotations: {
 			title: "Create editor draft",
 			...WRITE,
@@ -1867,6 +2599,7 @@ registerTool(
 		async (
 			args: {
 				product_prompt?: string;
+				product_subject?: string;
 				language?: string;
 				creative_format?: string;
 				visual_language?: string;
@@ -1880,6 +2613,7 @@ registerTool(
 			const prompt = args.product_prompt?.trim();
 			const body: Record<string, unknown> = {
 				language: args.language ?? "en",
+				product_subject: args.product_subject,
 				creative_format: args.creative_format,
 				visual_language: args.visual_language,
 				theme: args.theme,
@@ -1891,13 +2625,20 @@ registerTool(
 			const created = await client.post<{ data: { slug: string } }>(
 				"/editor",
 				body,
+				// Fold every create-affecting param into the key so two calls that
+				// differ only by intent/style/theme/voice/aspect get distinct
+				// drafts; a transport retry of an identical call still reuses one.
 				idemKey(
 					"create-editor-draft",
 					prompt ?? "",
+					args.product_subject ?? "",
+					args.project_intent ?? "",
 					args.language ?? "en",
 					args.creative_format ?? "",
 					args.visual_language ?? "",
 					args.theme ?? "",
+					args.voice_id ?? "",
+					args.export_aspect_ratio ?? "",
 				),
 			);
 			return ok({
@@ -2039,7 +2780,7 @@ registerTool(
 		title: "Set the number of scenes",
 		description:
 			"Adjusts the editor to exactly `count` scenes (1–20) by adding pending segments to grow, or deleting " +
-			"only TRAILING un-generated (pending) segments to shrink. Never deletes completed/processing segments — " +
+			"only TRAILING un-generated (pending or failed) segments to shrink. Never deletes completed/processing segments — " +
 			"if a shrink would require that, it stops and reports. Free (no credits, no assist). Each AI-generated " +
 			"scene is a fixed 8 seconds, so `count` scenes ≈ count×8s of AI footage (uploaded clips keep their own length).",
 		inputSchema: {
@@ -2063,15 +2804,22 @@ registerTool(
 		const target = args.count;
 
 		if (target > current) {
+			// Salt the add-segment idempotency keys with ONE fresh nonce per call so a
+			// grow→shrink→grow on this draft inside the server's 24h dedupe window
+			// doesn't replay an earlier round's cached 201s (which would add nothing).
+			// Safe: the tool re-derives `current` from live state every call, so a
+			// whole-tool retry with the same target still adds nothing (target ≤ current).
+			const growNonce = randomUUID();
 			for (let i = current; i < target; i++) {
 				await client.post(
 					`/editor/${args.slug}/segments`,
 					{},
-					idemKey("add-segment", args.slug, String(i)),
+					addSegmentKey(args.slug, i, growNonce),
 				);
 			}
 		} else if (target < current) {
-			// Delete only trailing pending segments (never completed/processing).
+			// Delete only trailing un-generated segments — pending/draft/unset OR a
+			// previously-failed scene (never completed/processing).
 			const isPending = (s: Record<string, unknown>) => {
 				const st = (s.status as string) ?? (s.generation_status as string);
 				return (
@@ -2088,8 +2836,8 @@ registerTool(
 			}
 			if (current - removable > target) {
 				return fail(
-					`Cannot shrink to ${target} scenes: only ${removable} trailing pending segment(s) are safe to ` +
-						`delete (the rest are completed/processing). Currently ${current} scenes.`,
+					`Cannot shrink to ${target} scenes: only ${removable} trailing un-generated (pending/failed) segment(s) are safe ` +
+						`to delete (the rest are completed/processing). Currently ${current} scenes.`,
 				);
 			}
 			for (let i = segments.length - 1; i >= target; i--) {
@@ -2188,7 +2936,9 @@ registerTool(
 			"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 " +
-			"scenes are skipped). Tip: to generate everything at lowest cost, skip this and just call render — it auto-generates any ungenerated scenes at the batch rate (4 credits/scene for ≥3); use this tool when you want to review or stop per scene. May take several minutes.",
+			"scenes are skipped). The whole call is capped at ~280s: on a project with many scenes it processes as " +
+			"many as fit, returns timed_out, and you re-run to continue (it picks up the remaining pending scenes). " +
+			"Tip: to generate everything at lowest cost, skip this and just call render — it auto-generates any ungenerated scenes at the batch rate (4 credits/scene for ≥3); use this tool when you want to review or stop per scene. May take several minutes.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
 		annotations: {
 			title: "Generate all segments",
@@ -2212,12 +2962,34 @@ registerTool(
 			);
 		});
 
+		// Overall wall-clock budget: cap the whole call at the same 280s ceiling the
+		// other wait loops use (under a typical 300s client timeout). Without it a
+		// project with many pending scenes could run unbounded (~8 min/scene × 20 ≈
+		// hours) in a single call. When the budget runs out mid-batch we stop and
+		// return the standard resume contract — call again and it naturally continues
+		// with whatever scenes are still pending (completed ones are skipped).
+		const overallDeadline = Date.now() + 280_000;
+		// Each scene's own poll budget stays generous (a Veo scene can take minutes)
+		// but is clamped to the time left overall so one scene can't overrun 280s.
+		const PER_SEGMENT_MAX_MS = 6 * 60 * 1000;
+
 		const generated: Array<string | number> = [];
 		let n = 0;
 		for (const seg of pending) {
 			const id = seg.id;
 			if (id === undefined) continue;
 			const sid = id as string | number;
+			// Stop before submitting another scene once the overall budget is spent, so
+			// the call returns instead of charging + waiting past the deadline.
+			const remainingMs = overallDeadline - Date.now();
+			if (remainingMs <= 0) {
+				return ok({
+					slug: args.slug,
+					generated,
+					timed_out: true,
+					note: "Wall-clock budget reached — stopped before the next scene. Re-run generate_all_segments to continue (it retries failed/pending scenes and skips completed ones).",
+				});
+			}
 			await reportProgress(
 				extra,
 				++n,
@@ -2242,12 +3014,13 @@ registerTool(
 			// Gate on THIS segment finishing before starting the next, so the next
 			// scene can build on this one's last frame (visual continuity). Poll the
 			// segment itself — the project-level status never goes terminal mid-batch.
+			// Clamp its budget to the time left overall so the whole call honours 280s.
 			const seg_result = await pollSegmentToTerminal(
 				client,
 				args.slug,
 				sid,
 				extra,
-				6 * 60 * 1000,
+				Math.min(PER_SEGMENT_MAX_MS, remainingMs),
 				15000,
 			);
 			if (seg_result.status === "failed") {
@@ -2707,6 +3480,8 @@ registerTool(
 				args.file_path,
 				{
 					fitMode: args.fit_mode,
+					onProgress: (completed, total, message) =>
+						reportProgress(extra, completed, message, total),
 				},
 			);
 			await reportProgress(
@@ -3140,9 +3915,12 @@ registerTool(
 	{
 		title: "Get generation status",
 		description:
-			"Returns a normalized status {stage, terminal, ready, video_url, error} for a short or editor " +
-			"project. ready:true means the post-ready MP4 is at video_url.",
+			"Returns a normalized status {stage, terminal, ready, video_url, error} for a short, editor, " +
+			"tracking, or slider project. ready:true means the post-ready MP4 is at video_url — except for a " +
+			"slider (a carousel of stills, not a video): its video_url is always null, ready:true means every " +
+			"slide is composited, and you read the per-slide image URLs with get_slider.",
 		inputSchema: { slug: z.string(), kind: kindSchema },
+		outputSchema: getStatusOutput,
 		annotations: { title: "Get status", ...RO },
 	},
 	tool(async (args: { slug: string; kind: Kind }, client) => {
@@ -3158,7 +3936,9 @@ registerTool(
 		description:
 			"Polls status (emitting progress) until terminal (ready/failed) or the wait budget is exhausted. " +
 			"Generation can take several minutes; if it returns terminal=false, call again to keep waiting. " +
-			"Pass save_path to download the finished MP4 when it's ready (e.g. to resume a make_video that timed out mid-render).",
+			"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).",
 		inputSchema: {
 			slug: z.string(),
 			kind: kindSchema,
@@ -3183,7 +3963,14 @@ registerTool(
 					"Optional .mp4 path to download to when ready (confined to HUBFLUENCER_OUTPUT_DIR or cwd)",
 				),
 		},
-		annotations: { title: "Wait for completion", ...RO },
+		outputSchema: waitForCompletionOutput,
+		// Not readOnly: when save_path is set this writes the finished MP4 to disk,
+		// so a client that auto-approves readOnly tools must not treat it as one.
+		annotations: {
+			title: "Wait for completion",
+			...WRITE,
+			idempotentHint: true,
+		},
 	},
 	tool(
 		async (
@@ -3232,7 +4019,8 @@ registerTool(
 		title: "Get / download the finished video",
 		description:
 			"Returns the post-ready MP4 URL for a completed project (presigned, ~24h TTL — use promptly). " +
-			"If save_path is given (confined to HUBFLUENCER_OUTPUT_DIR or cwd), the file is downloaded there.",
+			"If save_path is given (confined to HUBFLUENCER_OUTPUT_DIR or cwd), the file is downloaded there. " +
+			"Not for sliders — a carousel has no MP4; use get_slider for its slide images.",
 		inputSchema: {
 			slug: z.string(),
 			kind: kindSchema,
@@ -3241,10 +4029,21 @@ registerTool(
 				.optional()
 				.describe("Optional .mp4 path inside the output base"),
 		},
-		annotations: { title: "Download result", ...RO },
+		// Not readOnly: with save_path it writes the MP4 to disk. Reading the URL is
+		// side-effect-free but the tool as a whole can write, so it isn't readOnly.
+		outputSchema: downloadResultOutput,
+		annotations: { title: "Download result", ...WRITE, idempotentHint: true },
 	},
 	tool(
 		async (args: { slug: string; kind: Kind; save_path?: string }, client) => {
+			// A slider has no MP4 deliverable — steer the agent to get_slider instead
+			// of the misleading "not ready" path (a completed slider IS ready, but its
+			// video_url is null by design).
+			if (args.kind === "slider") {
+				return fail(
+					"A slider (carousel) has no MP4 to download. Use get_slider to read the per-slide image URLs.",
+				);
+			}
 			const status = await fetchStatus(client, args.kind, args.slug);
 			if (!status.ready || !status.video_url) {
 				return fail(
@@ -3270,6 +4069,2111 @@ registerTool(
 	),
 );
 
+// ── Campaign engine: product sources ─────────────────────────────────────────
+//
+// The "delegate my social content" surface. An agent ingests a product page,
+// persists a durable product/brand identity, plans a campaign, and creates a
+// pack full of editable DRAFTS — all at $0 (the planning tools meter the FREE
+// daily AI-assist quota; materialize creates 0-credit drafts). Generation/render
+// stays a SEPARATE, explicit, PAID step (autopilot/generate per draft).
+//
+// GROUND TRUTH: none of the campaign controllers mount the Idempotency plug, so
+// these tools send NO Idempotency-Key and their idempotentHint reflects the
+// server's real behavior (creates fork on retry; materialize is idempotent via a
+// server-side row lock; extract is stateless).
+
+registerTool(
+	"extract_product_page",
+	{
+		title: "Extract product facts from a URL",
+		description:
+			"Fetches a public product page SERVER-SIDE (SSRF-guarded, HTML-only, no redirects to internal ranges) " +
+			"and returns parsed product facts: name, description, benefits, price, brand, plus candidate product " +
+			"image URLs and a site/brand logo URL (URLs only — images are NOT downloaded here). Stateless: writes " +
+			"nothing and spends 0 credits. Scope: video:generate. Rate limit: 30/min. " +
+			"Next: create_product_profile from these facts, then import_product_image to pull the primary image + logo " +
+			"into the profile — or just call create_campaign to do all of that end to end.",
+		inputSchema: {
+			url: z
+				.string()
+				.max(2048)
+				.describe("Absolute http(s) URL of a product page (≤2048 chars)"),
+		},
+		annotations: {
+			title: "Extract product page",
+			...WRITE,
+			// Stateless (no DB write, no credit) → replaying the same URL is safe.
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { url: string }, client) => {
+		const url = args.url?.trim();
+		if (!url) return fail("url is required.");
+		const res = await client.post<{ data: unknown }>(
+			"/product-sources/extract",
+			{ url },
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"import_product_image",
+	{
+		title: "Import a product image URL into a profile",
+		description:
+			"Fetches an image at a public URL SERVER-SIDE (SSRF-guarded, JPEG/PNG only — verified by magic bytes, not " +
+			"just the Content-Type — size-capped) and stores it as a ready catalog asset, linking it to a product " +
+			"profile. link_as 'primary_image' (default) sets the profile's product image; 'logo' sets its logo. " +
+			"Spends 0 credits. Scope: video:generate. Rate limit: 30/min. Use the image/logo URLs from " +
+			"extract_product_page. 404 if the product profile isn't yours; 422 if the URL isn't a safe JPG/PNG.",
+		inputSchema: {
+			product_profile_id: z
+				.number()
+				.int()
+				.describe("Id of one of YOUR product profiles to link the image to"),
+			url: z
+				.string()
+				.max(2048)
+				.describe("Absolute http(s) URL of a JPG/PNG image (≤2048 chars)"),
+			link_as: z
+				.enum(["primary_image", "logo"])
+				.optional()
+				.describe(
+					"Which profile field to set: 'primary_image' (default) or 'logo'",
+				),
+		},
+		annotations: {
+			title: "Import product image",
+			...WRITE,
+			// Each call stores a NEW catalog asset (no idempotency plug) → not idempotent.
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				product_profile_id: number;
+				url: string;
+				link_as?: "primary_image" | "logo";
+			},
+			client,
+		) => {
+			const url = args.url?.trim();
+			if (!url) return fail("url is required.");
+			// The controller keys the image URL off `image_url` (distinct from
+			// extract's `url`); map the agent-facing `url` onto it.
+			const body: Record<string, unknown> = {
+				image_url: url,
+				product_profile_id: args.product_profile_id,
+			};
+			if (args.link_as !== undefined) body.link_as = args.link_as;
+			const res = await client.post<{ data: unknown }>(
+				"/product-sources/import-image",
+				body,
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+// ── Campaign engine: product profiles ────────────────────────────────────────
+
+registerTool(
+	"list_product_profiles",
+	{
+		title: "List your product profiles",
+		description:
+			"Lists your saved product fact sheets (name, benefits, offer, audience, CTA, compliance constraints, " +
+			"imported image/logo keys), newest first. Read-only, 0 credits. Scope: video:read. Pass an id to plan_campaign / " +
+			"generate_hook_variations / create_campaign_pack so a campaign is planned from a saved source of truth.",
+		inputSchema: {},
+		annotations: { title: "List product profiles", ...RO },
+	},
+	tool(async (_args, client) => ok(await client.get("/product-profiles"))),
+);
+
+registerTool(
+	"create_product_profile",
+	{
+		title: "Create a product profile",
+		description:
+			"Saves a reusable product fact sheet. Only `name` is required; the rest (description, benefits[], offer, " +
+			"proof_points[], audience, cta, banned_claims[], brand_tone) ground the AI when planning/generating. " +
+			"0 credits. Scope: video:generate. Tip: seed it from extract_product_page's facts. To attach imagery, call " +
+			"import_product_image afterwards (sets primary_image/logo).",
+		inputSchema: {
+			name: z.string().min(1).max(300).describe("Product name (required)"),
+			description: z
+				.string()
+				.max(4000)
+				.optional()
+				.describe("What the product is / does"),
+			benefits: z
+				.array(z.string())
+				.optional()
+				.describe("Key benefit statements"),
+			offer: z
+				.string()
+				.max(500)
+				.optional()
+				.describe("Headline offer / price / promotion"),
+			proof_points: z
+				.array(z.string())
+				.optional()
+				.describe("Ratings, review counts, other proof points"),
+			audience: z.string().max(500).optional().describe("Target audience"),
+			cta: z.string().max(300).optional().describe("Preferred call to action"),
+			banned_claims: z
+				.array(z.string())
+				.optional()
+				.describe("Claims the product must never make"),
+			brand_tone: z
+				.string()
+				.max(500)
+				.optional()
+				.describe("Tone of voice for generated copy"),
+			source_url: z
+				.string()
+				.max(2048)
+				.optional()
+				.describe("Product page URL the facts came from"),
+		},
+		annotations: {
+			title: "Create product profile",
+			...WRITE,
+			// No idempotency plug → a retry forks a duplicate profile.
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: Record<string, unknown>, client) => {
+		const res = await client.post<{ data: unknown }>(
+			"/product-profiles",
+			pickProductProfileFields(args),
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"update_product_profile",
+	{
+		title: "Update a product profile",
+		description:
+			"Patches a saved product profile — only the fields you pass change. 0 credits. Scope: video:generate. " +
+			"404 for an unknown/foreign id.",
+		inputSchema: {
+			id: z.number().int().describe("Product profile id"),
+			name: z.string().min(1).max(300).optional().describe("Product name"),
+			description: z.string().max(4000).optional(),
+			benefits: z.array(z.string()).optional(),
+			offer: z.string().max(500).optional(),
+			proof_points: z.array(z.string()).optional(),
+			audience: z.string().max(500).optional(),
+			cta: z.string().max(300).optional(),
+			banned_claims: z.array(z.string()).optional(),
+			brand_tone: z.string().max(500).optional(),
+			source_url: z.string().max(2048).optional(),
+		},
+		annotations: {
+			title: "Update product profile",
+			...WRITE,
+			// PATCH by id → replaying is naturally idempotent (same fields → same state).
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { id: number } & Record<string, unknown>, client) => {
+		const res = await client.patch<{ data: unknown }>(
+			`/product-profiles/${args.id}`,
+			pickProductProfileFields(args),
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+// ── Campaign engine: brand profiles ──────────────────────────────────────────
+
+registerTool(
+	"list_brand_profiles",
+	{
+		title: "List your brand profiles",
+		description:
+			"Lists your saved brand identities (name, logo key, colors, font, tone words, default CTA/audience, " +
+			"preferred visual_language/creative_format, and linked assets), newest first. Read-only, 0 credits. " +
+			"Scope: video:read. Pass an id as brand_profile_id to generate_hook_variations / create_campaign_pack / " +
+			"create_campaign to steer tone/format and inherit the logo into materialized drafts.",
+		inputSchema: {},
+		annotations: { title: "List brand profiles", ...RO },
+	},
+	tool(async (_args, client) => ok(await client.get("/brand-profiles"))),
+);
+
+registerTool(
+	"create_brand_profile",
+	{
+		title: "Create a brand profile",
+		description:
+			"Saves a reusable brand identity. Only `name` is required. primary_color/secondary_color are hex " +
+			"(e.g. #09EFBE); preferred_visual_language and preferred_creative_format take the same values as the " +
+			"editor/short tools; tone_words[]/default_cta/default_audience/banned_claims[] steer generated copy. " +
+			"0 credits. Scope: video:generate. Attach a logo/product asset from your catalog with " +
+			"update_brand_profile (attach_catalog_asset_id).",
+		inputSchema: {
+			name: z.string().min(1).max(300).describe("Brand name (required)"),
+			logo_s3_key: z
+				.string()
+				.optional()
+				.describe("S3 key of the brand logo (from an import/upload)"),
+			primary_color: z.string().optional().describe("Hex color, e.g. #ffffff"),
+			secondary_color: z
+				.string()
+				.optional()
+				.describe("Hex color, e.g. #ffffff"),
+			font_family: z
+				.string()
+				.optional()
+				.describe("Brand typography (a supported Shorts overlay font)"),
+			tone_words: z
+				.array(z.string())
+				.optional()
+				.describe("Tone descriptors, e.g. ['bold','warm']"),
+			default_cta: z.string().max(300).optional(),
+			default_audience: z.string().max(500).optional(),
+			banned_claims: z.array(z.string()).optional(),
+			preferred_visual_language: z
+				.enum(VISUAL_LANGUAGES)
+				.optional()
+				.describe("Default visual language for generated videos"),
+			preferred_creative_format: z
+				.enum(CREATIVE_FORMATS)
+				.optional()
+				.describe("Default creative format for generated videos"),
+		},
+		annotations: {
+			title: "Create brand profile",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: Record<string, unknown>, client) => {
+		const res = await client.post<{ data: unknown }>(
+			"/brand-profiles",
+			pickBrandProfileFields(args),
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
+registerTool(
+	"update_brand_profile",
+	{
+		title: "Update a brand profile (+ attach/detach assets)",
+		description:
+			"Patches a saved brand profile — only the fields you pass change. 0 credits. Scope: video:generate. " +
+			"You can ALSO manage its catalog-asset links in the same call: attach_catalog_asset_id links one of your " +
+			"catalog assets (role required: 'logo' | 'product_image' | 'other'); detach_asset_id removes an existing " +
+			"link by its LINK id (from the profile's assets[].id, not the catalog_asset_id). 404 for an unknown/foreign " +
+			"profile; 422 if the catalog asset isn't yours. Returns the updated profile with its assets.",
+		inputSchema: {
+			id: z.number().int().describe("Brand profile id"),
+			name: z.string().min(1).max(300).optional(),
+			logo_s3_key: z.string().optional(),
+			primary_color: z.string().optional().describe("Hex color, e.g. #ffffff"),
+			secondary_color: z.string().optional().describe("Hex color"),
+			font_family: z.string().optional(),
+			tone_words: z.array(z.string()).optional(),
+			default_cta: z.string().max(300).optional(),
+			default_audience: z.string().max(500).optional(),
+			banned_claims: z.array(z.string()).optional(),
+			preferred_visual_language: z.enum(VISUAL_LANGUAGES).optional(),
+			preferred_creative_format: z.enum(CREATIVE_FORMATS).optional(),
+			attach_catalog_asset_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Link this catalog asset id to the profile (requires asset_role)",
+				),
+			asset_role: z
+				.enum(["logo", "product_image", "other"])
+				.optional()
+				.describe("Role for attach_catalog_asset_id (required when attaching)"),
+			detach_asset_id: z
+				.number()
+				.int()
+				.optional()
+				.describe("Remove this asset LINK id (assets[].id) from the profile"),
+		},
+		annotations: {
+			title: "Update brand profile",
+			...WRITE,
+			// The PATCH itself is idempotent, but attach/detach sub-calls create/delete
+			// links (not idempotency-keyed), so a blind retry isn't a clean no-op.
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				id: number;
+				attach_catalog_asset_id?: number;
+				asset_role?: "logo" | "product_image" | "other";
+				detach_asset_id?: number;
+			} & Record<string, unknown>,
+			client,
+		) => {
+			if (
+				args.attach_catalog_asset_id !== undefined &&
+				args.asset_role === undefined
+			) {
+				return fail(
+					"asset_role is required when attach_catalog_asset_id is set ('logo' | 'product_image' | 'other').",
+				);
+			}
+			// 1) Patch the scalar brand fields when any were supplied.
+			const fields = pickBrandProfileFields(args);
+			if (Object.keys(fields).length > 0) {
+				await client.patch(`/brand-profiles/${args.id}`, fields);
+			}
+			// 2) Attach a catalog asset (separate endpoint keyed on catalog_asset_id).
+			if (args.attach_catalog_asset_id !== undefined) {
+				await client.post(`/brand-profiles/${args.id}/assets`, {
+					catalog_asset_id: args.attach_catalog_asset_id,
+					role: args.asset_role,
+				});
+			}
+			// 3) Detach an asset LINK by its id (204 No Content).
+			if (args.detach_asset_id !== undefined) {
+				await client.del(
+					`/brand-profiles/${args.id}/assets/${args.detach_asset_id}`,
+				);
+			}
+			// Return the fresh profile with its (updated) assets.
+			const res = await client.get<{ data: unknown }>(
+				`/brand-profiles/${args.id}`,
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+// ── Campaign engine: planning (free AI-assist quota) ──────────────────────────
+
+registerTool(
+	"plan_campaign",
+	{
+		title: "Plan a campaign from product facts",
+		description:
+			"Turns product facts (a saved product_profile_id OR an inline product with a name) into a campaign PLAN: " +
+			"ad hooks, recommended output formats, a one-line positioning statement, and a transparent credit ESTIMATE " +
+			"for the proposed paid outputs. Generates no media and persists nothing. Spends $0 — it consumes the FREE " +
+			"daily AI-assist quota (NOT credits). Scope: video:generate. Rate limit: 30/min. On 429 the quota is " +
+			"exhausted: set auto_unlock:true to spend 1 credit for +10 assists (retried once) or call unlock_ai_assists. " +
+			"Next: generate_hook_variations for draftable variations, then create_campaign_pack.",
+		inputSchema: {
+			product_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe("Id of a saved product profile (OR pass product)"),
+			product: z
+				.object({
+					name: z.string(),
+					description: z.string().optional(),
+					benefits: z.array(z.string()).optional(),
+					offer: z.string().optional(),
+					proof_points: z.array(z.string()).optional(),
+					audience: z.string().optional(),
+					cta: z.string().optional(),
+					banned_claims: z.array(z.string()).optional(),
+				})
+				.optional()
+				.describe(
+					"Inline product facts (name required) if you have no profile",
+				),
+			goal: z
+				.string()
+				.optional()
+				.describe("Campaign goal, e.g. awareness or conversion"),
+			platform: z
+				.string()
+				.optional()
+				.describe("Target platform, e.g. tiktok, instagram, reels, shorts"),
+			language: z
+				.string()
+				.optional()
+				.describe('Viewer-facing language code, e.g. "en" (default)'),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: {
+			title: "Plan campaign",
+			...WRITE,
+			// Consumes the free quota (a side effect) → not idempotent.
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				product_profile_id?: number;
+				product?: Record<string, unknown>;
+				goal?: string;
+				platform?: string;
+				language?: string;
+				auto_unlock?: boolean;
+			},
+			client,
+		) => {
+			const srcErr = validatePlanSource(
+				args.product_profile_id,
+				args.product as { name?: unknown } | undefined,
+			);
+			if (srcErr) return fail(srcErr);
+			const body = buildPlanBody(args);
+			const res = await withAssist(client, args.auto_unlock ?? false, () =>
+				client.post<{ data: unknown }>("/campaign-packs/plan", body),
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"generate_hook_variations",
+	{
+		title: "Generate a hook variations board",
+		description:
+			"Turns product facts (a saved product_profile_id OR an inline product with a name) and an OPTIONAL " +
+			"brand_profile_id into 3-6 distinct hook variations — each with a hook, angle, suggested output format " +
+			"(editor_ad/short/carousel), a draft script, a ready-to-post caption, hashtags, and a per-variation credit " +
+			"ESTIMATE. Generates no media and persists nothing. Spends $0 — it consumes the FREE daily AI-assist quota " +
+			"(NOT credits). Scope: video:generate. Rate limit: 30/min. On 429 set auto_unlock:true (1 credit → +10 " +
+			"assists, retried once) or call unlock_ai_assists. Next: create_campaign_pack, then add_pack_variations to " +
+			"persist + materialize the ones you pick as DRAFTS.",
+		inputSchema: {
+			product_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe("Id of a saved product profile (OR pass product)"),
+			product: z
+				.object({
+					name: z.string(),
+					description: z.string().optional(),
+					benefits: z.array(z.string()).optional(),
+					offer: z.string().optional(),
+					proof_points: z.array(z.string()).optional(),
+					audience: z.string().optional(),
+					cta: z.string().optional(),
+					banned_claims: z.array(z.string()).optional(),
+				})
+				.optional()
+				.describe(
+					"Inline product facts (name required) if you have no profile",
+				),
+			brand_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Optional saved brand profile to steer tone/format/banned claims",
+				),
+			count: z
+				.number()
+				.int()
+				.optional()
+				.describe("Desired number of variations, clamped to 3-6 (default 4)"),
+			goal: z.string().optional().describe("Campaign goal"),
+			platform: z
+				.string()
+				.optional()
+				.describe("Target platform, e.g. tiktok, instagram"),
+			language: z
+				.string()
+				.optional()
+				.describe('Viewer-facing language code, e.g. "en" (default)'),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: {
+			title: "Generate hook variations",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				product_profile_id?: number;
+				product?: Record<string, unknown>;
+				brand_profile_id?: number;
+				count?: number;
+				goal?: string;
+				platform?: string;
+				language?: string;
+				auto_unlock?: boolean;
+			},
+			client,
+		) => {
+			const srcErr = validatePlanSource(
+				args.product_profile_id,
+				args.product as { name?: unknown } | undefined,
+			);
+			if (srcErr) return fail(srcErr);
+			const body = buildPlanBody(args);
+			const res = await withAssist(client, args.auto_unlock ?? false, () =>
+				client.post<{ data: unknown }>("/campaign-packs/hook-variations", body),
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+// ── Campaign engine: packs (persist / materialize) ───────────────────────────
+
+registerTool(
+	"create_campaign_pack",
+	{
+		title: "Persist a campaign pack",
+		description:
+			"Stores a campaign pack (the planning container) plus any inline TEXT items (hook/caption copy). editor_ad/" +
+			"short/carousel items are NOT created here — persist them via add_pack_variations (which also materializes " +
+			"them into drafts). Spends 0 credits. Scope: video:generate. Link a product_profile_id and/or brand_profile_id " +
+			"so materialized drafts inherit the product image + brand logo. Returns the pack id + items. Next: " +
+			"add_pack_variations to fill it with draftable outputs.",
+		inputSchema: {
+			title: z
+				.string()
+				.max(300)
+				.optional()
+				.describe("Human-friendly pack name"),
+			product_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Saved product profile to ground the pack (422 if not yours)",
+				),
+			brand_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Saved brand profile applied to the pack + materialized drafts",
+				),
+			brief: z
+				.string()
+				.max(4000)
+				.optional()
+				.describe("Freeform brief for the campaign"),
+			source_type: z
+				.enum(["url", "image", "brief", "asset"])
+				.optional()
+				.describe("Where the pack originated"),
+			source_url: z
+				.string()
+				.max(2048)
+				.optional()
+				.describe("Origin URL when source_type is 'url'"),
+			language: z
+				.string()
+				.optional()
+				.describe(
+					"Language stored on the pack + used for materialized draft copy",
+				),
+			items: z
+				.array(
+					z.object({
+						kind: z
+							.enum(["hook", "caption"])
+							.describe("Only hook/caption text items persist here"),
+						hook: z.string().optional(),
+						caption: z.string().optional(),
+						hashtags: z.array(z.string()).optional(),
+					}),
+				)
+				.optional()
+				.describe("Optional inline hook/caption copy items"),
+		},
+		annotations: {
+			title: "Create campaign pack",
+			...WRITE,
+			// No idempotency plug → a retry forks a duplicate pack.
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				title?: string;
+				product_profile_id?: number;
+				brand_profile_id?: number;
+				brief?: string;
+				source_type?: string;
+				source_url?: string;
+				language?: string;
+				items?: Array<Record<string, unknown>>;
+			},
+			client,
+		) => {
+			const body: Record<string, unknown> = {};
+			if (args.title !== undefined) body.title = args.title;
+			if (args.product_profile_id !== undefined)
+				body.product_profile_id = args.product_profile_id;
+			if (args.brand_profile_id !== undefined)
+				body.brand_profile_id = args.brand_profile_id;
+			if (args.brief !== undefined) body.brief = args.brief;
+			if (args.source_type !== undefined) body.source_type = args.source_type;
+			if (args.source_url !== undefined) body.source_url = args.source_url;
+			if (args.language !== undefined) body.language = args.language;
+			if (args.items !== undefined) body.items = args.items;
+			const res = await client.post<{ data: unknown }>("/campaign-packs", body);
+			return ok(summarizePack(asRecord(res).data));
+		},
+	),
+);
+
+registerTool(
+	"list_campaign_packs",
+	{
+		title: "List your campaign packs",
+		description:
+			"Lists your campaign packs (newest first) at the PACK level only: id, title, status, source, and linked " +
+			"product/brand profile. It does NOT include per-item detail — the list endpoint doesn't load items, so " +
+			"per-item kind/status/draft slug/deep-link route/credit estimate come from get_campaign_pack({ id }). " +
+			"Read-only, 0 credits. Scope: video:read.",
+		inputSchema: {},
+		annotations: { title: "List campaign packs", ...RO },
+	},
+	tool(async (_args, client) => {
+		const res = await client.get<{ data: unknown }>("/campaign-packs");
+		const data = asRecord(res).data;
+		// The list endpoint does NOT preload items (they'd serialize as []); emit
+		// pack-level fields only and point the agent at get_campaign_pack for items.
+		const packs = Array.isArray(data) ? data.map(summarizePackListEntry) : [];
+		return ok({ packs });
+	}),
+);
+
+registerTool(
+	"get_campaign_pack",
+	{
+		title: "Get one campaign pack with its items",
+		description:
+			"Returns a campaign pack and its items. Per item you get: kind, status (planned → draft → generating → " +
+			"completed | failed), the materialized DRAFT slug + deep-link route (editor_ad/short → the video project, " +
+			"carousel → the slider), the per-item credit ESTIMATE, and — once an item has been generated — its " +
+			"preview_url/video_result_id. Read-only, 0 credits. Scope: video:read. Use the draft slugs to generate each " +
+			"output EXPLICITLY (a separate, PAID step): start_autopilot/generate for videos, generate_slider for carousels.",
+		inputSchema: {
+			id: z.number().int().describe("Campaign pack id"),
+		},
+		outputSchema: getCampaignPackOutput,
+		annotations: { title: "Get campaign pack", ...RO },
+	},
+	tool(async (args: { id: number }, client) => {
+		const res = await client.get<{ data: unknown }>(
+			`/campaign-packs/${args.id}`,
+		);
+		return ok(summarizePack(asRecord(res).data));
+	}),
+);
+
+registerTool(
+	"add_pack_variations",
+	{
+		title: "Add + materialize hook variations to a pack",
+		description:
+			"Persists a batch of selected hook variations (from generate_hook_variations) as items under a pack and, by " +
+			"default (materialize:true), turns each into an editable DRAFT (a video project or image slider). Spends 0 " +
+			"credits — nothing is generated/rendered (that's a separate PAID step). Scope: video:generate. Caps: at most " +
+			"12 variations per call; rate-limited to 15/min. Per-variation BEST-EFFORT: a variation that can't be " +
+			"materialized (e.g. you hit a draft limit) stays a 'planned' item with a recorded reason while the rest still " +
+			"materialize — the response summary lists created/materialized/planned + skipped_reasons. Pass the variation " +
+			"objects verbatim from the board (each needs at least suggested_format). Next: get_campaign_pack to review, " +
+			"then generate each draft explicitly.",
+		inputSchema: {
+			pack_id: z
+				.number()
+				.int()
+				.describe("Campaign pack id (from create_campaign_pack)"),
+			variations: z
+				.array(
+					z.object({
+						suggested_format: z
+							.enum(["editor_ad", "short", "carousel"])
+							.describe("Output kind for this variation"),
+						hook: z.string().optional(),
+						angle: z.string().optional(),
+						draft_script: z.string().optional(),
+						caption: z.string().optional(),
+						hashtags: z.array(z.string()).optional(),
+						credit_estimate: z.record(z.unknown()).optional(),
+					}),
+				)
+				.describe("1-12 variations to persist (echo them from the board)"),
+			materialize: z
+				.boolean()
+				.optional()
+				.describe(
+					"Materialize each into a draft (default true); false keeps them planned",
+				),
+		},
+		annotations: {
+			title: "Add pack variations",
+			...WRITE,
+			// Each call creates NEW items (no idempotency plug) → not idempotent.
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				pack_id: number;
+				variations: Array<Record<string, unknown>>;
+				materialize?: boolean;
+			},
+			client,
+		) => {
+			const err = validateVariationsBatch(args.variations);
+			if (err) return fail(err);
+			const body: Record<string, unknown> = { variations: args.variations };
+			if (args.materialize !== undefined) body.materialize = args.materialize;
+			const res = await client.post<{ data: unknown }>(
+				`/campaign-packs/${args.pack_id}/variations`,
+				body,
+			);
+			const data = asRecord(asRecord(res).data);
+			const items = Array.isArray(data.items)
+				? data.items.map(summarizePackItem)
+				: [];
+			return ok({
+				campaign_pack_id: data.campaign_pack_id ?? args.pack_id,
+				items,
+				summary: data.summary ?? null,
+				next: "get_campaign_pack to review the drafts; generation/render is a separate, explicit, PAID step per draft.",
+			});
+		},
+	),
+);
+
+registerTool(
+	"materialize_pack_item",
+	{
+		title: "Materialize one planned pack item into a draft",
+		description:
+			"Turns a single PLANNED editor_ad/short/carousel item into an editable DRAFT (a video project or image " +
+			"slider) and links it back to the item. Spends 0 credits — generation/render is a separate PAID step. " +
+			"Scope: video:generate. Rate limit: 60/min. Safe to retry: NO duplicate draft is ever created (a concurrent " +
+			"race loser converges on the same draft under a row lock). A SEQUENTIAL re-call of an already-materialized " +
+			"item returns 422 ('already materialized') — that 422 means the draft already exists; read it via " +
+			"get_campaign_pack. 422 also for hook/caption items or when you hit a draft limit. Prefer add_pack_variations " +
+			"to materialize a batch at once; use this to (re)try one item.",
+		inputSchema: {
+			pack_id: z.number().int().describe("Campaign pack id"),
+			item_id: z
+				.number()
+				.int()
+				.describe("Campaign pack item id (from get_campaign_pack)"),
+		},
+		annotations: {
+			title: "Materialize pack item",
+			...WRITE,
+			// idempotentHint in the "no duplicate is ever created" sense: the server
+			// locks the item row and re-asserts the output ref is still null, so a
+			// concurrent race loser converges on the SAME draft. A sequential replay is
+			// rejected 422 by the pre-lock ensure_materializable (already materialized) —
+			// it never forks a second draft.
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { pack_id: number; item_id: number }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/campaign-packs/${args.pack_id}/items/${args.item_id}/materialize`,
+		);
+		return ok(summarizePackItem(asRecord(res).data));
+	}),
+);
+
+// ── Campaign engine: high-level orchestrator ─────────────────────────────────
+
+registerTool(
+	"create_campaign",
+	{
+		title: "Create a whole campaign from a product (one shot)",
+		description:
+			"The high-level path (like make_video, but for a content CAMPAIGN): give a product URL (or a saved " +
+			"product_profile_id) and get back a persisted campaign pack full of editable DRAFTS. It runs the whole " +
+			"pipeline — extract the page (if a url) → save a product profile → best-effort import the primary image + " +
+			"logo → plan → generate hook variations → create the pack → add the variations as materialized DRAFTS. " +
+			"Spends $0 end to end: it only ever touches the FREE daily AI-assist quota (plan + hook variations) and " +
+			"creates 0-credit drafts. It NEVER starts autopilot/generation/render — that stays a SEPARATE, explicit, " +
+			"PAID step you trigger per draft afterwards. Scope: video:generate. On a partial failure it returns " +
+			"everything achieved so far (profile id, pack id, per-item status) plus precise resume guidance naming the " +
+			"granular tool to continue with. The result lists each draft's slug + kind + per-item credit estimate.",
+		inputSchema: {
+			url: z
+				.string()
+				.max(2048)
+				.optional()
+				.describe(
+					"Product page URL to ingest (required unless product_profile_id is given)",
+				),
+			product_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe("Use a saved product profile instead of extracting a URL"),
+			brand_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Optional saved brand profile — steers hooks and gives drafts your logo/brand",
+				),
+			item_count: z
+				.number()
+				.int()
+				.optional()
+				.describe("How many variations to aim for, clamped to 3-6 (default 6)"),
+			formats: z
+				.array(z.enum(["editor_ad", "short", "carousel"]))
+				.optional()
+				.describe(
+					"Restrict to these output formats (default: whatever the board recommends)",
+				),
+			language: z
+				.string()
+				.optional()
+				.describe('Viewer-facing language code, e.g. "en" (default)'),
+			goal: z.string().optional().describe("Campaign goal, e.g. conversion"),
+			platform: z
+				.string()
+				.optional()
+				.describe("Target platform, e.g. tiktok, instagram"),
+		},
+		annotations: {
+			title: "Create campaign",
+			...WRITE,
+			// Multi-step create pipeline (profiles, pack, items — none idempotency-keyed);
+			// a blind re-run forks new rows. Resume with the granular tools instead.
+			idempotentHint: false,
+		},
+		outputSchema: createCampaignOutput,
+	},
+	tool(async (args: CreateCampaignArgs, client) => {
+		if (!args.url && args.product_profile_id === undefined) {
+			return fail("Provide either url or product_profile_id.");
+		}
+		const result = await runCreateCampaign(client, args, (msg) =>
+			console.error(`[create_campaign] ${msg}`),
+		);
+		return ok(result);
+	}),
+);
+
+// ── Series: recurring-content shows ───────────────────────────────────────────
+
+registerTool(
+	"create_series",
+	{
+		title: "Create a recurring-content series",
+		description:
+			"Creates a reusable recurring-content SHOW template (e.g. 'Myth vs Fact', 'Founder Tip') bound to an " +
+			"optional brand + product profile — the durable format the episode planner draws upcoming ideas from. " +
+			"name and template are required. Spends 0 credits. Scope: video:generate. A supplied " +
+			"brand_profile_id/product_profile_id must be one of your own (422 invalid_brand_profile/" +
+			"invalid_product_profile otherwise). Next: plan_series_episodes to draft idea episodes.",
+		inputSchema: {
+			name: z
+				.string()
+				.max(300)
+				.describe("Show name, e.g. 'Myth vs Fact' (required)"),
+			template: z
+				.enum([
+					"founder_tip",
+					"myth_vs_fact",
+					"before_after",
+					"customer_question",
+					"build_in_public",
+					"product_demo_of_the_week",
+					"mistake_to_avoid",
+				])
+				.describe(
+					"The recurring format/template (required). One of: founder_tip, myth_vs_fact, " +
+						"before_after, customer_question, build_in_public, product_demo_of_the_week, mistake_to_avoid",
+				),
+			brand_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Optional saved brand profile the series (and its drafts) inherit",
+				),
+			product_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe("Optional saved product profile grounding episode ideas"),
+			cadence: z
+				.enum(["weekly", "biweekly", "monthly"])
+				.optional()
+				.describe(
+					"Posting cadence: weekly, biweekly, or monthly (steers the ideas)",
+				),
+			tone: z
+				.string()
+				.optional()
+				.describe("Editorial tone, e.g. playful, expert"),
+			default_format: z
+				.enum(["editor_ad", "short", "carousel"])
+				.optional()
+				.describe("Default output format for materialized episodes"),
+			status: z
+				.enum(["active", "paused", "archived"])
+				.optional()
+				.describe("Series status (default active)"),
+		},
+		annotations: {
+			title: "Create series",
+			...WRITE,
+			// No idempotency plug on the series controller → a retry forks a duplicate.
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				name: string;
+				template: string;
+				brand_profile_id?: number;
+				product_profile_id?: number;
+				cadence?: string;
+				tone?: string;
+				default_format?: string;
+				status?: string;
+			},
+			client,
+		) => {
+			const res = await client.post<{ data: unknown }>(
+				"/series",
+				pickSeriesFields(args),
+			);
+			return ok(summarizeSeries(asRecord(res).data));
+		},
+	),
+);
+
+registerTool(
+	"list_series",
+	{
+		title: "List your series",
+		description:
+			"Lists your recurring-content series (newest first), each summarized with its status, template, cadence, " +
+			"tone, default format, and linked brand/product profile + rolling campaign pack ids. Read-only, 0 credits. " +
+			"Scope: video:read. Use get_series_dashboard for one series' episodes grouped by lane.",
+		inputSchema: {},
+		annotations: { title: "List series", ...RO },
+	},
+	tool(async (_args, client) => {
+		const res = await client.get<{ data: unknown }>("/series");
+		const data = asRecord(res).data;
+		const series = Array.isArray(data) ? data.map(summarizeSeries) : [];
+		return ok({ series });
+	}),
+);
+
+registerTool(
+	"update_series",
+	{
+		title: "Update a series",
+		description:
+			"Patches one of your series; only the fields you pass change. Toggle status among active/paused/archived " +
+			"(a paused series stops surfacing for new ideas). A changed brand_profile_id/product_profile_id is " +
+			"re-verified against your own profiles (422 otherwise). Spends 0 credits. Scope: video:generate. " +
+			"404 for an unknown/foreign series.",
+		inputSchema: {
+			id: z.number().int().describe("Series id"),
+			name: z.string().max(300).optional().describe("Show name"),
+			template: z
+				.enum([
+					"founder_tip",
+					"myth_vs_fact",
+					"before_after",
+					"customer_question",
+					"build_in_public",
+					"product_demo_of_the_week",
+					"mistake_to_avoid",
+				])
+				.optional()
+				.describe(
+					"Recurring format/template. One of: founder_tip, myth_vs_fact, before_after, " +
+						"customer_question, build_in_public, product_demo_of_the_week, mistake_to_avoid",
+				),
+			brand_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe("Saved brand profile to bind (422 if not yours)"),
+			product_profile_id: z
+				.number()
+				.int()
+				.optional()
+				.describe("Saved product profile to bind (422 if not yours)"),
+			cadence: z
+				.enum(["weekly", "biweekly", "monthly"])
+				.optional()
+				.describe("Posting cadence: weekly, biweekly, or monthly"),
+			tone: z.string().optional().describe("Editorial tone"),
+			default_format: z
+				.enum(["editor_ad", "short", "carousel"])
+				.optional()
+				.describe("Default output format for materialized episodes"),
+			status: z
+				.enum(["active", "paused", "archived"])
+				.optional()
+				.describe("Series status"),
+		},
+		annotations: { title: "Update series", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: {
+				id: number;
+				name?: string;
+				template?: string;
+				brand_profile_id?: number;
+				product_profile_id?: number;
+				cadence?: string;
+				tone?: string;
+				default_format?: string;
+				status?: string;
+			},
+			client,
+		) => {
+			const res = await client.patch<{ data: unknown }>(
+				`/series/${args.id}`,
+				pickSeriesFields(args),
+			);
+			return ok(summarizeSeries(asRecord(res).data));
+		},
+	),
+);
+
+registerTool(
+	"plan_series_episodes",
+	{
+		title: "Plan upcoming episode ideas for a series",
+		description:
+			"Drafts 3-5 distinct upcoming EPISODE ideas (status 'idea') for one of your series, grounded on its " +
+			"product profile (or name) and steered by its brand/tone/cadence, and persists them as episodes. " +
+			"Generates no media and spends $0 — it consumes the FREE daily AI-assist quota (NOT credits). " +
+			"Scope: video:generate. Rate limit: 30/min. On 429 the quota is exhausted: set auto_unlock:true to spend " +
+			"1 credit for +10 assists (retried once) or call unlock_ai_assists. 404 for an unknown/foreign series. " +
+			"Next: materialize_episode to turn a chosen idea into a 0-credit draft.",
+		inputSchema: {
+			series_id: z.number().int().describe("Series id"),
+			count: z
+				.number()
+				.int()
+				.optional()
+				.describe("Desired number of ideas, clamped to 3-5 (default 4)"),
+			language: z
+				.string()
+				.optional()
+				.describe('Viewer-facing language code, e.g. "en" (default)'),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: {
+			title: "Plan series episodes",
+			...WRITE,
+			// Consumes the free quota + persists idea episodes (a side effect) → not idempotent.
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				series_id: number;
+				count?: number;
+				language?: string;
+				auto_unlock?: boolean;
+			},
+			client,
+		) => {
+			const body: Record<string, unknown> = {};
+			if (args.count !== undefined) body.count = args.count;
+			if (args.language !== undefined && args.language.trim() !== "")
+				body.language = args.language;
+			const res = await withAssist(client, args.auto_unlock ?? false, () =>
+				client.post<{ data: unknown }>(
+					`/series/${args.series_id}/episodes/plan`,
+					body,
+				),
+			);
+			const data = asRecord(asRecord(res).data);
+			const episodes = Array.isArray(data.episodes)
+				? data.episodes.map(summarizeEpisode)
+				: [];
+			return ok({
+				series_id: args.series_id,
+				episodes,
+				ai_assist_quota: data.ai_assist_quota ?? null,
+				next: "materialize_episode({ series_id, episode_id }) to turn an idea into a 0-credit draft.",
+			});
+		},
+	),
+);
+
+registerTool(
+	"list_series_episodes",
+	{
+		title: "List a series' episodes",
+		description:
+			"Lists a series' episodes (position ascending), each summarized with its status (idea → drafted → " +
+			"published), hook/brief/caption, suggested format, and — once materialized — the draft slug + deep-link " +
+			"route (editor_ad/short → the video project, carousel → the slider). Optionally filter by status. " +
+			"Read-only, 0 credits. Scope: video:read. 404 for an unknown/foreign series.",
+		inputSchema: {
+			series_id: z.number().int().describe("Series id"),
+			status: z
+				.enum(["idea", "drafted", "published", "archived"])
+				.optional()
+				.describe("Filter to one status"),
+		},
+		annotations: { title: "List series episodes", ...RO },
+	},
+	tool(async (args: { series_id: number; status?: string }, client) => {
+		const res = await client.get<{ data: unknown }>(
+			`/series/${args.series_id}/episodes`,
+			args.status ? { status: args.status } : undefined,
+		);
+		const data = asRecord(asRecord(res).data);
+		const episodes = Array.isArray(data.episodes)
+			? data.episodes.map(summarizeEpisode)
+			: [];
+		return ok({ series_id: args.series_id, episodes });
+	}),
+);
+
+registerTool(
+	"materialize_episode",
+	{
+		title: "Materialize an episode idea into a draft",
+		description:
+			"Turns an 'idea' episode into an editable 0-credit DRAFT (a video project or image slider) grouped under " +
+			"the series' rolling campaign pack and inheriting the series' brand. Spends 0 credits — generation/render " +
+			"is a SEPARATE, explicit, PAID step. Scope: video:generate. Rate limit: 60/min. Safe to retry: NO duplicate " +
+			"draft is ever created (a concurrent race loser converges on the same draft under a row lock). A SEQUENTIAL " +
+			"re-call of an already-materialized episode returns 422 ('already materialized') — that 422 means the draft " +
+			"already exists; find it via list_series_episodes / get_series_dashboard. 422 also for a non-idea episode or " +
+			"when you hit a draft limit. Returns the drafted episode with its draft slug + kind; generate it explicitly " +
+			"next (start_autopilot/generate for videos, generate_slider for carousels).",
+		inputSchema: {
+			series_id: z.number().int().describe("Series id"),
+			episode_id: z
+				.number()
+				.int()
+				.describe(
+					"Episode id (from plan_series_episodes / list_series_episodes)",
+				),
+		},
+		annotations: {
+			title: "Materialize episode",
+			...WRITE,
+			// idempotentHint in the "no duplicate is ever created" sense: the server
+			// takes FOR UPDATE locks and re-checks materializability, so a concurrent
+			// race loser converges on the SAME draft. A sequential replay is rejected
+			// 422 by the pre-lock ensure_materializable (already materialized) — it
+			// never forks a second draft.
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { series_id: number; episode_id: number }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/series/${args.series_id}/episodes/${args.episode_id}/materialize`,
+		);
+		const episode = summarizeEpisode(asRecord(res).data);
+		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 })."
+				: "Draft created — review it with list_series_episodes.",
+		});
+	}),
+);
+
+registerTool(
+	"get_series_dashboard",
+	{
+		title: "Get a series dashboard",
+		description:
+			"Returns a read-only overview of one series: the series plus its episodes grouped into lanes — upcoming " +
+			"(ideas), drafted, and published — with per-item performance notes for episodes linked to a campaign-pack " +
+			"item. Each drafted/published episode carries its draft slug + deep-link route. Read-only, 0 credits. " +
+			"Scope: video:read. 404 for an unknown/foreign series.",
+		inputSchema: {
+			series_id: z.number().int().describe("Series id"),
+		},
+		outputSchema: getSeriesDashboardOutput,
+		annotations: { title: "Get series dashboard", ...RO },
+	},
+	tool(async (args: { series_id: number }, client) => {
+		const res = await client.get<{ data: unknown }>(
+			`/series/${args.series_id}/dashboard`,
+		);
+		return ok(summarizeDashboard(asRecord(res).data));
+	}),
+);
+
+registerTool(
+	"mark_episode_posted",
+	{
+		title: "Mark a drafted episode as posted",
+		description:
+			"Records that you posted a DRAFTED episode MANUALLY (there is no platform posting API): flips the episode " +
+			"'drafted' → 'published' (labelled 'Posted' in the app) and stamps posted_at, making the dashboard's " +
+			"published lane reachable. Spends 0 credits. Scope: video:generate. Atomic — only a drafted episode " +
+			"transitions; an idea or archived episode returns 422 invalid_status (materialize it into a draft first). " +
+			"IDEMPOTENT on replay: re-marking an already-published episode returns 200 with the original posted_at " +
+			"untouched. 404 for an unknown/foreign series or episode.",
+		inputSchema: {
+			series_id: z.number().int().describe("Series id"),
+			episode_id: z
+				.number()
+				.int()
+				.describe("Episode id (must be a drafted episode)"),
+		},
+		annotations: {
+			title: "Mark episode posted",
+			...WRITE,
+			// The server transition is a CAS whose replay it defines as a no-op 200
+			// (already-published keeps the original posted_at), so re-marking is safe.
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { series_id: number; episode_id: number }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/series/${args.series_id}/episodes/${args.episode_id}/mark-posted`,
+		);
+		return ok(summarizeEpisode(asRecord(res).data));
+	}),
+);
+
+// ── Content calendar: reminder-only scheduling ────────────────────────────────
+//
+// REMINDER-FIRST BY DESIGN: these tools schedule a completed video as a manual-
+// posting REMINDER (a push to the USER at the due time, then mark_scheduled_posted
+// to record the manual post). They NEVER accept or send a social-account id, so
+// every post is reminder-only and the pipeline WriteScope floor authorizes the
+// write with video:generate — publishing stays human. Attaching an account
+// (auto-publish) is app-only (account:admin), so a 403 insufficient_scope from
+// the write tools means the TARGETED post already carries an account, or the token
+// predates the reminder-calendar scope split — calendarWrite() spells that out.
+
+/**
+ * Wraps a calendar WRITE (schedule/reschedule/cancel) so an
+ * `insufficient_scope` 403 is re-surfaced with the reminder-only explanation
+ * (the generic errMessage would print the bare server sentence). Any other
+ * failure flows through tool()'s normal errMessage path unchanged.
+ */
+function calendarWrite<A>(
+	fn: (
+		args: A,
+		client: HubfluencerClient,
+		extra: ToolExtra,
+	) => Promise<ReturnType<typeof ok>>,
+) {
+	return tool<A>(async (args, client, extra) => {
+		try {
+			return await fn(args, client, extra);
+		} catch (e) {
+			const he = e as HubfluencerError;
+			if (he && he.status === 403) {
+				return fail(calendarScopeErrorText(he.status, he.code, errMessage(e)));
+			}
+			throw e;
+		}
+	});
+}
+
+registerTool(
+	"schedule_post",
+	{
+		title: "Schedule a posting reminder for a finished video",
+		description:
+			"Schedules one of your own COMPLETED video results for a FUTURE UTC instant as a manual-posting REMINDER: " +
+			"a push notification fires to YOU at the scheduled time and you confirm the manual post with " +
+			"mark_scheduled_posted. This tool is reminder-only — it never attaches a social account, so publishing " +
+			"stays in your hands (auto-publish is app-only). Spends 0 credits. Scope: video:generate. Get the " +
+			"video_result_id from a completed project's result (get_status/download_result) or list_scheduled_posts. " +
+			`platform is your posting INTENT (${SCHEDULED_POST_PLATFORMS.join("/")}); "other" for anywhere else. ` +
+			`Caption ≤${5000} chars; ≤${30} hashtags (each ≤${100}). At most ${MAX_PENDING_SCHEDULED_POSTS} pending ` +
+			"reminders per account (422 scheduled_post_limit_reached beyond that — cancel or mark some posted first). " +
+			"422 for a non-completed/foreign video result or a non-future instant.",
+		inputSchema: {
+			video_result_id: z
+				.number()
+				.int()
+				.describe(
+					"Id of one of your own COMPLETED video results (the render to post)",
+				),
+			platform: z
+				.enum(SCHEDULED_POST_PLATFORMS)
+				.describe('Where you intend to post: tiktok, instagram, or "other"'),
+			scheduled_at: z
+				.string()
+				.describe(
+					"The UTC instant to be reminded, ISO-8601 (must be in the future)",
+				),
+			caption: z
+				.string()
+				.optional()
+				.describe(
+					"Optional post caption to stage with the reminder (≤5000 chars)",
+				),
+			hashtags: z
+				.array(z.string())
+				.optional()
+				.describe("Optional hashtags to stage (≤30, each ≤100 chars)"),
+			timezone: z
+				.string()
+				.optional()
+				.describe("Your chosen timezone (display only), e.g. Europe/Paris"),
+			campaign_pack_item_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Optional id of one of your own campaign pack items to group under",
+				),
+		},
+		annotations: {
+			title: "Schedule post reminder",
+			...WRITE,
+			// No idempotency plug on the scheduled-post controller → a retry forks a
+			// duplicate reminder.
+			idempotentHint: false,
+		},
+	},
+	calendarWrite(
+		async (
+			args: {
+				video_result_id: number;
+				platform: string;
+				scheduled_at: string;
+				caption?: string;
+				hashtags?: string[];
+				timezone?: string;
+				campaign_pack_item_id?: number;
+			},
+			client,
+		) => {
+			const copyErr = validateScheduledPostCopy(args);
+			if (copyErr) return fail(copyErr);
+			const res = await client.post<{ data: unknown }>(
+				"/scheduled-posts",
+				buildScheduledPostBody(args),
+			);
+			return ok(summarizeScheduledPost(asRecord(res).data));
+		},
+	),
+);
+
+registerTool(
+	"list_scheduled_posts",
+	{
+		title: "List your scheduled posts (calendar)",
+		description:
+			"Lists your scheduled posts (calendar) ordered by scheduled_at ascending, each summarized with its " +
+			"platform, status, the staged caption/hashtags, the presigned export video_url (post it manually), and the " +
+			"owning video's kind. Optionally narrow the window with from/to (ISO-8601 UTC) and/or filter by status " +
+			`(${SCHEDULED_POST_STATUSES.join("/")}). Read-only, 0 credits. Scope: video:read. Account bindings are ` +
+			"intentionally omitted (this surface is reminder-only).",
+		inputSchema: {
+			from: z
+				.string()
+				.optional()
+				.describe("Lower bound (inclusive) on scheduled_at, ISO-8601 UTC"),
+			to: z
+				.string()
+				.optional()
+				.describe("Upper bound (inclusive) on scheduled_at, ISO-8601 UTC"),
+			status: z
+				.enum(SCHEDULED_POST_STATUSES)
+				.optional()
+				.describe("Filter to one status"),
+		},
+		outputSchema: listScheduledPostsOutput,
+		annotations: { title: "List scheduled posts", ...RO },
+	},
+	tool(
+		async (args: { from?: string; to?: string; status?: string }, client) => {
+			const query: Record<string, string> = {};
+			if (args.from !== undefined) query.from = args.from;
+			if (args.to !== undefined) query.to = args.to;
+			if (args.status !== undefined) query.status = args.status;
+			const res = await client.get<{ data: unknown }>(
+				"/scheduled-posts",
+				Object.keys(query).length > 0 ? query : undefined,
+			);
+			const data = asRecord(res).data;
+			const posts = Array.isArray(data) ? data.map(summarizeScheduledPost) : [];
+			return ok({ posts });
+		},
+	),
+);
+
+registerTool(
+	"reschedule_post",
+	{
+		title: "Reschedule a scheduled post",
+		description:
+			"Moves a still-'scheduled' or 'reminded' post to a new FUTURE instant (a reminded post is re-armed back to " +
+			"'scheduled' — 'remind me later'). Spends 0 credits. Scope: video:generate. 422 not_reschedulable for a " +
+			"post already posted/publishing/published/failed/canceled, or scheduled_in_past for a non-future/ malformed " +
+			"instant. 404 for unknown/foreign ids. A 403 insufficient_scope means the targeted post carries a social " +
+			"account (app-only) — reminder-only posts are reschedulable with video:generate.",
+		inputSchema: {
+			id: z.number().int().describe("Scheduled post id"),
+			scheduled_at: z
+				.string()
+				.describe("The new UTC instant, ISO-8601 (must be in the future)"),
+		},
+		annotations: { title: "Reschedule post", ...WRITE, idempotentHint: false },
+	},
+	calendarWrite(async (args: { id: number; scheduled_at: string }, client) => {
+		const res = await client.patch<{ data: unknown }>(
+			`/scheduled-posts/${args.id}`,
+			{ scheduled_at: args.scheduled_at },
+		);
+		return ok(summarizeScheduledPost(asRecord(res).data));
+	}),
+);
+
+registerTool(
+	"cancel_scheduled_post",
+	{
+		title: "Cancel a scheduled post",
+		description:
+			"Cancels a 'scheduled', 'reminded', or 'failed' post (status → 'canceled'); it will no longer fire. Spends " +
+			"0 credits. Scope: video:generate. 422 not_cancelable for a post already posted/publishing/published/" +
+			"canceled. 404 for unknown/foreign ids. A 403 insufficient_scope means the targeted post carries a social " +
+			"account (app-only) — reminder-only posts are cancelable with video:generate.",
+		inputSchema: {
+			id: z.number().int().describe("Scheduled post id"),
+		},
+		annotations: {
+			title: "Cancel scheduled post",
+			readOnlyHint: false,
+			// Cancellation is a state-destroying transition on the reminder.
+			destructiveHint: true,
+			openWorldHint: true,
+			idempotentHint: false,
+		},
+	},
+	calendarWrite(async (args: { id: number }, client) => {
+		const res = await client.del<{ data: unknown }>(
+			`/scheduled-posts/${args.id}`,
+		);
+		return ok(summarizeScheduledPost(asRecord(res).data));
+	}),
+);
+
+registerTool(
+	"mark_scheduled_posted",
+	{
+		title: "Mark a scheduled post as posted (manual posting)",
+		description:
+			"Records that you posted this content MANUALLY: transitions a 'scheduled' or 'reminded' post to 'posted' " +
+			"and stamps posted_at. Spends 0 credits. Scope: video:generate (closing the manual-posting loop is allowed " +
+			"for agent tokens). Atomic — a post in any other status (including an already-posted one, so a SECOND call) " +
+			"returns 422 not_markable; this is NOT a replayable no-op. 404 for unknown/foreign ids. Touches no platform API.",
+		inputSchema: {
+			id: z
+				.number()
+				.int()
+				.describe("Scheduled post id (a scheduled or reminded post)"),
+		},
+		annotations: {
+			title: "Mark scheduled post posted",
+			...WRITE,
+			// The CAS returns 422 not_markable on a second call (not a no-op), so a
+			// blind retry after success is NOT idempotent.
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { id: number }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/scheduled-posts/${args.id}/mark-posted`,
+		);
+		return ok(summarizeScheduledPost(asRecord(res).data));
+	}),
+);
+
+// ── Performance loop: metrics, attributes, cautious recommendation ────────────
+//
+// Attach lightweight performance snapshots + creative-attribute tags to a
+// campaign-pack ITEM (keyed by the globally-unique item id), then read a CAUTIOUS
+// aggregate recommendation over your own items. Everything here is user-scoped
+// (a foreign/unknown item is a generic 404) and spends NO video credits; only
+// make_more_like_winner consumes the free daily AI-assist quota. get_status ids
+// come from a materialized pack item (get_campaign_pack surfaces each item id).
+
+registerTool(
+	"record_performance",
+	{
+		title: "Record a performance snapshot for a campaign-pack item",
+		description:
+			"Attaches one performance snapshot (platform + engagement/conversion counts + optional revenue/watch " +
+			"time) to one of your own campaign-pack items (item_id from get_campaign_pack). Many snapshots per item " +
+			"are allowed — captured_at (defaults to now if omitted) distinguishes them, so you can log a trend over " +
+			"time. Spends 0 credits. Scope: video:generate. Rate limit: 30/min. 404 for a foreign/unknown item; 422 " +
+			"for invalid metrics. NOT idempotency-keyed — a transport retry records a DUPLICATE snapshot, so don't " +
+			"blindly retry a success.",
+		inputSchema: {
+			item_id: z
+				.number()
+				.int()
+				.describe("Campaign-pack item id (from get_campaign_pack)"),
+			platform: z
+				.enum(PERFORMANCE_PLATFORMS)
+				.describe('Where it ran: tiktok, instagram, or "other"'),
+			views: z.number().int().optional().describe("View count (≥0)"),
+			likes: z.number().int().optional().describe("Like count (≥0)"),
+			comments: z.number().int().optional().describe("Comment count (≥0)"),
+			shares: z.number().int().optional().describe("Share count (≥0)"),
+			clicks: z.number().int().optional().describe("Click count (≥0)"),
+			conversions: z
+				.number()
+				.int()
+				.optional()
+				.describe("Conversion count (≥0)"),
+			revenue: z
+				.number()
+				.optional()
+				.describe("Attributed revenue (≥0, ≤~1 trillion)"),
+			watch_time_seconds: z
+				.number()
+				.int()
+				.optional()
+				.describe("Total watch time in seconds (≥0)"),
+			source: z
+				.enum(PERFORMANCE_SOURCES)
+				.optional()
+				.describe("How the metrics were gathered (default manual)"),
+			captured_at: z
+				.string()
+				.optional()
+				.describe("When measured, ISO-8601 UTC (defaults to now; not future)"),
+			metadata: z
+				.record(z.string(), z.unknown())
+				.optional()
+				.describe("Optional provenance blob (≤16 KiB JSON)"),
+		},
+		annotations: {
+			title: "Record performance",
+			...WRITE,
+			// Append-only (many snapshots per item, no idempotency plug) → a retry
+			// forks a duplicate snapshot.
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: RecordPerformanceArgs & { item_id: number }, client) => {
+		const err = validatePerformanceMetrics(args);
+		if (err) return fail(err);
+		const res = await client.post<{ data: unknown }>(
+			`/campaign-pack-items/${args.item_id}/performance`,
+			buildPerformanceBody(args),
+		);
+		return ok({
+			...summarizePerformance(asRecord(res).data),
+			next: "set_item_attributes to tag this item's creative, then get_recommendations once a few items have both.",
+		});
+	}),
+);
+
+registerTool(
+	"list_performance",
+	{
+		title: "List a campaign-pack item's performance snapshots",
+		description:
+			"Returns one of your own campaign-pack items' performance snapshots (newest first) plus a small summary " +
+			"(latest snapshot + count). Read-only, 0 credits. Scope: video:read. 404 for a foreign/unknown item.",
+		inputSchema: {
+			item_id: z.number().int().describe("Campaign-pack item id"),
+		},
+		annotations: { title: "List performance", ...RO },
+	},
+	tool(async (args: { item_id: number }, client) => {
+		const res = await client.get<{ data: unknown }>(
+			`/campaign-pack-items/${args.item_id}/performance`,
+		);
+		const data = asRecord(asRecord(res).data);
+		const performance = Array.isArray(data.performance)
+			? data.performance.map(summarizePerformance)
+			: [];
+		return ok({
+			item_id: args.item_id,
+			performance,
+			summary: data.summary ?? null,
+		});
+	}),
+);
+
+registerTool(
+	"set_item_attributes",
+	{
+		title: "Set the creative attributes for a campaign-pack item",
+		description:
+			"Inserts-or-updates the SINGLE creative-attributes row (hook_type, creative_format, visual_language, " +
+			"product_category, cta, length, caption_style) for one of your own campaign-pack items — the tags the " +
+			"recommendation loop correlates with performance. Calling it again UPDATES the same row (atomic upsert). " +
+			"Spends 0 credits. Scope: video:generate. 404 for a foreign/unknown item; 422 for invalid attributes.",
+		inputSchema: {
+			item_id: z.number().int().describe("Campaign-pack item id"),
+			hook_type: z
+				.string()
+				.optional()
+				.describe('The hook style, e.g. "question", "bold_claim"'),
+			creative_format: z
+				.string()
+				.optional()
+				.describe('Narrative format, e.g. "problem_solution"'),
+			visual_language: z
+				.string()
+				.optional()
+				.describe('Production treatment, e.g. "ugc_realism"'),
+			product_category: z.string().optional().describe("Product category tag"),
+			cta: z.string().optional().describe("Call-to-action used"),
+			length: z.string().optional().describe('Length bucket, e.g. "short"'),
+			caption_style: z.string().optional().describe("Caption style tag"),
+			metadata: z
+				.record(z.string(), z.unknown())
+				.optional()
+				.describe("Optional extra classifiers"),
+		},
+		annotations: {
+			title: "Set item attributes",
+			...WRITE,
+			// A single upserted row: a repeat identical call converges to the same
+			// row, so re-applying is safe.
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { item_id: number } & Record<string, unknown>, client) => {
+		const res = await client.put<{ data: unknown }>(
+			`/campaign-pack-items/${args.item_id}/attributes`,
+			pickCreativeAttributeFields(args),
+		);
+		return ok(asRecord(res).data);
+	}),
+);
+
+registerTool(
+	"get_item_attributes",
+	{
+		title: "Fetch the creative attributes for a campaign-pack item",
+		description:
+			"Returns the single creative-attributes row for one of your own campaign-pack items, or null if none has " +
+			"been set. Read-only, 0 credits. Scope: video:read. 404 for a foreign/unknown item.",
+		inputSchema: {
+			item_id: z.number().int().describe("Campaign-pack item id"),
+		},
+		annotations: { title: "Get item attributes", ...RO },
+	},
+	tool(async (args: { item_id: number }, client) => {
+		const res = await client.get<{ data: unknown }>(
+			`/campaign-pack-items/${args.item_id}/attributes`,
+		);
+		return ok(asRecord(res).data ?? null);
+	}),
+);
+
+registerTool(
+	"get_recommendations",
+	{
+		title: "Cautious creative recommendation from your own performance",
+		description:
+			"Aggregates your own campaign-pack items that have BOTH creative attributes AND at least one performance " +
+			"snapshot into a CAUTIOUS recommendation: the top-performing hook_type / creative_format / visual_language " +
+			"by average views, your best items, and an HONEST confidence level. Confidence is a function of sample size " +
+			'and is returned as "none" (no data yet), "low", or "moderate" — it is NEVER overstated, and the result ' +
+			"NEVER claims causation, ROAS, or attribution: these are correlations in YOUR OWN data, a hint to test, not " +
+			"proof. Present the server's `note` and `confidence` as-is; do not upgrade them. Read-only; NO LLM; NO " +
+			"video credits; NO quota. Scope: video:read.",
+		inputSchema: {},
+		outputSchema: getRecommendationsOutput,
+		annotations: { title: "Get recommendations", ...RO },
+	},
+	tool(async (_args, client) => {
+		const res = await client.get<{ data: unknown }>(
+			"/performance/recommendations",
+		);
+		// Pass the server aggregate through UNCHANGED — the caution semantics
+		// (confidence tier + non-causal note) are the server's to state, not ours.
+		return ok(asRecord(res).data);
+	}),
+);
+
+registerTool(
+	"make_more_like_winner",
+	{
+		title: "Make more hook variations like a winning item",
+		description:
+			"Generates 3 follow-up hook variations from one of your own campaign-pack items, threading that item's " +
+			"winning angle/format/hook into the generator while keeping its brand + product profile — the way to " +
+			"double down on a proven creative. Generates no media, persists nothing, and spends NO video credits: it " +
+			"consumes the FREE daily AI-assist quota instead (429 when exhausted; set auto_unlock:true to spend 1 credit " +
+			"for +10 assists, retried once, or call unlock_ai_assists). Scope: video:generate. Rate limit: 30/min. 404 " +
+			"for a foreign/unknown item; 422 when the item has no usable product context. These are new IDEAS — feed a " +
+			"chosen one into add_pack_variations / create_campaign_pack to turn it into a draft.",
+		inputSchema: {
+			item_id: z
+				.number()
+				.int()
+				.describe("Campaign-pack item id of the winning creative"),
+			auto_unlock: z
+				.boolean()
+				.optional()
+				.describe(
+					"On 429, spend 1 credit to unlock +10 assists and retry once (default false)",
+				),
+		},
+		annotations: {
+			title: "Make more like winner",
+			...WRITE,
+			// Consumes the free quota (a side effect); no idempotency plug.
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { item_id: number; auto_unlock?: boolean }, client) => {
+		const res = await withAssist(client, args.auto_unlock ?? false, () =>
+			client.post<{ data: unknown }>(
+				`/campaign-pack-items/${args.item_id}/make-more`,
+			),
+		);
+		const data = asRecord(asRecord(res).data);
+		return ok({
+			item_id: args.item_id,
+			variations: Array.isArray(data.variations) ? data.variations : [],
+			ai_assist_quota: data.ai_assist_quota ?? null,
+			next: "Feed a chosen variation into add_pack_variations({ pack_id, variations, materialize: true }) to draft it.",
+		});
+	}),
+);
+
+// ── Review links: no-login approval loop ──────────────────────────────────────
+//
+// Mint an expiring, hashed-token review link for ONE completed output so a
+// reviewer can open /review/<token> with no account. The plaintext token is
+// returned ONCE at creation and is NOT retrievable again (only its hash is
+// stored). All user-scoped; spends 0 credits; writes need video:generate.
+
+registerTool(
+	"create_review_link",
+	{
+		title: "Create a no-login review link for one completed output",
+		description:
+			"Mints an expiring, hashed-token review link for EXACTLY ONE of your own COMPLETED outputs — a video " +
+			"result (video_result_id) OR a carousel/slider (slider_id), never both — optionally grouped under one of " +
+			"your campaign packs. The reviewer opens the returned URL with NO account. Spends 0 credits. Scope: " +
+			"video:generate. IMPORTANT: the plaintext token + review URL are returned ONCE and CANNOT be retrieved " +
+			"again (only the hash is stored) — surface them to the user immediately. expires_in_hours defaults to 168 " +
+			`(7 days) and is clamped to ${REVIEW_LINK_MIN_EXPIRES_IN_HOURS}..${REVIEW_LINK_MAX_EXPIRES_IN_HOURS}. ` +
+			"422 for a not-completed/foreign output or a foreign campaign pack.",
+		inputSchema: {
+			video_result_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Id of one of your own COMPLETED video results (mutually exclusive with slider_id)",
+				),
+			slider_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Id of one of your own COMPLETED sliders/carousels (mutually exclusive with video_result_id)",
+				),
+			campaign_pack_id: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					"Optional id of one of your own campaign packs to group under",
+				),
+			expires_in_hours: z
+				.number()
+				.int()
+				.optional()
+				.describe(
+					`How long the link stays valid; clamped ${REVIEW_LINK_MIN_EXPIRES_IN_HOURS}..${REVIEW_LINK_MAX_EXPIRES_IN_HOURS} (default 168 = 7 days)`,
+				),
+			download_enabled: z
+				.boolean()
+				.optional()
+				.describe(
+					"Whether the reviewer may download the output (default false)",
+				),
+			version_label: z
+				.string()
+				.optional()
+				.describe("Optional human label for this review version (≤120 chars)"),
+		},
+		annotations: {
+			title: "Create review link",
+			...WRITE,
+			// Mints a fresh token every call (no idempotency plug) → a retry forks a
+			// second link with a NEW token.
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: {
+				video_result_id?: number;
+				slider_id?: number;
+				campaign_pack_id?: number;
+				expires_in_hours?: number;
+				download_enabled?: boolean;
+				version_label?: string;
+			},
+			client,
+		) => {
+			const err = validateReviewOutput(args.video_result_id, args.slider_id);
+			if (err) return fail(err);
+			const res = await client.post<{ data: unknown }>(
+				"/review-links",
+				buildReviewLinkBody(args),
+			);
+			// The reviewer page (/review/<token>) is a FRONT web-app route, not an API
+			// endpoint, so build the absolute URL on the web-app origin (HUBFLUENCER_WEB_URL,
+			// default https://app.hubfluencer.com) — NOT client.origin (the API base).
+			const result: CreateReviewLinkResult = shapeCreateReviewLink(
+				asRecord(res).data,
+				reviewWebOrigin(),
+			);
+			return ok(result);
+		},
+	),
+);
+
+registerTool(
+	"list_review_links",
+	{
+		title: "List your review links",
+		description:
+			"Lists your review links, newest first, each summarized with its status (pending → viewed → approved / " +
+			"changes_requested / revoked), the output it points at, expiry, and its visible comment_count — so you can " +
+			"see review + approval activity at a glance. NEVER returns the token (only shown once at creation). " +
+			"Read-only, 0 credits. Scope: video:read.",
+		inputSchema: {},
+		annotations: { title: "List review links", ...RO },
+	},
+	tool(async (_args, client) => {
+		const res = await client.get<{ data: unknown }>("/review-links");
+		const data = asRecord(res).data;
+		const links = Array.isArray(data) ? data.map(summarizeReviewLink) : [];
+		return ok({ review_links: links });
+	}),
+);
+
+registerTool(
+	"revoke_review_link",
+	{
+		title: "Revoke a review link",
+		description:
+			"Revokes one of your own review links (status → 'revoked'); the no-login URL immediately stops working. " +
+			"Returns the revoked link. Spends 0 credits. Scope: video:generate. 404 for an unknown/foreign id.",
+		inputSchema: {
+			id: z.number().int().describe("Review link id (from list_review_links)"),
+		},
+		annotations: {
+			title: "Revoke review link",
+			readOnlyHint: false,
+			// Disabling the public URL is a state-destroying transition on the link.
+			destructiveHint: true,
+			openWorldHint: true,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { id: number }, client) => {
+		const res = await client.del<{ data: unknown }>(`/review-links/${args.id}`);
+		return ok(summarizeReviewLink(asRecord(res).data));
+	}),
+);
+
+// ── Asset catalog: cross-project reusable media ───────────────────────────────
+//
+// The reusable user asset library (images + videos). Uploading here lets an asset
+// be reused across projects (via the app's from-asset flows). SUBSCRIPTION-GATED:
+// these routes sit behind RequireSubscription, which returns 402
+// `subscription_required` when the user has no active subscription —
+// assetCatalog() re-surfaces that as a clear "needs an active subscription".
+
+/**
+ * Wraps an asset-catalog tool so a `subscription_required` 402 (the
+ * RequireSubscription plug) is re-surfaced with a clear "subscribe first"
+ * explanation (the generic errMessage would print the bare server sentence). Any
+ * other failure flows through tool()'s normal errMessage path unchanged.
+ */
+function assetCatalog<A>(
+	fn: (
+		args: A,
+		client: HubfluencerClient,
+		extra: ToolExtra,
+	) => Promise<ReturnType<typeof ok>>,
+) {
+	return tool<A>(async (args, client, extra) => {
+		try {
+			return await fn(args, client, extra);
+		} catch (e) {
+			const he = e as HubfluencerError;
+			if (he && he.status === 402) {
+				return fail(
+					assetSubscriptionErrorText(he.status, he.code, errMessage(e)),
+				);
+			}
+			throw e;
+		}
+	});
+}
+
+registerTool(
+	"list_assets",
+	{
+		title: "List your reusable asset catalog",
+		description:
+			"Lists your reusable asset catalog (images + videos), newest first, each with its media type, mime, size, " +
+			"description, status, and a presigned asset_url — plus your storage quota. Optionally page with limit/offset " +
+			"(offset = page * limit). Read-only, 0 credits. Scope: video:read. Requires an ACTIVE SUBSCRIPTION (402 " +
+			"subscription_required otherwise).",
+		inputSchema: {
+			limit: z
+				.number()
+				.int()
+				.optional()
+				.describe("Max assets to return (a positive integer)"),
+			offset: z
+				.number()
+				.int()
+				.optional()
+				.describe("How many to skip (offset = page * limit)"),
+		},
+		annotations: { title: "List assets", ...RO },
+	},
+	assetCatalog(async (args: { limit?: number; offset?: number }, client) => {
+		const query: Record<string, number> = {};
+		if (args.limit !== undefined) query.limit = args.limit;
+		if (args.offset !== undefined) query.offset = args.offset;
+		const res = await client.get<{ data: unknown; meta?: unknown }>(
+			"/assets",
+			Object.keys(query).length > 0 ? query : undefined,
+		);
+		const data = asRecord(res).data;
+		const assets = Array.isArray(data) ? data.map(summarizeCatalogAsset) : [];
+		const quota = asRecord(asRecord(res).meta).quota;
+		return ok({
+			assets,
+			quota: quota ? summarizeAssetQuota(quota) : null,
+		});
+	}),
+);
+
+registerTool(
+	"get_asset_quota",
+	{
+		title: "Get your asset-catalog storage quota",
+		description:
+			"Returns your asset-catalog storage quota (limit / used / pending / reserved / remaining bytes). Read-only, " +
+			"0 credits. Scope: video:read. Requires an ACTIVE SUBSCRIPTION (402 subscription_required otherwise).",
+		inputSchema: {},
+		annotations: { title: "Get asset quota", ...RO },
+	},
+	assetCatalog(async (_args, client) => {
+		const res = await client.get<{ data: unknown }>("/assets/quota");
+		return ok(summarizeAssetQuota(asRecord(res).data));
+	}),
+);
+
+registerTool(
+	"upload_asset",
+	{
+		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. ` +
+			"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 " +
+			"subscription_required otherwise). The local path is confined to HUBFLUENCER_INPUT_DIR (default: cwd). " +
+			"Returns the confirmed asset id + media type + status.",
+		inputSchema: {
+			file_path: z
+				.string()
+				.describe(
+					"Path to a local image/video, inside HUBFLUENCER_INPUT_DIR (default: cwd)",
+				),
+			description: z
+				.string()
+				.optional()
+				.describe("Optional description stored with the asset"),
+			duration_seconds: z
+				.number()
+				.optional()
+				.describe("Video duration in seconds (REQUIRED for a video, ≤60)"),
+			width: z.number().int().optional().describe("Optional pixel width"),
+			height: z.number().int().optional().describe("Optional pixel height"),
+		},
+		annotations: {
+			title: "Upload asset",
+			...WRITE,
+			// Each upload presigns a fresh asset row (no idempotency plug) → a retry
+			// uploads a duplicate.
+			idempotentHint: false,
+		},
+	},
+	assetCatalog(
+		async (
+			args: {
+				file_path: string;
+				description?: string;
+				duration_seconds?: number;
+				width?: number;
+				height?: number;
+			},
+			client,
+		) => {
+			const asset = await uploadCatalogAsset(client, args.file_path, {
+				description: args.description,
+				durationSeconds: args.duration_seconds,
+				width: args.width,
+				height: args.height,
+			});
+			return ok({
+				...asset,
+				next: "list_assets to see it; reuse it across projects from the app's asset picker.",
+			});
+		},
+	),
+);
+
 // ── Boot ──────────────────────────────────────────────────────────────────────
 
 async function main() {