@mevdragon/vidfarm-devcli 0.20.5 → 0.20.6

package/dist/src/app.js

@@ -55,7 +55,7 @@ import { resolveRootFileCandidates } from "./lib/package-root.js";
 import { stripTrackingParams } from "./lib/url-clean.js";
 import { addSeconds, nowIso } from "./lib/time.js";
 import { templateRegistry } from "./registry.js";
-import { buildAsyncJobHandoffText, buildEditorChatGuardrailNotice, buildEditorChatSystemInstruction, collectVerifiedHttpJobIds, compactEditorChatModelMessages, createLoadSkillTool, createStreamingJobIdRedactor, defaultEditorChatModel, EDITOR_CHAT_PROVIDER_PRIORITY, extractEditorChatCompositionBrief, formatEditorChatCurrentDateTime, lintReplaceCompositionAction, readAsyncJobHandoff, toEditorChatModelMessages } from "./editor-chat.js";
+import { buildAsyncJobHandoffText, buildEditorChatGuardrailNotice, buildEditorChatSystemInstruction, collectVerifiedHttpJobIds, compactEditorChatModelMessages, createLoadSkillTool, createStreamingJobIdRedactor, defaultEditorChatModel, EDITOR_CHAT_PROVIDER_PRIORITY, extractEditorChatCompositionBrief, extractEditorChatLazyPromptInstruction, formatEditorChatCurrentDateTime, lintReplaceCompositionAction, readAsyncJobHandoff, toEditorChatModelMessages } from "./editor-chat.js";
 import { apiCallHistoryStore } from "./services/api-call-history.js";
 import { AuthService } from "./services/auth.js";
 import { BillingService } from "./services/billing.js";
@@ -5003,7 +5003,8 @@ async function streamEditorChatAgent(input, send) {
         template: input.template,
         cachedContext: input.cachedContext ?? null,
         currentDateTime: formatEditorChatCurrentDateTime(input.clientContext) || `ISO timestamp: ${nowIso()}`,
-        compositionBrief: extractEditorChatCompositionBrief(rawMessages)
+        compositionBrief: extractEditorChatCompositionBrief(rawMessages),
+        lazyPromptInstruction: extractEditorChatLazyPromptInstruction(rawMessages)
     });
     const preparedMessages = compactEditorChatModelMessages(toEditorChatModelMessages(rawMessages));
     const tools = input.template

package/dist/src/cli.js

@@ -1429,6 +1429,7 @@ function writeLocalAgentHarnessFiles(dir) {
         generated_at: new Date().toISOString(),
         source_title: readJsonString(videoContext?.summary) || null,
         composition_context: viralDna,
+        static_vs_pivot: viralDna?.static_vs_pivot ?? null,
         editor_harness: harness,
         scenes: Array.isArray(videoContext?.scenes) ? videoContext?.scenes : [],
         scene_annotations: annotations,
@@ -1444,6 +1445,27 @@ function writeLocalAgentHarnessFiles(dir) {
     const doList = readJsonStringList(harness?.do, 5);
     const dontList = readJsonStringList(harness?.dont, 5);
     const preserve = readJsonStringList(emotionalPunch?.preserve, 5);
+    const staticVsPivot = viralDna?.static_vs_pivot && typeof viralDna.static_vs_pivot === "object"
+        ? viralDna.static_vs_pivot
+        : null;
+    const sceneReplacement = staticVsPivot?.scene_replacement && typeof staticVsPivot.scene_replacement === "object"
+        ? staticVsPivot.scene_replacement
+        : null;
+    const narrationPivot = staticVsPivot?.narration && typeof staticVsPivot.narration === "object"
+        ? staticVsPivot.narration
+        : null;
+    const musicPivot = staticVsPivot?.music && typeof staticVsPivot.music === "object"
+        ? staticVsPivot.music
+        : null;
+    const captionsPivot = staticVsPivot?.captions && typeof staticVsPivot.captions === "object"
+        ? staticVsPivot.captions
+        : null;
+    const visualRebuild = staticVsPivot?.visual_rebuild && typeof staticVsPivot.visual_rebuild === "object"
+        ? staticVsPivot.visual_rebuild
+        : null;
+    const viralPivot = staticVsPivot?.viral_dna && typeof staticVsPivot.viral_dna === "object"
+        ? staticVsPivot.viral_dna
+        : null;
     const mustPreserve = annotations
         .flatMap((entry) => readJsonStringList(entry.must_preserve, 3).map((item) => {
         const slug = readJsonString(entry.scene_slug);
@@ -1465,8 +1487,11 @@ Rules:
 - Treat the viral DNA and editor harness as hard defaults unless the user explicitly overrides them.
 - If you rewrite text, make it fit the existing performance and joke mechanic. Do not replace a format-specific bit with generic product-benefit copy.
 - Preserve the emotional punch first: tone, mechanism, contrast, audio/visual tension, delivery, and preserve beats.
+- If the user gives a lazy prompt like "recreate this for my business" with little detail, use static_vs_pivot as the first-pass execution plan instead of interrogating them for every choice.
 - Protect any harness scene marked critical/must_keep and the must_preserve notes from scene annotations.
 - When swapping visuals, match both the literal scene DNA and the narrative purpose of the beat.
+- For replacement graphics, screenshots, or still-like scenes, prefer AI image generation plus Ken Burns before paying for AI video unless static_vs_pivot says motion footage is load-bearing.
+- If narration must be customized, default to premium ElevenLabs first, then the user's own ElevenLabs path, then BYOK OpenAI/Gemini/OpenRouter. If captions or scenes were timed to the old VO, retime them to the new narration.
 
 Current format snapshot:
 - Trend tagline: ${readJsonString(viralDna?.trend_tagline) || "unknown"}
@@ -1480,9 +1505,26 @@ Current format snapshot:
 - Delivery: ${readJsonString(emotionalPunch?.delivery) || "unknown"}
 - Harness one-liner: ${readJsonString(harness?.one_liner) || "unknown"}
 
+Static vs pivot:
+- Summary: ${readJsonString(staticVsPivot?.summary) || "unknown"}
+- Scene replacement: ${readJsonString(sceneReplacement?.overall) || "unknown"}${readJsonString(sceneReplacement?.reason) ? ` — ${readJsonString(sceneReplacement?.reason)}` : ""}
+- Narration: ${readJsonString(narrationPivot?.overall) || "unknown"}${readJsonString(narrationPivot?.reason) ? ` — ${readJsonString(narrationPivot?.reason)}` : ""}
+- Music: ${readJsonString(musicPivot?.overall) || "unknown"}${readJsonString(musicPivot?.volume_guidance) ? ` — ${readJsonString(musicPivot?.volume_guidance)}` : ""}
+- Captions: ${readJsonString(captionsPivot?.overall) || "unknown"}${readJsonString(captionsPivot?.animation_dependency) ? ` — ${readJsonString(captionsPivot?.animation_dependency)}` : ""}
+- Visual rebuild: ${readJsonString(visualRebuild?.default_strategy) || "unknown"}${readJsonString(visualRebuild?.reason) ? ` — ${readJsonString(visualRebuild?.reason)}` : ""}
+
 Priority preserve beats:
 ${preserve.length ? preserve.map((item) => `- ${item}`).join("\n") : "- none recorded"}
 
+Static-vs-pivot must-keep:
+${readJsonStringList(viralPivot?.must_keep, 6).length ? readJsonStringList(viralPivot?.must_keep, 6).map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
+Static-vs-pivot flexible:
+${readJsonStringList(viralPivot?.flexible, 6).length ? readJsonStringList(viralPivot?.flexible, 6).map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
+Static-vs-pivot load-bearing scenes:
+${readJsonStringList(sceneReplacement?.load_bearing_scenes, 6).length ? readJsonStringList(sceneReplacement?.load_bearing_scenes, 6).map((item) => `- ${item}`).join("\n") : "- none recorded"}
+
 Important scenes:
 ${importantScenes.length ? importantScenes.map((item) => `- ${item}`).join("\n") : "- none recorded"}
 

package/dist/src/editor-chat.js

@@ -50,7 +50,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "IMAGE UTILITY PRIMITIVES beyond generate/edit are also first-class here. POST /api/v1/primitives/images/inpaint with body { tracer, payload: { source_image_url, mask_url, instruction } } does a MASKED edit — reach for it when only a region of an image should change and a mask is available. POST /api/v1/primitives/images/render-html with body { tracer, payload: { html, css?, width?, height?, background_color? } } rasterizes HTML/CSS into a still image — use it for title cards, quote cards, data callouts, or any designed graphic you want as a timeline image. POST /api/v1/primitives/images/remove-background with body { tracer, payload: { source_image_url } } is the AI-matting cut-out for ARBITRARY photos with a messy background; it BILLS THE WALLET (RapidAPI). POST /api/v1/primitives/images/remove-background-greenscreen with body { tracer, payload: { source_image_url, key_color?, tolerance?, softness?, despill? } } is the CHEAP local chroma-key alternative — when the source already sits on a FLAT solid background (green screen, or any key_color like #FFFFFF for white), prefer this over the RapidAPI route. MOST IMPORTANT — POST /api/v1/primitives/images/create-overlay with body { tracer, payload: { prompt, key_color?, aspect_ratio?, prompt_attachments? } } is the go-to CREATE MEDIA OVERLAY primitive: it generates an AI image on a forced flat key-color background (BYOK image keys) and chroma-keys it out in ONE job, returning a ready-to-composite transparent PNG (result.primary_file_url). This is exactly how you mint 'Vox-style' floating illustrations, props, icons, and cut-out characters to add_layer as an animated overlay — reach for it FREQUENTLY instead of a flat still whenever a scene wants a transparent graphic element floating over the video. It bills a small wallet fee plus the BYOK image-gen cost.",
         "If the user asks to generate a new AI video from text or reference images, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, input_references?, duration? } }. AI video duration is seconds; use duration: 4 for a 4-second video and never use duration_ms on /videos/generate. input_references must be direct image asset URLs, not webpage or social post URLs. Use frame_images for exact first/last-frame image-to-video.",
         "If the user asks to render HTML/design into an image, call POST /api/v1/primitives/images/render-html. If the user asks to turn existing media URLs into a slideshow/video, call POST /api/v1/primitives/videos/render-slides. If the user asks to dedupe, camouflage, or apply small zoom/tilt/rotate/filter/tint transforms to an image or video for reuse, call POST /api/v1/primitives/media/dedupe with body { tracer, payload: { source_media_url, media_type?, effects?: { zoom?, tilt?, rotate?, saturation?, speed?, horizontal_flip?, contrast?, brightness?, hue_rotate?, blur? }, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Primitive media utility routes are also allowed directly here, including /videos/trim, /videos/remove-captions, /videos/extract-audio, /videos/probe, /videos/extract-frame, /videos/mute, /videos/replace-audio, /videos/concat, /audio/trim, /audio/probe, /audio/concat, and /audio/normalize. 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 a 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?, tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver), aspect crops every clip, and avoid_text prefers text-free scenes via scene SELECTION (never caption removal on the source). The hunt is async (202 + scan_id): poll GET /clips/scan/:scanId, then browse 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. To erase captions from a finished HUNTED clip, pass that short mp4 to /videos/remove-captions afterwards. When the user instead wants ONE EXACT subrange saved as a raw — 'clip 0:30 to 0:45 into my raws', 'save that 10-second bit as a raw', a precise hand-picked in/out — do NOT run an AI hunt: call POST /raws/clip-range with body { source_url | preview_url | temp_file_id, start_sec, end_sec, tracer?, folder_path?, name? }. It trims EXACTLY [start_sec, end_sec] and lands a single raw (compute-only, no AI, no BYOK key). This is the same operation as the web /tools/clipper page and the devcli `vidfarm clipper` command; use it for surgical single clips and reserve /clips/scan for open-ended multi-clip hunts.",
-        "SPEECH PRIMITIVES (TTS/STT) are first-class here. VOICEOVER / NARRATION: when the user wants a script, hook, caption, or dub read aloud as AI audio, call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? } } — instructions is a free-form voice-STYLE prompt (tone, pacing, accent, emotion, persona; e.g. 'calm warm bedtime narrator' or 'excited sports announcer, fast paced'), and voice picks a provider preset (OpenAI: alloy/ash/coral/...; Gemini: Kore/Puck/Charon/...). When sending a voice you may omit provider — it is inferred from the voice preset; a voice paired with the WRONG provider (e.g. voice 'Kore' with provider 'openai') is rejected with a 400, so never mix families. The finished job returns a durable audio URL — place it on the timeline with editor_action add_layer (kind=audio, src=that URL), typically starting where the narration should begin. TRANSCRIPTION: when the user wants a transcript, subtitles/captions from speech, a translation source, or to know who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language?, prompt? } } — source_url may be a VIDEO or AUDIO URL (video audio is demuxed automatically; pick the fork's source via GET /api/v1/compositions/:forkId/remove-video-captions first when transcribing the current composition). One job returns BOTH formats: a simple subtitle version (plain transcript text + timed SRT cues, stored as transcript.txt/transcript.srt) and an advanced multi-speaker version (speaker-attributed timed segments in output.segments and transcript.json) for multi-narration sources like podcasts and interviews. diarize defaults to true and speaker attribution needs a Gemini key — openai/openrouter keys degrade to a plain single-speaker transcript. For transcript-grounded caption work on THIS fork, the read-only video_context tool may already contain the decompose-time transcript; prefer it before running a new billable-key transcription, and use /audio/transcribe for other URLs, multi-speaker attribution, or SRT output. REGENERATE / REVOICE: when the user wants the SAME speaker to say DIFFERENT words (reword the narration, fix a line, change an offer or CTA, redub in 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 — one of the two is required), voice?, instructions?, provider?, model?, language?, output_format? } }. One job listens to the source, profiles the speaker's voice, rewords the script, and returns a durable audio URL spoken by the CLOSEST PRESET voice with a style prompt matched to the speaker (result fields: audioUrl, script, original_transcript, voice_profile, voice_match). Voice profiling needs a saved Gemini key — with only openai/openrouter keys the job degrades to transcript-only rewording with a default or explicitly passed voice and voice_match 'none'. IMPORTANT HONESTY RULE: OpenAI and Gemini APIs cannot clone voice identity (preset voices only), so always tell the user the regenerated audio APPROXIMATES the original voice rather than clones it. To swap the regenerated audio into the composition, mute the original span (/videos/mute or volume/muted on the layer) and place the new audio with editor_action add_layer (kind=audio, src=audioUrl). RECONCILE LENGTH: reworded narration is rarely exactly the same length as the original, so after placing it do NOT assume the timeline still lines up — read the new audio layer's duration (or /audio/probe it) and re-sync: adjust the muted original span, and when captions or scenes were timed to the narration, re-run set_captions (or ripple_edit / set_layer_timing) so words and visuals track the new audio instead of drifting out of sync.",
+        "SPEECH PRIMITIVES (TTS/STT) are first-class here. VOICEOVER / NARRATION: when the user wants a script, hook, caption, or dub read aloud as AI audio, call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions?, use_wallet_credits?, provider?, model?, output_format? } }. `use_wallet_credits` defaults to true, which routes to premium ElevenLabs on the platform path; keep that default for the best narration unless there is a reason to avoid wallet spend. Set `use_wallet_credits:false` only when you intentionally want the user's own ElevenLabs key or a BYOK OpenAI/Gemini/OpenRouter path. ElevenLabs voices use a voice_id (list them with GET /api/v1/primitives/audio/voices); OpenAI/Gemini voices use their normal provider presets. instructions is a free-form voice-STYLE prompt (tone, pacing, accent, emotion, persona; e.g. 'calm warm bedtime narrator' or 'excited sports announcer, fast paced'). The finished job returns a durable audio URL — place it on the timeline with editor_action add_layer (kind=audio, src=that URL), typically starting where the narration should begin. TRANSCRIPTION: when the user wants a transcript, subtitles/captions from speech, a translation source, or to know who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language?, prompt? } } — source_url may be a VIDEO or AUDIO URL (video audio is demuxed automatically; pick the fork's source via GET /api/v1/compositions/:forkId/remove-video-captions first when transcribing the current composition). One job returns BOTH formats: a simple subtitle version (plain transcript text + timed SRT cues, stored as transcript.txt/transcript.srt) and an advanced multi-speaker version (speaker-attributed timed segments in output.segments and transcript.json) for multi-narration sources like podcasts and interviews. diarize defaults to true and speaker attribution needs a Gemini key — openai/openrouter keys degrade to a plain single-speaker transcript. For transcript-grounded caption work on THIS fork, the read-only video_context tool may already contain the decompose-time transcript; prefer it before running a new billable-key transcription, and use /audio/transcribe for other URLs, multi-speaker attribution, or SRT output. REGENERATE / REVOICE: when the user wants the SAME speaker to say DIFFERENT words (reword the narration, fix a line, change an offer or CTA, redub in 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 — one of the two is required), voice?, instructions?, provider?, model?, language?, output_format? } }. One job listens to the source, profiles the speaker's voice, rewords the script, and returns a durable audio URL spoken by the CLOSEST PRESET voice with a style prompt matched to the speaker (result fields: audioUrl, script, original_transcript, voice_profile, voice_match). Voice profiling needs a saved Gemini key — with only openai/openrouter keys the job degrades to transcript-only rewording with a default or explicitly passed voice and voice_match 'none'. IMPORTANT HONESTY RULE: OpenAI and Gemini APIs cannot clone voice identity (preset voices only), so always tell the user the regenerated audio APPROXIMATES the original voice rather than clones it. To swap the regenerated audio into the composition, mute the original span (/videos/mute or volume/muted on the layer) and place the new audio with editor_action add_layer (kind=audio, src=audioUrl). RECONCILE LENGTH: reworded narration is rarely exactly the same length as the original, so after placing it do NOT assume the timeline still lines up — read the new audio layer's duration (or /audio/probe it) and re-sync: adjust the muted original span, and when captions or scenes were timed to the narration, re-run set_captions (or ripple_edit / set_layer_timing) so words and visuals track the new audio instead of drifting out of sync.",
         "MUSIC / BGM — HONESTY RULE: there is NO music-generation capability in this editor. You CANNOT create a background-music track from a prompt, and you must NEVER fabricate one by duplicating the narration/speech audio onto a second 'music' layer — that just doubles the voice and is not music. Real background music can ONLY come from: (1) a track the user already owns — browse_files search across /files and /raws for their audio (mp3/wav/m4a/aac) — or (2) a music file/URL the user explicitly provides. If neither exists, tell the user plainly that you can't generate music here and offer to search their files or use a track they upload; do NOT invent a music layer or claim you added music. Only once you have a REAL music URL, add_layer kind=audio at a low volume (e.g. 0.1-0.2) under the narration.",
         "NATIVE MULTI-TRACK AUDIO — the timeline mixes UNLIMITED simultaneous audio layers. Each audio layer sits on its own track and carries its own data-volume (0-2, default 1), and the runtime mixes them together with per-track volume honored IDENTICALLY in the live preview and the exported MP4 (the render does a real ffmpeg amix of every audio layer). So overlaying sound is native: you do NOT need a pre-mixed file. Put narration/voiceover on one audio layer at full level (~1.0), a music bed on a SEPARATE audio layer at low level (~0.1-0.2), and any SFX on their own layers — each via editor_action add_layer (kind=audio, src, plus its own start/duration/track/volume), or tune an existing audio/video layer's level with set_layer_media (volume, muted). Different layers at different volumes is the normal, supported case — never collapse multiple sounds into one track when they should be independently adjustable.",
         "SPLIT COMBINED AUDIO WHEN RECREATING — the most important use of multi-track audio: when the user is recreating/replicating a template whose ORIGINAL had music + narration baked TOGETHER into a single audio track, do NOT reproduce it as one combined bed. Rebuild it as TWO independent audio tracks — a fresh narration track (generate the new script via /api/v1/primitives/audio/speech, or same-speaker reword via /api/v1/primitives/audio/regenerate-speech) at ~1.0 on one track, and a separate REAL music track at ~0.1-0.2 on another track — then mute or remove the original combined source-audio layer so the old voice doesn't play under the new one. This gives the user independent voice and music volume afterwards, and is the elegant workaround for AI TTS models being unable to emit narration+music in one file: compose the mix on the timeline instead. HONESTY: you cannot un-mix / stem-separate the original's baked-in combined audio — the 2-track version is BUILT from a fresh narration track PLUS a real music file (owned / user-provided / found via browse_files), never by faking a music layer or duplicating the voice track (see the MUSIC/BGM honesty rule).",
@@ -88,7 +88,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "FORKING IS AUTOMATIC — you never manually 'create a fork' before editing. The editor_context reports the project state so you know what you're holding: composition_origin ('inspiration' = a decomposed catalog template opened as a structural reference — the common case; 'raw' = the user's own new project), has_saved_fork (whether edits are currently persisting to a real editable copy), and is_new_project. When has_saved_fork is false on a REAL template (a template_… id, a catalog reference, or any decomposed composition), just start editing — the FIRST mutating editor_action mints the user their OWN private editable fork and every edit after it persists normally; do NOT ask permission to fork, wait for the user to fork, or announce 'forking'. The ONE exception is is_new_project:true (composition_id \"original\"): that is a BLANK project with no template behind it yet, so there is nothing to fork and editor_action edits will NOT persist. In that state don't promise saves — mint a real composition first: on a blank project the create_video tool IS available (call it to build a brand-new video from the user's idea via mode=generate, or to recreate a pasted TikTok/YouTube/Instagram/X URL via mode=replicate — it runs the ingest→decompose→fork pipeline and drops an 'Open in editor' link), or point the user at a fitting existing template (GET /discover/feed?q=<their idea>). Once a real composition is open, edit it normally. A save_status:\"error\" / is_read_only immediately after editing a brand-new project means the auto-fork itself failed — say so plainly instead of claiming the edit saved. The ONLY time you fork ON PURPOSE is when the user EXPLICITLY asks to branch / duplicate / 'save as' / 'make a copy' / 'try a variation' / 'keep this version and start another' — then call editor_action action_type=fork_composition with fork_from='current' (branch a new copy that keeps all current edits) or fork_from='default' (start a fresh copy from the original template, discarding the current edits). This mints a NEW fork and opens it in the editor; it is the same 'New fork' action available in the editor's ⋯ menu. Never call fork_composition just to begin editing — that is what the automatic first-edit fork is for.",
         "AGENTIC VIDEO EDITING — THE THREE AXES (your core mental model for this editor). Almost every /editor session is the user taking a template, fork, or project and RE-WORKING it, and a re-work only ever touches three independent axes: SCENES (the video/image clips that carry the visuals), AUDIO (narration/voiceover, music, SFX), and TEXT (on-screen captions, titles, overlays). On each axis the intent sits somewhere on a SWAP↔REPLACE spectrum, and the three axes in one request can sit at DIFFERENT points — read the request and place each axis before you act. SWAP (light, cheap, the common case) keeps the existing structure and changes content IN PLACE: rewrite a caption/text layer (set_layer_text / set_captions), swap one clip's media for another of the same kind while keeping its timing and geometry (set_layer_media), or re-voice the narration (regenerate-speech, then mute the original span and add_layer the new audio). Many sessions are ONLY a text swap — that is a two-minute job, so just do it and confirm. REPLACE (heavy) throws out that axis's content and rebuilds it: restructure the scenes outright (new clip count / new beats via remove_layer + add_layer / generate_layer, or one replace_composition_html), lay down a brand-new audio bed, or rewrite every caption. The HARDEST end is a full re-theme where the ONLY thing preserved is the VIRAL DNA — the hook shape, pacing, scene-count rhythm, and transition/caption style — while every scene, every word, and the audio are all replaced for the user's new subject. Name your plan back to the user in these terms (e.g. 'I'll SWAP the captions and REPLACE the scenes'), then execute axis by axis. Be proactive at the heavy end: propose the whole re-work and drive it scene by scene instead of waiting to be micro-managed one layer at a time. This is first-class agentic editing — you are expected to carry a total transformation, not just nudge single layers.",
         "EDITOR HARNESS — YOUR STYLE-EXECUTION BRIEF (read it before any nontrivial edit). editor_context.editor_harness is the decompose pass's TECHNICAL EDITING DIRECTION: how to edit so the result recreates the source's STYLE. It is the 'how to edit like this' companion to composition_context's viral DNA ('why it works'). When present it carries: one_liner (the style in a sentence); pacing (cut_rhythm fast|medium|slow|varied, avg_scene_seconds, cuts_per_10s, energy_curve); typography (caption_style, placement, font_character, emphasis, text_density); broll (reliance, sourcing, shot_kinds, cadence); transitions (default, intro, outro, usage); audio (voiceover, music, sfx, captions_from); emotional (target_feeling, tone, comedic_timing, intonation, vibe_anchors — HOW to edit so the FEELING survives); scenes[] (each a beat's role + importance + must_keep + edit_bias); important_scenes; editing_bias; do; dont. USE IT to pick concrete moves: map typography.caption_style straight to a set_captions caption_style preset (karaoke/word-pop/spotlight/stack-up/neon/bounce); map transitions.default/intro/outro to a set_transitions call; honor pacing (keep cut rhythm / avg_scene_seconds when adding or splitting scenes); follow broll.reliance + sourcing to decide whether to HUNT raws (/clips/scan) vs generate_layer and at what cadence; lay audio per audio.*; treat emotional.* as a HARD constraint — the vibe, the joke, and the intonation are the first things a remix flattens, so preserve emotional.comedic_timing (the held beat / pause / hard cut that sells the joke), keep the delivery cadence in emotional.intonation when you rewrite or re-voice narration, and honor every one of emotional.vibe_anchors when you re-cut or re-time; and above all PROTECT the beats in important_scenes and any scene with must_keep:true or importance 'critical' (swapping their subject is fine, but preserve their timing, role, and caption cadence — that is where the style lives). Treat editing_bias/do/dont as hard constraints for this composition. The harness sets defaults, not a straitjacket — an explicit user instruction always wins. The local devcli agent reads the SAME brief from editor-harness.json (under `.harness`); the web editor gets it inline here. If editor_harness is absent, the fork wasn't decomposed with the harness pass — fall back to composition_context + the video_context tool.",
-        "RE-THEME / REUSE A TEMPLATE AS A REFERENCE — the single most common editor intent. Users open a template to keep its VIRAL DNA (structure, scene count, pacing, hook shape, transitions, caption style) while changing the SUBJECT to their own topic — e.g. 'make this book-recap template about \"The Richest Man in Babylon\"', 'do this one for my coffee brand'. Treat it as a first-class flow: PRESERVE the DNA and format (read composition_context and, when you need the scene beats/arc, the video_context tool) and REPLACE the content — rewrite every on-screen text/caption layer to the new subject IN THE TEMPLATE'S VOICE (set_layer_text / set_captions, per the format rule above), regenerate the narration in the SAME speaker's voice for the new script (/audio/regenerate-speech, then swap per the speech rule), and swap the visuals to match (generate_layer to replace scene clips, or reuse the user's own footage from My Files / raws via browse_files). Keep the clip timings, transitions, and caption animation intact so the proven format survives the swap. You don't ask permission to fork — the first edit auto-forks it into the user's own copy (see FORKING IS AUTOMATIC). Before rewriting, PROPOSE a short plan and ask ONLY what you can't infer: the specifics of the new subject (e.g. which of the book's ideas to feature — offer to pick the strongest N to match the scene count), whether to keep the current narrator voice, any brand assets/images they want used (else you'll generate them), and a target length if it differs from the template. Don't interrogate — one concise proposal plus a couple of questions, then execute scene by scene. Example opener for the book case: 'I'll keep this template's N-scene structure, pacing and caption style and re-theme it to The Richest Man in Babylon — rewriting the narration around the book's core money lessons and swapping the visuals to match. Any specific lessons you want featured (or I'll pick the strongest N)? Keep the current narrator voice? Have a cover image or should I generate the visuals?'",
+        "RE-THEME / REUSE A TEMPLATE AS A REFERENCE — the single most common editor intent. Users open a template to keep its VIRAL DNA (structure, scene count, pacing, hook shape, transitions, caption style) while changing the SUBJECT to their own topic — e.g. 'make this book-recap template about \"The Richest Man in Babylon\"', 'do this one for my coffee brand'. Treat it as a first-class flow: PRESERVE the DNA and format (read composition_context and, when you need the scene beats/arc, the video_context tool) and REPLACE the content — rewrite every on-screen text/caption layer to the new subject IN THE TEMPLATE'S VOICE (set_layer_text / set_captions, per the format rule above), regenerate the narration only when composition_context.static_vs_pivot.narration says the original words no longer make sense, and swap the visuals according to composition_context.static_vs_pivot.scene_replacement and visual_rebuild (prefer image generation plus Ken Burns for graphic/still scenes, and reserve AI video or hunted footage for load-bearing motion scenes). Keep the clip timings, transitions, and caption animation intact unless static_vs_pivot says the new narration/captions need re-timing. You don't ask permission to fork — the first edit auto-forks it into the user's own copy (see FORKING IS AUTOMATIC). Before rewriting, PROPOSE a short plan and ask ONLY what you can't infer: the specifics of the new subject (e.g. which of the book's ideas to feature — offer to pick the strongest N to match the scene count), whether to keep the current narrator voice, any brand assets/images they want used (else you'll generate them), and a target length if it differs from the template. Don't interrogate — one concise proposal plus a couple of questions, then execute scene by scene. Example opener for the book case: 'I'll keep this template's N-scene structure, pacing and caption style and re-theme it to The Richest Man in Babylon — rewriting the narration around the book's core money lessons and swapping the visuals to match. Any specific lessons you want featured (or I'll pick the strongest N)? Keep the current narrator voice? Have a cover image or should I generate the visuals?'",
         "FUEL A SCENE REPLACE WITH RAW CLIPS (don't default to expensive AI video). A heavy REPLACE of the SCENES axis needs footage, and you have three sources in cost order: (1) the user's own library — browse_files search across /raws and /files for clips that already fit the new scenes; (2) HUNTING new raws out of a long-form source — the cheap way to get REAL footage; (3) AI generation (generate_layer) — the expensive last resort, only for scenes no real clip can cover. When a scene replace needs footage the user could plausibly supply and their library doesn't already have it, PROACTIVELY offer to mine it: if they have or name a podcast, stream VOD, webinar, or any YouTube/TikTok/IG/X URL, call POST /clips/scan (alias /raws/scan) with body { tracer, source_url|temp_file_id|attachment_id, prompt: <what the new scenes need>, aspect: <the editor_context aspect_ratio>, target_duration_sec?, avoid_text?, ranges? } — an async hunt (202 + scan_id; bills AWS compute only, its BYOK AI tagging is free) that cuts the source into short, tagged, searchable raws. Poll GET /clips/scan/:scanId, then browse GET /raws/feed?source=<source_video_id> or POST /raws/search { query } and drop the picks onto the timeline (set_layer_media to swap a clip in place keeping timing+geometry, add_layer for net-new scenes). Hunting real clips is dramatically cheaper than AI-generating every scene and usually more authentic, so reach for it FIRST when a heavy scene REPLACE needs footage — reserve generate_layer for the gaps real footage cannot fill. If the user describes a big scene re-work but hasn't given you footage, ASK them for a source video to hunt (or point them at their /raws library) BEFORE reaching for AI generation.",
         "CRITICAL — verify your edits actually landed. An editor_action tool result only echoes the arguments you sent; it is NOT proof the change was applied or saved. The real outcome shows up in the NEXT <editor_context>. Before telling the user an edit succeeded, check that block: (1) if it contains save_status:\"error\" (or is_read_only:true / a save_error message), the composition is NOT being saved — do NOT claim any edit worked; tell the user exactly what save_error says (e.g. the video is read-only from this link and they should open their own copy to edit) and stop making mutating editor_action calls until it clears; (2) if it contains recent_action_results, each entry with ok:false is an edit from your previous turn that FAILED (read its error) — acknowledge the failure and retry or explain it rather than repeating a false success; (3) otherwise confirm the intended change is reflected in the layers (e.g. the new text on the target layer) before saying it's done. Never report a timeline edit as successful without this check.",
         "editor_context also carries the canvas shape and free time: composition_width, composition_height, and aspect_ratio (e.g. '9:16') describe the output frame — when generating media to place on this timeline, request the matching aspect_ratio on /videos/generate and /images/generate so it fills the canvas without letterboxing or wrong cropping. timeline_gaps is a precomputed array of {start, end, duration} spans (seconds) where NO visual layer is on screen — i.e. the literal blank/black moments. When the user says something like 'at 00:05:52 there's blank space, add X', map their timestamp (interpret mm:ss or seconds sensibly) to the covering entry in timeline_gaps, set the new layer's start to that gap's start (or the user's exact time if inside the gap) and clamp its duration to fit the gap unless the user asks otherwise. If the requested time is NOT inside any timeline_gaps entry, tell the user it already has content there and offer to overlay on a higher track or replace the existing layer instead of silently colliding.",
@@ -191,6 +191,9 @@ export function buildEditorChatSystemInstruction(input) {
     if (input.compositionBrief?.trim()) {
         sections.push(input.compositionBrief.trim());
     }
+    if (input.lazyPromptInstruction?.trim()) {
+        sections.push(input.lazyPromptInstruction.trim());
+    }
     if (input.currentDateTime?.trim()) {
         sections.push([
             "Current datetime for scheduling:",
@@ -216,6 +219,75 @@ export function formatEditorChatCurrentDateTime(clientContext) {
     }
     return lines.join("\n");
 }
+function stripEditorContextBlock(text) {
+    return text.replace(EDITOR_CONTEXT_BLOCK_RE, "").trim();
+}
+function latestUserMessageText(messages) {
+    if (!Array.isArray(messages)) {
+        return "";
+    }
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const entry = messages[i];
+        if (!entry || typeof entry !== "object" || entry.role !== "user") {
+            continue;
+        }
+        return stripEditorContextBlock(readRawMessageText(entry));
+    }
+    return "";
+}
+function isLazyRethemePrompt(text) {
+    const normalized = text.trim().toLowerCase();
+    if (!normalized) {
+        return false;
+    }
+    const isShort = normalized.length <= 220;
+    const likelyRetheme = [
+        "recreate this",
+        "recreate that",
+        "do this for",
+        "make this for",
+        "redo this for",
+        "use this for",
+        "turn this into",
+        "for my business",
+        "for my brand",
+        "for my company",
+        "for my product",
+        "for my app",
+        "for my store"
+    ].some((needle) => normalized.includes(needle));
+    const detailed = [
+        "scene",
+        "script",
+        "voice",
+        "narration",
+        "caption",
+        "captions",
+        "music",
+        "shot",
+        "b-roll",
+        "asset",
+        "logo",
+        "exactly",
+        "specific"
+    ].filter((needle) => normalized.includes(needle)).length >= 3 || normalized.split(/\s+/).length > 40;
+    return isShort && likelyRetheme && !detailed;
+}
+export function extractEditorChatLazyPromptInstruction(messages) {
+    const latest = latestUserMessageText(messages);
+    if (!isLazyRethemePrompt(latest)) {
+        return null;
+    }
+    return [
+        "LAZY RETHEME MODE — the latest user prompt is a thin 'recreate this for my business/brand' request with little detail, so do NOT bounce the user into a long interview.",
+        "Default to a proactive re-theme plan grounded in composition_context, editor_harness, video_context, and especially viral_dna.static_vs_pivot. Treat static_vs_pivot as the source of truth for what must stay versus what can pivot.",
+        "For replacement visuals, prefer the cheapest faithful path first: when scenes are graphics, screenshots, cards, stills, or can plausibly read as motion from a still, generate IMAGES and apply Ken Burns rather than paying for AI video. Only escalate to AI video or hunted footage when static_vs_pivot says the scene truly needs moving footage.",
+        "Narration decision: if static_vs_pivot.narration says the original audio is load-bearing, keep it. If the spoken words are source-specific and static_vs_pivot says customize_script, regenerate narration and then re-sync dependent scenes/captions. Prefer premium ElevenLabs narration on the platform path first, then the customer's own ElevenLabs path if they have one, then BYOK OpenAI/Gemini/OpenRouter as fallback.",
+        "If narration is customized, also inspect static_vs_pivot.music and decide whether the original music must stay, be recreated under the new voice, or is irrelevant. Preserve the intended voice/music balance with native multi-track audio rather than one baked combined track.",
+        "If static_vs_pivot.captions says timings or animations depend on the spoken words, recreate the animated captions against the NEW narration timing rather than reusing stale cue timing.",
+        "Be explicit about scene replacement: replace every scene static_vs_pivot.scene_replacement marks as replaceable, but preserve every load-bearing or must-keep scene it names. Do not flatten the viral DNA by replacing scenes that are the core proof, payoff, or joke mechanic."
+    ].join("\n");
+}
 function tryParseUrl(value) {
     try {
         return new URL(value);

package/dist/src/services/hyperframes.js

@@ -1556,6 +1556,41 @@ Return strictly valid JSON matching this schema:
       "delivery": string,
       "preserve": [string, ...]
     },
+    "static_vs_pivot": {
+      "summary": string,
+      "scene_replacement": {
+        "overall": "replace_most" | "replace_some" | "keep_most" | "keep_all",
+        "reason": string,
+        "must_keep": [string, ...],
+        "should_replace": [string, ...],
+        "load_bearing_scenes": [string, ...]
+      },
+      "narration": {
+        "overall": "keep_original" | "customize_script" | "optional",
+        "reason": string,
+        "same_timing_required": boolean,
+        "use_premium_tts_when_customizing": boolean
+      },
+      "music": {
+        "overall": "keep_original" | "recreate_under_narration" | "optional" | "none",
+        "reason": string,
+        "volume_guidance": string
+      },
+      "captions": {
+        "overall": "reuse_existing" | "retime_to_new_narration" | "optional" | "none",
+        "reason": string,
+        "animation_dependency": string
+      },
+      "visual_rebuild": {
+        "default_strategy": "ai_images_with_ken_burns" | "real_footage" | "mixed",
+        "reason": string
+      },
+      "viral_dna": {
+        "must_keep": [string, ...],
+        "flexible": [string, ...],
+        "do_not_change": [string, ...]
+      }
+    },
     "preserve": [string, ...],
     "avoid": [string, ...],
     "promotions": [string, ...],
@@ -1606,6 +1641,14 @@ VIRAL_DNA RULES:
   - "delivery": the performance cues to preserve so the vibe survives — speech intonation / cadence (from the AUDIO TRANSCRIPT), the pause held before the punchline, a facial beat or reaction, and especially the SOUND: the music / trending-audio bed, where the beat drop or lyric hit lands relative to the cut, a music swell, an sfx sting, the deadpan-then-cut. This is what keeps intonation, comedic timing, and the audio-driven vibe from being lost in a remix.
   - "preserve": 2-4 emotional beats a remix MUST keep to reproduce the same feeling (e.g. "keep the beat drop landing exactly on the reveal cut", "hold the silent beat before the reveal", "keep the flat unbothered delivery", "the payoff must undercut the buildup, not confirm it").
   Use BOTH the frames and the AUDIO TRANSCRIPT block above. Never leave emotional_punch empty — infer the feeling from the frames, captions, and pacing even when there is no audio, and when the audio is music-only, treat the sound itself as the emotional engine. Do NOT over-index on a single gesture or hand movement if the real emotional engine is the character attitude, the soundtrack choice, the setting mismatch, or the audio-vs-visual contrast.
+- "static_vs_pivot": this is the load-bearing reuse guidance for lazy prompts like "please recreate this video for my business". Make it operational, not vague.
+  - "summary": one sentence on what can change versus what must stay.
+  - "scene_replacement": decide whether most scenes should be replaced or only some, why, which scenes are load-bearing, and which scenes are the first candidates to swap.
+  - "narration": decide whether the original spoken audio can stay as-is (for example because it is a generic or trending sound) or whether it must be customized because the words are source-specific. Set "customize_script" whenever the spoken words would stop making sense after a subject swap. If narration is timing-sensitive, set same_timing_required true.
+  - "music": decide whether original music should stay, be recreated under a new narration, or is irrelevant. Include simple mix guidance like "keep low under VO" or "music is the main viral engine".
+  - "captions": decide whether existing caption timing/animation can be reused, whether they must be re-timed to new narration, or whether captions are not important. Call out if the animation is tightly coupled to the spoken words.
+  - "visual_rebuild": default strategy for replacement visuals. When the source mainly uses graphics, screenshots, product cards, or still-like scenes that do not need expensive motion video, prefer "ai_images_with_ken_burns" and explain that slow pan/zoom is enough.
+  - "viral_dna": separate format elements into "must_keep", "flexible", and "do_not_change" so an agent can preserve the viral structure while swapping subject matter.
 - "preserve": 3-5 concrete elements a remixer MUST keep to preserve the format (e.g., "Pinned comment stays on-screen the whole video", "Wedding dance payoff shot").
 - "avoid": 3-5 things that would break the format if changed (e.g., "Do not remove the on-screen text overlay", "Do not slow the cuts below 1.5s").
 - "promotions": 3-5 categories of product / service / offer this exact format could be reused to promote, WITHOUT changing the beat structure or hook mechanic. Each item is a concrete pitchable use-case, not a genre. Examples: "SaaS free-trial signup (before/after workflow)", "Fitness challenge (7-day transformation)", "Local restaurant grand-opening (line-out-the-door proof)", "Ebook / course launch (result-first payoff)", "Real-estate open-house (walk-through reveal)". Anchor each promotion to the same viral tactic captured in "hook" — do not invent unrelated verticals.
@@ -1797,7 +1840,24 @@ const DEFAULT_EMOTIONAL_PUNCH = {
     preserve: []
 };
 export const DEFAULT_VIRAL_DNA = {
-    trend_tagline: "", hook: "", retention: "", payoff: "", emotional_punch: { ...DEFAULT_EMOTIONAL_PUNCH }, preserve: [], avoid: [], promotions: [], keywords: []
+    trend_tagline: "",
+    hook: "",
+    retention: "",
+    payoff: "",
+    emotional_punch: { ...DEFAULT_EMOTIONAL_PUNCH },
+    static_vs_pivot: {
+        summary: "",
+        scene_replacement: { overall: "replace_some", reason: "", must_keep: [], should_replace: [], load_bearing_scenes: [] },
+        narration: { overall: "optional", reason: "", same_timing_required: false, use_premium_tts_when_customizing: true },
+        music: { overall: "optional", reason: "", volume_guidance: "" },
+        captions: { overall: "optional", reason: "", animation_dependency: "" },
+        visual_rebuild: { default_strategy: "mixed", reason: "" },
+        viral_dna: { must_keep: [], flexible: [], do_not_change: [] }
+    },
+    preserve: [],
+    avoid: [],
+    promotions: [],
+    keywords: []
 };
 function normalizeEmotionalPunch(value) {
     if (!value || typeof value !== "object")
@@ -1820,6 +1880,82 @@ function normalizeEmotionalPunch(value) {
         preserve: asStringArray(record.preserve).slice(0, 4)
     };
 }
+function normalizeStaticVsPivot(value) {
+    const fallback = DEFAULT_VIRAL_DNA.static_vs_pivot;
+    if (!value || typeof value !== "object") {
+        return {
+            ...fallback,
+            scene_replacement: { ...fallback.scene_replacement },
+            narration: { ...fallback.narration },
+            music: { ...fallback.music },
+            captions: { ...fallback.captions },
+            visual_rebuild: { ...fallback.visual_rebuild },
+            viral_dna: { ...fallback.viral_dna }
+        };
+    }
+    const record = value;
+    const asString = (v) => typeof v === "string" ? v.trim() : "";
+    const asStringArray = (v) => Array.isArray(v)
+        ? v.map((item) => (typeof item === "string" ? item.trim() : "")).filter((item) => item.length > 0)
+        : [];
+    const sceneReplacement = record.scene_replacement && typeof record.scene_replacement === "object"
+        ? record.scene_replacement
+        : {};
+    const narration = record.narration && typeof record.narration === "object"
+        ? record.narration
+        : {};
+    const music = record.music && typeof record.music === "object"
+        ? record.music
+        : {};
+    const captions = record.captions && typeof record.captions === "object"
+        ? record.captions
+        : {};
+    const visualRebuild = record.visual_rebuild && typeof record.visual_rebuild === "object"
+        ? record.visual_rebuild
+        : {};
+    const viralDna = record.viral_dna && typeof record.viral_dna === "object"
+        ? record.viral_dna
+        : {};
+    const oneOf = (v, allowed, fallbackValue) => {
+        const text = asString(v);
+        return allowed.includes(text) ? text : fallbackValue;
+    };
+    return {
+        summary: asString(record.summary),
+        scene_replacement: {
+            overall: oneOf(sceneReplacement.overall, ["replace_most", "replace_some", "keep_most", "keep_all"], "replace_some"),
+            reason: asString(sceneReplacement.reason),
+            must_keep: asStringArray(sceneReplacement.must_keep),
+            should_replace: asStringArray(sceneReplacement.should_replace),
+            load_bearing_scenes: asStringArray(sceneReplacement.load_bearing_scenes)
+        },
+        narration: {
+            overall: oneOf(narration.overall, ["keep_original", "customize_script", "optional"], "optional"),
+            reason: asString(narration.reason),
+            same_timing_required: narration.same_timing_required === true,
+            use_premium_tts_when_customizing: narration.use_premium_tts_when_customizing !== false
+        },
+        music: {
+            overall: oneOf(music.overall, ["keep_original", "recreate_under_narration", "optional", "none"], "optional"),
+            reason: asString(music.reason),
+            volume_guidance: asString(music.volume_guidance)
+        },
+        captions: {
+            overall: oneOf(captions.overall, ["reuse_existing", "retime_to_new_narration", "optional", "none"], "optional"),
+            reason: asString(captions.reason),
+            animation_dependency: asString(captions.animation_dependency)
+        },
+        visual_rebuild: {
+            default_strategy: oneOf(visualRebuild.default_strategy, ["ai_images_with_ken_burns", "real_footage", "mixed"], "mixed"),
+            reason: asString(visualRebuild.reason)
+        },
+        viral_dna: {
+            must_keep: asStringArray(viralDna.must_keep),
+            flexible: asStringArray(viralDna.flexible),
+            do_not_change: asStringArray(viralDna.do_not_change)
+        }
+    };
+}
 function normalizeViralDna(value) {
     if (!value || typeof value !== "object")
         return DEFAULT_VIRAL_DNA;
@@ -1834,6 +1970,7 @@ function normalizeViralDna(value) {
         retention: asString(record.retention),
         payoff: asString(record.payoff),
         emotional_punch: normalizeEmotionalPunch(record.emotional_punch ?? record.emotionalPunch),
+        static_vs_pivot: normalizeStaticVsPivot(record.static_vs_pivot ?? record.staticVsPivot),
         preserve: asStringArray(record.preserve),
         avoid: asStringArray(record.avoid),
         promotions: asStringArray(record.promotions),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.20.5",
+  "version": "0.20.6",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {