@mevdragon/vidfarm-devcli 0.11.0 → 0.13.0

package/dist/src/app.js

@@ -1,6 +1,8 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline as streamPipeline } from "node:stream/promises";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import { createOpenAI } from "@ai-sdk/openai";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
@@ -21,7 +23,7 @@ import { writeForkManifest } from "./services/fork-manifest.js";
 import { renderHelpPage } from "./help-page.js";
 import { renderHomepage } from "./homepage.js";
 import { COMPOSITION_RUNTIME_SCRIPT_BODY } from "./composition-runtime.js";
-import { KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER } from "./hyperframes/composition.js";
+import { CAPTION_ANIM_CSS, CAPTION_STYLE_MARKER, KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, TRANSITION_CSS, TRANSITION_STYLE_MARKER } from "./hyperframes/composition.js";
 import { normalizeCompositionZIndexHtml, sanitizeCompositionHtml } from "./services/composition-sanitize.js";
 import { applyMarkupUsd } from "./services/billing-pricing.js";
 import { primitiveRegistry } from "./primitive-registry.js";
@@ -45,10 +47,14 @@ import { ServerlessProviderKeyService } from "./services/serverless-provider-key
 import { ServerlessTemplateConfigService } from "./services/serverless-template-configs.js";
 import { parseHTML } from "linkedom";
 import { joinStorageKey, StorageService } from "./services/storage.js";
+import { buildCaptionCues, cuesFromText } from "./services/captions.js";
+import { defaultSpeechModelFor as speechModelFor, transcribeSpeechWithKey } from "./services/speech.js";
+import { insertCaptionLayers } from "./devcli/composition-edit.js";
+import { loadSpeechAudioLocally, MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES } from "./devcli/speech.js";
 import { DescribeExecutionCommand, SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
 import { clipRecords, makeUserPreset } from "./services/clip-records.js";
-import { matchScenesToClips, searchUserClips } from "./services/clip-search.js";
-import { BUILTIN_PRESETS, ClipModelClient, effectiveHuntDurationSec, estimateScanCostFromDuration, normalizeHuntSpec, parseClipHuntPrompt, resolveDurationBand } from "./services/clip-curation/index.js";
+import { matchScenesToClips, searchUserClips, vectorIndex } from "./services/clip-search.js";
+import { BUILTIN_PRESETS, buildEffectiveGuidance, ClipModelClient, detectLocalAgent, effectiveHuntDurationSec, estimateScanCostFromDuration, hasFfmpeg, LocalAgentClipClient, normalizeCropFocus, normalizeHuntSpec, parseClipHuntPrompt, probeVideo, resolveDurationBand, scanVideo } from "./services/clip-curation/index.js";
 import { analyzeCastMembers, annotateScenesFromSource, buildSmartDecomposedHtml, HyperframesService, smartDecomposeVideo, stampCompositionIdentity } from "./services/hyperframes.js";
 import { buildPendingSceneAnnotationsState } from "./services/scene-annotations.js";
 import { createPrimitiveJobContext } from "./primitive-context.js";
@@ -850,6 +856,26 @@ function consumeSettingsFlash(c) {
         return null;
     }
 }
+// Fully-local box (`vidfarm serve`): the browser is pre-authed through
+// /auto-login at boot, but a fresh browser profile / cleared cookies / a
+// directly-opened /editor URL carries no session cookie — and every editor
+// POST (Render, chat, uploads) then fails with a 401 "Unauthorized" modal
+// even though the box is a single-user localhost machine whose only customer
+// is the env-bootstrapped one. Fall back to the bootstrap key's customer,
+// the exact identity /auto-login would have granted.
+async function localBoxFallbackCustomer() {
+    const isFullyLocalBox = !config.isProduction
+        && config.RECORDS_DRIVER === "local"
+        && config.STORAGE_DRIVER === "local";
+    if (!isFullyLocalBox || !config.VIDFARM_API_KEY)
+        return null;
+    try {
+        return await auth.authenticateAsync(config.VIDFARM_API_KEY);
+    }
+    catch {
+        return null;
+    }
+}
 async function getBrowserCustomer(c, body) {
     try {
         // Agent-first auth: an explicit vidfarm-api-key header wins over browser
@@ -881,10 +907,10 @@ async function getBrowserCustomer(c, body) {
             return currentCustomer;
         }
         const customers = await listBrowserSessionCustomers(c);
-        if (customers.length !== 1) {
-            return null;
+        if (customers.length === 1) {
+            return customers[0] ?? null;
         }
-        return customers[0] ?? null;
+        return await localBoxFallbackCustomer();
     }
     catch {
         return null;
@@ -2918,10 +2944,19 @@ function isFormFile(value) {
         && "arrayBuffer" in value);
 }
 async function getVisibleApiKey(customerId) {
-    const existing = await serverlessRecords.getLatestApiKeyForCustomer(customerId);
-    const rawValue = existing?.raw_value ? String(existing.raw_value) : null;
-    if (rawValue) {
-        return rawValue;
+    // Prefer the newest key THIS server can validate, not just the newest key.
+    // After an API_KEY_SALT rotation the shared table holds keys hashed under
+    // different salts (deployed stage vs local dev boxes share the staging
+    // table); embedding a key the current server rejects breaks editor chat and
+    // its tool calls with "Invalid API credentials." on every message.
+    const existingKeys = await serverlessRecords.listActiveApiKeysForCustomer(customerId);
+    for (const row of existingKeys) {
+        const rawValue = row?.raw_value ? String(row.raw_value) : null;
+        if (!rawValue)
+            continue;
+        if (String(row.key_hash ?? "") === hashSecret(rawValue + config.API_KEY_SALT)) {
+            return rawValue;
+        }
     }
     const apiKey = `vf_${createId("key")}`;
     await serverlessRecords.insertApiKey({
@@ -3031,6 +3066,13 @@ function asRecord(value) {
 function readNonEmptyString(value) {
     return typeof value === "string" && value.trim() ? value.trim() : null;
 }
+// "raw" = the user's own new project (prompt-generated, own raw clips) — the
+// editor must not auto-prompt the Decompose modal for these. Anything else
+// (absent, unknown) reads as "inspiration", matching records that predate the
+// field.
+function readProjectOrigin(value) {
+    return value === "raw" ? "raw" : "inspiration";
+}
 function readFiniteNumber(value, fallback = 0) {
     const number = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
     return Number.isFinite(number) ? number : fallback;
@@ -3089,8 +3131,9 @@ function buildPrimitiveEditorDocsRoutes() {
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/probe`, summary: "Primitive audio probe job. Body must be { tracer, payload: { source_audio_url }, webhook_url? }. Returns durable JSON metadata." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/concat`, summary: "Primitive audio concat job. Body must be { tracer, payload: { source_audio_urls, output_format?, audio_bitrate_kbps? }, webhook_url? }." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/normalize`, summary: "Primitive audio normalization job. Body must be { tracer, payload: { source_audio_url, output_format?, audio_bitrate_kbps?, sample_rate_hz? }, webhook_url? }." },
-        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/speech`, summary: "Primitive text-to-speech (TTS) job using saved OpenAI, Gemini, or OpenRouter provider keys. Body must be { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? }, webhook_url? }. instructions is a free-form voice-style prompt (tone, pacing, accent, emotion, persona — e.g. \"calm, warm bedtime narrator with a slight British accent\"). Returns a durable platform audio URL (mp3 or wav). Alias: POST /api/v1/primitives/tts." },
-        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/transcribe`, summary: "Primitive speech-to-text (STT) job using saved provider keys. Accepts VIDEO or AUDIO sources; video audio is demuxed automatically. Body must be { tracer, payload: { source_url (aliases: source_video_url, source_audio_url, url), diarize?, language?, prompt?, provider?, model? }, webhook_url? }. Returns TWO formats in one job: a simple subtitle transcript (plain text + timed SRT cues, no speakers) and an advanced multi-speaker version (speaker-attributed timed segments for multi-narration), plus transcript.json/.srt/.txt artifacts. diarize defaults to true; speaker attribution needs a Gemini key (openai/openrouter degrade to a plain single-speaker transcript). Sources over ~40 minutes of speech must be trimmed first. Alias: POST /api/v1/primitives/stt." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/speech`, summary: "Primitive text-to-speech (TTS) job using saved OpenAI, Gemini, or OpenRouter provider keys. Body must be { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? }, webhook_url? }. instructions is a free-form voice-style prompt (tone, pacing, accent, emotion, persona — e.g. \"calm, warm bedtime narrator with a slight British accent\"). voice is a provider preset (OpenAI: alloy/ash/coral/…; Gemini: Kore/Puck/Charon/…); provider is inferred from the voice when omitted, and a voice paired with the wrong provider is rejected with a 400. Returns a durable platform audio URL (mp3 or wav). Alias: POST /api/v1/primitives/tts." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/transcribe`, summary: "Primitive speech-to-text (STT) job using saved provider keys. Accepts VIDEO or AUDIO sources; video audio is demuxed automatically. Body must be { tracer, payload: { source_url (aliases: source_video_url, source_audio_url, url), diarize?, language?, prompt?, provider?, model? }, webhook_url? }. Returns TWO formats in one job: a simple subtitle transcript (plain text + timed SRT cues, no speakers) and an advanced multi-speaker version (speaker-attributed timed segments for multi-narration), plus transcript.json/.srt/.txt artifacts. diarize defaults to true; speaker attribution needs a Gemini key (openai/openrouter degrade to a plain single-speaker transcript). Sources over ~40 minutes of speech must be trimmed first. Alias: POST /api/v1/primitives/stt. Pass word_timestamps: true for word-level timings on each segment (real timestamps on an OpenAI key via whisper-1; other providers stay segment-level)." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/captions`, summary: "ANIMATED CAPTIONS from speech: one job transcribes narration WITH word-level timings and pages it into word-by-word caption cues ready for the editor's set_captions action. Body must be { tracer, payload: { source_url (video or audio; video audio is demuxed) OR text (page a script instead of transcribing), style? (spotlight|karaoke|word-pop|stack-up|neon|bounce), animation?, active_color?, highlight_color?, uppercase?, color?, background?, background_style?, font_family?, font_size?, max_words_per_cue?, offset_sec?, language?, provider?, window_start?/window_duration? (text mode) }, webhook_url? }. The finished job's result carries captions (the cue array) and set_captions_action (fully-formed editor_action arguments — apply verbatim). Real word timestamps need an OpenAI key (whisper-1, tried first); gemini/openrouter fall back to estimated word windows. Alias: POST /api/v1/primitives/captions." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/brainstorm/coldstart`, summary: "Primitive cold-start strategy questionnaire. Body should usually be { tracer, payload: { user_message }, webhook_url? }. user_message can be rough, like \"I don't know where to start\" or a messy description. count is optional only when the user explicitly wants more or fewer questions. offer_description remains accepted as a backward-compatible alias." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/brainstorm/awareness_stages`, summary: "Primitive awareness-stage recommendation. Body must be { tracer, payload: { offer_description }, webhook_url? }. Use this when the customer is unsure what type of ads to produce." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/brainstorm/angles`, summary: "Primitive ad-angle brainstorm. Body must be { tracer, payload: { offer_description, problem_awareness, solution_awareness }, webhook_url? }. Allowed values: problem_awareness is problem_unaware|problem_aware, solution_awareness is solution_unaware|solution_aware. count is optional only when the user explicitly wants more or fewer angles. Returns diverse persuasive TikTok angles with explanations." },
@@ -3684,7 +3727,7 @@ function normalizeOperationRequestTracer(tracer) {
 }
 function createTemplateHttpTool(input) {
     return tool({
-        description: "Call exactly one Vidfarm REST API route and inspect the response before deciding the next call. Use template routes for metadata, skill, config, operations, jobs, logs, and cancel routes. Use primitive routes under /api/v1/primitives for reusable image generation, image editing, inpainting, still rendering, social/media video download, AI video generation, video slide rendering, burned-in caption removal, video trim/extract/probe/mute/concat operations, audio trim/probe/concat/normalize operations, text-to-speech narration (audio/speech) and speech-to-text transcription (audio/transcribe) routes, brainstorm strategy routes, and primitive job inspection; these primitive routes are allowed directly from editor chat even when they are not specific to the current template. Primitive POST bodies must use { tracer, payload: { ...primitive fields... }, webhook_url? }; do not put prompt, source_image_url, instruction, slides, html, or other primitive fields at the top level. Never say primitive image generation, image edit, inpaint, HTML render, video download, AI video generation, caption removal, trim, probe, extract-audio, concat, mute, video render, text-to-speech, speech transcription, or brainstorm routes are unavailable here when the route exists. If the user asks to generate a new image similar to an attachment, call POST /api/v1/primitives/images/generate with body { tracer, payload: { prompt, prompt_attachments: [exact attachment URL] } }. If the user asks to revise the attached image itself, call POST /api/v1/primitives/images/edit with body { tracer, payload: { source_image_url, instruction } }. If the user asks to download a social/media post into a durable MP4, call POST /api/v1/primitives/videos/download with body { tracer, payload: { source_url|video_url|url, quality?: \"best\"|\"hd\"|\"full_hd\" } }. If the user asks to generate a new AI video, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, provider?: \"openai\"|\"gemini\"|\"openrouter\", duration?: seconds, input_references?: [direct image asset URL], frame_images?: [{ image_url, frame_type }] } }; never send webpage or social post URLs in input_references. duration is seconds, not milliseconds, and duration_ms belongs only to /videos/render-slides slides. Default video models are openai/sora-2, gemini/veo-3.0-generate-001, and openrouter/bytedance/seedance-2.0. Use POST /api/v1/primitives/videos/render-slides only to assemble existing media URLs into an MP4 slideshow. Use POST /api/v1/primitives/media/dedupe to apply subtle dedupe transforms (zoom/tilt/rotate/saturation/speed/horizontal_flip/contrast/brightness/hue_rotate/blur/tint) to any image or video URL, with body { tracer, payload: { source_media_url, media_type?, effects?, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Use POST /api/v1/primitives/videos/trim for clipping, /videos/extract-audio for demuxing, /videos/probe or /audio/probe for metadata-only JSON outputs, /videos/extract-frame for stills, /videos/mute to remove audio, /videos/replace-audio to swap tracks, /videos/concat for sequential muted MP4 joins, /audio/trim for clipped audio, /audio/concat for stitched audio, and /audio/normalize for leveled/re-encoded audio. If the user asks for AI voiceover, narration, or dub audio from text (a script, hook, or caption read aloud), call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions? } } — instructions is a free-form voice-style prompt like \"excited sports announcer, fast paced\" and the job returns a durable audio URL you can place with add_layer. If the user asks to transcribe a video or audio, get subtitles/captions from speech, or identify who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language? } } — it accepts video or audio URLs (video audio is demuxed automatically) and one job returns BOTH a simple subtitle transcript (plain text + timed SRT cues) and an advanced multi-speaker version (speaker-attributed timed segments for multi-narration); speaker attribution needs a Gemini key. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. Caption removal is capped at ~15 minutes of source and must NEVER be used on long-form video: when the user wants short clips out of a long video (a podcast, stream VOD, webinar, or any YouTube/TikTok/IG/X URL), call POST /clips/scan instead with body { source_url | temp_file_id | s3_key, prompt, ranges?: [\"MM:SS-MM:SS\"], target_duration_sec?, aspect?: \"9:16\"|\"16:9\"|\"4:3\"|\"1:1\", avoid_text?, tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver on long videos), aspect crops every clip, and avoid_text prefers scenes WITHOUT on-screen text via scene SELECTION (never caption removal on the source). The hunt is async: it returns scan_id immediately; poll GET /clips/scan/:scanId, then browse results via GET /clips/feed?source=<source_video_id> or POST /clips/search. Hunts bill AWS compute only — the AI tagging runs on the user's own saved provider keys. To remove captions from a finished HUNTED clip, pass that clip's short mp4 to /videos/remove-captions afterwards. If the user explicitly asks for hooks, angles, awareness-stage advice, or a cold-start strategy questionnaire, call the matching brainstorm route immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart when the customer is starting from zero, /brainstorm/awareness_stages when they do not know what ad types to make, /brainstorm/angles when they want persuasive angles, and /brainstorm/hooks when they want many openings. Product placement is a first-class brainstorm primitive like angles and hooks: when the user wants to identify product-placement opportunities in a video or repurpose a video into a native ad for their product, call POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? } — it watches the video and returns timestamped native placement opportunities and prefers a Gemini key. You may also analyze an attached video directly to answer product-placement questions conversationally instead of the primitive when the user just wants a quick take. For brainstorm routes, do not send count by default; only include count when the user explicitly asks for a specific number of hooks, angles, questions, or opportunities. When brainstorm jobs finish and the response includes a JSON artifact, tell the user to open and review that JSON in the chat UI because it contains the structured output. When the user asks for content ideas or says they do not know where to start, prefer the sequence coldstart -> awareness_stages -> angles -> hooks, then use the output to choose templates. For template operation POST bodies, use top-level template_preview_media=\"auto\" by default, \"include\" when the user wants the template to use catalog preview media as references where supported, and \"exclude\" when the user asks not to use preview media as references. Templates decide which generation steps honor that policy. If a POST returns a queued job, do not poll it in this same response; continue with any remaining requested POST calls, then summarize the queued job ids and tracers. If you know a job_id but not the template or primitive, use GET /api/v1/user/me/jobs/:jobId or its /logs and /artifacts subroutes instead of paging through job lists. Use GET /api/v1/compositions/:forkId/remove-video-captions to look up both the original source video URL and the subtitle-removed mirrored URL for the current fork before feeding a video URL into a primitive route; this is a read-only, non-billing status check — never confuse it with POST /remove-video-captions-poll (which advances the fork's decompose-time subtitle-removal job and can bill). Use POST /api/v1/approved/posts with title, caption, pinned_comment, media URLs, and tracer to approve a finished output into a preview/share page. Use POST /api/v1/approved/posts/:postId/schedules with destination_type, destination_id, scheduled_at, timezone, and optional settings/additional_notes to schedule an approved post. When a rendered video was built from slideshow frame images, include both versions in one media array: final MP4 first with kind=\"video\" and role=\"primary\", then every finished captioned slide frame image in order with kind=\"image\" and role=\"slide\". Prefer create-slideshow result.renderVideoInput.slides[].imageUrl or result.slides[].frameImageUrl for carousel media; do not use backgroundImageUrl, manifests, thumbnails, or a partial files array as the full slide set. If the user supplies exact media file URLs for approval, use those URLs as the backup source of truth, preserve their order, infer kind when needed, and assign primary/video and slide/image roles correctly. If the user asks for N distinct generated outputs, make N sequential POST calls rather than one combined POST and do not stop after the first queued job.",
+        description: "Call exactly one Vidfarm REST API route and inspect the response before deciding the next call. Use template routes for metadata, skill, config, operations, jobs, logs, and cancel routes. Use primitive routes under /api/v1/primitives for reusable image generation, image editing, inpainting, still rendering, social/media video download, AI video generation, video slide rendering, burned-in caption removal, video trim/extract/probe/mute/concat operations, audio trim/probe/concat/normalize operations, text-to-speech narration (audio/speech) and speech-to-text transcription (audio/transcribe) routes, brainstorm strategy routes, and primitive job inspection; these primitive routes are allowed directly from editor chat even when they are not specific to the current template. Primitive POST bodies must use { tracer, payload: { ...primitive fields... }, webhook_url? }; do not put prompt, source_image_url, instruction, slides, html, or other primitive fields at the top level. Never say primitive image generation, image edit, inpaint, HTML render, video download, AI video generation, caption removal, trim, probe, extract-audio, concat, mute, video render, text-to-speech, speech transcription, or brainstorm routes are unavailable here when the route exists. If the user asks to generate a new image similar to an attachment, call POST /api/v1/primitives/images/generate with body { tracer, payload: { prompt, prompt_attachments: [exact attachment URL] } }. If the user asks to revise the attached image itself, call POST /api/v1/primitives/images/edit with body { tracer, payload: { source_image_url, instruction } }. If the user asks to download a social/media post into a durable MP4, call POST /api/v1/primitives/videos/download with body { tracer, payload: { source_url|video_url|url, quality?: \"best\"|\"hd\"|\"full_hd\" } }. If the user asks to generate a new AI video, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, provider?: \"openai\"|\"gemini\"|\"openrouter\", duration?: seconds, input_references?: [direct image asset URL], frame_images?: [{ image_url, frame_type }] } }; never send webpage or social post URLs in input_references. duration is seconds, not milliseconds, and duration_ms belongs only to /videos/render-slides slides. Default video models are openai/sora-2, gemini/veo-3.0-generate-001, and openrouter/bytedance/seedance-2.0. Use POST /api/v1/primitives/videos/render-slides only to assemble existing media URLs into an MP4 slideshow. Use POST /api/v1/primitives/media/dedupe to apply subtle dedupe transforms (zoom/tilt/rotate/saturation/speed/horizontal_flip/contrast/brightness/hue_rotate/blur/tint) to any image or video URL, with body { tracer, payload: { source_media_url, media_type?, effects?, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Use POST /api/v1/primitives/videos/trim for clipping, /videos/extract-audio for demuxing, /videos/probe or /audio/probe for metadata-only JSON outputs, /videos/extract-frame for stills, /videos/mute to remove audio, /videos/replace-audio to swap tracks, /videos/concat for sequential muted MP4 joins, /audio/trim for clipped audio, /audio/concat for stitched audio, and /audio/normalize for leveled/re-encoded audio. If the user asks for AI voiceover, narration, or dub audio from text (a script, hook, or caption read aloud), call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions? } } — instructions is a free-form voice-style prompt like \"excited sports announcer, fast paced\" and the job returns a durable audio URL you can place with add_layer. If the user asks to transcribe a video or audio, get subtitles/captions from speech, or identify who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language? } } — it accepts video or audio URLs (video audio is demuxed automatically) and one job returns BOTH a simple subtitle transcript (plain text + timed SRT cues) and an advanced multi-speaker version (speaker-attributed timed segments for multi-narration); speaker attribution needs a Gemini key, and word_timestamps: true adds word-level timings per segment (real on an OpenAI key via whisper-1). If the user wants ANIMATED word-by-word captions generated from narration, call POST /api/v1/primitives/audio/captions with body { tracer, payload: { source_url (narration audio or video URL) OR text (a script to page), style?: \"spotlight\"|\"karaoke\"|\"word-pop\"|\"stack-up\"|\"neon\"|\"bounce\", max_words_per_cue?, offset_sec?, language?, provider? } } — the finished job's result carries captions (the cue array) and set_captions_action (fully-formed editor_action arguments); apply them with the editor_action tool (action_type=set_captions) so the change flows through the editor state. Real word timestamps need an OpenAI key (whisper-1, tried first); gemini/openrouter estimate word windows. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. Caption removal is capped at ~15 minutes of source and must NEVER be used on long-form video: when the user wants short clips out of a long video (a podcast, stream VOD, webinar, or any YouTube/TikTok/IG/X URL), call POST /clips/scan instead with body { source_url | temp_file_id | s3_key, prompt, ranges?: [\"MM:SS-MM:SS\"], target_duration_sec?, aspect?: \"9:16\"|\"16:9\"|\"4:3\"|\"1:1\", avoid_text?, provider?: \"gemini\"|\"openai\"|\"openrouter\", tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver on long videos), aspect crops every clip, and avoid_text prefers scenes WITHOUT on-screen text via scene SELECTION (never caption removal on the source). The hunt is async: it returns scan_id immediately; poll GET /clips/scan/:scanId, then browse results via GET /clips/feed?source=<source_video_id> or POST /clips/search. Hunts bill AWS compute only — the AI tagging runs on the user's own saved provider keys (auto-picked gemini → openai → openrouter unless body.provider names one). To remove captions from a finished HUNTED clip, pass that clip's short mp4 to /videos/remove-captions afterwards. If the user explicitly asks for hooks, angles, awareness-stage advice, or a cold-start strategy questionnaire, call the matching brainstorm route immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart when the customer is starting from zero, /brainstorm/awareness_stages when they do not know what ad types to make, /brainstorm/angles when they want persuasive angles, and /brainstorm/hooks when they want many openings. Product placement is a first-class brainstorm primitive like angles and hooks: when the user wants to identify product-placement opportunities in a video or repurpose a video into a native ad for their product, call POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? } — it watches the video and returns timestamped native placement opportunities and prefers a Gemini key. You may also analyze an attached video directly to answer product-placement questions conversationally instead of the primitive when the user just wants a quick take. For brainstorm routes, do not send count by default; only include count when the user explicitly asks for a specific number of hooks, angles, questions, or opportunities. When brainstorm jobs finish and the response includes a JSON artifact, tell the user to open and review that JSON in the chat UI because it contains the structured output. When the user asks for content ideas or says they do not know where to start, prefer the sequence coldstart -> awareness_stages -> angles -> hooks, then use the output to choose templates. For template operation POST bodies, use top-level template_preview_media=\"auto\" by default, \"include\" when the user wants the template to use catalog preview media as references where supported, and \"exclude\" when the user asks not to use preview media as references. Templates decide which generation steps honor that policy. If a POST returns a queued job, do not poll it in this same response; continue with any remaining requested POST calls, then summarize the queued job ids and tracers. If you know a job_id but not the template or primitive, use GET /api/v1/user/me/jobs/:jobId or its /logs and /artifacts subroutes instead of paging through job lists. Use GET /api/v1/compositions/:forkId/remove-video-captions to look up both the original source video URL and the subtitle-removed mirrored URL for the current fork before feeding a video URL into a primitive route; this is a read-only, non-billing status check — never confuse it with POST /remove-video-captions-poll (which advances the fork's decompose-time subtitle-removal job and can bill). Use POST /api/v1/approved/posts with title, caption, pinned_comment, media URLs, and tracer to approve a finished output into a preview/share page. Use POST /api/v1/approved/posts/:postId/schedules with destination_type, destination_id, scheduled_at, timezone, and optional settings/additional_notes to schedule an approved post. When a rendered video was built from slideshow frame images, include both versions in one media array: final MP4 first with kind=\"video\" and role=\"primary\", then every finished captioned slide frame image in order with kind=\"image\" and role=\"slide\". Prefer create-slideshow result.renderVideoInput.slides[].imageUrl or result.slides[].frameImageUrl for carousel media; do not use backgroundImageUrl, manifests, thumbnails, or a partial files array as the full slide set. If the user supplies exact media file URLs for approval, use those URLs as the backup source of truth, preserve their order, infer kind when needed, and assign primary/video and slide/image roles correctly. If the user asks for N distinct generated outputs, make N sequential POST calls rather than one combined POST and do not stop after the first queued job.",
         inputSchema: z.object({
             method: z.enum(["GET", "POST"]).describe("HTTP method to use."),
             path: z.string().min(1).describe("Absolute path or same-origin URL for an allowed Vidfarm REST route."),
@@ -4187,8 +4230,9 @@ function createEditorActionTool() {
                 "ungroup_layers",
                 "replace_composition_html",
                 "export_composition",
-                "generate_layer"
-            ]).describe("Which mutation to perform. Use generate_layer to AI-generate a video/image and auto-place it on the timeline (fill a gap or replace a scene). Use export_composition to trigger the same Export button available in the editor UI — this queues an AWS Lambda render and the finished MP4 URL will surface in the next editor_context as last_export_url."),
+                "generate_layer",
+                "set_captions"
+            ]).describe("Which mutation to perform. Use generate_layer to AI-generate a video/image and auto-place it on the timeline (fill a gap or replace a scene). Use export_composition to trigger the same Export button available in the editor UI — this queues an AWS Lambda render and the finished MP4 URL will surface in the next editor_context as last_export_url. Use set_captions to lay down a full run of ANIMATED word-by-word captions (TikTok/CapCut style): pass captions[] cues (or text + start/duration to auto-page), plus caption_style; it replaces any existing animated caption layers. To restyle existing captions without changing text/timing, use set_layer_style with caption_* fields on each caption layer."),
             layer_key: z.string().optional().describe("Existing layer key from editor_context (required for remove/set/duplicate/split). MAY be either the element_id (data-hf-id) or the slug (data-hf-slug). For add_layer, optionally provide a stable id (starts with a letter, [A-Za-z0-9_-], <=64 chars) to reuse in later tool calls this turn."),
             slug: z.string().optional().describe("snake_case slug for the layer. On add_layer, seeds data-hf-slug. On set_layer_identity, sets it. Slugs give viral DNA a stable handle for the element."),
             note: z.string().optional().describe("Human-facing note explaining the layer's role, referenced by viral DNA. On add_layer seeds data-hf-note. On set_layer_identity, sets it. Empty string removes."),
@@ -4221,6 +4265,23 @@ function createEditorActionTool() {
             object_position: z.string().optional().describe("CSS object-position for image/video (e.g., center, top, bottom left)."),
             ken_burns: z.enum(["zoom-in", "zoom-out", "pan-left", "pan-right", "pan-up", "pan-down", "zoom-in-left", "zoom-in-right", "none"]).optional().describe("Ken Burns motion for still-image layers: a slow pan/zoom spanning the clip's full duration. Apply with set_layer_media on an existing image, or seed it on add_layer/generate_layer when kind/media_type is image. 'none' removes the effect. When the user says 'animate the images' / 'ken burns', apply it to every still image, varying presets across adjacent clips (zoom-in, pan-left, zoom-out, ...) for a documentary feel."),
             ken_burns_intensity: z.number().optional().describe("Ken Burns strength: extra zoom / pan travel as a fraction of the frame, 0.04-0.5 (default 0.18; ~0.1 subtle, ~0.3 dramatic). Only meaningful alongside ken_burns."),
+            transition: z.enum(["crossfade", "fade-black", "slide-left", "slide-right", "slide-up", "slide-down", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-open", "none"]).optional().describe("Scene transition INTO this clip at its start, from the previous clip on the same track. Set it on the INCOMING clip (the one after the cut) with set_layer_media, or seed it on add_layer/generate_layer. Works on video and image scene clips; 'none' removes it. The previous butt-cut clip is automatically held on screen beneath the incoming one for the transition window — do not retime anything yourself. When the user asks for 'transitions between scenes' / 'smooth cuts', apply one to EVERY scene clip except the first, varying or matching presets to the template's energy (crossfade/fade-black = calm, slide/wipe = energetic, zoom/circle-open = punchy)."),
+            transition_duration: z.number().optional().describe("Transition length in seconds, 0.1-2.5 (default 0.5; ~0.3 snappy, ~1.0 slow cinematic). Only meaningful alongside transition."),
+            caption_style: z.enum(["spotlight", "karaoke", "word-pop", "stack-up", "neon", "bounce"]).optional().describe("Animated caption preset look: spotlight (active word gets a highlight pill, bold outline text), karaoke (words fill with color as spoken), word-pop (one word at a time, punchy scale-in), stack-up (words fade/rise in and stay), neon (active word glow pulse), bounce (active word bounces). Applies animation + colors + background treatment in one go; individual caption_*/color/background/background_style fields override specifics."),
+            caption_animation: z.enum(["highlight-pop", "karaoke-fill", "word-pop", "cumulative-reveal", "glow-pulse", "bounce-wave", "none"]).optional().describe("Word-by-word caption animation, if you want to set it directly instead of via caption_style. Works on set_captions, add_layer (kind=text), and set_layer_style. 'none' removes the animation and flattens the layer back to static text."),
+            caption_active_color: z.string().optional().describe("CSS color the active word takes while it is spoken (karaoke fill color, highlight text color, glow color)."),
+            caption_highlight_color: z.string().optional().describe("CSS color of the rounded pill behind the active word (highlight-pop animation only)."),
+            caption_uppercase: z.boolean().optional().describe("Render caption words in uppercase."),
+            captions: z.array(z.object({
+                text: z.string().describe("Cue text — one page of ~3-5 words shown together."),
+                start: z.number().describe("Cue start in seconds on the composition timeline."),
+                duration: z.number().describe("Cue length in seconds (cues must not overlap)."),
+                words: z.array(z.object({
+                    text: z.string(),
+                    start: z.number().describe("Word start in seconds RELATIVE to the cue start."),
+                    end: z.number().describe("Word end in seconds RELATIVE to the cue start.")
+                })).optional().describe("Word-level timings relative to the cue start (e.g. from a transcript). Omit to auto-estimate across the cue.")
+            })).optional().describe("set_captions: the full animated-caption cue list, one caption layer per cue on a shared free track. Replaces ALL existing animated caption layers. Derive cue timing from the video's transcript/segments when available. Alternatively omit this and pass text (+ start/duration window) to auto-page plain text."),
             volume: z.number().optional().describe("Volume 0..1 for audio/video."),
             muted: z.boolean().optional().describe("Toggle mute on audio/video."),
             group_label: z.string().optional().describe("Optional label for group_layers."),
@@ -4615,6 +4676,34 @@ function rewriteHyperframesDraftCompositionHtml(html, draftPath) {
             rewritten = `${rewritten}\n${kenBurnsTag}`;
         }
     }
+    // Same deal for the animated-caption keyframes: applying a caption style in
+    // the editor must animate immediately on older stored compositions.
+    if (!rewritten.includes(CAPTION_STYLE_MARKER)) {
+        const captionTag = `<style data-vf-captions="true">${CAPTION_ANIM_CSS}</style>`;
+        if (/<\/head>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/head>/i, `${captionTag}\n</head>`);
+        }
+        else if (/<\/body>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/body>/i, `${captionTag}\n</body>`);
+        }
+        else {
+            rewritten = `${rewritten}\n${captionTag}`;
+        }
+    }
+    // And the scene-transition keyframes: toggling data-transition on a clip
+    // must animate immediately on older stored compositions.
+    if (!rewritten.includes(TRANSITION_STYLE_MARKER)) {
+        const transitionTag = `<style data-vf-transitions="true">${TRANSITION_CSS}</style>`;
+        if (/<\/head>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/head>/i, `${transitionTag}\n</head>`);
+        }
+        else if (/<\/body>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/body>/i, `${transitionTag}\n</body>`);
+        }
+        else {
+            rewritten = `${rewritten}\n${transitionTag}`;
+        }
+    }
     return rewritten;
 }
 async function renderHyperframesStudioEditorPage(input) {
@@ -4818,7 +4907,8 @@ app.get("/editor/:templateId/composition", async (c) => {
         compositionId: templateId,
         sourceUrl: template.videoUrl,
         durationSeconds: template.durationSeconds ?? 12,
-        title: template.title || `Template · ${template.sourceHost}`
+        title: template.title || `Template · ${template.sourceHost}`,
+        origin: template.origin
     }));
 });
 app.get("/help", async (c) => renderApprovedHelpPage(c));
@@ -4930,6 +5020,7 @@ function buildTemplateHomepageEntry(template) {
         keywords: template.keywords ?? null,
         summary: template.searchSummary ?? null,
         visibility: template.visibility,
+        origin: template.origin ?? "inspiration",
         notes: template.notes,
         status: "ready"
     };
@@ -5082,6 +5173,7 @@ app.post("/discover/templates", async (c) => {
         const explicitTitle = readNonEmptyString(body.title) ?? null;
         const tagline = readNonEmptyString(body.tagline) ?? readNonEmptyString(body.trend_tagline) ?? null;
         const notes = readNonEmptyString(body.notes) ?? null;
+        const origin = readProjectOrigin(body.origin);
         const uploadFileName = readNonEmptyString(uploadRef?.file_name) ?? null;
         const primitive = primitiveRegistry.get("primitive:video_ingest");
         if (!primitive)
@@ -5137,6 +5229,7 @@ app.post("/discover/templates", async (c) => {
             downloadJobId: job.id,
             trendTagline: tagline,
             visibility: "private",
+            origin,
             notes
         });
         // Pending-card label while the ingest runs: explicit title, else the file
@@ -5294,6 +5387,7 @@ function buildPendingInspirationHomepageEntry(inspiration) {
         sourceType: inspiration.sourceHost || "social",
         durationSeconds: inspiration.durationSeconds ?? null,
         visibility: "private",
+        origin: inspiration.origin ?? "inspiration",
         notes: inspiration.notes,
         status: inspiration.status === "failed" ? "failed" : "processing"
     };
@@ -5655,7 +5749,8 @@ app.get("/composition/current.html", async (c) => {
             compositionId,
             sourceUrl: template.videoUrl,
             durationSeconds: template.durationSeconds ?? 12,
-            title: template.title || `Template · ${template.sourceHost}`
+            title: template.title || `Template · ${template.sourceHost}`,
+            origin: template.origin
         });
         const rewritten = rewriteHyperframesDraftCompositionHtml(rawHtml, `templates/${encodeURIComponent(template.id)}`);
         return c.html(rewritten, 200, { "cache-control": "no-store" });
@@ -6166,7 +6261,8 @@ app.post(COMPOSITIONS_PREFIX, async (c) => {
             compositionId: fork.id,
             sourceUrl: template.videoUrl,
             durationSeconds: template.durationSeconds ?? 12,
-            title
+            title,
+            origin: template.origin
         });
         await storage.putText(storage.compositionForkWorkingKey(fork.id, "composition.html"), rawHtml, "text/html; charset=utf-8");
     }
@@ -6305,6 +6401,144 @@ app.put(`${COMPOSITIONS_PREFIX}/:forkId/composition.html`, async (c) => {
         return forkAccessErrorResponse(c, error);
     }
 });
+// ONE-STEP animated captions: transcribe the fork's own narration (word-level
+// timings when an OpenAI key is saved) and write the animated caption cue
+// layers straight into the working composition.html. Runs on the caller's raw
+// provider keys (BYOK — never billed), synchronous (~5-20s of STT). The write
+// goes through the same sanitize+persist path as the editor's PUT, and is
+// deliberately NOT watch-suppressed so a local `vidfarm serve` live-morphs the
+// captions into open editor tabs. When an editor tab is open against the
+// CLOUD host, prefer the two-part flow instead (POST /api/v1/primitives/
+// audio/captions → editor_action set_captions) so the mutation flows through
+// the editor's own state and cannot be clobbered by its next auto-save.
+app.post(`${COMPOSITIONS_PREFIX}/:forkId/captions`, async (c) => {
+    const customer = await getBrowserCustomer(c);
+    if (!customer)
+        return c.json({ ok: false, error: "Unauthorized" }, 401);
+    try {
+        const access = await assertForkAccess({ forkId: c.req.param("forkId"), customerId: customer.id, shareToken: readShareToken(c) }, "edit");
+        const fork = access.fork;
+        const html = await storage.readText(storage.compositionForkWorkingKey(fork.id, "composition.html"));
+        if (!html)
+            return c.json({ ok: false, error: "Composition missing" }, 404);
+        const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
+        const str = (key) => (typeof body[key] === "string" && body[key].trim() ? body[key].trim() : undefined);
+        const num = (key) => (typeof body[key] === "number" && Number.isFinite(body[key]) ? body[key] : undefined);
+        const parsed = parseHTML(html);
+        const root = parsed.document.querySelector("[data-composition-id]");
+        const compositionDuration = Number(root?.getAttribute("data-duration")) || 0;
+        const maxWords = Math.max(1, Math.min(8, Math.round(num("max_words_per_cue") ?? 4)));
+        const offsetSec = Math.max(0, num("offset_sec") ?? 0);
+        let cues;
+        let wordTimestampSource = "estimated";
+        let sourceNote;
+        const text = str("text");
+        if (text) {
+            const windowStart = Math.max(0, num("start") ?? 0);
+            const windowDuration = num("duration") ?? Math.max(0.4, compositionDuration - windowStart);
+            cues = cuesFromText(text, windowStart + offsetSec, windowDuration, { maxWordsPerCue: maxWords });
+            sourceNote = "text";
+        }
+        else {
+            // Narration source: explicit override → audio layer → backing playback
+            // video → source video attr → any video layer.
+            const timedNodes = Array.from(parsed.document.querySelectorAll("[data-start]"));
+            const audioLayer = timedNodes.find((node) => node.getAttribute("data-layer-kind") === "audio" && (node.getAttribute("src") || "").trim());
+            const videoLayer = timedNodes.find((node) => node.getAttribute("data-layer-kind") === "video" && (node.getAttribute("src") || "").trim());
+            const backing = parsed.document.querySelector("[data-vf-playback-source]");
+            const sourceUrl = str("audio_url") ?? str("source_url")
+                ?? audioLayer?.getAttribute("src")?.trim()
+                ?? backing?.getAttribute("src")?.trim()
+                ?? backing?.getAttribute("data-src")?.trim()
+                ?? root?.getAttribute("data-source-video")?.trim()
+                ?? videoLayer?.getAttribute("src")?.trim();
+            if (!sourceUrl || !/^https?:\/\//i.test(sourceUrl)) {
+                return c.json({
+                    ok: false,
+                    error: "No narration to transcribe — the composition has no audio/video layer with a usable URL. Pass audio_url (or text to page a script)."
+                }, 400);
+            }
+            const keys = await loadCustomerVisionKeys(customer.id);
+            const requested = str("provider");
+            // openai first: whisper-1 is the only STT with real word-level timestamps.
+            const provider = ["openai", "gemini", "openrouter"].find((name) => requested ? name === requested && keys[name] : Boolean(keys[name]));
+            if (!provider) {
+                return c.json({
+                    ok: false,
+                    error: requested
+                        ? `No active ${requested} provider key is saved for this account.`
+                        : "Captions need an AI provider key for transcription. Add an OpenAI (best: real word timings), Gemini, or OpenRouter key in Settings."
+                }, 400);
+            }
+            const audio = await loadSpeechAudioLocally(sourceUrl);
+            if (audio.bytes.byteLength > MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES) {
+                return c.json({ ok: false, error: "Narration audio exceeds the ~40-minute transcription limit. Trim it or pass a shorter audio_url." }, 400);
+            }
+            const transcription = await transcribeSpeechWithKey({
+                provider,
+                model: str("model") ?? speechModelFor("stt", provider) ?? "",
+                audio: audio.bytes,
+                contentType: audio.contentType,
+                language: str("language"),
+                diarize: false,
+                wordTimestamps: true,
+                apiKey: keys[provider]
+            });
+            if (!transcription.segments.length) {
+                return c.json({ ok: false, error: "Transcription returned no speech segments — the narration may be silent." }, 502);
+            }
+            wordTimestampSource = transcription.segments.some((segment) => segment.words?.length) ? "provider" : "estimated";
+            cues = buildCaptionCues(transcription.segments, {
+                maxWordsPerCue: maxWords,
+                offsetSec,
+                fallbackDurationSec: compositionDuration || undefined
+            });
+            sourceNote = sourceUrl;
+        }
+        if (compositionDuration > 0) {
+            cues = cues
+                .filter((cue) => cue.start < compositionDuration)
+                .map((cue) => ({ ...cue, duration: Math.min(cue.duration, Math.max(0.1, compositionDuration - cue.start)) }));
+        }
+        if (!cues.length) {
+            return c.json({ ok: false, error: "No caption cues produced." }, 502);
+        }
+        const result = insertCaptionLayers(html, cues, {
+            style: str("style"),
+            animation: str("animation"),
+            activeColor: str("active_color"),
+            highlightColor: str("highlight_color"),
+            uppercase: body.uppercase === true ? true : body.uppercase === false ? false : undefined,
+            color: str("color"),
+            background: str("background"),
+            backgroundStyle: str("background_style"),
+            fontFamily: str("font_family"),
+            fontSize: num("font_size"),
+            track: num("track"),
+            x: num("x"),
+            y: num("y"),
+            width: num("width"),
+            height: num("height")
+        });
+        const { html: sanitized, removed } = sanitizeCompositionHtml(result.html);
+        await storage.putText(storage.compositionForkWorkingKey(fork.id, "composition.html"), sanitized, "text/html; charset=utf-8");
+        const updated = await serverlessRecords.updateCompositionFork({ forkId: fork.id, patch: {} });
+        await writeForkManifest(storage, updated ?? fork, { kind: "working" });
+        return c.json({
+            ok: true,
+            cue_count: cues.length,
+            replaced: result.replaced,
+            style: result.styleId,
+            word_timestamps: wordTimestampSource,
+            source: sourceNote,
+            layer_keys: result.layerKeys,
+            sanitized: removed
+        });
+    }
+    catch (error) {
+        return forkAccessErrorResponse(c, error);
+    }
+});
 // Same-origin live-reload stream (local `vidfarm serve` only). Broadcasts when
 // an on-disk working composition file changes so open editor tabs live-morph
 // the agent's edits. Replaces the old cross-origin dev-serve `/_events`.
@@ -8604,6 +8838,7 @@ function serializeInspiration(inspiration) {
         keywords: inspiration.keywords ?? null,
         summary: inspiration.searchSummary ?? null,
         visibility: inspiration.visibility ?? "public",
+        origin: inspiration.origin ?? "inspiration",
         notes: inspiration.notes ?? null,
         ingester_customer_id: inspiration.customerId,
         error: inspiration.errorMessage,
@@ -8664,6 +8899,7 @@ async function finalizeInspirationIfReady(inspiration) {
                 songName: ready.songName,
                 songUrl: ready.songUrl,
                 visibility: "private",
+                origin: ready.origin ?? "inspiration",
                 notes: ready.notes
             });
             ready = (await serverlessRecords.updateInspiration({
@@ -10762,7 +10998,8 @@ async function ensureInspirationReadyThenFork(input) {
             videoUrl: inspiration.videoUrl,
             durationSeconds: inspiration.durationSeconds,
             songName: inspiration.songName,
-            songUrl: inspiration.songUrl
+            songUrl: inspiration.songUrl,
+            origin: inspiration.origin ?? "inspiration"
         });
         await serverlessRecords.updateInspiration({
             inspirationId: inspiration.id,
@@ -10789,6 +11026,10 @@ function buildRawTikTokCompositionHtml(input) {
     const duration = Number.isFinite(input.durationSeconds) && input.durationSeconds > 0
         ? Number(input.durationSeconds.toFixed(3))
         : 12;
+    // data-vf-origin travels with the document through fork copies; the editor
+    // reads it to decide whether to auto-prompt the Decompose modal ("raw"
+    // projects never prompt). Absent means "inspiration" (pre-field documents).
+    const origin = input.origin === "raw" ? "raw" : "inspiration";
     return `<!doctype html>
 <html lang="en">
 <head>
@@ -10801,7 +11042,7 @@ function buildRawTikTokCompositionHtml(input) {
   </style>
 </head>
 <body>
-  <div data-composition-id="${escapeAttribute(input.compositionId)}" data-source-video="${escapeAttribute(input.sourceUrl)}" data-width="720" data-height="1280" data-duration="${duration}" data-source-title="${escapeAttribute(input.title)}">
+  <div data-composition-id="${escapeAttribute(input.compositionId)}" data-vf-origin="${origin}" data-source-video="${escapeAttribute(input.sourceUrl)}" data-width="720" data-height="1280" data-duration="${duration}" data-source-title="${escapeAttribute(input.title)}">
     <video id="vf-source-video" data-hf-id="vf-source-video" data-vf-playback-source="true" data-layer-kind="video" data-start="0" data-duration="${duration}" data-track-index="0" data-label="Original video" data-timeline-label="Original video" src="${escapeAttribute(input.sourceUrl)}" muted playsinline preload="auto" style="position:absolute;left:0%;top:0%;width:100%;height:100%;z-index:0;object-fit:cover;background:#050604"></video>
   </div>
 </body>
@@ -13777,7 +14018,8 @@ const AI_PRIMITIVE_IDS = new Set([
     "primitive:image_inpaint",
     "primitive:video_generate",
     "primitive:tts",
-    "primitive:stt"
+    "primitive:stt",
+    "primitive:captions"
 ]);
 async function preflightAiProviderKeys(input) {
     if (!operationMayUseAiProvider(input)) {
@@ -14300,6 +14542,9 @@ app.post(`${PRIMITIVES_PREFIX}/audio/speech`, async (c) => createPrimitiveJob(c,
 app.post(`${PRIMITIVES_PREFIX}/tts`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:tts", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/audio/transcribe`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:stt", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/stt`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:stt", operationName: "run" }));
+// Animated-caption cues from narration (STT + word timings + cue paging).
+app.post(`${PRIMITIVES_PREFIX}/audio/captions`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:captions", operationName: "run" }));
+app.post(`${PRIMITIVES_PREFIX}/captions`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:captions", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/brainstorm/hooks`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:brainstorm_hooks", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/brainstorm/awareness_stages`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:brainstorm_awareness_stages", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/brainstorm/angles`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:brainstorm_angles", operationName: "run" }));
@@ -15266,6 +15511,9 @@ function renderClipsPage(input) {
       .clips-import-head p { font-size: 0.9rem; }
       .clips-import-field { display: grid; gap: 6px; }
       .clips-import-field textarea { min-height: 96px; border-radius: 18px; }
+      .clips-import-field select { width: 100%; }
+      .clips-import-hint { font-size: 0.78rem; font-weight: 400; color: var(--muted); }
+      .clips-import-hint a { color: inherit; text-decoration: underline; }
       .clips-import-note { min-height: 18px; font-size: 0.85rem; color: var(--muted); }
       .clips-import-note[data-tone="error"] { color: #9f3d3d; }
       .clips-import-note[data-tone="success"] { color: #3f7d55; }
@@ -15333,6 +15581,20 @@ function renderClipsPage(input) {
             <label for="importPrompt">What to clip for</label>
             <textarea id="importPrompt" name="prompt" placeholder="Clip scenes of people with food, no text on screen, vertical, between 5-10 secs long"></textarea>
           </div>
+          <div class="clips-import-field">
+            <label for="importProvider">AI provider</label>
+            <select id="importProvider" name="provider">
+              <option value="">Auto — use my saved keys</option>
+              <option value="gemini">Gemini</option>
+              <option value="openai">OpenAI</option>
+              <option value="openrouter">OpenRouter</option>
+            </select>
+            <div class="clips-import-hint" id="importProviderHint"></div>
+          </div>
+          <div class="clips-import-field">
+            <label for="importTracer">Tracer <span class="clips-import-hint">optional — rolls up this hunt's billing and clips under one id</span></label>
+            <input id="importTracer" name="tracer" type="text" placeholder="my-campaign-001" autocomplete="off" spellcheck="false" />
+          </div>
           <div class="clips-import-note" id="importNote"></div>
           <div class="clips-import-actions">
             <button type="button" class="secondary" id="importCancel">Cancel</button>
@@ -15422,18 +15684,58 @@ function renderClipsPage(input) {
           var importForm = document.getElementById('importForm');
           var importUrl = document.getElementById('importUrl');
           var importPrompt = document.getElementById('importPrompt');
+          var importTracer = document.getElementById('importTracer');
+          var importProvider = document.getElementById('importProvider');
+          var importProviderHint = document.getElementById('importProviderHint');
           var importNote = document.getElementById('importNote');
           var importCancel = document.getElementById('importCancel');
           var importSubmit = document.getElementById('importSubmit');
           var scanPoll = null;
+          var scanOptions = null;
 
           function setNote(msg, tone){
             if(!importNote) return;
             importNote.textContent = msg || '';
             if(tone) importNote.setAttribute('data-tone', tone); else importNote.removeAttribute('data-tone');
           }
+          function providerName(p){ return p==='gemini'?'Gemini':p==='openai'?'OpenAI':p==='openrouter'?'OpenRouter':p; }
+          function renderProviderOptions(){
+            if(!importProvider || !scanOptions) return;
+            var d = scanOptions;
+            var hasAnyKey = (d.providers||[]).some(function(p){ return p.has_key; });
+            var autoLabel = 'Auto';
+            if(d.default_provider === 'agent') autoLabel = 'Auto — local '+((d.local_agent&&d.local_agent.kind)||'agent')+' CLI (no API key)';
+            else if(d.default_provider) autoLabel = 'Auto — saved '+providerName(d.default_provider)+' key';
+            else if(d.pipeline === 'upstream') autoLabel = 'Auto — linked cloud account';
+            var html = '<option value="">'+esc(autoLabel)+'</option>';
+            if(d.local_agent) html += '<option value="agent">Local agent ('+esc(d.local_agent.kind)+') — your CLI subscription, no API key</option>';
+            (d.providers||[]).forEach(function(p){
+              html += '<option value="'+esc(p.provider)+'"'+(p.has_key?'':' disabled')+'>'+esc(providerName(p.provider))+(p.has_key?' — key saved':' — no key saved')+'</option>';
+            });
+            importProvider.innerHTML = html;
+            if(!importProviderHint) return;
+            if(!hasAnyKey && !d.local_agent && d.pipeline !== 'upstream'){
+              importProviderHint.innerHTML = 'No AI provider available yet — add a Gemini, OpenAI, or OpenRouter key in <a href="/settings" target="_blank" rel="noopener">Settings</a>'
+                + (d.pipeline === 'cloud' ? '.' : ', or install the Claude Code / Codex CLI for keyless local scans.');
+            } else if(d.pipeline === 'upstream'){
+              importProviderHint.textContent = 'No local key or agent CLI — this hunt will run on your linked cloud account (its saved keys, cloud compute).';
+            } else if(d.pipeline === 'local'){
+              importProviderHint.textContent = d.default_provider === 'agent'
+                ? 'Runs on this machine with your local agent CLI — no API key needed. Or pick a saved key.'
+                : 'Runs on this machine with your saved key (BYOK — billed to your own provider account).';
+            } else {
+              importProviderHint.textContent = 'AI tagging runs on your own key (BYOK) — pick a provider or let Auto choose.';
+            }
+          }
+          function loadScanOptions(){
+            fetch('/clips/scan-options', {credentials:'same-origin', headers:{Accept:'application/json'}})
+              .then(function(r){ return r.ok ? r.json() : null; })
+              .then(function(d){ if(d){ scanOptions = d; renderProviderOptions(); } })
+              .catch(function(){});
+          }
           function openImport(){
             setNote('');
+            if(!scanOptions) loadScanOptions();
             if(importDialog && typeof importDialog.showModal === 'function' && !importDialog.open) importDialog.showModal();
             if(importUrl) importUrl.focus();
           }
@@ -15476,16 +15778,21 @@ function renderClipsPage(input) {
             e.preventDefault();
             var url = (importUrl && importUrl.value || '').trim();
             var prompt = (importPrompt && importPrompt.value || '').trim();
+            var tracer = (importTracer && importTracer.value || '').trim();
+            var provider = (importProvider && importProvider.value || '').trim();
             if(!url){ setNote('Enter a video URL.', 'error'); return; }
             setNote('Starting scan…');
             if(importSubmit) importSubmit.disabled = true;
-            fetch('/clips/scan', {method:'POST', credentials:'same-origin', headers:{'Content-Type':'application/json', Accept:'application/json'}, body: JSON.stringify({source_url:url, prompt:prompt})})
+            var payload = {source_url:url, prompt:prompt};
+            if(tracer) payload.tracer = tracer;
+            if(provider) payload.provider = provider;
+            fetch('/clips/scan', {method:'POST', credentials:'same-origin', headers:{'Content-Type':'application/json', Accept:'application/json'}, body: JSON.stringify(payload)})
               .then(function(r){ return r.json().then(function(d){ return {ok:r.ok, status:r.status, data:d}; }); })
               .then(function(res){
                 if(importSubmit) importSubmit.disabled = false;
                 if(!res.ok){ setNote((res.data && res.data.error) || 'Could not start the scan.', 'error'); return; }
                 setNote('Scan started — this can take a few minutes.', 'success');
-                statusEl.textContent='Scanning source…';
+                statusEl.textContent='Scanning source…'+(res.data && res.data.tracer ? ' (tracer '+res.data.tracer+')' : '');
                 closeImport();
                 if(importForm.reset) importForm.reset();
                 if(res.data && res.data.scan_id) pollScan(res.data.scan_id);
@@ -15513,9 +15820,23 @@ async function resolveCustomerProviderKey(customerId, provider) {
     }
     return null;
 }
-// Normalize a request-supplied provider to the supported set (default gemini).
-function normalizeClipProvider(value) {
-    return value === "openai" || value === "openrouter" ? value : "gemini";
+// The BYOK API providers clip hunts can run on, in auto-pick preference order.
+const CLIP_API_PROVIDERS = ["gemini", "openai", "openrouter"];
+const NO_CLIP_PROVIDER_KEY_ERROR = "No AI provider key saved. Add a gemini, openai, or openrouter key (Settings → AI Provider Keys, or POST /api/v1/user/me/provider-keys) and retry.";
+// An explicitly requested provider — "agent" means the caller's local
+// claude/codex CLI (vidfarm serve boxes only) — or null for auto-pick.
+function readClipProviderChoice(value) {
+    if (value === "gemini" || value === "openai" || value === "openrouter")
+        return value;
+    if (value === "agent" || value === "local" || value === "local-agent")
+        return "agent";
+    return null;
+}
+// Auto-pick: the first API provider the customer holds an active key for
+// (gemini → openai → openrouter) — no more hard gemini default.
+async function pickClipProviderFromKeys(customerId) {
+    const keys = await loadCustomerVisionKeys(customerId);
+    return CLIP_API_PROVIDERS.find((p) => keys[p]) ?? null;
 }
 /**
  * A client for embedding MATCH queries in the SAME vector space the library was
@@ -15571,7 +15892,8 @@ function parseClipStorageKey(pathOrUri) {
 async function clipMediaUrl(pathOrUri) {
     if (!pathOrUri)
         return null;
-    const key = parseClipStorageKey(pathOrUri);
+    // s3://… (cloud hunts) or a bare clips/thumbs storage key (serve-box local hunts).
+    const key = parseClipStorageKey(pathOrUri) ?? (/^(clips|thumbs)\//.test(pathOrUri) ? pathOrUri : null);
     if (key)
         return (await storage.getReadUrl(key)) ?? storage.getPublicUrl(key);
     return pathOrUri; // non-s3 value (e.g. a local devcli-origin path) — pass through
@@ -15631,11 +15953,14 @@ app.post(`${CLIPS_PREFIX}/search`, async (c) => {
     try {
         const body = (await c.req.json().catch(() => ({})));
         const limit = Math.max(1, Math.min(200, Number(body.limit) || 20));
-        const provider = normalizeClipProvider(body.provider);
+        const requested = readClipProviderChoice(body.provider);
         let criteria = body.criteria ?? (body.query ? { semantic_text: body.query } : {});
         let queryEmbedding;
         if (body.query || criteria.semantic_text) {
-            const built = await buildCustomerClipClient(customer.id, provider);
+            // Any saved key works for NL→criteria + query embedding; no key at all
+            // fail-softs to the structured/keyword pass below.
+            const provider = (requested !== "agent" ? requested : null) ?? (await pickClipProviderFromKeys(customer.id));
+            const built = provider ? await buildCustomerClipClient(customer.id, provider) : { error: NO_CLIP_PROVIDER_KEY_ERROR };
             if ("client" in built) {
                 const client = built.client;
                 if (body.query && !body.criteria)
@@ -15791,72 +16116,106 @@ app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
         }
         const rawS3Uri = body.raw_s3_uri ??
             (resolvedS3Key && config.AWS_S3_BUCKET ? `s3://${config.AWS_S3_BUCKET}/${resolvedS3Key}` : undefined);
-        if (!rawS3Uri && !huntSpec.source_url) {
+        // On a serve box (no bucket) resolvedS3Key is a LOCAL storage key — still a valid source.
+        if (!rawS3Uri && !resolvedS3Key && !huntSpec.source_url) {
             return c.json({ error: "Provide source_url (a video URL), temp_file_id/attachment_id of an upload, raw_s3_uri (s3://…), or s3_key of the staged source video." }, 400);
         }
-        // Hunts bill AWS compute post-hoc, so submission is the spend gate (same
-        // policy as job submission).
-        try {
-            await assertWalletCanQueueJobs(customer.id);
-        }
-        catch (error) {
-            if (error instanceof InsufficientWalletFundsError) {
-                return insufficientFundsResponse(c, error);
-            }
-            throw error;
-        }
-        const provider = normalizeClipProvider(body.provider);
-        const built = await buildCustomerClipClient(customer.id, provider);
-        if ("error" in built)
-            return c.json({ error: built.error }, 400);
-        const { client, apiKey: tagApiKey, embeddingKey } = built;
+        const cloudPipeline = Boolean(config.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN);
+        const choice = readClipProviderChoice(body.provider);
         const tier = normalizeScanTier(body.tier);
         const framesPerScene = Math.max(1, Math.min(3, Number(body.frames_per_scene) || 2));
-        const includeAudio = body.include_audio !== false && provider === "gemini";
         const tracer = readNonEmptyString(body.tracer) ?? `clips_import:${customer.id}`;
         const now = nowIso();
         const scanId = createIdV7("clipscan");
         const sourceVideoId = createIdV7("srcvid");
-        // The URL ingest is deferred to the Lambda, so raw_s3_uri may be empty here.
-        const sourcePointer = rawS3Uri ?? huntSpec.source_url ?? "";
+        // The URL ingest is deferred to the runner, so raw_s3_uri may be empty here.
+        const sourcePointer = rawS3Uri ?? resolvedS3Key ?? huntSpec.source_url ?? "";
         const filename = body.filename || (sourcePointer.split("/").pop() || "source.mp4").split("?")[0] || "source.mp4";
-        // Time-range hunts only pay for the windows: both estimates use the
-        // EFFECTIVE (windowed) duration, and the duration band drives the expected
-        // scene size. The BYOK estimate is the user's own provider spend; the
-        // compute estimate is what the wallet will be billed (AWS only, marked up).
-        const effectiveDurationSec = body.duration_sec && body.duration_sec > 0
-            ? effectiveHuntDurationSec(body.duration_sec, huntSpec.windows)
-            : null;
-        const estimate = effectiveDurationSec
-            ? estimateScanCostFromDuration(effectiveDurationSec, {
+        const putScanRecords = async (input) => {
+            await clipRecords.putSource({
+                source_video_id: sourceVideoId,
+                owner_id: customer.id,
+                filename,
+                raw_s3_uri: sourcePointer,
+                duration_sec: body.duration_sec,
+                clip_count: 0,
                 tier,
-                provider,
-                tagModelId: client.tagModelId,
-                embedModelId: client.embeddingModelId,
-                framesPerScene,
-                includeAudio,
-                avgSceneSec: huntSpec.duration_band?.target_sec
-            })
-            : null;
-        const computeEstimate = effectiveDurationSec
-            ? estimateClipScanComputeUsd(effectiveDurationSec, huntSpec.duration_band?.target_sec)
-            : null;
-        const source = {
-            source_video_id: sourceVideoId,
-            owner_id: customer.id,
-            filename,
-            raw_s3_uri: sourcePointer,
-            duration_sec: body.duration_sec,
-            clip_count: 0,
-            tier,
-            status: "pending",
-            scan_id: scanId,
-            created_at: now,
-            updated_at: now
+                status: "pending",
+                scan_id: scanId,
+                tracer,
+                created_at: now,
+                updated_at: now
+            });
+            await clipRecords.putScan({
+                scan_id: scanId,
+                owner_id: customer.id,
+                source_video_id: sourceVideoId,
+                status: input.scanStatus,
+                tier,
+                raw_s3_uri: sourcePointer,
+                execution_arn: input.executionArn,
+                tracer,
+                created_at: now,
+                updated_at: now
+            });
         };
-        await clipRecords.putSource(source);
-        let executionArn;
-        if (config.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN) {
+        const scanResponse = (input) => c.json({
+            scan_id: scanId,
+            source_video_id: sourceVideoId,
+            status: input.status,
+            execution_arn: input.executionArn ?? null,
+            tracer,
+            hunt_spec: huntSpec,
+            estimate: input.estimate ?? null,
+            compute_estimate: input.computeEstimate ?? null,
+            pipeline: input.pipeline,
+            pipeline_deployed: cloudPipeline
+        }, 202);
+        if (cloudPipeline) {
+            // ── Deployed pipeline (Lambda + Step Functions): BYOK API keys only ──
+            if (choice === "agent") {
+                return c.json({ error: "provider \"agent\" (your local claude/codex CLI) only runs on a local `vidfarm serve` box — the deployed pipeline needs a saved gemini, openai, or openrouter key." }, 400);
+            }
+            // Hunts bill AWS compute post-hoc, so submission is the spend gate (same
+            // policy as job submission).
+            try {
+                await assertWalletCanQueueJobs(customer.id);
+            }
+            catch (error) {
+                if (error instanceof InsufficientWalletFundsError) {
+                    return insufficientFundsResponse(c, error);
+                }
+                throw error;
+            }
+            const provider = choice ?? (await pickClipProviderFromKeys(customer.id));
+            if (!provider)
+                return c.json({ error: NO_CLIP_PROVIDER_KEY_ERROR }, 400);
+            const built = await buildCustomerClipClient(customer.id, provider);
+            if ("error" in built)
+                return c.json({ error: built.error }, 400);
+            const { client, apiKey: tagApiKey, embeddingKey } = built;
+            const includeAudio = body.include_audio !== false && provider === "gemini";
+            // Time-range hunts only pay for the windows: both estimates use the
+            // EFFECTIVE (windowed) duration, and the duration band drives the expected
+            // scene size. The BYOK estimate is the user's own provider spend; the
+            // compute estimate is what the wallet will be billed (AWS only, marked up).
+            const effectiveDurationSec = body.duration_sec && body.duration_sec > 0
+                ? effectiveHuntDurationSec(body.duration_sec, huntSpec.windows)
+                : null;
+            const estimate = effectiveDurationSec
+                ? estimateScanCostFromDuration(effectiveDurationSec, {
+                    tier,
+                    provider,
+                    tagModelId: client.tagModelId,
+                    embedModelId: client.embeddingModelId,
+                    framesPerScene,
+                    includeAudio,
+                    avgSceneSec: huntSpec.duration_band?.target_sec
+                })
+                : null;
+            const computeEstimate = effectiveDurationSec
+                ? estimateClipScanComputeUsd(effectiveDurationSec, huntSpec.duration_band?.target_sec)
+                : null;
             const res = await clipScanSfn.send(new StartExecutionCommand({
                 stateMachineArn: config.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN,
                 name: scanId.replace(/[^A-Za-z0-9-_]/g, "-").slice(0, 80),
@@ -15878,43 +16237,358 @@ app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
                     tracer
                 })
             }));
-            executionArn = res.executionArn;
+            await putScanRecords({ scanStatus: "running", executionArn: res.executionArn });
+            return scanResponse({ status: "running", executionArn: res.executionArn, pipeline: "cloud", estimate, computeEstimate });
+        }
+        // ── vidfarm serve (no deployed pipeline): LOCAL-FIRST, cloud as backup ──
+        // Same policy as `vidfarm clips scan`: the user's local claude/codex CLI
+        // subscription evaluates scenes when installed, their saved BYOK keys are
+        // the fallback, and the upstream cloud REST API is the explicit backup.
+        // Local hunts are free (no wallet gate), like local renders.
+        let localSourcePath = null;
+        if (resolvedS3Key) {
+            localSourcePath = storage.getLocalPath(resolvedS3Key);
+            if (!localSourcePath || !existsSync(localSourcePath)) {
+                return c.json({ error: "That upload isn't on this box's local storage — re-upload it or pass source_url." }, 400);
+            }
+        }
+        else if (body.raw_s3_uri) {
+            return c.json({ error: "raw_s3_uri isn't supported on a local box — pass source_url, temp_file_id, or attachment_id." }, 400);
+        }
+        const localAgent = choice === "agent" || choice === null ? detectLocalAgent() : null;
+        if (choice === "agent" && !localAgent) {
+            return c.json({ error: "No local agent CLI found — install Claude Code (`claude`) or Codex (`codex`), or pick gemini/openai/openrouter." }, 400);
+        }
+        let evaluator = null;
+        let evaluatorProvider = null;
+        let evaluatorError = null;
+        if (localAgent) {
+            const keys = await loadCustomerVisionKeys(customer.id);
+            const embedding = keys.gemini
+                ? { provider: "gemini", apiKey: keys.gemini }
+                : keys.openai
+                    ? { provider: "openai", apiKey: keys.openai }
+                    : null;
+            evaluator = new LocalAgentClipClient({ agent: localAgent.kind, bin: localAgent.bin, embedding, tier });
+            evaluatorProvider = `agent/${localAgent.kind}`;
+        }
+        else {
+            const provider = (choice !== "agent" ? choice : null) ?? (await pickClipProviderFromKeys(customer.id));
+            if (provider) {
+                const built = await buildCustomerClipClient(customer.id, provider);
+                if ("error" in built) {
+                    if (choice)
+                        return c.json({ error: built.error }, 400);
+                    evaluatorError = built.error;
+                }
+                else {
+                    evaluator = built.client;
+                    evaluatorProvider = provider;
+                }
+            }
+            else {
+                evaluatorError = NO_CLIP_PROVIDER_KEY_ERROR;
+            }
+        }
+        const ffmpegOk = await hasFfmpeg();
+        const canIngestUrl = !huntSpec.source_url ||
+            Boolean((config.RAPIDAPI_KEY || "").trim()) ||
+            looksLikeDirectVideoUrl(huntSpec.source_url);
+        if (evaluator && ffmpegOk && (localSourcePath || canIngestUrl)) {
+            const includeAudio = body.include_audio !== false && evaluatorProvider === "gemini";
+            await putScanRecords({ scanStatus: "running" });
+            void runClipScanInProcess({
+                scanId,
+                ownerId: customer.id,
+                sourceVideoId,
+                filename,
+                client: evaluator,
+                localSourcePath,
+                sourceUrl: huntSpec.source_url ?? null,
+                huntSpec,
+                guidancePrompt,
+                framesPerScene,
+                includeAudio
+            }).catch((error) => {
+                devLog("clip_scan.local_run_failed", { scan_id: scanId, ...devErrorFields(error) }, "error");
+            });
+            return scanResponse({ status: "running", pipeline: "local" });
+        }
+        // BACKUP: hand the hunt to the upstream cloud deployment (its saved BYOK
+        // keys run the AI; its account is billed the AWS compute).
+        if (hasUpstreamKey() && huntSpec.source_url) {
+            const upstream = await upstreamJson("/clips/scan", {
+                method: "POST",
+                body: {
+                    source_url: huntSpec.source_url,
+                    prompt: guidancePrompt,
+                    hunt_spec: huntSpec,
+                    tracer,
+                    ...(choice && choice !== "agent" ? { provider: choice } : {})
+                },
+                timeoutMs: 30_000
+            });
+            if (!upstream.ok || !upstream.json?.scan_id) {
+                return c.json({ error: upstream.json?.error ?? `Upstream cloud scan failed to start (HTTP ${upstream.status}).` }, 502);
+            }
+            const marker = `upstream:${upstream.json.scan_id}:${upstream.json.source_video_id ?? ""}`;
+            await putScanRecords({ scanStatus: "running", executionArn: marker });
+            return scanResponse({ status: "running", executionArn: marker, pipeline: "upstream" });
+        }
+        const reasons = [];
+        if (!evaluator)
+            reasons.push(evaluatorError ?? "no scene evaluator available");
+        if (evaluator && !ffmpegOk)
+            reasons.push("ffmpeg was not found on this machine");
+        if (evaluator && ffmpegOk && huntSpec.source_url && !canIngestUrl) {
+            reasons.push("this box can't ingest social URLs (set RAPIDAPI_KEY, or pass a direct .mp4 link / upload the file)");
         }
-        const scan = {
-            scan_id: scanId,
-            owner_id: customer.id,
-            source_video_id: sourceVideoId,
-            status: executionArn ? "running" : "queued",
-            tier,
-            raw_s3_uri: sourcePointer,
-            execution_arn: executionArn,
-            tracer,
-            created_at: now,
-            updated_at: now
-        };
-        await clipRecords.putScan(scan);
         return c.json({
-            scan_id: scanId,
-            source_video_id: sourceVideoId,
-            status: scan.status,
-            execution_arn: executionArn ?? null,
-            tracer,
-            hunt_spec: huntSpec,
-            estimate,
-            compute_estimate: computeEstimate,
-            pipeline_deployed: Boolean(config.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN)
-        }, 202);
+            error: `Can't run this hunt on this box: ${reasons.join("; ")}. Install Claude Code (\`claude\`) or Codex (\`codex\`) for keyless local scans, add a provider key, or link a cloud account (VIDFARM_UPSTREAM_HOST + VIDFARM_UPSTREAM_API_KEY) to use the cloud as backup.`
+        }, 400);
     }
     catch (error) {
         return c.json({ error: error instanceof Error ? error.message : "Failed to start clip scan." }, 400);
     }
 });
+// GET /clips/scan-options — what the Import Source modal can run a hunt with:
+// which BYOK providers have saved keys, whether a local agent CLI is available
+// (vidfarm serve boxes only), what "auto" resolves to, and where the hunt runs.
+app.get(`${CLIPS_PREFIX}/scan-options`, async (c) => {
+    const customer = requireCustomer(c);
+    const keys = await loadCustomerVisionKeys(customer.id);
+    const cloudPipeline = Boolean(config.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN);
+    const localAgent = cloudPipeline ? null : detectLocalAgent();
+    const keyProvider = CLIP_API_PROVIDERS.find((p) => keys[p]) ?? null;
+    const defaultProvider = localAgent ? "agent" : keyProvider;
+    const ffmpegOk = cloudPipeline ? true : await hasFfmpeg();
+    const pipeline = cloudPipeline
+        ? keyProvider ? "cloud" : null
+        : defaultProvider && ffmpegOk ? "local" : hasUpstreamKey() ? "upstream" : null;
+    return c.json({
+        providers: CLIP_API_PROVIDERS.map((p) => ({ provider: p, has_key: Boolean(keys[p]) })),
+        local_agent: localAgent ? { kind: localAgent.kind } : null,
+        default_provider: defaultProvider,
+        pipeline,
+        upstream_backup: !cloudPipeline && hasUpstreamKey()
+    });
+});
+function looksLikeDirectVideoUrl(url) {
+    try {
+        return /\.(mp4|mov|m4v|webm|mkv)$/i.test(new URL(url).pathname);
+    }
+    catch {
+        return false;
+    }
+}
+// Local URL ingest for serve-box hunts: direct video links download straight;
+// social URLs (TikTok/YouTube/IG/X) resolve through the same RapidAPI
+// downloader the video_download primitive uses (needs RAPIDAPI_KEY locally).
+async function ingestClipSourceUrlLocally(sourceUrl, workDir) {
+    if (!sourceUrl)
+        throw new Error("Clip scan needs a source video.");
+    let mediaUrl = sourceUrl;
+    if (!looksLikeDirectVideoUrl(sourceUrl)) {
+        const apiKey = (config.RAPIDAPI_KEY || "").trim();
+        if (!apiKey) {
+            throw new Error("This box can't ingest social URLs (RAPIDAPI_KEY unset) — pass a direct .mp4 URL or upload the file.");
+        }
+        const lookupRes = await fetch(config.RAPIDAPI_VIDEO_DOWNLOAD_URL, {
+            method: "POST",
+            headers: {
+                "x-rapidapi-key": apiKey,
+                "x-rapidapi-host": config.RAPIDAPI_VIDEO_DOWNLOAD_HOST,
+                "content-type": "application/x-www-form-urlencoded"
+            },
+            body: new URLSearchParams({ url: sourceUrl })
+        });
+        if (!lookupRes.ok)
+            throw new Error(`Video download lookup failed with HTTP ${lookupRes.status}.`);
+        const lookup = (await lookupRes.json());
+        const playable = (lookup.medias ?? []).filter((m) => m.url && m.videoAvailable !== false && (m.type ? /video/i.test(m.type) : true));
+        const chosen = playable.find((m) => (m.extension ?? "").toLowerCase() === "mp4" || /\.mp4(\?|$)/i.test(m.url ?? "")) ?? playable[0];
+        if (!chosen?.url)
+            throw new Error("Video download lookup returned no playable MP4 media URL.");
+        mediaUrl = chosen.url;
+    }
+    const localPath = path.join(workDir, "ingest", "source.mp4");
+    mkdirSync(path.dirname(localPath), { recursive: true });
+    const res = await fetch(mediaUrl);
+    if (!res.ok || !res.body)
+        throw new Error(`Source video download failed with HTTP ${res.status}.`);
+    await streamPipeline(Readable.fromWeb(res.body), createWriteStream(localPath));
+    return localPath;
+}
+// In-process clip hunt for `vidfarm serve` boxes (no Step Functions worker).
+// Mirrors the clip-scan Lambda pipeline — ingest → probe/detect → refine →
+// per-scene tag/embed → finalize — with local ffmpeg and the resolved
+// evaluator (local claude/codex CLI or a BYOK key). Free: no wallet billing,
+// exactly like local renders. Detached; the client polls /clips/scan/:scanId.
+async function runClipScanInProcess(input) {
+    const workRoot = path.join(config.VIDFARM_DATA_DIR, "clip-scans", input.scanId);
+    const touchScan = async (patch) => {
+        const scan = await clipRecords.getScan(input.ownerId, input.scanId);
+        if (scan)
+            await clipRecords.putScan({ ...scan, ...patch, updated_at: nowIso() });
+    };
+    const touchSource = async (patch) => {
+        const source = await clipRecords.getSource(input.ownerId, input.sourceVideoId);
+        if (source)
+            await clipRecords.putSource({ ...source, ...patch, updated_at: nowIso() });
+    };
+    try {
+        mkdirSync(workRoot, { recursive: true });
+        const videoPath = input.localSourcePath ?? (await ingestClipSourceUrlLocally(input.sourceUrl ?? "", workRoot));
+        const probe = await probeVideo(videoPath);
+        await touchSource({ status: "scanning", duration_sec: probe.duration_sec });
+        const spec = input.huntSpec;
+        const ctx = {
+            client: input.client,
+            workDir: path.join(workRoot, "work"),
+            clipsDir: path.join(workRoot, "clips"),
+            thumbsDir: path.join(workRoot, "thumbs"),
+            framesPerScene: input.framesPerScene,
+            includeAudio: input.includeAudio,
+            guidancePrompt: buildEffectiveGuidance({ contentPrompt: input.guidancePrompt, avoidText: spec.avoid_text }) || undefined,
+            reencodeClips: true,
+            crop: spec.aspect && spec.aspect !== "original"
+                ? { aspect: spec.aspect, focus: normalizeCropFocus(spec.crop_focus) }
+                : undefined
+        };
+        let stored = 0;
+        await scanVideo({
+            ctx,
+            videoPath,
+            probe,
+            windows: spec.windows,
+            durationBand: spec.duration_band ?? null,
+            sourceVideoId: input.sourceVideoId,
+            sourceFilename: input.filename,
+            ownerId: input.ownerId,
+            // Local agents run one CLI process per call — keep parallelism modest.
+            concurrency: input.client.provider === "local-agent" ? 2 : 3,
+            onClip: async (clip) => {
+                // Persist through the storage service (local driver) as bare keys —
+                // clipMediaUrl resolves clips/… + thumbs/… keys to fetchable URLs.
+                const clipKey = `clips/${input.ownerId}/${clip.clip_id}.mp4`;
+                const clipLocal = path.join(ctx.clipsDir, `${clip.clip_id}.mp4`);
+                await storage.putBuffer(clipKey, readFileSync(clipLocal), "video/mp4");
+                clip.file_path = clipKey;
+                const thumbLocal = path.join(ctx.thumbsDir, `${clip.clip_id}.jpg`);
+                if (existsSync(thumbLocal)) {
+                    const thumbKey = `thumbs/${input.ownerId}/${clip.clip_id}.jpg`;
+                    await storage.putBuffer(thumbKey, readFileSync(thumbLocal), "image/jpeg");
+                    clip.thumbnail_path = thumbKey;
+                }
+                else {
+                    clip.thumbnail_path = "";
+                }
+                await clipRecords.putClip(clip);
+                await vectorIndex.upsert(input.ownerId, clip);
+                stored++;
+            },
+            onError: (scene, error) => {
+                devLog("clip_scan.local_scene_failed", { scan_id: input.scanId, scene_start: scene.start_time_sec, ...devErrorFields(error) }, "warn");
+            }
+        });
+        await touchSource({ status: "complete", clip_count: stored });
+        await touchScan({ status: "complete" });
+    }
+    catch (error) {
+        devLog("clip_scan.local_failed", { scan_id: input.scanId, ...devErrorFields(error) }, "error");
+        await touchSource({ status: "failed" }).catch(() => undefined);
+        await touchScan({ status: "failed", error: error instanceof Error ? error.message : String(error) }).catch(() => undefined);
+    }
+    finally {
+        rmSync(workRoot, { recursive: true, force: true });
+    }
+}
+// A serve-box hunt handed to the upstream cloud (execution_arn
+// "upstream:<scan_id>:<source_video_id>"): mirror the upstream status onto the
+// local records, and when the cloud hunt completes pull the finished clips
+// down into local storage — the cloud runs the hunt, the box owns the result.
+const activeUpstreamClipMirrors = new Set();
+async function reconcileUpstreamClipScan(ownerId, scan) {
+    const [, upstreamScanId, upstreamSourceId = ""] = (scan.execution_arn ?? "").split(":");
+    if (!upstreamScanId)
+        return scan;
+    const res = await upstreamJson(`/clips/scan/${encodeURIComponent(upstreamScanId)}`);
+    if (!res.ok || !res.json)
+        return scan; // transient upstream hiccup — keep polling
+    const status = res.json.source?.status ?? res.json.scan?.status ?? "running";
+    if (status === "failed" || status === "error") {
+        const failed = { ...scan, status: "failed", error: res.json.scan?.error ?? "Upstream cloud hunt failed.", updated_at: nowIso() };
+        await clipRecords.putScan(failed);
+        const source = await clipRecords.getSource(ownerId, scan.source_video_id);
+        if (source && source.status !== "complete") {
+            await clipRecords.putSource({ ...source, status: "failed", updated_at: nowIso() });
+        }
+        return failed;
+    }
+    if (status === "complete" && !activeUpstreamClipMirrors.has(scan.scan_id)) {
+        activeUpstreamClipMirrors.add(scan.scan_id);
+        void mirrorUpstreamClipsToLocal({ ownerId, scan, upstreamSourceId })
+            .catch((error) => devLog("clip_scan.upstream_mirror_failed", { scan_id: scan.scan_id, ...devErrorFields(error) }, "error"))
+            .finally(() => activeUpstreamClipMirrors.delete(scan.scan_id));
+    }
+    return scan; // stays "running" until the mirror lands the clips locally
+}
+async function mirrorUpstreamClipsToLocal(input) {
+    const { ownerId, scan } = input;
+    const query = input.upstreamSourceId ? `?source=${encodeURIComponent(input.upstreamSourceId)}&limit=200` : "?limit=200";
+    const feed = await upstreamJson(`/clips/feed${query}`, { timeoutMs: 60_000 });
+    if (!feed.ok || !feed.json)
+        throw new Error(`Upstream clip feed unavailable (HTTP ${feed.status}).`);
+    let stored = 0;
+    for (const raw of feed.json.clips ?? []) {
+        const clipId = typeof raw.clip_id === "string" ? raw.clip_id : null;
+        const viewUrl = typeof raw.view_url === "string" ? raw.view_url : null;
+        if (!clipId || !viewUrl)
+            continue;
+        const clipRes = await fetch(viewUrl);
+        if (!clipRes.ok)
+            continue;
+        const clipKey = `clips/${ownerId}/${clipId}.mp4`;
+        await storage.putBuffer(clipKey, new Uint8Array(await clipRes.arrayBuffer()), "video/mp4");
+        let thumbKey = "";
+        const thumbUrl = typeof raw.thumbnail_url === "string" ? raw.thumbnail_url : null;
+        if (thumbUrl) {
+            const thumbRes = await fetch(thumbUrl);
+            if (thumbRes.ok) {
+                thumbKey = `thumbs/${ownerId}/${clipId}.jpg`;
+                await storage.putBuffer(thumbKey, new Uint8Array(await thumbRes.arrayBuffer()), "image/jpeg");
+            }
+        }
+        const { view_url: _v, thumbnail_url: _t, ...rest } = raw;
+        void _v;
+        void _t;
+        await clipRecords.putClip({
+            ...rest,
+            owner_id: ownerId,
+            source_video_id: scan.source_video_id,
+            file_path: clipKey,
+            thumbnail_path: thumbKey
+        });
+        stored++;
+    }
+    const source = await clipRecords.getSource(ownerId, scan.source_video_id);
+    if (source)
+        await clipRecords.putSource({ ...source, status: "complete", clip_count: stored, updated_at: nowIso() });
+    const current = await clipRecords.getScan(ownerId, scan.scan_id);
+    await clipRecords.putScan({ ...(current ?? scan), status: "complete", updated_at: nowIso() });
+}
 // GET /clips/scan/:scanId — poll scan status.
 app.get(`${CLIPS_PREFIX}/scan/:scanId`, async (c) => {
     const customer = requireCustomer(c);
     let scan = await clipRecords.getScan(customer.id, c.req.param("scanId"));
     if (!scan)
         return c.json({ error: "Scan not found" }, 404);
+    // Serve-box hunts handed to the upstream cloud reconcile against the
+    // upstream REST API instead of Step Functions.
+    if ((scan.status === "running" || scan.status === "queued") && scan.execution_arn?.startsWith("upstream:")) {
+        scan = await reconcileUpstreamClipScan(customer.id, scan);
+    }
+    else 
     // Lazily reconcile with the Step Functions execution: the pipeline has no
     // failure hook back into the scan record, so a crashed execution would
     // otherwise leave "running" forever and pollers spin.
@@ -15960,7 +16634,11 @@ app.post(`${CLIPS_PREFIX}/presets`, async (c) => {
             return c.json({ error: "name is required." }, 400);
         let criteria = body.criteria;
         if (!criteria && body.query) {
-            const built = await buildCustomerClipClient(customer.id, normalizeClipProvider(body.provider));
+            const requested = readClipProviderChoice(body.provider);
+            const provider = (requested !== "agent" ? requested : null) ?? (await pickClipProviderFromKeys(customer.id));
+            if (!provider)
+                return c.json({ error: NO_CLIP_PROVIDER_KEY_ERROR }, 400);
+            const built = await buildCustomerClipClient(customer.id, provider);
             if ("error" in built)
                 return c.json({ error: built.error }, 400);
             criteria = await built.client.naturalLanguageToCriteria(body.query);