@mevdragon/vidfarm-devcli 0.14.0 → 0.16.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";
@@ -22,6 +22,7 @@ import { assertForkAccess, resolveForkAccess, ForkAccessDeniedError, ForkNotFoun
 import { writeForkManifest } from "./services/fork-manifest.js";
 import { renderHelpPage } from "./help-page.js";
 import { renderHomepage } from "./homepage.js";
+import { POPULAR_INSPIRATION_GROUPS } from "./frontend/homepage-shared.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, upgradeLegacyTransitionCss } from "./hyperframes/composition.js";
 import { normalizeCompositionZIndexHtml, sanitizeCompositionHtml } from "./services/composition-sanitize.js";
@@ -35,7 +36,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,12 +55,12 @@ 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, cosineSimilarity, 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";
 import { buildPendingCastState, castMemberFromRaw, extractCastStill, isolateCastMember } from "./services/cast.js";
-import { MediaDurationExceededError, probeMediaAsset } from "./services/media-processing.js";
+import { MediaDurationExceededError, probeMediaAsset, trimVideoAsset } from "./services/media-processing.js";
 import { estimateGhostcutCostUsd, isGhostcutConfigured, mirrorGhostcutVideoToStorage, pollStatus as pollGhostcutStatus, submitSubtitleRemoval } from "./services/ghostcut.js";
 import { hasUpstreamKey, isUpstreamEnabled, proxyRequestToUpstream, seedFromUpstream, upstreamHost, upstreamJson } from "./services/upstream.js";
 import { TemplateSourceService } from "./services/template-sources.js";
@@ -3609,7 +3610,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)
@@ -4463,95 +4469,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) => ({
@@ -4595,6 +4520,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
                 }),
@@ -4621,6 +4550,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 = [];
@@ -4635,16 +4565,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":
@@ -4738,6 +4666,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,
@@ -5002,6 +4938,28 @@ app.get("/editor/:templateId", async (c) => {
         if (!forkRecord || forkRecord.deletedAt) {
             effectiveForkParam = null;
         }
+        else if (customer) {
+            // A caller who can VIEW but not EDIT this fork (e.g. a public template's
+            // default fork opened via a shared deep link) must not be pinned onto it:
+            // the editor would happily let them "edit", but every composition.html PUT
+            // is 403'd and the change silently reverts on reload — the exact "the AI
+            // said it changed the text but it didn't" failure. Drop the fork and fall
+            // through to per-user resolution so they get (or mint) their own editable
+            // copy instead.
+            try {
+                const access = await resolveForkAccess({
+                    forkId: effectiveForkParam,
+                    customerId: customer.id,
+                    shareToken: readShareToken(c) ?? undefined
+                });
+                if (!access.capabilities.canEdit) {
+                    effectiveForkParam = null;
+                }
+            }
+            catch {
+                effectiveForkParam = null;
+            }
+        }
     }
     if (!effectiveForkParam) {
         // Per-user default fork resolution: prefer caller's most-recently-updated
@@ -5018,8 +4976,14 @@ app.get("/editor/:templateId", async (c) => {
             if (mostRecent)
                 targetForkId = mostRecent.id;
         }
-        if (!targetForkId)
+        // Only fall back to the template's canonical default fork when the caller can
+        // actually edit it — i.e. they own the template. A non-owner sent to the
+        // default fork would land back on a read-only fork (and, since it's also the
+        // page we just dropped, loop). Leaving targetForkId null routes them to the
+        // bare editor, where the client mints their own editable fork on first save.
+        if (!targetForkId && template.customerId === customer?.id) {
             targetForkId = template.defaultForkId;
+        }
         if (targetForkId) {
             // Do NOT auto-attach a thread_id here: the caller's browser is the
             // source of truth for "which chat is active" via localStorage. Injecting
@@ -5127,6 +5091,11 @@ app.get("/discover/feed", async (c) => {
     }
     const templates = await serverlessRecords.listTemplatesFeed({ limit, query });
     for (const template of templates) {
+        // Curated "Popular" picks live only under the Popular toggle
+        // (GET /discover/popular) — keep them out of the continuously-grown Feed
+        // so the two views stay distinct.
+        if (typeof template.popularGroup === "string" && template.popularGroup.trim().length > 0)
+            continue;
         const entry = buildTemplateHomepageEntry(template);
         if (entry)
             templateEntries.push(entry);
@@ -5143,7 +5112,7 @@ app.get("/discover/feed", async (c) => {
         const upstreamFeed = (await upstreamJson(`/discover/feed?${search.toString()}`)).json?.templates ?? [];
         const seen = new Set(templateEntries.map((entry) => entry.templateId));
         for (const entry of upstreamFeed) {
-            if (entry && typeof entry.templateId === "string" && !seen.has(entry.templateId)) {
+            if (entry && typeof entry.templateId === "string" && !seen.has(entry.templateId) && !entry.popularGroup) {
                 templateEntries.push(entry);
                 seen.add(entry.templateId);
             }
@@ -5158,16 +5127,60 @@ app.get("/discover/feed", async (c) => {
         next_cursor: null
     });
 });
+// Curated "Popular" feed: the editorial list surfaced under the /discover
+// Popular toggle. Same template records as Feed, just the ones flagged with a
+// popularGroup — rendered client-side as autoplay TemplateCards grouped by that
+// label. Public + identical for everyone, so it caches shared. Mirrors upstream
+// (vidfarm serve) exactly like /discover/feed so a locally-empty box still sees
+// the cloud-seeded picks. Seed with POST /api/v1/admin/popular/seed.
+app.get("/discover/popular", async (c) => {
+    const templateEntries = [];
+    const seen = new Set();
+    const popular = await serverlessRecords.listPopularTemplates();
+    for (const template of popular) {
+        const entry = buildTemplateHomepageEntry(template);
+        if (entry) {
+            templateEntries.push(entry);
+            seen.add(entry.templateId);
+        }
+    }
+    if (isUpstreamEnabled()) {
+        const upstream = (await upstreamJson(`/discover/popular`)).json?.templates ?? [];
+        for (const entry of upstream) {
+            if (entry && typeof entry.templateId === "string" && !seen.has(entry.templateId) && entry.popularGroup) {
+                templateEntries.push(entry);
+                seen.add(entry.templateId);
+            }
+        }
+    }
+    // Stable editorial order: popularRank is a global sequence assigned by the
+    // seed (group index * 1000 + item index), so a plain rank sort preserves both
+    // group order and within-group order. Group label is only a tiebreak.
+    templateEntries.sort((a, b) => {
+        const rankCompare = (a.popularRank ?? 0) - (b.popularRank ?? 0);
+        if (rankCompare !== 0)
+            return rankCompare;
+        return String(a.popularGroup ?? "").localeCompare(String(b.popularGroup ?? ""));
+    });
+    c.header("cache-control", "public, max-age=60");
+    return c.json({
+        templates: templateEntries,
+        next_cursor: null
+    });
+});
 function buildTemplateHomepageEntry(template) {
     // Undecomposed templates (no defaultForkId yet) still appear on /discover so
     // users can open them and mint the first fork via the Decompose modal.
     if (!template.videoUrl)
         return null;
     const isPrivate = template.visibility === "private";
+    const isPopular = typeof template.popularGroup === "string" && template.popularGroup.trim().length > 0;
     // Older records stored the source host ("youtube.com") as a title fallback —
     // never show that as a card title; the template id is the canonical default.
     const storedTitle = template.title && template.title !== template.sourceHost ? template.title : null;
-    const title = isPrivate ? (storedTitle || template.id) : template.id;
+    // Public feed cards default to the template id, but curated Popular picks show
+    // their editorial title (the whole point of the Popular list).
+    const title = (isPrivate || isPopular) ? (storedTitle || template.id) : template.id;
     const previewUrl = template.thumbnailUrl || template.videoUrl || null;
     return {
         title,
@@ -5187,6 +5200,8 @@ function buildTemplateHomepageEntry(template) {
         summary: template.searchSummary ?? null,
         visibility: template.visibility,
         origin: template.origin ?? "inspiration",
+        popularGroup: template.popularGroup ?? null,
+        popularRank: template.popularRank ?? null,
         notes: template.notes,
         status: "ready"
     };
@@ -5554,6 +5569,8 @@ function buildPendingInspirationHomepageEntry(inspiration) {
         durationSeconds: inspiration.durationSeconds ?? null,
         visibility: "private",
         origin: inspiration.origin ?? "inspiration",
+        popularGroup: inspiration.popularGroup ?? null,
+        popularRank: inspiration.popularRank ?? null,
         notes: inspiration.notes,
         status: inspiration.status === "failed" ? "failed" : "processing"
     };
@@ -5677,21 +5694,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", {
@@ -6601,7 +6790,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";
         }
@@ -7018,6 +7213,13 @@ app.post(`${INSPIRATIONS_PREFIX}/:inspirationId/decompose`, async (c) => {
 // so a forced re-run may start. Must exceed the longest real decompose but stay
 // under the API lambda's 15-min timeout.
 const DECOMPOSE_PROCESSING_STALE_MS = 10 * 60 * 1000;
+// Inspiration ingest + auto-decompose no longer hard-cap the source at 120s.
+// Users can bring longer inspiration; an operator can still re-impose a ceiling
+// via INSPIRATION_MAX_DURATION_SEC (>0). 0 → unlimited, translated to Infinity so
+// probeMediaAsset never rejects a source purely on length.
+const INSPIRATION_PROBE_MAX_DURATION_SECONDS = config.INSPIRATION_MAX_DURATION_SEC > 0
+    ? config.INSPIRATION_MAX_DURATION_SEC
+    : Number.POSITIVE_INFINITY;
 async function readDecomposeJobState(forkId) {
     const text = await storage.readText(storage.compositionForkWorkingKey(forkId, "decompose.json"));
     if (!text)
@@ -7137,7 +7339,10 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
         let probedDurationSeconds = null;
         if (sourceUrl) {
             try {
-                const probe = await probeMediaAsset({ sourceUrl });
+                const probe = await probeMediaAsset({
+                    sourceUrl,
+                    maxDurationSeconds: INSPIRATION_PROBE_MAX_DURATION_SECONDS
+                });
                 const probed = probe.metadata.durationSeconds;
                 if (Number.isFinite(probed) && probed && probed > 0) {
                     probedDurationSeconds = probed;
@@ -7185,7 +7390,17 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
             ghostcutSkipReason = "ghostcut_not_configured";
             console.warn(`ghostcut: skipping subtitle removal for fork ${fork.id} — GHOSTCUT_KEY/GHOSTCUT_SECRET not configured. Composition will keep the original video with baked-in text.`);
         }
-        if (sourceUrl && sourceIsVideo && isGhostcutConfigured()) {
+        else if (config.GHOSTCUT_DECOMPOSE_MAX_DURATION_SEC > 0 &&
+            probedDurationSeconds !== null &&
+            probedDurationSeconds > config.GHOSTCUT_DECOMPOSE_MAX_DURATION_SEC) {
+            // GhostCut is per-30s-chunk and meant for short clips. Long inspiration is
+            // now allowed through ingest/decompose, but laundering a multi-minute video
+            // through GhostCut is disproportionately expensive — skip it and keep the
+            // original burned-in captions instead.
+            ghostcutSkipReason = `source_too_long:${probedDurationSeconds.toFixed(1)}s>${config.GHOSTCUT_DECOMPOSE_MAX_DURATION_SEC}s`;
+            console.warn(`ghostcut: skipping subtitle removal for fork ${fork.id} — source is ${probedDurationSeconds.toFixed(1)}s, over the ${config.GHOSTCUT_DECOMPOSE_MAX_DURATION_SEC}s decompose ceiling. Composition keeps the original burned-in captions.`);
+        }
+        if (sourceUrl && sourceIsVideo && isGhostcutConfigured() && !ghostcutSkipReason) {
             try {
                 const submission = await submitSubtitleRemoval(sourceUrl);
                 ghostcutTaskId = submission.taskId;
@@ -9005,6 +9220,8 @@ function serializeInspiration(inspiration) {
         summary: inspiration.searchSummary ?? null,
         visibility: inspiration.visibility ?? "public",
         origin: inspiration.origin ?? "inspiration",
+        popular_group: inspiration.popularGroup ?? null,
+        popular_rank: inspiration.popularRank ?? null,
         notes: inspiration.notes ?? null,
         ingester_customer_id: inspiration.customerId,
         error: inspiration.errorMessage,
@@ -11109,7 +11326,10 @@ async function ensureInspirationReadyThenFork(input) {
     // the true length instead of a placeholder.
     if (!inspiration.durationSeconds) {
         try {
-            const probe = await probeMediaAsset({ sourceUrl: inspiration.videoUrl });
+            const probe = await probeMediaAsset({
+                sourceUrl: inspiration.videoUrl,
+                maxDurationSeconds: INSPIRATION_PROBE_MAX_DURATION_SECONDS
+            });
             const probedDuration = probe.metadata.durationSeconds;
             if (Number.isFinite(probedDuration) && probedDuration && probedDuration > 0) {
                 inspiration = (await serverlessRecords.updateInspiration({
@@ -11188,6 +11408,205 @@ function buildTemplateEditorUrl(publicBaseUrl, templateId) {
     const path = `/editor/${encodeURIComponent(templateId)}`;
     return publicBaseUrl ? `${publicBaseUrl.replace(/\/$/, "")}${path}` : path;
 }
+// Curated Popular picks are short-form: a source longer than the 120s ingest
+// limit is clipped to this many seconds (kept safely under 120 for the probe).
+const POPULAR_MAX_CLIP_SEC = 115;
+// Seed the curated "Popular" catalog from POPULAR_INSPIRATION_GROUPS: ingest
+// each URL once into a real PUBLIC template (same path as admin TikTok
+// submissions) and stamp it with the editorial title + popularGroup +
+// popularRank so it always shows under the /discover Popular toggle and
+// autoplays inline exactly like a Feed card. Over-length sources are clipped to
+// POPULAR_MAX_CLIP_SEC. Idempotent — find-or-create by URL, then (re)stamp.
+// Requires RAPIDAPI_KEY (the download primitive), so run this on staging/prod.
+app.post(`${API_PREFIX}/admin/popular/seed`, async (c) => {
+    try {
+        requireSuperagency(c);
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Forbidden" }, 403);
+    }
+    const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
+    const requestedOwnerEmail = readNonEmptyString(body.owner_email)?.trim().toLowerCase();
+    const ownerEmail = requestedOwnerEmail ?? config.adminEmails[0]?.trim().toLowerCase();
+    if (!ownerEmail)
+        return c.json({ error: "No owner_email supplied and no admin email configured." }, 400);
+    const ownerCustomer = await serverlessRecords.getCustomerByEmail(ownerEmail);
+    if (!ownerCustomer)
+        return c.json({ error: `Owner not found: ${ownerEmail}` }, 404);
+    const primitive = primitiveRegistry.get("primitive:video_download");
+    if (!primitive)
+        return c.json({ error: "video_download primitive missing" }, 500);
+    const operation = primitive.operations["run"];
+    if (!operation)
+        return c.json({ error: "video_download.run missing" }, 500);
+    const publicBaseUrl = config.PUBLIC_BASE_URL?.trim() || "";
+    try {
+        await assertWalletCanQueueJobs(ownerCustomer.id);
+    }
+    catch (error) {
+        if (error instanceof InsufficientWalletFundsError)
+            return insufficientFundsResponse(c, error);
+        throw error;
+    }
+    // Flatten the manifest into one ranked list. popularRank is a global sequence
+    // (group index * 1000 + item index) so a plain rank sort restores both the
+    // group order and the order within each group.
+    const allItems = POPULAR_INSPIRATION_GROUPS.flatMap((group, gi) => group.items.map((item, ri) => ({ title: item.title, url: item.url, group: group.label, rank: gi * 1000 + ri })));
+    // Optional { groups: [...] } filter seeds one category at a time so a large
+    // catalog stays well under the Lambda timeout (each URL downloads inline).
+    // Reconcile below still runs against the FULL manifest, so a partial seed
+    // never retires the groups it skipped.
+    const onlyGroups = Array.isArray(body.groups) ? new Set(body.groups.map((g) => String(g))) : null;
+    const items = onlyGroups ? allItems.filter((it) => onlyGroups.has(it.group)) : allItems;
+    const results = [];
+    for (const item of items) {
+        const originalUrl = stripTrackingParams(item.url);
+        const sourceHost = safeUrlHostname(originalUrl);
+        if (!sourceHost) {
+            results.push({ source_url: item.url, title: item.title, error: "invalid URL" });
+            continue;
+        }
+        let inspiration = await serverlessRecords.findInspirationByOriginalUrl(originalUrl);
+        // (Re)start the download only when there's no usable video yet — a genuine
+        // download failure (no videoUrl) retries, but a pick that DID download and
+        // only tripped the duration limit keeps its bytes and gets clipped below.
+        const needsIngest = !inspiration
+            || (!inspiration.videoUrl && inspiration.status !== "downloading");
+        if (needsIngest) {
+            const payload = operation.inputSchema.parse({ source_url: originalUrl, save_manifest: true });
+            let job;
+            try {
+                job = await jobs.createRootJob({
+                    templateId: primitive.id,
+                    operationName: "run",
+                    workflowName: operation.workflow,
+                    tracer: `popular_seed_ingest:${ownerCustomer.id}`,
+                    payload,
+                    webhookUrl: null,
+                    customer: ownerCustomer,
+                    providerHint: undefined
+                });
+            }
+            catch (error) {
+                results.push({ source_url: item.url, title: item.title, error: error instanceof Error ? error.message : String(error) });
+                continue;
+            }
+            inspiration = inspiration
+                ? ((await serverlessRecords.updateInspiration({
+                    inspirationId: inspiration.id,
+                    patch: { status: "downloading", downloadJobId: job.id, errorMessage: null }
+                })) ?? inspiration)
+                : await serverlessRecords.createInspiration({
+                    customerId: ownerCustomer.id,
+                    sourceUrl: item.url,
+                    originalUrl,
+                    sourceHost,
+                    downloadJobId: job.id,
+                    trendTagline: item.title
+                });
+        }
+        // Stamp the editorial marker + curated title up front so a still-downloading
+        // pick already surfaces under Popular with the right label (pending cards
+        // read trendTagline, which finalize never clobbers).
+        inspiration = (await serverlessRecords.updateInspiration({
+            inspirationId: inspiration.id,
+            patch: { title: item.title, trendTagline: item.title, popularGroup: item.group, popularRank: item.rank, visibility: "public" }
+        })) ?? inspiration;
+        // On a local box (no Step Functions) the download job would queue forever —
+        // run it in-process so ensureInspirationReadyThenFork can finalize.
+        if (!config.VIDFARM_JOB_STATE_MACHINE_ARN && inspiration.status === "downloading" && inspiration.downloadJobId) {
+            const pendingJobId = inspiration.downloadJobId;
+            void runPrimitiveJobInProcess(pendingJobId).catch((error) => {
+                console.error("popular seed download failed", pendingJobId, error instanceof Error ? error.message : error);
+            });
+        }
+        const finalized = await ensureInspirationReadyThenFork({ inspiration, ownerCustomer, publicBaseUrl, note: null });
+        let templateId = typeof finalized.template_id === "string" ? finalized.template_id : null;
+        let clipped = false;
+        let sourceDurationSec = null;
+        // Curated Popular picks are short-form. If the source downloaded fine but was
+        // rejected ONLY for exceeding the 120s ingest limit, clip it to <=115s and
+        // finalize the clip — so a long reference video still becomes a Popular card.
+        if (!templateId) {
+            const rejected = await serverlessRecords.getInspiration(inspiration.id);
+            const tooLong = Boolean(rejected?.videoUrl)
+                && ((Number.isFinite(rejected?.durationSeconds) && Number(rejected?.durationSeconds) > POPULAR_MAX_CLIP_SEC)
+                    || /exceeds/i.test(rejected?.errorMessage ?? ""));
+            if (Number.isFinite(rejected?.durationSeconds))
+                sourceDurationSec = Number(rejected?.durationSeconds);
+            else {
+                const m = /([0-9.]+)s exceeds/.exec(rejected?.errorMessage ?? "");
+                if (m)
+                    sourceDurationSec = Number(m[1]);
+            }
+            if (rejected?.videoUrl && tooLong) {
+                try {
+                    const trimmed = await trimVideoAsset({ sourceUrl: rejected.videoUrl, startMs: 0, durationMs: POPULAR_MAX_CLIP_SEC * 1000 });
+                    // Store under the public "primitives/" prefix so getPublicUrl can hand
+                    // back a directly-fetchable S3 URL (other prefixes resolve to null).
+                    const clipKey = joinStorageKey("primitives", "popular-clips", `${rejected.id}.mp4`);
+                    const stored = await storage.putBuffer(clipKey, trimmed.bytes, "video/mp4");
+                    const clipUrl = stored.url ?? storage.getPublicUrl(clipKey);
+                    if (!clipUrl)
+                        console.error("popular seed clip: no public URL for", clipKey);
+                    const clipDurRaw = trimmed.metadata.trimmed?.durationSeconds;
+                    const clipDur = Number.isFinite(clipDurRaw) && clipDurRaw ? Number(clipDurRaw) : POPULAR_MAX_CLIP_SEC;
+                    if (clipUrl) {
+                        const readyInsp = await serverlessRecords.updateInspiration({
+                            inspirationId: rejected.id,
+                            patch: {
+                                videoUrl: clipUrl,
+                                videoStorageKey: clipKey,
+                                thumbnailUrl: null,
+                                durationSeconds: clipDur,
+                                status: "ready",
+                                errorMessage: null
+                            }
+                        });
+                        if (readyInsp) {
+                            const reFinalized = await ensureInspirationReadyThenFork({ inspiration: readyInsp, ownerCustomer, publicBaseUrl, note: null });
+                            templateId = typeof reFinalized.template_id === "string" ? reFinalized.template_id : null;
+                            clipped = Boolean(templateId);
+                        }
+                    }
+                }
+                catch (error) {
+                    console.error("popular seed clip failed", rejected.id, error instanceof Error ? error.message : error);
+                }
+            }
+        }
+        if (templateId) {
+            await serverlessRecords.updateTemplate({
+                templateId,
+                patch: { title: item.title, popularGroup: item.group, popularRank: item.rank, visibility: "public" }
+            });
+        }
+        results.push({
+            source_url: item.url,
+            title: item.title,
+            group: item.group,
+            rank: item.rank,
+            template_id: templateId,
+            status: templateId ? "ready" : (finalized.status ?? null),
+            clipped,
+            source_duration_sec: sourceDurationSec,
+            pending: finalized.pending ?? false
+        });
+    }
+    // Reconcile: any previously-seeded pick whose URL is no longer in the manifest
+    // (a replaced or removed entry) gets un-flagged so it drops out of the Popular
+    // view — the manifest is the single source of truth. Compared after the same
+    // tracking-param stripping the stored originalUrl went through.
+    const manifestUrls = new Set(allItems.map((it) => stripTrackingParams(it.url)));
+    const retired = [];
+    for (const tmpl of await serverlessRecords.listPopularTemplates()) {
+        if (!manifestUrls.has(tmpl.originalUrl)) {
+            await serverlessRecords.updateTemplate({ templateId: tmpl.id, patch: { popularGroup: null, popularRank: null } });
+            retired.push({ template_id: tmpl.id, title: tmpl.title, original_url: tmpl.originalUrl });
+        }
+    }
+    return c.json({ ok: true, owner_customer_id: ownerCustomer.id, count: results.length, items: results, retired }, 202);
+});
 function buildRawTikTokCompositionHtml(input) {
     const duration = Number.isFinite(input.durationSeconds) && input.durationSeconds > 0
         ? Number(input.durationSeconds.toFixed(3))
@@ -14938,6 +15357,31 @@ 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
@@ -14946,7 +15390,7 @@ app.get(`${USER_PREFIX}/me/generated-media`, async (c) => {
 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"];
+    const providers = libModel ? [inferEmbeddingProviderFromModel(libModel)] : ["gemini", "openai"];
     for (const provider of providers) {
         const apiKey = await resolveCustomerProviderKey(customerId, provider);
         if (!apiKey)
@@ -16162,7 +16606,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;
@@ -16532,29 +16976,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
@@ -16856,6 +17325,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;
@@ -16875,16 +17349,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);