@mevdragon/vidfarm-devcli 0.12.0 → 0.14.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 { CAPTION_ANIM_CSS, CAPTION_STYLE_MARKER, KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, TRANSITION_CSS, TRANSITION_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, upgradeLegacyTransitionCss } 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, cosineSimilarity, 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";
@@ -395,7 +401,16 @@ const userAttachmentFinalizeSchema = z.object({
     content_type: z.string().trim().min(1).max(255),
     size_bytes: z.coerce.number().int().min(1).max(1024 * 1024 * 1024),
     storage_key: z.string().min(1).max(2000),
-    folder_path: z.string().trim().max(500).optional()
+    folder_path: z.string().trim().max(500).optional(),
+    notes: z.string().trim().max(4000).optional()
+});
+const userAttachmentNotesSchema = z.object({
+    notes: z.string().max(4000).nullable().optional()
+});
+const userAttachmentSearchSchema = z.object({
+    query: z.string().min(1).max(2000),
+    folder_path: z.string().trim().max(500).optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional()
 });
 const userFileFolderSchema = z.object({
     folder_path: z.string().trim().min(1).max(500)
@@ -850,6 +865,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 +916,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;
@@ -2891,6 +2926,9 @@ function serializeUserAttachment(c, attachment) {
         sizeBytes: attachment.sizeBytes,
         createdAt: attachment.createdAt,
         folderPath: attachment.folderPath ?? "",
+        notes: attachment.notes ?? null,
+        // Flag only — the raw vector never ships to the client (mirrors serializeClip).
+        hasNotesEmbedding: Boolean(attachment.notesEmbedding && attachment.notesEmbedding.length > 0),
         viewUrl: attachment.publicUrl || storage.getPublicUrl(attachment.storageKey) || buildUserAttachmentViewUrl(c, attachment.storageKey)
     };
 }
@@ -2918,10 +2956,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 +3078,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;
@@ -3090,7 +3144,8 @@ function buildPrimitiveEditorDocsRoutes() {
         { 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\"). 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." },
+        { 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 +3739,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."),
@@ -3932,16 +3987,19 @@ function browseFilesTextContentType(fileName) {
 }
 function createBrowseFilesTool(input) {
     return tool({
-        description: "Browse AND write the user's My Files filesystem — their personal library of uploaded assets (mp4, mov, webm, png, jpg, jpeg, gif, webp, svg, mp3, wav, m4a, aac, pdf, md, txt, csv, and more) organized into virtual folders. Use action=list to enumerate files and virtual folders so you can discover what assets exist; pass folder_path to scope the listing to one folder (omit or empty for the root). Use action=read to fetch one file by file_id (preferred; copy it from a prior list result) or by file_name: it returns the file's durable view_url plus metadata, and for text files (md, txt, csv, srt, vtt, json) it also returns the full text_content inline so you can read it. For images, video, audio, and PDFs it returns view_url only — reference that URL directly (drop it into composition layers, or pass it into primitive routes like images/edit source_image_url, videos/generate input_references, or videos/download); you cannot read their raw bytes as text. Use action=write to SAVE a text file into My Files — pass file_name (e.g. About.md), content (the full text), and optional folder_path to namescope it under a product/offer folder. This is how you persist Getting Started context the user can reuse later: a product About.md or Interview.md, and awareness-levels.md / persuasive-angles.md / ad-hooks.md distilled from brainstorm output. write only accepts text files (md, txt, csv, json, srt, vtt); to save generated images/video/audio use the primitive routes and reference their durable URLs. write returns the new file_id and view_url. Always list before you read so you use a real file_id; never invent file ids or view URLs.",
+        description: "Browse AND write the user's My Files filesystem — their personal library of uploaded assets (mp4, mov, webm, png, jpg, jpeg, gif, webp, svg, mp3, wav, m4a, aac, pdf, md, txt, csv, and more) organized into virtual folders. Use action=list to enumerate files and virtual folders so you can discover what assets exist; pass folder_path to scope the listing to one folder (omit or empty for the root). Use action=search to find files by MEANING when you don't know where something lives: pass query (plain language, e.g. 'character reference sheet for the mascot' or 'logo on transparent background') and it matches keywords AND vector-embedded metadata notes across every file's name, folder, and notes — prefer search over paging through list when My Files is large or the user references an asset vaguely. Use action=read to fetch one file by file_id (preferred; copy it from a prior list/search result) or by file_name: it returns the file's durable view_url plus metadata, and for text files (md, txt, csv, srt, vtt, json) it also returns the full text_content inline so you can read it. For images, video, audio, and PDFs it returns view_url only — reference that URL directly (drop it into composition layers, or pass it into primitive routes like images/edit source_image_url, videos/generate input_references, or videos/download); you cannot read their raw bytes as text. Use action=write to SAVE a text file into My Files — pass file_name (e.g. About.md), content (the full text), optional folder_path to namescope it under a product/offer folder, and optional notes. This is how you persist Getting Started context the user can reuse later: a product About.md or Interview.md, and awareness-levels.md / persuasive-angles.md / ad-hooks.md distilled from brainstorm output. write saves text files (md, txt, csv, json, srt, vtt) via content, or IMPORTS any media asset into the library by passing its durable URL as source_url — e.g. save a finished image job's output as character_sprite_card.png so it persists in My Files instead of living only in a job result. write returns the new file_id and view_url. Use action=annotate to set metadata notes on ANY existing file (including binary assets): notes say what the file is, who/what it depicts, and when to use it, and they are vector-embedded so future sessions can search their way back to the asset. Annotate every asset worth finding again — especially character references: keep a character_sprite_card.png plus an about_character.md per recurring character in that character's folder, annotate both, and pass the sprite card's view_url into generation reference inputs (images prompt_attachments / videos input_references) for character consistency. Always list or search before you read so you use a real file_id; never invent file ids or view URLs.",
         inputSchema: z.object({
-            action: z.enum(["list", "read", "write"]).describe("list = enumerate files and folders; read = fetch one file's view_url and, for text files, its contents; write = save a text file into My Files."),
-            folder_path: z.string().optional().describe("Folder to scope a list to, the folder of the file to read, or the folder to write into. Omit or leave empty for the root."),
-            file_id: z.string().optional().describe("Attachment id to read, copied from a prior list result. Preferred over file_name."),
-            file_name: z.string().optional().describe("File name to read when you do not have the id, or the name to save under for write (e.g. About.md). For read it is matched within folder_path when one is provided."),
-            content: z.string().optional().describe("For write: the full text content of the file to save (e.g. Markdown for About.md). Required for write; ignored otherwise."),
-            explanation: z.string().optional().describe("Short reason for the browse or save.")
+            action: z.enum(["list", "read", "write", "annotate", "search"]).describe("list = enumerate files and folders; read = fetch one file's view_url and, for text files, its contents; write = save a text file into My Files; annotate = set the metadata notes on one existing file; search = find files by meaning across names, folders, and notes."),
+            folder_path: z.string().optional().describe("Folder to scope a list or search to, the folder of the file to read, or the folder to write into. Omit or leave empty for the root."),
+            file_id: z.string().optional().describe("Attachment id to read or annotate, copied from a prior list/search result. Preferred over file_name."),
+            file_name: z.string().optional().describe("File name to read/annotate when you do not have the id, or the name to save under for write (e.g. About.md). Matched within folder_path when one is provided."),
+            content: z.string().optional().describe("For write: the full text content of the file to save (e.g. Markdown for About.md). Required for text writes; mutually exclusive with source_url."),
+            source_url: z.string().optional().describe("For write: a durable media URL (from a finished primitive job result or an existing asset) to IMPORT into My Files as file_name — this is how you save a generated character_sprite_card.png or other binary asset into the library. Mutually exclusive with content."),
+            notes: z.string().optional().describe("For annotate (required) or write (optional): metadata notes describing what the file is, who/what it depicts, and when to use it — e.g. 'Sprite card for Zara, our mascot: front/side/back views, teal jacket. Use as the reference image whenever generating Zara.' Notes are vector-embedded so search finds the file by meaning. For annotate, an empty string clears existing notes."),
+            query: z.string().optional().describe("For search: what you're looking for, in plain language. Required for search; ignored otherwise."),
+            explanation: z.string().optional().describe("Short reason for the browse, save, annotation, or search.")
         }),
-        execute: async ({ action, folder_path, file_id, file_name, content, explanation }) => {
+        execute: async ({ action, folder_path, file_id, file_name, content, source_url, notes, query, explanation }) => {
             const listUrl = new URL(`${USER_PREFIX}/me/attachments`, config.PUBLIC_BASE_URL);
             const headers = new Headers();
             headers.set("vidfarm-api-key", input.vidfarmApiKey);
@@ -3954,22 +4012,59 @@ function createBrowseFilesTool(input) {
                 if (action === "write") {
                     const name = (file_name ?? "").trim();
                     if (!name) {
-                        return { action, explanation: explanation ?? null, status: 400, error: "write requires file_name (e.g. About.md)." };
+                        return { action, explanation: explanation ?? null, status: 400, error: "write requires file_name (e.g. About.md, or character_sprite_card.png with source_url)." };
                     }
-                    if (typeof content !== "string") {
-                        return { action, explanation: explanation ?? null, status: 400, error: "write requires content (the full text of the file)." };
+                    const importSrc = (source_url ?? "").trim();
+                    let fileBlob;
+                    if (importSrc) {
+                        // Import a durable media URL (e.g. a finished primitive job's output)
+                        // into My Files. The api-key header only travels to our own origin.
+                        let sourceUrl;
+                        try {
+                            sourceUrl = new URL(importSrc, config.PUBLIC_BASE_URL);
+                        }
+                        catch {
+                            return { action, explanation: explanation ?? null, status: 400, error: `source_url is not a valid URL: ${importSrc.slice(0, 200)}` };
+                        }
+                        const sourceHeaders = new Headers();
+                        if (sourceUrl.origin === new URL(config.PUBLIC_BASE_URL).origin) {
+                            sourceHeaders.set("vidfarm-api-key", input.vidfarmApiKey);
+                        }
+                        const sourceResponse = await fetch(sourceUrl, {
+                            method: "GET",
+                            headers: sourceHeaders,
+                            signal: mergeAbortSignals(input.abortSignal, timeoutController.signal)
+                        });
+                        if (!sourceResponse.ok) {
+                            return { action, explanation: explanation ?? null, status: sourceResponse.status, error: `Could not fetch source_url (${sourceResponse.status}). Use a durable URL from a finished job result or an existing asset.` };
+                        }
+                        const sourceBytes = await sourceResponse.arrayBuffer();
+                        if (sourceBytes.byteLength > 50 * 1024 * 1024) {
+                            return { action, explanation: explanation ?? null, status: 400, error: "source_url asset is larger than the 50 MB My Files limit." };
+                        }
+                        const sourceType = (sourceResponse.headers.get("content-type") ?? "").split(";")[0].trim();
+                        fileBlob = new Blob([sourceBytes], sourceType ? { type: sourceType } : undefined);
                     }
-                    if (!isBrowseFilesTextFile(name, "")) {
-                        return { action, explanation: explanation ?? null, status: 400, error: `write only supports text files (md, txt, csv, json, srt, vtt). "${name}" is not one; save generated media via primitive routes and reference their view_url instead.` };
+                    else {
+                        if (typeof content !== "string") {
+                            return { action, explanation: explanation ?? null, status: 400, error: "write requires content (the full text of the file) or source_url (a durable media URL to import)." };
+                        }
+                        if (!isBrowseFilesTextFile(name, "")) {
+                            return { action, explanation: explanation ?? null, status: 400, error: `write with content only supports text files (md, txt, csv, json, srt, vtt). To save media like "${name}", pass its durable URL as source_url instead.` };
+                        }
+                        fileBlob = new Blob([content], { type: browseFilesTextContentType(name) });
                     }
                     const uploadUrl = new URL(`${USER_PREFIX}/me/attachments/upload`, config.PUBLIC_BASE_URL);
                     const uploadHeaders = new Headers();
                     uploadHeaders.set("vidfarm-api-key", input.vidfarmApiKey);
                     const form = new FormData();
-                    form.append("file", new Blob([content], { type: browseFilesTextContentType(name) }), name);
+                    form.append("file", fileBlob, name);
                     if (normalizedFolder) {
                         form.append("folder_path", normalizedFolder);
                     }
+                    if (typeof notes === "string" && notes.trim()) {
+                        form.append("notes", notes.trim());
+                    }
                     const writeResponse = await fetch(uploadUrl, {
                         method: "POST",
                         headers: uploadHeaders,
@@ -4004,11 +4099,65 @@ function createBrowseFilesTool(input) {
                             content_type: saved.contentType,
                             size_bytes: saved.sizeBytes,
                             folder_path: saved.folderPath ?? "",
+                            notes: saved.notes ?? null,
                             view_url: saved.viewUrl,
                             created_at: saved.createdAt
                         }
                     };
                 }
+                if (action === "search") {
+                    const q = (query ?? "").trim();
+                    if (!q) {
+                        return { action, explanation: explanation ?? null, status: 400, error: "search requires query (what you're looking for, in plain language)." };
+                    }
+                    const searchUrl = new URL(`${USER_PREFIX}/me/attachments/search`, config.PUBLIC_BASE_URL);
+                    const searchHeaders = new Headers();
+                    searchHeaders.set("vidfarm-api-key", input.vidfarmApiKey);
+                    searchHeaders.set("Content-Type", "application/json");
+                    const searchResponse = await fetch(searchUrl, {
+                        method: "POST",
+                        headers: searchHeaders,
+                        body: JSON.stringify({ query: q, ...(normalizedFolder ? { folder_path: normalizedFolder } : {}), limit: 20 }),
+                        signal: mergeAbortSignals(input.abortSignal, timeoutController.signal)
+                    });
+                    const searchText = await searchResponse.text();
+                    let searchJson = null;
+                    try {
+                        searchJson = searchText ? JSON.parse(searchText) : null;
+                    }
+                    catch {
+                        searchJson = null;
+                    }
+                    if (!searchResponse.ok || !Array.isArray(searchJson?.results)) {
+                        return {
+                            action,
+                            explanation: explanation ?? null,
+                            status: searchResponse.status,
+                            error: `My Files search failed (${searchResponse.status}). ${(searchJson?.error ?? searchText).slice(0, 500)}`
+                        };
+                    }
+                    return {
+                        action,
+                        explanation: explanation ?? null,
+                        status: 200,
+                        query: q,
+                        folder_path: normalizedFolder,
+                        semantic: Boolean(searchJson.semantic),
+                        result_count: searchJson.results.length,
+                        results: searchJson.results.map((file) => ({
+                            file_id: file.id,
+                            file_name: file.fileName,
+                            content_type: file.contentType,
+                            size_bytes: file.sizeBytes,
+                            folder_path: file.folderPath ?? "",
+                            notes: file.notes ?? null,
+                            similarity: file.similarity ?? null,
+                            keyword_match: Boolean(file.keyword_match),
+                            view_url: file.viewUrl,
+                            created_at: file.createdAt
+                        }))
+                    };
+                }
                 const listResponse = await fetch(listUrl, {
                     method: "GET",
                     headers,
@@ -4043,6 +4192,7 @@ function createBrowseFilesTool(input) {
                             content_type: file.contentType,
                             size_bytes: file.sizeBytes,
                             folder_path: file.folderPath ?? "",
+                            notes: file.notes ?? null,
                             view_url: file.viewUrl,
                             created_at: file.createdAt
                         }))
@@ -4061,7 +4211,56 @@ function createBrowseFilesTool(input) {
                         status: 404,
                         error: file_id || file_name
                             ? "No matching file in My Files. Call action=list first to copy an exact file_id."
-                            : "read requires file_id (preferred) or file_name."
+                            : `${action} requires file_id (preferred) or file_name.`
+                    };
+                }
+                if (action === "annotate") {
+                    if (typeof notes !== "string") {
+                        return { action, explanation: explanation ?? null, status: 400, error: "annotate requires notes (the metadata to attach; empty string clears)." };
+                    }
+                    const annotateUrl = new URL(`${USER_PREFIX}/me/attachments/${encodeURIComponent(match.id)}`, config.PUBLIC_BASE_URL);
+                    const annotateHeaders = new Headers();
+                    annotateHeaders.set("vidfarm-api-key", input.vidfarmApiKey);
+                    annotateHeaders.set("Content-Type", "application/json");
+                    const annotateResponse = await fetch(annotateUrl, {
+                        method: "PATCH",
+                        headers: annotateHeaders,
+                        body: JSON.stringify({ notes }),
+                        signal: mergeAbortSignals(input.abortSignal, timeoutController.signal)
+                    });
+                    const annotateText = await annotateResponse.text();
+                    let annotateJson = null;
+                    try {
+                        annotateJson = annotateText ? JSON.parse(annotateText) : null;
+                    }
+                    catch {
+                        annotateJson = null;
+                    }
+                    if (!annotateResponse.ok || !annotateJson?.attachment) {
+                        return {
+                            action,
+                            explanation: explanation ?? null,
+                            status: annotateResponse.status,
+                            error: `Could not annotate file (${annotateResponse.status}). ${(annotateJson?.error ?? annotateText).slice(0, 500)}`
+                        };
+                    }
+                    const annotated = annotateJson.attachment;
+                    return {
+                        action,
+                        explanation: explanation ?? null,
+                        status: 200,
+                        annotated: true,
+                        notes_embedded: Boolean(annotateJson.notes_embedded),
+                        file: {
+                            file_id: annotated.id,
+                            file_name: annotated.fileName,
+                            content_type: annotated.contentType,
+                            size_bytes: annotated.sizeBytes,
+                            folder_path: annotated.folderPath ?? "",
+                            notes: annotated.notes ?? null,
+                            view_url: annotated.viewUrl,
+                            created_at: annotated.createdAt
+                        }
                     };
                 }
                 const fileInfo = {
@@ -4070,6 +4269,7 @@ function createBrowseFilesTool(input) {
                     content_type: match.contentType,
                     size_bytes: match.sizeBytes,
                     folder_path: match.folderPath ?? "",
+                    notes: match.notes ?? null,
                     view_url: match.viewUrl,
                     created_at: match.createdAt
                 };
@@ -4188,8 +4388,9 @@ function createEditorActionTool() {
                 "replace_composition_html",
                 "export_composition",
                 "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."),
+                "set_captions",
+                "set_transitions"
+            ]).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. Use set_transitions to configure scene transitions across the WHOLE timeline in one call: transition = the junction preset applied at every cut (every scene clip except each track's first; 'none' clears), transition_intro = the first clip's entrance, transition_outro = the last clip's exit."),
             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."),
@@ -4222,8 +4423,12 @@ 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."),
+            transition: z.enum(["crossfade", "fade-black", "fade-white", "flash", "smoke", "blur", "slide-left", "slide-right", "slide-up", "slide-down", "whip-left", "whip-right", "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. On set_transitions it is the junction preset applied at EVERY cut. 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. Preset energy: crossfade/fade-black/fade-white/blur = calm, smoke = dreamy, slide/wipe = energetic, whip/flash = fast-paced social, 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/transition_intro."),
+            transition_out: z.enum(["fade", "fade-black", "fade-white", "flash", "smoke", "blur", "slide-left", "slide-right", "slide-up", "slide-down", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-close", "none"]).optional().describe("Exit transition OUT of this clip at its end (fade to black, slide away, ...). Set it with set_layer_media on the clip that should animate away, or seed it on add_layer/generate_layer. The animation plays over the clip's last transition_out_duration seconds; no retiming needed. Most cuts only need the incoming clip's transition — use transition_out for ending a video (fade to black), for clips followed by a gap, or for deliberate dip-to-black moments (outgoing fade-black + incoming fade-black)."),
+            transition_out_duration: z.number().optional().describe("Exit transition length in seconds, 0.1-2.5 (default 0.5). Only meaningful alongside transition_out/transition_outro."),
+            transition_intro: z.enum(["crossfade", "fade-black", "fade-white", "flash", "smoke", "blur", "slide-left", "slide-right", "slide-up", "slide-down", "whip-left", "whip-right", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-open", "none"]).optional().describe("set_transitions only: entrance for the very FIRST scene clip (fade in from black = fade-black). 'none' clears it."),
+            transition_outro: z.enum(["fade", "fade-black", "fade-white", "flash", "smoke", "blur", "slide-left", "slide-right", "slide-up", "slide-down", "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-close", "none"]).optional().describe("set_transitions only: exit for the very LAST scene clip (fade to black = fade-black). 'none' clears it."),
             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)."),
@@ -4648,7 +4853,11 @@ function rewriteHyperframesDraftCompositionHtml(html, draftPath) {
         }
     }
     // And the scene-transition keyframes: toggling data-transition on a clip
-    // must animate immediately on older stored compositions.
+    // must animate immediately on older stored compositions. Compositions that
+    // embed the V1 block get it swapped for the current one in place; if the
+    // swap misses (drifted block), the marker check below appends V2 after it,
+    // which wins by source order.
+    rewritten = upgradeLegacyTransitionCss(rewritten);
     if (!rewritten.includes(TRANSITION_STYLE_MARKER)) {
         const transitionTag = `<style data-vf-transitions="true">${TRANSITION_CSS}</style>`;
         if (/<\/head>/i.test(rewritten)) {
@@ -4864,7 +5073,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));
@@ -4976,6 +5186,7 @@ function buildTemplateHomepageEntry(template) {
         keywords: template.keywords ?? null,
         summary: template.searchSummary ?? null,
         visibility: template.visibility,
+        origin: template.origin ?? "inspiration",
         notes: template.notes,
         status: "ready"
     };
@@ -5128,6 +5339,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)
@@ -5183,6 +5395,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
@@ -5340,6 +5553,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"
     };
@@ -5701,7 +5915,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" });
@@ -6212,7 +6427,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");
     }
@@ -6351,6 +6567,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`.
@@ -8650,6 +9004,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,
@@ -8710,6 +9065,7 @@ async function finalizeInspirationIfReady(inspiration) {
                 songName: ready.songName,
                 songUrl: ready.songUrl,
                 visibility: "private",
+                origin: ready.origin ?? "inspiration",
                 notes: ready.notes
             });
             ready = (await serverlessRecords.updateInspiration({
@@ -10808,7 +11164,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,
@@ -10835,6 +11192,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>
@@ -10847,7 +11208,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>
@@ -13823,7 +14184,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)) {
@@ -14346,6 +14708,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" }));
@@ -14573,6 +14938,52 @@ app.get(`${USER_PREFIX}/me/generated-media`, async (c) => {
         next_cursor: page.nextCursor
     });
 });
+// Embedder for My Files notes — the same BYOK seam clip search uses. Prefer the
+// provider matching the embedding model the file library was built with (from
+// the newest annotated attachment) so query vectors stay cosine-comparable; a
+// fresh library takes the first embed-capable key (gemini → openai; openrouter
+// can't embed). Null (no key) fail-softs notes search to keyword-only.
+async function buildFileNotesEmbedder(customerId) {
+    const attachments = await serverlessRecords.listUserAttachments(customerId);
+    const libModel = attachments.find((a) => a.notesEmbeddingModel && Array.isArray(a.notesEmbedding) && a.notesEmbedding.length > 0)?.notesEmbeddingModel ?? null;
+    const providers = libModel ? [libModel.startsWith("text-embedding") ? "openai" : "gemini"] : ["gemini", "openai"];
+    for (const provider of providers) {
+        const apiKey = await resolveCustomerProviderKey(customerId, provider);
+        if (!apiKey)
+            continue;
+        const client = new ClipModelClient({ provider, apiKey });
+        if (client.canEmbed)
+            return client;
+    }
+    return null;
+}
+// What we embed for a My Files entry: folder + file name + the notes, so
+// "the sprite card for our mascot" is findable from any phrasing. Fail-soft:
+// no key or an embed error still saves the notes (keyword-searchable).
+async function embedAttachmentNotes(customerId, input) {
+    if (!input.notes.trim())
+        return null;
+    try {
+        const embedder = await buildFileNotesEmbedder(customerId);
+        if (!embedder?.embeddingModelId)
+            return null;
+        const text = [input.folderPath, input.fileName, input.notes].filter(Boolean).join("\n");
+        const embedding = await embedder.embedQuery(text);
+        return embedding && embedding.length > 0 ? { embedding, model: embedder.embeddingModelId } : null;
+    }
+    catch (error) {
+        devLog("attachment_notes.embed_failed", devErrorFields(error));
+        return null;
+    }
+}
+function attachmentKeywordMatch(attachment, q) {
+    const hay = `${attachment.fileName} ${attachment.folderPath ?? ""} ${attachment.notes ?? ""}`.toLowerCase();
+    return q
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean)
+        .every((term) => hay.includes(term));
+}
 app.get(`${USER_PREFIX}/me/attachments`, async (c) => {
     const customer = requireCustomer(c);
     const attachments = (await serverlessRecords.listUserAttachments(customer.id)).map((attachment) => serializeUserAttachment(c, attachment));
@@ -14651,6 +15062,7 @@ app.post(`${USER_PREFIX}/me/attachments/upload`, async (c) => {
         const fileName = sanitizeFileName(file.name || "upload.bin");
         const contentType = file.type || inferAttachmentContentType(fileName);
         const folderPath = sanitizeStorageSubpath(String(formData.get("folder_path") ?? ""));
+        const notes = String(formData.get("notes") ?? "").trim().slice(0, 4000) || null;
         if (!isAllowedAttachment(fileName, contentType)) {
             return c.json({ error: `Unsupported attachment type: ${fileName}` }, 400);
         }
@@ -14662,6 +15074,7 @@ app.post(`${USER_PREFIX}/me/attachments/upload`, async (c) => {
         const attachmentId = randomUUID();
         const storageKey = storage.userAttachmentKey(customer.id, attachmentId, fileName, folderPath);
         const stored = await storage.putBuffer(storageKey, buffer, contentType);
+        const embedded = notes ? await embedAttachmentNotes(customer.id, { fileName, folderPath, notes }) : null;
         await serverlessRecords.createUserAttachment({
             id: attachmentId,
             customerId: customer.id,
@@ -14670,7 +15083,10 @@ app.post(`${USER_PREFIX}/me/attachments/upload`, async (c) => {
             sizeBytes: buffer.byteLength,
             storageKey,
             folderPath,
-            publicUrl: stored.url || storage.getPublicUrl(storageKey) || buildUserAttachmentViewUrl(c, storageKey)
+            publicUrl: stored.url || storage.getPublicUrl(storageKey) || buildUserAttachmentViewUrl(c, storageKey),
+            notes,
+            notesEmbedding: embedded?.embedding ?? null,
+            notesEmbeddingModel: embedded?.model ?? null
         });
         const attachment = await serverlessRecords.getUserAttachment(customer.id, attachmentId);
         if (!attachment) {
@@ -14699,6 +15115,8 @@ app.post(`${USER_PREFIX}/me/attachments`, async (c) => {
         if (!isAllowedAttachment(fileName, contentType)) {
             return c.json({ error: `Unsupported attachment type: ${fileName}` }, 400);
         }
+        const notes = body.notes?.trim() || null;
+        const embedded = notes ? await embedAttachmentNotes(customer.id, { fileName, folderPath, notes }) : null;
         await serverlessRecords.createUserAttachment({
             id: body.attachment_id,
             customerId: customer.id,
@@ -14707,7 +15125,10 @@ app.post(`${USER_PREFIX}/me/attachments`, async (c) => {
             sizeBytes: body.size_bytes,
             storageKey: expectedStorageKey,
             folderPath,
-            publicUrl: storage.getPublicUrl(expectedStorageKey) || buildUserAttachmentViewUrl(c, expectedStorageKey)
+            publicUrl: storage.getPublicUrl(expectedStorageKey) || buildUserAttachmentViewUrl(c, expectedStorageKey),
+            notes,
+            notesEmbedding: embedded?.embedding ?? null,
+            notesEmbeddingModel: embedded?.model ?? null
         });
         const attachment = await serverlessRecords.getUserAttachment(customer.id, body.attachment_id);
         if (!attachment) {
@@ -14741,6 +15162,89 @@ app.patch(`${USER_PREFIX}/me/attachments/folders`, async (c) => {
     await serverlessRecords.moveUserAttachmentFolder(customer.id, fromFolder, toFolder);
     return c.json({ ok: true, from_folder_path: fromFolder, to_folder_path: toFolder });
 });
+// PATCH /me/attachments/:attachmentId — set/clear the metadata notes on one My
+// Files entry and (re)embed them for vector search. Notes are what make assets
+// findable by MEANING later — e.g. annotate a character_sprite_card.png with
+// who the character is so /me/attachments/search finds it from any phrasing.
+// (Registered after the /folders PATCH so "folders" never matches as an id.)
+app.patch(`${USER_PREFIX}/me/attachments/:attachmentId`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = userAttachmentNotesSchema.parse(await c.req.json());
+        const attachment = await serverlessRecords.getUserAttachment(customer.id, c.req.param("attachmentId"));
+        if (!attachment) {
+            return c.json({ error: "Attachment not found." }, 404);
+        }
+        const notes = (body.notes ?? "").trim() || null;
+        const embedded = notes
+            ? await embedAttachmentNotes(customer.id, { fileName: attachment.fileName, folderPath: attachment.folderPath, notes })
+            : null;
+        const updated = await serverlessRecords.updateUserAttachmentNotes(customer.id, attachment.id, {
+            notes,
+            notesEmbedding: embedded?.embedding ?? null,
+            notesEmbeddingModel: embedded?.model ?? null
+        });
+        if (!updated) {
+            return c.json({ error: "Attachment not found." }, 404);
+        }
+        return c.json({ ok: true, attachment: serializeUserAttachment(c, updated), notes_embedded: Boolean(embedded) });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Unable to update attachment notes." }, 400);
+    }
+});
+// POST /me/attachments/search — find My Files entries by meaning, mirroring
+// /clips/search: keyword filter over name/folder/notes, semantically re-ranked
+// via the notes embeddings; when nothing keyword-matches, relax to a pure
+// semantic pass. Embeddings are BYOK — no saved key fail-softs to keyword-only.
+app.post(`${USER_PREFIX}/me/attachments/search`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = userAttachmentSearchSchema.parse(await c.req.json());
+        const query = body.query.trim();
+        if (!query) {
+            return c.json({ error: "Provide a search query." }, 400);
+        }
+        const folderPath = sanitizeStorageSubpath(body.folder_path);
+        const limit = Math.max(1, Math.min(100, body.limit ?? 20));
+        const all = await serverlessRecords.listUserAttachments(customer.id);
+        const scoped = folderPath ? all.filter((a) => (a.folderPath ?? "") === folderPath) : all;
+        let queryEmbedding;
+        try {
+            const embedder = await buildFileNotesEmbedder(customer.id);
+            if (embedder)
+                queryEmbedding = await embedder.embedQuery(query);
+        }
+        catch (error) {
+            devLog("attachment_search.embed_failed", devErrorFields(error));
+        }
+        const keywordIds = new Set(scoped.filter((a) => attachmentKeywordMatch(a, query)).map((a) => a.id));
+        const pool = keywordIds.size > 0 ? scoped.filter((a) => keywordIds.has(a.id)) : scoped;
+        const hits = pool
+            .map((a) => ({
+            attachment: a,
+            keyword: keywordIds.has(a.id),
+            similarity: queryEmbedding && Array.isArray(a.notesEmbedding) && a.notesEmbedding.length > 0
+                ? cosineSimilarity(a.notesEmbedding, queryEmbedding)
+                : undefined
+        }))
+            .filter((h) => h.keyword || (h.similarity ?? 0) > 0)
+            .sort((x, y) => ((y.similarity ?? 0) + (y.keyword ? 0.2 : 0)) - ((x.similarity ?? 0) + (x.keyword ? 0.2 : 0)))
+            .slice(0, limit);
+        return c.json({
+            results: hits.map((h) => ({
+                ...serializeUserAttachment(c, h.attachment),
+                similarity: h.similarity ?? null,
+                keyword_match: h.keyword
+            })),
+            semantic: Boolean(queryEmbedding),
+            folder_path: folderPath || null
+        });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "My Files search failed." }, 400);
+    }
+});
 app.delete(`${USER_PREFIX}/me/attachments/folders`, async (c) => {
     const customer = requireCustomer(c);
     const body = userFileFolderSchema.parse(await c.req.json());
@@ -15312,25 +15816,39 @@ 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; }
       .clips-import-actions { display: flex; justify-content: flex-end; gap: 10px; }
 
-      @media (max-width: 1180px) {
+      @media (min-width: 1025px) and (max-width: 1180px) {
+        /* Rail stacks inline below the content in this band only; at ≤1024px
+           the shared shell turns the rail into the FAB + popup overlay. */
         .clips-frame { padding-left: 0; }
         .editor-right-rail { position: relative; inset: auto; width: 100%; height: 540px; margin-top: 14px; border-radius: 24px; overflow: hidden; }
         .editor-chat-panel { border-right: 0; border-radius: 24px; }
-      }
-      @media (min-width: 1025px) and (max-width: 1180px) {
         html, body { height: auto; min-height: 100%; overflow: auto; overflow-x: hidden; }
         .app-shell { height: auto; min-height: 100svh; }
         .page-stack, .frame { height: auto; min-height: 0; overflow: visible; }
         .clips-scroll { overflow: visible; padding-right: 0; }
       }
       @media (max-width: 1024px) {
+        .clips-frame { padding-left: 0; }
         .clips-shell { grid-template-rows: auto auto; }
         .clips-scroll { overflow: visible; padding-right: 0; }
+        .clips-toolbar-row { gap: 8px; }
+        .clips-search { flex: 1 1 100%; min-width: 0; }
+        .clips-search input { min-width: 0; font-size: 16px; }
+        .clips-import-form input,
+        .clips-import-form textarea,
+        .clips-import-form select { font-size: 16px; }
+      }
+      @media (max-width: 560px) {
+        .clips-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px; }
+        .clip-body { padding: 10px; }
       }
     `,
         body: `
@@ -15379,6 +15897,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>
@@ -15468,18 +16000,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();
           }
@@ -15522,16 +16094,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);
@@ -15559,9 +16136,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
@@ -15617,7 +16208,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
@@ -15677,11 +16269,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)
@@ -15837,72 +16432,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),
@@ -15924,43 +16553,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.
@@ -16006,7 +16950,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);