@mevdragon/vidfarm-devcli 0.18.1 → 0.19.0

package/dist/src/app.js

@@ -31,6 +31,8 @@ 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";
@@ -62,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";
@@ -71,12 +73,12 @@ import { DescribeExecutionCommand, SFNClient, StartExecutionCommand } from "@aws
 import { clipRecords, makeUserPreset } from "./services/clip-records.js";
 import { matchScenesToClips, searchUserClips, vectorIndex } from "./services/clip-search.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, extractThumbnail, hasFfmpeg, LocalAgentClipClient, normalizeCropFocus, normalizeHuntSpec, parseClipHuntPrompt, pickBestVideoMedia, probeVideo, resolveDurationBand, resolveTargetClipCount, scanVideo } from "./services/clip-curation/index.js";
-import { analyzeCastMembers, annotateScenesFromSource, buildSmartDecomposedHtml, HyperframesService, smartDecomposeVideo, stampCompositionIdentity } from "./services/hyperframes.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";
@@ -92,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";
@@ -1627,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`;
     }
@@ -2951,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,
@@ -2962,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) {
@@ -2996,6 +3048,7 @@ function attachmentToDirectoryItem(c, a) {
         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 }
     };
@@ -3035,10 +3088,160 @@ function clipSerializedToDirectoryItem(s) {
         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).
+ * that dispatches a canonical path to its backend (attachments / temp / raws /
+ * projects / approved).
  */
 async function listDirectoryFolder(c, customerId, root, folderPath) {
     const cur = normalizeFolderPath(folderPath);
@@ -3060,17 +3263,31 @@ async function listDirectoryFolder(c, customerId, root, folderPath) {
             .map((f) => temporaryFileToDirectoryItem(c, f));
         return { folders: childNames.map((n) => folderItem("temp", cur, n)), files };
     }
-    // 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 === "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" : "raws";
+    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() {
@@ -3259,7 +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? }. BILLS THE WALLET (RapidAPI) — unlike the BYOK images/generate and images/edit routes." },
+        { 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? }." },
@@ -3987,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
@@ -4039,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
@@ -4136,10 +4371,11 @@ function browseFilesTextContentType(fileName) {
 }
 function createBrowseFilesTool(input) {
     return tool({
-        description: "Browse AND write the user's file directory — a navigable tree with THREE 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), and /raws (the reusable clip/source-footage library, foldered by source). 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 three roots; path='/raws' 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` (a raw's id) and `path` (target folder, e.g. /raws/demos) reorganizes a raw between /raws folders. 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", "move"]).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."),
-            path: z.string().optional().describe("Canonical directory path to list or search: '/' for the three roots, '/raws' or '/files/brand-assets' for a folder. For move, the target folder (e.g. /raws/demos). Preferred over folder_path for cross-root navigation."),
+            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."),
@@ -4153,7 +4389,7 @@ function createBrowseFilesTool(input) {
             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, path, mode, folder_path, file_id, file_name, content, source_url, notes, query, content_type, offset, limit, 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);
@@ -4208,10 +4444,12 @@ function createBrowseFilesTool(input) {
                     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." };
-                    if (root !== "raws")
-                        return { action, explanation: explanation ?? null, status: 400, error: "move is currently supported only within /raws." };
-                    const url = new URL(`${RAWS_PREFIX}/${encodeURIComponent(id)}`, config.PUBLIC_BASE_URL);
+                        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, {
@@ -4223,6 +4461,24 @@ function createBrowseFilesTool(input) {
                     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) {
@@ -4584,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",
@@ -4608,9 +4864,12 @@ function createEditorActionTool() {
                 "nudge_layers",
                 "ripple_edit",
                 "set_layer_zindex",
-                "trim_layer"
-            ]).describe("Which mutation to perform. Use generate_layer to AI-generate a video/image and auto-place it on the timeline (fill a gap or replace a scene). Use export_composition to trigger the same Export button available in the editor UI — this queues an AWS Lambda render and the finished MP4 URL will surface in the next editor_context as last_export_url. 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."),
+                "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."),
@@ -4635,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."),
@@ -4757,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() }
                     : {})
             };
@@ -5165,6 +5438,11 @@ async function renderHyperframesStudioEditorPage(input) {
   ${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>`;
@@ -5311,7 +5589,14 @@ const reskinLibraryHandler = async (c, tab) => {
             email: customer.email,
             posts: [],
             schedule: { channels: [], connectHref: "/settings/channels?connect=flockposter" },
-            editorChat: null
+            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);
@@ -5323,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,
@@ -5466,9 +5756,17 @@ app.get("/chat-dock/boot", async (c) => {
         return c.json({ editorChat: null });
     return c.json({ 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) => {
+// 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));
@@ -5476,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) {
@@ -5604,7 +5923,7 @@ app.get("/reskin/discover/:mode", (c) => {
     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"));
@@ -5612,12 +5931,18 @@ 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));
+// 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 an
-// empty composition, and the client mints a real template_* + fork_* on the
-// first save/generate/decompose, then history.replaceState's the URL to the
-// canonical /editor/:templateId/fork/:forkId form.
-async function renderBlankEditorPage(c) {
+// 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));
@@ -5625,7 +5950,7 @@ async function renderBlankEditorPage(c) {
     }
     const threadParam = c.req.query("thread");
     const blankComposition = {
-        title: "Untitled project",
+        title: titleOverride?.trim() || "Untitled project",
         templateId: "original",
         slugId: "original",
         difficulty: "easy",
@@ -5643,6 +5968,26 @@ async function renderBlankEditorPage(c) {
     };
     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
@@ -5650,6 +5995,10 @@ async function renderBlankEditorPage(c) {
 // 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);
@@ -5797,6 +6146,13 @@ app.get("/editor/:templateId", async (c) => {
 });
 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);
@@ -5823,7 +6179,13 @@ app.get(`${ACCOUNT_FRONTEND_PREFIX}/chat`, (c) => dispatchScopedGetToLegacyRoute
 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"));
@@ -6138,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,
@@ -6246,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.
@@ -6763,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) {
@@ -7251,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)
@@ -7643,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");
     }
@@ -7658,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,
@@ -7712,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.
@@ -7777,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);
@@ -8277,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
@@ -8749,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,
@@ -8783,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
@@ -9171,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");
@@ -9372,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
@@ -10186,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)
@@ -10195,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);
     }
@@ -12006,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,
@@ -12013,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 });
@@ -13342,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,
@@ -15991,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":
@@ -16651,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" }));
@@ -16814,6 +17441,27 @@ app.delete(`${APPROVED_POSTS_PREFIX}/:postId`, requireAuth, async (c) => {
         return c.json({ error: error instanceof Error ? error.message : "Forbidden" }, 403);
     }
 });
+// 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(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)
@@ -17073,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,
@@ -17082,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
@@ -17097,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);
@@ -17116,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,
@@ -17124,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
@@ -17525,6 +18315,36 @@ app.get(`${USER_PREFIX}/me/directory`, async (c) => {
         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;
@@ -17641,6 +18461,24 @@ app.post(`${USER_PREFIX}/me/directory/search`, async (c) => {
                 }
             }
         }
+        // ── /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 });
@@ -17660,6 +18498,9 @@ app.post(`${USER_PREFIX}/me/directory/folders`, async (c) => {
         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 });
     }
@@ -17667,6 +18508,104 @@ app.post(`${USER_PREFIX}/me/directory/folders`, async (c) => {
         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);
@@ -18126,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>'
@@ -18403,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";
@@ -18613,11 +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).
@@ -18653,6 +19612,11 @@ app.post(`${RAWS_PREFIX}/scan`, async (c) => {
             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).
@@ -18750,6 +19714,7 @@ app.post(`${RAWS_PREFIX}/scan`, async (c) => {
                     sourceVideoId,
                     filename,
                     tracer,
+                    folderPath: folderOverride,
                     localSourcePath: importSourcePath && existsSync(importSourcePath) ? importSourcePath : null,
                     sourceUrl: huntSpec.source_url ?? null
                 });
@@ -19141,13 +20106,16 @@ async function importWholeVideoAsRaw(input) {
             taxonomy_version: ACTIVE_TAXONOMY_VERSION,
             tier: "flash-lite",
             tracer: input.tracer,
-            // Default into a source-derived Raws subfolder (canonical `/raws/<slug>`).
-            folder_path: normalizeFolderPath(String(displayName || "")
-                .toLowerCase()
-                .replace(/\.[a-z0-9]+$/i, "")
-                .replace(/[^a-z0-9]+/g, "-")
-                .replace(/^-+|-+$/g, "")
-                .slice(0, 60)),
+            // 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()
         };
@@ -19183,6 +20151,373 @@ async function importWholeVideoAsRaw(input) {
         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 →
 // per-scene tag/embed → finalize — with local ffmpeg and the resolved
@@ -19236,6 +20571,21 @@ async function runClipScanInProcess(input) {
             // 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`;
@@ -19259,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" });
     }
@@ -19358,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)