@mevdragon/vidfarm-devcli 0.18.0 → 0.19.0

package/dist/src/app.js

@@ -31,10 +31,14 @@ import { renderReskinDiscover } from "./reskin/discover-page.js";
 import { renderReskinChat } from "./reskin/chat-page.js";
 import { renderReskinCalendar } from "./reskin/calendar-page.js";
 import { renderReskinInpaint } from "./reskin/inpaint-page.js";
+import { renderReskinInpaintVideo } from "./reskin/inpaint-video-page.js";
+import { renderReskinInpaintClipper } from "./reskin/inpaint-clipper-page.js";
 import { renderReskinAgency } from "./reskin/agency-page.js";
 import { renderReskinPricing } from "./reskin/pricing-page.js";
 import { renderReskinLogin } from "./reskin/login-page.js";
 import { renderReskinHelp } from "./reskin/help-page.js";
+import { renderChatDock, RESKIN_CHROME_SCRIPT } from "./reskin/document.js";
+import { RESKIN_CSS, RESKIN_FONT_LINKS } from "./reskin/theme.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";
@@ -60,7 +64,7 @@ import { RateLimitExceededError, RateLimitService } from "./services/rate-limits
 import { ServerlessProviderKeyService } from "./services/serverless-provider-keys.js";
 import { ServerlessTemplateConfigService } from "./services/serverless-template-configs.js";
 import { parseHTML } from "linkedom";
-import { joinStorageKey, StorageService } from "./services/storage.js";
+import { joinStorageKey, storage as sharedStorage } from "./services/storage.js";
 import { buildCaptionCues, cuesFromText } from "./services/captions.js";
 import { defaultSpeechModelFor as speechModelFor, transcribeSpeechWithKey } from "./services/speech.js";
 import { insertCaptionLayers } from "./devcli/composition-edit.js";
@@ -68,12 +72,13 @@ 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, 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 { ATTACHMENTS_FOLDER_SCOPE, buildDirectoryPath, DIRECTORY_ROOTS, DIRECTORY_ROOT_KEYS, folderItem, immediateChildFolders, normalizeFolderPath, parseDirectoryPath } from "./services/file-directory.js";
+import { applyHuntSpecDefaults, BUILTIN_PRESETS, buildClipEmbeddingText, buildEffectiveGuidance, ClipModelClient, cosineSimilarity, detectLocalAgent, effectiveHuntDurationSec, ACTIVE_TAXONOMY_VERSION, estimateScanCostFromDuration, extractClip, extractThumbnail, hasFfmpeg, LocalAgentClipClient, normalizeCropFocus, normalizeHuntSpec, parseClipHuntPrompt, pickBestVideoMedia, probeVideo, resolveDurationBand, resolveTargetClipCount, scanVideo } from "./services/clip-curation/index.js";
+import { analyzeCastMembers, annotateScenesFromSource, buildBlankCompositionHtml, buildSmartDecomposedHtml, DEFAULT_EDITOR_HARNESS, 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, extractVideoFrameAsset, probeMediaAsset } 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";
@@ -89,7 +94,7 @@ const providers = new ProviderService();
 const rateLimits = new RateLimitService();
 const serverlessProviderKeys = new ServerlessProviderKeyService();
 const serverlessTemplateConfigs = new ServerlessTemplateConfigService();
-const storage = new StorageService();
+const storage = sharedStorage;
 const templateSources = new TemplateSourceService();
 const hyperframes = new HyperframesService();
 const API_PREFIX = "/api/v1";
@@ -846,7 +851,7 @@ function consumeLoginReturnPath(c) {
 function resolvePostLoginRedirect(c, customer) {
     const returnPath = consumeLoginReturnPath(c) ?? sanitizeLoginReturnPath(c.req.query("return_to"));
     if (!returnPath) {
-        return withAccountQuery("/settings", customer.id);
+        return withAccountQuery("/settings/profile", customer.id);
     }
     const parsed = new URL(returnPath, "https://vidfarm.local");
     if (parsed.pathname === "/settings" || parsed.pathname.startsWith("/settings/")) {
@@ -861,6 +866,10 @@ function setSettingsFlash(c, input) {
 function clearSettingsFlash(c) {
     appendCookie(c, `${SETTINGS_FLASH_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0${cookieSecureAttribute()}`);
 }
+const SETTINGS_TABS = ["profile", "wallet", "channels", "developer"];
+function isSettingsTab(value) {
+    return value === "profile" || value === "wallet" || value === "channels" || value === "developer";
+}
 function consumeSettingsFlash(c) {
     const cookies = parseCookieHeader(c.req.header("cookie"));
     const raw = cookies.get(SETTINGS_FLASH_COOKIE);
@@ -1048,19 +1057,15 @@ function parseTracerList(searchParams) {
     return output.slice(0, 24);
 }
 function redirectToSettings(c, input) {
-    if (input?.notice || input?.error || input?.tab) {
-        setSettingsFlash(c, input);
+    // Notice/error still travel in a short-lived flash cookie; the tab now travels
+    // in the path (/settings/<tab>) so the URL matches the panel that's shown.
+    if (input?.notice || input?.error) {
+        setSettingsFlash(c, { notice: input.notice, error: input.error, tab: input.tab });
     }
-    const params = new URLSearchParams();
     const accountId = input?.accountId ?? getRequestedAccountId(c);
-    if (input?.tab) {
-        params.set("tab", input.tab);
-    }
-    if (input?.refreshChannels) {
-        params.set("refresh", "channels");
-    }
-    const suffix = params.size ? `?${params.toString()}` : "";
-    return redirect(c, `${accountId ? withAccountQuery("/settings", accountId) : "/settings"}${suffix}`, 303);
+    const tab = isSettingsTab(input?.tab) ? input.tab : "profile";
+    const suffix = input?.refreshChannels ? "?refresh=channels" : "";
+    return redirect(c, `${withAccountQuery(`/settings/${tab}`, accountId)}${suffix}`, 303);
 }
 async function validateFlockPosterApiKey(apiKey) {
     await fetchFlockPosterIntegrations(apiKey);
@@ -1624,6 +1629,12 @@ function primitiveOperationPathForJob(job) {
     if (job.templateId === "primitive:image_remove_background" && job.operationName === "run") {
         return `${PRIMITIVES_PREFIX}/images/remove-background`;
     }
+    if (job.templateId === "primitive:image_remove_background_greenscreen" && job.operationName === "run") {
+        return `${PRIMITIVES_PREFIX}/images/remove-background-greenscreen`;
+    }
+    if (job.templateId === "primitive:media_overlay" && job.operationName === "run") {
+        return `${PRIMITIVES_PREFIX}/images/create-overlay`;
+    }
     if (job.templateId === "primitive:video_generate" && job.operationName === "run") {
         return `${PRIMITIVES_PREFIX}/videos/generate`;
     }
@@ -2892,6 +2903,16 @@ function sanitizeStorageSubpath(value) {
         .filter((segment) => segment && segment !== "." && segment !== "..")
         .join("/");
 }
+// Temp files auto-organize by date: an upload with no explicit folder lands in
+// today's YYYY-MM-DD subfolder (canonical `/temp/2026-07-08/…`), so the scratch
+// space stays browsable instead of a flat dump. Applied at the write points
+// (presign + direct upload); finalize trusts the folder the presign echoed back.
+function todayDateFolder() {
+    return new Date().toISOString().slice(0, 10);
+}
+function withTempDateFolder(folderPath) {
+    return folderPath || todayDateFolder();
+}
 function inferAttachmentContentType(fileName) {
     switch (path.extname(fileName).toLowerCase()) {
         case ".png":
@@ -2938,7 +2959,50 @@ function buildUserAttachmentViewUrl(c, storageKey) {
 function buildUserFileUrl(c, storageKey) {
     return storage.getPublicUrl(storageKey) ?? buildAbsoluteUrl(c, `/template-media?key=${encodeURIComponent(storageKey)}`);
 }
+// Ensure a durable poster image URL for a My Files attachment so the file
+// directory can render a snappy thumbnail. Policy per media type:
+//   image/* → the image IS its own poster (return its own view URL, no re-encode
+//             — cheapest + snappiest).
+//   video/* → extract a frame (~1000ms in, fall back to 0), store the JPEG under
+//             thumbs/attachments/<customer>/<id>.jpg and return that key + url.
+//   audio / pdf / text / everything else → null; the frontend shows a type icon.
+// BEST-EFFORT / fail-soft: a failed extraction NEVER fails the upload — it just
+// returns null and logs (mirrors importWholeVideoAsRaw's `.catch(() => false)`).
+async function ensureAttachmentThumbnail(input) {
+    const type = (input.contentType || "").toLowerCase();
+    if (type.startsWith("image/")) {
+        // An image is its own poster — never re-encode.
+        const url = input.attachmentUrl || storage.getPublicUrl(input.storageKey);
+        return url ? { thumbnailStorageKey: null, thumbnailUrl: url } : null;
+    }
+    if (!type.startsWith("video/")) {
+        // Audio, PDF, text, etc. — the file directory already renders a type icon.
+        return null;
+    }
+    // extractVideoFrameAsset downloads a URL, so point it at the just-stored
+    // object's own public URL when no explicit source URL is supplied.
+    const frameSource = input.sourceUrl || input.attachmentUrl || storage.getPublicUrl(input.storageKey);
+    if (!frameSource)
+        return null;
+    try {
+        const frame = await extractVideoFrameAsset({ sourceUrl: frameSource, atMs: 1000, format: "jpeg" })
+            // Very short clips have no frame 1s in — fall back to the very first frame.
+            .catch(() => extractVideoFrameAsset({ sourceUrl: frameSource, atMs: 0, format: "jpeg" }));
+        const thumbKey = joinStorageKey("thumbs", "attachments", input.customerId, `${input.attachmentId}.jpg`);
+        const stored = await storage.putBuffer(thumbKey, frame.bytes, "image/jpeg");
+        const thumbnailUrl = stored.url || storage.getPublicUrl(thumbKey);
+        return { thumbnailStorageKey: thumbKey, thumbnailUrl: thumbnailUrl ?? null };
+    }
+    catch (error) {
+        devLog("attachment.thumbnail_failed", { attachment_id: input.attachmentId, ...devErrorFields(error) }, "warn");
+        return null;
+    }
+}
 function serializeUserAttachment(c, attachment) {
+    // Every image poster falls back to the file's own view URL so image entries
+    // always render a thumbnail even if the record predates thumbnail wiring.
+    const viewUrl = attachment.publicUrl || storage.getPublicUrl(attachment.storageKey) || buildUserAttachmentViewUrl(c, attachment.storageKey);
+    const isImage = (attachment.contentType || "").toLowerCase().startsWith("image/");
     return {
         id: attachment.id,
         fileName: attachment.fileName,
@@ -2949,7 +3013,8 @@ function serializeUserAttachment(c, attachment) {
         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)
+        viewUrl,
+        thumbnailUrl: attachment.thumbnailUrl || (isImage ? viewUrl : null)
     };
 }
 function serializeUserTemporaryFile(c, file) {
@@ -2969,6 +3034,272 @@ function serializeUserTemporaryFile(c, file) {
 function buildFolderList(items) {
     return Array.from(new Set(items.map((item) => item.folderPath ?? "").filter(Boolean))).sort();
 }
+// ── Unified file directory: convert each backend's record into the one
+// canonical DirectoryItem shape so /files, /temp, /raws browse uniformly. ─────
+function attachmentToDirectoryItem(c, a) {
+    const s = serializeUserAttachment(c, a);
+    const folderPath = normalizeFolderPath(a.folderPath);
+    return {
+        path: buildDirectoryPath("files", folderPath, a.fileName),
+        root: "files",
+        folderPath,
+        name: a.fileName,
+        kind: "file",
+        id: a.id,
+        contentType: a.contentType,
+        viewUrl: s.viewUrl,
+        thumbUrl: s.thumbnailUrl ?? undefined,
+        sizeBytes: a.sizeBytes,
+        meta: { notes: s.notes, hasNotesEmbedding: s.hasNotesEmbedding, createdAt: a.createdAt }
+    };
+}
+function temporaryFileToDirectoryItem(c, f) {
+    const s = serializeUserTemporaryFile(c, f);
+    const folderPath = normalizeFolderPath(f.folderPath);
+    return {
+        path: buildDirectoryPath("temp", folderPath, f.fileName),
+        root: "temp",
+        folderPath,
+        name: f.fileName,
+        kind: "file",
+        id: f.id,
+        contentType: f.contentType,
+        viewUrl: s.viewUrl,
+        sizeBytes: f.sizeBytes,
+        meta: { expiresAt: f.expiresAt, createdAt: f.createdAt, s3Url: s.s3Url }
+    };
+}
+// Takes the OUTPUT of serializeClip (view/thumbnail URLs already resolved).
+function clipSerializedToDirectoryItem(s) {
+    const folderPath = normalizeFolderPath(s.folder_path);
+    const name = s.source_filename || s.description || "clip";
+    const duration = s.duration_sec;
+    return {
+        path: buildDirectoryPath("raws", folderPath, name),
+        root: "raws",
+        folderPath,
+        name,
+        kind: "file",
+        id: s.clip_id,
+        contentType: "video/mp4",
+        viewUrl: s.view_url || undefined,
+        thumbUrl: s.thumbnail_url || undefined,
+        durationSec: typeof duration === "number" ? duration : undefined,
+        meta: { description: s.description, tags: s.tags, created_at: s.created_at, source_video_id: s.source_video_id }
+    };
+}
+// An approved ready-post as a canonical directory file. view/thumb come from the
+// post's media assets (video for playback, an image asset for the poster).
+function readyPostToDirectoryItem(post) {
+    const folderPath = normalizeFolderPath(post.folderPath ?? "");
+    const name = (post.title && post.title.trim()) || `Post ${post.id}`;
+    const media = post.mediaAssets || [];
+    const video = media.find((a) => a.kind === "video");
+    const image = media.find((a) => a.kind === "image");
+    const primary = media.find((a) => a.role === "primary") || video || media[0] || null;
+    return {
+        path: buildDirectoryPath("approved", folderPath, name),
+        root: "approved",
+        folderPath,
+        name,
+        kind: "file",
+        id: post.id,
+        contentType: video ? "video/mp4" : (primary?.contentType || "application/octet-stream"),
+        viewUrl: (primary?.url || video?.url) || undefined,
+        thumbUrl: image?.url || undefined,
+        meta: { tracer: post.tracer, status: post.status, caption: post.caption, created_at: post.createdAt }
+    };
+}
+// Infer a MIME type from a fork file's name so the explorer can preview images /
+// video / audio and the agent can tell text (composition.html/json) from binary.
+function inferProjectFileContentType(name) {
+    const ext = (name.split(".").pop() || "").toLowerCase();
+    switch (ext) {
+        case "html":
+        case "htm": return "text/html; charset=utf-8";
+        case "json": return "application/json";
+        case "txt": return "text/plain; charset=utf-8";
+        case "md": return "text/markdown; charset=utf-8";
+        case "css": return "text/css; charset=utf-8";
+        case "js":
+        case "mjs": return "text/javascript; charset=utf-8";
+        case "srt": return "application/x-subrip";
+        case "vtt": return "text/vtt";
+        case "png": return "image/png";
+        case "jpg":
+        case "jpeg": return "image/jpeg";
+        case "gif": return "image/gif";
+        case "webp": return "image/webp";
+        case "svg": return "image/svg+xml";
+        case "mp4":
+        case "m4v": return "video/mp4";
+        case "webm": return "video/webm";
+        case "mov": return "video/quicktime";
+        case "mp3": return "audio/mpeg";
+        case "wav": return "audio/wav";
+        case "m4a": return "audio/mp4";
+        default: return "application/octet-stream";
+    }
+}
+// A fork (composition-editing project) as a top-level /projects folder. The
+// folder path segment is the STABLE fork id (so paths round-trip); the display
+// name prefers a human title (the fork's own, else its template's) so the tile
+// is recognizable.
+function projectForkToFolderItem(fork, displayName) {
+    const versions = fork.latestVersion ?? 0;
+    return {
+        path: buildDirectoryPath("projects", fork.id),
+        root: "projects",
+        folderPath: fork.id,
+        name: displayName,
+        kind: "folder",
+        meta: {
+            description: `video project · ${versions ? `v${versions}` : "unsaved"}`,
+            forkId: fork.id,
+            templateId: fork.templateId,
+            updated_at: fork.updatedAt,
+            latest_version: versions
+        }
+    };
+}
+// One object under a fork's storage root as a canonical directory file. `name`
+// is the trailing filename; `key` is the physical S3 key — it lives under the
+// public `compositions/forks/` prefix, so getPublicUrl yields a directly
+// fetchable view URL (and the composition.html/json are also readable through
+// the existing GET /api/v1/compositions/:forkId/* routes).
+function forkStorageFileToDirectoryItem(folderPath, name, key) {
+    return {
+        path: buildDirectoryPath("projects", folderPath, name),
+        root: "projects",
+        folderPath,
+        name,
+        kind: "file",
+        id: key,
+        contentType: inferProjectFileContentType(name),
+        viewUrl: storage.getPublicUrl(key) || undefined,
+        meta: { storageKey: key }
+    };
+}
+// List one folder of the /projects root. At depth 0 (folderPath "") every fork
+// the customer owns is a folder; deeper, the fork's S3 storage tree (working/ +
+// versions/…) is presented as a generic prefix explorer, so any composition file
+// is a real, copyable, agent-addressable path like
+// /projects/<forkId>/working/composition.html. Read-only.
+async function listProjectsFolder(customerId, cur) {
+    const segments = cur ? cur.split("/") : [];
+    if (segments.length === 0) {
+        const forks = (await serverlessRecords.listCompositionForksForCustomer(customerId))
+            .filter((f) => !f.deletedAt);
+        forks.sort((a, b) => String(b.updatedAt ?? "").localeCompare(String(a.updatedAt ?? "")));
+        // One template lookup, mapped, to give forks recognizable names.
+        const templates = await serverlessRecords.listTemplatesForCustomer(customerId).catch(() => []);
+        const titleByTemplate = new Map();
+        for (const t of templates) {
+            if (t.title && t.title.trim())
+                titleByTemplate.set(t.id, t.title.trim());
+        }
+        const folders = forks.map((fork) => {
+            const name = (fork.title && fork.title.trim())
+                || titleByTemplate.get(fork.templateId)
+                || `Project ${fork.id.slice(-6)}`;
+            return projectForkToFolderItem(fork, name);
+        });
+        return { folders, files: [] };
+    }
+    const forkId = segments[0];
+    // Browse is scoped to the owner: only the customer's own forks are listable.
+    const fork = await serverlessRecords.getCompositionFork(forkId);
+    if (!fork || fork.customerId !== customerId || fork.deletedAt) {
+        return { folders: [], files: [] };
+    }
+    const rootPrefix = storage.compositionForkRoot(forkId) + "/"; // compositions/forks/<id>/
+    const keys = await storage.listKeys(rootPrefix);
+    const subPath = segments.slice(1).join("/");
+    const subPrefix = subPath ? subPath + "/" : "";
+    const childFolders = new Set();
+    const files = [];
+    for (const key of keys) {
+        if (key.indexOf(rootPrefix) !== 0)
+            continue;
+        const rel = key.slice(rootPrefix.length);
+        if (!rel || (subPrefix && rel.indexOf(subPrefix) !== 0))
+            continue;
+        const remainder = rel.slice(subPrefix.length);
+        if (!remainder)
+            continue;
+        const slash = remainder.indexOf("/");
+        if (slash >= 0)
+            childFolders.add(remainder.slice(0, slash));
+        else
+            files.push(forkStorageFileToDirectoryItem(cur, remainder, key));
+    }
+    const folders = Array.from(childFolders).sort().map((n) => folderItem("projects", cur, n));
+    files.sort((a, b) => a.name.localeCompare(b.name));
+    return { folders, files };
+}
+/**
+ * List one folder of one directory root, returning immediate child folders + the
+ * files directly in this folder as canonical DirectoryItems. The single place
+ * that dispatches a canonical path to its backend (attachments / temp / raws /
+ * projects / approved).
+ */
+async function listDirectoryFolder(c, customerId, root, folderPath) {
+    const cur = normalizeFolderPath(folderPath);
+    if (root === "files") {
+        const atts = await serverlessRecords.listUserAttachments(customerId);
+        const explicit = await serverlessRecords.listUserFileFolders(customerId, ATTACHMENTS_FOLDER_SCOPE);
+        const childNames = immediateChildFolders([...explicit, ...atts.map((a) => a.folderPath)], cur);
+        const files = atts
+            .filter((a) => normalizeFolderPath(a.folderPath) === cur)
+            .map((a) => attachmentToDirectoryItem(c, a));
+        return { folders: childNames.map((n) => folderItem("files", cur, n)), files };
+    }
+    if (root === "temp") {
+        const list = await serverlessRecords.listUserTemporaryFiles(customerId);
+        const explicit = await serverlessRecords.listUserFileFolders(customerId, "temporary");
+        const childNames = immediateChildFolders([...explicit, ...list.map((f) => f.folderPath)], cur);
+        const files = list
+            .filter((f) => normalizeFolderPath(f.folderPath) === cur)
+            .map((f) => temporaryFileToDirectoryItem(c, f));
+        return { folders: childNames.map((n) => folderItem("temp", cur, n)), files };
+    }
+    if (root === "raws") {
+        const clips = await clipRecords.listClips(customerId, { limit: 5000 });
+        const explicitRawFolders = await serverlessRecords.listUserFileFolders(customerId, "raws");
+        const childNames = immediateChildFolders([...explicitRawFolders, ...clips.map((clip) => clip.folder_path)], cur);
+        const here = clips.filter((clip) => normalizeFolderPath(clip.folder_path) === cur);
+        const files = (await Promise.all(here.map(serializeClip))).map(clipSerializedToDirectoryItem);
+        return { folders: childNames.map((n) => folderItem("raws", cur, n)), files };
+    }
+    if (root === "projects") {
+        return listProjectsFolder(customerId, cur);
+    }
+    // approved — finished ready-to-post cuts, foldered by folder_path.
+    const posts = (await serverlessRecords.listReadyPosts(customerId)).filter((p) => p.status !== "deleted");
+    const explicitApprovedFolders = await serverlessRecords.listUserFileFolders(customerId, "approved");
+    const childNames = immediateChildFolders([...explicitApprovedFolders, ...posts.map((p) => p.folderPath ?? "")], cur);
+    const here = posts.filter((p) => normalizeFolderPath(p.folderPath ?? "") === cur);
+    const files = here.map(readyPostToDirectoryItem);
+    return { folders: childNames.map((n) => folderItem("approved", cur, n)), files };
+}
+// The user_file_folder scope backing each directory root's empty folders.
+function directoryFolderScope(root) {
+    return root === "files" ? ATTACHMENTS_FOLDER_SCOPE
+        : root === "temp" ? "temporary"
+            : root === "approved" ? "approved"
+                : "raws";
+}
+// The three roots presented as folders at the virtual root ("/").
+function directoryRootFolders() {
+    return DIRECTORY_ROOTS.map((r) => ({
+        path: `/${r.key}`,
+        root: r.key,
+        folderPath: "",
+        name: r.label,
+        kind: "folder",
+        meta: { description: r.description }
+    }));
+}
 function isFormFile(value) {
     return Boolean(value
         && typeof value === "object"
@@ -3145,6 +3476,9 @@ function buildPrimitiveEditorDocsRoutes() {
         { method: "POST", path: `${PRIMITIVES_PREFIX}/images/edit`, summary: "Primitive whole-image edit job. Body must be { tracer, payload: { source_image_url, instruction, reference_attachments?, aspect_ratio?, image_size?, output_format? }, webhook_url? }." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/images/inpaint`, summary: "Primitive masked image edit job. Body must be { tracer, payload: { source_image_url, mask_url, instruction, reference_attachments?, aspect_ratio?, image_size?, output_format? }, webhook_url? }." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/images/render-html`, summary: "Primitive HTML still-image render job. Body must be { tracer, payload: { html, css?, width?, height?, background_color?, output_format? }, webhook_url? }." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/images/remove-background`, summary: "Primitive background-removal job. Returns a transparent-background PNG cut-out of the subject (subject isolation for overlays, product cut-outs, sprite cards, caption matting). Body must be { tracer, payload: { source_image_url }, webhook_url? }. AI matting for ARBITRARY photos with a messy background. BILLS THE WALLET (RapidAPI) — unlike the BYOK images/generate and images/edit routes. If the source already sits on a FLAT solid background, prefer the much cheaper images/remove-background-greenscreen." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/images/remove-background-greenscreen`, summary: "CHEAP local chroma-key background removal. Keys out a FLAT, solid background (green screen by default; pass key_color for white/blue/black/any flat fill) to a transparent PNG/WebP — sharp, no third-party API, compute-only wallet fee. Body must be { tracer, payload: { source_image_url, key_color? (default #00FF00), tolerance? (0..1, default 0.3), softness? (0..1, default 0.1), despill? (default true), output_format? (png|webp) }, webhook_url? }. Use for images you generated on a controlled solid background; for uncontrolled photos use images/remove-background. Flat alias: POST /api/v1/primitives/remove-background-greenscreen." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/images/create-overlay`, summary: "CREATE MEDIA OVERLAY (Vox-style) — the preferred one-shot way to mint a transparent floating illustration/prop/icon/character to animate over a composition. ONE job: generate an AI image of the subject on a forced flat key-color background (BYOK image keys) THEN chroma-key it out to a ready-to-composite transparent PNG/WebP. Body must be { tracer, payload: { prompt, provider?, model?, prompt_attachments?, aspect_ratio?, image_size?, key_color? (default #00FF00), tolerance? (default 0.3), softness? (default 0.1), despill? (default true), output_format? (png|webp) }, webhook_url? }. Result carries primary_file_url (the transparent overlay) plus greenscreen_source_url (the raw pre-key frame). BILLS THE WALLET (small platform fee); the image-gen leg additionally rides the caller's own provider key. Flat alias: POST /api/v1/primitives/create-media-overlay." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/videos/download`, summary: "Primitive social/media video download job. Body must be { tracer, payload: { source_url|video_url|url, quality? }, webhook_url? }. Use this to turn supported page/post URLs into a durable Vidfarm-hosted MP4 before later template work." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/videos/generate`, summary: "Primitive AI video generation job using saved OpenAI, Gemini, or OpenRouter provider keys. Body must be { tracer, payload: { prompt, provider?, model?, input_references?, frame_images?, aspect_ratio?, duration?, resolution?, generate_audio? }, webhook_url? }. input_references must be direct image asset URLs, not webpage or social post URLs. duration is seconds, not milliseconds; use duration: 4 for a 4-second AI video. Defaults: openai/sora-2, gemini/veo-3.0-generate-001, openrouter/bytedance/seedance-2.0. Use this for new AI-generated footage." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/videos/normalize`, summary: "Primitive video normalization job. Body must be { tracer, payload: { source_video_url, max_width?, max_height?, crf?, preset?, max_video_bitrate_kbps?, audio_bitrate_kbps? }, webhook_url? }." },
@@ -3609,6 +3943,10 @@ function normalizeEditorChatPath(input) {
         PRIMITIVES_PREFIX,
         APPROVED_POSTS_PREFIX,
         `${USER_PREFIX}/me/jobs`,
+        // Unified file directory: browse/search /files, /temp, /raws by canonical
+        // path (GET /me/directory, POST /me/directory/search). browse_files uses the
+        // same endpoints; this lets the agent hit them directly via http_request too.
+        `${USER_PREFIX}/me/directory`,
         // Read-only catalog discovery so the copilot can answer "which templates
         // suit my <offer>?": the template feed (supports ?q=&limit=) and the source
         // video / inspiration catalog (supports ?q=&limit=&mine=). Ingest lives at
@@ -3631,6 +3969,10 @@ function normalizeEditorChatPath(input) {
         // scene-selection filter; caption removal stays a per-finished-clip
         // primitive (/api/v1/primitives/videos/remove-captions).
         RAWS_PREFIX,
+        // Legacy /clips alias (server redispatches /clips/* → /raws/*). Allowed so a
+        // prompt that still says /clips/scan works identically to /raws/scan and the
+        // allowlist doesn't drift from the deployed Lambda copy.
+        CLIPS_COMPAT_PREFIX,
         // Public skill knowledge: the vendored skill packs (load_skill fetches
         // these too) and per-template SKILL.md manifests. Read-only markdown.
         "/skill/",
@@ -3864,10 +4206,18 @@ function createVideoContextTool(input) {
     return tool({
         description: "OPTIONAL context fetch: retrieve the current composition fork's decomposed video context — the source video's verbatim audio transcript (full text plus timestamped segments) and a literal visual description of every scene, along with viral DNA and per-scene transcript excerpts. Call it when the user asks what the source video says or shows, when writing or translating captions/hooks/dubs that must match the spoken audio, or when you need scene-by-scene grounding before planning timeline edits. Read-only and non-billing. The data comes from the smart-decompose snapshot; status=\"none\" means the fork was never smart-decomposed — offer to run POST /api/v1/compositions/:forkId/auto-decompose first. The same data is also available via GET /api/v1/compositions/:forkId/video-context.json through http_request.",
         inputSchema: z.object({
-            fork_id: z.string().min(1).describe("Composition fork id. Copy it from the current editor_context; never invent one."),
+            fork_id: z.string().min(1).describe("Composition fork id — a fork_* id. Copy it verbatim from editor_context.fork_id in the most recent <editor_context>; never pass editor_context.composition_id (that is the template_* id, not a fork) and never invent one. If editor_context has no fork_id, this composition has no saved fork yet — do not call this tool; edit the composition first to mint a fork."),
             explanation: z.string().optional().describe("Short reason for fetching the video context.")
         }),
         execute: async ({ fork_id, explanation }) => {
+            if (fork_id.startsWith("template_")) {
+                return {
+                    explanation: explanation ?? null,
+                    status: 0,
+                    video_context: null,
+                    error: `"${fork_id}" is a template id (composition_id), not a fork id. Video context is keyed by fork — read editor_context.fork_id (a fork_* id) from the most recent <editor_context> and call again with that. If editor_context has no fork_id, this composition has no saved fork yet; make an edit first to mint one.`
+                };
+            }
             const url = normalizeEditorChatPath({
                 path: `/api/v1/compositions/${encodeURIComponent(fork_id)}/video-context.json`,
                 template: input.template
@@ -3916,10 +4266,18 @@ function createProductPlacementContextTool(input) {
     return tool({
         description: "OPTIONAL context fetch: retrieve the current composition fork's product-placement surfaces — the product-AGNOSTIC slots found during decompose where any product could later be inserted natively (each with a timestamp, start seconds, scene_slug, surface_type, surface_note, best_for product categories, and why_it_works). Call it BEFORE running the brainstorm_product_placement primitive so you can seed it with real, grounded moments, and whenever the user asks where a product could be placed in this video. Read-only and non-billing. status=\"none\" means the fork was never decomposed (offer POST /api/v1/compositions/:forkId/auto-decompose); status=\"empty\" means decompose found no natural surface. Same data is available via GET /api/v1/compositions/:forkId/product-placement.json through http_request.",
         inputSchema: z.object({
-            fork_id: z.string().min(1).describe("Composition fork id. Copy it from the current editor_context; never invent one."),
+            fork_id: z.string().min(1).describe("Composition fork id — a fork_* id. Copy it verbatim from editor_context.fork_id in the most recent <editor_context>; never pass editor_context.composition_id (that is the template_* id, not a fork) and never invent one. If editor_context has no fork_id, this composition has no saved fork yet — do not call this tool; edit the composition first to mint a fork."),
             explanation: z.string().optional().describe("Short reason for fetching the placement surfaces.")
         }),
         execute: async ({ fork_id, explanation }) => {
+            if (fork_id.startsWith("template_")) {
+                return {
+                    explanation: explanation ?? null,
+                    status: 0,
+                    product_placement: null,
+                    error: `"${fork_id}" is a template id (composition_id), not a fork id. Product-placement surfaces are keyed by fork — read editor_context.fork_id (a fork_* id) from the most recent <editor_context> and call again with that. If editor_context has no fork_id, this composition has no saved fork yet; make an edit first to mint one.`
+                };
+            }
             const url = normalizeEditorChatPath({
                 path: `/api/v1/compositions/${encodeURIComponent(fork_id)}/product-placement.json`,
                 template: input.template
@@ -4013,19 +4371,25 @@ 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=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.",
+        description: "Browse AND write the user's file directory — a navigable tree with FIVE roots: /files (durable My Files: uploaded assets like mp4, mov, png, jpg, mp3, pdf, md, txt, csv, plus text context you save — vector-searchable via notes), /temp (scratch space auto-foldered by date YYYY-MM-DD, auto-deleted after 30 days), /raws (the reusable clip/source-footage library, foldered by source), /projects (READ-ONLY: the user's video-editing projects — one folder per composition fork, holding that fork's stored files like working/composition.html and working/composition.json plus saved versions/; browse here to study or reference ANOTHER fork, then read its composition through GET /api/v1/compositions/<forkId>/composition.html), and /approved (finished, ready-to-post cuts, foldered — defaults to a folder per tracer/campaign). Every folder can have nested subfolders and every file has a canonical copyable path like /raws/product-demos/clip.mp4.\n\nNAVIGATE BY PATH: pass `path` to list or search any location — path='/' lists the five roots; path='/raws', '/approved/summer-launch', or '/files/brand-assets' lists that folder's subfolders + files. Use action=list to enumerate a folder (folders[] + files[], each a canonical item with path, name, kind, view_url). (Legacy: action=list with folder_path and no path still lists /files only.)\n\nSEARCH: action=search with `query` (plain language) and optional `path` scope finds files by MEANING across roots — it combines semantic vector match, substring, and absolute-path match (control with `mode`: auto|semantic|substring|path). Prefer search when the user references an asset vaguely or you don't know which root/folder it's in; scope with path='/raws' to search only footage, path='/files' for durable assets, or path='/' for everything.\n\nMOVE: action=move with `file_id` and `path` (target folder) reorganizes a raw between /raws folders (e.g. /raws/demos) OR an approved post between /approved folders (e.g. /approved/summer-launch). RENAME: action=rename tidies the directory — pass path + new_name + file_id to rename a /files or /temp file (display name only; its view_url keeps working), or path + new_name with NO file_id to rename a folder in ANY root — /files, /temp, /raws, or /approved (its files come along; renaming a /raws folder re-points every clip inside it, so this is how you tidy an auto-named source folder like /raws/lvlldspajcg into /raws/marlin-fishing). 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: RECURRING CHARACTERS live under /files/characters/<slug>/ as a trio — <character_id>.json (the manifest, named after the id 'character_'+slug, e.g. character_zara.json; fields: id, slug, name, appearance, wardrobe, palette, voice, sprite_card_path, about_path), character_sprite_card.png (the reference sheet), and character_about.md (the prose). List /files/characters to see who exists, annotate all three, 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", "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."),
+            action: z.enum(["list", "read", "write", "annotate", "search", "move", "rename"]).describe("list = enumerate a folder's subfolders + files (pass path for any root); read = fetch one file's view_url and, for text files, its contents; write = save a text file into /files; annotate = set the metadata notes on one existing /files entry; search = find files by meaning/name/path across roots; move = move a raw between /raws folders OR an approved post between /approved folders; rename = rename a file (pass file_id + its path + new_name; /files or /temp only) or a folder (pass the folder path + new_name, no file_id) in ANY root — /files, /temp, /raws, or /approved."),
+            path: z.string().optional().describe("Canonical directory path to list or search: '/' for the four roots, '/raws', '/approved/summer-launch', or '/files/brand-assets' for a folder. For move, the target folder (e.g. /raws/demos or /approved/summer-launch). For rename, the current path of the file or folder to rename. Preferred over folder_path for cross-root navigation."),
+            new_name: z.string().optional().describe("For rename: the new file name (e.g. character_about.md) or the new folder name (a single segment, no slashes)."),
+            mode: z.enum(["auto", "semantic", "substring", "path"]).optional().describe("For search: which signals to combine. auto (default) = semantic vector + substring + absolute-path; or force one."),
+            folder_path: z.string().optional().describe("Legacy /files-only scope for a list or search, the folder of the file to read, or the folder to write into. Omit or leave empty for the root. Prefer `path` for anything outside /files."),
             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."),
+            content_type: z.string().optional().describe("For list/search of /raws: an EXACT shot-kind filter (not semantic) — one or a comma-separated OR set of talking_head, b_roll, product_shot, screen_recording, demo, reaction, interview, establishing, lifestyle, text_graphic. Narrows raw clips to those kinds; ignored outside /raws."),
+            offset: z.number().int().optional().describe("For list: page offset into a large folder (default 0). The response's next_offset is the offset to pass for the next page; null means no more."),
+            limit: z.number().int().optional().describe("For list/search: max items to return (list default 200, max 500; search default 30, max 50)."),
             explanation: z.string().optional().describe("Short reason for the browse, save, annotation, or search.")
         }),
-        execute: async ({ action, folder_path, file_id, file_name, content, source_url, notes, query, explanation }) => {
+        execute: async ({ action, path, mode, folder_path, file_id, file_name, new_name, content, source_url, notes, query, content_type, offset, limit, explanation }) => {
             const listUrl = new URL(`${USER_PREFIX}/me/attachments`, config.PUBLIC_BASE_URL);
             const headers = new Headers();
             headers.set("vidfarm-api-key", input.vidfarmApiKey);
@@ -4034,7 +4398,87 @@ function createBrowseFilesTool(input) {
                 timeoutController.abort(new Error("Browse files request timed out after 30 seconds."));
             }, 30_000);
             const normalizedFolder = (folder_path ?? "").trim().replace(/^\/+|\/+$/g, "");
+            // Default list/search to the WHOLE directory ('/') when neither a canonical
+            // path nor a legacy folder_path is given — otherwise these silently fell
+            // back to a /files-only search and the user's /raws + /temp were invisible.
+            const canonicalPath = (path ?? "").trim()
+                || ((action === "list" || action === "search") && !normalizedFolder ? "/" : "");
+            const contentTypeParam = (content_type ?? "").trim();
             try {
+                // ── unified directory navigation (any of /files, /temp, /raws) ──
+                if (action === "list" && canonicalPath) {
+                    const url = new URL(`${USER_PREFIX}/me/directory`, config.PUBLIC_BASE_URL);
+                    url.searchParams.set("path", canonicalPath);
+                    if (contentTypeParam)
+                        url.searchParams.set("content_type", contentTypeParam);
+                    if (offset !== undefined && Number.isFinite(offset))
+                        url.searchParams.set("offset", String(Math.max(0, Math.trunc(offset))));
+                    if (limit !== undefined && Number.isFinite(limit))
+                        url.searchParams.set("limit", String(Math.max(1, Math.trunc(limit))));
+                    const r = await fetch(url, { method: "GET", headers, signal: mergeAbortSignals(input.abortSignal, timeoutController.signal) });
+                    const body = await r.json().catch(() => null);
+                    return { action, explanation: explanation ?? null, status: r.status, ...(body || {}) };
+                }
+                if (action === "search" && canonicalPath) {
+                    const url = new URL(`${USER_PREFIX}/me/directory/search`, config.PUBLIC_BASE_URL);
+                    const searchHeaders = new Headers(headers);
+                    searchHeaders.set("content-type", "application/json");
+                    const searchLimit = limit !== undefined && Number.isFinite(limit) ? Math.max(1, Math.trunc(limit)) : 30;
+                    const r = await fetch(url, {
+                        method: "POST",
+                        headers: searchHeaders,
+                        body: JSON.stringify({
+                            query: (query ?? "").trim(),
+                            path: canonicalPath,
+                            mode: mode ?? "auto",
+                            limit: searchLimit,
+                            ...(contentTypeParam ? { content_type: contentTypeParam } : {})
+                        }),
+                        signal: mergeAbortSignals(input.abortSignal, timeoutController.signal)
+                    });
+                    const body = await r.json().catch(() => null);
+                    return { action, explanation: explanation ?? null, status: r.status, ...(body || {}) };
+                }
+                if (action === "move") {
+                    const id = (file_id ?? "").trim();
+                    const seg = canonicalPath.split("/").map((s) => s.trim()).filter(Boolean);
+                    const root = seg[0];
+                    if (!id || !root)
+                        return { action, explanation: explanation ?? null, status: 400, error: "move requires file_id and a target path like /raws/demos or /approved/summer-launch." };
+                    if (root !== "raws" && root !== "approved")
+                        return { action, explanation: explanation ?? null, status: 400, error: "move is supported within /raws (clips) and /approved (posts)." };
+                    const url = root === "approved"
+                        ? new URL(`${APPROVED_POSTS_PREFIX}/${encodeURIComponent(id)}`, config.PUBLIC_BASE_URL)
+                        : new URL(`${RAWS_PREFIX}/${encodeURIComponent(id)}`, config.PUBLIC_BASE_URL);
+                    const moveHeaders = new Headers(headers);
+                    moveHeaders.set("content-type", "application/json");
+                    const r = await fetch(url, {
+                        method: "PATCH",
+                        headers: moveHeaders,
+                        body: JSON.stringify({ folder_path: seg.slice(1).join("/") }),
+                        signal: mergeAbortSignals(input.abortSignal, timeoutController.signal)
+                    });
+                    const body = await r.json().catch(() => null);
+                    return { action, explanation: explanation ?? null, status: r.status, ...(body || {}) };
+                }
+                if (action === "rename") {
+                    const target = (path ?? "").trim();
+                    const nextName = (new_name ?? "").trim();
+                    if (!target || !nextName) {
+                        return { action, explanation: explanation ?? null, status: 400, error: "rename requires path (the file or folder to rename) and new_name. For a file also pass file_id." };
+                    }
+                    const url = new URL(`${USER_PREFIX}/me/directory/rename`, config.PUBLIC_BASE_URL);
+                    const renameHeaders = new Headers(headers);
+                    renameHeaders.set("content-type", "application/json");
+                    const r = await fetch(url, {
+                        method: "POST",
+                        headers: renameHeaders,
+                        body: JSON.stringify({ path: target, new_name: nextName, ...((file_id ?? "").trim() ? { file_id: (file_id ?? "").trim() } : {}) }),
+                        signal: mergeAbortSignals(input.abortSignal, timeoutController.signal)
+                    });
+                    const body = await r.json().catch(() => null);
+                    return { action, explanation: explanation ?? null, status: r.status, ...(body || {}) };
+                }
                 if (action === "write") {
                     const name = (file_name ?? "").trim();
                     if (!name) {
@@ -4396,7 +4840,7 @@ function createVideoCreationTool() {
 }
 function createEditorActionTool() {
     return tool({
-        description: "Directly mutate the composition timeline in the editor OR start an export render OR generate-and-place AI media. Use this whenever the user asks for a timeline change (add/remove/duplicate/split layers, retime, reposition, resize, restyle text, swap media, group/ungroup), asks to generate an AI video/image and drop it on the timeline (action_type=generate_layer), or asks to export/render/publish/download the final MP4 (action_type=export_composition). The most recent <editor_context> in the user message is the source of truth for current layer_keys, layer indices (called 'track'), durations, timeline_gaps (blank spans), pending_generations (AI gens still rendering), and the most recent exported MP4 (last_export_url). Always provide explanation. For add_layer, also provide layer_key with a stable descriptive id (e.g., 'vf-caption-hook', 'vf-hero-image') so subsequent tool calls in the same turn can reference it — the editor will use that id as the new layer's data-hf-id. PREFER action_type=generate_layer to create NEW AI footage/images on the timeline: it submits the primitive generate job, drops a placeholder clip into the target slot immediately, and auto-swaps in the finished media when the job settles (no manual poll, no separate add_layer). Only use the http_request→add_layer flow for media that already has a URL. Avoid layer/track collisions: pick a track index higher than any existing layer on the requested time range, or set start/duration so the range is free. Never invent layer_keys for remove/set/duplicate/split actions; only use keys present in the most recent editor_context. For action_type=export_composition, no layer_key/geometry fields are needed; the editor kicks off the render and streams status in the UI, and the resulting MP4 URL will appear in the next <editor_context> as last_export_url.",
+        description: "Directly mutate the composition timeline in the editor OR start an export render OR generate-and-place AI media. Use this whenever the user asks for a timeline change (add/remove/duplicate/split layers, retime, reposition, resize, restyle text, swap media, group/ungroup), asks to generate an AI video/image and drop it on the timeline (action_type=generate_layer), or asks to export/render/publish/download the final MP4 (action_type=export_composition). The most recent <editor_context> in the user message is the source of truth for current layer_keys, layer indices (called 'track'), durations, timeline_gaps (blank spans), pending_generations (AI gens still rendering), and the most recent exported MP4 (last_export_url). Forking is automatic — the FIRST mutating editor_action on a real template auto-mints the user's own private editable copy; you never create a fork manually, just edit (the exception is a blank project with composition_id \"original\", which has no template to fork yet, so edits there won't persist until a real video is created). Always provide explanation. For add_layer, also provide layer_key with a stable descriptive id (e.g., 'vf-caption-hook', 'vf-hero-image') so subsequent tool calls in the same turn can reference it — the editor will use that id as the new layer's data-hf-id. PREFER action_type=generate_layer to create NEW AI footage/images on the timeline: it submits the primitive generate job, drops a placeholder clip into the target slot immediately, and auto-swaps in the finished media when the job settles (no manual poll, no separate add_layer). Only use the http_request→add_layer flow for media that already has a URL. Avoid layer/track collisions: pick a track index higher than any existing layer on the requested time range, or set start/duration so the range is free. Never invent layer_keys for remove/set/duplicate/split actions; only use keys present in the most recent editor_context. For action_type=export_composition, no layer_key/geometry fields are needed; the editor kicks off the render and streams status in the UI, and the resulting MP4 URL will appear in the next <editor_context> as last_export_url. Editing works on THREE axes — SCENES (video/image clips), AUDIO (narration/music/SFX), and TEXT (captions/titles/overlays) — and on each the user may lightly SWAP (change content in place, keeping timing/geometry) or heavily REPLACE (restructure outright, often keeping only the template's viral DNA); for a heavy scene REPLACE prefer hunting real raw clips (POST /clips/scan) or the user's /raws library over AI generation, and carry the whole re-work rather than only single-layer nudges.",
         inputSchema: z.object({
             action_type: z.enum([
                 "add_layer",
@@ -4415,9 +4859,17 @@ function createEditorActionTool() {
                 "export_composition",
                 "generate_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."),
+                "set_transitions",
+                "set_layer_keyframes",
+                "nudge_layers",
+                "ripple_edit",
+                "set_layer_zindex",
+                "trim_layer",
+                "set_composition",
+                "fork_composition"
+            ]).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 fork_composition ONLY when the user EXPLICITLY asks to branch / duplicate / 'save as' / 'make a copy' / 'start a fresh version' of this project (routine editing already auto-forks — do NOT call this to begin editing): set fork_from='current' to branch from the current working copy (keep all edits) or fork_from='default' to start a fresh copy from the original template (discard current edits); the editor mints the new fork and opens it. 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. FINE TIMELINE CONTROL: set_layer_keyframes authors a custom script-free CSS @keyframes animation on ONE layer (opacity/translate/scale/rotate over the clip) that previews AND renders; nudge_layers moves one or more layers by a relative delta_start/delta_track (group-aware); ripple_edit inserts or closes time at at_time and shifts all downstream clips; trim_layer moves one edge (start|end) of a clip to a time, coupling media in-point on a left trim; set_layer_zindex restacks a layer (front|back|forward|backward) — stacking is the track index. STATIC LOOK: set_layer_visual also sets a constant opacity (0..1, e.g. a ghosted b-roll underlay — a FADE over time is set_layer_keyframes instead); set_layer_style also sets line_height (unitless leading) and letter_spacing (px tracking, negative tightens) for typography the presets can't reach. COMPOSITION-LEVEL: set_composition changes the whole canvas — canvas_width/canvas_height resize the frame, canvas_duration retargets total render length, background_color recolors the canvas (all written on the composition root, no layer_key)."),
             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."),
+            fork_from: z.enum(["current", "default"]).optional().describe("For action_type=fork_composition: 'current' branches a new fork from the current working copy (keeps all edits); 'default' starts a fresh fork from the template's original default (discards current edits). Defaults to 'current'."),
             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."),
             layer_keys: z.array(z.string()).optional().describe("Multiple layer keys. Required for group_layers (>=2) and ungroup_layers. For duplicate_layer, layer_keys[1] optionally names the duplicate."),
@@ -4442,11 +4894,18 @@ function createEditorActionTool() {
             underline: z.boolean().optional().describe("Toggle underline on text layers."),
             text_align: z.string().optional().describe("CSS text-align value (left, center, right, justify)."),
             border_radius: z.number().optional().describe("Border radius in pixels."),
+            opacity: z.number().optional().describe("set_layer_visual: constant layer opacity, 0 (invisible) to 1 (opaque). Baked as static inline style (seek-safe) — use it for a ghosted/dimmed underlay or a translucent overlay. For an opacity change OVER TIME (fade in/out) use set_layer_keyframes instead."),
+            line_height: z.number().optional().describe("set_layer_style: unitless CSS line-height (leading) for text/caption layers, e.g. 1.1 tight, 1.5 airy."),
+            letter_spacing: z.number().optional().describe("set_layer_style: CSS letter-spacing in px for text/caption layers (negative tightens, positive expands) — the lever for a condensed all-caps or wide-tracked look the font presets can't reach."),
+            canvas_width: z.number().optional().describe("set_composition: new canvas WIDTH in pixels (e.g. 1080). Written to the composition root's data-width. Resizes the output frame."),
+            canvas_height: z.number().optional().describe("set_composition: new canvas HEIGHT in pixels (e.g. 1920 for 9:16, 1080 for 1:1, or 1080 with width 1920 for 16:9). Written to data-height."),
+            canvas_duration: z.number().optional().describe("set_composition: total render length in seconds. Written to the root's data-duration (the overall video length). Distinct from a single clip's duration."),
+            background_color: z.string().optional().describe("set_composition: CSS color for the whole composition CANVAS background (behind all layers), e.g. '#000000' or 'white'. Distinct from a single layer's background."),
             color: z.string().optional().describe("CSS color for text foreground."),
             background: z.string().optional().describe("CSS color for background."),
             background_style: z.enum(["plain", "outline", "highlight-solid", "highlight-translucent"]).optional().describe("Text background treatment."),
-            object_fit: z.string().optional().describe("CSS object-fit for image/video (cover, contain, fill, none, scale-down)."),
-            object_position: z.string().optional().describe("CSS object-position for image/video (e.g., center, top, bottom left)."),
+            object_fit: z.string().optional().describe("CSS object-fit for image/video — how the media fills its layer box when its native aspect differs from the frame. 'cover' (default) fills the frame and crops the overflow (best for footage whose subject you keep centered or steer with object_position); 'contain' shows the WHOLE media with black letterbox/pillarbox bars (use only when nothing may be cropped — an infographic, whole screenshot, chart, logo); 'fill' stretches/distorts (avoid); 'none'; 'scale-down'. To fit a 16:9 landscape clip on a 9:16 vertical frame, prefer cover + a subject-aware object_position over contain unless the entire frame must be visible."),
+            object_position: z.string().optional().describe("CSS object-position — WHERE an object_fit:cover crop is anchored, so the subject stays in frame instead of being center-cropped out. Accepts keywords (center, left, right, top, bottom, 'top left', 'bottom right', ...) OR percentages/lengths ('30% 50%' holds the point 30% from the left and 50% down; '50% 20%' keeps the upper-middle). Landscape clip with the subject on the left → 'left' or '25% 50%'; tall screenshot with key content up top → 'top'. Only meaningful with object_fit cover/none."),
             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", "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."),
@@ -4486,6 +4945,22 @@ function createEditorActionTool() {
             resolution: z.string().optional().describe("generate_layer (video): optional resolution (480p|720p|1080p|1K|2K|4K)."),
             generate_audio: z.boolean().optional().describe("generate_layer (video): whether the model should generate an audio track."),
             replace_layer_key: z.string().optional().describe("generate_layer intent=replace_layer: the existing layer_key/slug whose scene slot (timing+geometry) the generated clip should take over."),
+            keyframes: z.array(z.object({
+                offset: z.number().describe("Position along the animation as a 0..1 fraction (0 = clip start, 1 = end)."),
+                opacity: z.number().optional().describe("Opacity 0..1 at this stop."),
+                translate_x: z.number().optional().describe("Horizontal move as a percent of the layer's own width (e.g. -100 = fully off to the left, 0 = rest)."),
+                translate_y: z.number().optional().describe("Vertical move as a percent of the layer's own height (e.g. 100 = one height below, 0 = rest)."),
+                scale: z.number().optional().describe("Uniform scale factor (1 = natural size, 1.2 = 20% larger)."),
+                rotate: z.number().optional().describe("Rotation in degrees.")
+            })).optional().describe("set_layer_keyframes: an ordered list of >=2 animation stops for ONE layer. The editor writes a script-free CSS @keyframes rule + inline animation that both previews and renders (the JS runtime adapters like anime.js/GSAP are NOT available in the web editor). Each stop sets any of opacity/translate_x/translate_y/scale/rotate at its offset. Example fly-in: [{offset:0,opacity:0,translate_y:40},{offset:1,opacity:1,translate_y:0}]."),
+            keyframe_easing: z.string().optional().describe("set_layer_keyframes timing function: linear (default), ease, ease-in, ease-out, ease-in-out, or a cubic-bezier(...)/steps(...) value."),
+            keyframe_duration: z.number().optional().describe("set_layer_keyframes: seconds the animation spans (default = the clip's full duration). The keyframe offsets map across this window."),
+            delta_start: z.number().optional().describe("nudge_layers: seconds to shift the layer(s) along the timeline (negative = earlier). ripple_edit: seconds to insert (positive) or close (negative) at at_time."),
+            delta_track: z.number().int().optional().describe("nudge_layers: lanes to shift the layer(s) by (negative = down/behind)."),
+            at_time: z.number().optional().describe("ripple_edit: the composition-time boundary (seconds) — every clip that starts at or after it shifts by delta_start."),
+            edge: z.enum(["start", "end"]).optional().describe("trim_layer: which edge to move. 'start' (left) advances the in-point and, for video/audio, pushes the media start so the visible frame stays put; 'end' (right) only changes duration."),
+            to_time: z.number().optional().describe("trim_layer: the new composition-time position (seconds) for the chosen edge."),
+            z_order: z.enum(["front", "back", "forward", "backward"]).optional().describe("set_layer_zindex: restack a layer. Stacking == track index (higher draws on top); 'front'/'forward' raise it, 'back'/'backward' lower it. Alternatively pass an explicit track."),
             explanation: z.string().describe("One-sentence reason shown in the UI.")
         }),
         execute: async (args) => {
@@ -4548,9 +5023,16 @@ async function streamEditorChatAgent(input, send) {
                     tracerRegistry
                 }),
                 editor_action: createEditorActionTool(),
-                // Discover/brainstorm surface only: "create me a video of…" / "replicate
-                // this URL…". The editor surfaces edit an already-open composition.
-                ...(input.template.templateId === "chat-brainstorm"
+                // create_video is for making a BRAND-NEW video. It belongs on the
+                // discover/brainstorm surface ("create me a video of…" / "replicate this
+                // URL…") AND on a BLANK editor project (templateId "original", the
+                // /editor/original/fork/new sentinel): a blank project has no template to
+                // fork yet, so editor_action edits can't persist — the model must mint a
+                // real composition first, and the dock already owns runCreateVideoFlow to
+                // run the ingest→decompose→fork pipeline and drop an "Open in editor" link.
+                // Real template_… compositions stay edit-only (editor_action) so the model
+                // never spawns a new template when the user just wanted to edit this one.
+                ...(input.template.templateId === "chat-brainstorm" || input.template.templateId === "original"
                     ? { create_video: createVideoCreationTool() }
                     : {})
             };
@@ -4753,6 +5235,24 @@ function renderHyperframesTimelineRuler(durationSeconds) {
     }).join("");
     return `<div class="hf-timeline-ruler" aria-hidden="true">${marks}</div>`;
 }
+// A not-yet-decomposed project is the raw single-video base: one <video> that
+// is BOTH the playback source AND its own timeline layer (data-layer-kind).
+// In the EDITOR its own audio is the point, so strip the baked-in `muted`
+// attribute when serving the composition to the editor stage (the editor plays
+// on a user gesture, so muted-autoplay is not needed). This is scoped to the
+// editor's composition.html load ONLY — card/swipe previews load a different
+// path and keep `muted` so their silent autoplay-loop still works. Decomposed
+// compositions emit a data-vf-playback-source WITHOUT data-layer-kind, so they
+// are left untouched.
+function unmuteRawPlaybackSourceVideo(html) {
+    return html.replace(/<video\b[^>]*>/gi, (tag) => {
+        if (!/data-vf-playback-source\s*=\s*["']?true/i.test(tag))
+            return tag;
+        if (!/data-layer-kind\s*=\s*["']?video/i.test(tag))
+            return tag;
+        return tag.replace(/\smuted(?=(\s|\/?>))/i, "");
+    });
+}
 function rewriteHyperframesDraftCompositionHtml(html, draftPath) {
     const baseHref = `/${normalizeDraftRelativePath(draftPath)}/`;
     const baseTag = `<base href="${escapeAttribute(baseHref)}">`;
@@ -4828,6 +5328,72 @@ function rewriteHyperframesDraftCompositionHtml(html, draftPath) {
     }
     return rewritten;
 }
+// Reskin overrides layered on top of the editor's own /assets/editor/app.css.
+// RESKIN_CSS scopes its element rules under .rk-root, so the only thing it changes
+// globally is the --rk-* token set + box-sizing. The editor chrome stays on its
+// original DARK theme; these rules only pin the reused reskin chat dock as a
+// permanent left column (the one farmville element we keep here).
+const EDITOR_FARMVILLE_CSS = `
+html,body{margin:0;background:#050604;color:#fffbe6}
+#root{min-height:100vh}
+
+/* The reused farmville chat dock, pinned flush as a permanent LEFT column
+   (desktop). Width stays natural: 440px for the clean chat column, widening to
+   overlay the editor's left edge only while the Files/History drawer is open. */
+@media (min-width:1025px){
+  .rk-aichat.rk-aichat--editor{
+    left:0 !important;top:0 !important;bottom:0 !important;right:auto !important;
+    height:100vh !important;max-height:100vh !important;
+    margin:0 !important;border-radius:0 !important;border-right:1px solid var(--rk-border) !important;
+    box-shadow:var(--rk-shadow-lg) !important;transform:none !important;z-index:40
+  }
+  /* Make room for the docked chat: shift the SPA workbench right + drop its
+     now-empty first grid column (the old embedded chat lived there). */
+  .vidfarm-workbench{margin-left:440px !important;grid-template-columns:minmax(0,1fr) !important}
+}
+.rk-aichat,.rk-fab{font-family:var(--rk-font-body)}
+
+/* ── Dark-mode the reused farmville chat dock so it matches the editor's dark
+   chrome. The reskin /reskin pages keep the light warm theme; this remap is
+   scoped to the editor dock only. Almost every dock surface reads a --rk-*
+   token, so remapping the token set here re-themes the panel wholesale; the
+   few hardcoded #fff backgrounds from the shared sheet are overridden below. */
+.rk-aichat.rk-aichat--editor{
+  --rk-white:#12160d;
+  --rk-surface:#0c0f08;--rk-bg:#0c0f08;--rk-bg-section:#0a0d07;
+  --rk-n-50:#0a0d07;--rk-n-100:#191d12;--rk-n-200:#262b1a;--rk-n-300:#333a24;
+  --rk-n-400:#6b7057;--rk-n-500:#8f9472;--rk-n-600:#b7bd97;--rk-n-700:#dcddc4;--rk-n-800:#eceada;
+  --rk-ink:#fffbe6;--rk-text:#e7e6cd;--rk-text-muted:#9a9d80;--rk-text-faint:#71745c;
+  --rk-border:rgba(255,251,230,.10);--rk-border-strong:rgba(255,251,230,.20);
+  --rk-gold-tint:rgba(252,185,0,.14);--rk-gold-tint2:rgba(252,185,0,.22);
+  --rk-shadow-xs:0 1px 2px 0 rgba(0,0,0,.4);
+  background:#0c0f08;
+}
+/* surfaces hardcoded #fff in the shared sheet → dark cards on the editor dock */
+.rk-aichat--editor .rk-aichat-msg.is-ai,
+.rk-aichat--editor .rk-aichat-composer,
+.rk-aichat--editor .rk-aichat-tool,
+.rk-aichat--editor .rk-aichat-back,
+.rk-aichat--editor .rk-aichat-fstate button,
+.rk-aichat--editor .rk-aichat-drop,
+.rk-aichat--editor .rk-aichat-toolnote,
+.rk-aichat--editor .rk-aichat-http,
+.rk-aichat--editor .rk-input,
+.rk-aichat--editor .rk-aichat-loadmore{background:#141810}
+.rk-aichat--editor .rk-aichat-back:hover{background:#1b2013}
+.rk-aichat--editor .rk-aichat-loadmore:hover{background:#1b2013}
+.rk-aichat--editor .rk-input{color:var(--rk-ink)}
+.rk-aichat--editor .rk-aichat-frow:hover,
+.rk-aichat--editor .rk-aichat-hist-body .rk-aichat-frow.is-active{background:#1b2013}
+.rk-aichat--editor .rk-aichat-err{background:#141810;color:#ff9b8f}
+.rk-aichat--editor .rk-aichat-toolnote.is-ok{color:#7ee2a8}
+.rk-aichat--editor .rk-aichat-toolnote.is-ok::before{background:#33d17a}
+.rk-aichat--editor .rk-aichat-toolnote.is-err{color:#ff9b8f}
+.rk-aichat--editor .rk-aichat-toolnote.is-err::before{background:#ff6a5a}
+
+/* Hide the SPA's own embedded chat (replaced by the farmville dock). */
+.chat-dock,.chat-dock-fab{display:none !important}
+`;
 async function renderHyperframesStudioEditorPage(input) {
     const accountId = input.customer?.id ?? null;
     const compositionId = input.composition.templateId ?? input.composition.slugId;
@@ -4836,6 +5402,8 @@ async function renderHyperframesStudioEditorPage(input) {
         slugId: input.composition.slugId,
         templateId: input.composition.templateId,
         title: input.composition.title,
+        // "raw" = the user's own new/blank project — never auto-prompt Decompose.
+        origin: input.composition.origin ?? null,
         originalUrl: input.composition.originalUrl ?? null,
         songName: input.composition.songName ?? null,
         songUrl: input.composition.songUrl ?? null,
@@ -4857,17 +5425,24 @@ async function renderHyperframesStudioEditorPage(input) {
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>${escapeHtml(input.composition.title)} | Studio</title>
-  <link rel="preconnect" href="https://fonts.googleapis.com" />
-  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <title>${escapeHtml(input.composition.title)} | VidFarm Studio</title>
   <link rel="icon" href="/assets/favicon.ico" />
   <link rel="stylesheet" href="/assets/editor/app.css" />
-  <style>html,body{margin:0;background:#050604;color:#fffbe6;}#root{min-height:100vh;}</style>
+  ${RESKIN_FONT_LINKS}
+  <style>${RESKIN_CSS}</style>
+  <style>${EDITOR_FARMVILLE_CSS}</style>
   <script src="/assets/sentry-config.js"></script>
 </head>
-<body>
+<body data-rk-editor-dock>
   <div id="root"></div>
+  ${renderChatDock("editor")}
   <script id="hf-boot" type="application/json">${escapeJsonForHtml(boot)}</script>
+  <script>${RESKIN_CHROME_SCRIPT}</script>
+  <!-- Files drawer of the editor dock = the reusable directory-explorer component,
+       auto-mounts [data-rk-directory] (#rkAichatFilesMount). reskinDocument ships
+       this bundle on full-chrome pages, but the editor builds its own document, so
+       it must be loaded here too or the "Your files" panel mounts empty. -->
+  <script type="module" src="/assets/file-directory-app.js"></script>
   <script type="module" src="/assets/editor/app.js"></script>
 </body>
 </html>`;
@@ -4914,7 +5489,11 @@ app.get("/", async (c) => {
 // Each page is a standalone document with its own CSS; renders sample data so
 // it's viewable without auth. Ported pages are wired here one at a time.
 app.get("/reskin", (c) => c.html(renderReskinIndex()));
-app.get("/settings", async (c) => {
+// Settings lives at /settings/<tab> (profile · wallet · channels · developer).
+// Tabs still switch client-side without a reload (the page renders every panel
+// and toggles visibility) but each has its own canonical URL so links,
+// bookmarks and back/forward land on the right tab.
+async function renderSettingsTabPage(c, tabOverride) {
     const customer = await requireBrowserCustomer(c);
     if (!customer) {
         setLoginReturnPath(c, currentPathWithSearch(c));
@@ -4922,11 +5501,12 @@ app.get("/settings", async (c) => {
     }
     const flash = consumeSettingsFlash(c);
     const flockPosterApiKey = customer.flockposterApiKey?.trim() || null;
-    const activeTab = flash?.tab === "wallet" || flash?.tab === "channels" || flash?.tab === "developer"
-        ? flash.tab
-        : c.req.query("tab") === "wallet" || c.req.query("tab") === "channels" || c.req.query("tab") === "developer"
-            ? c.req.query("tab")
-            : "profile";
+    const activeTab = tabOverride
+        ?? (isSettingsTab(flash?.tab)
+            ? flash.tab
+            : isSettingsTab(c.req.query("tab"))
+                ? c.req.query("tab")
+                : "profile");
     const directorSkill = readRootSkillFile("SKILL.director.md", "SKILL.user.md");
     const emailChannels = await getEmailPseudoChannels(customer.id, c);
     const [wallet, walletEvents] = await Promise.all([
@@ -4975,8 +5555,22 @@ app.get("/settings", async (c) => {
         })),
         attachments: (await serverlessRecords.listUserAttachments(customer.id)).map((attachment) => serializeUserAttachment(c, attachment))
     }));
-});
-// Library hosts two tabs at distinct URLs (approved projects + mined clips).
+}
+// Bare /settings redirects to its canonical first tab; legacy ?tab= / ?connect=
+// links are preserved by folding them into the path/query of the target.
+app.get("/settings", (c) => {
+    const q = c.req.query("tab");
+    const tab = isSettingsTab(q) ? q : "profile";
+    const connect = c.req.query("connect");
+    const path = connect ? `/settings/${tab}?connect=${encodeURIComponent(connect)}` : `/settings/${tab}`;
+    return redirect(c, withAccountQuery(path, getRequestedAccountId(c)));
+});
+app.get("/settings/profile", (c) => renderSettingsTabPage(c, "profile"));
+app.get("/settings/wallet", (c) => renderSettingsTabPage(c, "wallet"));
+app.get("/settings/channels", (c) => renderSettingsTabPage(c, "channels"));
+app.get("/settings/developer", (c) => renderSettingsTabPage(c, "developer"));
+// Library hosts tabs at distinct URLs: Approved projects, mined Raws, and the
+// full-page Files directory explorer (plus a right-floated Logs button → /library/logs).
 app.get("/library", (c) => redirect(c, "/library/approved"));
 const reskinLibraryHandler = async (c, tab) => {
     const customer = await getPreferredBrowserCustomer(c);
@@ -4984,6 +5578,27 @@ const reskinLibraryHandler = async (c, tab) => {
         setLoginReturnPath(c, currentPathWithSearch(c));
         return redirect(c, "/login");
     }
+    // Files is the self-contained directory explorer (client-fetches /me/directory),
+    // so it needs none of the posts/channels payload — skip that comparatively
+    // expensive work for it.
+    if (tab === "files") {
+        return c.html(renderReskinLibrary(tab, {
+            userId: customer.id,
+            currentAccountId: customer.id,
+            name: customer.name,
+            email: customer.email,
+            posts: [],
+            schedule: { channels: [], connectHref: "/settings/channels?connect=flockposter" },
+            editorChat: null,
+            // On a `vidfarm serve` box with a cloud upstream, offer the Local ⇄ Cloud
+            // space switch in the explorer (reads /me/cloud/directory passthrough).
+            cloudSpace: isUpstreamEnabled(),
+            // ?path= deep-links the explorer into a folder (e.g. ?path=/approved/swipes).
+            // Safe raw: the client's parseDirectoryPath only honors the known roots and
+            // drops anything else back to the virtual root "/".
+            initialFilesPath: (c.req.query("path") ?? "").trim() || undefined
+        }));
+    }
     const emailChannels = await getEmailPseudoChannels(customer.id, c);
     const flockPoster = await getFlockPosterChannels(customer.flockposterApiKey?.trim() || null);
     const scheduleChannels = [
@@ -4993,7 +5608,12 @@ const reskinLibraryHandler = async (c, tab) => {
     const localPosts = await Promise.all((await serverlessRecords.listReadyPosts(customer.id))
         .filter((post) => (post.source ?? "legacy") === "hyperframes")
         .filter((post) => post.status === "ready" || post.status === "scheduled")
-        .map(async (post) => ({ ...serializeReadyPost(c, post, { includePrivate: true }), template_id: post.compositionId ?? null })));
+        .map(async (post) => {
+        // Backfill the rendered MP4 for swipe-approved posts whose detached
+        // finalize poll died on Lambda before it could attach the media.
+        const reconciled = await reconcileReadyPostMedia(customer.id, post);
+        return { ...serializeReadyPost(c, reconciled, { includePrivate: true }), template_id: reconciled.compositionId ?? null };
+    }));
     const posts = await mergeUpstreamReadyPosts(localPosts);
     return c.html(renderReskinLibrary(tab, {
         userId: customer.id,
@@ -5001,23 +5621,114 @@ const reskinLibraryHandler = async (c, tab) => {
         name: customer.name,
         email: customer.email,
         posts,
-        schedule: { channels: scheduleChannels, connectHref: "/settings?tab=channels&connect=flockposter" },
+        schedule: { channels: scheduleChannels, connectHref: "/settings/channels?connect=flockposter" },
         editorChat: null
     }));
 };
 app.get("/library/approved", (c) => reskinLibraryHandler(c, "approved"));
 app.get("/library/raws", (c) => reskinLibraryHandler(c, "raws"));
-app.get("/library/logs", (c) => reskinLibraryHandler(c, "logs")); // job-runs, folded in
+app.get("/library/logs", (c) => reskinLibraryHandler(c, "logs")); // job-runs, floated-right button (not a tab)
+app.get("/library/files", (c) => reskinLibraryHandler(c, "files")); // full-page file-directory explorer
 app.get("/library/clips", (c) => redirect(c, "/library/raws")); // renamed Clips → Raws
-// Discover has three modes selected via ?view= (feed default / swipe / categories).
-// Path segments are avoided because /discover/feed, /discover/swipe/* are JSON APIs.
+// Discover has three modes, each on its own path: /discover (feed default),
+// /discover/swipe, /discover/categories. These exact page paths sit alongside
+// the JSON APIs at /discover/feed, /discover/popular and /discover/swipe/*
+// (which are all deeper/other paths, so there's no collision).
+// Shared feed builder — the single source of both the JSON /discover/feed
+// response and the SSR seed inlined into the reskin Feed page's boot. Feed
+// browses INSPIRATIONS (the caller's OWN inspirations plus the curated
+// popularGroup catalog), never the global public pool; raw own-projects are
+// excluded (they live in the Library). NOTE: for a logged-in caller this
+// finalizes still-downloading inspirations as a side effect — the feed poll
+// doubles as the completion check.
+async function collectDiscoverFeedEntries(customer, opts) {
+    const { query, limit } = opts;
+    const entries = [];
+    const seenInspirations = new Set();
+    const pushInspiration = (inspiration) => {
+        if (seenInspirations.has(inspiration.id))
+            return;
+        if ((inspiration.origin ?? "inspiration") === "raw")
+            return;
+        seenInspirations.add(inspiration.id);
+        entries.push(buildInspirationFeedEntry(inspiration));
+    };
+    if (customer) {
+        // The caller's own inspirations rank first (finalized → "ready" here).
+        const ownInspirations = (await serverlessRecords.listInspirationsForCustomer(customer.id));
+        const finalized = await Promise.all(ownInspirations.map(finalizeInspirationIfReady));
+        finalized
+            .filter((inspiration) => recordMatchesSearchQuery(inspiration, query))
+            .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
+            .forEach(pushInspiration);
+    }
+    // Curated/official catalog: public, ready inspirations flagged popularGroup.
+    const curated = (await serverlessRecords.listInspirationsFeed({ limit, query }))
+        .filter((inspiration) => typeof inspiration.popularGroup === "string" && inspiration.popularGroup.trim().length > 0);
+    curated.forEach(pushInspiration);
+    // Cloud passthrough (vidfarm serve): surface the upstream Feed behind the
+    // local one, deduped on inspirationId (→ templateId). Fail-soft.
+    if (isUpstreamEnabled()) {
+        const search = new URLSearchParams({ limit: String(limit) });
+        if (query)
+            search.set("q", query);
+        const upstreamFeed = (await upstreamJson(`/discover/feed?${search.toString()}`)).json?.templates ?? [];
+        const seen = new Set(entries.map((entry) => entry.inspirationId || entry.templateId));
+        for (const entry of upstreamFeed) {
+            const key = entry && (entry.inspirationId || entry.templateId);
+            if (entry && typeof key === "string" && key && !seen.has(key) && entry.origin !== "raw") {
+                entries.push(entry);
+                seen.add(key);
+            }
+        }
+    }
+    return entries.slice(0, limit);
+}
+const renderDiscoverMode = async (c, mode) => {
+    const customer = await getOptionalPreferredBrowserCustomer(c);
+    let feedInitial;
+    let feedFetchedAt;
+    if (mode === "feed") {
+        // SSR-seed the first page of the default feed into the boot so the client
+        // paints instantly, skipping the redundant follow-up fetch. Fail-soft: on
+        // any error we omit the seed and the client cold-fetches as before. The
+        // limit mirrors the client's un-parameterized fetch (clampPageLimit → 100).
+        try {
+            feedInitial = await collectDiscoverFeedEntries(customer, { query: null, limit: clampPageLimit(Number.NaN, 100, 200) });
+            feedFetchedAt = new Date().toISOString();
+        }
+        catch {
+            feedInitial = undefined;
+        }
+    }
+    return c.html(renderReskinDiscover(mode, {
+        accountId: customer?.id,
+        isLoggedIn: Boolean(customer),
+        name: customer?.name ?? null,
+        email: customer?.email ?? null,
+        feedInitial,
+        feedFetchedAt
+    }));
+};
 app.get("/discover", async (c) => {
+    // Every mode has its own canonical path — Feed included — so redirect the bare
+    // /discover (and old ?view= links) onto it. Feed then lives at /discover/feed,
+    // which content-negotiates: browser navigations get the page, fetch/API get
+    // the JSON feed (see the /discover/feed handler below).
     const view = c.req.query("view");
-    const mode = view === "swipe" || view === "categories" ? view : "feed";
-    const customer = await getOptionalPreferredBrowserCustomer(c);
-    return c.html(renderReskinDiscover(mode, { accountId: customer?.id, isLoggedIn: Boolean(customer) }));
-});
-app.get("/chat", async (c) => {
+    const account = c.req.query(ACCOUNT_QUERY_PARAM);
+    const suffix = account ? `?${ACCOUNT_QUERY_PARAM}=${encodeURIComponent(account)}` : "";
+    if (view === "swipe" || view === "categories") {
+        return redirect(c, `/discover/${view}${suffix}`);
+    }
+    return redirect(c, `/discover/feed${suffix}`);
+});
+app.get("/discover/swipe", (c) => renderDiscoverMode(c, "swipe"));
+app.get("/discover/categories", (c) => renderDiscoverMode(c, "categories"));
+// Brainstorm chat. /chat is a fresh conversation; /chat/:id deep-links to a
+// saved thread (the client auto-opens it and keeps the URL in sync as the user
+// switches / starts conversations).
+const renderChatBrainstorm = async (c, initialThreadId) => {
     const customer = await getPreferredBrowserCustomer(c);
     if (!customer) {
         setLoginReturnPath(c, currentPathWithSearch(c));
@@ -5029,11 +5740,33 @@ app.get("/chat", async (c) => {
         name: customer.name,
         email: customer.email,
         editorChat: await buildChatBrainstormEditorChatBoot({ customer })
-    }));
-});
-// /reskin/inpaint — the "Create Image" masked-image editor (reached from the
-// chat page's studio-mode select). Auth-gated like the other tools.
-app.get("/inpaint", async (c) => {
+    }, { initialThreadId: initialThreadId ?? null }));
+};
+app.get("/chat", (c) => renderChatBrainstorm(c));
+app.get("/chat/:id", (c) => renderChatBrainstorm(c, c.req.param("id")));
+// Boot for the global pop-panel AI chat (renderChatDock, on every reskin page).
+// The dock is shared chrome so we can't thread a boot through every route —
+// instead it fetches this lazily on first open (cookie-authed, same-origin) to
+// get the real editor-chat endpoint + api key + brainstorm template context.
+// Returns { editorChat: null } for signed-out visitors so the dock degrades to
+// a friendly "sign in to chat" state instead of erroring.
+app.get("/chat-dock/boot", async (c) => {
+    const customer = await getOptionalPreferredBrowserCustomer(c);
+    if (!customer)
+        return c.json({ editorChat: null });
+    return c.json({ editorChat: await buildChatBrainstormEditorChatBoot({ customer }) });
+});
+// The creative tools are three twins under /tools: /tools/image (masked image
+// edits), /tools/video (start/end-frame + time-scoped video edits), and
+// /tools/clipper (subrange-clip a source video into the raws library). The bare
+// /tools redirects to the image editor, preserving any ?source_image_url /
+// ?tracer preload params. The legacy /inpaint/* paths 302 here for back-compat
+// so existing deep-links (and editor "Edit Media") keep working.
+app.get("/tools", (c) => {
+    const search = new URL(c.req.url).search;
+    return redirect(c, "/tools/image" + search);
+});
+app.get("/tools/image", async (c) => {
     const customer = await getOptionalPreferredBrowserCustomer(c);
     if (!customer) {
         setLoginReturnPath(c, currentPathWithSearch(c));
@@ -5041,6 +5774,27 @@ app.get("/inpaint", async (c) => {
     }
     return c.html(renderReskinInpaint({ accountId: customer.id, isLoggedIn: true }));
 });
+app.get("/tools/video", async (c) => {
+    const customer = await getOptionalPreferredBrowserCustomer(c);
+    if (!customer) {
+        setLoginReturnPath(c, currentPathWithSearch(c));
+        return redirect(c, "/login");
+    }
+    return c.html(renderReskinInpaintVideo({ accountId: customer.id, isLoggedIn: true }));
+});
+app.get("/tools/clipper", async (c) => {
+    const customer = await getOptionalPreferredBrowserCustomer(c);
+    if (!customer) {
+        setLoginReturnPath(c, currentPathWithSearch(c));
+        return redirect(c, "/login");
+    }
+    return c.html(renderReskinInpaintClipper({ accountId: customer.id, isLoggedIn: true }));
+});
+// Legacy /inpaint/* → /tools/* back-compat redirects (preserve query string).
+app.get("/inpaint", (c) => redirect(c, "/tools/image" + new URL(c.req.url).search));
+app.get("/inpaint/image", (c) => redirect(c, "/tools/image" + new URL(c.req.url).search));
+app.get("/inpaint/video", (c) => redirect(c, "/tools/video" + new URL(c.req.url).search));
+app.get("/inpaint/clipper", (c) => redirect(c, "/tools/clipper" + new URL(c.req.url).search));
 app.get("/calendar", async (c) => {
     const customer = await requireBrowserCustomer(c);
     if (!customer) {
@@ -5065,7 +5819,7 @@ app.get("/calendar", async (c) => {
         posts: [],
         loadEndpoint: withAccountQuery("/calendar/feed", customer.id),
         hasFlockPosterKey: Boolean(flockPosterApiKey || emailChannels.length),
-        connectChannelsHref: "/settings?tab=channels&connect=flockposter"
+        connectChannelsHref: "/settings/channels?connect=flockposter"
     }));
 });
 // Job runs were renamed and folded into the Library "Logs" tab.
@@ -5166,10 +5920,10 @@ app.get("/reskin/clips", (c) => redirect(c, "/library/raws"));
 app.get("/reskin/discover", (c) => redirect(c, "/discover"));
 app.get("/reskin/discover/:mode", (c) => {
     const m = c.req.param("mode");
-    return redirect(c, m === "swipe" || m === "categories" ? `/discover?view=${m}` : "/discover");
+    return redirect(c, m === "swipe" || m === "categories" ? `/discover/${m}` : "/discover");
 });
 app.get("/reskin/chat", (c) => redirect(c, "/chat"));
-app.get("/reskin/inpaint", (c) => redirect(c, "/inpaint"));
+app.get("/reskin/inpaint", (c) => redirect(c, "/tools/image"));
 app.get("/reskin/calendar", (c) => redirect(c, "/calendar"));
 app.get("/reskin/job-runs", (c) => redirect(c, "/library/logs"));
 app.get("/reskin/agency", (c) => redirect(c, "/agency"));
@@ -5177,9 +5931,74 @@ app.get("/reskin/pricing", (c) => redirect(c, "/pricing"));
 app.get("/reskin/help", (c) => redirect(c, "/help"));
 app.get("/reskin/login", (c) => redirect(c, "/login"));
 app.get("/discover", async (c) => renderApprovedHomepage(c));
-app.get("/editor/:templateId", async (c) => {
-    const templateId = c.req.param("templateId");
+// The sentinel composition/template id for a brand-new blank project. It never
+// collides with a real template (those are `template_<uuid>`). Pre-fork it is
+// served the canonical blank scaffold (buildBlankCompositionHtml); on first edit
+// the SPA POSTs it as the fork `source`, minting a per-user fork seeded from
+// that same scaffold — so "every new blank is a fork of the blank composition".
+const BLANK_COMPOSITION_ID = "original";
+// Blank / new-project editor. The "New project" button and the empty-library
+// CTAs point here. There is no template or fork yet: we boot the SPA into the
+// canonical blank composition (3 placeholder scenes), and the client mints a
+// fork_* seeded from it on the first save/generate/decompose, then
+// history.replaceState's the URL to the /editor/original/fork/:forkId form.
+async function renderBlankEditorPage(c, titleOverride) {
+    const customer = await getOptionalPreferredBrowserCustomer(c);
+    if (!customer) {
+        setLoginReturnPath(c, currentPathWithSearch(c));
+        return redirect(c, "/login");
+    }
+    const threadParam = c.req.query("thread");
+    const blankComposition = {
+        title: titleOverride?.trim() || "Untitled project",
+        templateId: "original",
+        slugId: "original",
+        difficulty: "easy",
+        viralDna: "",
+        previewUrl: null,
+        approvedAt: null,
+        sourceType: "tiktok",
+        durationSeconds: null,
+        originalUrl: null,
+        songName: null,
+        songUrl: null,
+        // Raw origin: a brand-new project, so the SPA never auto-opens Decompose.
+        origin: "raw",
+        initialThreadId: threadParam ?? null
+    };
+    return c.html(await renderHyperframesStudioEditorPage({ composition: blankComposition, customer }));
+}
+// Reload / direct-load of a blank project's own fork URL (/editor/original/fork/
+// <forkId>) after the SPA minted it. There is no template to resolve — we just
+// confirm the caller owns this blank fork, then render the same blank editor
+// shell (the SPA reads the forkId from the URL and the player loads the fork's
+// stored composition via ?fork=). Anything stale/foreign falls back to a fresh
+// blank so the user never lands on a 404.
+async function renderBlankForkEditorPage(c, forkParam) {
+    const customer = await getOptionalPreferredBrowserCustomer(c);
+    if (!customer) {
+        setLoginReturnPath(c, currentPathWithSearch(c));
+        return redirect(c, "/login");
+    }
+    if (forkParam) {
+        const fork = await serverlessRecords.getCompositionFork(forkParam);
+        if (fork && !fork.deletedAt && fork.customerId === customer.id && fork.templateId === BLANK_COMPOSITION_ID) {
+            return renderBlankEditorPage(c, fork.title ?? undefined);
+        }
+    }
+    return redirect(c, "/editor/original/fork/new");
+}
+// Shared handler for both the bare /editor/:templateId (resolver) route and the
+// canonical /editor/:templateId/fork/:forkId (path-form) route. `forkParam` is
+// the fork id from the URL path (path route) or null (bare route). We validate
+// it, and when it's missing/stale/uneditable we resolve a per-user fork and
+// redirect to the canonical path form.
+async function renderEditorPage(c, templateId, forkParam) {
     const customer = await getOptionalPreferredBrowserCustomer(c);
+    // Blank project forks carry the sentinel templateId, not a real template_*.
+    // Route them to the blank-fork renderer instead of 404'ing.
+    if (templateId === BLANK_COMPOSITION_ID)
+        return renderBlankForkEditorPage(c, forkParam);
     if (!templateId.startsWith("template_"))
         return c.notFound();
     let template = await serverlessRecords.getTemplate(templateId);
@@ -5191,7 +6010,7 @@ app.get("/editor/:templateId", async (c) => {
         await seedFromUpstream({
             customerId: customer.id,
             templateId,
-            forkId: c.req.query("fork") ?? undefined,
+            forkId: forkParam ?? undefined,
             shareToken: readShareToken(c) ?? undefined
         });
         template = await serverlessRecords.getTemplate(templateId);
@@ -5202,7 +6021,6 @@ app.get("/editor/:templateId", async (c) => {
     // template id doesn't leak to other accounts.
     if (template.visibility === "private" && template.customerId !== customer?.id)
         return c.notFound();
-    const forkParam = c.req.query("fork");
     const threadParam = c.req.query("thread");
     // Validate the caller-provided fork. Stale bookmarks / share links keep
     // pointing at forks we've since hard-deleted, and if we blindly pass the
@@ -5279,11 +6097,11 @@ app.get("/editor/:templateId", async (c) => {
             // source of truth for "which chat is active" via localStorage. Injecting
             // the server's most-recent thread into the URL blows away a fresh
             // client-side "New chat" the user just started but hasn't persisted.
-            const path = `/editor/${encodeURIComponent(template.id)}?fork=${encodeURIComponent(targetForkId)}`;
+            const path = `/editor/${encodeURIComponent(template.id)}/fork/${encodeURIComponent(targetForkId)}`;
             return redirect(c, path);
         }
         // No fork exists yet for this template + user — redirect to the bare
-        // /editor/{templateId} URL so any stale `?fork=` gets stripped and the
+        // /editor/{templateId} URL so any stale fork segment gets stripped and the
         // Decompose modal opens fresh (client-side flow mints a new fork on
         // first save/decompose).
         if (forkParam) {
@@ -5310,9 +6128,31 @@ app.get("/editor/:templateId", async (c) => {
         initialThreadId: threadParam ?? null
     };
     return c.html(await renderHyperframesStudioEditorPage({ composition: syntheticComposition, customer }));
+}
+// Canonical path-form editor route. Sentinel /editor/original/fork/new opens a
+// blank new project; everything else validates/resolves the fork in the path.
+app.get("/editor/:templateId/fork/:forkId", async (c) => {
+    const templateId = c.req.param("templateId");
+    const forkId = c.req.param("forkId");
+    if (templateId === "original" && forkId === "new") {
+        return renderBlankEditorPage(c);
+    }
+    return renderEditorPage(c, templateId, forkId);
+});
+// Bare editor route: resolves a per-user fork and redirects to the path form.
+app.get("/editor/:templateId", async (c) => {
+    const templateId = c.req.param("templateId");
+    return renderEditorPage(c, templateId, null);
 });
 app.get("/editor/:templateId/composition", async (c) => {
     const templateId = c.req.param("templateId");
+    // Blank new project: the SPA fetches this to seed its client-side timeline
+    // state. Serve the same canonical blank scaffold the player iframe gets (raw,
+    // no runtime — the studio only parses the clips out of it) so client state and
+    // the rendered player agree on element ids.
+    if (templateId === BLANK_COMPOSITION_ID) {
+        return c.html(buildBlankCompositionHtml(templateId), 200, { "cache-control": "no-store" });
+    }
     if (!templateId.startsWith("template_"))
         return c.notFound();
     const template = await serverlessRecords.getTemplate(templateId);
@@ -5336,17 +6176,40 @@ app.get(`${ACCOUNT_FRONTEND_PREFIX}`, (c) => redirect(c, withAccountQuery("/libr
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/discover`, (c) => redirectToPublicPath(c, "/discover"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/help`, (c) => redirectToPublicPath(c, "/help"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/chat`, (c) => dispatchScopedGetToLegacyRoute(c, "/chat"));
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/chat/:id`, (c) => dispatchScopedGetToLegacyRoute(c, `/chat/${c.req.param("id")}`));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/library`, (c) => dispatchScopedGetToLegacyRoute(c, "/library"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/clips`, (c) => dispatchScopedGetToLegacyRoute(c, "/clips"));
-app.get(`${ACCOUNT_FRONTEND_PREFIX}/inpaint`, (c) => dispatchScopedGetToLegacyRoute(c, "/inpaint"));
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/tools`, (c) => dispatchScopedGetToLegacyRoute(c, "/tools/image"));
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/tools/image`, (c) => dispatchScopedGetToLegacyRoute(c, "/tools/image"));
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/tools/video`, (c) => dispatchScopedGetToLegacyRoute(c, "/tools/video"));
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/tools/clipper`, (c) => dispatchScopedGetToLegacyRoute(c, "/tools/clipper"));
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/inpaint`, (c) => dispatchScopedGetToLegacyRoute(c, "/tools/image"));
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/inpaint/image`, (c) => dispatchScopedGetToLegacyRoute(c, "/tools/image"));
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/inpaint/video`, (c) => dispatchScopedGetToLegacyRoute(c, "/tools/video"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/calendar`, (c) => dispatchScopedGetToLegacyRoute(c, "/calendar"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/settings`, (c) => dispatchScopedGetToLegacyRoute(c, "/settings"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/job-runs`, (c) => dispatchScopedGetToLegacyRoute(c, "/job-runs"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/job-runs/history`, (c) => dispatchScopedGetToLegacyRoute(c, "/job-runs/history"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/calendar/feed`, (c) => dispatchScopedGetToLegacyRoute(c, "/calendar/feed"));
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/settings/flockposter`, (c) => dispatchScopedGetToLegacyRoute(c, "/settings/flockposter"));
+// Per-tab settings pages under an account scope (registered AFTER the static
+// /settings/flockposter route so that stays reachable).
+app.get(`${ACCOUNT_FRONTEND_PREFIX}/settings/:tab`, (c) => {
+    const tab = c.req.param("tab");
+    return dispatchScopedGetToLegacyRoute(c, `/settings/${isSettingsTab(tab) ? tab : "profile"}`);
+});
 app.post(`${ACCOUNT_FRONTEND_PREFIX}/settings/wallet/funding-link`, (c) => dispatchScopedPostToLegacyRoute(c, "/settings/wallet/funding-link"));
 app.get("/discover/feed", async (c) => {
+    // Content negotiation: a browser NAVIGATION to /discover/feed (Accept:
+    // text/html) renders the Feed page — this is the canonical Feed URL now that
+    // /discover redirects here. Everything else (the in-page loader, which sends
+    // Accept: application/json, plus agents/devcli/upstream passthrough) falls
+    // through to the JSON feed below. The two never collide because the page's
+    // own fetch is explicitly application/json.
+    const acceptHeader = (c.req.header("accept") || "").toLowerCase();
+    if (acceptHeader.includes("text/html") && !acceptHeader.includes("application/json")) {
+        return renderDiscoverMode(c, "feed");
+    }
     const limit = clampPageLimit(Number(c.req.query("limit") || ""), 100, 200);
     // Optional keyword search so callers (UI, agents, devcli) can ask "which
     // templates suit my <offer>?" and get a ranked subset instead of the full
@@ -5354,66 +6217,12 @@ app.get("/discover/feed", async (c) => {
     // decompose-derived promotions/keywords/summary.
     const query = (c.req.query("q") || c.req.query("query") || "").trim() || null;
     const customer = await getOptionalPreferredBrowserCustomer(c);
-    const templateEntries = [];
-    if (customer) {
-        // The caller's own private submissions rank above the public catalog.
-        // Finalizing pending inspirations here is what mints the private template
-        // as soon as the download job completes — the feed poll doubles as the
-        // completion check.
-        const ownInspirations = (await serverlessRecords.listInspirationsForCustomer(customer.id))
-            .filter((inspiration) => inspiration.visibility === "private");
-        const finalized = await Promise.all(ownInspirations.map(finalizeInspirationIfReady));
-        const ownTemplates = (await serverlessRecords.listTemplatesForCustomer(customer.id))
-            .filter((template) => template.visibility === "private")
-            .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
-        const pending = finalized
-            .filter((inspiration) => !inspiration.templateId)
-            .filter((inspiration) => recordMatchesSearchQuery(inspiration, query))
-            .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
-        for (const inspiration of pending) {
-            templateEntries.push(buildPendingInspirationHomepageEntry(inspiration));
-        }
-        for (const template of ownTemplates.filter((template) => recordMatchesSearchQuery(template, query))) {
-            const entry = buildTemplateHomepageEntry(template);
-            if (entry)
-                templateEntries.push(entry);
-        }
-    }
-    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);
-    }
-    // Cloud passthrough (vidfarm serve): the local records are just the working
-    // set of seeded templates, so surface the upstream (cloud) catalog behind
-    // them. Local entries win on id conflicts — a seeded template also exists
-    // upstream and the local copy reflects any local edits. Fail-soft: an
-    // unreachable upstream degrades to the local-only feed.
-    if (isUpstreamEnabled()) {
-        const search = new URLSearchParams({ limit: String(limit) });
-        if (query)
-            search.set("q", query);
-        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) && !entry.popularGroup) {
-                templateEntries.push(entry);
-                seen.add(entry.templateId);
-            }
-        }
-    }
-    // The public feed is identical for every caller, but a logged-in response
-    // interleaves the caller's private templates — never let a shared cache
-    // serve that to someone else.
+    const entries = await collectDiscoverFeedEntries(customer, { query, limit });
+    // The Feed interleaves the caller's own inspirations, so a logged-in response
+    // must never be served from a shared cache.
     c.header("cache-control", customer ? "private, max-age=10" : "public, max-age=60");
     return c.json({
-        templates: templateEntries,
+        templates: entries,
         next_cursor: null
     });
 });
@@ -5562,8 +6371,40 @@ function injectSwipePreviewFit(doc, cardId) {
       function play() {
         try { if (window.__player) { window.__player.play(); } } catch (e) {}
       }
+      // The runtime paints video through a single backing <video> whose CSS
+      // background is near-black, so until a frame decodes the card shows solid
+      // black behind the captions. Drive that element directly as a
+      // belt-and-suspenders fallback: a muted backing video may autoplay even
+      // if the runtime's own play() was swallowed, and forcing a load()/frame
+      // decode guarantees the first frame paints instead of the black
+      // background — many source clips fade in from black, so we also nudge a
+      // hair off 0 to avoid parking on a dark intro frame.
+      var backingVideo = document.querySelector('[data-vf-playback-source]');
+      var framePainted = false;
+      function kickBackingVideo() {
+        if (!backingVideo) return;
+        try { backingVideo.muted = true; backingVideo.playsInline = true; } catch (e) {}
+        try { if (backingVideo.readyState < 2) { backingVideo.load(); } } catch (e) {}
+        try { var p = backingVideo.play(); if (p && p.catch) { p.catch(function () {}); } } catch (e) {}
+      }
+      if (backingVideo) {
+        backingVideo.addEventListener('loadeddata', function () {
+          kickBackingVideo();
+          if (!framePainted) {
+            framePainted = true;
+            // Only nudge if the runtime hasn't already advanced playback.
+            try {
+              if (backingVideo.currentTime < 0.05 && (!window.__player || !window.__player.isPlaying())) {
+                backingVideo.currentTime = 0.12;
+              }
+            } catch (e) {}
+          }
+        });
+        backingVideo.addEventListener('canplay', kickBackingVideo);
+      }
       applySound(false);
       play();
+      kickBackingVideo();
       var lastWant = false;
       var stalled = 0;
       var mutedFallback = false;
@@ -5572,7 +6413,7 @@ function injectSwipePreviewFit(doc, cardId) {
           var want = wantSound();
           if (want !== lastWant) { lastWant = want; mutedFallback = false; stalled = 0; }
           applySound(want && !mutedFallback);
-          if (!window.__player || !window.__player.getDuration) { return; }
+          if (!window.__player || !window.__player.getDuration) { kickBackingVideo(); return; }
           var t = window.__player.getTime(), d = window.__player.getDuration();
           if (d > 0 && t >= d - 0.08) { window.__player.seek(0, { keepPlaying: true }); }
           else if (!window.__player.isPlaying()) {
@@ -5582,6 +6423,7 @@ function injectSwipePreviewFit(doc, cardId) {
             // the preview never freezes on a frame.
             if (stalled >= 3 && want && !mutedFallback) { mutedFallback = true; applySound(false); }
             play();
+            kickBackingVideo();
           } else { stalled = 0; }
         } catch (e) {}
       }, 400);
@@ -5658,6 +6500,12 @@ app.post("/discover/swipe/:id/approve", async (c) => {
         status: "ready",
         compositionId: fork.id,
         tracer: `swipe:${record.id}`,
+        // All approved swipe cuts collect into ONE canonical /approved/swipes folder.
+        // Without this explicit path the tracer-slug default would mint a unique
+        // per-swipe folder (swipe-swipe-<id>) — 1 post each — which is the clutter
+        // seen on /library/approved. The tracer still carries the swipe id for
+        // job-run correlation.
+        folderPath: "swipes",
         title: record.tailoredTitle,
         caption: record.tailoredCaption,
         pinnedComment: record.tailoredPinnedComment,
@@ -5766,6 +6614,50 @@ async function finalizeSwipeApproveRender(input) {
         }
     }
 }
+// Self-heal a ready post that is still missing its rendered media. Swipe-approve
+// mints the post with EMPTY media and relies on the fire-and-forget
+// finalizeSwipeApproveRender poll to backfill the finished MP4 — but that
+// detached poll does NOT survive a serverless/Lambda response, so on prod the
+// render completes (the Step Functions worker is durable) yet the MP4 is never
+// attached, and the library shows "No preview" forever. Reconciling on read
+// closes that gap: for any ready hyperframes post with no media, resolve its
+// fork's render job and attach the completed MP4 when the render has finished.
+// No-ops (short-circuits) once media exists, so a post is reconciled at most
+// once. Best-effort: any failure leaves the post untouched.
+async function reconcileReadyPostMedia(customerId, post) {
+    if (post.mediaAssets.length > 0)
+        return post;
+    if ((post.source ?? "legacy") !== "hyperframes" || !post.compositionId)
+        return post;
+    try {
+        const fork = await serverlessRecords.getCompositionFork(post.compositionId);
+        const renderJobId = fork?.currentRenderJobId;
+        if (!renderJobId)
+            return post;
+        const job = await jobs.getJobAsync(renderJobId);
+        const status = String(asRecord(job)?.status ?? "").toLowerCase();
+        if (status !== "succeeded" && status !== "completed")
+            return post;
+        const url = extractOutputUrlFromJob(job);
+        if (!url)
+            return post;
+        const slug = (post.title || "swipe-ad").replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "").toLowerCase().slice(0, 40) || "swipe-ad";
+        const asset = {
+            id: `render-${renderJobId}`,
+            url,
+            fileName: `${slug}.mp4`,
+            contentType: "video/mp4",
+            kind: "video",
+            role: "primary"
+        };
+        const updated = await serverlessRecords.setReadyPostMedia({ customerId, postId: post.id, mediaAssets: [asset] });
+        return updated ?? { ...post, mediaAssets: [asset] };
+    }
+    catch (error) {
+        console.error("ready-post media reconcile failed", post.id, error instanceof Error ? error.message : error);
+        return post;
+    }
+}
 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.
@@ -6091,6 +6983,36 @@ app.post("/discover/templates", async (c) => {
     });
     return c.json(serializeInspiration(inspiration), 202);
 });
+// Remix (decompose on demand): mint the template for a Feed inspiration the
+// moment the user chooses to open it. The Feed browses lightweight inspirations
+// with no template, so this is where a template is first created — for the
+// caller's own inspirations and for curated/public ones alike (a non-owner then
+// gets their own fork when the editor opens template_<id>). Idempotent: an
+// already-decomposed inspiration just returns its existing template id.
+app.post("/discover/inspirations/:id/decompose", async (c) => {
+    const customer = await requireBrowserCustomer(c);
+    if (!customer)
+        return c.json({ ok: false, error: "Log in to remix an inspiration." }, 401);
+    const inspiration = await serverlessRecords.getInspiration(c.req.param("id"));
+    if (!inspiration)
+        return c.json({ ok: false, error: "Inspiration not found." }, 404);
+    // Only the owner may open a PRIVATE inspiration; public/curated ones are
+    // remixable by anyone (the editor forks per-user on open).
+    if (inspiration.visibility === "private" && inspiration.customerId !== customer.id) {
+        return c.notFound();
+    }
+    if (inspiration.templateId) {
+        return c.json({ ok: true, templateId: inspiration.templateId });
+    }
+    if (inspiration.status !== "ready" || !inspiration.videoUrl) {
+        return c.json({ ok: false, error: "This inspiration is still processing — try again in a moment." }, 409);
+    }
+    const decomposed = await mintTemplateForInspiration(inspiration);
+    if (!decomposed.templateId) {
+        return c.json({ ok: false, error: "Could not prepare this inspiration for editing." }, 500);
+    }
+    return c.json({ ok: true, templateId: decomposed.templateId });
+});
 // Delete a private discover entry the caller owns. Accepts either the minted
 // template id (template_...) or the raw inspiration id (inspiration_..., i.e.
 // a still-processing/failed card) and removes both records. Public catalog
@@ -6144,6 +7066,51 @@ app.delete("/discover/templates/:entryId", async (c) => {
 // on its owner's /discover as a placeholder card so the Add Template flow has
 // immediate feedback. It has no template yet, so the editor CTA is disabled
 // client-side via status.
+// Feed card for a single INSPIRATION (Feed browses inspirations, not templates).
+// Lightweight: no template is required. If the inspiration has already minted a
+// template (templateId set), the card opens the editor directly; otherwise the
+// card previews the source video and its CTA decomposes on demand (preview →
+// Remix). Covers ready / downloading / failed states in one shape.
+function buildInspirationFeedEntry(inspiration) {
+    const isReady = inspiration.status === "ready";
+    const isFailed = inspiration.status === "failed";
+    const title = (inspiration.sourceHost === "upload"
+        ? (inspiration.title || inspiration.trendTagline)
+        : (inspiration.trendTagline || inspiration.title)) || inspiration.sourceHost || "New inspiration";
+    // Prefer the raw source video so the Feed + TikTok viewer actually play; fall
+    // back to the poster thumbnail (image) when the video URL isn't available yet.
+    const previewUrl = inspiration.videoUrl || inspiration.thumbnailUrl || "";
+    const viralDna = isFailed
+        ? (inspiration.errorMessage || "Video ingest failed. Try adding it again.")
+        : isReady
+            ? (inspiration.notes || inspiration.searchSummary || inspiration.trendTagline
+                || `A proven viral ${inspiration.sourceHost || "social"} post. Preview it, then remix it into an ad for your product.`)
+            : (inspiration.notes || (inspiration.sourceHost === "upload"
+                ? "Processing your uploaded video. This card unlocks automatically once it's ready."
+                : "Downloading the source video. This card unlocks automatically once it's ready."));
+    return {
+        title,
+        // Real template id when already decomposed; "" means "decompose on open".
+        templateId: inspiration.templateId ?? "",
+        inspirationId: inspiration.id,
+        slugId: inspiration.templateId ?? inspiration.id,
+        difficulty: "easy",
+        viralDna,
+        previewUrl,
+        approvedAt: inspiration.createdAt,
+        sourceType: inspiration.sourceHost || "social",
+        durationSeconds: inspiration.durationSeconds ?? null,
+        promotions: inspiration.promotions ?? null,
+        keywords: inspiration.keywords ?? null,
+        summary: inspiration.searchSummary ?? null,
+        visibility: inspiration.visibility,
+        origin: inspiration.origin ?? "inspiration",
+        popularGroup: inspiration.popularGroup ?? null,
+        popularRank: inspiration.popularRank ?? null,
+        notes: inspiration.notes,
+        status: isFailed ? "failed" : isReady ? "ready" : "processing"
+    };
+}
 function buildPendingInspirationHomepageEntry(inspiration) {
     return {
         // Uploads: explicit title (or file name, stored at submit time) outranks
@@ -6208,6 +7175,23 @@ app.delete(`${ACCOUNT_FRONTEND_PREFIX}/approved/posts/:postId`, async (c) => {
     const deleted = await serverlessRecords.deleteReadyPost(customer.id, post.id);
     return c.json({ post: deleted ? serializeReadyPost(c, deleted, { includePrivate: true }) : null });
 });
+// Move an approved post between /approved folders ({ folder_path }, ""=root).
+// Mirrors PATCH /raws/:clipId — the /library/approved explorer uses it to
+// reorganize posts and to materialize a folder when renaming a legacy group.
+app.patch(`${ACCOUNT_FRONTEND_PREFIX}/approved/posts/:postId`, async (c) => {
+    const customer = await requireBrowserCustomer(c);
+    if (!customer) {
+        return c.json({ error: "Unauthorized" }, 401);
+    }
+    const post = await serverlessRecords.getReadyPost(String(c.req.param("postId")));
+    if (!post || post.status === "deleted" || post.customerId !== customer.id) {
+        return c.json({ error: "Approved post not found." }, 404);
+    }
+    const body = (await c.req.json().catch(() => ({})));
+    const folderPath = normalizeFolderPath(body.folder_path ?? "");
+    const updated = await serverlessRecords.setReadyPostFolder(customer.id, post.id, folderPath);
+    return c.json({ post: updated ? serializeReadyPost(c, updated, { includePrivate: true }) : null });
+});
 app.get(`${ACCOUNT_FRONTEND_PREFIX}/approved/posts/:postId/schedules`, async (c) => {
     const customer = await requireBrowserCustomer(c);
     if (!customer) {
@@ -6538,6 +7522,8 @@ app.get("/assets/sentry-config.js", (c) => {
 });
 app.get("/assets/homepage-client-app.js", (c) => serveRootJsBundle(c, "public/assets/homepage-client-app.js"));
 app.get("/assets/page-runtime-client-app.js", (c) => serveRootJsBundle(c, "public/assets/page-runtime-client-app.js"));
+app.get("/assets/file-directory-app.js", (c) => serveRootJsBundle(c, "public/assets/file-directory-app.js"));
+app.get("/assets/discover-client-app.js", (c) => serveRootJsBundle(c, "public/assets/discover-client-app.js"));
 function serveRootJsBundle(c, relativePath) {
     const filePath = resolveRootFileCandidates(relativePath).find((candidate) => existsSync(candidate));
     if (!filePath) {
@@ -6694,6 +7680,14 @@ app.get("/composition/current.html", async (c) => {
     const compositionId = (c.req.query("composition") ?? "").trim();
     if (!compositionId)
         return c.text("Missing composition", 400);
+    // Blank new project (the /editor/original/fork/new sentinel, before its first
+    // edit mints a fork). Serve the canonical blank scaffold — 3 placeholder image
+    // scenes + "Scene N" captions — so the player paints an editable 12s timeline
+    // instead of "Composition not found". Runtime is injected by the rewrite.
+    if (compositionId === BLANK_COMPOSITION_ID) {
+        const rewritten = rewriteHyperframesDraftCompositionHtml(buildBlankCompositionHtml(compositionId), "blank");
+        return c.html(rewritten, 200, { "cache-control": "no-store" });
+    }
     if (compositionId.startsWith("template_")) {
         const template = await serverlessRecords.getTemplate(compositionId);
         if (!template || !template.videoUrl)
@@ -7086,6 +8080,9 @@ async function snapshotForkVersion(input) {
     // Scene annotations (clip-replacement + recreation DNA) likewise travel with
     // every version — reusable decompose metadata, same as placement surfaces.
     const workingAnnotations = await storage.readText(storage.compositionForkWorkingKey(input.fork.id, "scene-annotations.json"));
+    // Editor harness (technical editing direction) travels with every version too
+    // — reusable decompose style metadata, same as placement / annotations.
+    const workingHarness = await storage.readText(storage.compositionForkWorkingKey(input.fork.id, "editor-harness.json"));
     if (workingHtml) {
         await storage.putText(storage.compositionForkVersionKey(input.fork.id, version, "composition.html"), workingHtml, "text/html; charset=utf-8");
     }
@@ -7101,6 +8098,9 @@ async function snapshotForkVersion(input) {
     if (workingAnnotations) {
         await storage.putBuffer(storage.compositionForkVersionKey(input.fork.id, version, "scene-annotations.json"), Buffer.from(workingAnnotations, "utf8"), "application/json");
     }
+    if (workingHarness) {
+        await storage.putBuffer(storage.compositionForkVersionKey(input.fork.id, version, "editor-harness.json"), Buffer.from(workingHarness, "utf8"), "application/json");
+    }
     const versionRecord = await serverlessRecords.createForkVersion({
         forkId: input.fork.id,
         ownerCustomerId: input.fork.customerId,
@@ -7155,58 +8155,71 @@ function serializeFork(fork, caps) {
             : null
     };
 }
-app.post(COMPOSITIONS_PREFIX, async (c) => {
-    const customer = await requireBrowserCustomer(c);
-    if (!customer)
-        return c.json({ ok: false, error: "Unauthorized" }, 401);
-    const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
-    const templateId = readNonEmptyString(body.template_id) ?? readNonEmptyString(body.source);
-    if (!templateId || !templateId.startsWith("template_")) {
-        return c.json({ ok: false, error: "Missing or invalid template_id" }, 400);
+// ── Shared fork-creation helpers ────────────────────────────────────────────
+// A "new fork" always has one of two SOURCES, and every surface (the editor's
+// New-fork modal, the AI chat fork_composition action, and the devcli clone
+// command) funnels through these so the seed logic stays uniform:
+//   • "default" → fresh from the template's canonical default fork (start over
+//     from the original template — discard the current working edits).
+//   • "current" → branch from an existing working copy (clone this fork,
+//     optionally pinned to a saved version).
+// Copy the canonical working files from a source fork (optionally a pinned
+// version) into a destination fork's working tree. Returns whether an HTML
+// body was seeded.
+async function seedForkWorkingFromFork(destForkId, sourceForkId, version) {
+    const read = async (filename) => {
+        if (version && Number.isFinite(version)) {
+            const versioned = await storage.readText(storage.compositionForkVersionKey(sourceForkId, version, filename));
+            if (versioned)
+                return versioned;
+        }
+        return storage.readText(storage.compositionForkWorkingKey(sourceForkId, filename));
+    };
+    const html = await read("composition.html");
+    const json = await read("composition.json");
+    const cast = await read("cast.json");
+    const placement = await read("product-placement.json");
+    const annotations = await read("scene-annotations.json");
+    const harness = await read("editor-harness.json");
+    if (html) {
+        await storage.putText(storage.compositionForkWorkingKey(destForkId, "composition.html"), html, "text/html; charset=utf-8");
     }
-    const template = await serverlessRecords.getTemplate(templateId);
-    if (!template)
-        return c.json({ ok: false, error: "Template not found" }, 404);
+    if (json) {
+        await storage.putBuffer(storage.compositionForkWorkingKey(destForkId, "composition.json"), Buffer.from(json, "utf8"), "application/json");
+    }
+    if (cast) {
+        await storage.putBuffer(storage.compositionForkWorkingKey(destForkId, "cast.json"), Buffer.from(cast, "utf8"), "application/json");
+    }
+    if (placement) {
+        await storage.putBuffer(storage.compositionForkWorkingKey(destForkId, "product-placement.json"), Buffer.from(placement, "utf8"), "application/json");
+    }
+    if (annotations) {
+        await storage.putBuffer(storage.compositionForkWorkingKey(destForkId, "scene-annotations.json"), Buffer.from(annotations, "utf8"), "application/json");
+    }
+    if (harness) {
+        await storage.putBuffer(storage.compositionForkWorkingKey(destForkId, "editor-harness.json"), Buffer.from(harness, "utf8"), "application/json");
+    }
+    return Boolean(html);
+}
+// Fork FRESH from a template's canonical default fork (from: "default"). Never
+// overwrites template.defaultForkId — that stays canonical so other users keep
+// getting it as their fallback. No version snapshot (matches a first fork).
+async function forkCompositionFromTemplateDefault(customerId, template, title) {
     const canonicalFork = template.defaultForkId
         ? await serverlessRecords.getCompositionFork(template.defaultForkId)
         : null;
-    const title = readNonEmptyString(body.title) ?? template.title ?? `Template ${template.id}`;
-    // Per-user fork: never overwrite template.defaultForkId. That stays as the
-    // canonical decomposition so other users continue to get it as their
-    // fallback.
     const fork = await serverlessRecords.createCompositionFork({
-        customerId: customer.id,
+        customerId,
         templateId: template.id,
         parentForkId: canonicalFork?.id ?? null,
         parentVersion: canonicalFork?.latestVersion ?? null,
         visibility: "private",
         title
     });
-    // Seed new fork with the canonical composition html/json if available so
-    // it starts from the same base as everyone else.
     if (canonicalFork) {
-        const html = await storage.readText(storage.compositionForkWorkingKey(canonicalFork.id, "composition.html"));
-        const json = await storage.readText(storage.compositionForkWorkingKey(canonicalFork.id, "composition.json"));
-        // Seed the canonical cast so every user's fresh fork inherits the same
-        // identified people + reference stills as the shared default composition.
-        const cast = await storage.readText(storage.compositionForkWorkingKey(canonicalFork.id, "cast.json"));
-        const placement = await storage.readText(storage.compositionForkWorkingKey(canonicalFork.id, "product-placement.json"));
-        const annotations = await storage.readText(storage.compositionForkWorkingKey(canonicalFork.id, "scene-annotations.json"));
-        if (html) {
-            await storage.putText(storage.compositionForkWorkingKey(fork.id, "composition.html"), html, "text/html; charset=utf-8");
-        }
-        if (json) {
-            await storage.putBuffer(storage.compositionForkWorkingKey(fork.id, "composition.json"), Buffer.from(json, "utf8"), "application/json");
-        }
-        if (cast) {
-            await storage.putBuffer(storage.compositionForkWorkingKey(fork.id, "cast.json"), Buffer.from(cast, "utf8"), "application/json");
-        }
-        if (placement) {
-            await storage.putBuffer(storage.compositionForkWorkingKey(fork.id, "product-placement.json"), Buffer.from(placement, "utf8"), "application/json");
-        }
-        if (annotations) {
-            await storage.putBuffer(storage.compositionForkWorkingKey(fork.id, "scene-annotations.json"), Buffer.from(annotations, "utf8"), "application/json");
-        }
+        // Seed with the canonical composition (html/json/cast/placement/annotations)
+        // so it starts from the same base as everyone else.
+        await seedForkWorkingFromFork(fork.id, canonicalFork.id, null);
     }
     else if (template.videoUrl) {
         // Template exists but has no canonical fork yet — seed with raw HTML.
@@ -7220,6 +8233,71 @@ app.post(COMPOSITIONS_PREFIX, async (c) => {
         await storage.putText(storage.compositionForkWorkingKey(fork.id, "composition.html"), rawHtml, "text/html; charset=utf-8");
     }
     await writeForkManifest(storage, fork, { kind: "working" });
+    return fork;
+}
+// Fork from an EXISTING fork (from: "current"). Copies its working (or a pinned
+// version) files into a new private fork and snapshots v-next.
+async function forkCompositionFromExistingFork(customerId, sourceFork, parentVersion, title) {
+    const cloned = await serverlessRecords.createCompositionFork({
+        customerId,
+        templateId: sourceFork.templateId,
+        parentForkId: sourceFork.id,
+        parentVersion: parentVersion ?? null,
+        visibility: "private",
+        title
+    });
+    await seedForkWorkingFromFork(cloned.id, sourceFork.id, parentVersion);
+    await snapshotForkVersion({
+        fork: cloned,
+        callerCustomerId: customerId,
+        reason: "clone",
+        message: `Cloned from ${sourceFork.id}${parentVersion ? `@v${parentVersion}` : ""}`
+    });
+    return (await serverlessRecords.getCompositionFork(cloned.id));
+}
+// Mint a fresh per-user fork of the canonical blank composition. There is no
+// template record — the fork carries the sentinel templateId so it stays
+// isolated per customer — and its working copy is seeded with the same blank
+// scaffold the pre-fork editor shows, so the user's first edit lands on the 3
+// placeholder scenes and now persists. This is the "every new blank is a fork of
+// the blank composition" path (see BLANK_COMPOSITION_ID).
+async function forkBlankComposition(customerId, title) {
+    const fork = await serverlessRecords.createCompositionFork({
+        customerId,
+        templateId: BLANK_COMPOSITION_ID,
+        parentForkId: null,
+        parentVersion: null,
+        visibility: "private",
+        title
+    });
+    await storage.putText(storage.compositionForkWorkingKey(fork.id, "composition.html"), buildBlankCompositionHtml(fork.id), "text/html; charset=utf-8");
+    await writeForkManifest(storage, fork, { kind: "working" });
+    return (await serverlessRecords.getCompositionFork(fork.id));
+}
+app.post(COMPOSITIONS_PREFIX, async (c) => {
+    const customer = await requireBrowserCustomer(c);
+    if (!customer)
+        return c.json({ ok: false, error: "Unauthorized" }, 401);
+    const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
+    const templateId = readNonEmptyString(body.template_id) ?? readNonEmptyString(body.source);
+    // Blank project: the SPA POSTs source="original" on the first edit. Mint a
+    // fork seeded from the canonical blank scaffold instead of rejecting it, so
+    // edits on a new project persist (previously blank edits were lost on reload).
+    if (templateId === BLANK_COMPOSITION_ID) {
+        const blankTitle = readNonEmptyString(body.title) ?? "Untitled project";
+        const fork = await forkBlankComposition(customer.id, blankTitle);
+        return c.json(serializeFork(fork, {
+            isOwner: true, canView: true, canEdit: true, canPublish: true, canShare: true, canDelete: true, role: "owner"
+        }), 201);
+    }
+    if (!templateId || !templateId.startsWith("template_")) {
+        return c.json({ ok: false, error: "Missing or invalid template_id" }, 400);
+    }
+    const template = await serverlessRecords.getTemplate(templateId);
+    if (!template)
+        return c.json({ ok: false, error: "Template not found" }, 404);
+    const title = readNonEmptyString(body.title) ?? template.title ?? `Template ${template.id}`;
+    const fork = await forkCompositionFromTemplateDefault(customer.id, template, title);
     return c.json(serializeFork(fork, {
         isOwner: true, canView: true, canEdit: true, canPublish: true, canShare: true, canDelete: true, role: "owner"
     }), 201);
@@ -7263,7 +8341,11 @@ app.get(`${COMPOSITIONS_PREFIX}/:forkId/composition.html`, async (c) => {
         const html = await storage.readText(storage.compositionForkWorkingKey(access.fork.id, "composition.html"));
         if (!html)
             return c.json({ ok: false, error: "Composition missing" }, 404);
-        return c.body(html, 200, { "content-type": "text/html; charset=utf-8" });
+        // The editor stage loads the composition here (then injects its own runtime),
+        // so unmute the not-yet-decomposed raw single-video base so its own audio
+        // plays. Older stored raw bases baked in a `muted` attribute; strip it on the
+        // way out. Decomposed compositions are left untouched (see helper).
+        return c.body(unmuteRawPlaybackSourceVideo(html), 200, { "content-type": "text/html; charset=utf-8" });
     }
     catch (error) {
         return forkAccessErrorResponse(c, error);
@@ -7716,6 +8798,24 @@ app.post(`${INSPIRATIONS_PREFIX}/:inspirationId/decompose`, async (c) => {
             catch (placementPersistError) {
                 console.error("inspiration product-placement persist failed", placementPersistError instanceof Error ? placementPersistError.message : placementPersistError);
             }
+            // Persist the editor harness on the canonical fork too, before the
+            // snapshot, so it travels with v1 and seeds every downstream fork.
+            try {
+                await storage.putJson(storage.compositionForkWorkingKey(canonicalFork.id, "editor-harness.json"), {
+                    version: 1,
+                    savedAtMs: Date.now(),
+                    compositionId: canonicalFork.id,
+                    sourceUrl,
+                    title,
+                    provider: smart.provider,
+                    model: smart.model,
+                    durationSeconds: smart.durationSeconds,
+                    harness: smart.editorHarness
+                });
+            }
+            catch (harnessPersistError) {
+                console.error("inspiration editor-harness persist failed", harnessPersistError instanceof Error ? harnessPersistError.message : harnessPersistError);
+            }
             // Seed the scene-annotation pass "pending" on the canonical fork too,
             // before the snapshot, so the pending state travels with v1 and every
             // downstream fork can drive /scene-annotations-poll (or inherit the
@@ -8188,6 +9288,7 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
                 result: {
                     summary: smart.summary,
                     viralDna: smart.viralDna,
+                    editorHarness: smart.editorHarness,
                     transcript: smart.transcript,
                     durationSeconds: smart.durationSeconds,
                     width: smart.width,
@@ -8222,6 +9323,27 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
         catch (placementPersistError) {
             console.error("product-placement persist failed", placementPersistError instanceof Error ? placementPersistError.message : placementPersistError);
         }
+        // Persist the EDITOR HARNESS as its own decompose artifact (mirrors
+        // product-placement.json). Technical editing direction — read-only style
+        // context injected into both the web /editor AI (via the editor_context
+        // snapshot's editor_harness field, parsed from data-editor-harness in the
+        // HTML) and the local devcli agent (via this synced file). Non-fatal.
+        try {
+            await storage.putJson(storage.compositionForkWorkingKey(fork.id, "editor-harness.json"), {
+                version: 1,
+                savedAtMs: Date.now(),
+                compositionId,
+                sourceUrl: analysisSourceUrl,
+                title,
+                provider: smart.provider,
+                model: smart.model,
+                durationSeconds: smart.durationSeconds,
+                harness: smart.editorHarness
+            });
+        }
+        catch (harnessPersistError) {
+            console.error("editor-harness persist failed", harnessPersistError instanceof Error ? harnessPersistError.message : harnessPersistError);
+        }
         // Seed the per-scene clip-annotation pass as "pending" and let the client
         // drive it via POST /scene-annotations-poll (same async model as cast /
         // ghostcut). The annotation is its own vision call — running it inline would
@@ -8610,7 +9732,11 @@ const pollForkSubtitleRemoval = async (c) => {
                                 captions: Array.isArray(persisted.result.captions) ? persisted.result.captions : [],
                                 // Placement surfaces live in their own artifact and aren't used
                                 // by the HTML rebuild; supply an empty list to satisfy the type.
-                                placementSurfaces: []
+                                placementSurfaces: [],
+                                // Editor harness round-trips from the snapshot so the rebuilt
+                                // HTML keeps its data-editor-harness; default if a pre-harness
+                                // snapshot is being rebuilt.
+                                editorHarness: persisted.result.editorHarness ?? DEFAULT_EDITOR_HARNESS
                             }
                         });
                         await storage.putText(storage.compositionForkWorkingKey(fork.id, "composition.html"), rebuilt, "text/html; charset=utf-8");
@@ -8811,6 +9937,50 @@ app.get(`${COMPOSITIONS_PREFIX}/:forkId/product-placement.json`, async (c) => {
         return c.json({ ok: false, error: error instanceof Error ? error.message : String(error) }, 500);
     }
 });
+// Read-only EDITOR HARNESS for a fork: the technical editing direction extracted
+// during decompose (pace, typography, b-roll usage, transitions, audio bed, and
+// the role each scene plays). This is the "how to edit like this" companion to
+// viral DNA's "why it works". The web /editor AI already receives it inline via
+// editor_context.editor_harness (parsed from data-editor-harness in the HTML);
+// this route is how the local devcli agent + http_request tool fetch it.
+// Optional-auth like /product-placement.json. Returns { status: "none" } when
+// the fork was never decomposed (or predates this pass).
+app.get(`${COMPOSITIONS_PREFIX}/:forkId/editor-harness.json`, async (c) => {
+    const customer = await getBrowserCustomer(c);
+    try {
+        const access = await assertForkAccess({ forkId: c.req.param("forkId"), customerId: customer?.id ?? null, shareToken: readShareToken(c) }, "view");
+        const text = await storage.readText(storage.compositionForkWorkingKey(access.fork.id, "editor-harness.json"));
+        if (!text) {
+            return c.json({
+                ok: true,
+                status: "none",
+                hint: "This fork has no editor-harness pass yet. Run POST /api/v1/compositions/:forkId/auto-decompose to generate it."
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return c.json({ ok: true, status: "none" });
+        }
+        const harness = (parsed.harness && typeof parsed.harness === "object") ? parsed.harness : null;
+        return c.json({
+            ok: true,
+            status: harness ? "ready" : "empty",
+            provider: parsed.provider ?? null,
+            model: parsed.model ?? null,
+            source_url: parsed.sourceUrl ?? null,
+            duration_seconds: parsed.durationSeconds ?? null,
+            harness: harness ?? DEFAULT_EDITOR_HARNESS
+        });
+    }
+    catch (error) {
+        if (error instanceof ForkNotFoundError || error instanceof ForkAccessDeniedError)
+            return forkAccessErrorResponse(c, error);
+        return c.json({ ok: false, error: error instanceof Error ? error.message : String(error) }, 500);
+    }
+});
 // Read-only scene-annotation context for a fork: the detected content FORMAT
 // plus one annotation per scene carrying the literal + viral DNA needed to
 // (a) match a REPLACEMENT clip from the library (each annotation ships a
@@ -9625,6 +10795,42 @@ app.patch(`${COMPOSITIONS_PREFIX}/:forkId/visibility`, async (c) => {
         return forkAccessErrorResponse(c, error);
     }
 });
+// Unified "new fork" endpoint. from="current" (default) branches from this
+// fork's working copy (or a pinned version); from="default" starts a fresh copy
+// from the template's canonical default fork, discarding the current edits.
+// This is the single REST surface behind the editor's New-fork modal, the AI
+// chat fork_composition action, and the devcli clone command.
+app.post(`${COMPOSITIONS_PREFIX}/:forkId/fork`, async (c) => {
+    const customer = await requireBrowserCustomer(c);
+    if (!customer)
+        return c.json({ ok: false, error: "Login required to fork" }, 401);
+    try {
+        const sourceAccess = await assertForkAccess({ forkId: c.req.param("forkId"), customerId: customer.id, shareToken: readShareToken(c) }, "view");
+        const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
+        const from = readNonEmptyString(body.from) === "default" ? "default" : "current";
+        if (from === "default") {
+            const template = await serverlessRecords.getTemplate(sourceAccess.fork.templateId);
+            if (!template)
+                return c.json({ ok: false, error: "Template not found for this fork" }, 404);
+            const title = readNonEmptyString(body.title) ?? template.title ?? sourceAccess.fork.title;
+            const fresh = await forkCompositionFromTemplateDefault(customer.id, template, title);
+            return c.json(serializeFork(fresh, {
+                isOwner: true, canView: true, canEdit: true, canPublish: true, canShare: true, canDelete: true, role: "owner"
+            }), 201);
+        }
+        const parentVersionRaw = readNonEmptyString(body.parent_version);
+        const parentVersion = parentVersionRaw ? Number.parseInt(parentVersionRaw, 10) : sourceAccess.fork.latestVersion || null;
+        const cloned = await forkCompositionFromExistingFork(customer.id, sourceAccess.fork, parentVersion ?? null, readNonEmptyString(body.title) ?? sourceAccess.fork.title);
+        return c.json(serializeFork(cloned, {
+            isOwner: true, canView: true, canEdit: true, canPublish: true, canShare: true, canDelete: true, role: "owner"
+        }), 201);
+    }
+    catch (error) {
+        return forkAccessErrorResponse(c, error);
+    }
+});
+// Legacy alias: clone == fork from the current working copy. Retained for
+// existing callers; new callers should use POST /:forkId/fork { from }.
 app.post(`${COMPOSITIONS_PREFIX}/:forkId/clone`, async (c) => {
     const customer = await requireBrowserCustomer(c);
     if (!customer)
@@ -9634,50 +10840,8 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/clone`, async (c) => {
         const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
         const parentVersionRaw = readNonEmptyString(body.parent_version);
         const parentVersion = parentVersionRaw ? Number.parseInt(parentVersionRaw, 10) : sourceAccess.fork.latestVersion || null;
-        const cloned = await serverlessRecords.createCompositionFork({
-            customerId: customer.id,
-            templateId: sourceAccess.fork.templateId,
-            parentForkId: sourceAccess.fork.id,
-            parentVersion: parentVersion ?? null,
-            visibility: "private",
-            title: readNonEmptyString(body.title) ?? sourceAccess.fork.title
-        });
-        const readVersionFile = async (filename) => {
-            if (parentVersion && Number.isFinite(parentVersion)) {
-                const versioned = await storage.readText(storage.compositionForkVersionKey(sourceAccess.fork.id, parentVersion, filename));
-                if (versioned)
-                    return versioned;
-            }
-            return storage.readText(storage.compositionForkWorkingKey(sourceAccess.fork.id, filename));
-        };
-        const html = await readVersionFile("composition.html");
-        const json = await readVersionFile("composition.json");
-        const cast = await readVersionFile("cast.json");
-        const placement = await readVersionFile("product-placement.json");
-        const annotations = await readVersionFile("scene-annotations.json");
-        if (html) {
-            await storage.putText(storage.compositionForkWorkingKey(cloned.id, "composition.html"), html, "text/html; charset=utf-8");
-        }
-        if (json) {
-            await storage.putBuffer(storage.compositionForkWorkingKey(cloned.id, "composition.json"), Buffer.from(json, "utf8"), "application/json");
-        }
-        if (cast) {
-            await storage.putBuffer(storage.compositionForkWorkingKey(cloned.id, "cast.json"), Buffer.from(cast, "utf8"), "application/json");
-        }
-        if (placement) {
-            await storage.putBuffer(storage.compositionForkWorkingKey(cloned.id, "product-placement.json"), Buffer.from(placement, "utf8"), "application/json");
-        }
-        if (annotations) {
-            await storage.putBuffer(storage.compositionForkWorkingKey(cloned.id, "scene-annotations.json"), Buffer.from(annotations, "utf8"), "application/json");
-        }
-        await snapshotForkVersion({
-            fork: cloned,
-            callerCustomerId: customer.id,
-            reason: "clone",
-            message: `Cloned from ${sourceAccess.fork.id}${parentVersion ? `@v${parentVersion}` : ""}`
-        });
-        const refreshed = await serverlessRecords.getCompositionFork(cloned.id);
-        return c.json(serializeFork(refreshed, {
+        const cloned = await forkCompositionFromExistingFork(customer.id, sourceAccess.fork, parentVersion ?? null, readNonEmptyString(body.title) ?? sourceAccess.fork.title);
+        return c.json(serializeFork(cloned, {
             isOwner: true, canView: true, canEdit: true, canPublish: true, canShare: true, canDelete: true, role: "owner"
         }), 201);
     }
@@ -9827,6 +10991,101 @@ function serializeInspiration(inspiration) {
         updated_at: inspiration.updatedAt
     };
 }
+// Mint the template for a READY inspiration (idempotent): creates a template
+// inheriting the inspiration's visibility + origin and links it back via
+// templateId. Returns the inspiration with templateId set — or unchanged if it
+// already has one / isn't ready / has no source video. Shared by the eager
+// (private, on-download) path and the lazy Remix path (POST
+// /discover/inspirations/:id/decompose).
+async function mintTemplateForInspiration(inspiration) {
+    if (inspiration.templateId || inspiration.status !== "ready" || !inspiration.videoUrl)
+        return inspiration;
+    const template = await serverlessRecords.createTemplate({
+        inspirationId: inspiration.id,
+        customerId: inspiration.customerId,
+        originalUrl: inspiration.originalUrl,
+        sourceHost: inspiration.sourceHost,
+        // No host/"Untitled" fallback: a template without an explicit title or
+        // tagline displays as its template id on /discover.
+        title: (inspiration.sourceHost === "upload"
+            ? (inspiration.title || inspiration.trendTagline)
+            : (inspiration.trendTagline || inspiration.title)) || null,
+        thumbnailUrl: inspiration.thumbnailUrl,
+        videoUrl: inspiration.videoUrl,
+        durationSeconds: inspiration.durationSeconds,
+        songName: inspiration.songName,
+        songUrl: inspiration.songUrl,
+        visibility: inspiration.visibility === "private" ? "private" : "public",
+        origin: inspiration.origin ?? "inspiration",
+        notes: inspiration.notes
+    });
+    // Seed the template's canonical DEFAULT fork with the raw single-video
+    // timeline so opening the editor lands on an editable project immediately —
+    // the whole clip as ONE element across the trackpad. Because origin stays
+    // "inspiration" the editor still auto-prompts Decompose; decomposing rebuilds
+    // this same default fork in place, so the multi-scene version becomes the new
+    // default everyone forks off. Non-fatal: on failure the template just falls
+    // back to the on-demand raw seed in POST /api/v1/compositions.
+    try {
+        await seedRawDefaultForkForTemplate(template);
+    }
+    catch (error) {
+        console.error("seed raw default fork failed", error instanceof Error ? error.message : error);
+    }
+    return (await serverlessRecords.updateInspiration({
+        inspirationId: inspiration.id,
+        patch: { templateId: template.id }
+    })) ?? { ...inspiration, templateId: template.id };
+}
+// Create + stamp a template's canonical DEFAULT fork holding the raw
+// single-video composition (the full source clip as one timeline element).
+// Idempotent: returns the existing default fork id if one is already stamped,
+// or null if the template has no source video to seed from. Owned privately by
+// the template owner — other users never touch it through permissions; POST
+// /api/v1/compositions seeds their forks by copying its composition html.
+async function seedRawDefaultForkForTemplate(template) {
+    if (template.defaultForkId)
+        return template.defaultForkId;
+    const sourceUrl = template.videoUrl?.trim();
+    if (!sourceUrl)
+        return null;
+    const title = template.title ?? `Template ${template.id}`;
+    const fork = await serverlessRecords.createCompositionFork({
+        customerId: template.customerId,
+        templateId: template.id,
+        parentForkId: null,
+        parentVersion: null,
+        visibility: "private",
+        title
+    });
+    const html = buildRawTikTokCompositionHtml({
+        compositionId: fork.id,
+        sourceUrl,
+        durationSeconds: template.durationSeconds ?? 12,
+        title,
+        origin: template.origin ?? "inspiration"
+    });
+    await storage.putText(storage.compositionForkWorkingKey(fork.id, "composition.html"), html, "text/html; charset=utf-8");
+    await writeForkManifest(storage, fork, { kind: "working" });
+    // Snapshot v1 (reason "clone" bypasses the version ceiling) so version
+    // history + revert work from the very first raw base.
+    try {
+        await snapshotForkVersion({
+            fork,
+            callerCustomerId: template.customerId,
+            reason: "clone",
+            message: "Raw single-video base"
+        });
+    }
+    catch (error) {
+        console.error("seed raw default fork snapshot failed", error instanceof Error ? error.message : error);
+    }
+    const stamp = await serverlessRecords.stampDefaultForkIfUnset({
+        templateId: template.id,
+        forkId: fork.id
+    });
+    return stamp.template?.defaultForkId ?? fork.id;
+}
 async function finalizeInspirationIfReady(inspiration) {
     if (inspiration.status !== "downloading" || !inspiration.downloadJobId)
         return inspiration;
@@ -9856,38 +11115,12 @@ async function finalizeInspirationIfReady(inspiration) {
                 songUrl: songUrl ?? null
             }
         })) ?? inspiration;
-        // Private (user-added) inspirations mint their template as soon as the
-        // download lands so the card on the owner's /discover becomes openable.
-        // Public inspirations keep the existing behavior: templates only come
-        // from the admin ingest flow.
-        if (ready.visibility === "private" && !ready.templateId && ready.videoUrl) {
-            const template = await serverlessRecords.createTemplate({
-                inspirationId: ready.id,
-                customerId: ready.customerId,
-                originalUrl: ready.originalUrl,
-                sourceHost: ready.sourceHost,
-                // No host/"Untitled" fallback: a template without an explicit title or
-                // tagline displays as its template id on /discover. For uploads the
-                // manifest title IS the caller's explicit title, so it outranks the
-                // tagline; URL ingests keep tagline-first (manifest title is just the
-                // social post's own caption).
-                title: (ready.sourceHost === "upload"
-                    ? (ready.title || ready.trendTagline)
-                    : (ready.trendTagline || ready.title)) || null,
-                thumbnailUrl: ready.thumbnailUrl,
-                videoUrl: ready.videoUrl,
-                durationSeconds: ready.durationSeconds,
-                songName: ready.songName,
-                songUrl: ready.songUrl,
-                visibility: "private",
-                origin: ready.origin ?? "inspiration",
-                notes: ready.notes
-            });
-            ready = (await serverlessRecords.updateInspiration({
-                inspirationId: ready.id,
-                patch: { templateId: template.id }
-            })) ?? ready;
-        }
+        // EVERY ready inspiration eagerly mints a template + a raw single-video
+        // default fork, so every card opens the editor directly onto an editable
+        // project (the whole clip as one timeline element) with the Decompose
+        // prompt still available. The Feed browses inspirations (deduped on
+        // inspirationId||templateId) so a template per upload doesn't flood it.
+        ready = await mintTemplateForInspiration(ready);
         return ready;
     }
     if (job.status === "failed" || job.status === "cancelled") {
@@ -10826,7 +12059,7 @@ app.get("/library", async (c) => {
         posts,
         schedule: {
             channels: scheduleChannels,
-            connectHref: withAccountQuery("/settings?tab=channels&connect=flockposter", customer.id)
+            connectHref: withAccountQuery("/settings/channels?connect=flockposter", customer.id)
         },
         editorChat: await buildLibraryEditorChatBoot({
             customer,
@@ -10997,7 +12230,7 @@ app.get("/calendar", async (c) => {
         posts: [],
         loadEndpoint: withAccountQuery("/calendar/feed", customer.id),
         hasFlockPosterKey: Boolean(flockPosterApiKey || emailChannels.length),
-        connectChannelsHref: withAccountQuery("/settings?tab=channels&connect=flockposter", customer.id)
+        connectChannelsHref: withAccountQuery("/settings/channels?connect=flockposter", customer.id)
     }));
 });
 app.get("/agency", async (c) => {
@@ -11307,7 +12540,7 @@ app.get("/email-channels/confirm", async (c) => {
         <h1 style="overflow-wrap: anywhere;">${escapeHtml(title)}</h1>
         <p>${channel ? "Your email has been confirmed and can receive email tasks from Vidfarm." : "This confirmation link is invalid or has already been used."}</p>
         <div class="toolbar">
-          <a class="button" href="/settings?tab=channels">Go to settings</a>
+          <a class="button" href="/settings/channels">Go to settings</a>
           <a class="button secondary" href="/discover">Back to Discover</a>
         </div>
       </section>
@@ -11376,6 +12609,15 @@ app.post("/settings/attachments", async (c) => {
             const attachmentId = randomUUID();
             const storageKey = storage.userAttachmentKey(customer.id, attachmentId, fileName);
             const stored = await storage.putBuffer(storageKey, buffer, contentType);
+            const publicUrl = stored.url || storage.getPublicUrl(storageKey) || buildUserAttachmentViewUrl(c, storageKey);
+            const thumb = await ensureAttachmentThumbnail({
+                customerId: customer.id,
+                attachmentId,
+                storageKey,
+                contentType,
+                attachmentUrl: publicUrl,
+                sourceUrl: publicUrl
+            });
             await serverlessRecords.createUserAttachment({
                 id: attachmentId,
                 customerId: customer.id,
@@ -11383,7 +12625,9 @@ app.post("/settings/attachments", async (c) => {
                 contentType,
                 sizeBytes: buffer.byteLength,
                 storageKey,
-                publicUrl: stored.url || storage.getPublicUrl(storageKey) || buildUserAttachmentViewUrl(c, storageKey)
+                publicUrl,
+                thumbnailStorageKey: thumb?.thumbnailStorageKey ?? null,
+                thumbnailUrl: thumb?.thumbnailUrl ?? null
             });
         }
         return redirectToSettings(c, { notice: "Attachment upload complete.", accountId: customer.id });
@@ -12712,6 +13956,7 @@ function serializeReadyPost(c, post, input) {
         status: post.status,
         title: post.title,
         caption: post.caption,
+        folder_path: normalizeFolderPath(post.folderPath ?? ""),
         pinned_comment: post.pinnedComment,
         media: post.mediaAssets.map((asset) => ({
             id: asset.id,
@@ -13427,38 +14672,58 @@ function countReadyPostMediaMatches(job, post) {
     return matches;
 }
 async function resolveReadyPostEditorHref(post, accountId) {
+    // "Edit Post" must land in the NEW /editor experience, never the retired
+    // /templates/:id/editor/docs editor. The /editor routes live at the top
+    // level and read the agency sub-account from the ?account= query param (there
+    // is no /u/:account/editor route), so account context is attached that way.
+    const withAccount = (path) => {
+        if (!accountId)
+            return path;
+        const sep = path.includes("?") ? "&" : "?";
+        return `${path}${sep}${ACCOUNT_QUERY_PARAM}=${encodeURIComponent(accountId)}`;
+    };
+    const editorForkHref = (templateId, forkId) => withAccount(`/editor/${encodeURIComponent(templateId)}/fork/${encodeURIComponent(forkId)}`);
+    // Bare editor: the route resolves (or mints) the caller's own fork.
+    const editorTemplateHref = (templateId) => withAccount(`/editor/${encodeURIComponent(templateId)}`);
+    // Fresh blank project in the new editor — used when nothing editable is
+    // linked to this post (e.g. a post approved straight from a primitive render
+    // with no composition fork or tracer).
+    const blankEditorHref = () => withAccount("/editor/original/fork/new");
+    // 1) Preferred: deep-link to the exact composition fork the post came from.
+    const compositionId = post.compositionId?.trim();
+    if (compositionId) {
+        const fork = await serverlessRecords.getCompositionFork(compositionId);
+        if (fork && !fork.deletedAt && fork.templateId) {
+            return editorForkHref(fork.templateId, fork.id);
+        }
+        // Some create paths stash a serverless template id in compositionId rather
+        // than a fork id — open the bare editor for that template.
+        if (compositionId.startsWith("template_")) {
+            return editorTemplateHref(compositionId);
+        }
+    }
+    // 2) Fall back to the tracer's most-relevant render job, but only when that
+    // job points at a serverless (template_) template the new editor can open.
+    // Legacy catalog jobs (plain-UUID templateIds) are skipped on purpose so we
+    // never route back into the old editor.
     const tracer = post.tracer?.trim();
-    const buildDocsHref = (templateId, tracers) => {
-        const params = new URLSearchParams();
-        if (accountId) {
-            params.set(ACCOUNT_QUERY_PARAM, accountId);
-        }
-        if (tracers) {
-            params.set("tracers", tracers);
+    if (tracer) {
+        const matchingJob = (await jobs.listJobsAsync({ customerId: post.customerId, tracer, limit: 100 }))
+            .filter((job) => job.templateId.startsWith("template_"))
+            .map((job) => ({
+            job,
+            score: (countReadyPostMediaMatches(job, post) * 1000)
+                + (job.parentJobId ? 0 : 120)
+                + (job.status === "succeeded" ? 30 : 0)
+        }))
+            .sort((a, b) => (b.score - a.score
+            || Date.parse(b.job.completedAt ?? b.job.updatedAt ?? b.job.createdAt) - Date.parse(a.job.completedAt ?? a.job.updatedAt ?? a.job.createdAt)))[0]?.job ?? null;
+        if (matchingJob && await serverlessRecords.getTemplate(matchingJob.templateId)) {
+            return editorTemplateHref(matchingJob.templateId);
         }
-        const suffix = params.size ? `?${params.toString()}` : "";
-        return `/templates/${encodeURIComponent(templateId)}/editor/docs${suffix}`;
-    };
-    if (!tracer) {
-        const firstTemplate = templateRegistry.list().find((template) => !template.id.startsWith("primitive:"));
-        return firstTemplate ? buildDocsHref(firstTemplate.id) : withAccountQuery("/templates", accountId);
-    }
-    const candidates = (await jobs.listJobsAsync({ customerId: post.customerId, tracer, limit: 100 }))
-        .filter((job) => !job.templateId.startsWith("primitive:") && Boolean(templateRegistry.get(job.templateId)));
-    const matchingJob = candidates
-        .map((job) => ({
-        job,
-        score: (countReadyPostMediaMatches(job, post) * 1000)
-            + (job.parentJobId ? 0 : 120)
-            + (job.status === "succeeded" ? 30 : 0)
-    }))
-        .sort((a, b) => (b.score - a.score
-        || Date.parse(b.job.completedAt ?? b.job.updatedAt ?? b.job.createdAt) - Date.parse(a.job.completedAt ?? a.job.updatedAt ?? a.job.createdAt)))[0]?.job ?? null;
-    if (matchingJob) {
-        return buildDocsHref(matchingJob.templateId, tracer);
     }
-    const firstTemplate = templateRegistry.list().find((template) => !template.id.startsWith("primitive:"));
-    return firstTemplate ? buildDocsHref(firstTemplate.id, tracer) : withAccountQuery("/templates", accountId);
+    // 3) Nothing editable is linked — open a fresh project in the new editor.
+    return blankEditorHref();
 }
 async function renderReadyPostPage(c, post, viewer) {
     const visiblePost = serializeReadyPost(c, post, { password: viewer.hasPasswordAccess ? viewer.password : null });
@@ -13488,7 +14753,7 @@ async function renderReadyPostPage(c, post, viewer) {
         error: scheduleChannels.error,
         feedEndpoint: viewer.canManage && viewer.customer ? withAccountQuery("/calendar/feed", viewer.customer.id) : null,
         scheduleEndpoint: viewer.canManage && viewer.customer ? scopedApprovedPostSchedulePath(viewer.customer.id, post.id) : null,
-        connectHref: viewer.customer ? withAccountQuery("/settings?tab=channels&connect=flockposter", viewer.customer.id) : "/settings?tab=channels&connect=flockposter",
+        connectHref: viewer.customer ? withAccountQuery("/settings/channels?connect=flockposter", viewer.customer.id) : "/settings/channels?connect=flockposter",
         userId: viewer.customer?.id ?? null
     };
     const shareUrl = viewer.canView
@@ -14308,6 +15573,282 @@ async function renderReadyPostPage(c, post, viewer) {
       gap: 8px;
       margin-top: 4px;
     }
+
+    /* ─────────────────────────────────────────────────────────────────────
+       farmville-saas-ux restyle (honey-gold accent, Hanken Grotesk display,
+       soft rounded white cards). SCOPED to .ready-post-shell so it never
+       leaks into other legacy pages, and placed last so it wins over both the
+       page-shell base CSS and the ready-post rules above. Structure + JS are
+       untouched — this is a pure visual reskin via token remap + component
+       overrides. Hanken Grotesk is loaded by a <link> in the page body.
+       ───────────────────────────────────────────────────────────────────── */
+    /* page canvas → clean warm-neutral farmville surface. Drops the old
+       beige/tan gradient + technical grid overlay baked into the base shell
+       <body> (which the .ready-post-shell scope can't reach). A whisper of
+       honey glow up top keeps the "sunny afternoon" warmth without the grid. */
+    body:has(.ready-post-shell) {
+      background:
+        radial-gradient(1150px 520px at 50% -12%, rgba(255, 199, 56, 0.10), transparent 62%),
+        linear-gradient(180deg, #fdfcf9 0%, #fbfaf6 46%, #f6f4ee 100%);
+      background-attachment: fixed;
+    }
+    body:has(.ready-post-shell)::before {
+      content: none;
+    }
+    @media (max-width: 1024px) {
+      body:has(.ready-post-shell) {
+        background-attachment: scroll;
+      }
+    }
+    .ready-post-shell {
+      --accent: #ffc738;
+      font-family: "Inter", "Manrope", sans-serif;
+      --accent-deep: #171717;
+      --accent-soft: rgba(255, 199, 56, 0.22);
+      --ink: #171717;
+      --muted: #6f6f70;
+      --line: #ededed;
+      --line-strong: #e0e0e0;
+      --bg: #fbfaf6;
+      --paper: #ffffff;
+      --paper-strong: #ffffff;
+      --panel-muted: #faf9f6;
+      --radius-lg: 24px;
+      --radius-md: 18px;
+      --radius-sm: 12px;
+      --shadow: 0 1px 2px rgba(0, 0, 0, 0.05), 0 18px 40px -20px rgba(0, 0, 0, 0.12);
+      --shadow-soft: 0 1px 2px rgba(0, 0, 0, 0.05), 0 10px 26px -16px rgba(0, 0, 0, 0.14);
+    }
+    .ready-post-shell h1,
+    .ready-post-shell h2,
+    .ready-post-shell .ready-post-schedule-head h2 {
+      font-family: "Hanken Grotesk", "Manrope", sans-serif;
+      font-weight: 800;
+      letter-spacing: -0.02em;
+      color: #171717;
+    }
+    /* buttons → honey-gold pill / white ghost / red danger */
+    .ready-post-shell .button,
+    .ready-post-shell button,
+    .ready-post-shell .link-button,
+    .ready-post-shell .cta-button {
+      border: 1px solid transparent;
+      border-radius: 999px;
+      background: #ffc738;
+      color: #171717;
+      font-family: "Hanken Grotesk", "Manrope", sans-serif;
+      font-weight: 700;
+      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.06);
+    }
+    @media (hover: hover) {
+      .ready-post-shell .button:hover,
+      .ready-post-shell button:hover,
+      .ready-post-shell .link-button:hover {
+        background: #fcb900;
+        border-color: transparent;
+        transform: translateY(-1px);
+        box-shadow: 0 10px 22px -8px rgba(252, 185, 0, 0.55);
+      }
+    }
+    .ready-post-shell .button.secondary,
+    .ready-post-shell button.secondary,
+    .ready-post-shell .link-button.secondary {
+      background: #ffffff;
+      color: #171717;
+      border: 1px solid #e5e5e5;
+      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04);
+    }
+    @media (hover: hover) {
+      .ready-post-shell .button.secondary:hover,
+      .ready-post-shell button.secondary:hover {
+        background: #ffffff;
+        border-color: #d4d4d4;
+        box-shadow: 0 4px 12px -6px rgba(0, 0, 0, 0.12);
+      }
+    }
+    .ready-post-shell .button.danger,
+    .ready-post-shell button.danger,
+    .ready-post-shell .ready-post-danger {
+      background: #ef4444;
+      color: #fff;
+      border-color: transparent;
+    }
+    .ready-post-shell button[disabled] {
+      opacity: 0.5;
+    }
+    /* inputs → soft farmville field, gold focus ring */
+    .ready-post-shell input,
+    .ready-post-shell select,
+    .ready-post-shell textarea {
+      border: 1px solid #e5e5e5;
+      border-radius: 12px;
+      background: #ffffff;
+      color: #171717;
+      box-shadow: none;
+    }
+    .ready-post-shell textarea {
+      border-radius: 16px;
+    }
+    .ready-post-shell input:focus,
+    .ready-post-shell select:focus,
+    .ready-post-shell textarea:focus {
+      border-color: #ffc738;
+      box-shadow: 0 0 0 3px rgba(255, 199, 56, 0.28);
+    }
+    /* tracer / status chip */
+    .ready-post-shell .pill {
+      background: #fff5e4;
+      color: #8a6d1f;
+      border: 1px solid #ffe9cc;
+      border-radius: 999px;
+      font-weight: 700;
+    }
+    /* cards / panels → white farmville card */
+    .ready-post-shell .ready-post-card,
+    .ready-post-shell .ready-post-panel {
+      background: #ffffff;
+      border: 1px solid #ededed;
+      border-radius: 24px;
+      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04), 0 12px 30px -18px rgba(0, 0, 0, 0.14);
+    }
+    /* copy + menu buttons → neutral ghost */
+    .ready-post-shell .ready-post-copy,
+    .ready-post-shell .ready-post-actions [data-menu-button] {
+      background: #ffffff;
+      border: 1px solid #e5e5e5;
+      color: #525252;
+      box-shadow: none;
+    }
+    .ready-post-shell .ready-post-copy[data-copied="true"] {
+      background: #dcfce7;
+      border-color: #86efac;
+      color: #15803d;
+      box-shadow: 0 0 0 3px rgba(34, 197, 94, 0.15);
+    }
+    .ready-post-shell .ready-post-menu {
+      border: 1px solid #ededed;
+      border-radius: 16px;
+      background: #ffffff;
+      box-shadow: 0 20px 40px -16px rgba(0, 0, 0, 0.22);
+    }
+    /* video/slides mode toggle → farmville pill toggle */
+    .ready-post-shell .ready-post-media-mode-toggle button.active {
+      background: #ffc738;
+      color: #171717;
+    }
+    /* login modal card */
+    .ready-post-shell .ready-post-login-modal-card {
+      border: 1px solid #ededed;
+      border-radius: 24px;
+      background: #ffffff;
+      box-shadow: 0 24px 60px -20px rgba(0, 0, 0, 0.3);
+    }
+    /* schedule modal → farmville surface + gold selected day */
+    .ready-post-shell .ready-post-schedule-modal {
+      border-radius: 24px;
+    }
+    /* ── de-saturate: structural buttons must NOT inherit the blanket gold ──
+       The broad gold button rule above is meant for primary
+       CTAs only, but it also painted calendar days, the channel-picker trigger,
+       channel rows and kebab-menu items gold (a wall of yellow). Restore their
+       neutral surfaces here (placed last so they win); only true primaries and
+       genuinely-selected states stay honey-gold. */
+    .ready-post-shell .ready-post-calendar-day {
+      background: #ffffff;
+      color: #3a3a3c;
+      border: 1px solid #ececec;
+      box-shadow: none;
+      font-weight: 700;
+    }
+    .ready-post-shell .ready-post-calendar-day.is-muted {
+      background: #faf9f6;
+      color: #b5b5b7;
+    }
+    .ready-post-shell .ready-post-calendar-day.has-posts {
+      background: rgba(83, 114, 89, 0.10);
+      border-color: rgba(83, 114, 89, 0.30);
+    }
+    .ready-post-shell .ready-post-calendar-day.has-many-posts {
+      background: rgba(255, 199, 56, 0.16);
+      border-color: rgba(255, 199, 56, 0.42);
+    }
+    @media (hover: hover) {
+      .ready-post-shell .ready-post-calendar-day:hover {
+        background: #fff8e8;
+        border-color: #ffc738;
+        transform: none;
+        box-shadow: none;
+      }
+    }
+    .ready-post-shell .ready-post-calendar-day.is-selected,
+    .ready-post-shell .ready-post-calendar-day.is-selected:hover {
+      background: #ffc738;
+      color: #171717;
+      border-color: transparent;
+    }
+    .ready-post-shell .ready-post-calendar-day.is-today {
+      border-color: #ffc738;
+    }
+    /* channel-picker trigger → neutral field, not a gold pill */
+    .ready-post-shell .ready-post-channel-trigger {
+      background: #ffffff;
+      color: #171717;
+      border: 1px solid #e5e5e5;
+      box-shadow: none;
+      font-weight: 600;
+    }
+    .ready-post-shell .ready-post-channel-trigger.is-placeholder {
+      color: #6f6f70;
+    }
+    @media (hover: hover) {
+      .ready-post-shell .ready-post-channel-trigger:hover {
+        background: #ffffff;
+        border-color: #d4d4d4;
+        transform: none;
+        box-shadow: none;
+      }
+    }
+    /* channel rows + kebab-menu items → transparent, gold tint only on hover/selected */
+    .ready-post-shell .ready-post-channel-option,
+    .ready-post-shell .ready-post-menu a,
+    .ready-post-shell .ready-post-menu button {
+      background: transparent;
+      color: #171717;
+      border: 0;
+      box-shadow: none;
+      font-weight: 600;
+    }
+    @media (hover: hover) {
+      .ready-post-shell .ready-post-channel-option:hover,
+      .ready-post-shell .ready-post-menu a:hover,
+      .ready-post-shell .ready-post-menu button:hover {
+        background: #fff5e4;
+        transform: none;
+        box-shadow: none;
+      }
+    }
+    .ready-post-shell .ready-post-channel-option.is-selected {
+      background: #fff5e4;
+    }
+    .ready-post-shell .ready-post-menu .ready-post-danger {
+      color: #dc2626;
+      font-weight: 700;
+    }
+    @media (hover: hover) {
+      .ready-post-shell .ready-post-menu .ready-post-danger:hover {
+        background: #fef2f2;
+      }
+    }
+    /* popover close chip stays a neutral ghost */
+    .ready-post-shell .ready-post-calendar-popover-close {
+      background: #ffffff;
+      color: #6f6f70;
+      border: 1px solid #e5e5e5;
+      box-shadow: none;
+    }
+    .ready-post-shell .ready-post-locked {
+      font-family: "Hanken Grotesk", "Manrope", sans-serif;
+    }
   `;
     const readyPostBody = viewer.canView ? `
     <section class="ready-post-frame">
@@ -14349,10 +15890,19 @@ async function renderReadyPostPage(c, post, viewer) {
         </footer>
       </div>
     </div>` : `<section class="ready-post-locked"><form method="get" action="${escapeAttribute(accountApprovedPostPath(post.customerId, post.id))}"><h1>Approved post</h1><p>Enter the share password to preview and download this approved post.</p><input name="password" type="password" value="${escapeAttribute(DEFAULT_APPROVED_POST_VIEW_PASSWORD)}" autofocus autocomplete="current-password"><button type="submit">View post</button></form></section>`;
+    const socialImage = thumbnail?.url ?? slides[0]?.url;
+    const socialDescription = post.caption?.trim() || undefined;
     return c.html(renderPageShell({
         title: post.title ?? "Approved post",
         shellClass: "ready-post-shell",
+        description: socialDescription,
+        social: {
+            image: socialImage,
+            url: shareUrl,
+            type: primaryVideo ? "video.other" : "website"
+        },
         body: `
+      <link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:wght@500;600;700;800&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
       ${readyPostBody}
   <script id="ready-post-data" type="application/json">${escapeJsonForHtml(serialized)}</script>
   <script id="ready-post-zip-data" type="application/json">${escapeJsonForHtml({
@@ -15056,6 +16606,10 @@ function primitiveAliasPathForKind(kind) {
             return `${PRIMITIVES_PREFIX}/images/render-html`;
         case "image_remove_background":
             return `${PRIMITIVES_PREFIX}/images/remove-background`;
+        case "image_remove_background_greenscreen":
+            return `${PRIMITIVES_PREFIX}/images/remove-background-greenscreen`;
+        case "media_overlay":
+            return `${PRIMITIVES_PREFIX}/images/create-overlay`;
         case "video_generate":
             return `${PRIMITIVES_PREFIX}/videos/generate`;
         case "video_render_slides":
@@ -15716,6 +17270,14 @@ app.post(`${PRIMITIVES_PREFIX}/images/edit`, async (c) => createPrimitiveJob(c,
 app.post(`${PRIMITIVES_PREFIX}/images/inpaint`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:image_inpaint", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/images/render-html`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:image_render_html", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/images/remove-background`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:image_remove_background", operationName: "run" }));
+// Cheap local chroma-key background removal. Canonical images/* path plus a flat
+// plain-English alias matching the primitive's spoken name.
+app.post(`${PRIMITIVES_PREFIX}/images/remove-background-greenscreen`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:image_remove_background_greenscreen", operationName: "run" }));
+app.post(`${PRIMITIVES_PREFIX}/remove-background-greenscreen`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:image_remove_background_greenscreen", operationName: "run" }));
+// Two-step "create media overlay": BYOK image gen on a forced key-color
+// background + local chroma key → transparent overlay.
+app.post(`${PRIMITIVES_PREFIX}/images/create-overlay`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:media_overlay", operationName: "run" }));
+app.post(`${PRIMITIVES_PREFIX}/create-media-overlay`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:media_overlay", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/videos/generate`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:video_generate", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/videos/download`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:video_download", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/videos/render-slides`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:video_render_slides", operationName: "run" }));
@@ -15879,11 +17441,32 @@ app.delete(`${APPROVED_POSTS_PREFIX}/:postId`, requireAuth, async (c) => {
         return c.json({ error: error instanceof Error ? error.message : "Forbidden" }, 403);
     }
 });
-app.get(`${APPROVED_POSTS_PREFIX}/:postId/download-zip`, async (c) => {
+// PATCH /api/v1/approved/posts/:postId { folder_path } — move a post between
+// /approved folders (""=root). Mirrors PATCH /raws/:clipId for the agent.
+app.patch(`${APPROVED_POSTS_PREFIX}/:postId`, requireAuth, async (c) => {
     const proxied = await maybeProxyUnknownReadyPostToUpstream(c);
     if (proxied)
         return proxied;
-    const post = await serverlessRecords.getReadyPost(c.req.param("postId"));
+    const post = await serverlessRecords.getReadyPost(String(c.req.param("postId")));
+    if (!post) {
+        return c.json({ error: "Approved post not found." }, 404);
+    }
+    try {
+        const customer = requireReadyPostOwner(c, post);
+        const body = (await c.req.json().catch(() => ({})));
+        const folderPath = normalizeFolderPath(body.folder_path ?? "");
+        const updated = await serverlessRecords.setReadyPostFolder(customer.id, post.id, folderPath);
+        return c.json({ post: updated ? serializeReadyPost(c, updated, { includePrivate: true }) : null });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Forbidden" }, 403);
+    }
+});
+app.get(`${APPROVED_POSTS_PREFIX}/:postId/download-zip`, async (c) => {
+    const proxied = await maybeProxyUnknownReadyPostToUpstream(c);
+    if (proxied)
+        return proxied;
+    const post = await serverlessRecords.getReadyPost(c.req.param("postId"));
     if (!post || post.status === "deleted") {
         return c.json({ error: "Approved post not found." }, 404);
     }
@@ -16138,7 +17721,18 @@ 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 publicUrl = stored.url || storage.getPublicUrl(storageKey) || buildUserAttachmentViewUrl(c, storageKey);
         const embedded = notes ? await embedAttachmentNotes(customer.id, { fileName, folderPath, notes }) : null;
+        // Durable poster for the file directory (image = itself, video = extracted
+        // frame from the just-stored object, else none). Fail-soft — never blocks.
+        const thumb = await ensureAttachmentThumbnail({
+            customerId: customer.id,
+            attachmentId,
+            storageKey,
+            contentType,
+            attachmentUrl: publicUrl,
+            sourceUrl: publicUrl
+        });
         await serverlessRecords.createUserAttachment({
             id: attachmentId,
             customerId: customer.id,
@@ -16147,7 +17741,9 @@ app.post(`${USER_PREFIX}/me/attachments/upload`, async (c) => {
             sizeBytes: buffer.byteLength,
             storageKey,
             folderPath,
-            publicUrl: stored.url || storage.getPublicUrl(storageKey) || buildUserAttachmentViewUrl(c, storageKey),
+            publicUrl,
+            thumbnailStorageKey: thumb?.thumbnailStorageKey ?? null,
+            thumbnailUrl: thumb?.thumbnailUrl ?? null,
             notes,
             notesEmbedding: embedded?.embedding ?? null,
             notesEmbeddingModel: embedded?.model ?? null
@@ -16162,6 +17758,122 @@ app.post(`${USER_PREFIX}/me/attachments/upload`, async (c) => {
         return c.json({ error: error instanceof Error ? error.message : "Unable to upload attachment." }, 400);
     }
 });
+// POST /me/attachments/from-url — save a durable media URL (e.g. a finished
+// inpaint / generate job's output) into My Files at a chosen folder. Fetched
+// server-side so cross-origin S3 objects don't need browser CORS. Only trusted
+// app / storage origins are allowed (no arbitrary SSRF fetch).
+function isTrustedMediaOrigin(u) {
+    try {
+        if (u.protocol !== "https:" && u.protocol !== "http:")
+            return false;
+        const appOrigin = new URL(config.PUBLIC_BASE_URL).origin;
+        if (u.origin === appOrigin)
+            return true;
+        if (config.AWS_S3_ENDPOINT) {
+            try {
+                if (u.origin === new URL(config.AWS_S3_ENDPOINT).origin)
+                    return true;
+            }
+            catch { /* noop */ }
+        }
+        const host = u.hostname.toLowerCase();
+        if (host.endsWith(".amazonaws.com"))
+            return true;
+        if (host.endsWith(".cloudfront.net"))
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+app.post(`${USER_PREFIX}/me/attachments/from-url`, async (c) => {
+    try {
+        const customer = requireCustomer(c);
+        const raw = (await c.req.json().catch(() => null));
+        const src = typeof raw?.source_url === "string" ? raw.source_url.trim() : "";
+        if (!src) {
+            return c.json({ error: "source_url is required." }, 400);
+        }
+        let sourceUrl;
+        try {
+            sourceUrl = new URL(src, config.PUBLIC_BASE_URL);
+        }
+        catch {
+            return c.json({ error: "source_url is not a valid URL." }, 400);
+        }
+        if (!isTrustedMediaOrigin(sourceUrl)) {
+            return c.json({ error: "source_url must point to a vidfarm asset or job output." }, 400);
+        }
+        const folderPath = sanitizeStorageSubpath(typeof raw?.folder_path === "string" ? raw.folder_path : "");
+        const notes = (typeof raw?.notes === "string" ? raw.notes : "").trim().slice(0, 4000) || null;
+        const response = await fetch(sourceUrl, { method: "GET" });
+        if (!response.ok) {
+            return c.json({ error: `Could not fetch the media (${response.status}).` }, 400);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const buffer = Buffer.from(arrayBuffer);
+        if (buffer.byteLength > 50 * 1024 * 1024) {
+            return c.json({ error: "My Files uploads can be at most 50 MB." }, 400);
+        }
+        const responseType = (response.headers.get("content-type") ?? "").split(";")[0].trim();
+        // Prefer an explicit file_name; else derive from the URL path; else fall back.
+        const urlName = decodeURIComponent((sourceUrl.pathname.split("/").pop() || "").trim());
+        const requested = typeof raw?.file_name === "string" ? raw.file_name.trim() : "";
+        let fileName = sanitizeFileName(requested || urlName || "media.bin");
+        const contentType = responseType || inferAttachmentContentType(fileName);
+        // Ensure the name carries an extension matching the content type so the file
+        // directory renders it correctly (job outputs are often extensionless keys).
+        if (!/\.[a-z0-9]+$/i.test(fileName)) {
+            const extByType = {
+                "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp", "image/gif": "gif",
+                "video/mp4": "mp4", "video/webm": "webm", "audio/mpeg": "mp3", "audio/wav": "wav"
+            };
+            const ext = extByType[contentType.toLowerCase()];
+            if (ext)
+                fileName = `${fileName}.${ext}`;
+        }
+        if (!isAllowedAttachment(fileName, contentType)) {
+            return c.json({ error: `Unsupported attachment type: ${fileName}` }, 400);
+        }
+        const attachmentId = randomUUID();
+        const storageKey = storage.userAttachmentKey(customer.id, attachmentId, fileName, folderPath);
+        const stored = await storage.putBuffer(storageKey, buffer, contentType);
+        const publicUrl = stored.url || storage.getPublicUrl(storageKey) || buildUserAttachmentViewUrl(c, storageKey);
+        const embedded = notes ? await embedAttachmentNotes(customer.id, { fileName, folderPath, notes }) : null;
+        const thumb = await ensureAttachmentThumbnail({
+            customerId: customer.id,
+            attachmentId,
+            storageKey,
+            contentType,
+            attachmentUrl: publicUrl,
+            sourceUrl: publicUrl
+        });
+        await serverlessRecords.createUserAttachment({
+            id: attachmentId,
+            customerId: customer.id,
+            fileName,
+            contentType,
+            sizeBytes: buffer.byteLength,
+            storageKey,
+            folderPath,
+            publicUrl,
+            thumbnailStorageKey: thumb?.thumbnailStorageKey ?? null,
+            thumbnailUrl: thumb?.thumbnailUrl ?? null,
+            notes,
+            notesEmbedding: embedded?.embedding ?? null,
+            notesEmbeddingModel: embedded?.model ?? null
+        });
+        const attachment = await serverlessRecords.getUserAttachment(customer.id, attachmentId);
+        if (!attachment) {
+            return c.json({ error: "Attachment could not be saved." }, 500);
+        }
+        return c.json({ ok: true, attachment: serializeUserAttachment(c, attachment) }, 201);
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Unable to save media to My Files." }, 400);
+    }
+});
 app.post(`${USER_PREFIX}/me/attachments`, async (c) => {
     try {
         const customer = requireCustomer(c);
@@ -16181,6 +17893,17 @@ app.post(`${USER_PREFIX}/me/attachments`, async (c) => {
         }
         const notes = body.notes?.trim() || null;
         const embedded = notes ? await embedAttachmentNotes(customer.id, { fileName, folderPath, notes }) : null;
+        const publicUrl = storage.getPublicUrl(expectedStorageKey) || buildUserAttachmentViewUrl(c, expectedStorageKey);
+        // The bytes were PUT straight to storage (no local copy here), so the frame
+        // extractor fetches them back from the object's own durable URL. Fail-soft.
+        const thumb = await ensureAttachmentThumbnail({
+            customerId: customer.id,
+            attachmentId: body.attachment_id,
+            storageKey: expectedStorageKey,
+            contentType,
+            attachmentUrl: publicUrl,
+            sourceUrl: publicUrl
+        });
         await serverlessRecords.createUserAttachment({
             id: body.attachment_id,
             customerId: customer.id,
@@ -16189,7 +17912,9 @@ app.post(`${USER_PREFIX}/me/attachments`, async (c) => {
             sizeBytes: body.size_bytes,
             storageKey: expectedStorageKey,
             folderPath,
-            publicUrl: storage.getPublicUrl(expectedStorageKey) || buildUserAttachmentViewUrl(c, expectedStorageKey),
+            publicUrl,
+            thumbnailStorageKey: thumb?.thumbnailStorageKey ?? null,
+            thumbnailUrl: thumb?.thumbnailUrl ?? null,
             notes,
             notesEmbedding: embedded?.embedding ?? null,
             notesEmbeddingModel: embedded?.model ?? null
@@ -16369,7 +18094,7 @@ app.post(`${USER_PREFIX}/me/temporary-files/presign`, async (c) => {
         const body = userTemporaryFilePresignSchema.parse(await c.req.json());
         const fileName = sanitizeFileName(body.file_name);
         const contentType = body.content_type?.trim() || inferAttachmentContentType(fileName);
-        const folderPath = sanitizeStorageSubpath(body.folder_path);
+        const folderPath = withTempDateFolder(sanitizeStorageSubpath(body.folder_path));
         if (!isAllowedAttachment(fileName, contentType)) {
             return c.json({ error: `Unsupported temporary file type: ${fileName}` }, 400);
         }
@@ -16427,7 +18152,7 @@ app.post(`${USER_PREFIX}/me/temporary-files/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 folderPath = withTempDateFolder(sanitizeStorageSubpath(String(formData.get("folder_path") ?? "")));
         if (!isAllowedAttachment(fileName, contentType)) {
             return c.json({ error: `Unsupported temporary file type: ${fileName}` }, 400);
         }
@@ -16549,6 +18274,338 @@ app.delete(`${USER_PREFIX}/me/temporary-files/:fileId`, async (c) => {
     await serverlessRecords.deleteUserTemporaryFile(customer.id, file.id);
     return c.json({ ok: true, file_id: file.id });
 });
+// ── Unified file directory ───────────────────────────────────────────────────
+// The first-class, navigable view over all three file backends as one tree:
+//   /files  → My Files attachments   /temp → temp scratch   /raws → clip library
+// Both the reskin explorer UI and the AI chat agent browse through here, so a
+// path like /raws/product-demos is a real, copyable, agent-addressable location.
+// GET /me/directory?path=/raws/demos → folders[] + files[] under that path.
+// path "/" (or omitted) lists the three roots as folders.
+app.get(`${USER_PREFIX}/me/directory`, async (c) => {
+    const customer = requireCustomer(c);
+    const parsed = parseDirectoryPath(c.req.query("path") ?? "");
+    if (!parsed.root) {
+        return c.json({ path: "/", root: null, folders: directoryRootFolders(), files: [], next_offset: null });
+    }
+    const limit = clampPageLimit(Number(c.req.query("limit") || "200"), 500);
+    const offset = Math.max(0, Math.trunc(Number(c.req.query("offset") || "0")) || 0);
+    // Exact shot-kind filter (raws only): comma-separated OR set of content_type tags.
+    const contentTypes = (c.req.query("content_type") || "")
+        .split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+    try {
+        const { folders, files } = await listDirectoryFolder(c, customer.id, parsed.root, parsed.folderPath);
+        const filtered = (parsed.root === "raws" && contentTypes.length)
+            ? files.filter((f) => {
+                const tags = (f.meta && f.meta.tags) || null;
+                const ct = Array.isArray(tags?.content_type) ? tags?.content_type : [];
+                return ct.some((x) => contentTypes.includes(String(x).toLowerCase()));
+            })
+            : files;
+        const page = filtered.slice(offset, offset + limit);
+        const nextOffset = filtered.length > offset + limit ? offset + limit : null;
+        return c.json({
+            path: buildDirectoryPath(parsed.root, parsed.folderPath),
+            root: parsed.root,
+            folders,
+            files: page,
+            next_offset: nextOffset
+        });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Unable to list directory." }, 400);
+    }
+});
+// Cloud passthrough for a `vidfarm serve` box: browse the CLOUD (vidfarm.cc)
+// directory alongside the local one so the file explorer can offer /local vs
+// /cloud spaces (and `vidfarm directory --both`). Proxies to the same upstream
+// routes with the ambient cloud key. No upstream (e.g. running ON cloud) → 400
+// so the UI simply hides the /cloud tab.
+app.get(`${USER_PREFIX}/me/cloud/directory`, async (c) => {
+    requireCustomer(c);
+    if (!isUpstreamEnabled())
+        return c.json({ error: "No cloud upstream configured on this box." }, 400);
+    const qs = new URLSearchParams();
+    for (const key of ["path", "limit", "offset", "content_type"]) {
+        const v = c.req.query(key);
+        if (v)
+            qs.set(key, v);
+    }
+    const res = await upstreamJson(`${USER_PREFIX}/me/directory${qs.toString() ? `?${qs.toString()}` : ""}`);
+    if (!res.ok || !res.json)
+        return c.json({ error: "Cloud directory unavailable." }, 502);
+    return c.json(res.json);
+});
+app.post(`${USER_PREFIX}/me/cloud/directory/search`, async (c) => {
+    requireCustomer(c);
+    if (!isUpstreamEnabled())
+        return c.json({ error: "No cloud upstream configured on this box." }, 400);
+    const body = await c.req.json().catch(() => ({}));
+    const res = await upstreamJson(`${USER_PREFIX}/me/directory/search`, { method: "POST", body });
+    if (!res.ok || !res.json)
+        return c.json({ error: "Cloud search unavailable." }, 502);
+    return c.json(res.json);
+});
+// POST /me/directory/search { query, path?, mode?, limit? }
+// Unified search combining semantic (vector), substring, and absolute-path
+// matching across the in-scope roots. `path` narrows scope to one root/folder;
+// `mode` ∈ auto|semantic|substring|path (default auto = all three signals).
+function directoryPathContains(itemPath, query) {
+    return itemPath.toLowerCase().includes(query.toLowerCase());
+}
+app.post(`${USER_PREFIX}/me/directory/search`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json().catch(() => ({})));
+        const query = (body.query ?? "").trim();
+        if (!query)
+            return c.json({ error: "Provide a search query." }, 400);
+        const limit = Math.max(1, Math.min(50, Number(body.limit) || 20));
+        // Exact shot-kind filter applied to the /raws branch only.
+        const contentTypes = (body.content_type || "")
+            .split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+        const parsed = parseDirectoryPath(body.path ?? "");
+        const scopeRoots = parsed.root ? [parsed.root] : DIRECTORY_ROOT_KEYS;
+        const scopeFolder = normalizeFolderPath(parsed.folderPath);
+        const inScopeFolder = (fp) => !scopeFolder || (normalizeFolderPath(fp) + "/").indexOf(scopeFolder + "/") === 0;
+        const mode = ["semantic", "substring", "path"].includes(String(body.mode)) ? body.mode : "auto";
+        const wantSemantic = mode === "auto" || mode === "semantic";
+        const wantSubstring = mode === "auto" || mode === "substring";
+        const wantPath = mode === "auto" || mode === "path";
+        const scored = [];
+        let semanticUsed = false;
+        // ── /files: notes embedding (semantic) + name/folder/notes substring ──────
+        if (scopeRoots.includes("files")) {
+            const atts = (await serverlessRecords.listUserAttachments(customer.id)).filter((a) => inScopeFolder(a.folderPath));
+            let queryEmbedding;
+            if (wantSemantic) {
+                try {
+                    const embedder = await buildFileNotesEmbedder(customer.id);
+                    if (embedder)
+                        queryEmbedding = await embedder.embedQuery(query);
+                }
+                catch (error) {
+                    devLog("directory_search.files_embed_failed", devErrorFields(error));
+                }
+            }
+            if (queryEmbedding)
+                semanticUsed = true;
+            for (const a of atts) {
+                const item = attachmentToDirectoryItem(c, a);
+                let score = 0;
+                let sem = false;
+                if (queryEmbedding && Array.isArray(a.notesEmbedding) && a.notesEmbedding.length > 0) {
+                    const sim = cosineSimilarity(a.notesEmbedding, queryEmbedding);
+                    if (sim > 0) {
+                        score += sim;
+                        sem = true;
+                    }
+                }
+                if (wantSubstring && attachmentKeywordMatch(a, query))
+                    score += 0.5;
+                if (wantPath && directoryPathContains(item.path, query))
+                    score += 0.6;
+                if (score > 0)
+                    scored.push({ item, score, semantic: sem });
+            }
+        }
+        // ── /temp: no embeddings → substring + absolute-path only ─────────────────
+        if (scopeRoots.includes("temp")) {
+            const files = (await serverlessRecords.listUserTemporaryFiles(customer.id)).filter((f) => inScopeFolder(f.folderPath));
+            for (const f of files) {
+                const item = temporaryFileToDirectoryItem(c, f);
+                let score = 0;
+                if (wantSubstring && attachmentKeywordMatch(f, query))
+                    score += 0.5;
+                if (wantPath && directoryPathContains(item.path, query))
+                    score += 0.6;
+                if (score > 0)
+                    scored.push({ item, score, semantic: false });
+            }
+        }
+        // ── /raws: semantic-first clip search, or keyword/path filter otherwise ────
+        if (scopeRoots.includes("raws")) {
+            if (wantSemantic) {
+                let queryEmbedding;
+                try {
+                    const embedder = await buildMatchEmbedder(customer.id);
+                    if (embedder)
+                        [queryEmbedding] = await embedder.embedQueries([query]);
+                }
+                catch (error) {
+                    devLog("directory_search.raws_embed_failed", devErrorFields(error));
+                }
+                if (queryEmbedding)
+                    semanticUsed = true;
+                const hits = await searchUserClips(customer.id, {
+                    criteria: { semantic_text: query, ...(contentTypes.length ? { content_type: contentTypes } : {}) },
+                    queryEmbedding,
+                    limit: limit * 3
+                });
+                for (const h of hits) {
+                    if (!inScopeFolder(h.clip.folder_path))
+                        continue;
+                    const item = clipSerializedToDirectoryItem(await serializeClip(h.clip));
+                    scored.push({ item, score: h.similarity ?? h.score ?? 0.1, semantic: Boolean(queryEmbedding) });
+                }
+            }
+            else {
+                const clips = (await clipRecords.listClips(customer.id, { limit: 5000 }))
+                    .filter((cl) => inScopeFolder(cl.folder_path))
+                    .filter((cl) => !contentTypes.length || (cl.tags?.content_type ?? []).some((ct) => contentTypes.includes(String(ct).toLowerCase())));
+                for (const cl of clips) {
+                    const kw = wantSubstring && clipKeywordMatch(cl, query);
+                    const item = clipSerializedToDirectoryItem(await serializeClip(cl));
+                    const pm = wantPath && directoryPathContains(item.path, query);
+                    if (kw || pm)
+                        scored.push({ item, score: (kw ? 0.5 : 0) + (pm ? 0.6 : 0), semantic: false });
+                }
+            }
+        }
+        // ── /approved: no embeddings → substring (title/caption/tracer) + path ─────
+        if (scopeRoots.includes("approved")) {
+            const posts = (await serverlessRecords.listReadyPosts(customer.id))
+                .filter((p) => p.status !== "deleted")
+                .filter((p) => inScopeFolder(p.folderPath ?? ""));
+            const ql = query.toLowerCase();
+            for (const p of posts) {
+                const item = readyPostToDirectoryItem(p);
+                let score = 0;
+                const hay = [p.title, p.caption, p.tracer].filter(Boolean).join(" ").toLowerCase();
+                if (wantSubstring && hay.includes(ql))
+                    score += 0.5;
+                if (wantPath && directoryPathContains(item.path, query))
+                    score += 0.6;
+                if (score > 0)
+                    scored.push({ item, score, semantic: false });
+            }
+        }
+        scored.sort((x, y) => y.score - x.score);
+        const results = scored.slice(0, limit).map((s) => ({ ...s.item, score: s.score }));
+        return c.json({ results, query, mode, scope: parsed.root ?? "all", semantic: semanticUsed });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Directory search failed." }, 400);
+    }
+});
+// POST /me/directory/folders { path } — create an empty folder at a canonical
+// path (e.g. /files/brand-assets, /raws/demos). Persisted as a user_file_folder
+// record scoped to the root, so it shows up in listings before any file lands.
+app.post(`${USER_PREFIX}/me/directory/folders`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json().catch(() => ({})));
+        const parsed = parseDirectoryPath(body.path ?? "");
+        if (!parsed.root || !parsed.folderPath) {
+            return c.json({ error: "Provide a folder path under a root, e.g. /files/brand-assets or /raws/demos." }, 400);
+        }
+        if (parsed.root === "projects") {
+            return c.json({ error: "/projects is read-only — folders there are your composition forks. Create a project by forking a template in the editor." }, 400);
+        }
+        await serverlessRecords.createUserFileFolder(customer.id, directoryFolderScope(parsed.root), parsed.folderPath);
+        return c.json({ ok: true, path: buildDirectoryPath(parsed.root, parsed.folderPath), root: parsed.root, folder_path: parsed.folderPath });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Unable to create folder." }, 400);
+    }
+});
+// POST /me/directory/rename { path, new_name, file_id? } — rename a file or a
+// folder in place. With file_id it's a FILE rename (display name only — the S3
+// key and view URL are untouched); without it, the trailing segment of `path`
+// is treated as a FOLDER and renamed (its files, and for /raws its nested
+// subfolders, move with it). Both the explorer UI and the chat agent call this,
+// so directory entries — character folders especially — stay tidy over time.
+app.post(`${USER_PREFIX}/me/directory/rename`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json().catch(() => ({})));
+        const parsed = parseDirectoryPath(body.path ?? "");
+        const rawName = String(body.new_name ?? "").trim();
+        const fileId = String(body.file_id ?? "").trim();
+        if (!parsed.root) {
+            return c.json({ error: "Provide a path under a root (/files, /temp, /raws, /projects, /approved)." }, 400);
+        }
+        if (parsed.root === "projects") {
+            return c.json({ error: "/projects is read-only — its folders are your composition forks and its files are stored composition assets. Rename a project by editing its title in the editor." }, 400);
+        }
+        if (!rawName) {
+            return c.json({ error: "Provide new_name." }, 400);
+        }
+        // ── FILE rename (file_id given) — /files and /temp only ──────────────────
+        if (fileId) {
+            const newName = sanitizeFileName(rawName);
+            if (!newName)
+                return c.json({ error: "Provide a valid new file name." }, 400);
+            if (parsed.root === "files") {
+                const att = await serverlessRecords.getUserAttachment(customer.id, fileId);
+                if (!att)
+                    return c.json({ error: "File not found." }, 404);
+                if (!isAllowedAttachment(newName, att.contentType)) {
+                    return c.json({ error: `Unsupported file name: ${newName}` }, 400);
+                }
+                const updated = await serverlessRecords.renameUserAttachment(customer.id, fileId, newName);
+                if (!updated)
+                    return c.json({ error: "File not found." }, 404);
+                return c.json({
+                    ok: true,
+                    path: buildDirectoryPath("files", updated.folderPath, newName),
+                    file: serializeUserAttachment(c, updated)
+                });
+            }
+            if (parsed.root === "temp") {
+                const file = await serverlessRecords.getUserTemporaryFile(customer.id, fileId);
+                if (!file)
+                    return c.json({ error: "File not found." }, 404);
+                const updated = await serverlessRecords.renameUserTemporaryFile(customer.id, fileId, newName);
+                if (!updated)
+                    return c.json({ error: "File not found." }, 404);
+                return c.json({
+                    ok: true,
+                    path: buildDirectoryPath("temp", updated.folderPath, newName),
+                    file: serializeUserTemporaryFile(c, updated)
+                });
+            }
+            return c.json({ error: "Raws and approved posts are named after their source/title and can't be renamed as files — rename their folder, or use move to reorganize them." }, 400);
+        }
+        // ── FOLDER rename (no file_id) — rename the trailing path segment ─────────
+        const fromFolder = normalizeFolderPath(parsed.folderPath);
+        if (!fromFolder) {
+            return c.json({ error: "Provide a folder path (e.g. /files/characters/zara) or a file_id to rename a file." }, 400);
+        }
+        const newSegment = sanitizeStorageSubpath(rawName);
+        if (!newSegment || newSegment.includes("/")) {
+            return c.json({ error: "A folder name can't be empty or contain slashes." }, 400);
+        }
+        const segs = fromFolder.split("/");
+        segs[segs.length - 1] = newSegment;
+        const toFolder = normalizeFolderPath(segs.join("/"));
+        if (parsed.root === "files") {
+            await serverlessRecords.moveUserFileFolder(customer.id, "my_files", fromFolder, toFolder);
+            await serverlessRecords.moveUserAttachmentFolder(customer.id, fromFolder, toFolder);
+        }
+        else if (parsed.root === "temp") {
+            await serverlessRecords.moveUserFileFolder(customer.id, "temporary", fromFolder, toFolder);
+            await serverlessRecords.moveUserTemporaryFolder(customer.id, fromFolder, toFolder);
+        }
+        else if (parsed.root === "approved") {
+            await serverlessRecords.moveUserFileFolder(customer.id, "approved", fromFolder, toFolder);
+            await serverlessRecords.moveReadyPostFolder(customer.id, fromFolder, toFolder);
+        }
+        else {
+            await serverlessRecords.moveUserFileFolder(customer.id, "raws", fromFolder, toFolder);
+            await clipRecords.moveClipsFolder(customer.id, fromFolder, toFolder);
+        }
+        return c.json({
+            ok: true,
+            path: buildDirectoryPath(parsed.root, toFolder),
+            root: parsed.root,
+            from_folder_path: fromFolder,
+            to_folder_path: toFolder
+        });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Rename failed." }, 400);
+    }
+});
 app.post(`${USER_PREFIX}/me/developer/preview-media/presign`, async (c) => {
     try {
         const customer = requireCustomer(c);
@@ -17008,8 +19065,10 @@ function renderClipsPage(input) {
               : '<div class="clip-noimg">no thumb</div>';
             var vid = clip.view_url ? '<video muted loop playsinline preload="none" style="display:none;position:absolute;inset:0" src="'+esc(clip.view_url)+'"></video>' : '';
             var tags = topTags(clip.tags).map(function(t){ return '<span class="clip-tag">'+esc(t)+'</span>'; }).join('');
+            // The full original video a hunt was mined from is badged distinctly.
+            var sourceBadge = clip.is_source_original ? '<div class="clip-fullbadge" style="position:absolute;top:6px;left:6px;background:rgba(20,20,22,.82);color:#fff;font-size:11px;font-weight:600;padding:2px 7px;border-radius:6px;">Full video</div>' : '';
             return '<div class="clip-card">'
-              + '<div class="clip-thumb" onmouseleave="var v=this.querySelector(&quot;video&quot;); if(v){v.pause();v.style.display=&quot;none&quot;;}">'+media+vid+'<div class="clip-range">'+range+' · '+clip.duration_sec.toFixed(1)+'s</div>'+score+'</div>'
+              + '<div class="clip-thumb" onmouseleave="var v=this.querySelector(&quot;video&quot;); if(v){v.pause();v.style.display=&quot;none&quot;;}">'+media+vid+sourceBadge+'<div class="clip-range">'+range+' · '+clip.duration_sec.toFixed(1)+'s</div>'+score+'</div>'
               + '<div class="clip-body">'
               + '<div class="clip-desc">'+esc(clip.description||clip.tags&&clip.tags.transcript||'(untagged clip)')+'</div>'
               + '<div class="clip-tags">'+tags+'</div>'
@@ -17285,7 +19344,9 @@ async function serializeClip(clip) {
     ]);
     const { embedding, ...rest } = clip;
     void embedding; // never ship the raw vector to the client
-    return { ...rest, view_url, thumbnail_url };
+    // Convenience flag alongside `role` so the raws UI can badge/sort the full
+    // original video without reasoning about the union type.
+    return { ...rest, view_url, thumbnail_url, is_source_original: clip.role === "source" };
 }
 function normalizeScanTier(value) {
     return value === "flash" ? "flash" : "flash-lite";
@@ -17314,18 +19375,73 @@ app.get(RAWS_PREFIX, async (c) => {
         editorChat: await buildClipsEditorChatBoot({ customer })
     }));
 });
-// GET /clips/feed — the caller's clip library as JSON (optional ?source, ?q, ?limit).
+// GET /clips/feed — the caller's clip library as JSON (optional ?source, ?q,
+// ?content_type, ?limit, ?offset). ?content_type is an exact tag filter
+// (comma-separated = OR) over each raw's content_type tags — the /library/raws
+// content-type chips use it for real structured filtering, distinct from ?q
+// semantic/keyword search. ?offset pages the (descending) result set for the
+// chat file browser; the response carries next_offset (null when exhausted).
 app.get(`${RAWS_PREFIX}/feed`, async (c) => {
     const customer = requireCustomer(c);
     const limit = clampPageLimit(Number(c.req.query("limit") || "60"), 200);
+    const offset = Math.max(0, Math.trunc(Number(c.req.query("offset") || "0")) || 0);
     const q = c.req.query("q")?.trim();
+    const contentTypes = (c.req.query("content_type") || "")
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    // ?folder= scopes the feed to one virtual Raws subfolder (exact match, or ""
+    // for the raws root) — the directory browser navigates with it.
+    const folderParam = c.req.query("folder");
+    const folderScoped = folderParam != null;
+    const folder = normalizeFolderPath(folderParam ?? "");
+    const narrowed = Boolean(q) || contentTypes.length > 0 || folderScoped;
+    // Unfiltered: load only up to the page window (+1 to detect a next page),
+    // capped so a huge library never pulls unbounded. Filtered paths must scan a
+    // wider set before slicing, since the filter runs in memory.
+    const loadLimit = narrowed ? 5000 : Math.min(offset + limit + 1, 2000);
     let clips = await clipRecords.listClips(customer.id, {
         sourceVideoId: c.req.query("source") || undefined,
-        limit: q ? 5000 : limit
+        limit: loadLimit
     });
+    // Derive the folder tree from every loaded clip BEFORE the folder scope trims
+    // the set (so the browser can see sibling folders). Complete whenever the load
+    // scanned the whole library (all narrowed paths do).
+    const folders = buildFolderList(clips.map((clip) => ({ folderPath: clip.folder_path })));
+    if (contentTypes.length) {
+        clips = clips.filter((clip) => (clip.tags.content_type ?? []).some((ct) => contentTypes.includes(ct)));
+    }
+    if (folderScoped) {
+        clips = clips.filter((clip) => normalizeFolderPath(clip.folder_path) === folder);
+    }
     if (q)
-        clips = clips.filter((clip) => clipKeywordMatch(clip, q)).slice(0, limit);
-    return c.json({ clips: await Promise.all(clips.map(serializeClip)) });
+        clips = clips.filter((clip) => clipKeywordMatch(clip, q));
+    const page = clips.slice(offset, offset + limit);
+    const nextOffset = clips.length > offset + limit ? offset + limit : null;
+    return c.json({ clips: await Promise.all(page.map(serializeClip)), folders, next_offset: nextOffset });
+});
+// PATCH /raws/:clipId — move a clip between virtual Raws folders (or to the
+// root with folder_path: ""). Registered before other /raws/:param routes so a
+// literal like "feed"/"search" never matches as a clip id (those are GET/POST).
+app.patch(`${RAWS_PREFIX}/:clipId`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json().catch(() => ({})));
+        if (typeof body.folder_path !== "string") {
+            return c.json({ error: "Provide folder_path (\"\" moves to the raws root)." }, 400);
+        }
+        const clipId = c.req.param("clipId");
+        const existing = await clipRecords.getClip(customer.id, clipId);
+        if (!existing)
+            return c.json({ error: "Raw not found." }, 404);
+        const folderPath = normalizeFolderPath(body.folder_path);
+        await clipRecords.updateClipFolder(customer.id, clipId, folderPath);
+        const updated = await clipRecords.getClip(customer.id, clipId);
+        return c.json({ ok: true, clip: updated ? await serializeClip(updated) : null });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Unable to move raw." }, 400);
+    }
 });
 // POST /clips/search — hybrid structured + semantic search.
 app.post(`${RAWS_PREFIX}/search`, async (c) => {
@@ -17440,10 +19556,27 @@ app.post(`${RAWS_PREFIX}/match-scenes`, async (c) => {
 // pipeline runs the hunt and GET /clips/scan/:scanId polls it. Billing is AWS
 // compute only (clip_scan_lambda + step_functions_standard) — the AI spend is
 // the caller's own provider key (BYOK) and is never wallet-billed.
+// Turn a free-text folder name (e.g. "My Campaign 001") into the canonical
+// single-segment Raws folder slug ("my-campaign-001"). Returns null when the
+// input is empty so callers keep the source-derived default. Mirrors the slug
+// transform used elsewhere for auto-named raws folders.
+function slugifyRawFolder(value) {
+    const slug = String(value ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+    return slug || null;
+}
 app.post(`${RAWS_PREFIX}/scan`, async (c) => {
     const customer = requireCustomer(c);
     try {
         const body = (await c.req.json());
+        const importOnly = body.import_only === true;
+        // A caller-named destination folder (the /editor "Clip from Raw" modal sends
+        // the folder name here) overrides the default source-title slug for every
+        // clip this import/hunt produces. Null keeps the source-derived default.
+        const folderOverride = slugifyRawFolder(body.folder_path);
         const guidancePrompt = body.prompt?.trim() || "";
         // Build the hunt spec: explicit structured fields win, the free "what to
         // clip for" prompt fills the gaps (duration band, vertical/aspect, no-text).
@@ -17454,7 +19587,7 @@ app.post(`${RAWS_PREFIX}/scan`, async (c) => {
         if (sourceUrl && !/^https?:\/\//i.test(sourceUrl)) {
             return c.json({ error: "That doesn't look like a valid video URL." }, 400);
         }
-        const huntSpec = normalizeHuntSpec({
+        let huntSpec = normalizeHuntSpec({
             ...(body.hunt_spec && typeof body.hunt_spec === "object" ? body.hunt_spec : {}),
             ...(body.ranges != null ? { ranges: body.ranges } : {}),
             ...(body.target_duration_sec != null ? { target_duration_sec: body.target_duration_sec } : {}),
@@ -17475,8 +19608,20 @@ app.post(`${RAWS_PREFIX}/scan`, async (c) => {
             huntSpec.aspect = parsedPrompt.aspect;
         if (!huntSpec.avoid_text && parsedPrompt.avoid_text)
             huntSpec.avoid_text = true;
+        if (!huntSpec.max_clips && parsedPrompt.max_clips)
+            huntSpec.max_clips = parsedPrompt.max_clips;
         if (!huntSpec.source_url && sourceUrl)
             huntSpec.source_url = sourceUrl;
+        // Carry the named destination folder on the hunt spec — it rides the opaque
+        // hunt_spec object end-to-end (cloud Step Functions, local runner, upstream
+        // backup) so mined clips land in `/raws/<folder>` without a pipeline change.
+        if (folderOverride)
+            huntSpec.folder_path = folderOverride;
+        // Fill the unspecified-prompt mining defaults (5–15s clips, vertical 9:16,
+        // avoid on-screen text). Explicit user/prompt choices above already won;
+        // this only fills the gaps. Skipped for import_only (no mining happens).
+        if (!importOnly)
+            huntSpec = applyHuntSpecDefaults(huntSpec);
         // Uploaded-source hunts: resolve a temp-folder file (the canonical home for
         // hunt originals — 30-day TTL) or a My Files attachment to its S3 key.
         let resolvedS3Key = readNonEmptyString(body.s3_key) ?? undefined;
@@ -17551,6 +19696,34 @@ app.post(`${RAWS_PREFIX}/scan`, async (c) => {
             pipeline: input.pipeline,
             pipeline_deployed: cloudPipeline
         }, 202);
+        // ── Import individual video (no clip mining) ─────────────────────────────
+        // The Import Source modal's unchecked "Clip raws" box: just pull the source
+        // into the raws library as ONE whole-video raw. No BYOK key, no AI tagging,
+        // no wallet bill. Runs inline (awaited) so it's reliable on Lambda, then
+        // returns a "complete" scan the poller sees immediately.
+        if (importOnly) {
+            const importSourcePath = resolvedS3Key ? storage.getLocalPath(resolvedS3Key) : null;
+            if (resolvedS3Key && (!importSourcePath || !existsSync(importSourcePath)) && !huntSpec.source_url) {
+                return c.json({ error: "That upload isn't reachable for a direct import — pass source_url instead." }, 400);
+            }
+            await putScanRecords({ scanStatus: "running" });
+            try {
+                await importWholeVideoAsRaw({
+                    ownerId: customer.id,
+                    scanId,
+                    sourceVideoId,
+                    filename,
+                    tracer,
+                    folderPath: folderOverride,
+                    localSourcePath: importSourcePath && existsSync(importSourcePath) ? importSourcePath : null,
+                    sourceUrl: huntSpec.source_url ?? null
+                });
+            }
+            catch (error) {
+                return c.json({ error: error instanceof Error ? error.message : "Could not import that video." }, 502);
+            }
+            return scanResponse({ status: "complete", pipeline: "local" });
+        }
         if (cloudPipeline) {
             // ── Deployed pipeline (Lambda + Step Functions): BYOK API keys only ──
             if (choice === "agent") {
@@ -17780,7 +19953,11 @@ app.get(`${RAWS_PREFIX}/scan-options`, async (c) => {
 });
 function looksLikeDirectVideoUrl(url) {
     try {
-        return /\.(mp4|mov|m4v|webm|mkv)$/i.test(new URL(url).pathname);
+        const u = new URL(url);
+        // Match a video extension in the path OR a query value (signed/CDN links
+        // often carry the real filename as `?file=clip.mp4` with a path-less route).
+        return /\.(mp4|mov|m4v|webm|mkv)(\?|$)/i.test(u.pathname) ||
+            /\.(mp4|mov|m4v|webm|mkv)(&|$)/i.test(u.search);
     }
     catch {
         return false;
@@ -17789,10 +19966,13 @@ function looksLikeDirectVideoUrl(url) {
 // Local URL ingest for serve-box hunts: direct video links download straight;
 // social URLs (TikTok/YouTube/IG/X) resolve through the same RapidAPI
 // downloader the video_download primitive uses (needs RAPIDAPI_KEY locally).
+// Returns the local path plus the source's human title (when RapidAPI gives one)
+// so callers can name the raw/folder something better than a bare URL slug.
 async function ingestClipSourceUrlLocally(sourceUrl, workDir) {
     if (!sourceUrl)
         throw new Error("Clip scan needs a source video.");
     let mediaUrl = sourceUrl;
+    let title = null;
     if (!looksLikeDirectVideoUrl(sourceUrl)) {
         const apiKey = (config.RAPIDAPI_KEY || "").trim();
         if (!apiKey) {
@@ -17810,11 +19990,14 @@ async function ingestClipSourceUrlLocally(sourceUrl, workDir) {
         if (!lookupRes.ok)
             throw new Error(`Video download lookup failed with HTTP ${lookupRes.status}.`);
         const lookup = (await lookupRes.json());
-        const playable = (lookup.medias ?? []).filter((m) => m.url && m.videoAvailable !== false && (m.type ? /video/i.test(m.type) : true));
-        const chosen = playable.find((m) => (m.extension ?? "").toLowerCase() === "mp4" || /\.mp4(\?|$)/i.test(m.url ?? "")) ?? playable[0];
+        // Pick the HIGHEST-resolution playable MP4 (not just the first one) so the
+        // ingested source — and every clip cut from it — is as high-quality as the
+        // provider offers.
+        const chosen = pickBestVideoMedia(lookup.medias ?? []);
         if (!chosen?.url)
             throw new Error("Video download lookup returned no playable MP4 media URL.");
         mediaUrl = chosen.url;
+        title = typeof lookup.title === "string" && lookup.title.trim() ? lookup.title.trim() : null;
     }
     const localPath = path.join(workDir, "ingest", "source.mp4");
     mkdirSync(path.dirname(localPath), { recursive: true });
@@ -17822,7 +20005,518 @@ async function ingestClipSourceUrlLocally(sourceUrl, workDir) {
     if (!res.ok || !res.body)
         throw new Error(`Source video download failed with HTTP ${res.status}.`);
     await streamPipeline(Readable.fromWeb(res.body), createWriteStream(localPath));
-    return localPath;
+    return { videoPath: localPath, title };
+}
+// Record the RapidAPI social-download cost for an in-process URL ingest (the
+// whole-video import path bypasses the clip-scan Lambda, which is where this
+// third-party cost is normally billed). Mirrors the Lambda's cost center +
+// idempotency key so a retry never double-bills. Non-fatal.
+async function recordRapidApiIngestCost(input) {
+    // Direct .mp4 links never touch RapidAPI, so there's nothing to bill.
+    if (!input.sourceUrl || looksLikeDirectVideoUrl(input.sourceUrl))
+        return;
+    try {
+        await billing.record({
+            customerId: input.ownerId,
+            jobId: input.scanId,
+            tracer: input.tracer ?? null,
+            templateId: "clips/scan",
+            type: "cpu_estimate",
+            costUsd: config.RAPIDAPI_VIDEO_DOWNLOAD_BASE_COST_USD,
+            costCenterSlug: "rapidapi_video_download",
+            idempotencyKey: `rapidapi_video_download:${input.scanId}`,
+            occurredAtMs: Date.now(),
+            metadata: { operation: "clip_import_ingest", source_url: input.sourceUrl }
+        });
+    }
+    catch (error) {
+        devLog("clip_import.ingest_billing_failed", { scan_id: input.scanId, ...devErrorFields(error) }, "warn");
+    }
+}
+// Import a whole video as a SINGLE raw — the plain "import individual video"
+// path behind the Import Source modal's unchecked "Clip raws" box. Ingests the
+// source (direct link or RapidAPI social download), probes its duration, cuts
+// one thumbnail, and writes ONE clip record spanning the entire video. No BYOK
+// key, no AI tagging, no wallet bill. Awaited by the caller so it completes
+// inside the request (reliable on Lambda, which freezes detached work).
+async function importWholeVideoAsRaw(input) {
+    const workRoot = path.join(config.VIDFARM_DATA_DIR, "clip-scans", input.scanId);
+    const touchScan = async (patch) => {
+        const scan = await clipRecords.getScan(input.ownerId, input.scanId);
+        if (scan)
+            await clipRecords.putScan({ ...scan, ...patch, updated_at: nowIso() });
+    };
+    const touchSource = async (patch) => {
+        const source = await clipRecords.getSource(input.ownerId, input.sourceVideoId);
+        if (source)
+            await clipRecords.putSource({ ...source, ...patch, updated_at: nowIso() });
+    };
+    try {
+        mkdirSync(workRoot, { recursive: true });
+        let videoPath = input.localSourcePath;
+        let ingestedTitle = null;
+        if (!videoPath) {
+            const ingested = await ingestClipSourceUrlLocally(input.sourceUrl ?? "", workRoot);
+            videoPath = ingested.videoPath;
+            ingestedTitle = ingested.title;
+            // URL ingest hits RapidAPI (same third-party cost the clip-scan Lambda
+            // bills on its own ingest); the whole-video path skips the Lambda, so
+            // record the download here or it goes unbilled. Non-fatal on failure.
+            await recordRapidApiIngestCost({
+                ownerId: input.ownerId,
+                scanId: input.scanId,
+                tracer: input.tracer,
+                sourceUrl: input.sourceUrl ?? ""
+            });
+        }
+        const probe = await probeVideo(videoPath);
+        const durationSec = probe.duration_sec || 0;
+        await touchSource({ status: "scanning", duration_sec: durationSec });
+        // A RapidAPI title beats a URL-slug filename for the raw's description and
+        // its source-folder name in the /library/raws explorer.
+        const displayName = ingestedTitle || input.filename;
+        const clipId = createIdV7("clip");
+        const clipKey = `clips/${input.ownerId}/${clipId}.mp4`;
+        // Stream the source to storage instead of readFileSync-into-Buffer — whole
+        // videos can be hundreds of MB and would otherwise pin the entire file in
+        // memory on the request Lambda.
+        await storage.putFile(clipKey, videoPath, "video/mp4");
+        let thumbKey = "";
+        const thumbLocal = path.join(workRoot, `${clipId}.jpg`);
+        const wroteThumb = await extractThumbnail({
+            videoPath,
+            scene: { index: 0, start_time_sec: 0, end_time_sec: durationSec, duration_sec: durationSec },
+            outPath: thumbLocal
+        }).catch(() => false);
+        if (wroteThumb && existsSync(thumbLocal)) {
+            thumbKey = `thumbs/${input.ownerId}/${clipId}.jpg`;
+            await storage.putFile(thumbKey, thumbLocal, "image/jpeg");
+        }
+        const clip = {
+            clip_id: clipId,
+            source_video_id: input.sourceVideoId,
+            source_filename: displayName,
+            start_time_sec: 0,
+            end_time_sec: durationSec,
+            duration_sec: durationSec,
+            file_path: clipKey,
+            thumbnail_path: thumbKey,
+            tags: { content_type: [], subject: [], action: [], emotion: [], setting: [], composition: [], motion: [], energy: "", audio_type: [], transcript: "" },
+            description: displayName,
+            taxonomy_version: ACTIVE_TAXONOMY_VERSION,
+            tier: "flash-lite",
+            tracer: input.tracer,
+            // A caller-named folder wins; otherwise default into a source-derived Raws
+            // subfolder (canonical `/raws/<slug>`).
+            folder_path: input.folderPath
+                ? normalizeFolderPath(input.folderPath)
+                : normalizeFolderPath(String(displayName || "")
+                    .toLowerCase()
+                    .replace(/\.[a-z0-9]+$/i, "")
+                    .replace(/[^a-z0-9]+/g, "-")
+                    .replace(/^-+|-+$/g, "")
+                    .slice(0, 60)),
+            owner_id: input.ownerId,
+            created_at: nowIso()
+        };
+        // Best-effort semantic-search embedding of the title/description so an
+        // imported whole video is findable by meaning (not just visible in its
+        // folder). No AI tagging call, no wallet bill — fail-soft when the owner
+        // has no embed-capable key (keyword-only, as before).
+        try {
+            const embedder = await buildClipLibraryEmbedder(input.ownerId);
+            if (embedder?.embeddingModelId) {
+                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_import.embed_failed", { scan_id: input.scanId, ...devErrorFields(error) }, "warn");
+        }
+        await clipRecords.putClip(clip);
+        await vectorIndex.upsert(input.ownerId, clip).catch(() => undefined);
+        await touchSource({ status: "complete", clip_count: 1, filename: displayName });
+        await touchScan({ status: "complete" });
+    }
+    catch (error) {
+        devLog("clip_import.failed", { scan_id: input.scanId, ...devErrorFields(error) }, "error");
+        await touchSource({ status: "failed" }).catch(() => undefined);
+        await touchScan({ status: "failed", error: error instanceof Error ? error.message : String(error) }).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        rmSync(workRoot, { recursive: true, force: true });
+    }
+}
+// ── /tools/clipper support: resolve a preview URL + save an exact subrange ─────
+// Resolve a pasted source URL to a DIRECT, playable media URL (plus a human
+// title / poster) WITHOUT downloading or re-hosting it — the clipper page plays
+// this URL in a <video> so the user can pick a subrange, and only the chosen
+// subrange is ever written to our S3. Direct .mp4/.mov links pass through as-is;
+// social URLs (TikTok/YouTube/IG/X) resolve through the same RapidAPI downloader
+// the video_download primitive uses. This is a lightweight metadata lookup — the
+// billed download/trim happens later in importSubrangeAsRaw when a clip is saved.
+async function resolveSourcePreview(sourceUrl) {
+    const url = (sourceUrl || "").trim();
+    if (!url)
+        throw new Error("A source video URL is required.");
+    if (looksLikeDirectVideoUrl(url)) {
+        const name = (url.split("/").pop() || "").split("?")[0] || null;
+        return { mediaUrl: url, title: name, thumbnail: null, durationSec: null };
+    }
+    const apiKey = (config.RAPIDAPI_KEY || "").trim();
+    if (!apiKey) {
+        throw new Error("Can't resolve that URL for preview (RAPIDAPI_KEY unset) — paste a direct .mp4 URL instead.");
+    }
+    const lookupRes = await fetch(config.RAPIDAPI_VIDEO_DOWNLOAD_URL, {
+        method: "POST",
+        headers: {
+            "x-rapidapi-key": apiKey,
+            "x-rapidapi-host": config.RAPIDAPI_VIDEO_DOWNLOAD_HOST,
+            "content-type": "application/x-www-form-urlencoded"
+        },
+        body: new URLSearchParams({ url })
+    });
+    if (!lookupRes.ok)
+        throw new Error(`Video lookup failed with HTTP ${lookupRes.status}.`);
+    const lookup = (await lookupRes.json());
+    const chosen = pickBestVideoMedia(lookup.medias ?? []);
+    if (!chosen?.url)
+        throw new Error("That URL returned no playable MP4 to preview.");
+    const durationRaw = typeof lookup.duration === "number" ? lookup.duration : Number(lookup.duration);
+    return {
+        mediaUrl: chosen.url,
+        title: typeof lookup.title === "string" && lookup.title.trim() ? lookup.title.trim() : null,
+        thumbnail: typeof lookup.thumbnail === "string" && lookup.thumbnail.trim() ? lookup.thumbnail.trim() : null,
+        durationSec: Number.isFinite(durationRaw) && durationRaw > 0 ? durationRaw : null
+    };
+}
+// Stream a direct media URL to a local file (no RapidAPI). Used when the clipper
+// hands back an already-resolved preview_url so we don't re-resolve it.
+async function downloadDirectToFile(mediaUrl, destPath) {
+    mkdirSync(path.dirname(destPath), { recursive: true });
+    const res = await fetch(mediaUrl);
+    if (!res.ok || !res.body)
+        throw new Error(`Source download failed with HTTP ${res.status}.`);
+    await streamPipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+}
+// Trim EXACTLY [startSec, endSec] out of a source video and save that single
+// subrange as one raw — the /tools/clipper equivalent of importWholeVideoAsRaw,
+// but frame-trimmed instead of whole. The whole source is fetched once to a
+// scratch dir, ffmpeg cuts the range, and only the trimmed mp4 (+ its thumbnail)
+// is written to durable storage. Runs inline; returns the finished clip so the
+// caller can surface it immediately.
+async function importSubrangeAsRaw(input) {
+    const workRoot = path.join(config.VIDFARM_DATA_DIR, "clip-scans", input.scanId);
+    const touchScan = async (patch) => {
+        const scan = await clipRecords.getScan(input.ownerId, input.scanId);
+        if (scan)
+            await clipRecords.putScan({ ...scan, ...patch, updated_at: nowIso() });
+    };
+    const touchSource = async (patch) => {
+        const source = await clipRecords.getSource(input.ownerId, input.sourceVideoId);
+        if (source)
+            await clipRecords.putSource({ ...source, ...patch, updated_at: nowIso() });
+    };
+    try {
+        mkdirSync(workRoot, { recursive: true });
+        let videoPath = input.localSourcePath && existsSync(input.localSourcePath) ? input.localSourcePath : null;
+        let ingestedTitle = null;
+        if (!videoPath && input.mediaUrl) {
+            videoPath = path.join(workRoot, "ingest", "source.mp4");
+            await downloadDirectToFile(input.mediaUrl, videoPath);
+        }
+        else if (!videoPath) {
+            const ingested = await ingestClipSourceUrlLocally(input.sourceUrl ?? "", workRoot);
+            videoPath = ingested.videoPath;
+            ingestedTitle = ingested.title;
+            await recordRapidApiIngestCost({ ownerId: input.ownerId, scanId: input.scanId, tracer: input.tracer, sourceUrl: input.sourceUrl ?? "" });
+        }
+        const probe = await probeVideo(videoPath);
+        const sourceDurationSec = probe.duration_sec || 0;
+        // Clamp the requested range into the real source duration and enforce end>start.
+        const start = Math.max(0, sourceDurationSec > 0 ? Math.min(input.startSec, sourceDurationSec - 0.05) : input.startSec);
+        const rawEnd = sourceDurationSec > 0 ? Math.min(input.endSec, sourceDurationSec) : input.endSec;
+        const end = Math.max(start + 0.05, rawEnd);
+        const clipDurationSec = Number((end - start).toFixed(3));
+        await touchSource({ status: "scanning", duration_sec: sourceDurationSec });
+        const clipId = createIdV7("clip");
+        const clipKey = `clips/${input.ownerId}/${clipId}.mp4`;
+        const localClip = path.join(workRoot, `${clipId}.mp4`);
+        const trimmed = await extractClip({
+            videoPath,
+            scene: { index: 0, start_time_sec: start, end_time_sec: end, duration_sec: clipDurationSec },
+            outPath: localClip
+        });
+        if (!trimmed || !existsSync(localClip))
+            throw new Error("Could not trim that subrange.");
+        await storage.putFile(clipKey, localClip, "video/mp4");
+        let thumbKey = "";
+        const thumbLocal = path.join(workRoot, `${clipId}.jpg`);
+        const wroteThumb = await extractThumbnail({
+            videoPath: localClip,
+            scene: { index: 0, start_time_sec: 0, end_time_sec: clipDurationSec, duration_sec: clipDurationSec },
+            outPath: thumbLocal
+        }).catch(() => false);
+        if (wroteThumb && existsSync(thumbLocal)) {
+            thumbKey = `thumbs/${input.ownerId}/${clipId}.jpg`;
+            await storage.putFile(thumbKey, thumbLocal, "image/jpeg");
+        }
+        const baseName = (input.name || ingestedTitle || input.filename || "clip").trim() || "clip";
+        const description = `${baseName} (${formatClockRange(start)}–${formatClockRange(end)})`;
+        const folderPath = input.folderPath
+            ? normalizeFolderPath(input.folderPath)
+            : normalizeFolderPath(String(baseName).toLowerCase().replace(/\.[a-z0-9]+$/i, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60));
+        const clip = {
+            clip_id: clipId,
+            source_video_id: input.sourceVideoId,
+            source_filename: baseName,
+            start_time_sec: 0,
+            end_time_sec: clipDurationSec,
+            duration_sec: clipDurationSec,
+            file_path: clipKey,
+            thumbnail_path: thumbKey,
+            tags: { content_type: [], subject: [], action: [], emotion: [], setting: [], composition: [], motion: [], energy: "", audio_type: [], transcript: "" },
+            description,
+            taxonomy_version: ACTIVE_TAXONOMY_VERSION,
+            tier: "flash-lite",
+            tracer: input.tracer,
+            folder_path: folderPath,
+            owner_id: input.ownerId,
+            created_at: nowIso()
+        };
+        try {
+            const embedder = await buildClipLibraryEmbedder(input.ownerId);
+            if (embedder?.embeddingModelId) {
+                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_range.embed_failed", { scan_id: input.scanId, ...devErrorFields(error) }, "warn");
+        }
+        await clipRecords.putClip(clip);
+        await vectorIndex.upsert(input.ownerId, clip).catch(() => undefined);
+        await touchSource({ status: "complete", clip_count: 1, filename: baseName });
+        await touchScan({ status: "complete" });
+        return { clipId, clipKey, thumbKey, durationSec: clipDurationSec, sourceStartSec: start, sourceEndSec: end, description, folderPath };
+    }
+    catch (error) {
+        devLog("clip_range.failed", { scan_id: input.scanId, ...devErrorFields(error) }, "error");
+        await touchSource({ status: "failed" }).catch(() => undefined);
+        await touchScan({ status: "failed", error: error instanceof Error ? error.message : String(error) }).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        rmSync(workRoot, { recursive: true, force: true });
+    }
+}
+// Compact H:MM:SS clock for a clip's human description/range label.
+function formatClockRange(sec) {
+    const s = Math.max(0, Math.floor(sec));
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const ss = s % 60;
+    const mm = h > 0 ? String(m).padStart(2, "0") : String(m);
+    return `${h > 0 ? h + ":" : ""}${mm}:${String(ss).padStart(2, "0")}`;
+}
+// POST /raws/resolve-source — resolve a pasted URL to a direct preview media URL
+// (no download, no S3 write). The /tools/clipper page calls this on load so it
+// can play the source and let the user pick a subrange before anything is saved.
+app.post(`${RAWS_PREFIX}/resolve-source`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json().catch(() => ({})));
+        const sourceUrl = readNonEmptyString(body.source_url) ?? readNonEmptyString(body.video_url) ?? readNonEmptyString(body.url);
+        if (!sourceUrl)
+            return c.json({ error: "Provide source_url (a video URL)." }, 400);
+        if (!/^https?:\/\//i.test(sourceUrl))
+            return c.json({ error: "That doesn't look like a valid video URL." }, 400);
+        void customer;
+        const resolved = await resolveSourcePreview(sourceUrl);
+        return c.json({
+            source_url: sourceUrl,
+            preview_url: resolved.mediaUrl,
+            is_direct: looksLikeDirectVideoUrl(sourceUrl),
+            title: resolved.title,
+            duration_sec: resolved.durationSec,
+            thumbnail_url: resolved.thumbnail
+        });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Could not resolve that video URL." }, 502);
+    }
+});
+// POST /raws/clip-range — trim EXACTLY [start_sec, end_sec] from a source and
+// save that single subrange as one raw. Reusable by the web clipper (which sends
+// the already-resolved preview_url), the devcli `clipper` command, and the AI
+// editor-chat. Runs inline and returns the finished clip.
+app.post(`${RAWS_PREFIX}/clip-range`, async (c) => {
+    const customer = requireCustomer(c);
+    try {
+        const body = (await c.req.json().catch(() => ({})));
+        const sourceUrl = readNonEmptyString(body.source_url) ?? readNonEmptyString(body.video_url) ?? readNonEmptyString(body.url);
+        const mediaUrl = readNonEmptyString(body.preview_url) ?? readNonEmptyString(body.media_url);
+        // Resolve an uploaded source (temp file / My Files attachment) to a local key.
+        let resolvedS3Key = readNonEmptyString(body.s3_key) ?? undefined;
+        const tempFileId = readNonEmptyString(body.temp_file_id);
+        const attachmentId = readNonEmptyString(body.attachment_id);
+        if (!resolvedS3Key && tempFileId) {
+            const file = await serverlessRecords.getUserTemporaryFile(customer.id, tempFileId);
+            if (!file)
+                return c.json({ error: "Temporary file not found." }, 404);
+            resolvedS3Key = file.storageKey;
+        }
+        else if (!resolvedS3Key && attachmentId) {
+            const attachment = await serverlessRecords.getUserAttachment(customer.id, attachmentId);
+            if (!attachment)
+                return c.json({ error: "Attachment not found in My Files." }, 404);
+            resolvedS3Key = attachment.storageKey;
+        }
+        const localSourcePath = resolvedS3Key ? storage.getLocalPath(resolvedS3Key) : null;
+        if (!sourceUrl && !mediaUrl && !(localSourcePath && existsSync(localSourcePath))) {
+            return c.json({ error: "Provide source_url / preview_url (a video URL) or temp_file_id/attachment_id/s3_key of an upload." }, 400);
+        }
+        if ((sourceUrl && !/^https?:\/\//i.test(sourceUrl)) || (mediaUrl && !/^https?:\/\//i.test(mediaUrl))) {
+            return c.json({ error: "That doesn't look like a valid video URL." }, 400);
+        }
+        // Accept seconds or milliseconds; require a positive-length range.
+        const startSec = body.start_sec != null ? Number(body.start_sec) : body.start_ms != null ? Number(body.start_ms) / 1000 : 0;
+        const endSec = body.end_sec != null ? Number(body.end_sec) : body.end_ms != null ? Number(body.end_ms) / 1000 : NaN;
+        if (!Number.isFinite(startSec) || startSec < 0)
+            return c.json({ error: "start_sec must be a non-negative number." }, 400);
+        if (!Number.isFinite(endSec))
+            return c.json({ error: "Provide end_sec (or duration via end_ms)." }, 400);
+        if (endSec <= startSec)
+            return c.json({ error: "end_sec must be greater than start_sec." }, 400);
+        const tracer = readNonEmptyString(body.tracer) ?? `clipper:${customer.id}`;
+        const folderOverride = slugifyRawFolder(body.folder_path) ?? slugifyRawFolder(tracer);
+        const now = nowIso();
+        const scanId = createIdV7("clipscan");
+        const sourceVideoId = createIdV7("srcvid");
+        const sourcePointer = mediaUrl ?? sourceUrl ?? resolvedS3Key ?? "";
+        const filename = readNonEmptyString(body.filename) ?? readNonEmptyString(body.name) ?? ((sourcePointer.split("/").pop() || "source.mp4").split("?")[0] || "source.mp4");
+        await clipRecords.putSource({ source_video_id: sourceVideoId, owner_id: customer.id, filename, raw_s3_uri: sourceUrl ?? sourcePointer, clip_count: 0, tier: "flash-lite", status: "pending", scan_id: scanId, tracer, created_at: now, updated_at: now });
+        await clipRecords.putScan({ scan_id: scanId, owner_id: customer.id, source_video_id: sourceVideoId, status: "running", tier: "flash-lite", raw_s3_uri: sourceUrl ?? sourcePointer, tracer, created_at: now, updated_at: now });
+        let result;
+        try {
+            result = await importSubrangeAsRaw({
+                ownerId: customer.id,
+                scanId,
+                sourceVideoId,
+                filename,
+                tracer,
+                folderPath: folderOverride,
+                localSourcePath: localSourcePath && existsSync(localSourcePath) ? localSourcePath : null,
+                mediaUrl: mediaUrl ?? null,
+                sourceUrl: sourceUrl ?? null,
+                startSec,
+                endSec,
+                name: readNonEmptyString(body.name) ?? null
+            });
+        }
+        catch (error) {
+            return c.json({ error: error instanceof Error ? error.message : "Could not clip that subrange." }, 502);
+        }
+        const [viewUrl, thumbnailUrl] = await Promise.all([
+            clipMediaUrl(result.clipKey),
+            result.thumbKey ? clipMediaUrl(result.thumbKey) : Promise.resolve(null)
+        ]);
+        return c.json({
+            clip_id: result.clipId,
+            source_video_id: sourceVideoId,
+            tracer,
+            folder_path: result.folderPath,
+            duration_sec: result.durationSec,
+            source_start_sec: result.sourceStartSec,
+            source_end_sec: result.sourceEndSec,
+            description: result.description,
+            view_url: viewUrl ?? `/clips/${result.clipId}/download`,
+            thumbnail_url: thumbnailUrl
+        });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Could not clip that subrange." }, 500);
+    }
+});
+// Store the full-length ORIGINAL video as a durable role:"source" raw for a
+// serve-box hunt — the same durable-original behavior the cloud finalize adds,
+// but reusing the local storage driver. The source is still on disk at finalize,
+// so it's copied straight in at its ORIGINAL aspect (no 9:16 crop). It lands in
+// the SAME source-slug folder as its mined clips so /library/raws groups them.
+// Best-effort; the caller ignores failures so the hunt still completes.
+async function storeSourceOriginalRawLocal(input) {
+    // Dedupe: never mint a second source-original for this source (re-run safety).
+    const existing = await clipRecords.listClips(input.ownerId, { sourceVideoId: input.sourceVideoId, limit: 5000 });
+    if (existing.some((c) => c.role === "source"))
+        return;
+    const source = await clipRecords.getSource(input.ownerId, input.sourceVideoId);
+    const tracer = source?.tracer;
+    const displayName = source?.filename || input.filename;
+    const clipId = createIdV7("clip");
+    const clipKey = `clips/${input.ownerId}/${clipId}.mp4`;
+    await storage.putFile(clipKey, input.videoPath, "video/mp4");
+    let thumbKey = "";
+    const thumbLocal = path.join(input.workRoot, `source-${clipId}.jpg`);
+    const wroteThumb = await extractThumbnail({
+        videoPath: input.videoPath,
+        scene: { index: 0, start_time_sec: 0, end_time_sec: input.durationSec, duration_sec: input.durationSec },
+        outPath: thumbLocal
+    }).catch(() => false);
+    if (wroteThumb && existsSync(thumbLocal)) {
+        thumbKey = `thumbs/${input.ownerId}/${clipId}.jpg`;
+        await storage.putFile(thumbKey, thumbLocal, "image/jpeg");
+    }
+    const clip = {
+        clip_id: clipId,
+        source_video_id: input.sourceVideoId,
+        source_filename: input.filename,
+        start_time_sec: 0,
+        end_time_sec: input.durationSec,
+        duration_sec: input.durationSec,
+        file_path: clipKey,
+        thumbnail_path: thumbKey,
+        tags: { content_type: [], subject: [], action: [], emotion: [], setting: [], composition: [], motion: [], energy: "", audio_type: [], transcript: "" },
+        description: displayName,
+        taxonomy_version: ACTIVE_TAXONOMY_VERSION,
+        tier: "flash-lite",
+        role: "source",
+        ...(tracer ? { tracer } : {}),
+        // Group with the mined clips: reuse the folder they actually landed in (a
+        // caller-named destination or the source slug) so the "Full video" raw sits
+        // in the same folder. Falls back to the source-title slug when no mined clip
+        // recorded one.
+        folder_path: existing.find((c) => c.folder_path)?.folder_path ?? normalizeFolderPath(String(input.filename || "")
+            .toLowerCase()
+            .replace(/\.[a-z0-9]+$/i, "")
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 60)),
+        owner_id: input.ownerId,
+        created_at: nowIso()
+    };
+    // Best-effort embedding so the full original is findable by meaning too.
+    try {
+        const embedder = await buildClipLibraryEmbedder(input.ownerId);
+        if (embedder?.embeddingModelId) {
+            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.source_original_embed_failed", { source_video_id: input.sourceVideoId, ...devErrorFields(error) }, "warn");
+    }
+    await clipRecords.putClip(clip);
+    await vectorIndex.upsert(input.ownerId, clip).catch(() => undefined);
 }
 // In-process clip hunt for `vidfarm serve` boxes (no Step Functions worker).
 // Mirrors the clip-scan Lambda pipeline — ingest → probe/detect → refine →
@@ -17843,7 +20537,7 @@ async function runClipScanInProcess(input) {
     };
     try {
         mkdirSync(workRoot, { recursive: true });
-        const videoPath = input.localSourcePath ?? (await ingestClipSourceUrlLocally(input.sourceUrl ?? "", workRoot));
+        const videoPath = input.localSourcePath ?? (await ingestClipSourceUrlLocally(input.sourceUrl ?? "", workRoot)).videoPath;
         const probe = await probeVideo(videoPath);
         await touchSource({ status: "scanning", duration_sec: probe.duration_sec });
         const spec = input.huntSpec;
@@ -17860,6 +20554,9 @@ async function runClipScanInProcess(input) {
                 ? { aspect: spec.aspect, focus: normalizeCropFocus(spec.crop_focus) }
                 : undefined
         };
+        // Aim for a distinct, density-bounded set (default ~10 clips / 10 min) over
+        // the effective (windowed) source duration.
+        const targetClipCount = resolveTargetClipCount(effectiveHuntDurationSec(probe.duration_sec, spec.windows), spec);
         let stored = 0;
         await scanVideo({
             ctx,
@@ -17867,12 +20564,28 @@ async function runClipScanInProcess(input) {
             probe,
             windows: spec.windows,
             durationBand: spec.duration_band ?? null,
+            targetClipCount,
             sourceVideoId: input.sourceVideoId,
             sourceFilename: input.filename,
             ownerId: input.ownerId,
             // Local agents run one CLI process per call — keep parallelism modest.
             concurrency: input.client.provider === "local-agent" ? 2 : 3,
             onClip: async (clip) => {
+                // Folder the mined clip: a caller-named destination (hunt_spec.folder_path,
+                // e.g. the /editor "Clip from Raw" folder) wins; otherwise fall back to the
+                // source-title slug so the local library groups by source like the cloud
+                // pipeline does. Legacy clips without either stay unfoldered.
+                if (!clip.folder_path) {
+                    const sourceSlug = String(input.filename || "")
+                        .toLowerCase()
+                        .replace(/\.[a-z0-9]+$/i, "")
+                        .replace(/[^a-z0-9]+/g, "-")
+                        .replace(/^-+|-+$/g, "")
+                        .slice(0, 60);
+                    const folder = spec.folder_path || sourceSlug;
+                    if (folder)
+                        clip.folder_path = folder;
+                }
                 // Persist through the storage service (local driver) as bare keys —
                 // clipMediaUrl resolves clips/… + thumbs/… keys to fetchable URLs.
                 const clipKey = `clips/${input.ownerId}/${clip.clip_id}.mp4`;
@@ -17896,6 +20609,20 @@ async function runClipScanInProcess(input) {
                 devLog("clip_scan.local_scene_failed", { scan_id: input.scanId, scene_start: scene.start_time_sec, ...devErrorFields(error) }, "warn");
             }
         });
+        // Keep a durable full-length copy of the original as its own role:"source"
+        // raw, grouped with the mined clips — only when the hunt produced clips.
+        // Fail-soft: a failure here must NOT fail the hunt. clip_count stays the
+        // mined count (the source-original is an extra reference raw).
+        if (stored > 0) {
+            await storeSourceOriginalRawLocal({
+                ownerId: input.ownerId,
+                sourceVideoId: input.sourceVideoId,
+                filename: input.filename,
+                videoPath,
+                durationSec: probe.duration_sec,
+                workRoot
+            }).catch((error) => devLog("clip_scan.source_original_failed", { scan_id: input.scanId, ...devErrorFields(error) }, "warn"));
+        }
         await touchSource({ status: "complete", clip_count: stored });
         await touchScan({ status: "complete" });
     }
@@ -17995,7 +20722,11 @@ async function mirrorUpstreamClipsToLocal(input) {
         }
         await clipRecords.putClip(clip);
         await vectorIndex.upsert(ownerId, clip);
-        stored++;
+        // The upstream feed includes the source-original raw (role:"source"); mirror
+        // it down like any clip but keep it OUT of the mined-clip count so clip_count
+        // stays consistent with the cloud/serve pipelines.
+        if (clip.role !== "source")
+            stored++;
     }
     const source = await clipRecords.getSource(ownerId, scan.source_video_id);
     if (source)