@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/dist/src/app.js

@@ -1,5 +1,5 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline as streamPipeline } from "node:stream/promises";
@@ -23,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";
@@ -35,7 +35,7 @@ import { resolveRootFileCandidates } from "./lib/package-root.js";
 import { stripTrackingParams } from "./lib/url-clean.js";
 import { addSeconds, nowIso } from "./lib/time.js";
 import { templateRegistry } from "./registry.js";
-import { buildEditorChatSystemInstruction, compactEditorChatModelMessages, defaultEditorChatModel, EDITOR_CHAT_PROVIDER_PRIORITY, extractEditorChatCompositionBrief, formatEditorChatCurrentDateTime, toEditorChatModelMessages } from "./editor-chat.js";
+import { buildAsyncJobHandoffText, buildEditorChatGuardrailNotice, buildEditorChatSystemInstruction, collectVerifiedHttpJobIds, compactEditorChatModelMessages, createLoadSkillTool, createStreamingJobIdRedactor, defaultEditorChatModel, EDITOR_CHAT_PROVIDER_PRIORITY, extractEditorChatCompositionBrief, formatEditorChatCurrentDateTime, lintReplaceCompositionAction, readAsyncJobHandoff, toEditorChatModelMessages } from "./editor-chat.js";
 import { apiCallHistoryStore } from "./services/api-call-history.js";
 import { AuthService } from "./services/auth.js";
 import { BillingService } from "./services/billing.js";
@@ -54,7 +54,7 @@ import { loadSpeechAudioLocally, MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES } from "./devc
 import { DescribeExecutionCommand, SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
 import { clipRecords, makeUserPreset } from "./services/clip-records.js";
 import { matchScenesToClips, searchUserClips, vectorIndex } from "./services/clip-search.js";
-import { BUILTIN_PRESETS, buildEffectiveGuidance, ClipModelClient, detectLocalAgent, effectiveHuntDurationSec, estimateScanCostFromDuration, hasFfmpeg, LocalAgentClipClient, normalizeCropFocus, normalizeHuntSpec, parseClipHuntPrompt, probeVideo, resolveDurationBand, scanVideo } from "./services/clip-curation/index.js";
+import { BUILTIN_PRESETS, buildClipEmbeddingText, 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";
@@ -401,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)
@@ -2917,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)
     };
 }
@@ -3597,7 +3609,12 @@ function normalizeEditorChatPath(input) {
         // and NEVER runs GhostCut on the long-form source — "no text" is a
         // scene-selection filter; caption removal stays a per-finished-clip
         // primitive (/api/v1/primitives/videos/remove-captions).
-        CLIPS_PREFIX
+        CLIPS_PREFIX,
+        // Public skill knowledge: the vendored skill packs (load_skill fetches
+        // these too) and per-template SKILL.md manifests. Read-only markdown.
+        "/skill/",
+        "/skill-pack/",
+        "/discover/skills/"
     ];
     const parsed = trimmed.startsWith("http://") || trimmed.startsWith("https://")
         ? new URL(trimmed)
@@ -3975,16 +3992,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);
@@ -3997,22 +4017,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,
@@ -4047,11 +4104,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,
@@ -4086,6 +4197,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
                         }))
@@ -4104,7 +4216,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 = {
@@ -4113,6 +4274,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
                 };
@@ -4231,8 +4393,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."),
@@ -4265,8 +4428,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)."),
@@ -4301,95 +4468,14 @@ function createEditorActionTool() {
             explanation: z.string().describe("One-sentence reason shown in the UI.")
         }),
         execute: async (args) => {
+            const linted = lintReplaceCompositionAction(args);
+            if (linted) {
+                return linted;
+            }
             return { ...args };
         }
     });
 }
-const JOB_ID_PATTERN = /\bjob_[a-z0-9]+\b/gi;
-const HTTP_TOOL_CLAIM_PATTERN = /\b(?:http_request|REST API call|API call|GET\s+https?:\/\/|POST\s+https?:\/\/|GET\s+\/api\/|POST\s+\/api\/)/i;
-function collectJobIdsFromUnknown(value, output = new Set()) {
-    if (typeof value === "string") {
-        for (const match of value.matchAll(JOB_ID_PATTERN)) {
-            output.add(match[0]);
-        }
-        return output;
-    }
-    if (Array.isArray(value)) {
-        for (const entry of value) {
-            collectJobIdsFromUnknown(entry, output);
-        }
-        return output;
-    }
-    if (value && typeof value === "object") {
-        for (const entry of Object.values(value)) {
-            collectJobIdsFromUnknown(entry, output);
-        }
-    }
-    return output;
-}
-function collectVerifiedHttpJobIds(toolResult) {
-    if (!toolResult || typeof toolResult !== "object") {
-        return new Set();
-    }
-    const record = toolResult;
-    return collectJobIdsFromUnknown(record.response?.body ?? record.result?.body);
-}
-function readAsyncJobHandoff(output) {
-    if (!output || typeof output !== "object") {
-        return null;
-    }
-    const record = output;
-    const body = record.response?.body;
-    if (!body || typeof body !== "object") {
-        return null;
-    }
-    const job = body;
-    if (typeof job.job_id !== "string" || typeof job.status !== "string") {
-        return null;
-    }
-    if (job.status === "succeeded" || job.status === "failed" || job.status === "cancelled") {
-        return null;
-    }
-    return {
-        jobId: job.job_id,
-        tracer: typeof job.tracer === "string" ? job.tracer : null,
-        status: job.status,
-        isNewQueuedJob: record.request?.method === "POST" && record.response?.status === 202
-    };
-}
-function buildAsyncJobHandoffText(input) {
-    if (!input.isNewQueuedJob) {
-        return `Render \`${input.jobId}\` is ${input.status}.`;
-    }
-    return [
-        `Started render \`${input.jobId}\`${input.tracer ? ` with tracer \`${input.tracer}\`` : ""}.`,
-        "If it takes a while, ask for an update later and I can check it for you."
-    ].join("\n\n");
-}
-function buildEditorChatGuardrailNotice(input) {
-    const mentionedJobIds = collectJobIdsFromUnknown(input.assistantText);
-    const unverifiedJobIds = [...mentionedJobIds].filter((jobId) => !input.verifiedJobIds.has(jobId));
-    const notices = [];
-    if (input.redactedJobIds.size) {
-        notices.push("Guardrail: I withheld unverified job ID text because it did not come from a visible HTTP response card.");
-    }
-    else if (unverifiedJobIds.length) {
-        notices.push("Guardrail: I mentioned an unverified job ID. Ignore it unless it appears in a visible HTTP response card.");
-    }
-    if (!input.hasHttpRequestResult && HTTP_TOOL_CLAIM_PATTERN.test(input.assistantText)) {
-        notices.push("Guardrail: no `http_request` tool result was recorded for this response, so any claimed REST/API call should be treated as not executed.");
-    }
-    return notices.length ? `\n\n${notices.join("\n\n")}` : "";
-}
-function redactUnverifiedJobIds(input) {
-    return input.text.replace(JOB_ID_PATTERN, (jobId) => {
-        if (input.verifiedJobIds.has(jobId)) {
-            return jobId;
-        }
-        input.redactedJobIds.add(jobId);
-        return "[unverified job id]";
-    });
-}
 function normalizeHistoryAttachments(attachments) {
     return Array.isArray(attachments)
         ? attachments.map((attachment) => ({
@@ -4433,6 +4519,10 @@ async function streamEditorChatAgent(input, send) {
                     vidfarmApiKey: input.vidfarmApiKey,
                     abortSignal: input.abortSignal
                 }),
+                load_skill: createLoadSkillTool({
+                    publicBaseUrl: config.PUBLIC_BASE_URL,
+                    abortSignal: input.abortSignal
+                }),
                 frontend_action: createEditorFrontendActionTool({
                     tracerRegistry
                 }),
@@ -4459,6 +4549,7 @@ async function streamEditorChatAgent(input, send) {
     let hasHttpRequestResult = false;
     const verifiedJobIds = new Set();
     const redactedJobIds = new Set();
+    const jobIdRedactor = createStreamingJobIdRedactor({ verifiedJobIds, redactedJobIds });
     const toolExchangeOrder = [];
     const toolExchangeMap = new Map();
     const httpExchanges = [];
@@ -4473,16 +4564,14 @@ async function streamEditorChatAgent(input, send) {
             case "text-delta":
                 assistantTextForAudit += part.text;
                 {
-                    const safeText = redactUnverifiedJobIds({
-                        text: part.text,
-                        verifiedJobIds,
-                        redactedJobIds
-                    });
-                    assistantTextForUser += safeText;
-                    send({
-                        type: "text-delta",
-                        delta: safeText
-                    });
+                    const safeText = jobIdRedactor.push(part.text);
+                    if (safeText) {
+                        assistantTextForUser += safeText;
+                        send({
+                            type: "text-delta",
+                            delta: safeText
+                        });
+                    }
                 }
                 break;
             case "tool-call":
@@ -4576,6 +4665,14 @@ async function streamEditorChatAgent(input, send) {
                 break;
             case "finish":
                 {
+                    const heldText = jobIdRedactor.flush();
+                    if (heldText) {
+                        assistantTextForUser += heldText;
+                        send({
+                            type: "text-delta",
+                            delta: heldText
+                        });
+                    }
                     const guardrailNotice = buildEditorChatGuardrailNotice({
                         assistantText: assistantTextForAudit,
                         verifiedJobIds,
@@ -4691,7 +4788,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)) {
@@ -5511,21 +5612,193 @@ const PUBLIC_SKILL_FILES = {
     "vidfarm-director": "SKILL.director.md",
     "vidfarm-platform": "SKILL.platform.md"
 };
+// Vendored skill packs (the heygen-scrubbed hyperframes pack + vidfarm-media)
+// mirrored from .agents/skills. Vidfarm is the distribution origin: the devcli
+// (`vidfarm skills add`) and the chat copilot's load_skill tool both pull from
+// these routes, so customers never fetch skills from an upstream vendor org.
+const SKILL_PACK_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,64}$/;
+const SKILL_PACK_IGNORED_ENTRIES = new Set([".DS_Store", "node_modules", ".git"]);
+function resolveSkillPackDir(name) {
+    if (!SKILL_PACK_NAME_PATTERN.test(name)) {
+        return null;
+    }
+    for (const candidate of resolveRootFileCandidates(path.join(".agents", "skills", name))) {
+        try {
+            if (statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function listSkillPackFiles(dir, prefix = "") {
+    const files = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (SKILL_PACK_IGNORED_ENTRIES.has(entry.name)) {
+            continue;
+        }
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const absolute = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listSkillPackFiles(absolute, relative));
+        }
+        else if (entry.isFile()) {
+            files.push(relative);
+        }
+    }
+    return files.sort();
+}
+function readSkillPackDescription(dir) {
+    try {
+        const skillMd = readFileSync(path.join(dir, "SKILL.md"), "utf8");
+        const match = skillMd.match(/^description:\s*(.+)$/m);
+        return match ? match[1].trim().slice(0, 300) : "";
+    }
+    catch {
+        return "";
+    }
+}
 app.get("/skill/:name", (c) => {
     const name = c.req.param("name").replace(/\.md$/i, "");
     const filename = PUBLIC_SKILL_FILES[name];
-    if (!filename) {
-        return c.text("Unknown skill", 404);
-    }
-    const contents = readRootSkillFile(filename);
+    const contents = filename
+        ? readRootSkillFile(filename)
+        : (() => {
+            const packDir = resolveSkillPackDir(name);
+            if (!packDir) {
+                return "";
+            }
+            try {
+                return readFileSync(path.join(packDir, "SKILL.md"), "utf8");
+            }
+            catch {
+                return "";
+            }
+        })();
     if (!contents) {
-        return c.text("Skill file unavailable", 404);
+        return c.text(filename ? "Skill file unavailable" : "Unknown skill", 404);
     }
     return c.body(contents, 200, {
         "content-type": "text/markdown; charset=utf-8",
         "cache-control": "no-cache"
     });
 });
+app.get("/skill-pack/index.json", (c) => {
+    const skills = [];
+    for (const candidate of resolveRootFileCandidates(path.join(".agents", "skills"))) {
+        let entries;
+        try {
+            entries = readdirSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.sort()) {
+            if (!SKILL_PACK_NAME_PATTERN.test(entry) || skills.some((skill) => skill.name === entry)) {
+                continue;
+            }
+            const dir = path.join(candidate, entry);
+            try {
+                if (!statSync(dir).isDirectory()) {
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            skills.push({ name: entry, description: readSkillPackDescription(dir) });
+        }
+        break;
+    }
+    return c.json({ skills });
+});
+// Manifest hashing reads every file in a pack (hyperframes-animation alone is
+// ~100 files) — memoize per pack dir, invalidated by a cheap stat signature,
+// so `vidfarm skills update` sweeps don't re-hash 5MB per request.
+const skillPackManifestCache = new Map();
+app.get("/skill-pack/:name/manifest.json", (c) => {
+    const packDir = resolveSkillPackDir(c.req.param("name"));
+    if (!packDir) {
+        return c.json({ error: "Unknown skill pack." }, 404);
+    }
+    const relativePaths = listSkillPackFiles(packDir);
+    const signature = relativePaths
+        .map((relative) => {
+        try {
+            const stats = statSync(path.join(packDir, relative));
+            return `${relative}:${stats.size}:${stats.mtimeMs}`;
+        }
+        catch {
+            return `${relative}:missing`;
+        }
+    })
+        .join("|");
+    const cached = skillPackManifestCache.get(packDir);
+    if (cached && cached.signature === signature) {
+        return c.json(cached.manifest);
+    }
+    const files = relativePaths.map((relative) => {
+        const bytes = readFileSync(path.join(packDir, relative));
+        return {
+            path: relative,
+            size: bytes.length,
+            sha256: createHash("sha256").update(bytes).digest("hex")
+        };
+    });
+    const manifest = { name: path.basename(packDir), files };
+    skillPackManifestCache.set(packDir, { signature, manifest });
+    return c.json(manifest);
+});
+app.get("/skill-pack/:name/files/*", (c) => {
+    const packDir = resolveSkillPackDir(c.req.param("name"));
+    if (!packDir) {
+        return c.text("Unknown skill pack.", 404);
+    }
+    const marker = "/files/";
+    const rawPath = c.req.path.slice(c.req.path.indexOf(marker) + marker.length);
+    let relative;
+    try {
+        relative = rawPath
+            .split("/")
+            .map((segment) => decodeURIComponent(segment))
+            .join("/");
+    }
+    catch {
+        return c.text("Bad file path.", 400);
+    }
+    const resolved = path.resolve(packDir, relative);
+    if (resolved !== packDir && !resolved.startsWith(packDir + path.sep)) {
+        return c.text("Bad file path.", 400);
+    }
+    let bytes;
+    try {
+        bytes = readFileSync(resolved);
+    }
+    catch {
+        return c.text("File not found.", 404);
+    }
+    const ext = path.extname(resolved).toLowerCase();
+    const contentType = ext === ".md" || ext === ".markdown" ? "text/markdown; charset=utf-8"
+        : ext === ".json" ? "application/json; charset=utf-8"
+            : ext === ".mjs" || ext === ".cjs" || ext === ".js" ? "text/javascript; charset=utf-8"
+                : ext === ".html" ? "text/html; charset=utf-8"
+                    : ext === ".css" ? "text/css; charset=utf-8"
+                        : ext === ".txt" || ext === ".srt" || ext === ".vtt" || ext === ".sh" || ext === ".yaml" || ext === ".yml" ? "text/plain; charset=utf-8"
+                            : ext === ".png" ? "image/png"
+                                : ext === ".avif" ? "image/avif"
+                                    : ext === ".webp" ? "image/webp"
+                                        : ext === ".jpg" || ext === ".jpeg" ? "image/jpeg"
+                                            : ext === ".mp3" ? "audio/mpeg"
+                                                : ext === ".woff2" ? "font/woff2"
+                                                    : "application/octet-stream";
+    return c.body(new Uint8Array(bytes), 200, {
+        "content-type": contentType,
+        "cache-control": "no-cache"
+    });
+});
 if (config.SENTRY_DEBUG_ROUTE === "true") {
     app.get("/debug-sentry", () => {
         Sentry.logger.info("User triggered test error", {
@@ -6435,7 +6708,13 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/captions`, async (c) => {
         const text = str("text");
         if (text) {
             const windowStart = Math.max(0, num("start") ?? 0);
-            const windowDuration = num("duration") ?? Math.max(0.4, compositionDuration - windowStart);
+            const availableWindow = compositionDuration - windowStart;
+            // When the composition declares no usable window (missing data-duration,
+            // or windowStart at/after the end), fall back to a word-count estimate
+            // (~0.32s/word, same as the /audio/captions primitive) instead of
+            // cramming the whole script into a 0.4s window of overlapping cues.
+            const estimatedWindow = Math.max(0.4, text.trim().split(/\s+/).filter(Boolean).length * 0.32);
+            const windowDuration = num("duration") ?? (availableWindow > 0.4 ? availableWindow : estimatedWindow);
             cues = cuesFromText(text, windowStart + offsetSec, windowDuration, { maxWordsPerCue: maxWords });
             sourceNote = "text";
         }
@@ -14772,6 +15051,77 @@ app.get(`${USER_PREFIX}/me/generated-media`, async (c) => {
         next_cursor: page.nextCursor
     });
 });
+// OpenAI's embedding models are named text-embedding-3-* / text-embedding-ada-*;
+// Gemini's family INCLUDES text-embedding-004 (plus gemini-embedding-*), so a
+// bare startsWith("text-embedding") misroutes a Gemini-built library to OpenAI
+// and returns cross-space (garbage) cosine scores. Match the OpenAI naming
+// precisely; everything else is gemini.
+function inferEmbeddingProviderFromModel(model) {
+    return model && /^text-embedding-(3|ada)/i.test(model) ? "openai" : "gemini";
+}
+// Embed-capable client for populating/searching a clip library. Matches the
+// library's existing embedding space when one exists (so vectors stay
+// cosine-comparable); otherwise takes the first embed-capable saved key
+// (gemini → openai; openrouter can't embed). Null → no key, keyword-only.
+async function buildClipLibraryEmbedder(customerId) {
+    const existing = await clipRecords.getLibraryEmbeddingModel(customerId);
+    const providers = existing ? [inferEmbeddingProviderFromModel(existing)] : ["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;
+}
+// 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 ? [inferEmbeddingProviderFromModel(libModel)] : ["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));
@@ -14850,6 +15200,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);
         }
@@ -14861,6 +15212,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,
@@ -14869,7 +15221,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) {
@@ -14898,6 +15253,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,
@@ -14906,7 +15263,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) {
@@ -14940,6 +15300,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());
@@ -15519,20 +15962,31 @@ function renderClipsPage(input) {
       .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: `
@@ -15846,7 +16300,7 @@ async function pickClipProviderFromKeys(customerId) {
  */
 async function buildMatchEmbedder(customerId) {
     const libModel = await clipRecords.getLibraryEmbeddingModel(customerId);
-    const provider = libModel && libModel.startsWith("text-embedding") ? "openai" : "gemini";
+    const provider = inferEmbeddingProviderFromModel(libModel);
     const key = await resolveCustomerProviderKey(customerId, provider);
     if (!key)
         return null;
@@ -16216,29 +16670,54 @@ app.post(`${CLIPS_PREFIX}/scan`, async (c) => {
             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),
-                input: JSON.stringify({
-                    scan_id: scanId,
-                    owner_id: customer.id,
-                    source_video_id: sourceVideoId,
-                    source_filename: filename,
-                    raw_s3_uri: rawS3Uri ?? "",
-                    tier,
-                    provider,
-                    tag_api_key: tagApiKey,
-                    embedding_provider: client.embeddingProvider ?? "",
-                    embedding_api_key: embeddingKey ?? "",
-                    guidance_prompt: guidancePrompt,
-                    frames_per_scene: framesPerScene,
-                    include_audio: includeAudio,
-                    hunt_spec: huntSpec,
-                    tracer
-                })
-            }));
-            await putScanRecords({ scanStatus: "running", executionArn: res.executionArn });
-            return scanResponse({ status: "running", executionArn: res.executionArn, pipeline: "cloud", estimate, computeEstimate });
+            // Records first: a Dynamo failure here aborts submission before anything
+            // is billed, and the warm probe lambda's later status:"scanning" write is
+            // never clobbered back to "pending" by a post-start putScanRecords.
+            await putScanRecords({ scanStatus: "running" });
+            let executionArn;
+            try {
+                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),
+                    input: JSON.stringify({
+                        scan_id: scanId,
+                        owner_id: customer.id,
+                        source_video_id: sourceVideoId,
+                        source_filename: filename,
+                        raw_s3_uri: rawS3Uri ?? "",
+                        tier,
+                        provider,
+                        tag_api_key: tagApiKey,
+                        embedding_provider: client.embeddingProvider ?? "",
+                        embedding_api_key: embeddingKey ?? "",
+                        guidance_prompt: guidancePrompt,
+                        frames_per_scene: framesPerScene,
+                        include_audio: includeAudio,
+                        hunt_spec: huntSpec,
+                        tracer
+                    })
+                }));
+                executionArn = res.executionArn;
+            }
+            catch (error) {
+                // The execution never started — roll the scan (and its source) to failed
+                // so pollers do not spin on a "running" record that will never progress,
+                // mirroring the lazy-reconcile failure path.
+                const orphan = await clipRecords.getScan(customer.id, scanId);
+                if (orphan)
+                    await clipRecords.putScan({ ...orphan, status: "failed", error: "Failed to start the scan pipeline.", updated_at: nowIso() });
+                const orphanSource = await clipRecords.getSource(customer.id, sourceVideoId);
+                if (orphanSource && orphanSource.status !== "complete")
+                    await clipRecords.putSource({ ...orphanSource, status: "failed", updated_at: nowIso() });
+                throw error;
+            }
+            // Attach the execution ARN for lazy SFN reconciliation (best-effort — the
+            // record is already pollable; spread the current record so a runner that
+            // has already advanced the status is not regressed).
+            const startedScan = await clipRecords.getScan(customer.id, scanId);
+            if (startedScan)
+                await clipRecords.putScan({ ...startedScan, execution_arn: executionArn, updated_at: nowIso() });
+            return scanResponse({ status: "running", 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
@@ -16540,6 +17019,11 @@ async function mirrorUpstreamClipsToLocal(input) {
     if (!feed.ok || !feed.json)
         throw new Error(`Upstream clip feed unavailable (HTTP ${feed.status}).`);
     let stored = 0;
+    // Upstream /clips/feed strips the embedding vector, so re-embed each mirrored
+    // clip on the owner's BYOK key — otherwise it lands with no embedding and is
+    // permanently invisible to semantic clip search (keyword-only). Fail-soft:
+    // no embed-capable key → store without embedding (keyword-only), as before.
+    const embedder = await buildClipLibraryEmbedder(ownerId);
     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;
@@ -16559,16 +17043,32 @@ async function mirrorUpstreamClipsToLocal(input) {
                 await storage.putBuffer(thumbKey, new Uint8Array(await thumbRes.arrayBuffer()), "image/jpeg");
             }
         }
-        const { view_url: _v, thumbnail_url: _t, ...rest } = raw;
+        const { view_url: _v, thumbnail_url: _t, embedding: _e, embedding_model: _em, ...rest } = raw;
         void _v;
         void _t;
-        await clipRecords.putClip({
+        void _e;
+        void _em;
+        const clip = {
             ...rest,
             owner_id: ownerId,
             source_video_id: scan.source_video_id,
             file_path: clipKey,
             thumbnail_path: thumbKey
-        });
+        };
+        if (embedder?.embeddingModelId) {
+            try {
+                const [vector] = await embedder.embedDocuments([buildClipEmbeddingText(clip.tags, clip.description)]);
+                if (vector?.length) {
+                    clip.embedding = vector;
+                    clip.embedding_model = embedder.embeddingModelId;
+                }
+            }
+            catch (error) {
+                devLog("clip_scan.upstream_mirror_embed_failed", { scan_id: scan.scan_id, clip_id: clipId, ...devErrorFields(error) }, "warn");
+            }
+        }
+        await clipRecords.putClip(clip);
+        await vectorIndex.upsert(ownerId, clip);
         stored++;
     }
     const source = await clipRecords.getSource(ownerId, scan.source_video_id);