@mevdragon/vidfarm-devcli 0.19.0 → 0.20.0

package/dist/src/app.js

@@ -34,6 +34,7 @@ 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 { renderReskinPortfolio, DEFAULT_PORTFOLIO_SLUG } from "./reskin/portfolio-page.js";
 import { renderReskinPricing } from "./reskin/pricing-page.js";
 import { renderReskinLogin } from "./reskin/login-page.js";
 import { renderReskinHelp } from "./reskin/help-page.js";
@@ -62,6 +63,7 @@ import { ActiveJobLimitExceededError, JobsService } from "./services/jobs.js";
 import { ProviderLeaseTimeoutError, ProviderService } from "./services/providers.js";
 import { RateLimitExceededError, RateLimitService } from "./services/rate-limits.js";
 import { ServerlessProviderKeyService } from "./services/serverless-provider-keys.js";
+import { DEFAULT_ELEVENLABS_VOICE_ID, ELEVENLABS_VOICE_LIBRARY_URL } from "./services/elevenlabs.js";
 import { ServerlessTemplateConfigService } from "./services/serverless-template-configs.js";
 import { parseHTML } from "linkedom";
 import { joinStorageKey, storage as sharedStorage } from "./services/storage.js";
@@ -73,7 +75,7 @@ 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, extractClip, extractThumbnail, hasFfmpeg, LocalAgentClipClient, normalizeCropFocus, normalizeHuntSpec, parseClipHuntPrompt, pickBestVideoMedia, probeVideo, resolveDurationBand, resolveTargetClipCount, scanVideo } from "./services/clip-curation/index.js";
+import { applyHuntSpecDefaults, BUILTIN_PRESETS, buildClipEmbeddingText, buildEffectiveGuidance, ClipModelClient, cosineSimilarity, detectLocalAgent, effectiveHuntDurationSec, ACTIVE_TAXONOMY_VERSION, estimateScanCostFromDuration, extractAudioClip, extractClip, extractThumbnail, extractWaveformThumbnail, 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";
@@ -380,12 +382,12 @@ const agencyPromoteSchema = z.object({
     message: "Provide customer_id or email."
 });
 const providerKeySchema = z.object({
-    provider: z.enum(["openai", "gemini", "openrouter", "perplexity"]),
+    provider: z.enum(["openai", "gemini", "openrouter", "perplexity", "elevenlabs"]),
     label: z.string().optional(),
     secret: z.string().min(8)
 });
 const settingsProviderKeyFormSchema = z.object({
-    provider: z.enum(["openai", "gemini", "openrouter", "perplexity"]),
+    provider: z.enum(["openai", "gemini", "openrouter", "perplexity", "elevenlabs"]),
     label: z.string().trim().optional(),
     secret: z.string().min(8)
 });
@@ -3072,6 +3074,7 @@ function temporaryFileToDirectoryItem(c, f) {
 // Takes the OUTPUT of serializeClip (view/thumbnail URLs already resolved).
 function clipSerializedToDirectoryItem(s) {
     const folderPath = normalizeFolderPath(s.folder_path);
+    const isAudio = s.media_kind === "audio";
     const name = s.source_filename || s.description || "clip";
     const duration = s.duration_sec;
     return {
@@ -3081,11 +3084,14 @@ function clipSerializedToDirectoryItem(s) {
         name,
         kind: "file",
         id: s.clip_id,
-        contentType: "video/mp4",
+        // Audio-only raws (.m4a) must advertise an audio contentType so the editor's
+        // media picker (mediaKindFromRef) auto-places them as an AUDIO track rather
+        // than a <video> layer. The picker checks contentType before extension.
+        contentType: isAudio ? "audio/mp4" : "video/mp4",
         viewUrl: s.view_url || undefined,
         thumbUrl: s.thumbnail_url || undefined,
         durationSec: typeof duration === "number" ? duration : undefined,
-        meta: { description: s.description, tags: s.tags, created_at: s.created_at, source_video_id: s.source_video_id }
+        meta: { description: s.description, tags: s.tags, created_at: s.created_at, source_video_id: s.source_video_id, media_kind: s.media_kind }
     };
 }
 // An approved ready-post as a canonical directory file. view/thumb come from the
@@ -3497,8 +3503,10 @@ function buildPrimitiveEditorDocsRoutes() {
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/probe`, summary: "Primitive audio probe job. Body must be { tracer, payload: { source_audio_url }, webhook_url? }. Returns durable JSON metadata." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/concat`, summary: "Primitive audio concat job. Body must be { tracer, payload: { source_audio_urls, output_format?, audio_bitrate_kbps? }, webhook_url? }." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/normalize`, summary: "Primitive audio normalization job. Body must be { tracer, payload: { source_audio_url, output_format?, audio_bitrate_kbps?, sample_rate_hz? }, webhook_url? }." },
-        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/speech`, summary: "Primitive text-to-speech (TTS) job using saved OpenAI, Gemini, or OpenRouter provider keys. Body must be { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? }, webhook_url? }. instructions is a free-form voice-style prompt (tone, pacing, accent, emotion, persona — e.g. \"calm, warm bedtime narrator with a slight British accent\"). voice is a provider preset (OpenAI: alloy/ash/coral/…; Gemini: Kore/Puck/Charon/…); provider is inferred from the voice when omitted, and a voice paired with the wrong provider is rejected with a 400. Returns a durable platform audio URL (mp3 or wav). Alias: POST /api/v1/primitives/tts." },
-        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/transcribe`, summary: "Primitive speech-to-text (STT) job using saved provider keys. Accepts VIDEO or AUDIO sources; video audio is demuxed automatically. Body must be { tracer, payload: { source_url (aliases: source_video_url, source_audio_url, url), diarize?, language?, prompt?, provider?, model? }, webhook_url? }. Returns TWO formats in one job: a simple subtitle transcript (plain text + timed SRT cues, no speakers) and an advanced multi-speaker version (speaker-attributed timed segments for multi-narration), plus transcript.json/.srt/.txt artifacts. diarize defaults to true; speaker attribution needs a Gemini key (openai/openrouter degrade to a plain single-speaker transcript). Sources over ~40 minutes of speech must be trimmed first. Alias: POST /api/v1/primitives/stt. Pass word_timestamps: true for word-level timings on each segment (real timestamps on an OpenAI key via whisper-1; other providers stay segment-level)." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/speech`, summary: "Primitive text-to-speech (TTS). Body must be { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format?, use_wallet_credits? }, webhook_url? }. use_wallet_credits DEFAULTS TRUE → best-quality ElevenLabs narration on the platform key, billed to the wallet; set false to use your own saved ElevenLabs key or a BYOK OpenAI/Gemini/OpenRouter key instead. voice on the ElevenLabs path is a voice_id (or friendly name george/sarah/…); browse voices via GET /api/v1/primitives/audio/voices and pass the chosen voice_id. On the BYOK path voice is a provider preset (OpenAI: alloy/ash/…; Gemini: Kore/Puck/…). instructions is a free-form voice-style prompt (tone/pacing/accent/emotion). Returns a durable platform audio URL. Alias: POST /api/v1/primitives/tts." },
+        { method: "GET", path: `${PRIMITIVES_PREFIX}/audio/voices`, summary: "List ElevenLabs voices for TTS. Query use_wallet_credits (default true) lists the platform account's voices; use_wallet_credits=false lists the voices on the customer's own saved ElevenLabs key. Returns { scope, default_voice_id, voice_library_url, voices: [{ voice_id, name, category, labels, description, preview_url }] }. Pick a voice_id and pass it as `voice` to /audio/speech. Browse more at the returned voice_library_url." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/music/generate`, summary: "Primitive MUSIC generation (ElevenLabs): instrumental tracks, songs with lyrics, background beds, jingles. Body must be { tracer, payload: { prompt, music_length_ms? (default 30000, max 300000 = 5 min), composition_plan? (ElevenLabs plan for section-by-section control), model?, use_wallet_credits? }, webhook_url? }. use_wallet_credits DEFAULTS TRUE → platform ElevenLabs key billed to the wallet; set false to use your own saved ElevenLabs key. Returns a durable platform audio URL (mp3). Alias: POST /api/v1/primitives/music." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/transcribe`, summary: "Primitive speech-to-text (STT). Accepts VIDEO or AUDIO sources; video audio is demuxed automatically. Body must be { tracer, payload: { source_url (aliases: source_video_url, source_audio_url, url), diarize?, word_timestamps?, language?, prompt?, provider?, model?, use_wallet_credits? }, webhook_url? }. use_wallet_credits DEFAULTS TRUE → ElevenLabs Scribe on the platform key (native diarization + real word timestamps), billed to the wallet; set false to use your own ElevenLabs key or a BYOK gemini/openai/openrouter key (gemini labels speakers, openai/whisper-1 gives real word timings). Returns TWO formats in one job: a simple subtitle transcript (plain text + timed SRT) and speaker-attributed timed segments, plus transcript.json/.srt/.txt. Sources over ~40 minutes must be trimmed first. Alias: POST /api/v1/primitives/stt." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/captions`, summary: "ANIMATED CAPTIONS from speech: one job transcribes narration WITH word-level timings and pages it into word-by-word caption cues ready for the editor's set_captions action. Body must be { tracer, payload: { source_url (video or audio; video audio is demuxed) OR text (page a script instead of transcribing), style? (spotlight|karaoke|word-pop|stack-up|neon|bounce), animation?, active_color?, highlight_color?, uppercase?, color?, background?, background_style?, font_family?, font_size?, max_words_per_cue?, offset_sec?, language?, provider?, window_start?/window_duration? (text mode) }, webhook_url? }. The finished job's result carries captions (the cue array) and set_captions_action (fully-formed editor_action arguments — apply verbatim). Real word timestamps need an OpenAI key (whisper-1, tried first); gemini/openrouter fall back to estimated word windows. Alias: POST /api/v1/primitives/captions." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/regenerate-speech`, summary: "REGENERATE SPEECH IN THE ORIGINAL SPEAKER'S VOICE (approximate match, not a clone): one job listens to a video/audio source, profiles the speaker's voice (needs a saved Gemini key; other keys degrade to transcript-only with no voice match), rewords the transcript per your instruction (or takes an exact replacement script), and returns new TTS audio using the closest preset voice + a style prompt matched to the speaker. Body must be { tracer, payload: { source_url (video or audio; video audio is demuxed; aliases source_video_url/source_audio_url/url), rewrite_instruction? (how to reword, e.g. \"mention the summer sale instead of the discount code\") OR text? (exact new script — one of the two is required), voice? (explicit preset override), instructions? (extra style guidance), provider?, model?, language?, output_format? }, webhook_url? }. Result carries audioUrl (durable, place with add_layer), script, original_transcript, voice_profile, and voice_match: \"approximate\"|\"none\" — OpenAI/Gemini APIs cannot clone voice identity, so always tell the user the voice is a matched approximation. Alias: POST /api/v1/primitives/regenerate-speech." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/brainstorm/coldstart`, summary: "Primitive cold-start strategy questionnaire. Body should usually be { tracer, payload: { user_message }, webhook_url? }. user_message can be rough, like \"I don't know where to start\" or a messy description. count is optional only when the user explicitly wants more or fewer questions. offer_description remains accepted as a backward-compatible alias." },
@@ -3639,7 +3647,10 @@ async function normalizeEditorChatProviderRows(customerId) {
         secret: readStoredSecret(String(entry.secret))
     }))
         .filter((entry) => entry.status === "active")
-        .filter((entry) => entry.secret.trim().length > 0);
+        .filter((entry) => entry.secret.trim().length > 0)
+        // ElevenLabs is an audio-only key — never a qualified text/image/video
+        // provider, so it must not surface as an editor-chat / media provider.
+        .filter((entry) => entry.provider !== "elevenlabs");
 }
 async function chooseEditorChatProvider(customerId, preferredProvider) {
     const rows = await normalizeEditorChatProviderRows(customerId);
@@ -3727,6 +3738,9 @@ function createEditorChatModel(input) {
                 apiKey: input.apiKey,
                 baseURL: "https://api.perplexity.ai"
             }).chatModel(input.model);
+        default:
+            // Audio-only providers (elevenlabs) are never editor-chat models.
+            throw new Error(`Editor chat does not support the ${input.provider} provider.`);
     }
 }
 function buildMockEditorChatText(input) {
@@ -4107,7 +4121,7 @@ function normalizeOperationRequestTracer(tracer) {
 }
 function createTemplateHttpTool(input) {
     return tool({
-        description: "Call exactly one Vidfarm REST API route and inspect the response before deciding the next call. Use template routes for metadata, skill, config, operations, jobs, logs, and cancel routes. Use primitive routes under /api/v1/primitives for reusable image generation, image editing, inpainting, still rendering, social/media video download, AI video generation, video slide rendering, burned-in caption removal, video trim/extract/probe/mute/concat operations, audio trim/probe/concat/normalize operations, text-to-speech narration (audio/speech) and speech-to-text transcription (audio/transcribe) routes, brainstorm strategy routes, and primitive job inspection; these primitive routes are allowed directly from editor chat even when they are not specific to the current template. Primitive POST bodies must use { tracer, payload: { ...primitive fields... }, webhook_url? }; do not put prompt, source_image_url, instruction, slides, html, or other primitive fields at the top level. Never say primitive image generation, image edit, inpaint, HTML render, video download, AI video generation, caption removal, trim, probe, extract-audio, concat, mute, video render, text-to-speech, speech transcription, or brainstorm routes are unavailable here when the route exists. If the user asks to generate a new image similar to an attachment, call POST /api/v1/primitives/images/generate with body { tracer, payload: { prompt, prompt_attachments: [exact attachment URL] } }. If the user asks to revise the attached image itself, call POST /api/v1/primitives/images/edit with body { tracer, payload: { source_image_url, instruction } }. If the user asks to download a social/media post into a durable MP4, call POST /api/v1/primitives/videos/download with body { tracer, payload: { source_url|video_url|url, quality?: \"best\"|\"hd\"|\"full_hd\" } }. If the user asks to generate a new AI video, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, provider?: \"openai\"|\"gemini\"|\"openrouter\", duration?: seconds, input_references?: [direct image asset URL], frame_images?: [{ image_url, frame_type }] } }; never send webpage or social post URLs in input_references. duration is seconds, not milliseconds, and duration_ms belongs only to /videos/render-slides slides. Default video models are openai/sora-2, gemini/veo-3.0-generate-001, and openrouter/bytedance/seedance-2.0. Use POST /api/v1/primitives/videos/render-slides only to assemble existing media URLs into an MP4 slideshow. Use POST /api/v1/primitives/media/dedupe to apply subtle dedupe transforms (zoom/tilt/rotate/saturation/speed/horizontal_flip/contrast/brightness/hue_rotate/blur/tint) to any image or video URL, with body { tracer, payload: { source_media_url, media_type?, effects?, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Use POST /api/v1/primitives/videos/trim for clipping, /videos/extract-audio for demuxing, /videos/probe or /audio/probe for metadata-only JSON outputs, /videos/extract-frame for stills, /videos/mute to remove audio, /videos/replace-audio to swap tracks, /videos/concat for sequential muted MP4 joins, /audio/trim for clipped audio, /audio/concat for stitched audio, and /audio/normalize for leveled/re-encoded audio. If the user asks for AI voiceover, narration, or dub audio from text (a script, hook, or caption read aloud), call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions? } } — instructions is a free-form voice-style prompt like \"excited sports announcer, fast paced\" and the job returns a durable audio URL you can place with add_layer. If the user asks to transcribe a video or audio, get subtitles/captions from speech, or identify who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language? } } — it accepts video or audio URLs (video audio is demuxed automatically) and one job returns BOTH a simple subtitle transcript (plain text + timed SRT cues) and an advanced multi-speaker version (speaker-attributed timed segments for multi-narration); speaker attribution needs a Gemini key, and word_timestamps: true adds word-level timings per segment (real on an OpenAI key via whisper-1). If the user wants ANIMATED word-by-word captions generated from narration, call POST /api/v1/primitives/audio/captions with body { tracer, payload: { source_url (narration audio or video URL) OR text (a script to page), style?: \"spotlight\"|\"karaoke\"|\"word-pop\"|\"stack-up\"|\"neon\"|\"bounce\", max_words_per_cue?, offset_sec?, language?, provider? } } — the finished job's result carries captions (the cue array) and set_captions_action (fully-formed editor_action arguments); apply them with the editor_action tool (action_type=set_captions) so the change flows through the editor state. Real word timestamps need an OpenAI key (whisper-1, tried first); gemini/openrouter estimate word windows. If the user wants the SAME speaker to say DIFFERENT words — reword, revoice, redub, or regenerate existing narration so it sounds like the original voice — call POST /api/v1/primitives/audio/regenerate-speech with body { tracer, payload: { source_url (video or audio; video audio is demuxed), rewrite_instruction (how to reword the original transcript) OR text (the exact new script), voice?, instructions?, provider?, language?, output_format? } } — the job listens to the source, profiles the speaker's voice (needs a saved Gemini key; other keys degrade to transcript-only with no voice match), rewords the script, and returns a durable audio URL spoken by the closest PRESET voice with a style prompt matched to the speaker. OpenAI/Gemini APIs cannot clone voice identity, so always present regenerate-speech output as an approximation of the original voice, never a clone; place the finished audio with editor_action add_layer, typically after muting the original span with /videos/mute or swapping tracks with /videos/replace-audio. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. Caption removal is capped at ~15 minutes of source and must NEVER be used on long-form video: when the user wants short clips out of a long video (a podcast, stream VOD, webinar, or any YouTube/TikTok/IG/X URL), call POST /clips/scan instead with body { source_url | temp_file_id | s3_key, prompt, ranges?: [\"MM:SS-MM:SS\"], target_duration_sec?, aspect?: \"9:16\"|\"16:9\"|\"4:3\"|\"1:1\", avoid_text?, provider?: \"gemini\"|\"openai\"|\"openrouter\", tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver on long videos), aspect crops every clip, and avoid_text prefers scenes WITHOUT on-screen text via scene SELECTION (never caption removal on the source). The hunt is async: it returns scan_id immediately; poll GET /clips/scan/:scanId, then browse results via GET /clips/feed?source=<source_video_id> or POST /clips/search. Hunts bill AWS compute only — the AI tagging runs on the user's own saved provider keys (auto-picked gemini → openai → openrouter unless body.provider names one). To remove captions from a finished HUNTED clip, pass that clip's short mp4 to /videos/remove-captions afterwards. If the user explicitly asks for hooks, angles, awareness-stage advice, or a cold-start strategy questionnaire, call the matching brainstorm route immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart when the customer is starting from zero, /brainstorm/awareness_stages when they do not know what ad types to make, /brainstorm/angles when they want persuasive angles, and /brainstorm/hooks when they want many openings. Product placement is a first-class brainstorm primitive like angles and hooks: when the user wants to identify product-placement opportunities in a video or repurpose a video into a native ad for their product, call POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? } — it watches the video and returns timestamped native placement opportunities and prefers a Gemini key. You may also analyze an attached video directly to answer product-placement questions conversationally instead of the primitive when the user just wants a quick take. For brainstorm routes, do not send count by default; only include count when the user explicitly asks for a specific number of hooks, angles, questions, or opportunities. When brainstorm jobs finish and the response includes a JSON artifact, tell the user to open and review that JSON in the chat UI because it contains the structured output. When the user asks for content ideas or says they do not know where to start, prefer the sequence coldstart -> awareness_stages -> angles -> hooks, then use the output to choose templates. For template operation POST bodies, use top-level template_preview_media=\"auto\" by default, \"include\" when the user wants the template to use catalog preview media as references where supported, and \"exclude\" when the user asks not to use preview media as references. Templates decide which generation steps honor that policy. If a POST returns a queued job, do not poll it in this same response; continue with any remaining requested POST calls, then summarize the queued job ids and tracers. If you know a job_id but not the template or primitive, use GET /api/v1/user/me/jobs/:jobId or its /logs and /artifacts subroutes instead of paging through job lists. Use GET /api/v1/compositions/:forkId/remove-video-captions to look up both the original source video URL and the subtitle-removed mirrored URL for the current fork before feeding a video URL into a primitive route; this is a read-only, non-billing status check — never confuse it with POST /remove-video-captions-poll (which advances the fork's decompose-time subtitle-removal job and can bill). Use POST /api/v1/approved/posts with title, caption, pinned_comment, media URLs, and tracer to approve a finished output into a preview/share page. Use POST /api/v1/approved/posts/:postId/schedules with destination_type, destination_id, scheduled_at, timezone, and optional settings/additional_notes to schedule an approved post. When a rendered video was built from slideshow frame images, include both versions in one media array: final MP4 first with kind=\"video\" and role=\"primary\", then every finished captioned slide frame image in order with kind=\"image\" and role=\"slide\". Prefer create-slideshow result.renderVideoInput.slides[].imageUrl or result.slides[].frameImageUrl for carousel media; do not use backgroundImageUrl, manifests, thumbnails, or a partial files array as the full slide set. If the user supplies exact media file URLs for approval, use those URLs as the backup source of truth, preserve their order, infer kind when needed, and assign primary/video and slide/image roles correctly. If the user asks for N distinct generated outputs, make N sequential POST calls rather than one combined POST and do not stop after the first queued job.",
+        description: "Call exactly one Vidfarm REST API route and inspect the response before deciding the next call. Use template routes for metadata, skill, config, operations, jobs, logs, and cancel routes. Use primitive routes under /api/v1/primitives for reusable image generation, image editing, inpainting, still rendering, social/media video download, AI video generation, video slide rendering, burned-in caption removal, video trim/extract/probe/mute/concat operations, audio trim/probe/concat/normalize operations, text-to-speech narration (audio/speech), music generation (music/generate), voice listing (audio/voices), and speech-to-text transcription (audio/transcribe) routes, brainstorm strategy routes, and primitive job inspection; these primitive routes are allowed directly from editor chat even when they are not specific to the current template. Primitive POST bodies must use { tracer, payload: { ...primitive fields... }, webhook_url? }; do not put prompt, source_image_url, instruction, slides, html, or other primitive fields at the top level. Never say primitive image generation, image edit, inpaint, HTML render, video download, AI video generation, caption removal, trim, probe, extract-audio, concat, mute, video render, text-to-speech, speech transcription, or brainstorm routes are unavailable here when the route exists. If the user asks to generate a new image similar to an attachment, call POST /api/v1/primitives/images/generate with body { tracer, payload: { prompt, prompt_attachments: [exact attachment URL] } }. If the user asks to revise the attached image itself, call POST /api/v1/primitives/images/edit with body { tracer, payload: { source_image_url, instruction } }. If the user asks to download a social/media post into a durable MP4, call POST /api/v1/primitives/videos/download with body { tracer, payload: { source_url|video_url|url, quality?: \"best\"|\"hd\"|\"full_hd\" } }. If the user asks to generate a new AI video, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, provider?: \"openai\"|\"gemini\"|\"openrouter\", duration?: seconds, input_references?: [direct image asset URL], frame_images?: [{ image_url, frame_type }] } }; never send webpage or social post URLs in input_references. duration is seconds, not milliseconds, and duration_ms belongs only to /videos/render-slides slides. Default video models are openai/sora-2, gemini/veo-3.0-generate-001, and openrouter/bytedance/seedance-2.0. Use POST /api/v1/primitives/videos/render-slides only to assemble existing media URLs into an MP4 slideshow. Use POST /api/v1/primitives/media/dedupe to apply subtle dedupe transforms (zoom/tilt/rotate/saturation/speed/horizontal_flip/contrast/brightness/hue_rotate/blur/tint) to any image or video URL, with body { tracer, payload: { source_media_url, media_type?, effects?, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Use POST /api/v1/primitives/videos/trim for clipping, /videos/extract-audio for demuxing, /videos/probe or /audio/probe for metadata-only JSON outputs, /videos/extract-frame for stills, /videos/mute to remove audio, /videos/replace-audio to swap tracks, /videos/concat for sequential muted MP4 joins, /audio/trim for clipped audio, /audio/concat for stitched audio, and /audio/normalize for leveled/re-encoded audio. If the user asks for AI voiceover, narration, or dub audio from text (a script, hook, or caption read aloud), call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions?, use_wallet_credits? } } — use_wallet_credits DEFAULTS TRUE, which routes to high-quality ElevenLabs on the platform key billed to the user's wallet; keep it true by default and only set it false to use the user's own ElevenLabs key or a BYOK OpenAI/Gemini/OpenRouter key (to save wallet credits). Default to a sensible voice and TELL the user they can pick from many ElevenLabs voices — call GET /api/v1/primitives/audio/voices (add ?use_wallet_credits=false to list voices on their own ElevenLabs key) to list voice_id + name + preview_url, then pass the chosen voice_id as `voice`. instructions is a free-form voice-style prompt like \"excited sports announcer, fast paced\" and the job returns a durable audio URL you can place with add_layer. If the user asks for MUSIC — a background track, beat, jingle, song, or score — call POST /api/v1/primitives/music/generate with body { tracer, payload: { prompt, music_length_ms?, use_wallet_credits? } } (use_wallet_credits DEFAULTS TRUE = platform ElevenLabs billed to the wallet; false = the user's own ElevenLabs key). music_length_ms defaults 30000 and caps at 300000 (5 min); the job returns a durable mp3 you place as its own <audio> layer (keep music ~0.1–0.2 volume under narration). If the user asks to transcribe a video or audio, get subtitles/captions from speech, or identify who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language? } } — it accepts video or audio URLs (video audio is demuxed automatically) and one job returns BOTH a simple subtitle transcript (plain text + timed SRT cues) and an advanced multi-speaker version (speaker-attributed timed segments for multi-narration); speaker attribution needs a Gemini key, and word_timestamps: true adds word-level timings per segment (real on an OpenAI key via whisper-1). If the user wants ANIMATED word-by-word captions generated from narration, call POST /api/v1/primitives/audio/captions with body { tracer, payload: { source_url (narration audio or video URL) OR text (a script to page), style?: \"spotlight\"|\"karaoke\"|\"word-pop\"|\"stack-up\"|\"neon\"|\"bounce\", max_words_per_cue?, offset_sec?, language?, provider? } } — the finished job's result carries captions (the cue array) and set_captions_action (fully-formed editor_action arguments); apply them with the editor_action tool (action_type=set_captions) so the change flows through the editor state. Real word timestamps need an OpenAI key (whisper-1, tried first); gemini/openrouter estimate word windows. If the user wants the SAME speaker to say DIFFERENT words — reword, revoice, redub, or regenerate existing narration so it sounds like the original voice — call POST /api/v1/primitives/audio/regenerate-speech with body { tracer, payload: { source_url (video or audio; video audio is demuxed), rewrite_instruction (how to reword the original transcript) OR text (the exact new script), voice?, instructions?, provider?, language?, output_format? } } — the job listens to the source, profiles the speaker's voice (needs a saved Gemini key; other keys degrade to transcript-only with no voice match), rewords the script, and returns a durable audio URL spoken by the closest PRESET voice with a style prompt matched to the speaker. OpenAI/Gemini APIs cannot clone voice identity, so always present regenerate-speech output as an approximation of the original voice, never a clone; place the finished audio with editor_action add_layer, typically after muting the original span with /videos/mute or swapping tracks with /videos/replace-audio. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. Caption removal is capped at ~15 minutes of source and must NEVER be used on long-form video: when the user wants short clips out of a long video (a podcast, stream VOD, webinar, or any YouTube/TikTok/IG/X URL), call POST /clips/scan instead with body { source_url | temp_file_id | s3_key, prompt, ranges?: [\"MM:SS-MM:SS\"], target_duration_sec?, aspect?: \"9:16\"|\"16:9\"|\"4:3\"|\"1:1\", avoid_text?, provider?: \"gemini\"|\"openai\"|\"openrouter\", tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver on long videos), aspect crops every clip, and avoid_text prefers scenes WITHOUT on-screen text via scene SELECTION (never caption removal on the source). The hunt is async: it returns scan_id immediately; poll GET /clips/scan/:scanId, then browse results via GET /clips/feed?source=<source_video_id> or POST /clips/search. Hunts bill AWS compute only — the AI tagging runs on the user's own saved provider keys (auto-picked gemini → openai → openrouter unless body.provider names one). To remove captions from a finished HUNTED clip, pass that clip's short mp4 to /videos/remove-captions afterwards. If the user explicitly asks for hooks, angles, awareness-stage advice, or a cold-start strategy questionnaire, call the matching brainstorm route immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart when the customer is starting from zero, /brainstorm/awareness_stages when they do not know what ad types to make, /brainstorm/angles when they want persuasive angles, and /brainstorm/hooks when they want many openings. Product placement is a first-class brainstorm primitive like angles and hooks: when the user wants to identify product-placement opportunities in a video or repurpose a video into a native ad for their product, call POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? } — it watches the video and returns timestamped native placement opportunities and prefers a Gemini key. You may also analyze an attached video directly to answer product-placement questions conversationally instead of the primitive when the user just wants a quick take. For brainstorm routes, do not send count by default; only include count when the user explicitly asks for a specific number of hooks, angles, questions, or opportunities. When brainstorm jobs finish and the response includes a JSON artifact, tell the user to open and review that JSON in the chat UI because it contains the structured output. When the user asks for content ideas or says they do not know where to start, prefer the sequence coldstart -> awareness_stages -> angles -> hooks, then use the output to choose templates. For template operation POST bodies, use top-level template_preview_media=\"auto\" by default, \"include\" when the user wants the template to use catalog preview media as references where supported, and \"exclude\" when the user asks not to use preview media as references. Templates decide which generation steps honor that policy. If a POST returns a queued job, do not poll it in this same response; continue with any remaining requested POST calls, then summarize the queued job ids and tracers. If you know a job_id but not the template or primitive, use GET /api/v1/user/me/jobs/:jobId or its /logs and /artifacts subroutes instead of paging through job lists. Use GET /api/v1/compositions/:forkId/remove-video-captions to look up both the original source video URL and the subtitle-removed mirrored URL for the current fork before feeding a video URL into a primitive route; this is a read-only, non-billing status check — never confuse it with POST /remove-video-captions-poll (which advances the fork's decompose-time subtitle-removal job and can bill). Use POST /api/v1/approved/posts with title, caption, pinned_comment, media URLs, and tracer to approve a finished output into a preview/share page. Use POST /api/v1/approved/posts/:postId/schedules with destination_type, destination_id, scheduled_at, timezone, and optional settings/additional_notes to schedule an approved post. When a rendered video was built from slideshow frame images, include both versions in one media array: final MP4 first with kind=\"video\" and role=\"primary\", then every finished captioned slide frame image in order with kind=\"image\" and role=\"slide\". Prefer create-slideshow result.renderVideoInput.slides[].imageUrl or result.slides[].frameImageUrl for carousel media; do not use backgroundImageUrl, manifests, thumbnails, or a partial files array as the full slide set. If the user supplies exact media file URLs for approval, use those URLs as the backup source of truth, preserve their order, infer kind when needed, and assign primary/video and slide/image roles correctly. If the user asks for N distinct generated outputs, make N sequential POST calls rather than one combined POST and do not stop after the first queued job.",
         inputSchema: z.object({
             method: z.enum(["GET", "POST"]).describe("HTTP method to use."),
             path: z.string().min(1).describe("Absolute path or same-origin URL for an allowed Vidfarm REST route."),
@@ -5838,6 +5852,19 @@ app.get("/pricing", async (c) => {
     const customer = await getOptionalPreferredBrowserCustomer(c);
     return c.html(renderReskinPricing({ email: customer?.email ?? "" }));
 });
+// /portfolio/:slug — public creator/agency showcase (hardcoded data, no auth).
+app.get("/portfolio", (c) => redirect(c, `/portfolio/${DEFAULT_PORTFOLIO_SLUG}`));
+app.get("/portfolio/:slug", async (c) => {
+    const customer = await getOptionalPreferredBrowserCustomer(c);
+    const html = renderReskinPortfolio(c.req.param("slug"), {
+        isLoggedIn: Boolean(customer),
+        name: customer?.name ?? null,
+        email: customer?.email ?? null
+    });
+    if (!html)
+        return c.notFound();
+    return c.html(html);
+});
 app.get("/login", (c) => c.html(renderReskinLogin({ mode: getLoginMode(c.req.query("mode")), routePrefix: "/login" })));
 app.post("/login/password", async (c) => {
     const mode = getLoginMode(c.req.query("mode"));
@@ -9379,6 +9406,40 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
             reason: "manual",
             message: `Smart-decomposed via ${smart.provider}(${smart.model}): ${smart.scenes.length} scene(s), ${smart.captions.length} caption(s)${ghostcutTaskId ? ` + GhostCut task ${ghostcutTaskId} pending` : ""}`
         });
+        // Race-closer: the GhostCut subtitle-removal poll (fast) may have already
+        // finished and mirrored the cleaned video while this (slow) vision analysis
+        // was running — in which case it parked ghostcut.json in
+        // "awaiting_composition" because smart-decompose.json didn't exist yet. Now
+        // that BOTH composition.html and smart-decompose.json are written, apply the
+        // rebuild here so the composition points at the subtitle-removed video even
+        // if the client never polls again. Also self-heals any "done"-without-swap
+        // fork left by the pre-fix code path. Non-fatal.
+        if (ghostcutTaskId !== null) {
+            try {
+                const gcText = await storage.readText(storage.compositionForkWorkingKey(fork.id, "ghostcut.json"));
+                if (gcText) {
+                    const gc = JSON.parse(gcText);
+                    if (gc.mirroredUrl && (gc.status === "awaiting_composition" || gc.status === "done")) {
+                        const currentHtml = await storage.readText(storage.compositionForkWorkingKey(fork.id, "composition.html"));
+                        const alreadyClean = currentHtml ? currentHtml.includes(gc.mirroredUrl) : false;
+                        if (!alreadyClean) {
+                            const swapApplied = await rebuildDecomposedCompositionAgainstCleanVideo({
+                                fork,
+                                callerCustomerId: caller.id,
+                                cleanedSourceUrl: gc.mirroredUrl,
+                                snapshotMessage: `GhostCut task ${gc.taskId} completed — subtitles removed, composition rebuilt against cleaned video`
+                            });
+                            if (swapApplied && gc.status !== "done") {
+                                await storage.putJson(storage.compositionForkWorkingKey(fork.id, "ghostcut.json"), { ...gc, status: "done", completedAtMs: gc.completedAtMs ?? Date.now() });
+                            }
+                        }
+                    }
+                }
+            }
+            catch (finalizeError) {
+                console.error("auto-decompose ghostcut finalize failed", finalizeError instanceof Error ? finalizeError.message : finalizeError);
+            }
+        }
         // First successful decompose for this template becomes everyone's default.
         // Later users get seeded from this fork's composition html. Enforced at the
         // storage layer via a conditional write so the first decompose wins even
@@ -9589,6 +9650,68 @@ app.get(`${COMPOSITIONS_PREFIX}/:forkId/video-context.json`, async (c) => {
         return c.json({ ok: false, error: error instanceof Error ? error.message : String(error) }, 500);
     }
 });
+// Rebuild a decomposed fork's composition.html DETERMINISTICALLY from the
+// persisted smart-decompose.json snapshot, substituting `cleanedSourceUrl` (the
+// GhostCut-mirrored, subtitle-removed video) as the source for every media
+// layer. Shared by BOTH the async GhostCut poll AND the synchronous tail of
+// /auto-decompose. Rationale: GhostCut removal (fast, ~30-90s) routinely
+// finishes BEFORE the vision analysis (slow, minutes) has written
+// smart-decompose.json, so whichever side "wins" the race must be able to apply
+// the swap. Returns true iff composition.html was rewritten against the clean
+// video; false when the snapshot is missing/unparseable/empty (the caller keeps
+// the original in place and retries later).
+async function rebuildDecomposedCompositionAgainstCleanVideo(input) {
+    const { fork, callerCustomerId, cleanedSourceUrl, snapshotMessage } = input;
+    const persistedText = await storage.readText(storage.compositionForkWorkingKey(fork.id, "smart-decompose.json"));
+    if (!persistedText) {
+        console.error(`ghostcut-rebuild: smart-decompose.json missing for fork ${fork.id}; composition NOT rebuilt (still references original video)`);
+        return false;
+    }
+    let persisted;
+    try {
+        persisted = JSON.parse(persistedText);
+    }
+    catch (parseError) {
+        console.error("ghostcut-rebuild: smart-decompose.json parse failed", parseError instanceof Error ? parseError.message : parseError);
+        return false;
+    }
+    if (!persisted.result || !Array.isArray(persisted.result.scenes) || persisted.result.scenes.length === 0) {
+        console.error(`ghostcut-rebuild: smart-decompose.json for fork ${fork.id} has no scenes; skipping rebuild`);
+        return false;
+    }
+    const rebuilt = buildSmartDecomposedHtml({
+        compositionId: persisted.compositionId ?? fork.id,
+        sourceUrl: cleanedSourceUrl,
+        title: persisted.title ?? fork.title ?? fork.id,
+        result: {
+            summary: persisted.result.summary ?? "",
+            viralDna: persisted.result.viralDna ?? {
+                trend_tagline: "", hook: "", retention: "", payoff: "",
+                preserve: [], avoid: [], promotions: [], keywords: []
+            },
+            transcript: persisted.result.transcript ?? null,
+            durationSeconds: Number(persisted.result.durationSeconds ?? 0),
+            width: Number(persisted.result.width ?? 720),
+            height: Number(persisted.result.height ?? 1280),
+            scenes: persisted.result.scenes,
+            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: [],
+            // Editor harness round-trips from the snapshot so the rebuilt HTML keeps
+            // its data-editor-harness; default if a pre-harness snapshot is rebuilt.
+            editorHarness: persisted.result.editorHarness ?? DEFAULT_EDITOR_HARNESS
+        }
+    });
+    await storage.putText(storage.compositionForkWorkingKey(fork.id, "composition.html"), rebuilt, "text/html; charset=utf-8");
+    await snapshotForkVersion({
+        fork,
+        callerCustomerId,
+        reason: "manual",
+        message: snapshotMessage
+    });
+    return true;
+}
 // Idempotent status probe for the async GhostCut subtitle-removal task kicked
 // off by /auto-decompose. The client polls this every few seconds after a
 // successful decompose. On this endpoint's side:
@@ -9637,6 +9760,41 @@ const pollForkSubtitleRemoval = async (c) => {
                 completed_at_ms: state.completedAtMs ?? null
             });
         }
+        // "awaiting_composition": GhostCut already finished and the cleaned video is
+        // mirrored; we're only waiting for smart-decompose.json to exist so we can
+        // rebuild. Do NOT re-poll GhostCut and do NOT re-bill — just retry the
+        // rebuild. Flips to terminal "done" the moment the snapshot is available.
+        if (state.status === "awaiting_composition" && state.mirroredUrl) {
+            const swapApplied = await rebuildDecomposedCompositionAgainstCleanVideo({
+                fork,
+                callerCustomerId: caller.id,
+                cleanedSourceUrl: state.mirroredUrl,
+                snapshotMessage: `GhostCut task ${state.taskId} completed — subtitles removed, composition rebuilt against cleaned video`
+            });
+            if (swapApplied) {
+                const next = {
+                    ...state,
+                    status: "done",
+                    completedAtMs: state.completedAtMs ?? Date.now()
+                };
+                await storage.putJson(stateKey, next);
+                return c.json({
+                    ok: true,
+                    status: "done",
+                    task_id: state.taskId,
+                    mirrored_url: state.mirroredUrl,
+                    completed_at_ms: next.completedAtMs,
+                    swap_applied: true
+                });
+            }
+            // Snapshot still not written — keep the client polling.
+            return c.json({
+                ok: true,
+                status: "pending",
+                task_id: state.taskId,
+                mirrored_url: state.mirroredUrl
+            });
+        }
         // Poll GhostCut once. We deliberately do only ONE HTTP call per invocation
         // so the client controls cadence and lambda time is bounded.
         const status = await pollGhostcutStatus(state.taskId);
@@ -9699,75 +9857,11 @@ const pollForkSubtitleRemoval = async (c) => {
             if (!finalMirroredUrl) {
                 throw new Error(`ghostcut mirror key not in a public prefix: ${mirrored.key}`);
             }
-            // REBUILD (not swap) the composition from the deterministic smart-decompose
-            // JSON we persisted at decompose time, substituting the ghostcut-mirrored
-            // URL as the source. No regex, no escape/unescape shuffling, no partial
-            // matches on URLs that contain "&". The composition is DERIVED from
-            // (scenes + captions + viralDna) × sourceUrl — flip the sourceUrl and
-            // reemit the HTML. If the persisted JSON is missing (shouldn't happen
-            // outside of a stale/interrupted fork), we log and skip the HTML update
-            // — the composition stays pointing at the original video, which the
-            // /render guard then blocks anyway.
-            let swapApplied = false;
-            const persistedText = await storage.readText(storage.compositionForkWorkingKey(fork.id, "smart-decompose.json"));
-            if (persistedText) {
-                try {
-                    const persisted = JSON.parse(persistedText);
-                    if (persisted.result && Array.isArray(persisted.result.scenes)) {
-                        const rebuilt = buildSmartDecomposedHtml({
-                            compositionId: persisted.compositionId ?? fork.id,
-                            sourceUrl: finalMirroredUrl,
-                            title: persisted.title ?? fork.title ?? fork.id,
-                            result: {
-                                summary: persisted.result.summary ?? "",
-                                viralDna: persisted.result.viralDna ?? {
-                                    trend_tagline: "", hook: "", retention: "", payoff: "",
-                                    preserve: [], avoid: [], promotions: [], keywords: []
-                                },
-                                transcript: persisted.result.transcript ?? null,
-                                durationSeconds: Number(persisted.result.durationSeconds ?? 0),
-                                width: Number(persisted.result.width ?? 720),
-                                height: Number(persisted.result.height ?? 1280),
-                                scenes: persisted.result.scenes,
-                                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: [],
-                                // 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");
-                        await snapshotForkVersion({
-                            fork,
-                            callerCustomerId: caller.id,
-                            reason: "manual",
-                            message: `GhostCut task ${state.taskId} completed — subtitles removed, composition rebuilt against cleaned video`
-                        });
-                        swapApplied = true;
-                    }
-                    else {
-                        console.error(`ghostcut-poll: smart-decompose.json for fork ${fork.id} has no scenes; skipping rebuild`);
-                    }
-                }
-                catch (parseError) {
-                    console.error("ghostcut-poll: smart-decompose.json parse failed", parseError instanceof Error ? parseError.message : parseError);
-                }
-            }
-            else {
-                console.error(`ghostcut-poll: smart-decompose.json missing for fork ${fork.id}; composition NOT rebuilt (still references original video)`);
-            }
-            const next = {
-                ...state,
-                status: "done",
-                mirroredUrl: finalMirroredUrl,
-                completedAtMs: Date.now()
-            };
-            await storage.putJson(stateKey, next);
-            // Bill the GhostCut chunk cost. Idempotency keyed on taskId so re-polls
-            // (in case of network hiccups) never double-charge.
+            // Bill the GhostCut chunk cost NOW that the mirror succeeded — the vendor
+            // work is done and paid for regardless of whether the composition rebuild
+            // lands this tick (it can't until smart-decompose.json exists). Idempotency
+            // keyed on taskId so re-polls / the awaiting_composition retry loop never
+            // double-charge.
             const seconds = state.probedDurationSeconds ?? 30;
             const cost = estimateGhostcutCostUsd(seconds);
             try {
@@ -9795,9 +9889,34 @@ const pollForkSubtitleRemoval = async (c) => {
             catch (billingError) {
                 console.error("ghostcut-poll billing failed", billingError instanceof Error ? billingError.message : billingError);
             }
+            // REBUILD (not swap) the composition from the deterministic smart-decompose
+            // snapshot, substituting the ghostcut-mirrored URL as the source. If the
+            // snapshot doesn't exist yet — EXPECTED, because the fast subtitle removal
+            // routinely beats the slow vision analysis that writes it — do NOT go
+            // terminal. Park in "awaiting_composition" (mirror preserved, already
+            // billed) and keep the client polling; the tail of /auto-decompose also
+            // attempts this same rebuild once the snapshot lands, so the swap happens
+            // whichever side wins the race. Going terminal-"done" here without the
+            // rebuild is exactly the bug that stranded compositions on the original
+            // text-baked video.
+            const swapApplied = await rebuildDecomposedCompositionAgainstCleanVideo({
+                fork,
+                callerCustomerId: caller.id,
+                cleanedSourceUrl: finalMirroredUrl,
+                snapshotMessage: `GhostCut task ${state.taskId} completed — subtitles removed, composition rebuilt against cleaned video`
+            });
+            const next = {
+                ...state,
+                status: swapApplied ? "done" : "awaiting_composition",
+                mirroredUrl: finalMirroredUrl,
+                completedAtMs: Date.now()
+            };
+            await storage.putJson(stateKey, next);
             return c.json({
                 ok: true,
-                status: "done",
+                // "pending" (not "done") until the rebuild actually lands, so the client
+                // keeps polling instead of stopping on a still-original composition.
+                status: swapApplied ? "done" : "pending",
                 task_id: state.taskId,
                 mirrored_url: finalMirroredUrl,
                 completed_at_ms: next.completedAtMs,
@@ -16563,6 +16682,9 @@ function buildJobDebugHints(input) {
     if (input.job.status === "waiting_for_provider" && Date.parse(input.job.runAfter) > Date.now()) {
         hints.push("The job is waiting for an available customer AI provider key. Step Functions will retry it after run_after.");
     }
+    if (input.job.status === "waiting_for_render") {
+        hints.push("The job dispatched a distributed render to its own state machine and is polling it via Step Functions wait+re-invoke (waiting_for_render). This is normal for long renders; check the hyperframes render execution if it never terminates.");
+    }
     if (input.job.status === "running" && input.job.updatedAt) {
         hints.push("For running jobs, compare updated_at with the latest structured log event to check heartbeat/progress freshness.");
     }
@@ -16774,15 +16896,41 @@ const AI_PRIMITIVE_IDS = new Set([
     "primitive:video_generate",
     "primitive:tts",
     "primitive:stt",
+    "primitive:music",
     "primitive:captions",
     "primitive:speech_regenerate"
 ]);
+// Audio primitives that ElevenLabs can serve — either the platform key
+// (use_wallet_credits) or the customer's own ElevenLabs key. TTS/STT can also
+// fall back to a BYOK openai/gemini/openrouter key; music cannot.
+const ELEVENLABS_AUDIO_PRIMITIVE_IDS = new Set(["primitive:tts", "primitive:stt", "primitive:music"]);
 async function preflightAiProviderKeys(input) {
     if (!operationMayUseAiProvider(input)) {
         return null;
     }
-    const activeProviders = (await normalizeEditorChatProviderRows(input.customerId)).map((entry) => entry.provider);
+    const activeProviders = (await listProviderKeysForCustomer(input.customerId))
+        .filter((entry) => String(entry.status) === "active")
+        .map((entry) => String(entry.provider));
     const mediaProviders = activeProviders.filter((provider) => MEDIA_AI_PROVIDER_TYPES.has(provider));
+    // Audio primitives run on ElevenLabs: allow when the platform key is
+    // configured, the customer saved their own ElevenLabs key, or (TTS/STT only)
+    // they hold a BYOK media key. Only block when none of those can serve it.
+    if (ELEVENLABS_AUDIO_PRIMITIVE_IDS.has(input.templateId)) {
+        const hasPlatform = Boolean(config.ELEVENLABS_API_KEY?.trim());
+        const hasUserElevenLabs = activeProviders.includes("elevenlabs");
+        const byokEligible = input.templateId !== "primitive:music";
+        if (hasPlatform || hasUserElevenLabs || (byokEligible && mediaProviders.length > 0)) {
+            return null;
+        }
+        return {
+            error: "No audio provider is available for this customer.",
+            type: "provider_key_required",
+            detail: input.templateId === "primitive:music"
+                ? "Music generation needs ElevenLabs. Enable use_wallet_credits (platform key) or save your own ElevenLabs key in Settings → AI keys."
+                : "This audio operation needs ElevenLabs (use_wallet_credits / your own ElevenLabs key) or a BYOK OpenAI/Gemini/OpenRouter key.",
+            configured_providers: [...new Set(activeProviders)]
+        };
+    }
     if (mediaProviders.length) {
         return null;
     }
@@ -17306,6 +17454,29 @@ app.post(`${PRIMITIVES_PREFIX}/audio/speech`, async (c) => createPrimitiveJob(c,
 app.post(`${PRIMITIVES_PREFIX}/tts`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:tts", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/audio/transcribe`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:stt", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/stt`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:stt", operationName: "run" }));
+// Music generation (ElevenLabs). use_wallet_credits defaults true (platform key
+// + wallet). Canonical /music/generate plus a flat /music alias.
+app.post(`${PRIMITIVES_PREFIX}/music/generate`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:music", operationName: "run" }));
+app.post(`${PRIMITIVES_PREFIX}/music`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:music", operationName: "run" }));
+// List ElevenLabs voices for TTS. Synchronous (not a job). Scope is the platform
+// account when use_wallet_credits is true/absent, else the customer's own key.
+app.get(`${PRIMITIVES_PREFIX}/audio/voices`, async (c) => {
+    const customer = requireCustomer(c);
+    const useWalletParam = (c.req.query("use_wallet_credits") ?? "").toLowerCase();
+    const useWalletCredits = useWalletParam === "false" || useWalletParam === "0" ? false : true;
+    try {
+        const { scope, voices } = await providers.listElevenLabsVoices({ customerId: customer.id, useWalletCredits });
+        return c.json({
+            scope,
+            voice_library_url: ELEVENLABS_VOICE_LIBRARY_URL,
+            default_voice_id: DEFAULT_ELEVENLABS_VOICE_ID,
+            voices
+        });
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : "Unable to list ElevenLabs voices." }, 400);
+    }
+});
 // Animated-caption cues from narration (STT + word timings + cue paging).
 app.post(`${PRIMITIVES_PREFIX}/audio/captions`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:captions", operationName: "run" }));
 app.post(`${PRIMITIVES_PREFIX}/captions`, async (c) => createPrimitiveJob(c, { primitiveId: "primitive:captions", operationName: "run" }));
@@ -19617,6 +19788,10 @@ app.post(`${RAWS_PREFIX}/scan`, async (c) => {
         // backup) so mined clips land in `/raws/<folder>` without a pipeline change.
         if (folderOverride)
             huntSpec.folder_path = folderOverride;
+        // Audio-only mining ("Clip audio only"): each mined clip is cut to an .m4a
+        // (no video). Rides the opaque hunt_spec end-to-end like folder_path.
+        if (body.audio_only === true)
+            huntSpec.audio_only = true;
         // 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).
@@ -20243,30 +20418,39 @@ async function importSubrangeAsRaw(input) {
         const end = Math.max(start + 0.05, rawEnd);
         const clipDurationSec = Number((end - start).toFixed(3));
         await touchSource({ status: "scanning", duration_sec: sourceDurationSec });
+        const audioOnly = Boolean(input.audioOnly);
+        const scene = { index: 0, start_time_sec: start, end_time_sec: end, duration_sec: clipDurationSec };
         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");
+        const clipExt = audioOnly ? "m4a" : "mp4";
+        const clipKey = `clips/${input.ownerId}/${clipId}.${clipExt}`;
+        const localClip = path.join(workRoot, `${clipId}.${clipExt}`);
+        if (audioOnly) {
+            const trimmed = await extractAudioClip({ videoPath, scene, outPath: localClip });
+            if (!trimmed || !existsSync(localClip))
+                throw new Error("Could not extract audio from that subrange (the source may have no audio track).");
+            await storage.putFile(clipKey, localClip, "audio/mp4");
+        }
+        else {
+            const trimmed = await extractClip({ videoPath, scene, 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);
+        const thumbLocal = path.join(workRoot, `${clipId}.${audioOnly ? "png" : "jpg"}`);
+        const thumbScene = { index: 0, start_time_sec: 0, end_time_sec: clipDurationSec, duration_sec: clipDurationSec };
+        // Audio raws have no video frame — plot a waveform PNG (from the trimmed audio)
+        // so the raws gallery still shows something recognizable.
+        const wroteThumb = audioOnly
+            ? await extractWaveformThumbnail({ videoPath: localClip, scene: thumbScene, outPath: thumbLocal }).catch(() => false)
+            : await extractThumbnail({ videoPath: localClip, scene: thumbScene, outPath: thumbLocal }).catch(() => false);
         if (wroteThumb && existsSync(thumbLocal)) {
-            thumbKey = `thumbs/${input.ownerId}/${clipId}.jpg`;
-            await storage.putFile(thumbKey, thumbLocal, "image/jpeg");
+            thumbKey = `thumbs/${input.ownerId}/${clipId}.${audioOnly ? "png" : "jpg"}`;
+            await storage.putFile(thumbKey, thumbLocal, audioOnly ? "image/png" : "image/jpeg");
         }
         const baseName = (input.name || ingestedTitle || input.filename || "clip").trim() || "clip";
-        const description = `${baseName} (${formatClockRange(start)}–${formatClockRange(end)})`;
+        const notes = (input.notes || "").trim();
+        const description = `${baseName}${audioOnly ? " (audio)" : ""} (${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));
@@ -20279,19 +20463,21 @@ async function importSubrangeAsRaw(input) {
             duration_sec: clipDurationSec,
             file_path: clipKey,
             thumbnail_path: thumbKey,
-            tags: { content_type: [], subject: [], action: [], emotion: [], setting: [], composition: [], motion: [], energy: "", audio_type: [], transcript: "" },
+            tags: { content_type: [], subject: [], action: [], emotion: [], setting: [], composition: [], motion: [], energy: "", audio_type: audioOnly ? ["music"] : [], transcript: "" },
             description,
             taxonomy_version: ACTIVE_TAXONOMY_VERSION,
             tier: "flash-lite",
             tracer: input.tracer,
             folder_path: folderPath,
+            media_kind: audioOnly ? "audio" : "video",
             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)]);
+                const embedText = buildClipEmbeddingText(clip.tags, clip.description) + (notes ? `\n${notes}` : "");
+                const [vector] = await embedder.embedDocuments([embedText]);
                 if (vector?.length) {
                     clip.embedding = vector;
                     clip.embedding_model = embedder.embeddingModelId;
@@ -20305,7 +20491,7 @@ async function importSubrangeAsRaw(input) {
         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 };
+        return { clipId, clipKey, thumbKey, durationSec: clipDurationSec, sourceStartSec: start, sourceEndSec: end, description, folderPath, mediaKind: audioOnly ? "audio" : "video" };
     }
     catch (error) {
         devLog("clip_range.failed", { scan_id: input.scanId, ...devErrorFields(error) }, "error");
@@ -20361,6 +20547,7 @@ app.post(`${RAWS_PREFIX}/clip-range`, async (c) => {
     const customer = requireCustomer(c);
     try {
         const body = (await c.req.json().catch(() => ({})));
+        const audioOnly = Boolean(body.audio_only ?? body.audioOnly);
         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.
@@ -20395,7 +20582,11 @@ app.post(`${RAWS_PREFIX}/clip-range`, async (c) => {
             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}`;
+        // Tracer doubles as the session id: prefer an explicit tracer/session_id,
+        // else mint a unique per-clip session so clips never collide in one shared
+        // bucket (a `clipper:<customer>` catch-all would merge every ad-hoc clip).
+        const tracer = readNonEmptyString(body.tracer) ?? readNonEmptyString(body.session_id) ?? `clipper-${createIdV7("clip").split("_").pop()}`;
+        const notes = readNonEmptyString(body.notes) ?? null;
         const folderOverride = slugifyRawFolder(body.folder_path) ?? slugifyRawFolder(tracer);
         const now = nowIso();
         const scanId = createIdV7("clipscan");
@@ -20418,7 +20609,9 @@ app.post(`${RAWS_PREFIX}/clip-range`, async (c) => {
                 sourceUrl: sourceUrl ?? null,
                 startSec,
                 endSec,
-                name: readNonEmptyString(body.name) ?? null
+                name: readNonEmptyString(body.name) ?? null,
+                notes,
+                audioOnly
             });
         }
         catch (error) {
@@ -20436,6 +20629,7 @@ app.post(`${RAWS_PREFIX}/clip-range`, async (c) => {
             duration_sec: result.durationSec,
             source_start_sec: result.sourceStartSec,
             source_end_sec: result.sourceEndSec,
+            media_kind: result.mediaKind,
             description: result.description,
             view_url: viewUrl ?? `/clips/${result.clipId}/download`,
             thumbnail_url: thumbnailUrl
@@ -20550,6 +20744,7 @@ async function runClipScanInProcess(input) {
             includeAudio: input.includeAudio,
             guidancePrompt: buildEffectiveGuidance({ contentPrompt: input.guidancePrompt, avoidText: spec.avoid_text }) || undefined,
             reencodeClips: true,
+            audioOnly: spec.audio_only === true,
             crop: spec.aspect && spec.aspect !== "original"
                 ? { aspect: spec.aspect, focus: normalizeCropFocus(spec.crop_focus) }
                 : undefined
@@ -20587,15 +20782,17 @@ async function runClipScanInProcess(input) {
                         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`;
-                const clipLocal = path.join(ctx.clipsDir, `${clip.clip_id}.mp4`);
-                await storage.putBuffer(clipKey, readFileSync(clipLocal), "video/mp4");
+                // clipMediaUrl resolves clips/… + thumbs/… keys to fetchable URLs. Audio-
+                // only hunts wrote an .m4a clip + .png waveform thumbnail (see scan.ts).
+                const audioClip = clip.media_kind === "audio";
+                const clipKey = `clips/${input.ownerId}/${clip.clip_id}.${audioClip ? "m4a" : "mp4"}`;
+                const clipLocal = path.join(ctx.clipsDir, `${clip.clip_id}.${audioClip ? "m4a" : "mp4"}`);
+                await storage.putBuffer(clipKey, readFileSync(clipLocal), audioClip ? "audio/mp4" : "video/mp4");
                 clip.file_path = clipKey;
-                const thumbLocal = path.join(ctx.thumbsDir, `${clip.clip_id}.jpg`);
+                const thumbLocal = path.join(ctx.thumbsDir, `${clip.clip_id}.${audioClip ? "png" : "jpg"}`);
                 if (existsSync(thumbLocal)) {
-                    const thumbKey = `thumbs/${input.ownerId}/${clip.clip_id}.jpg`;
-                    await storage.putBuffer(thumbKey, readFileSync(thumbLocal), "image/jpeg");
+                    const thumbKey = `thumbs/${input.ownerId}/${clip.clip_id}.${audioClip ? "png" : "jpg"}`;
+                    await storage.putBuffer(thumbKey, readFileSync(thumbLocal), audioClip ? "image/png" : "image/jpeg");
                     clip.thumbnail_path = thumbKey;
                 }
                 else {