videodraft 0.7.1 → 0.9.0

package/dist/index.js

@@ -24,8 +24,8 @@ function readVersionFromDisk() {
   }
 }
 function resolveVersion() {
-  if ("0.7.1") {
-    return "0.7.1";
+  if ("0.9.0") {
+    return "0.9.0";
   }
   return readVersionFromDisk();
 }
@@ -1262,7 +1262,13 @@ function registerAccountCommands(program) {
   ).option("--resolution <res>", 'e.g. "720p", "1080p", "1K", "2K"').option("--quality <tier>", 'e.g. "standard", "pro", "fast"').option(
     "--rendering-speed <tier>",
     'image speed/cost tier, e.g. Ideogram V4 "Turbo"/"Balanced"/"Quality"'
-  ).option("--audio", "include native model audio in the estimate").option("--no-audio", "exclude native model audio").option("--num <n>", "image batch size").action(async function(model) {
+  ).option("--audio", "include native model audio in the estimate").option("--no-audio", "exclude native model audio").option(
+    "--ref-images <n>",
+    "input/reference image count for MiniMax H3 or Grok 1.5"
+  ).option(
+    "--ref-video-seconds <seconds>",
+    "MiniMax H3 combined reference-video duration"
+  ).option("--num <n>", "image batch size").action(async function(model) {
     const ctx = buildContext(this);
     const opts = this.opts();
     const result = await ctx.client.callTool(
@@ -1277,6 +1283,8 @@ function registerAccountCommands(program) {
         quality: opts.quality,
         rendering_speed: opts.renderingSpeed,
         generate_audio: opts.audio,
+        reference_image_count: opts.refImages ? Number(opts.refImages) : void 0,
+        reference_video_duration_seconds: opts.refVideoSeconds ? Number(opts.refVideoSeconds) : void 0,
         num_images: opts.num ? Number(opts.num) : void 0
       })
     );
@@ -2062,6 +2070,26 @@ function parseSegments(values) {
     return { prompt, duration };
   });
 }
+function parseKeyframes(values) {
+  return values.map((value) => {
+    const separator = value.lastIndexOf("@");
+    if (separator <= 0 || separator === value.length - 1) {
+      throw new CliError(
+        `--keyframe expects "<url|file>@<seconds>", got: ${value}`,
+        EXIT.USAGE
+      );
+    }
+    const source = value.slice(0, separator).trim();
+    const timeSeconds = Number(value.slice(separator + 1));
+    if (!source || !Number.isFinite(timeSeconds) || timeSeconds < 0) {
+      throw new CliError(
+        `--keyframe "${value}" must be "<url|file>@<seconds>" with a non-negative time.`,
+        EXIT.USAGE
+      );
+    }
+    return { source, time_seconds: timeSeconds };
+  });
+}
 function optionalPositiveNumber(value, label, integer = false) {
   if (value === void 0) return void 0;
   const parsed = Number(value);
@@ -2119,6 +2147,8 @@ async function printEstimate(ctx, params) {
       quality: params.quality,
       rendering_speed: params.renderingSpeed,
       generate_audio: params.audio,
+      reference_image_count: params.referenceImageCount,
+      reference_video_duration_seconds: params.referenceVideoDurationSeconds,
       num_images: params.num
     })
   );
@@ -2268,18 +2298,26 @@ function registerGenerateCommands(program) {
     "Generate a video clip (async; per-second pricing, see --estimate)"
   ).option(
     "--model <id>",
-    "video model id (task-aware when omitted; usually Gemini Omni Flash, Seedance 2 for longer/mixed-reference work)"
-  ).option("--ar <ratio>", 'aspect ratio, e.g. "16:9", "9:16"').option("--duration <seconds>", "clip duration in seconds").option("--resolution <res>", 'e.g. "480p", "720p", "1080p", "4k"').option(
+    "video model id (task-aware when omitted; Grok 1.5 supports text, first frame, or 1-7 image refs)"
+  ).option("--ar <ratio>", 'aspect ratio, e.g. "16:9", "9:16"').option("--duration <seconds>", "clip duration in seconds").option("--resolution <res>", 'e.g. "480p", "720p", "1080p", "2K", "4k"').option(
     "--quality <tier>",
     'e.g. "mini", "fast", "standard", "quality", "pro"'
   ).option("--audio", "generate native model audio").option("--no-audio", "disable native model audio").option("--start-image <url|file>", "start frame (image-to-video)").option("--end-image <url|file>", "end frame (supported models only)").option("--ref <url|file>", "reference image (repeatable)", collect, []).option(
     "--ref-video <url|file>",
-    "reference video (repeatable; Gemini Omni Flash, Seedance 2, Wan 2.7, Kling/Wan Ref-Edit reference mode; local files uploaded)",
+    "reference video (repeatable; MiniMax H3, Gemini Omni Flash, Seedance 2, Wan 2.7, Kling/Wan Ref-Edit; local files uploaded)",
     collect,
     []
   ).option(
     "--ref-audio <url|file>",
-    "reference audio (repeatable; Seedance 2; local files uploaded)",
+    "reference audio (repeatable; MiniMax H3 or Seedance 2; local files uploaded)",
+    collect,
+    []
+  ).option(
+    "--ref-video-seconds <seconds>",
+    "combined reference-video duration for an exact MiniMax H3 --estimate"
+  ).option(
+    "--keyframe <url|file@seconds>",
+    "FLUX 3 keyframe pinned to a moment, e.g. shot.png@2.5 (repeatable, max 10; local files uploaded)",
     collect,
     []
   ).option(
@@ -2295,17 +2333,96 @@ function registerGenerateCommands(program) {
     const opts = this.opts();
     const prompt = promptWords.join(" ").trim();
     const duration = optionalPositiveNumber(opts.duration, "--duration");
+    const refVideoSeconds = optionalRangedNumber(
+      opts.refVideoSeconds,
+      "--ref-video-seconds",
+      0,
+      15
+    );
     const seed = optionalSeed(opts.seed);
+    if (opts.model === "grok-imagine-video-1.5") {
+      const referenceImageCount = Array.isArray(opts.ref) ? opts.ref.length : 0;
+      if (!prompt) {
+        throw new CliError(
+          "grok-imagine-video-1.5 requires a prompt.",
+          EXIT.USAGE
+        );
+      }
+      if (prompt.length > 4096) {
+        throw new CliError(
+          "grok-imagine-video-1.5 prompts must be 4096 characters or fewer.",
+          EXIT.USAGE
+        );
+      }
+      if (duration !== void 0 && (!Number.isInteger(duration) || duration < 1 || duration > 15)) {
+        throw new CliError(
+          "grok-imagine-video-1.5 --duration must be a whole second from 1 to 15.",
+          EXIT.USAGE
+        );
+      }
+      if (referenceImageCount > 7) {
+        throw new CliError(
+          "grok-imagine-video-1.5 accepts at most 7 --ref images.",
+          EXIT.USAGE
+        );
+      }
+      if (referenceImageCount > 0 && opts.startImage) {
+        throw new CliError(
+          "grok-imagine-video-1.5 cannot combine --ref images with --start-image.",
+          EXIT.USAGE
+        );
+      }
+      if (opts.endImage || (opts.refVideo?.length ?? 0) > 0 || (opts.refAudio?.length ?? 0) > 0 || (opts.segment?.length ?? 0) > 0 || opts.negative || opts.cameraFixed || opts.seed !== void 0 || opts.quality) {
+        throw new CliError(
+          "grok-imagine-video-1.5 does not support --end-image, --ref-video, --ref-audio, --segment, --negative, --camera-fixed, --seed, or --quality.",
+          EXIT.USAGE
+        );
+      }
+      if (opts.audio === false) {
+        throw new CliError(
+          "grok-imagine-video-1.5 always generates native audio; remove --no-audio.",
+          EXIT.USAGE
+        );
+      }
+      if (opts.startImage && opts.ar) {
+        throw new CliError(
+          "grok-imagine-video-1.5 first-frame mode derives aspect ratio from --start-image; remove --ar.",
+          EXIT.USAGE
+        );
+      }
+      if (opts.ar && !["16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16"].includes(opts.ar)) {
+        throw new CliError(
+          "grok-imagine-video-1.5 --ar must be 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, or 9:16.",
+          EXIT.USAGE
+        );
+      }
+      if (opts.resolution && !["480p", "720p", "1080p"].includes(opts.resolution)) {
+        throw new CliError(
+          "grok-imagine-video-1.5 --resolution must be 480p, 720p, or 1080p.",
+          EXIT.USAGE
+        );
+      }
+      if (referenceImageCount > 0 && opts.resolution === "1080p") {
+        throw new CliError(
+          "grok-imagine-video-1.5 reference mode supports only 480p or 720p.",
+          EXIT.USAGE
+        );
+      }
+    }
     if (opts.estimate) {
       const estimateModel = estimateVideoModel(opts, duration);
-      const estimateDuration = duration ?? (!opts.model && estimateModel === "google-veo3.1" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? 8 : 6 : void 0);
+      const estimateReferenceImageCount = estimateModel === "minimax-h3" ? Array.isArray(opts.ref) ? opts.ref.length : 0 : estimateModel === "grok-imagine-video-1.5" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? opts.ref.length : opts.startImage ? 1 : 0 : void 0;
+      const estimateReferenceVideoDuration = estimateModel === "minimax-h3" ? Array.isArray(opts.refVideo) && opts.refVideo.length > 0 ? refVideoSeconds : 0 : void 0;
+      const estimateDuration = duration ?? (estimateModel === "grok-imagine-video-1.5" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? 8 : 6 : !opts.model && estimateModel === "google-veo3.1" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? 8 : 6 : void 0);
       await printEstimate(ctx, {
         model: estimateModel,
         type: "video",
         duration: estimateDuration,
         resolution: opts.resolution,
         quality: opts.quality,
-        audio: opts.audio
+        audio: opts.audio,
+        referenceImageCount: estimateReferenceImageCount,
+        referenceVideoDurationSeconds: estimateReferenceVideoDuration
       });
       return;
     }
@@ -2317,7 +2434,17 @@ function registerGenerateCommands(program) {
       opts.endImage ? resolveRefs(ctx, [opts.endImage]).then((r) => r[0]) : void 0
     ]);
     const segments = parseSegments(opts.segment ?? []);
-    if (!prompt && segments.length === 0 && !startImage && refVideos.length === 0) {
+    const parsedKeyframes = parseKeyframes(opts.keyframe ?? []);
+    const keyframes = parsedKeyframes.length > 0 ? await resolveRefs(
+      ctx,
+      parsedKeyframes.map((keyframe) => keyframe.source)
+    ).then(
+      (urls) => parsedKeyframes.map((keyframe, index) => ({
+        image_url: urls[index],
+        time_seconds: keyframe.time_seconds
+      }))
+    ) : [];
+    if (!prompt && segments.length === 0 && !startImage && keyframes.length === 0 && refVideos.length === 0) {
       throw new CliError(
         "Provide a prompt, --segment (multi-prompt), or --start-image.",
         EXIT.USAGE
@@ -2414,6 +2541,7 @@ function registerGenerateCommands(program) {
         reference_videos: refVideos.length > 0 ? refVideos : void 0,
         reference_audio: refAudios.length > 0 ? refAudios : void 0,
         multi_prompt: segments.length > 0 ? segments : void 0,
+        keyframes: keyframes.length > 0 ? keyframes : void 0,
         negative_prompt: opts.negative,
         camera_fixed: opts.cameraFixed ? true : void 0,
         seed,
@@ -2594,8 +2722,7 @@ function registerGenerateCommands(program) {
       (o) => {
         for (const url of urls) process.stdout.write(`${url}
 `);
-        for (const f of downloaded ?? [])
-          note(o, fmt.dim(o, savedLine(f)));
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
       }
     );
   });
@@ -2657,8 +2784,7 @@ function registerGenerateCommands(program) {
       (o) => {
         for (const url of urls) process.stdout.write(`${url}
 `);
-        for (const f of downloaded ?? [])
-          note(o, fmt.dim(o, savedLine(f)));
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
       }
     );
   });
@@ -2690,8 +2816,7 @@ function registerGenerateCommands(program) {
       (o) => {
         for (const url of urls) process.stdout.write(`${url}
 `);
-        for (const f of downloaded ?? [])
-          note(o, fmt.dim(o, savedLine(f)));
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
       }
     );
   });
@@ -2742,8 +2867,7 @@ function registerGenerateCommands(program) {
       (o) => {
         for (const url of urls) process.stdout.write(`${url}
 `);
-        for (const f of downloaded ?? [])
-          note(o, fmt.dim(o, savedLine(f)));
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
       }
     );
   });
@@ -2785,8 +2909,7 @@ function registerGenerateCommands(program) {
       (o) => {
         for (const url of urls) process.stdout.write(`${url}
 `);
-        for (const f of downloaded ?? [])
-          note(o, fmt.dim(o, savedLine(f)));
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
       }
     );
   });
@@ -2840,8 +2963,7 @@ function registerGenerateCommands(program) {
       (o) => {
         for (const url of urls) process.stdout.write(`${url}
 `);
-        for (const f of downloaded ?? [])
-          note(o, fmt.dim(o, savedLine(f)));
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
       }
     );
   });
@@ -2875,8 +2997,7 @@ function registerGenerateCommands(program) {
       (o) => {
         for (const u of urls) process.stdout.write(`${u}
 `);
-        for (const f of downloaded ?? [])
-          note(o, fmt.dim(o, savedLine(f)));
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
       }
     );
   });
@@ -3871,8 +3992,8 @@ function bundledSkillDir() {
   throw new CliError("Bundled skill not found (package is missing skills/videodraft).");
 }
 function bundledSkillFiles() {
-  if ('{"SKILL.md":"---\\nname: videodraft\\ndescription: Create and edit AI videos, images, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers the cloud `videodraft` CLI/MCP and local headless `videodraft_editor` MCP. When the editor MCP is exposed, prefer it for production, timeline assembly, and export; use cloud production/export only when explicitly requested or the editor is unavailable.\\n---\\n\\n# VideoDraft\\n\\nVideoDraft is an AI video creation platform where asset generation is the priority lane:\\n\\n- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.\\n- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.\\n- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane whenever `videodraft_editor` is available.\\n- **Hosted project production**: idea \u2192 script \u2192 storyboard \u2192 hosted production timeline \u2192 exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.\\n\\n## How to connect\\n\\nCloud generation has two equivalent surfaces (same backend, credits, and hosted projects). Native timeline editing is a separate local surface:\\n\\n1. **CLI** (preferred when you have a shell): run `videodraft` if it\'s on PATH; otherwise `npx -y videodraft@latest` runs it with no install (needs Node \u226520; the `-y` skips npx\'s install prompt so it runs non-interactively; the package is fetched on first use and cached). For heavy use, `npm install -g videodraft`. If there\'s no Node/shell here but the MCP connector below is available, use that instead; if neither works, tell the user how to install (https://videodraft.ai/cli).\\n   - Auth \u2014 pick by context, don\'t guess:\\n     \u2022 INTERACTIVE (a human is in the session, e.g. Claude Code / Codex): on exit code 3 (\\"not authenticated\\"), tell the user to run `videodraft login` in their terminal \u2014 it opens their browser for a one-click VideoDraft sign-in (OAuth), no key to copy. Wait for them to confirm it succeeded, then retry the command. This is the preferred path when the user is present.\\n     \u2022 HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).\\n     \u2022 SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat \u2014 use browser `login` or the env var so the token never lands in the transcript.\\n   - Every command accepts `--json` (parse this, don\'t scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (\u2192 tell the user, don\'t retry).\\n   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.\\n   - Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft upload`, and `videodraft download`.\\n   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args \'<json>\'`.\\n2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly \u2014 the CLI\'s curated commands map 1:1 onto these tools.\\n3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export. Inside VideoDraft ADE on a supported Mac, Claude and Codex receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_control` (`list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.\\n\\nNative editor mutations are revision-guarded. Send them serially and carry forward each result\'s fresh revision. See [references/editor.md](references/editor.md) for project selection, media import, timing units, mutation deltas, verification, export, and the `videodraft-editor` terminal bridge.\\n\\nIf you are reading this skill through `videodraft skills show skill`, run `videodraft skills show editor` before native editor work to load that reference.\\n\\n**VideoDraft ADE routing rule:** the presence of `videodraft_editor` means the native editor is ready, even when no editor window is visible. Use cloud tools to generate or source assets and, when helpful, scripts or storyboards. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` by default. Import the assets into the native project, assemble there, and call native `export_start`. Use hosted production/export only when the user explicitly asks for the web workflow or the native editor tools are unavailable. Do not silently fall back to hosted production after a native tool error.\\n\\n## First decision: asset, hosted project, or native edit?\\n\\n- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.\\n  - `videodraft generate image \\"a red fox in snow, cinematic\\" --ar 16:9 --download ./out/`\\n  - `videodraft generate video \\"slow dolly over a misty lake\\" --model gemini-omni-flash --duration 6 --download ./out/`\\n- **Any final video, production timeline, existing footage, local `.vdproject`, or hands-on edit**: use `videodraft_editor` when available. List or open the intended local project, or create a native project for a new production. The editor can work without showing its UI.\\n- **A small set of related assets**: still stay in the asset lane. Use an AI Studio session if you need to group related generations. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.\\n- **A generated multi-scene video / ad / explainer**: when the editor is available, use hosted tools only for any needed script, storyboard, shot planning, or generated assets; stop before hosted production, import the assets, and build/export the native timeline. A hosted project is optional unless the user wants the web project or its storyboard workflow.\\n- **A hosted web project or hosted export**: use the hosted pipeline only when the user explicitly asks for it or the native editor is unavailable.\\n- **Just a script** (no video asked for): A script-only request creates a script-stage project but stops at the script. Use `videodraft create \\"...\\" --script-only`; do not build a storyboard the user didn\'t ask for.\\n- **Iterating on existing work**: identify the surface first. Use `project_control` with `action:\'list\'` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.\\n\\n## Choose the model from the task\\n\\nIf the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.\\n\\n**Images:**\\n\\n- `nano-banana-2`: general default, editing, consistency, and references.\\n- `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.\\n- `gpt-image-2`: posters, logos, signs, title cards, readable text, or precise composition/editing.\\n\\n**Videos:**\\n\\n- `gemini-omni-flash`: general default up to 10s, first frame/image references, or editing one source video without extra media references. Fixed 720p with audio.\\n- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. Use `mini` for cost, `fast` for speed, `standard` for quality or 1080p/4K.\\n- `kling-v3-turbo`: fast polished 3-15s with first frame, multi-prompt, and audio. `kling-o3`: image references, first/last frames, multi-prompt, audio control, or 4K. `kling-3.0`: similar without reference-image mode.\\n- Existing-video edits use `videodraft edit video`, not generic generation. Choose from the `video_edit` catalog category: Grok for simple prompt edits, Wan 2.7 for one style reference or source-matching duration, Happy Horse for up to 5 references, and Kling O3 for controlled reference-image edits.\\n- Kling O3 and Wan 2.7 Ref/Edit also have reference-generation modes. Use `videodraft generate video --model <ref-edit-id>` with `--ref-video`/`--ref` to generate a new guided clip; use `videodraft edit video` when changing the source itself.\\n- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.\\n- Use Veo 3.1 when explicitly requested or as a fallback.\\n\\n**Audio and utilities:**\\n\\n- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and settles at 19 credits per actual minute, with up to 38 credits reserved during generation. The CLI automatically retries transient responses with one operation key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- Prefer ElevenLabs for voiceover, dialogue, voice changing, dubbing, and sound effects. Honor an explicitly selected supported TTS voice/provider. Use Lyria for instrumental music and ElevenLabs Music for vocals, lyrics, or exact timing.\\n- Talking head/presenter: choose by source. Use managed `avatar create` then `avatar render` when the user wants a reusable avatar record and bundled speech. Use `avatar fabric` for a one-off portrait plus text or existing audio. Use `avatar lipsync` when both the source video and replacement audio already exist.\\n- Enhancement: use Topaz image/video upscaling only when the content is already correct. Use image 1x for cleanup, 2x by default, 4x when justified; use video 2x by default. Edit or regenerate creative errors.\\n\\nSee [references/models.md](references/models.md) for the detailed routing table and exact capability limits.\\n\\n## Prefer references when continuity matters\\n\\nPure text-to-image or text-to-video is fine for a generic one-off asset. When a specific character, product, location, style, composition, or brand identity must survive generation, use references instead of hoping the prompt recreates it.\\n\\n- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.\\n- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.\\n- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the native editor instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.\\n\\n## Cost and credits\\n\\nDo not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.\\n\\nFor expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user\'s confirmation preference for the session.\\n\\n`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` lists TTS voices. Consult them instead of guessing capabilities.\\n\\n## Async jobs\\n\\nImage/video generation is asynchronous: commands submit a job and **wait by default**, printing output URLs (and saving files with `--download`). Large downloaded images also get a downscaled copy in `previews/` next to them (the `preview` field / \\"inspect via preview\\" line in the output) \u2014 **look at the preview, deliver the original**; viewing full-resolution images bloats the chat permanently. In scripts/CI prefer explicit control:\\n\\n```bash\\nJOB=$(videodraft generate image \\"...\\" --no-wait --json | jq -r .job_id)\\nvideodraft wait \\"$JOB\\" --download \\"./outputs/{job_id}_{index}.{ext}\\" --json\\n```\\n\\nFor MANY jobs: submit each with `--no-wait`, collect ALL with one command \u2014 `videodraft wait <id1> <id2> ...` polls every job from one process with one batched request per tick. Do NOT spawn parallel `wait`/`generate --wait` processes for a batch.\\n\\nIf a wait times out, the job is still running server-side \u2014 `videodraft status <job_id>` later. Never re-submit just because a wait timed out (that double-spends credits).\\n\\n## Local files and reference images\\n\\nReference inputs must be public URLs. The CLI uploads local files automatically wherever a URL is expected (`--ref photo.jpg`, `--start-image frame.png`), or explicitly:\\n\\n```bash\\nURL=$(videodraft upload ./product.png --json | jq -r .url)\\n```\\n\\nNever silently drop a reference you couldn\'t upload \u2014 stop and tell the user. Never upload a user\'s file to a third-party host.\\n\\nWhen the user attaches media for a native production, import actual footage into the editor by default. For hosted generation/storyboarding, classify each item before acting: a recurring **visual asset** (character/product/location/style), actual **footage to place as shots**, or **inspiration only**. See [references/pipeline.md](references/pipeline.md) for the hosted role mapping.\\n\\n## Showing media to the user\\n\\nGenerated media is **not** displayed in the chat automatically \u2014 you decide what to show. To preview an asset inline, save it locally (use `--download` so it lands under `media/`) and reference its **local path** as a Markdown link with a **leading `./`**:\\n\\n```\\n[ferrari shot](./media/ferrari_01.png)     \u2190 image card\\n[the clip](./media/clip.mp4)               \u2190 video player\\n[voiceover](./media/vo.mp3)                \u2190 audio player\\n```\\n\\nPut the Markdown link **in your message text** \u2014 video and audio embed exactly like images. Do **not** use `SendUserFile` (or other file-send tools) to display media: that renders inside a collapsible tool card and gets buried in the tool list. The Markdown link in your prose is what produces the inline card.\\n\\nUse the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or `./<any-folder>/clip.mp4` \u2014 any folder in the workspace works), or the **absolute** path for a file outside the workspace (e.g. `/Users/you/Desktop/clip.mp4` or another workspace\'s path). Both render. Show the finished results worth showing (and only those \u2014 not every intermediate job). A bare CDN URL or a JSON dump of output URLs does **not** render; the local-path Markdown link is what produces an inline card.\\n\\n## Native-first VideoDraft ADE pipeline (idea \u2192 MP4)\\n\\nWhen `videodraft_editor` is present:\\n\\n1. Generate or source the script, storyboard, shot images, clips, voiceovers, music, and other assets through the cloud CLI/MCP as needed.\\n2. Call native `project_control` to open or create the `.vdproject`.\\n3. Call native `media_import`, wait for imports to become ready, then assemble and refine the timeline with editor tools.\\n4. Call native `export_start` and use `export_status` for progress and results.\\n\\nDo not run the hosted production or export steps in this path unless the user explicitly asks for a web production.\\n\\n## Hosted fallback pipeline (idea \u2192 MP4)\\n\\nUse this only when there is NO native editor at all, or the user explicitly requests the hosted web\\nworkflow. The native surface is not only the injected `videodraft_editor` MCP: a `videodraft-editor`\\nexecutable on PATH is the same editor reached through its terminal bridge, and\\n[references/editor.md](references/editor.md) covers driving it that way. Treating a missing MCP as\\n\\"no editor\\" sends sessions that have the binary into hosted production for no reason.\\n\\n```bash\\nvideodraft create \\"<idea>\\" --ar 9:16            # project: script \u2192 visual assets \u2192 storyboard\\nvideodraft shots <project_id> --grid --estimate # cost preview, confirm with user\\nvideodraft shots <project_id> --grid            # batch shot images (waits, writes onto shot cards)\\nvideodraft produce <project_id>                 # voiceovers + captions + production timeline\\nvideodraft export <project_id> --download final.mp4\\n```\\n\\nOptional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music \\"...\\" --attach <project_id>`), and standalone audio assets (`generate audio`, `generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).\\n\\n## Avatar and talking-head videos (both surfaces)\\n\\nAvatar generation is cloud-only \u2014 the native editor has no avatar or lipsync tools \u2014 so this applies whether or not `videodraft_editor` is present. Generate the avatar in the cloud; in VideoDraft ADE, import the rendered clip and cut it on the native timeline like any other footage.\\n\\nAvatar/talking-head videos use dedicated commands. For a reusable managed avatar, obtain or generate a clear portrait \u2192 `videodraft avatar script` when needed \u2192 `videodraft avatar create` \u2192 `videodraft avatar render --resolution 720p`. For a one-off portrait, use `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.\\n\\n## Working with hosted project data\\n\\nA hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` \u2014 objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace native editor tools when `videodraft_editor` is available for the production itself.\\n\\n## More\\n\\n- [references/pipeline.md](references/pipeline.md) \u2014 hosted fallback data model and production workflow\\n- [references/editor.md](references/editor.md) \u2014 native headless editor routing, project selection, import, timeline edits, verification, and export\\n- [references/models.md](references/models.md) \u2014 choosing image/video models, pricing patterns, voices and styles\\n- [references/examples.md](references/examples.md) \u2014 recipes: batch product videos from a CSV, talking-head from a script, changelog video in CI\\n","references/editor.md":"# Native VideoDraft Editor reference\\n\\nUse this reference when the user wants to assemble, cut, caption, mix, lay out, inspect, or export a local VideoDraft Editor project. The native editor is deterministic and local. Cloud generation remains in the `videodraft` CLI or hosted MCP.\\n\\n## VideoDraft ADE preference rule\\n\\nWhen `videodraft_editor` tools are exposed, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.\\n\\nUse cloud tools for asset generation and optional script/storyboard work, then import the results. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` unless the user explicitly requests an editable web production or the native editor tools are unavailable. If a native tool call fails after the editor was available, report or recover that native failure rather than silently switching surfaces.\\n\\n## Choose the correct surface\\n\\n- `videodraft` and the hosted VideoDraft MCP generate assets and can manage hosted web projects. They use the user\'s VideoDraft account and credits. In VideoDraft ADE, use them mainly as the source of generated media and optional storyboards for the native production.\\n- `videodraft_editor` edits local `.vdproject` packages. It has no generation, account, model, or credit tools.\\n- Inside VideoDraft ADE on a supported Mac, the editor MCP is injected automatically for Claude and Codex in both Code and VideoDraft modes. It starts headlessly before the chat opens. The user does not need to click Open Editor, and closing or hiding the editor window does not stop headless editing.\\n- Outside that environment, use the editor only if `videodraft_editor` MCP tools are already exposed or the `videodraft-editor` executable is on PATH. Do not confuse the public `videodraft` cloud CLI with the separate native editor executable.\\n\\nPrefer the direct MCP tools when they are available. The terminal bridge is useful for scripts, diagnostics, or an agent session where the MCP was not injected.\\n\\n## Start with the intended project\\n\\nAn MCP session can begin without a project selected. Project selection belongs to the session, not to whichever editor window happens to be frontmost.\\n\\n1. If the user named an existing project but its identity is unclear, call `project_control` with `action:\'list\'`.\\n2. Open the exact project by the returned `id`, unambiguous `name`, or `.vdproject` `path`.\\n3. Create only when the user wants a new local edit. `action:\'create\'` accepts optional `name`, `fps`, `aspectRatio`, and `quality`.\\n4. Treat `isActive` as this MCP session\'s target and `isVisible` as the project shown in the UI. Headless editing only needs the session target.\\n5. Use `action:\'close\'` only when closing is part of the task. It saves first and never deletes the project.\\n\\nDo not substitute a hosted project ID for a native project. A hosted project can supply scripts, storyboards, and generated media, but the native edit is a separate `.vdproject` package.\\n\\n## Keep a reliable editing model\\n\\n- Call `timeline_read` once after opening or creating a project, after switching timelines, or after an out-of-band user edit. It returns the revision and current clip/track state.\\n- Call `media_list` before using a `mediaRef`. Poll imports with a filtered read (`ids` for a known asset, `pending:true` for a batch) instead of repeatedly loading the full library.\\n- Timeline placement uses project frames. Source spans, media durations, transcript segments, and search hits use seconds. Pass those values to the relevant tools as returned; do not multiply by fps yourself.\\n- IDs are short stable prefixes. Pass them back exactly as returned. Tracks use stable `trackId` values; indexes can change.\\n- Send project mutations serially. Pass `ifRevision` from the latest read or mutation when available, then replace it with the fresh revision from the next result. Parallel edits against one project can race or invalidate each other\'s revision.\\n- Every mutation returns a delta in `timeline_read` vocabulary. Patch your working model from that delta instead of re-reading after every successful call. Re-read after a stale-state failure or an out-of-band change.\\n- Use `canvas_arrange` for split screens, picture-in-picture, grids, and canvas placement. Use `tracks_edit` to fix stacking. Do not synthesize layouts from generic transforms or keyframes.\\n- Use `media_view` before describing source content, and `transcript_read` to locate a spoken moment. Use `timeline_view` to verify the composited result the viewer will actually see.\\n- Volume inputs, including volume keyframes, are linear values from `0` to `1`. Timeline reads return the same linear scale.\\n\\n## Bring generated or local media into the editor\\n\\nUse cloud generation for new assets, save or download the outputs, then call native `media_import`:\\n\\n- `source.path`: absolute local file or directory. A directory imports recursively and preserves its folder structure.\\n- `source.url`: HTTPS asset URL. Set `mimeType` when a signed URL has no usable extension.\\n- `source.bytes`: small base64 media with a required `mimeType`.\\n- `source.matte`: generated solid-color image.\\n\\nReadiness differs by source, and so does the poll that detects it:\\n\\n- **URL and single-file path** imports return `status:\'downloading\'` with one `mediaRef`. Poll `media_list` with `ids:[mediaRef]` until `generationStatus` is absent.\\n- **Directory** imports return `status:\'preparing\'` once the batch is registered \u2014 not ready. A batch has no single `mediaRef` to poll by, so poll `media_list` with `pending:true` until it reports no unresolved imports.\\n- **Inline bytes and matte** imports finish inline and come back `status:\'ready\'`; no polling needed.\\n\\nNever place a pending asset on the timeline. `generationStatus` is the signal: `preparing` and\\n`downloading` mean keep polling, absent means usable, and **`failed` is terminal** \u2014 report it or\\nretry the import explicitly, never poll on. Do not treat \\"not downloading\\" as ready.\\n\\nFor a batch of local outputs, download them into one workspace directory and import that directory once when practical. This is safer and faster than racing many import calls; just remember it is the `pending:true` poll that tells you when the batch is usable.\\n\\n## Edit and verify\\n\\nUse the tool descriptions as the exact schema. A dependable sequence is:\\n\\n1. `project_control` to select or create the local project.\\n2. `timeline_read` and `media_list` to establish current state.\\n3. `media_view` when content selection matters.\\n4. Serialized clip, track, layout, text, caption, audio, color, effect, or cut mutations using the current revision.\\n5. `timeline_view` when visual composition or layer order matters.\\n6. `undo` if the requested result is wrong and the next mutation would not cleanly correct it.\\n\\nEdits are undoable. Do not ask for confirmation before each ordinary edit. Ask one focused question only when the user\'s creative direction is materially ambiguous.\\n\\n## Export\\n\\n`export_start` queues work in the background and returns a `jobId`, destination, and `started` or `queued` status.\\n\\n- Use `video` for H.264, H.265, or ProRes.\\n- Use `xml` for Premiere Pro.\\n- Use `xml` (XMEML) for Premiere Pro **and DaVinci Resolve** \u2014 Resolve reads XMEML natively.\\n  Use `fcpxml` only for Final Cut Pro. Sending Resolve an FCPXML produces a package it cannot\\n  open cleanly, so the target matters more than the file extension suggests.\\n- Use `videodraft` for a self-contained project package.\\n- Omit `outputPath` unless the user named a destination; the default is `~/Downloads`.\\n- Use `export_status` to list progress, warnings, and results. Cancel only when the user asks or the just-queued settings were wrong. Do not infer that an export is stuck from elapsed time alone.\\n\\n## Terminal bridge\\n\\nVideoDraft desktop terminals expose `videodraft-editor`, which controls the same process and MCP surface:\\n\\n```bash\\nvideodraft-editor status\\nvideodraft-editor list-tools\\nvideodraft-editor tool project_control --json \'{\\"action\\":\\"list\\"}\'\\nvideodraft-editor tool timeline_read --json \'{}\'\\nvideodraft-editor show\\nvideodraft-editor hide\\n```\\n\\nControl and tool commands auto-start a headless editor if none is running. `show` only reveals the already-running UI. Use `videodraft-editor tool <name> --json -` to read a JSON object from stdin when shell quoting would be fragile. Never read, copy, or expose the editor\'s rotating local authentication secret.\\n","references/examples.md":"# Recipes\\n\\nWorking patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.\\n\\nInside VideoDraft ADE, if a native editor is available, use these recipes for asset generation and\\noptional script/storyboard stages. Hand the results to the editor for production and export ONLY\\nwhen the deliverable the user asked for is a composed production. A standalone output \u2014 the batch\\nproduct clips in recipe 1, the upscale in recipe 7 \u2014 is finished when it is generated; importing it\\ninto a project and exporting a timeline builds an edit nobody asked for. Recipes below that call `videodraft produce` or `videodraft export` are hosted fallbacks only. Do not choose them over the available native editor unless the user explicitly asks for the hosted web workflow.\\n\\n## 1. Batch product videos from a CSV\\n\\nOne 9:16 product clip per row of `products.csv` (`name,image_url,tagline`):\\n\\n```bash\\n#!/usr/bin/env bash\\nset -euo pipefail\\nmkdir -p outputs\\n\\nwhile IFS=, read -r name image tagline; do\\n  job=$(videodraft generate video \\\\\\n    \\"Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting.\\" \\\\\\n    --model gemini-omni-flash --ar 9:16 --duration 6 \\\\\\n    --start-image \\"$image\\" \\\\\\n    --no-wait --json | jq -r .job_id)\\n  echo \\"$name,$job\\" >> outputs/jobs.csv\\ndone < <(tail -n +2 products.csv)\\n\\n# Collect ALL results with ONE process (batched polling \u2014 one request per tick)\\nvideodraft wait $(cut -d, -f2 outputs/jobs.csv) \\\\\\n  --download \\"outputs/{job_id}_{index}.{ext}\\" --json > outputs/results.json\\n# map job ids back to product names via outputs/jobs.csv\\n```\\n\\nSubmit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Gemini Omni Flash is selected because these are six-second first-frame product clips. Estimate first: `videodraft costs gemini-omni-flash --type video --duration 6 --resolution 720p --audio` \xD7 rows, and confirm with the user.\\n\\n## 2. Hosted full marketing video from one idea (fallback)\\n\\n```bash\\nvideodraft create \\"30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette.\\" \\\\\\n  --ar 9:16 --style cinematic --json > project.json\\nPROJECT=$(jq -r .project_id project.json)\\n\\nvideodraft shots \\"$PROJECT\\" --grid --estimate          # show the user the cost; get a go-ahead\\nvideodraft shots \\"$PROJECT\\" --grid\\nvideodraft produce \\"$PROJECT\\"\\nvideodraft generate music \\"minimal ambient, warm pads, 60 BPM\\" --attach \\"$PROJECT\\"\\nvideodraft generate audio \\"Extend @Audio1 into a 20-second transition\\" --ref-audio ./intro.wav --format wav --download ./transition.wav\\nvideodraft export \\"$PROJECT\\" --download solace-launch.mp4\\n```\\n\\nUse this complete hosted path only when the user requested a web project or the native editor is unavailable. Otherwise stop after the storyboard/assets, import them into the native `.vdproject`, and export with `export_start`. The hosted project stays editable at the URL in `project.json` (`.urls`).\\n\\n## 3. Talking-head (avatar) video\\n\\nWhen the user has no portrait, generate a clear front-facing avatar image first. Skip this step when they supplied one or an existing character should be reused.\\n\\n```bash\\nvideodraft generate image \\\\\\n  \\"Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background\\" \\\\\\n  --model nano-banana-2 --ar 9:16 --download ./media/avatar.png\\n\\nSCRIPT=$(videodraft avatar script \\"why our espresso subscription saves you money\\" --style ad-style --json | jq -r .script)\\nAVATAR=$(videodraft avatar create ./media/avatar.png --script \\"$SCRIPT\\" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)\\nvideodraft avatar render \\"$AVATAR\\" --resolution 720p   # VEED Fabric paid step; confirm cost first (~20 credits/sec)\\n```\\n\\n`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.\\n\\nIf the portrait is low resolution, enhance it before `avatar create`:\\n\\n```bash\\nvideodraft upscale image ./founder-small.jpg --scale 2x --download ./media/founder-upscaled.png\\n```\\n\\nFor a one-off portrait animation without creating a managed avatar record:\\n\\n```bash\\nvideodraft avatar fabric ./founder.jpg \\\\\\n  --text \\"Welcome to the weekly product update.\\" \\\\\\n  --voice-description \\"warm, confident American presenter\\" \\\\\\n  --resolution 720p --download ./media/presenter.mp4\\n```\\n\\nWhen the user already has both the video and replacement speech:\\n\\n```bash\\nvideodraft avatar lipsync ./presenter.mp4 \\\\\\n  --audio ./localized-voiceover.mp3 \\\\\\n  --sync-mode loop --download ./media/presenter-localized.mp4\\n```\\n\\nEdit an existing video with a dedicated edit model:\\n\\n```bash\\nvideodraft models video --category video_edit\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Turn the room into a warm evening scene while preserving the product and camera motion\\" \\\\\\n  --model wan-2.7-ref-edit --ref ./evening-style.jpg \\\\\\n  --preserve-audio --download ./media/product-demo-evening.mp4\\n```\\n\\nTransfer motion from a reference clip onto a character image:\\n\\n```bash\\nvideodraft edit motion ./character.png \\\\\\n  \\"Apply the dancer\'s movement to this character while preserving identity\\" \\\\\\n  --motion-video ./dance-reference.mp4 \\\\\\n  --model kling-v3-motion-control --quality pro \\\\\\n  --download ./media/character-dance.mp4\\n```\\n\\n## 4. Hosted changelog video in CI\\n\\nIn a GitHub Action with `VIDEODRAFT_API_KEY` set as a secret:\\n\\n```bash\\nNOTES=$(git log --oneline v1.2.0..HEAD | head -20)\\nvideodraft create \\"Weekly product update video. Energetic, 20 seconds. Changes: ${NOTES}\\" --ar 16:9 --json > p.json\\nPROJECT=$(jq -r .project_id p.json)\\nvideodraft shots \\"$PROJECT\\" && videodraft produce \\"$PROJECT\\"\\nvideodraft export \\"$PROJECT\\" --download changelog.mp4 --wait-timeout 30m\\n```\\n\\n## 5. Variations and picking a winner\\n\\n```bash\\nvideodraft generate image \\"logo concept: minimalist fox, geometric\\" --num 4 --download \\"./concepts/{job_id}_{index}.{ext}\\" --json\\n# Show all 4 to the user; regenerate the chosen one at higher res:\\nvideodraft generate image \\"<same prompt>\\" --model nano-banana-pro --resolution 4K\\n```\\n\\n## 6. Reaching tools without a curated command\\n\\n```bash\\nvideodraft tools list --json | jq -r \'.[].name\'\\nvideodraft tools schema attach_media_to_shot --json\\nvideodraft call attach_media_to_shot --args \'{\\"project_id\\":\\"...\\",\\"scene_index\\":0,\\"shot_index\\":1,\\"media_url\\":\\"https://...\\",\\"media_type\\":\\"video\\",\\"duration_seconds\\":6}\'\\n```\\n\\nAnything the hosted VideoDraft MCP exposes, including character studio, product studio, and hosted project data, is reachable this way even before it gets a curated command. Native `.vdproject` editing uses the separate `videodraft_editor` MCP described in SKILL.md.\\n\\n## 7. Enhance an existing asset without changing it\\n\\n```bash\\n# Light image cleanup, no enlargement\\nvideodraft upscale image ./poster.png --scale 1x --download ./media/poster-enhanced.png\\n\\n# General image and video enlargement\\nvideodraft upscale image ./frame.png --scale 2x --download ./media/frame-2x.png\\nvideodraft upscale video ./clip.mp4 --scale 2x --download ./media/clip-2x.mp4\\n```\\n\\nUse these when the content is correct and only quality or resolution needs improvement. If the poster text, composition, subject, or motion is wrong, edit or regenerate instead.\\n","references/models.md":"# Choosing models (and predicting cost)\\n\\nAlways consult the live catalog instead of memorizing this page \u2014 models change weekly:\\n\\n```bash\\nvideodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)\\nvideodraft models video --json     # every video model + inputs + per-second pricing metadata\\nvideodraft models audio --json     # standalone audio/media models + pricing inputs\\nvideodraft models voices --json    # TTS voices\\nvideodraft models styles --json    # visual style presets\\n```\\n\\n## Task-based model selection\\n\\nHonor an explicitly named model when it supports the request. Otherwise choose from the task\'s inputs, duration, audio, quality, speed, and cost. Pass the chosen model explicitly instead of relying on a blind platform fallback.\\n\\n### Images\\n\\n| Need                                                                                   | Choose               | Why                                                               |\\n| -------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------- |\\n| Most generation, editing, character consistency, or reference work                     | `nano-banana-2`      | Best general default; 1K/2K/4K and up to 14 reference images      |\\n| Highest-quality complex generation or reasoning                                        | `nano-banana-pro`    | Premium Nano Banana quality and reasoning                         |\\n| Fast, inexpensive drafts and iteration                                                 | `nano-banana-2-lite` | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |\\n| Posters, title cards, signs, logos, or any image with important readable text          | `gpt-image-2`        | Strong text rendering; up to 16 image inputs and 1K/2K/4K output  |\\n| Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2`        | Strong non-Nano alternative with multi-image input                |\\n\\nUse `--num 1..4` for variations of one prompt in a single call. Never loop separate paid calls for variations that fit in one request.\\n\\n### Videos\\n\\n| Need                                                                                                       | Choose              | Important limits                                                                                    |\\n| ---------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |\\n| Most text, first-frame, image-reference, or source-video-edit requests up to 10s                           | `gemini-omni-flash` | 720p, 3-10s or auto, audio always on, up to 10 total image inputs, one source video                 |\\n| Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2`        | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only |\\n| Fast polished 3-15s video with first frame, multi-prompt, and native audio                                 | `kling-v3-turbo`    | Audio always on; Pro default; no end frame or reference-media mode                                  |\\n| Cinematic 3-15s with image references, first+last frame, multi-prompt, audio control, or 4K                | `kling-o3`          | Up to 7 image refs; Standard/Pro/4K; audio toggle                                                   |\\n| Kling 3-15s with first+last frame, multi-prompt, optional audio, or 4K, without reference-image mode       | `kling-3.0`         | Standard/Pro/4K; audio toggle                                                                       |\\n| User explicitly requests Veo, or the selected workflow specifically needs Veo                              | `google-veo3.1`     | Good fallback, but not the preferred general model                                                  |\\n\\nRouting rules:\\n\\n- Around 11-15 seconds with native audio: use Kling or Seedance, not Gemini.\\n- One existing source video that should be edited, with an output up to 10 seconds and no additional media references to preserve: use Gemini Omni Flash.\\n- Video or audio supplied as creative reference: use Seedance 2.0.\\n- A video plus any image/audio references that must all be preserved: use Seedance 2.0. Do not promise that Gemini will preserve mixed source media; its Fal BYOK edit mode accepts only the source video and prompt.\\n- First and last frame control: use Seedance, Kling O3, or Kling 3.0. Gemini supports a first frame but not a last frame.\\n- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.\\n- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.\\n- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K.\\n\\n### Video edit and motion-control categories\\n\\nUse `videodraft models video --category video_edit` for existing-video transforms and `--category motion_control` for motion transfer.\\n\\n| Need                                  | Command/model                                                         | Important limits                                                                 |\\n| ------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |\\n| Simple prompt edit of one video       | `videodraft edit video <video> \\"...\\" --model grok-imagine-video-edit` | No image refs; source truncated to 8s; auto/480p/720p                            |\\n| Edit with one style/reference image   | `--model wan-2.7-ref-edit --ref <image>`                              | One image ref; 2-10s or match source                                             |\\n| Edit with several image references    | `--model happy-horse-video-edit --ref ...`                            | Up to 5 refs; 720p/1080p; source capped at 15s                                   |\\n| Controlled Kling edit                 | `--model kling-o3-video-ref-edit --ref ...`                           | Up to 4 refs; Standard/Pro; source clamped to 3-10s                              |\\n| Transfer reference motion to an image | `videodraft edit motion <image> \\"...\\" --motion-video <video>`         | Kling V3 default; image orientation caps motion at 10s, video orientation at 30s |\\n\\nIf the user explicitly names one of these models, preserve it. The CLI uploads local source videos and reference images automatically. Editing returns an async job and waits by default.\\n\\nKling O3 and Wan 2.7 Ref/Edit are dual-mode cards. `videodraft edit video` uses edit mode. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. `--model wan-2.7-ref-edit` generates a new clip from one or more `--ref`/`--ref-video` inputs.\\n\\n### Reference-first video workflow\\n\\n- Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.\\n- If the user gives a reference, pass it. Never silently replace it with a text description.\\n- If no reference exists and continuity matters, generate a still first with the user\'s explicitly requested compatible image model, otherwise use Nano Banana 2. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.\\n- For multi-shot scenes, generate shot images with `videodraft shots <project_id> --model <selected-image-model> --grid`. Preserve an explicitly requested compatible image model; otherwise use `nano-banana-2`. The grid establishes the scene and characters together, then decodes into individual shot images.\\n- Animate the decoded shot images as per-shot start frames or references. Do not independently text-generate each video clip when the shots need to match.\\n- Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.\\n\\n### Audio\\n\\n- **Seed Audio 1.0**: use `videodraft generate audio` for open-ended speech, sound, music, or prompt-driven audio editing. It accepts up to three audio references or one image. Address audio references as `@Audio1`, `@Audio2`, and `@Audio3`. Preset and custom cloned voice IDs are supported. Output is up to 120 seconds. There is no requested-duration input. The CLI automatically retries transient responses with one idempotency key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- **Voiceover/TTS**: prefer ElevenLabs. Brittney is the platform default voice; under ElevenLabs BYOK, use a compatible voice from the user\'s account. Honor another supported voice/provider when the user explicitly selects it.\\n- **Dialogue, voice changing, and dubbing**: ElevenLabs only.\\n- **Sound effects**: ElevenLabs Sound Effects only.\\n- **Music**: use `lyria-3-clip-preview` for a short instrumental/background score, `lyria-3-pro-preview` for a longer or higher-quality instrumental score, and `elevenlabs-music` when vocals/lyrics or a specified 10-120 second length matter.\\n- Voice Changer and Dubbing require the source media duration and currently accept source media up to 300 seconds.\\n\\n### Avatar / talking head\\n\\nChoose the dedicated path from the media the user already has:\\n\\n| Starting media                            | Command                                                                   | Use                                                 |\\n| ----------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |\\n| Portrait + script, reusable avatar record | `videodraft avatar create <portrait> --script \\"...\\"` then `avatar render` | Managed avatar flow with bundled speech preparation |\\n| Portrait + text                           | `videodraft avatar fabric <portrait> --text \\"...\\"`                        | One-off direct VEED Fabric text mode                |\\n| Portrait + existing audio                 | `videodraft avatar fabric <portrait> --audio <audio>`                     | One-off direct VEED Fabric audio lip sync           |\\n| Existing video + existing audio           | `videodraft avatar lipsync <video> --audio <audio>`                       | Sync Labs Lipsync 2                                 |\\n\\nThe managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric and Sync Labs are paid AI Studio generations and return async job IDs.\\n\\n1. Obtain the avatar image. Prefer the user\'s supplied portrait or an existing character. If none exists, use the user\'s explicitly requested compatible image model, otherwise generate a front-facing head-and-shoulders portrait with `nano-banana-2`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.\\n2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.\\n3. Generate a script only if needed: `videodraft avatar script \\"<idea>\\"`.\\n4. Create the avatar record and speech: `videodraft avatar create <portrait-url-or-file> --script \\"...\\" --voice <id> --ar 9:16`. Prefer ElevenLabs when unspecified, but honor another explicitly selected supported voice/provider.\\n5. Render with VEED Fabric: `videodraft avatar render <avatar_video_id> --resolution 720p`.\\n\\nThe portrait is passed as the avatar\'s character image, not as a generic video\'s start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.\\n\\nDirect Fabric text/audio and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. Sync costs 5 credits per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.\\n\\n### Upscaling / enhancement\\n\\n- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The result is synchronous.\\n- **Videos**: Topaz via `videodraft upscale video <url-or-file> --scale 2x`. Use 2x by default. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.\\n- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems.\\n- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.\\n\\n## Capability gotchas\\n\\n- Each model\'s `inputs` block is authoritative: supported `aspect_ratios`, `resolutions`, `quality_options`, `start_frame`/`end_frame`, `max_reference_images/videos/audio`, `multi_prompt`, `audio_toggle`. Passing an unsupported input fails with a clear error \u2014 check first, don\'t trial-and-error paid calls.\\n- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.\\n- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4); everything else ignores it. You do not need a seed for variation \u2014 `--num` already varies.\\n- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost \u2014 pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.\\n- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.\\n- Reference inputs: `--ref <img>` (images), `--ref-video <v>` (Gemini Omni Flash, Seedance 2, Wan 2.7), `--ref-audio <a>` (Seedance 2). The CLI uploads local files for all of these, so you can pass a path or a URL. `--segment \\"<prompt>:<seconds>\\"` (repeatable) drives multi-prompt models (Kling 3.0 / 3.0 Turbo / O3); total 3-15s. `generate image --video-ref` is the nano-banana-2 video reference.\\n- The top-level prompt is OPTIONAL for `generate video` with multi-prompt models and for Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video \u2014 a `--segment`-only or `--start-image`-only call is valid. Every other model still needs a prompt; the server enforces per-model rules.\\n- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.\\n\\n## Cost model\\n\\n- Images: per image (\xD7 `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.\\n- Video: usually credits/second \xD7 duration; rate depends on model + resolution + quality + native audio on/off.\\n- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) \u2014 the largest single spend in the pipeline.\\n- VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.\\n- Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.\\n- Sync Labs Lipsync 2: 5 credits per verified audio second.\\n- Voiceover TTS: 10 credits per 1000 characters for standard voices, 30 per 1000 for cloned `custom-*` voices (min 1, pro-rated); applies to standalone voiceovers AND per-scene narration during `produce`. Silent tracks are free. Voice cloning itself is a flat 150 credits per clone.\\n- Lyria music: flat per track, 10 credits (clip) / 15 credits (pro).\\n- Seed Audio 1.0: 19 credits per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum of 38 credits and refunds the unused portion after generation. Fal BYOK is free.\\n- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. Voice changer and dubbing reject source media above 300s in the current synchronous flow.\\n- Upscales: priced by scale and source size.\\n\\nQuote before spending:\\n\\n```bash\\nvideodraft costs gemini-omni-flash --type video --duration 8 --resolution 720p --audio\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio\\nvideodraft costs elevenlabs-dubbing --type audio --duration 60\\nvideodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length\\nvideodraft costs elevenlabs-dialogue --type audio --chars 350\\nvideodraft costs voiceover --type audio --chars 800    # TTS: 10 cr / 1000 chars\\nvideodraft generate video \\"...\\" --model gemini-omni-flash --estimate # same quote, inline\\n```\\n","references/pipeline.md":"# VideoDraft pipeline reference\\n\\nEverything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks). When the local `videodraft_editor` MCP is available, do not use hosted production or export by default. Use hosted tools only for asset generation and optional script/storyboard stages, then import the results and finish with the native editor reference linked from SKILL.md. Continue through `produce_project` and `export_video` only when the user explicitly requests a hosted web production or the native editor is unavailable.\\n\\nUse direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable. Script-only uses a script-stage project and stops at the script. In VideoDraft ADE with editor tools present, stop before hosted production, import the generated assets, and build/export the native project.\\n\\n## Stages and their tools\\n\\n| Stage                                   | CLI                                                                         | Underlying tool                            |\\n| --------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------ |\\n| Idea \u2192 full storyboard project          | `videodraft create \\"<idea>\\"`                                                | `generate_storyboard_from_idea`            |\\n| Idea \u2192 script only (stop there)         | `videodraft create \\"<idea>\\" --script-only`                                  | `generate_script_from_idea`                |\\n| Footage IS the video                    | `videodraft call generate_storyboard_from_media`                            | `generate_storyboard_from_media`           |\\n| Batch shot images                       | `videodraft shots <project>`                                                | `generate_shot_images`                     |\\n| One shot image                          | `videodraft generate image --project <id> --scene N --shot M`               | `generate_image`                           |\\n| Produce (voiceover, captions, timeline) | `videodraft produce <project>`                                              | `produce_project`                          |\\n| Per-shot motion prompts                 | `videodraft video-prompts <project>`                                        | `generate_video_prompts`                   |\\n| Motion clip for a shot                  | `videodraft generate video --project <id>`                                  | `generate_video`                           |\\n| Attach a finished clip to the timeline  | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot`                     |\\n| Background music                        | `videodraft generate music --attach <project>`                              | `generate_music` / `set_background_music`  |\\n| General or reference-driven audio       | `videodraft generate audio \\"...\\"`                                          | `generate_audio`                           |\\n| Sound effect                            | `videodraft generate sound-effect \\"...\\"`                                    | `generate_sound_effect`                    |\\n| Dialogue audio                          | `videodraft generate dialogue --line \\"voice:text\\"`                          | `generate_dialogue`                        |\\n| Voice changer                           | `videodraft generate voice-changer <audio>`                                 | `change_voice`                             |\\n| Dubbing                                 | `videodraft generate dub <audio_or_video>`                                  | `dub_media`                                |\\n| Scene voiceover                         | `videodraft generate voiceover --project <id> --scene N`                    | `generate_voiceover`                       |\\n| Avatar script                           | `videodraft avatar script \\"<idea>\\"`                                         | `generate_avatar_script`                   |\\n| Avatar + speech                         | `videodraft avatar create <portrait> --script \\"...\\"`                        | `create_avatar_video`                      |\\n| Talking-head render                     | `videodraft avatar render <avatar_video_id>`                                | `render_avatar_video` + `get_avatar_video` |\\n| Direct portrait + text/audio            | `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`      | `generate_veed_fabric_video`               |\\n| Existing video + replacement audio      | `videodraft avatar lipsync <video> --audio <file>`                          | `generate_sync_lipsync_video`              |\\n| Existing-video AI edit                  | `videodraft edit video <video> \\"<change>\\" --model <video-edit-model>`       | `edit_video`                               |\\n| Motion transfer                         | `videodraft edit motion <image> \\"<direction>\\" --motion-video <video>`       | `generate_motion_control_video`            |\\n| Image enhancement/upscale               | `videodraft upscale image <image>`                                          | `upscale_image`                            |\\n| Video enhancement/upscale               | `videodraft upscale video <video>`                                          | `upscale_video`                            |\\n| Final MP4                               | `videodraft export <project>`                                               | `export_video` + `check_export_status`     |\\n\\n## Rules that prevent broken results\\n\\n- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don\'t call `generate_storyboard_scenes` with a raw idea as the \\"script\\".\\n- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project\'s visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project\'s visual assets and/or the previous shot\'s image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.\\n- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.\\n- **Hold off generating shot images while the user is still iterating** on storyboard structure.\\n- **produce \u2192 export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.\\n- **Do not attach motion clips before production exists**: run `produce` successfully first, then attach finished motion clips to the production timeline. Attaching before `production_data` exists cannot place them in the final timeline.\\n- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:\\"video\\"`, include `duration_seconds`) \u2014 it replaces the production timeline clip while keeping the storyboard still.\\n- **Talking heads use dedicated avatar tools**: do not use `generate video`. Use managed `avatar create` and `avatar render` for reusable avatars, direct `avatar fabric` for a portrait plus text/audio, and `avatar lipsync` for an existing video plus replacement audio. Reuse a supplied person image or generate a clear front-facing portrait with the explicitly requested compatible image model, otherwise Nano Banana 2. Managed avatar creation and speech are bundled/free; direct Fabric, Sync, and render are paid.\\n- **Existing-video edits use their own category**: call `edit_video` or `videodraft edit video` with a `video_edit` model when transforming the source itself. Kling O3 and Wan 2.7 Ref/Edit are dual-mode: their reference-generation modes may use generic `generate_video` to create a new guided clip. Motion transfer similarly uses `generate_motion_control_video` or `videodraft edit motion` with a `motion_control` model.\\n- **Upscaling preserves rather than redesigns**: use Topaz when resolution, detail, or cleanup is the problem. Regenerate or edit when the subject, text, framing, continuity, or motion is wrong. Upscale a low-quality avatar portrait before Fabric; do not render a new avatar at 480p just to upscale the result.\\n- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side \u2014 `videodraft projects list`, take the most recent, and resume with its id. Don\'t start a duplicate.\\n\\n## User-attached media: classify roles first\\n\\nFor EACH attached file decide:\\n\\n- **visual_asset** \u2014 recurring reference (character / product / location / style). Upload, then pass in `visual_assets` of `generate_storyboard_from_idea` (via `videodraft call`), or add to an existing project with `add_visual_assets`. Type must be one of `character | object | location | style | custom` with a short name + concrete description.\\n- **shot** \u2014 the media IS footage for the video. Whole video = footage \u2192 `generate_storyboard_from_media`. Idea + footage \u2192 `generate_storyboard_from_idea` with `shot_media`. Existing storyboard \u2192 `attach_media_to_shots`.\\n- **reference** \u2014 inspiration only \u2192 fold a description into the idea/instructions; don\'t place it as a shot or asset.\\n\\nAmbiguous (e.g. a person holding a product)? Ask the user.\\n\\nUploads persist in the media library \u2014 recall later with `videodraft media list`.\\n\\n## Editing project data safely\\n\\n1. `videodraft call get_project_schema` \u2014 read the structure once per session.\\n2. `videodraft projects get <id> --raw` \u2014 the exact editable blob.\\n3. Modify; then `videodraft call update_project --stdin` with `{\\"project_id\\": \\"...\\", \\"data\\": {...}}`.\\n   - Objects deep-merge key-by-key; **arrays replace wholesale** \u2014 send the complete array you\'re changing (e.g. all of `storyboard.scenes`).\\n   - Scene shot arrays (`image_prompt` / `shot_types` / `shot_actions` / `search_prompt` / `preview_media`) are auto-aligned; fix-ups come back as warnings.\\n4. Snapshot before risky edits: `videodraft checkpoint create <id> --name \\"before re-script\\"`. Restore with `videodraft checkpoint restore <id> <version>`.\\n\\n## AI Studio sessions (standalone generations)\\n\\nProject generations group automatically. For standalone work in a long conversation, create one session up front and reuse it:\\n\\n```bash\\nSESSION=$(videodraft call create_ai_studio_session --arg name=\\"Fox brand explorations\\" --json | jq -r .session_id)\\nvideodraft generate image \\"...\\" --session \\"$SESSION\\"\\n```\\n"}') {
-    return JSON.parse('{"SKILL.md":"---\\nname: videodraft\\ndescription: Create and edit AI videos, images, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers the cloud `videodraft` CLI/MCP and local headless `videodraft_editor` MCP. When the editor MCP is exposed, prefer it for production, timeline assembly, and export; use cloud production/export only when explicitly requested or the editor is unavailable.\\n---\\n\\n# VideoDraft\\n\\nVideoDraft is an AI video creation platform where asset generation is the priority lane:\\n\\n- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.\\n- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.\\n- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane whenever `videodraft_editor` is available.\\n- **Hosted project production**: idea \u2192 script \u2192 storyboard \u2192 hosted production timeline \u2192 exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.\\n\\n## How to connect\\n\\nCloud generation has two equivalent surfaces (same backend, credits, and hosted projects). Native timeline editing is a separate local surface:\\n\\n1. **CLI** (preferred when you have a shell): run `videodraft` if it\'s on PATH; otherwise `npx -y videodraft@latest` runs it with no install (needs Node \u226520; the `-y` skips npx\'s install prompt so it runs non-interactively; the package is fetched on first use and cached). For heavy use, `npm install -g videodraft`. If there\'s no Node/shell here but the MCP connector below is available, use that instead; if neither works, tell the user how to install (https://videodraft.ai/cli).\\n   - Auth \u2014 pick by context, don\'t guess:\\n     \u2022 INTERACTIVE (a human is in the session, e.g. Claude Code / Codex): on exit code 3 (\\"not authenticated\\"), tell the user to run `videodraft login` in their terminal \u2014 it opens their browser for a one-click VideoDraft sign-in (OAuth), no key to copy. Wait for them to confirm it succeeded, then retry the command. This is the preferred path when the user is present.\\n     \u2022 HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).\\n     \u2022 SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat \u2014 use browser `login` or the env var so the token never lands in the transcript.\\n   - Every command accepts `--json` (parse this, don\'t scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (\u2192 tell the user, don\'t retry).\\n   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.\\n   - Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft upload`, and `videodraft download`.\\n   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args \'<json>\'`.\\n2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly \u2014 the CLI\'s curated commands map 1:1 onto these tools.\\n3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export. Inside VideoDraft ADE on a supported Mac, Claude and Codex receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_control` (`list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.\\n\\nNative editor mutations are revision-guarded. Send them serially and carry forward each result\'s fresh revision. See [references/editor.md](references/editor.md) for project selection, media import, timing units, mutation deltas, verification, export, and the `videodraft-editor` terminal bridge.\\n\\nIf you are reading this skill through `videodraft skills show skill`, run `videodraft skills show editor` before native editor work to load that reference.\\n\\n**VideoDraft ADE routing rule:** the presence of `videodraft_editor` means the native editor is ready, even when no editor window is visible. Use cloud tools to generate or source assets and, when helpful, scripts or storyboards. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` by default. Import the assets into the native project, assemble there, and call native `export_start`. Use hosted production/export only when the user explicitly asks for the web workflow or the native editor tools are unavailable. Do not silently fall back to hosted production after a native tool error.\\n\\n## First decision: asset, hosted project, or native edit?\\n\\n- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.\\n  - `videodraft generate image \\"a red fox in snow, cinematic\\" --ar 16:9 --download ./out/`\\n  - `videodraft generate video \\"slow dolly over a misty lake\\" --model gemini-omni-flash --duration 6 --download ./out/`\\n- **Any final video, production timeline, existing footage, local `.vdproject`, or hands-on edit**: use `videodraft_editor` when available. List or open the intended local project, or create a native project for a new production. The editor can work without showing its UI.\\n- **A small set of related assets**: still stay in the asset lane. Use an AI Studio session if you need to group related generations. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.\\n- **A generated multi-scene video / ad / explainer**: when the editor is available, use hosted tools only for any needed script, storyboard, shot planning, or generated assets; stop before hosted production, import the assets, and build/export the native timeline. A hosted project is optional unless the user wants the web project or its storyboard workflow.\\n- **A hosted web project or hosted export**: use the hosted pipeline only when the user explicitly asks for it or the native editor is unavailable.\\n- **Just a script** (no video asked for): A script-only request creates a script-stage project but stops at the script. Use `videodraft create \\"...\\" --script-only`; do not build a storyboard the user didn\'t ask for.\\n- **Iterating on existing work**: identify the surface first. Use `project_control` with `action:\'list\'` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.\\n\\n## Choose the model from the task\\n\\nIf the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.\\n\\n**Images:**\\n\\n- `nano-banana-2`: general default, editing, consistency, and references.\\n- `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.\\n- `gpt-image-2`: posters, logos, signs, title cards, readable text, or precise composition/editing.\\n\\n**Videos:**\\n\\n- `gemini-omni-flash`: general default up to 10s, first frame/image references, or editing one source video without extra media references. Fixed 720p with audio.\\n- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. Use `mini` for cost, `fast` for speed, `standard` for quality or 1080p/4K.\\n- `kling-v3-turbo`: fast polished 3-15s with first frame, multi-prompt, and audio. `kling-o3`: image references, first/last frames, multi-prompt, audio control, or 4K. `kling-3.0`: similar without reference-image mode.\\n- Existing-video edits use `videodraft edit video`, not generic generation. Choose from the `video_edit` catalog category: Grok for simple prompt edits, Wan 2.7 for one style reference or source-matching duration, Happy Horse for up to 5 references, and Kling O3 for controlled reference-image edits.\\n- Kling O3 and Wan 2.7 Ref/Edit also have reference-generation modes. Use `videodraft generate video --model <ref-edit-id>` with `--ref-video`/`--ref` to generate a new guided clip; use `videodraft edit video` when changing the source itself.\\n- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.\\n- Use Veo 3.1 when explicitly requested or as a fallback.\\n\\n**Audio and utilities:**\\n\\n- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and settles at 19 credits per actual minute, with up to 38 credits reserved during generation. The CLI automatically retries transient responses with one operation key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- Prefer ElevenLabs for voiceover, dialogue, voice changing, dubbing, and sound effects. Honor an explicitly selected supported TTS voice/provider. Use Lyria for instrumental music and ElevenLabs Music for vocals, lyrics, or exact timing.\\n- Talking head/presenter: choose by source. Use managed `avatar create` then `avatar render` when the user wants a reusable avatar record and bundled speech. Use `avatar fabric` for a one-off portrait plus text or existing audio. Use `avatar lipsync` when both the source video and replacement audio already exist.\\n- Enhancement: use Topaz image/video upscaling only when the content is already correct. Use image 1x for cleanup, 2x by default, 4x when justified; use video 2x by default. Edit or regenerate creative errors.\\n\\nSee [references/models.md](references/models.md) for the detailed routing table and exact capability limits.\\n\\n## Prefer references when continuity matters\\n\\nPure text-to-image or text-to-video is fine for a generic one-off asset. When a specific character, product, location, style, composition, or brand identity must survive generation, use references instead of hoping the prompt recreates it.\\n\\n- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.\\n- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.\\n- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the native editor instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.\\n\\n## Cost and credits\\n\\nDo not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.\\n\\nFor expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user\'s confirmation preference for the session.\\n\\n`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` lists TTS voices. Consult them instead of guessing capabilities.\\n\\n## Async jobs\\n\\nImage/video generation is asynchronous: commands submit a job and **wait by default**, printing output URLs (and saving files with `--download`). Large downloaded images also get a downscaled copy in `previews/` next to them (the `preview` field / \\"inspect via preview\\" line in the output) \u2014 **look at the preview, deliver the original**; viewing full-resolution images bloats the chat permanently. In scripts/CI prefer explicit control:\\n\\n```bash\\nJOB=$(videodraft generate image \\"...\\" --no-wait --json | jq -r .job_id)\\nvideodraft wait \\"$JOB\\" --download \\"./outputs/{job_id}_{index}.{ext}\\" --json\\n```\\n\\nFor MANY jobs: submit each with `--no-wait`, collect ALL with one command \u2014 `videodraft wait <id1> <id2> ...` polls every job from one process with one batched request per tick. Do NOT spawn parallel `wait`/`generate --wait` processes for a batch.\\n\\nIf a wait times out, the job is still running server-side \u2014 `videodraft status <job_id>` later. Never re-submit just because a wait timed out (that double-spends credits).\\n\\n## Local files and reference images\\n\\nReference inputs must be public URLs. The CLI uploads local files automatically wherever a URL is expected (`--ref photo.jpg`, `--start-image frame.png`), or explicitly:\\n\\n```bash\\nURL=$(videodraft upload ./product.png --json | jq -r .url)\\n```\\n\\nNever silently drop a reference you couldn\'t upload \u2014 stop and tell the user. Never upload a user\'s file to a third-party host.\\n\\nWhen the user attaches media for a native production, import actual footage into the editor by default. For hosted generation/storyboarding, classify each item before acting: a recurring **visual asset** (character/product/location/style), actual **footage to place as shots**, or **inspiration only**. See [references/pipeline.md](references/pipeline.md) for the hosted role mapping.\\n\\n## Showing media to the user\\n\\nGenerated media is **not** displayed in the chat automatically \u2014 you decide what to show. To preview an asset inline, save it locally (use `--download` so it lands under `media/`) and reference its **local path** as a Markdown link with a **leading `./`**:\\n\\n```\\n[ferrari shot](./media/ferrari_01.png)     \u2190 image card\\n[the clip](./media/clip.mp4)               \u2190 video player\\n[voiceover](./media/vo.mp3)                \u2190 audio player\\n```\\n\\nPut the Markdown link **in your message text** \u2014 video and audio embed exactly like images. Do **not** use `SendUserFile` (or other file-send tools) to display media: that renders inside a collapsible tool card and gets buried in the tool list. The Markdown link in your prose is what produces the inline card.\\n\\nUse the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or `./<any-folder>/clip.mp4` \u2014 any folder in the workspace works), or the **absolute** path for a file outside the workspace (e.g. `/Users/you/Desktop/clip.mp4` or another workspace\'s path). Both render. Show the finished results worth showing (and only those \u2014 not every intermediate job). A bare CDN URL or a JSON dump of output URLs does **not** render; the local-path Markdown link is what produces an inline card.\\n\\n## Native-first VideoDraft ADE pipeline (idea \u2192 MP4)\\n\\nWhen `videodraft_editor` is present:\\n\\n1. Generate or source the script, storyboard, shot images, clips, voiceovers, music, and other assets through the cloud CLI/MCP as needed.\\n2. Call native `project_control` to open or create the `.vdproject`.\\n3. Call native `media_import`, wait for imports to become ready, then assemble and refine the timeline with editor tools.\\n4. Call native `export_start` and use `export_status` for progress and results.\\n\\nDo not run the hosted production or export steps in this path unless the user explicitly asks for a web production.\\n\\n## Hosted fallback pipeline (idea \u2192 MP4)\\n\\nUse this only when there is NO native editor at all, or the user explicitly requests the hosted web\\nworkflow. The native surface is not only the injected `videodraft_editor` MCP: a `videodraft-editor`\\nexecutable on PATH is the same editor reached through its terminal bridge, and\\n[references/editor.md](references/editor.md) covers driving it that way. Treating a missing MCP as\\n\\"no editor\\" sends sessions that have the binary into hosted production for no reason.\\n\\n```bash\\nvideodraft create \\"<idea>\\" --ar 9:16            # project: script \u2192 visual assets \u2192 storyboard\\nvideodraft shots <project_id> --grid --estimate # cost preview, confirm with user\\nvideodraft shots <project_id> --grid            # batch shot images (waits, writes onto shot cards)\\nvideodraft produce <project_id>                 # voiceovers + captions + production timeline\\nvideodraft export <project_id> --download final.mp4\\n```\\n\\nOptional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music \\"...\\" --attach <project_id>`), and standalone audio assets (`generate audio`, `generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).\\n\\n## Avatar and talking-head videos (both surfaces)\\n\\nAvatar generation is cloud-only \u2014 the native editor has no avatar or lipsync tools \u2014 so this applies whether or not `videodraft_editor` is present. Generate the avatar in the cloud; in VideoDraft ADE, import the rendered clip and cut it on the native timeline like any other footage.\\n\\nAvatar/talking-head videos use dedicated commands. For a reusable managed avatar, obtain or generate a clear portrait \u2192 `videodraft avatar script` when needed \u2192 `videodraft avatar create` \u2192 `videodraft avatar render --resolution 720p`. For a one-off portrait, use `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.\\n\\n## Working with hosted project data\\n\\nA hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` \u2014 objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace native editor tools when `videodraft_editor` is available for the production itself.\\n\\n## More\\n\\n- [references/pipeline.md](references/pipeline.md) \u2014 hosted fallback data model and production workflow\\n- [references/editor.md](references/editor.md) \u2014 native headless editor routing, project selection, import, timeline edits, verification, and export\\n- [references/models.md](references/models.md) \u2014 choosing image/video models, pricing patterns, voices and styles\\n- [references/examples.md](references/examples.md) \u2014 recipes: batch product videos from a CSV, talking-head from a script, changelog video in CI\\n","references/editor.md":"# Native VideoDraft Editor reference\\n\\nUse this reference when the user wants to assemble, cut, caption, mix, lay out, inspect, or export a local VideoDraft Editor project. The native editor is deterministic and local. Cloud generation remains in the `videodraft` CLI or hosted MCP.\\n\\n## VideoDraft ADE preference rule\\n\\nWhen `videodraft_editor` tools are exposed, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.\\n\\nUse cloud tools for asset generation and optional script/storyboard work, then import the results. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` unless the user explicitly requests an editable web production or the native editor tools are unavailable. If a native tool call fails after the editor was available, report or recover that native failure rather than silently switching surfaces.\\n\\n## Choose the correct surface\\n\\n- `videodraft` and the hosted VideoDraft MCP generate assets and can manage hosted web projects. They use the user\'s VideoDraft account and credits. In VideoDraft ADE, use them mainly as the source of generated media and optional storyboards for the native production.\\n- `videodraft_editor` edits local `.vdproject` packages. It has no generation, account, model, or credit tools.\\n- Inside VideoDraft ADE on a supported Mac, the editor MCP is injected automatically for Claude and Codex in both Code and VideoDraft modes. It starts headlessly before the chat opens. The user does not need to click Open Editor, and closing or hiding the editor window does not stop headless editing.\\n- Outside that environment, use the editor only if `videodraft_editor` MCP tools are already exposed or the `videodraft-editor` executable is on PATH. Do not confuse the public `videodraft` cloud CLI with the separate native editor executable.\\n\\nPrefer the direct MCP tools when they are available. The terminal bridge is useful for scripts, diagnostics, or an agent session where the MCP was not injected.\\n\\n## Start with the intended project\\n\\nAn MCP session can begin without a project selected. Project selection belongs to the session, not to whichever editor window happens to be frontmost.\\n\\n1. If the user named an existing project but its identity is unclear, call `project_control` with `action:\'list\'`.\\n2. Open the exact project by the returned `id`, unambiguous `name`, or `.vdproject` `path`.\\n3. Create only when the user wants a new local edit. `action:\'create\'` accepts optional `name`, `fps`, `aspectRatio`, and `quality`.\\n4. Treat `isActive` as this MCP session\'s target and `isVisible` as the project shown in the UI. Headless editing only needs the session target.\\n5. Use `action:\'close\'` only when closing is part of the task. It saves first and never deletes the project.\\n\\nDo not substitute a hosted project ID for a native project. A hosted project can supply scripts, storyboards, and generated media, but the native edit is a separate `.vdproject` package.\\n\\n## Keep a reliable editing model\\n\\n- Call `timeline_read` once after opening or creating a project, after switching timelines, or after an out-of-band user edit. It returns the revision and current clip/track state.\\n- Call `media_list` before using a `mediaRef`. Poll imports with a filtered read (`ids` for a known asset, `pending:true` for a batch) instead of repeatedly loading the full library.\\n- Timeline placement uses project frames. Source spans, media durations, transcript segments, and search hits use seconds. Pass those values to the relevant tools as returned; do not multiply by fps yourself.\\n- IDs are short stable prefixes. Pass them back exactly as returned. Tracks use stable `trackId` values; indexes can change.\\n- Send project mutations serially. Pass `ifRevision` from the latest read or mutation when available, then replace it with the fresh revision from the next result. Parallel edits against one project can race or invalidate each other\'s revision.\\n- Every mutation returns a delta in `timeline_read` vocabulary. Patch your working model from that delta instead of re-reading after every successful call. Re-read after a stale-state failure or an out-of-band change.\\n- Use `canvas_arrange` for split screens, picture-in-picture, grids, and canvas placement. Use `tracks_edit` to fix stacking. Do not synthesize layouts from generic transforms or keyframes.\\n- Use `media_view` before describing source content, and `transcript_read` to locate a spoken moment. Use `timeline_view` to verify the composited result the viewer will actually see.\\n- Volume inputs, including volume keyframes, are linear values from `0` to `1`. Timeline reads return the same linear scale.\\n\\n## Bring generated or local media into the editor\\n\\nUse cloud generation for new assets, save or download the outputs, then call native `media_import`:\\n\\n- `source.path`: absolute local file or directory. A directory imports recursively and preserves its folder structure.\\n- `source.url`: HTTPS asset URL. Set `mimeType` when a signed URL has no usable extension.\\n- `source.bytes`: small base64 media with a required `mimeType`.\\n- `source.matte`: generated solid-color image.\\n\\nReadiness differs by source, and so does the poll that detects it:\\n\\n- **URL and single-file path** imports return `status:\'downloading\'` with one `mediaRef`. Poll `media_list` with `ids:[mediaRef]` until `generationStatus` is absent.\\n- **Directory** imports return `status:\'preparing\'` once the batch is registered \u2014 not ready. A batch has no single `mediaRef` to poll by, so poll `media_list` with `pending:true` until it reports no unresolved imports.\\n- **Inline bytes and matte** imports finish inline and come back `status:\'ready\'`; no polling needed.\\n\\nNever place a pending asset on the timeline. `generationStatus` is the signal: `preparing` and\\n`downloading` mean keep polling, absent means usable, and **`failed` is terminal** \u2014 report it or\\nretry the import explicitly, never poll on. Do not treat \\"not downloading\\" as ready.\\n\\nFor a batch of local outputs, download them into one workspace directory and import that directory once when practical. This is safer and faster than racing many import calls; just remember it is the `pending:true` poll that tells you when the batch is usable.\\n\\n## Edit and verify\\n\\nUse the tool descriptions as the exact schema. A dependable sequence is:\\n\\n1. `project_control` to select or create the local project.\\n2. `timeline_read` and `media_list` to establish current state.\\n3. `media_view` when content selection matters.\\n4. Serialized clip, track, layout, text, caption, audio, color, effect, or cut mutations using the current revision.\\n5. `timeline_view` when visual composition or layer order matters.\\n6. `undo` if the requested result is wrong and the next mutation would not cleanly correct it.\\n\\nEdits are undoable. Do not ask for confirmation before each ordinary edit. Ask one focused question only when the user\'s creative direction is materially ambiguous.\\n\\n## Export\\n\\n`export_start` queues work in the background and returns a `jobId`, destination, and `started` or `queued` status.\\n\\n- Use `video` for H.264, H.265, or ProRes.\\n- Use `xml` for Premiere Pro.\\n- Use `xml` (XMEML) for Premiere Pro **and DaVinci Resolve** \u2014 Resolve reads XMEML natively.\\n  Use `fcpxml` only for Final Cut Pro. Sending Resolve an FCPXML produces a package it cannot\\n  open cleanly, so the target matters more than the file extension suggests.\\n- Use `videodraft` for a self-contained project package.\\n- Omit `outputPath` unless the user named a destination; the default is `~/Downloads`.\\n- Use `export_status` to list progress, warnings, and results. Cancel only when the user asks or the just-queued settings were wrong. Do not infer that an export is stuck from elapsed time alone.\\n\\n## Terminal bridge\\n\\nVideoDraft desktop terminals expose `videodraft-editor`, which controls the same process and MCP surface:\\n\\n```bash\\nvideodraft-editor status\\nvideodraft-editor list-tools\\nvideodraft-editor tool project_control --json \'{\\"action\\":\\"list\\"}\'\\nvideodraft-editor tool timeline_read --json \'{}\'\\nvideodraft-editor show\\nvideodraft-editor hide\\n```\\n\\nControl and tool commands auto-start a headless editor if none is running. `show` only reveals the already-running UI. Use `videodraft-editor tool <name> --json -` to read a JSON object from stdin when shell quoting would be fragile. Never read, copy, or expose the editor\'s rotating local authentication secret.\\n","references/examples.md":"# Recipes\\n\\nWorking patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.\\n\\nInside VideoDraft ADE, if a native editor is available, use these recipes for asset generation and\\noptional script/storyboard stages. Hand the results to the editor for production and export ONLY\\nwhen the deliverable the user asked for is a composed production. A standalone output \u2014 the batch\\nproduct clips in recipe 1, the upscale in recipe 7 \u2014 is finished when it is generated; importing it\\ninto a project and exporting a timeline builds an edit nobody asked for. Recipes below that call `videodraft produce` or `videodraft export` are hosted fallbacks only. Do not choose them over the available native editor unless the user explicitly asks for the hosted web workflow.\\n\\n## 1. Batch product videos from a CSV\\n\\nOne 9:16 product clip per row of `products.csv` (`name,image_url,tagline`):\\n\\n```bash\\n#!/usr/bin/env bash\\nset -euo pipefail\\nmkdir -p outputs\\n\\nwhile IFS=, read -r name image tagline; do\\n  job=$(videodraft generate video \\\\\\n    \\"Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting.\\" \\\\\\n    --model gemini-omni-flash --ar 9:16 --duration 6 \\\\\\n    --start-image \\"$image\\" \\\\\\n    --no-wait --json | jq -r .job_id)\\n  echo \\"$name,$job\\" >> outputs/jobs.csv\\ndone < <(tail -n +2 products.csv)\\n\\n# Collect ALL results with ONE process (batched polling \u2014 one request per tick)\\nvideodraft wait $(cut -d, -f2 outputs/jobs.csv) \\\\\\n  --download \\"outputs/{job_id}_{index}.{ext}\\" --json > outputs/results.json\\n# map job ids back to product names via outputs/jobs.csv\\n```\\n\\nSubmit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Gemini Omni Flash is selected because these are six-second first-frame product clips. Estimate first: `videodraft costs gemini-omni-flash --type video --duration 6 --resolution 720p --audio` \xD7 rows, and confirm with the user.\\n\\n## 2. Hosted full marketing video from one idea (fallback)\\n\\n```bash\\nvideodraft create \\"30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette.\\" \\\\\\n  --ar 9:16 --style cinematic --json > project.json\\nPROJECT=$(jq -r .project_id project.json)\\n\\nvideodraft shots \\"$PROJECT\\" --grid --estimate          # show the user the cost; get a go-ahead\\nvideodraft shots \\"$PROJECT\\" --grid\\nvideodraft produce \\"$PROJECT\\"\\nvideodraft generate music \\"minimal ambient, warm pads, 60 BPM\\" --attach \\"$PROJECT\\"\\nvideodraft generate audio \\"Extend @Audio1 into a 20-second transition\\" --ref-audio ./intro.wav --format wav --download ./transition.wav\\nvideodraft export \\"$PROJECT\\" --download solace-launch.mp4\\n```\\n\\nUse this complete hosted path only when the user requested a web project or the native editor is unavailable. Otherwise stop after the storyboard/assets, import them into the native `.vdproject`, and export with `export_start`. The hosted project stays editable at the URL in `project.json` (`.urls`).\\n\\n## 3. Talking-head (avatar) video\\n\\nWhen the user has no portrait, generate a clear front-facing avatar image first. Skip this step when they supplied one or an existing character should be reused.\\n\\n```bash\\nvideodraft generate image \\\\\\n  \\"Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background\\" \\\\\\n  --model nano-banana-2 --ar 9:16 --download ./media/avatar.png\\n\\nSCRIPT=$(videodraft avatar script \\"why our espresso subscription saves you money\\" --style ad-style --json | jq -r .script)\\nAVATAR=$(videodraft avatar create ./media/avatar.png --script \\"$SCRIPT\\" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)\\nvideodraft avatar render \\"$AVATAR\\" --resolution 720p   # VEED Fabric paid step; confirm cost first (~20 credits/sec)\\n```\\n\\n`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.\\n\\nIf the portrait is low resolution, enhance it before `avatar create`:\\n\\n```bash\\nvideodraft upscale image ./founder-small.jpg --scale 2x --download ./media/founder-upscaled.png\\n```\\n\\nFor a one-off portrait animation without creating a managed avatar record:\\n\\n```bash\\nvideodraft avatar fabric ./founder.jpg \\\\\\n  --text \\"Welcome to the weekly product update.\\" \\\\\\n  --voice-description \\"warm, confident American presenter\\" \\\\\\n  --resolution 720p --download ./media/presenter.mp4\\n```\\n\\nWhen the user already has both the video and replacement speech:\\n\\n```bash\\nvideodraft avatar lipsync ./presenter.mp4 \\\\\\n  --audio ./localized-voiceover.mp3 \\\\\\n  --sync-mode loop --download ./media/presenter-localized.mp4\\n```\\n\\nEdit an existing video with a dedicated edit model:\\n\\n```bash\\nvideodraft models video --category video_edit\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Turn the room into a warm evening scene while preserving the product and camera motion\\" \\\\\\n  --model wan-2.7-ref-edit --ref ./evening-style.jpg \\\\\\n  --preserve-audio --download ./media/product-demo-evening.mp4\\n```\\n\\nTransfer motion from a reference clip onto a character image:\\n\\n```bash\\nvideodraft edit motion ./character.png \\\\\\n  \\"Apply the dancer\'s movement to this character while preserving identity\\" \\\\\\n  --motion-video ./dance-reference.mp4 \\\\\\n  --model kling-v3-motion-control --quality pro \\\\\\n  --download ./media/character-dance.mp4\\n```\\n\\n## 4. Hosted changelog video in CI\\n\\nIn a GitHub Action with `VIDEODRAFT_API_KEY` set as a secret:\\n\\n```bash\\nNOTES=$(git log --oneline v1.2.0..HEAD | head -20)\\nvideodraft create \\"Weekly product update video. Energetic, 20 seconds. Changes: ${NOTES}\\" --ar 16:9 --json > p.json\\nPROJECT=$(jq -r .project_id p.json)\\nvideodraft shots \\"$PROJECT\\" && videodraft produce \\"$PROJECT\\"\\nvideodraft export \\"$PROJECT\\" --download changelog.mp4 --wait-timeout 30m\\n```\\n\\n## 5. Variations and picking a winner\\n\\n```bash\\nvideodraft generate image \\"logo concept: minimalist fox, geometric\\" --num 4 --download \\"./concepts/{job_id}_{index}.{ext}\\" --json\\n# Show all 4 to the user; regenerate the chosen one at higher res:\\nvideodraft generate image \\"<same prompt>\\" --model nano-banana-pro --resolution 4K\\n```\\n\\n## 6. Reaching tools without a curated command\\n\\n```bash\\nvideodraft tools list --json | jq -r \'.[].name\'\\nvideodraft tools schema attach_media_to_shot --json\\nvideodraft call attach_media_to_shot --args \'{\\"project_id\\":\\"...\\",\\"scene_index\\":0,\\"shot_index\\":1,\\"media_url\\":\\"https://...\\",\\"media_type\\":\\"video\\",\\"duration_seconds\\":6}\'\\n```\\n\\nAnything the hosted VideoDraft MCP exposes, including character studio, product studio, and hosted project data, is reachable this way even before it gets a curated command. Native `.vdproject` editing uses the separate `videodraft_editor` MCP described in SKILL.md.\\n\\n## 7. Enhance an existing asset without changing it\\n\\n```bash\\n# Light image cleanup, no enlargement\\nvideodraft upscale image ./poster.png --scale 1x --download ./media/poster-enhanced.png\\n\\n# General image and video enlargement\\nvideodraft upscale image ./frame.png --scale 2x --download ./media/frame-2x.png\\nvideodraft upscale video ./clip.mp4 --scale 2x --download ./media/clip-2x.mp4\\n```\\n\\nUse these when the content is correct and only quality or resolution needs improvement. If the poster text, composition, subject, or motion is wrong, edit or regenerate instead.\\n","references/models.md":"# Choosing models (and predicting cost)\\n\\nAlways consult the live catalog instead of memorizing this page \u2014 models change weekly:\\n\\n```bash\\nvideodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)\\nvideodraft models video --json     # every video model + inputs + per-second pricing metadata\\nvideodraft models audio --json     # standalone audio/media models + pricing inputs\\nvideodraft models voices --json    # TTS voices\\nvideodraft models styles --json    # visual style presets\\n```\\n\\n## Task-based model selection\\n\\nHonor an explicitly named model when it supports the request. Otherwise choose from the task\'s inputs, duration, audio, quality, speed, and cost. Pass the chosen model explicitly instead of relying on a blind platform fallback.\\n\\n### Images\\n\\n| Need                                                                                   | Choose               | Why                                                               |\\n| -------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------- |\\n| Most generation, editing, character consistency, or reference work                     | `nano-banana-2`      | Best general default; 1K/2K/4K and up to 14 reference images      |\\n| Highest-quality complex generation or reasoning                                        | `nano-banana-pro`    | Premium Nano Banana quality and reasoning                         |\\n| Fast, inexpensive drafts and iteration                                                 | `nano-banana-2-lite` | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |\\n| Posters, title cards, signs, logos, or any image with important readable text          | `gpt-image-2`        | Strong text rendering; up to 16 image inputs and 1K/2K/4K output  |\\n| Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2`        | Strong non-Nano alternative with multi-image input                |\\n\\nUse `--num 1..4` for variations of one prompt in a single call. Never loop separate paid calls for variations that fit in one request.\\n\\n### Videos\\n\\n| Need                                                                                                       | Choose              | Important limits                                                                                    |\\n| ---------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |\\n| Most text, first-frame, image-reference, or source-video-edit requests up to 10s                           | `gemini-omni-flash` | 720p, 3-10s or auto, audio always on, up to 10 total image inputs, one source video                 |\\n| Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2`        | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only |\\n| Fast polished 3-15s video with first frame, multi-prompt, and native audio                                 | `kling-v3-turbo`    | Audio always on; Pro default; no end frame or reference-media mode                                  |\\n| Cinematic 3-15s with image references, first+last frame, multi-prompt, audio control, or 4K                | `kling-o3`          | Up to 7 image refs; Standard/Pro/4K; audio toggle                                                   |\\n| Kling 3-15s with first+last frame, multi-prompt, optional audio, or 4K, without reference-image mode       | `kling-3.0`         | Standard/Pro/4K; audio toggle                                                                       |\\n| User explicitly requests Veo, or the selected workflow specifically needs Veo                              | `google-veo3.1`     | Good fallback, but not the preferred general model                                                  |\\n\\nRouting rules:\\n\\n- Around 11-15 seconds with native audio: use Kling or Seedance, not Gemini.\\n- One existing source video that should be edited, with an output up to 10 seconds and no additional media references to preserve: use Gemini Omni Flash.\\n- Video or audio supplied as creative reference: use Seedance 2.0.\\n- A video plus any image/audio references that must all be preserved: use Seedance 2.0. Do not promise that Gemini will preserve mixed source media; its Fal BYOK edit mode accepts only the source video and prompt.\\n- First and last frame control: use Seedance, Kling O3, or Kling 3.0. Gemini supports a first frame but not a last frame.\\n- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.\\n- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.\\n- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K.\\n\\n### Video edit and motion-control categories\\n\\nUse `videodraft models video --category video_edit` for existing-video transforms and `--category motion_control` for motion transfer.\\n\\n| Need                                  | Command/model                                                         | Important limits                                                                 |\\n| ------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |\\n| Simple prompt edit of one video       | `videodraft edit video <video> \\"...\\" --model grok-imagine-video-edit` | No image refs; source truncated to 8s; auto/480p/720p                            |\\n| Edit with one style/reference image   | `--model wan-2.7-ref-edit --ref <image>`                              | One image ref; 2-10s or match source                                             |\\n| Edit with several image references    | `--model happy-horse-video-edit --ref ...`                            | Up to 5 refs; 720p/1080p; source capped at 15s                                   |\\n| Controlled Kling edit                 | `--model kling-o3-video-ref-edit --ref ...`                           | Up to 4 refs; Standard/Pro; source clamped to 3-10s                              |\\n| Transfer reference motion to an image | `videodraft edit motion <image> \\"...\\" --motion-video <video>`         | Kling V3 default; image orientation caps motion at 10s, video orientation at 30s |\\n\\nIf the user explicitly names one of these models, preserve it. The CLI uploads local source videos and reference images automatically. Editing returns an async job and waits by default.\\n\\nKling O3 and Wan 2.7 Ref/Edit are dual-mode cards. `videodraft edit video` uses edit mode. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. `--model wan-2.7-ref-edit` generates a new clip from one or more `--ref`/`--ref-video` inputs.\\n\\n### Reference-first video workflow\\n\\n- Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.\\n- If the user gives a reference, pass it. Never silently replace it with a text description.\\n- If no reference exists and continuity matters, generate a still first with the user\'s explicitly requested compatible image model, otherwise use Nano Banana 2. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.\\n- For multi-shot scenes, generate shot images with `videodraft shots <project_id> --model <selected-image-model> --grid`. Preserve an explicitly requested compatible image model; otherwise use `nano-banana-2`. The grid establishes the scene and characters together, then decodes into individual shot images.\\n- Animate the decoded shot images as per-shot start frames or references. Do not independently text-generate each video clip when the shots need to match.\\n- Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.\\n\\n### Audio\\n\\n- **Seed Audio 1.0**: use `videodraft generate audio` for open-ended speech, sound, music, or prompt-driven audio editing. It accepts up to three audio references or one image. Address audio references as `@Audio1`, `@Audio2`, and `@Audio3`. Preset and custom cloned voice IDs are supported. Output is up to 120 seconds. There is no requested-duration input. The CLI automatically retries transient responses with one idempotency key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- **Voiceover/TTS**: prefer ElevenLabs. Brittney is the platform default voice; under ElevenLabs BYOK, use a compatible voice from the user\'s account. Honor another supported voice/provider when the user explicitly selects it.\\n- **Dialogue, voice changing, and dubbing**: ElevenLabs only.\\n- **Sound effects**: ElevenLabs Sound Effects only.\\n- **Music**: use `lyria-3-clip-preview` for a short instrumental/background score, `lyria-3-pro-preview` for a longer or higher-quality instrumental score, and `elevenlabs-music` when vocals/lyrics or a specified 10-120 second length matter.\\n- Voice Changer and Dubbing require the source media duration and currently accept source media up to 300 seconds.\\n\\n### Avatar / talking head\\n\\nChoose the dedicated path from the media the user already has:\\n\\n| Starting media                            | Command                                                                   | Use                                                 |\\n| ----------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |\\n| Portrait + script, reusable avatar record | `videodraft avatar create <portrait> --script \\"...\\"` then `avatar render` | Managed avatar flow with bundled speech preparation |\\n| Portrait + text                           | `videodraft avatar fabric <portrait> --text \\"...\\"`                        | One-off direct VEED Fabric text mode                |\\n| Portrait + existing audio                 | `videodraft avatar fabric <portrait> --audio <audio>`                     | One-off direct VEED Fabric audio lip sync           |\\n| Existing video + existing audio           | `videodraft avatar lipsync <video> --audio <audio>`                       | Sync Labs Lipsync 2                                 |\\n\\nThe managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric and Sync Labs are paid AI Studio generations and return async job IDs.\\n\\n1. Obtain the avatar image. Prefer the user\'s supplied portrait or an existing character. If none exists, use the user\'s explicitly requested compatible image model, otherwise generate a front-facing head-and-shoulders portrait with `nano-banana-2`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.\\n2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.\\n3. Generate a script only if needed: `videodraft avatar script \\"<idea>\\"`.\\n4. Create the avatar record and speech: `videodraft avatar create <portrait-url-or-file> --script \\"...\\" --voice <id> --ar 9:16`. Prefer ElevenLabs when unspecified, but honor another explicitly selected supported voice/provider.\\n5. Render with VEED Fabric: `videodraft avatar render <avatar_video_id> --resolution 720p`.\\n\\nThe portrait is passed as the avatar\'s character image, not as a generic video\'s start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.\\n\\nDirect Fabric text/audio and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. Sync costs 5 credits per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.\\n\\n### Upscaling / enhancement\\n\\n- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The result is synchronous.\\n- **Videos**: Topaz via `videodraft upscale video <url-or-file> --scale 2x`. Use 2x by default. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.\\n- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems.\\n- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.\\n\\n## Capability gotchas\\n\\n- Each model\'s `inputs` block is authoritative: supported `aspect_ratios`, `resolutions`, `quality_options`, `start_frame`/`end_frame`, `max_reference_images/videos/audio`, `multi_prompt`, `audio_toggle`. Passing an unsupported input fails with a clear error \u2014 check first, don\'t trial-and-error paid calls.\\n- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.\\n- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4); everything else ignores it. You do not need a seed for variation \u2014 `--num` already varies.\\n- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost \u2014 pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.\\n- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.\\n- Reference inputs: `--ref <img>` (images), `--ref-video <v>` (Gemini Omni Flash, Seedance 2, Wan 2.7), `--ref-audio <a>` (Seedance 2). The CLI uploads local files for all of these, so you can pass a path or a URL. `--segment \\"<prompt>:<seconds>\\"` (repeatable) drives multi-prompt models (Kling 3.0 / 3.0 Turbo / O3); total 3-15s. `generate image --video-ref` is the nano-banana-2 video reference.\\n- The top-level prompt is OPTIONAL for `generate video` with multi-prompt models and for Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video \u2014 a `--segment`-only or `--start-image`-only call is valid. Every other model still needs a prompt; the server enforces per-model rules.\\n- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.\\n\\n## Cost model\\n\\n- Images: per image (\xD7 `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.\\n- Video: usually credits/second \xD7 duration; rate depends on model + resolution + quality + native audio on/off.\\n- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) \u2014 the largest single spend in the pipeline.\\n- VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.\\n- Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.\\n- Sync Labs Lipsync 2: 5 credits per verified audio second.\\n- Voiceover TTS: 10 credits per 1000 characters for standard voices, 30 per 1000 for cloned `custom-*` voices (min 1, pro-rated); applies to standalone voiceovers AND per-scene narration during `produce`. Silent tracks are free. Voice cloning itself is a flat 150 credits per clone.\\n- Lyria music: flat per track, 10 credits (clip) / 15 credits (pro).\\n- Seed Audio 1.0: 19 credits per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum of 38 credits and refunds the unused portion after generation. Fal BYOK is free.\\n- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. Voice changer and dubbing reject source media above 300s in the current synchronous flow.\\n- Upscales: priced by scale and source size.\\n\\nQuote before spending:\\n\\n```bash\\nvideodraft costs gemini-omni-flash --type video --duration 8 --resolution 720p --audio\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio\\nvideodraft costs elevenlabs-dubbing --type audio --duration 60\\nvideodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length\\nvideodraft costs elevenlabs-dialogue --type audio --chars 350\\nvideodraft costs voiceover --type audio --chars 800    # TTS: 10 cr / 1000 chars\\nvideodraft generate video \\"...\\" --model gemini-omni-flash --estimate # same quote, inline\\n```\\n","references/pipeline.md":"# VideoDraft pipeline reference\\n\\nEverything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks). When the local `videodraft_editor` MCP is available, do not use hosted production or export by default. Use hosted tools only for asset generation and optional script/storyboard stages, then import the results and finish with the native editor reference linked from SKILL.md. Continue through `produce_project` and `export_video` only when the user explicitly requests a hosted web production or the native editor is unavailable.\\n\\nUse direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable. Script-only uses a script-stage project and stops at the script. In VideoDraft ADE with editor tools present, stop before hosted production, import the generated assets, and build/export the native project.\\n\\n## Stages and their tools\\n\\n| Stage                                   | CLI                                                                         | Underlying tool                            |\\n| --------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------ |\\n| Idea \u2192 full storyboard project          | `videodraft create \\"<idea>\\"`                                                | `generate_storyboard_from_idea`            |\\n| Idea \u2192 script only (stop there)         | `videodraft create \\"<idea>\\" --script-only`                                  | `generate_script_from_idea`                |\\n| Footage IS the video                    | `videodraft call generate_storyboard_from_media`                            | `generate_storyboard_from_media`           |\\n| Batch shot images                       | `videodraft shots <project>`                                                | `generate_shot_images`                     |\\n| One shot image                          | `videodraft generate image --project <id> --scene N --shot M`               | `generate_image`                           |\\n| Produce (voiceover, captions, timeline) | `videodraft produce <project>`                                              | `produce_project`                          |\\n| Per-shot motion prompts                 | `videodraft video-prompts <project>`                                        | `generate_video_prompts`                   |\\n| Motion clip for a shot                  | `videodraft generate video --project <id>`                                  | `generate_video`                           |\\n| Attach a finished clip to the timeline  | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot`                     |\\n| Background music                        | `videodraft generate music --attach <project>`                              | `generate_music` / `set_background_music`  |\\n| General or reference-driven audio       | `videodraft generate audio \\"...\\"`                                          | `generate_audio`                           |\\n| Sound effect                            | `videodraft generate sound-effect \\"...\\"`                                    | `generate_sound_effect`                    |\\n| Dialogue audio                          | `videodraft generate dialogue --line \\"voice:text\\"`                          | `generate_dialogue`                        |\\n| Voice changer                           | `videodraft generate voice-changer <audio>`                                 | `change_voice`                             |\\n| Dubbing                                 | `videodraft generate dub <audio_or_video>`                                  | `dub_media`                                |\\n| Scene voiceover                         | `videodraft generate voiceover --project <id> --scene N`                    | `generate_voiceover`                       |\\n| Avatar script                           | `videodraft avatar script \\"<idea>\\"`                                         | `generate_avatar_script`                   |\\n| Avatar + speech                         | `videodraft avatar create <portrait> --script \\"...\\"`                        | `create_avatar_video`                      |\\n| Talking-head render                     | `videodraft avatar render <avatar_video_id>`                                | `render_avatar_video` + `get_avatar_video` |\\n| Direct portrait + text/audio            | `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`      | `generate_veed_fabric_video`               |\\n| Existing video + replacement audio      | `videodraft avatar lipsync <video> --audio <file>`                          | `generate_sync_lipsync_video`              |\\n| Existing-video AI edit                  | `videodraft edit video <video> \\"<change>\\" --model <video-edit-model>`       | `edit_video`                               |\\n| Motion transfer                         | `videodraft edit motion <image> \\"<direction>\\" --motion-video <video>`       | `generate_motion_control_video`            |\\n| Image enhancement/upscale               | `videodraft upscale image <image>`                                          | `upscale_image`                            |\\n| Video enhancement/upscale               | `videodraft upscale video <video>`                                          | `upscale_video`                            |\\n| Final MP4                               | `videodraft export <project>`                                               | `export_video` + `check_export_status`     |\\n\\n## Rules that prevent broken results\\n\\n- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don\'t call `generate_storyboard_scenes` with a raw idea as the \\"script\\".\\n- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project\'s visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project\'s visual assets and/or the previous shot\'s image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.\\n- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.\\n- **Hold off generating shot images while the user is still iterating** on storyboard structure.\\n- **produce \u2192 export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.\\n- **Do not attach motion clips before production exists**: run `produce` successfully first, then attach finished motion clips to the production timeline. Attaching before `production_data` exists cannot place them in the final timeline.\\n- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:\\"video\\"`, include `duration_seconds`) \u2014 it replaces the production timeline clip while keeping the storyboard still.\\n- **Talking heads use dedicated avatar tools**: do not use `generate video`. Use managed `avatar create` and `avatar render` for reusable avatars, direct `avatar fabric` for a portrait plus text/audio, and `avatar lipsync` for an existing video plus replacement audio. Reuse a supplied person image or generate a clear front-facing portrait with the explicitly requested compatible image model, otherwise Nano Banana 2. Managed avatar creation and speech are bundled/free; direct Fabric, Sync, and render are paid.\\n- **Existing-video edits use their own category**: call `edit_video` or `videodraft edit video` with a `video_edit` model when transforming the source itself. Kling O3 and Wan 2.7 Ref/Edit are dual-mode: their reference-generation modes may use generic `generate_video` to create a new guided clip. Motion transfer similarly uses `generate_motion_control_video` or `videodraft edit motion` with a `motion_control` model.\\n- **Upscaling preserves rather than redesigns**: use Topaz when resolution, detail, or cleanup is the problem. Regenerate or edit when the subject, text, framing, continuity, or motion is wrong. Upscale a low-quality avatar portrait before Fabric; do not render a new avatar at 480p just to upscale the result.\\n- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side \u2014 `videodraft projects list`, take the most recent, and resume with its id. Don\'t start a duplicate.\\n\\n## User-attached media: classify roles first\\n\\nFor EACH attached file decide:\\n\\n- **visual_asset** \u2014 recurring reference (character / product / location / style). Upload, then pass in `visual_assets` of `generate_storyboard_from_idea` (via `videodraft call`), or add to an existing project with `add_visual_assets`. Type must be one of `character | object | location | style | custom` with a short name + concrete description.\\n- **shot** \u2014 the media IS footage for the video. Whole video = footage \u2192 `generate_storyboard_from_media`. Idea + footage \u2192 `generate_storyboard_from_idea` with `shot_media`. Existing storyboard \u2192 `attach_media_to_shots`.\\n- **reference** \u2014 inspiration only \u2192 fold a description into the idea/instructions; don\'t place it as a shot or asset.\\n\\nAmbiguous (e.g. a person holding a product)? Ask the user.\\n\\nUploads persist in the media library \u2014 recall later with `videodraft media list`.\\n\\n## Editing project data safely\\n\\n1. `videodraft call get_project_schema` \u2014 read the structure once per session.\\n2. `videodraft projects get <id> --raw` \u2014 the exact editable blob.\\n3. Modify; then `videodraft call update_project --stdin` with `{\\"project_id\\": \\"...\\", \\"data\\": {...}}`.\\n   - Objects deep-merge key-by-key; **arrays replace wholesale** \u2014 send the complete array you\'re changing (e.g. all of `storyboard.scenes`).\\n   - Scene shot arrays (`image_prompt` / `shot_types` / `shot_actions` / `search_prompt` / `preview_media`) are auto-aligned; fix-ups come back as warnings.\\n4. Snapshot before risky edits: `videodraft checkpoint create <id> --name \\"before re-script\\"`. Restore with `videodraft checkpoint restore <id> <version>`.\\n\\n## AI Studio sessions (standalone generations)\\n\\nProject generations group automatically. For standalone work in a long conversation, create one session up front and reuse it:\\n\\n```bash\\nSESSION=$(videodraft call create_ai_studio_session --arg name=\\"Fox brand explorations\\" --json | jq -r .session_id)\\nvideodraft generate image \\"...\\" --session \\"$SESSION\\"\\n```\\n"}');
+  if ('{"SKILL.md":"---\\nname: videodraft\\ndescription: Create and edit AI videos, images, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers the cloud `videodraft` CLI/MCP and local headless `videodraft_editor` MCP. When the editor MCP is exposed, prefer it for production, timeline assembly, and export; use cloud production/export only when explicitly requested or the editor is unavailable.\\n---\\n\\n# VideoDraft\\n\\nVideoDraft is an AI video creation platform where asset generation is the priority lane:\\n\\n- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.\\n- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.\\n- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane whenever `videodraft_editor` is available.\\n- **Hosted project production**: idea \u2192 script \u2192 storyboard \u2192 hosted production timeline \u2192 exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.\\n\\n## How to connect\\n\\nCloud generation has two equivalent surfaces (same backend, credits, and hosted projects). Native timeline editing is a separate local surface:\\n\\n1. **CLI** (preferred when you have a shell): run `videodraft` if it\'s on PATH; otherwise `npx -y videodraft@latest` runs it with no install (needs Node \u226520; the `-y` skips npx\'s install prompt so it runs non-interactively; the package is fetched on first use and cached). For heavy use, `npm install -g videodraft`. If there\'s no Node/shell here but the MCP connector below is available, use that instead; if neither works, tell the user how to install (https://videodraft.ai/cli).\\n   - Auth \u2014 pick by context, don\'t guess:\\n     \u2022 INTERACTIVE (a human is in the session, e.g. Claude Code / Codex): on exit code 3 (\\"not authenticated\\"), tell the user to run `videodraft login` in their terminal \u2014 it opens their browser for a one-click VideoDraft sign-in (OAuth), no key to copy. Wait for them to confirm it succeeded, then retry the command. This is the preferred path when the user is present.\\n     \u2022 HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).\\n     \u2022 SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat \u2014 use browser `login` or the env var so the token never lands in the transcript.\\n   - Every command accepts `--json` (parse this, don\'t scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (\u2192 tell the user, don\'t retry).\\n   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.\\n   - Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft upload`, and `videodraft download`.\\n   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args \'<json>\'`.\\n2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly \u2014 the CLI\'s curated commands map 1:1 onto these tools.\\n3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export. Inside VideoDraft ADE on a supported Mac, Claude and Codex receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_control` (`list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.\\n\\nNative editor mutations are revision-guarded. Send them serially and carry forward each result\'s fresh revision. See [references/editor.md](references/editor.md) for project selection, media import, timing units, mutation deltas, verification, export, and the `videodraft-editor` terminal bridge.\\n\\nIf you are reading this skill through `videodraft skills show skill`, run `videodraft skills show editor` before native editor work to load that reference.\\n\\n**VideoDraft ADE routing rule:** the presence of `videodraft_editor` means the native editor is ready, even when no editor window is visible. Use cloud tools to generate or source assets and, when helpful, scripts or storyboards. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` by default. Import the assets into the native project, assemble there, and call native `export_start`. Use hosted production/export only when the user explicitly asks for the web workflow or the native editor tools are unavailable. Do not silently fall back to hosted production after a native tool error.\\n\\n## First decision: asset, hosted project, or native edit?\\n\\n- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.\\n  - `videodraft generate image \\"a red fox in snow, cinematic\\" --ar 16:9 --download ./out/`\\n  - `videodraft generate video \\"slow dolly over a misty lake\\" --model gemini-omni-flash --duration 6 --download ./out/`\\n- **Any final video, production timeline, existing footage, local `.vdproject`, or hands-on edit**: use `videodraft_editor` when available. List or open the intended local project, or create a native project for a new production. The editor can work without showing its UI.\\n- **A small set of related assets**: still stay in the asset lane. Use an AI Studio session if you need to group related generations. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.\\n- **A generated multi-scene video / ad / explainer**: when the editor is available, use hosted tools only for any needed script, storyboard, shot planning, or generated assets; stop before hosted production, import the assets, and build/export the native timeline. A hosted project is optional unless the user wants the web project or its storyboard workflow.\\n- **A hosted web project or hosted export**: use the hosted pipeline only when the user explicitly asks for it or the native editor is unavailable.\\n- **Just a script** (no video asked for): A script-only request creates a script-stage project but stops at the script. Use `videodraft create \\"...\\" --script-only`; do not build a storyboard the user didn\'t ask for.\\n- **Iterating on existing work**: identify the surface first. Use `project_control` with `action:\'list\'` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.\\n\\n## Choose the model from the task\\n\\nIf the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.\\n\\n**Images:**\\n\\n- `nano-banana-2`: general default, editing, consistency, and references.\\n- `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.\\n- `gpt-image-2`: posters, logos, signs, title cards, readable text, or precise composition/editing.\\n\\n**Videos:**\\n\\n- `gemini-omni-flash`: general default up to 10s, first frame/image references, or editing one source video without extra media references. Fixed 720p with audio.\\n- `grok-imagine-video-1.5`: 1-15s text, first-frame, or 1-7 reference-image generation with native audio. Text/first-frame modes support 480p, 720p, and 1080p; reference mode supports 480p/720p. Cite references as `<IMAGE_0>` through `<IMAGE_6>`. It has no last frame, seed, negative prompt, quality tier, reference video, or reference audio.\\n- `minimax-h3`: fixed 2K, native stereo audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total. Cite them as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- `flux-3`: Black Forest Labs FLUX 3. 5-20s at 720p/1080p with 24fps native audio, from a prompt, a first frame, first + last frames, or up to 10 keyframes pinned to specific moments (`--keyframe shot.png@2.5`, repeatable). `--quality draft` renders the same shot at 720p for roughly a third of the cost \u2014 use it to check blocking before committing. Auto duration is text/first-frame only.\\n- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. Use `mini` for cost, `fast` for speed, `standard` for quality or 1080p/4K.\\n- `kling-v3-turbo`: fast polished 3-15s with first frame, multi-prompt, and audio. `kling-o3`: image references, first/last frames, multi-prompt, audio control, or 4K. `kling-3.0`: similar without reference-image mode.\\n- Existing-video edits use `videodraft edit video`, not generic generation. Choose from the `video_edit` catalog category: Grok for simple prompt edits, Wan 2.7 for one style reference or source-matching duration, Happy Horse for up to 5 references, and Kling O3 for controlled reference-image edits.\\n- Kling O3 and Wan 2.7 Ref/Edit also have reference-generation modes. Use `videodraft generate video --model <ref-edit-id>` with `--ref-video`/`--ref` to generate a new guided clip; use `videodraft edit video` when changing the source itself.\\n- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.\\n- Use Veo 3.1 when explicitly requested or as a fallback.\\n\\n**Audio and utilities:**\\n\\n- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and settles at 19 credits per actual minute, with up to 38 credits reserved during generation. The CLI automatically retries transient responses with one operation key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- Prefer ElevenLabs for voiceover, dialogue, voice changing, dubbing, and sound effects. Honor an explicitly selected supported TTS voice/provider. Use Lyria for instrumental music and ElevenLabs Music for vocals, lyrics, or exact timing.\\n- Talking head/presenter: choose by source. Use managed `avatar create` then `avatar render` when the user wants a reusable avatar record and bundled speech. Use `avatar fabric` for a one-off portrait plus text or existing audio. Use `avatar lipsync` when both the source video and replacement audio already exist.\\n- Enhancement: use Topaz image/video upscaling only when the content is already correct. Use image 1x for cleanup, 2x by default, 4x when justified; use video 2x by default. Edit or regenerate creative errors.\\n\\nSee [references/models.md](references/models.md) for the detailed routing table and exact capability limits.\\n\\n## Prefer references when continuity matters\\n\\nPure text-to-image or text-to-video is fine for a generic one-off asset. When a specific character, product, location, style, composition, or brand identity must survive generation, use references instead of hoping the prompt recreates it.\\n\\n- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.\\n- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.\\n- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the native editor instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.\\n\\n## Cost and credits\\n\\nDo not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.\\n\\nFor expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user\'s confirmation preference for the session.\\n\\nMiniMax H3 costs 26 credits per output second. In reference mode the first 5 images are included, each additional image costs 8 credits, and reference video costs 26 credits per verified input second. Audio references are included. For a pre-upload estimate, pass `--ref-video-seconds <total>`; the server measures the actual uploaded video duration before charging.\\n\\nGrok Imagine Video 1.5 costs 8 credits per output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native audio is always generated.\\n\\n`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` lists TTS voices. Consult them instead of guessing capabilities.\\n\\n## Async jobs\\n\\nImage/video generation is asynchronous: commands submit a job and **wait by default**, printing output URLs (and saving files with `--download`). Large downloaded images also get a downscaled copy in `previews/` next to them (the `preview` field / \\"inspect via preview\\" line in the output) \u2014 **look at the preview, deliver the original**; viewing full-resolution images bloats the chat permanently. In scripts/CI prefer explicit control:\\n\\n```bash\\nJOB=$(videodraft generate image \\"...\\" --no-wait --json | jq -r .job_id)\\nvideodraft wait \\"$JOB\\" --download \\"./outputs/{job_id}_{index}.{ext}\\" --json\\n```\\n\\nFor MANY jobs: submit each with `--no-wait`, collect ALL with one command \u2014 `videodraft wait <id1> <id2> ...` polls every job from one process with one batched request per tick. Do NOT spawn parallel `wait`/`generate --wait` processes for a batch.\\n\\nIf a wait times out, the job is still running server-side \u2014 `videodraft status <job_id>` later. Never re-submit just because a wait timed out (that double-spends credits).\\n\\n## Local files and reference images\\n\\nReference inputs must be public URLs. The CLI uploads local files automatically wherever a URL is expected (`--ref photo.jpg`, `--start-image frame.png`), or explicitly:\\n\\n```bash\\nURL=$(videodraft upload ./product.png --json | jq -r .url)\\n```\\n\\nNever silently drop a reference you couldn\'t upload \u2014 stop and tell the user. Never upload a user\'s file to a third-party host.\\n\\nWhen the user attaches media for a native production, import actual footage into the editor by default. For hosted generation/storyboarding, classify each item before acting: a recurring **visual asset** (character/product/location/style), actual **footage to place as shots**, or **inspiration only**. See [references/pipeline.md](references/pipeline.md) for the hosted role mapping.\\n\\n## Showing media to the user\\n\\nGenerated media is **not** displayed in the chat automatically \u2014 you decide what to show. To preview an asset inline, save it locally (use `--download` so it lands under `media/`) and reference its **local path** as a Markdown link with a **leading `./`**:\\n\\n```\\n[ferrari shot](./media/ferrari_01.png)     \u2190 image card\\n[the clip](./media/clip.mp4)               \u2190 video player\\n[voiceover](./media/vo.mp3)                \u2190 audio player\\n```\\n\\nPut the Markdown link **in your message text** \u2014 video and audio embed exactly like images. Do **not** use `SendUserFile` (or other file-send tools) to display media: that renders inside a collapsible tool card and gets buried in the tool list. The Markdown link in your prose is what produces the inline card.\\n\\nUse the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or `./<any-folder>/clip.mp4` \u2014 any folder in the workspace works), or the **absolute** path for a file outside the workspace (e.g. `/Users/you/Desktop/clip.mp4` or another workspace\'s path). Both render. Show the finished results worth showing (and only those \u2014 not every intermediate job). A bare CDN URL or a JSON dump of output URLs does **not** render; the local-path Markdown link is what produces an inline card.\\n\\n## Native-first VideoDraft ADE pipeline (idea \u2192 MP4)\\n\\nWhen `videodraft_editor` is present:\\n\\n1. Generate or source the script, storyboard, shot images, clips, voiceovers, music, and other assets through the cloud CLI/MCP as needed.\\n2. Call native `project_control` to open or create the `.vdproject`.\\n3. Call native `media_import`, wait for imports to become ready, then assemble and refine the timeline with editor tools.\\n4. Call native `export_start` and use `export_status` for progress and results.\\n\\nDo not run the hosted production or export steps in this path unless the user explicitly asks for a web production.\\n\\n## Hosted fallback pipeline (idea \u2192 MP4)\\n\\nUse this only when there is NO native editor at all, or the user explicitly requests the hosted web\\nworkflow. The native surface is not only the injected `videodraft_editor` MCP: a `videodraft-editor`\\nexecutable on PATH is the same editor reached through its terminal bridge, and\\n[references/editor.md](references/editor.md) covers driving it that way. Treating a missing MCP as\\n\\"no editor\\" sends sessions that have the binary into hosted production for no reason.\\n\\n```bash\\nvideodraft create \\"<idea>\\" --ar 9:16            # project: script \u2192 visual assets \u2192 storyboard\\nvideodraft shots <project_id> --grid --estimate # cost preview, confirm with user\\nvideodraft shots <project_id> --grid            # batch shot images (waits, writes onto shot cards)\\nvideodraft produce <project_id>                 # voiceovers + captions + production timeline\\nvideodraft export <project_id> --download final.mp4\\n```\\n\\nOptional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music \\"...\\" --attach <project_id>`), and standalone audio assets (`generate audio`, `generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).\\n\\n## Avatar and talking-head videos (both surfaces)\\n\\nAvatar generation is cloud-only \u2014 the native editor has no avatar or lipsync tools \u2014 so this applies whether or not `videodraft_editor` is present. Generate the avatar in the cloud; in VideoDraft ADE, import the rendered clip and cut it on the native timeline like any other footage.\\n\\nAvatar/talking-head videos use dedicated commands. For a reusable managed avatar, obtain or generate a clear portrait \u2192 `videodraft avatar script` when needed \u2192 `videodraft avatar create` \u2192 `videodraft avatar render --resolution 720p`. For a one-off portrait, use `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.\\n\\n## Working with hosted project data\\n\\nA hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` \u2014 objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace native editor tools when `videodraft_editor` is available for the production itself.\\n\\n## More\\n\\n- [references/pipeline.md](references/pipeline.md) \u2014 hosted fallback data model and production workflow\\n- [references/editor.md](references/editor.md) \u2014 native headless editor routing, project selection, import, timeline edits, verification, and export\\n- [references/models.md](references/models.md) \u2014 choosing image/video models, pricing patterns, voices and styles\\n- [references/examples.md](references/examples.md) \u2014 recipes: batch product videos from a CSV, talking-head from a script, changelog video in CI\\n","references/editor.md":"# Native VideoDraft Editor reference\\n\\nUse this reference when the user wants to assemble, cut, caption, mix, lay out, inspect, or export a local VideoDraft Editor project. The native editor is deterministic and local. Cloud generation remains in the `videodraft` CLI or hosted MCP.\\n\\n## VideoDraft ADE preference rule\\n\\nWhen `videodraft_editor` tools are exposed, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.\\n\\nUse cloud tools for asset generation and optional script/storyboard work, then import the results. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` unless the user explicitly requests an editable web production or the native editor tools are unavailable. If a native tool call fails after the editor was available, report or recover that native failure rather than silently switching surfaces.\\n\\n## Choose the correct surface\\n\\n- `videodraft` and the hosted VideoDraft MCP generate assets and can manage hosted web projects. They use the user\'s VideoDraft account and credits. In VideoDraft ADE, use them mainly as the source of generated media and optional storyboards for the native production.\\n- `videodraft_editor` edits local `.vdproject` packages. It has no generation, account, model, or credit tools.\\n- Inside VideoDraft ADE on a supported Mac, the editor MCP is injected automatically for Claude and Codex in both Code and VideoDraft modes. It starts headlessly before the chat opens. The user does not need to click Open Editor, and closing or hiding the editor window does not stop headless editing.\\n- Outside that environment, use the editor only if `videodraft_editor` MCP tools are already exposed or the `videodraft-editor` executable is on PATH. Do not confuse the public `videodraft` cloud CLI with the separate native editor executable.\\n\\nPrefer the direct MCP tools when they are available. The terminal bridge is useful for scripts, diagnostics, or an agent session where the MCP was not injected.\\n\\n## Start with the intended project\\n\\nAn MCP session can begin without a project selected. Project selection belongs to the session, not to whichever editor window happens to be frontmost.\\n\\n1. If the user named an existing project but its identity is unclear, call `project_control` with `action:\'list\'`.\\n2. Open the exact project by the returned `id`, unambiguous `name`, or `.vdproject` `path`.\\n3. Create only when the user wants a new local edit. `action:\'create\'` accepts optional `name`, `fps`, `aspectRatio`, and `quality`.\\n4. Treat `isActive` as this MCP session\'s target and `isVisible` as the project shown in the UI. Headless editing only needs the session target.\\n5. Use `action:\'close\'` only when closing is part of the task. It saves first and never deletes the project.\\n\\nDo not substitute a hosted project ID for a native project. A hosted project can supply scripts, storyboards, and generated media, but the native edit is a separate `.vdproject` package.\\n\\n## Keep a reliable editing model\\n\\n- Call `timeline_read` once after opening or creating a project, after switching timelines, or after an out-of-band user edit. It returns the revision and current clip/track state.\\n- Call `media_list` before using a `mediaRef`. Poll imports with a filtered read (`ids` for a known asset, `pending:true` for a batch) instead of repeatedly loading the full library.\\n- Timeline placement uses project frames. Source spans, media durations, transcript segments, and search hits use seconds. Pass those values to the relevant tools as returned; do not multiply by fps yourself.\\n- IDs are short stable prefixes. Pass them back exactly as returned. Tracks use stable `trackId` values; indexes can change.\\n- Send project mutations serially. Pass `ifRevision` from the latest read or mutation when available, then replace it with the fresh revision from the next result. Parallel edits against one project can race or invalidate each other\'s revision.\\n- Every mutation returns a delta in `timeline_read` vocabulary. Patch your working model from that delta instead of re-reading after every successful call. Re-read after a stale-state failure or an out-of-band change.\\n- Use `canvas_arrange` for split screens, picture-in-picture, grids, and canvas placement. Use `tracks_edit` to fix stacking. Do not synthesize layouts from generic transforms or keyframes.\\n- Use `media_view` before describing source content, and `transcript_read` to locate a spoken moment. Use `timeline_view` to verify the composited result the viewer will actually see.\\n- Volume inputs, including volume keyframes, are linear values from `0` to `1`. Timeline reads return the same linear scale.\\n\\n## Bring generated or local media into the editor\\n\\nUse cloud generation for new assets, save or download the outputs, then call native `media_import`:\\n\\n- `source.path`: absolute local file or directory. A directory imports recursively and preserves its folder structure.\\n- `source.url`: HTTPS asset URL. Set `mimeType` when a signed URL has no usable extension.\\n- `source.bytes`: small base64 media with a required `mimeType`.\\n- `source.matte`: generated solid-color image.\\n\\nReadiness differs by source, and so does the poll that detects it:\\n\\n- **URL and single-file path** imports return `status:\'downloading\'` with one `mediaRef`. Poll `media_list` with `ids:[mediaRef]` until `generationStatus` is absent.\\n- **Directory** imports return `status:\'preparing\'` once the batch is registered \u2014 not ready. A batch has no single `mediaRef` to poll by, so poll `media_list` with `pending:true` until it reports no unresolved imports.\\n- **Inline bytes and matte** imports finish inline and come back `status:\'ready\'`; no polling needed.\\n\\nNever place a pending asset on the timeline. `generationStatus` is the signal: `preparing` and\\n`downloading` mean keep polling, absent means usable, and **`failed` is terminal** \u2014 report it or\\nretry the import explicitly, never poll on. Do not treat \\"not downloading\\" as ready.\\n\\nFor a batch of local outputs, download them into one workspace directory and import that directory once when practical. This is safer and faster than racing many import calls; just remember it is the `pending:true` poll that tells you when the batch is usable.\\n\\n## Edit and verify\\n\\nUse the tool descriptions as the exact schema. A dependable sequence is:\\n\\n1. `project_control` to select or create the local project.\\n2. `timeline_read` and `media_list` to establish current state.\\n3. `media_view` when content selection matters.\\n4. Serialized clip, track, layout, text, caption, audio, color, effect, or cut mutations using the current revision.\\n5. `timeline_view` when visual composition or layer order matters.\\n6. `undo` if the requested result is wrong and the next mutation would not cleanly correct it.\\n\\nEdits are undoable. Do not ask for confirmation before each ordinary edit. Ask one focused question only when the user\'s creative direction is materially ambiguous.\\n\\n## Export\\n\\n`export_start` queues work in the background and returns a `jobId`, destination, and `started` or `queued` status.\\n\\n- Use `video` for H.264, H.265, or ProRes.\\n- Use `xml` for Premiere Pro.\\n- Use `xml` (XMEML) for Premiere Pro **and DaVinci Resolve** \u2014 Resolve reads XMEML natively.\\n  Use `fcpxml` only for Final Cut Pro. Sending Resolve an FCPXML produces a package it cannot\\n  open cleanly, so the target matters more than the file extension suggests.\\n- Use `videodraft` for a self-contained project package.\\n- Omit `outputPath` unless the user named a destination; the default is `~/Downloads`.\\n- Use `export_status` to list progress, warnings, and results. Cancel only when the user asks or the just-queued settings were wrong. Do not infer that an export is stuck from elapsed time alone.\\n\\n## Terminal bridge\\n\\nVideoDraft desktop terminals expose `videodraft-editor`, which controls the same process and MCP surface:\\n\\n```bash\\nvideodraft-editor status\\nvideodraft-editor list-tools\\nvideodraft-editor tool project_control --json \'{\\"action\\":\\"list\\"}\'\\nvideodraft-editor tool timeline_read --json \'{}\'\\nvideodraft-editor show\\nvideodraft-editor hide\\n```\\n\\nControl and tool commands auto-start a headless editor if none is running. `show` only reveals the already-running UI. Use `videodraft-editor tool <name> --json -` to read a JSON object from stdin when shell quoting would be fragile. Never read, copy, or expose the editor\'s rotating local authentication secret.\\n","references/examples.md":"# Recipes\\n\\nWorking patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.\\n\\nInside VideoDraft ADE, if a native editor is available, use these recipes for asset generation and\\noptional script/storyboard stages. Hand the results to the editor for production and export ONLY\\nwhen the deliverable the user asked for is a composed production. A standalone output \u2014 the batch\\nproduct clips in recipe 1, the upscale in recipe 7 \u2014 is finished when it is generated; importing it\\ninto a project and exporting a timeline builds an edit nobody asked for. Recipes below that call `videodraft produce` or `videodraft export` are hosted fallbacks only. Do not choose them over the available native editor unless the user explicitly asks for the hosted web workflow.\\n\\n## 1. Batch product videos from a CSV\\n\\nOne 9:16 product clip per row of `products.csv` (`name,image_url,tagline`):\\n\\n```bash\\n#!/usr/bin/env bash\\nset -euo pipefail\\nmkdir -p outputs\\n\\nwhile IFS=, read -r name image tagline; do\\n  job=$(videodraft generate video \\\\\\n    \\"Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting.\\" \\\\\\n    --model gemini-omni-flash --ar 9:16 --duration 6 \\\\\\n    --start-image \\"$image\\" \\\\\\n    --no-wait --json | jq -r .job_id)\\n  echo \\"$name,$job\\" >> outputs/jobs.csv\\ndone < <(tail -n +2 products.csv)\\n\\n# Collect ALL results with ONE process (batched polling \u2014 one request per tick)\\nvideodraft wait $(cut -d, -f2 outputs/jobs.csv) \\\\\\n  --download \\"outputs/{job_id}_{index}.{ext}\\" --json > outputs/results.json\\n# map job ids back to product names via outputs/jobs.csv\\n```\\n\\nSubmit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Gemini Omni Flash is selected because these are six-second first-frame product clips. Estimate first: `videodraft costs gemini-omni-flash --type video --duration 6 --resolution 720p --audio` \xD7 rows, and confirm with the user.\\n\\n## 2. Hosted full marketing video from one idea (fallback)\\n\\n```bash\\nvideodraft create \\"30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette.\\" \\\\\\n  --ar 9:16 --style cinematic --json > project.json\\nPROJECT=$(jq -r .project_id project.json)\\n\\nvideodraft shots \\"$PROJECT\\" --grid --estimate          # show the user the cost; get a go-ahead\\nvideodraft shots \\"$PROJECT\\" --grid\\nvideodraft produce \\"$PROJECT\\"\\nvideodraft generate music \\"minimal ambient, warm pads, 60 BPM\\" --attach \\"$PROJECT\\"\\nvideodraft generate audio \\"Extend @Audio1 into a 20-second transition\\" --ref-audio ./intro.wav --format wav --download ./transition.wav\\nvideodraft export \\"$PROJECT\\" --download solace-launch.mp4\\n```\\n\\nUse this complete hosted path only when the user requested a web project or the native editor is unavailable. Otherwise stop after the storyboard/assets, import them into the native `.vdproject`, and export with `export_start`. The hosted project stays editable at the URL in `project.json` (`.urls`).\\n\\n## 3. Talking-head (avatar) video\\n\\nWhen the user has no portrait, generate a clear front-facing avatar image first. Skip this step when they supplied one or an existing character should be reused.\\n\\n```bash\\nvideodraft generate image \\\\\\n  \\"Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background\\" \\\\\\n  --model nano-banana-2 --ar 9:16 --download ./media/avatar.png\\n\\nSCRIPT=$(videodraft avatar script \\"why our espresso subscription saves you money\\" --style ad-style --json | jq -r .script)\\nAVATAR=$(videodraft avatar create ./media/avatar.png --script \\"$SCRIPT\\" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)\\nvideodraft avatar render \\"$AVATAR\\" --resolution 720p   # VEED Fabric paid step; confirm cost first (~20 credits/sec)\\n```\\n\\n`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.\\n\\nIf the portrait is low resolution, enhance it before `avatar create`:\\n\\n```bash\\nvideodraft upscale image ./founder-small.jpg --scale 2x --download ./media/founder-upscaled.png\\n```\\n\\nFor a one-off portrait animation without creating a managed avatar record:\\n\\n```bash\\nvideodraft avatar fabric ./founder.jpg \\\\\\n  --text \\"Welcome to the weekly product update.\\" \\\\\\n  --voice-description \\"warm, confident American presenter\\" \\\\\\n  --resolution 720p --download ./media/presenter.mp4\\n```\\n\\nWhen the user already has both the video and replacement speech:\\n\\n```bash\\nvideodraft avatar lipsync ./presenter.mp4 \\\\\\n  --audio ./localized-voiceover.mp3 \\\\\\n  --sync-mode loop --download ./media/presenter-localized.mp4\\n```\\n\\nEdit an existing video with a dedicated edit model:\\n\\n```bash\\nvideodraft models video --category video_edit\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Turn the room into a warm evening scene while preserving the product and camera motion\\" \\\\\\n  --model wan-2.7-ref-edit --ref ./evening-style.jpg \\\\\\n  --preserve-audio --download ./media/product-demo-evening.mp4\\n```\\n\\nTransfer motion from a reference clip onto a character image:\\n\\n```bash\\nvideodraft edit motion ./character.png \\\\\\n  \\"Apply the dancer\'s movement to this character while preserving identity\\" \\\\\\n  --motion-video ./dance-reference.mp4 \\\\\\n  --model kling-v3-motion-control --quality pro \\\\\\n  --download ./media/character-dance.mp4\\n```\\n\\n## 4. Hosted changelog video in CI\\n\\nIn a GitHub Action with `VIDEODRAFT_API_KEY` set as a secret:\\n\\n```bash\\nNOTES=$(git log --oneline v1.2.0..HEAD | head -20)\\nvideodraft create \\"Weekly product update video. Energetic, 20 seconds. Changes: ${NOTES}\\" --ar 16:9 --json > p.json\\nPROJECT=$(jq -r .project_id p.json)\\nvideodraft shots \\"$PROJECT\\" && videodraft produce \\"$PROJECT\\"\\nvideodraft export \\"$PROJECT\\" --download changelog.mp4 --wait-timeout 30m\\n```\\n\\n## 5. Variations and picking a winner\\n\\n```bash\\nvideodraft generate image \\"logo concept: minimalist fox, geometric\\" --num 4 --download \\"./concepts/{job_id}_{index}.{ext}\\" --json\\n# Show all 4 to the user; regenerate the chosen one at higher res:\\nvideodraft generate image \\"<same prompt>\\" --model nano-banana-pro --resolution 4K\\n```\\n\\n## 6. Reaching tools without a curated command\\n\\n```bash\\nvideodraft tools list --json | jq -r \'.[].name\'\\nvideodraft tools schema attach_media_to_shot --json\\nvideodraft call attach_media_to_shot --args \'{\\"project_id\\":\\"...\\",\\"scene_index\\":0,\\"shot_index\\":1,\\"media_url\\":\\"https://...\\",\\"media_type\\":\\"video\\",\\"duration_seconds\\":6}\'\\n```\\n\\nAnything the hosted VideoDraft MCP exposes, including character studio, product studio, and hosted project data, is reachable this way even before it gets a curated command. Native `.vdproject` editing uses the separate `videodraft_editor` MCP described in SKILL.md.\\n\\n## 7. Enhance an existing asset without changing it\\n\\n```bash\\n# Light image cleanup, no enlargement\\nvideodraft upscale image ./poster.png --scale 1x --download ./media/poster-enhanced.png\\n\\n# General image and video enlargement\\nvideodraft upscale image ./frame.png --scale 2x --download ./media/frame-2x.png\\nvideodraft upscale video ./clip.mp4 --scale 2x --download ./media/clip-2x.mp4\\n```\\n\\nUse these when the content is correct and only quality or resolution needs improvement. If the poster text, composition, subject, or motion is wrong, edit or regenerate instead.\\n","references/models.md":"# Choosing models (and predicting cost)\\n\\nAlways consult the live catalog instead of memorizing this page \u2014 models change weekly:\\n\\n```bash\\nvideodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)\\nvideodraft models video --json     # every video model + inputs + per-second pricing metadata\\nvideodraft models audio --json     # standalone audio/media models + pricing inputs\\nvideodraft models voices --json    # TTS voices\\nvideodraft models styles --json    # visual style presets\\n```\\n\\n## Task-based model selection\\n\\nHonor an explicitly named model when it supports the request. Otherwise choose from the task\'s inputs, duration, audio, quality, speed, and cost. Pass the chosen model explicitly instead of relying on a blind platform fallback.\\n\\n### Images\\n\\n| Need                                                                                   | Choose               | Why                                                               |\\n| -------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------- |\\n| Most generation, editing, character consistency, or reference work                     | `nano-banana-2`      | Best general default; 1K/2K/4K and up to 14 reference images      |\\n| Highest-quality complex generation or reasoning                                        | `nano-banana-pro`    | Premium Nano Banana quality and reasoning                         |\\n| Fast, inexpensive drafts and iteration                                                 | `nano-banana-2-lite` | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |\\n| Posters, title cards, signs, logos, or any image with important readable text          | `gpt-image-2`        | Strong text rendering; up to 16 image inputs and 1K/2K/4K output  |\\n| Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2`        | Strong non-Nano alternative with multi-image input                |\\n\\nUse `--num 1..4` for variations of one prompt in a single call. Never loop separate paid calls for variations that fit in one request.\\n\\n### Videos\\n\\n| Need                                                                                                       | Choose              | Important limits                                                                                    |\\n| ---------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |\\n| Most text, first-frame, image-reference, or source-video-edit requests up to 10s                           | `gemini-omni-flash` | 720p, 3-10s or auto, audio always on, up to 10 total image inputs, one source video                 |\\n| Grok 1.5 text, first-frame, or 1-7 image-reference clips with native audio and optional 1080p              | `grok-imagine-video-1.5` | 1-15s; 480p/720p/1080p for text/first-frame; references are 480p/720p only; no last frame       |\\n| Fixed 2K with native stereo audio, first/last frames, or mixed image/video/audio references                | `minimax-h3`        | 5-15s; up to 9 image, 3 video, 3 audio refs, 12 files total; reference video/audio each total <=15s |\\n| Images pinned to specific moments (keyframes), 16-20s clips, or a cheap draft pass before committing       | `flux-3`            | 5-20s (auto for text/first-frame only); 720p/1080p; up to 10 keyframes; `--quality draft` is 720p-only at ~1/3 the cost |\\n| Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2`        | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only |\\n| Fast polished 3-15s video with first frame, multi-prompt, and native audio                                 | `kling-v3-turbo`    | Audio always on; Pro default; no end frame or reference-media mode                                  |\\n| Cinematic 3-15s with image references, first+last frame, multi-prompt, audio control, or 4K                | `kling-o3`          | Up to 7 image refs; Standard/Pro/4K; audio toggle                                                   |\\n| Kling 3-15s with first+last frame, multi-prompt, optional audio, or 4K, without reference-image mode       | `kling-3.0`         | Standard/Pro/4K; audio toggle                                                                       |\\n| User explicitly requests Veo, or the selected workflow specifically needs Veo                              | `google-veo3.1`     | Good fallback, but not the preferred general model                                                  |\\n\\nRouting rules:\\n\\n- Fixed 2K with native stereo audio: use MiniMax H3.\\n- Grok 1.5 reference mode accepts 1-7 images only. Address them in array order as `<IMAGE_0>` through `<IMAGE_6>`. Do not combine reference images with `--start-image`, `--end-image`, `--ref-video`, or `--ref-audio`.\\n- Grok 1.5 first-frame mode accepts one `--start-image`, derives the output aspect ratio from that image, and does not support `--end-image`. Text and first-frame modes support 480p, 720p, or 1080p. Reference mode supports 480p or 720p.\\n- Grok 1.5 always generates native audio. Do not pass `--no-audio`, `--seed`, `--negative`, or `--quality`.\\n- Around 11-15 seconds with native audio: use MiniMax H3, Kling, or Seedance, not Gemini.\\n- One existing source video that should be edited, with an output up to 10 seconds and no additional media references to preserve: use Gemini Omni Flash.\\n- Video or audio supplied as creative reference: use MiniMax H3 for fixed 2K/native audio, or Seedance 2.0 when resolution/quality tier or audio-toggle control matters.\\n- A video plus any image/audio references that must all be preserved: use MiniMax H3 or Seedance 2.0. Do not promise that Gemini will preserve mixed source media; its Fal BYOK edit mode accepts only the source video and prompt.\\n- First and last frame control: use MiniMax H3, Seedance, Kling O3, or Kling 3.0. Gemini supports a first frame but not a last frame.\\n- MiniMax H3 reference mode and first-plus-last-frame mode are separate. Audio cannot be the only reference. Address references as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.\\n- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.\\n- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K.\\n\\n### Video edit and motion-control categories\\n\\nUse `videodraft models video --category video_edit` for existing-video transforms and `--category motion_control` for motion transfer.\\n\\n| Need                                  | Command/model                                                         | Important limits                                                                 |\\n| ------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |\\n| Simple prompt edit of one video       | `videodraft edit video <video> \\"...\\" --model grok-imagine-video-edit` | No image refs; source truncated to 8s; auto/480p/720p                            |\\n| Edit with one style/reference image   | `--model wan-2.7-ref-edit --ref <image>`                              | One image ref; 2-10s or match source                                             |\\n| Edit with several image references    | `--model happy-horse-video-edit --ref ...`                            | Up to 5 refs; 720p/1080p; source capped at 15s                                   |\\n| Controlled Kling edit                 | `--model kling-o3-video-ref-edit --ref ...`                           | Up to 4 refs; Standard/Pro; source clamped to 3-10s                              |\\n| Transfer reference motion to an image | `videodraft edit motion <image> \\"...\\" --motion-video <video>`         | Kling V3 default; image orientation caps motion at 10s, video orientation at 30s |\\n\\nIf the user explicitly names one of these models, preserve it. The CLI uploads local source videos and reference images automatically. Editing returns an async job and waits by default.\\n\\nKling O3 and Wan 2.7 Ref/Edit are dual-mode cards. `videodraft edit video` uses edit mode. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. `--model wan-2.7-ref-edit` generates a new clip from one or more `--ref`/`--ref-video` inputs.\\n\\n### Reference-first video workflow\\n\\n- Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.\\n- If the user gives a reference, pass it. Never silently replace it with a text description.\\n- If no reference exists and continuity matters, generate a still first with the user\'s explicitly requested compatible image model, otherwise use Nano Banana 2. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.\\n- For multi-shot scenes, generate shot images with `videodraft shots <project_id> --model <selected-image-model> --grid`. Preserve an explicitly requested compatible image model; otherwise use `nano-banana-2`. The grid establishes the scene and characters together, then decodes into individual shot images.\\n- Animate the decoded shot images as per-shot start frames or references. Do not independently text-generate each video clip when the shots need to match.\\n- Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.\\n\\n### Audio\\n\\n- **Seed Audio 1.0**: use `videodraft generate audio` for open-ended speech, sound, music, or prompt-driven audio editing. It accepts up to three audio references or one image. Address audio references as `@Audio1`, `@Audio2`, and `@Audio3`. Preset and custom cloned voice IDs are supported. Output is up to 120 seconds. There is no requested-duration input. The CLI automatically retries transient responses with one idempotency key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- **Voiceover/TTS**: prefer ElevenLabs. Brittney is the platform default voice; under ElevenLabs BYOK, use a compatible voice from the user\'s account. Honor another supported voice/provider when the user explicitly selects it.\\n- **Dialogue, voice changing, and dubbing**: ElevenLabs only.\\n- **Sound effects**: ElevenLabs Sound Effects only.\\n- **Music**: use `lyria-3-clip-preview` for a short instrumental/background score, `lyria-3-pro-preview` for a longer or higher-quality instrumental score, and `elevenlabs-music` when vocals/lyrics or a specified 10-120 second length matter.\\n- Voice Changer and Dubbing require the source media duration and currently accept source media up to 300 seconds.\\n\\n### Avatar / talking head\\n\\nChoose the dedicated path from the media the user already has:\\n\\n| Starting media                            | Command                                                                   | Use                                                 |\\n| ----------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |\\n| Portrait + script, reusable avatar record | `videodraft avatar create <portrait> --script \\"...\\"` then `avatar render` | Managed avatar flow with bundled speech preparation |\\n| Portrait + text                           | `videodraft avatar fabric <portrait> --text \\"...\\"`                        | One-off direct VEED Fabric text mode                |\\n| Portrait + existing audio                 | `videodraft avatar fabric <portrait> --audio <audio>`                     | One-off direct VEED Fabric audio lip sync           |\\n| Existing video + existing audio           | `videodraft avatar lipsync <video> --audio <audio>`                       | Sync Labs Lipsync 2                                 |\\n\\nThe managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric and Sync Labs are paid AI Studio generations and return async job IDs.\\n\\n1. Obtain the avatar image. Prefer the user\'s supplied portrait or an existing character. If none exists, use the user\'s explicitly requested compatible image model, otherwise generate a front-facing head-and-shoulders portrait with `nano-banana-2`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.\\n2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.\\n3. Generate a script only if needed: `videodraft avatar script \\"<idea>\\"`.\\n4. Create the avatar record and speech: `videodraft avatar create <portrait-url-or-file> --script \\"...\\" --voice <id> --ar 9:16`. Prefer ElevenLabs when unspecified, but honor another explicitly selected supported voice/provider.\\n5. Render with VEED Fabric: `videodraft avatar render <avatar_video_id> --resolution 720p`.\\n\\nThe portrait is passed as the avatar\'s character image, not as a generic video\'s start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.\\n\\nDirect Fabric text/audio and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. Sync costs 5 credits per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.\\n\\n### Upscaling / enhancement\\n\\n- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The result is synchronous.\\n- **Videos**: Topaz via `videodraft upscale video <url-or-file> --scale 2x`. Use 2x by default. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.\\n- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems.\\n- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.\\n\\n## Capability gotchas\\n\\n- Each model\'s `inputs` block is authoritative: supported `aspect_ratios`, `resolutions`, `quality_options`, `start_frame`/`end_frame`, `max_reference_images/videos/audio`, `multi_prompt`, `audio_toggle`. Passing an unsupported input fails with a clear error \u2014 check first, don\'t trial-and-error paid calls.\\n- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.\\n- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4); everything else ignores it. You do not need a seed for variation \u2014 `--num` already varies.\\n- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost \u2014 pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.\\n- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.\\n- Reference inputs: `--ref <img>` (images, including up to 7 for Grok 1.5), `--ref-video <v>` (Gemini Omni Flash, MiniMax H3, Seedance 2, Wan 2.7), `--ref-audio <a>` (MiniMax H3, Seedance 2). The CLI uploads local files for all of these, so you can pass a path or a URL. For an exact MiniMax H3 pre-upload estimate, add `--ref-video-seconds <combined-seconds>`; the server measures actual duration before charging a real job. `--segment \\"<prompt>:<seconds>\\"` (repeatable) drives multi-prompt models (Kling 3.0 / 3.0 Turbo / O3); total 3-15s. `generate image --video-ref` is the nano-banana-2 video reference.\\n- The top-level prompt is OPTIONAL for `generate video` with multi-prompt models and for Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video \u2014 a `--segment`-only or `--start-image`-only call is valid. Every other model still needs a prompt; the server enforces per-model rules.\\n- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.\\n\\n## Cost model\\n\\n- Images: per image (\xD7 `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.\\n- Video: usually credits/second \xD7 duration; rate depends on model + resolution + quality + native audio on/off.\\n- MiniMax H3: 26 credits/output second. The first 5 reference images are included, then 8 credits for each additional image. Reference video adds 26 credits/input second; reference audio is included.\\n- Grok Imagine Video 1.5: 8 credits/output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native generated audio is part of every output.\\n- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) \u2014 the largest single spend in the pipeline.\\n- VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.\\n- Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.\\n- Sync Labs Lipsync 2: 5 credits per verified audio second.\\n- Voiceover TTS: 10 credits per 1000 characters for standard voices, 30 per 1000 for cloned `custom-*` voices (min 1, pro-rated); applies to standalone voiceovers AND per-scene narration during `produce`. Silent tracks are free. Voice cloning itself is a flat 150 credits per clone.\\n- Lyria music: flat per track, 10 credits (clip) / 15 credits (pro).\\n- Seed Audio 1.0: 19 credits per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum of 38 credits and refunds the unused portion after generation. Fal BYOK is free.\\n- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. Voice changer and dubbing reject source media above 300s in the current synchronous flow.\\n- Upscales: priced by scale and source size.\\n\\nQuote before spending:\\n\\n```bash\\nvideodraft costs gemini-omni-flash --type video --duration 8 --resolution 720p --audio\\nvideodraft costs minimax-h3 --type video --duration 10 --ref-images 7 --ref-video-seconds 5\\nvideodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio\\nvideodraft costs elevenlabs-dubbing --type audio --duration 60\\nvideodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length\\nvideodraft costs elevenlabs-dialogue --type audio --chars 350\\nvideodraft costs voiceover --type audio --chars 800    # TTS: 10 cr / 1000 chars\\nvideodraft generate video \\"...\\" --model gemini-omni-flash --estimate # same quote, inline\\n```\\n","references/pipeline.md":"# VideoDraft pipeline reference\\n\\nEverything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks). When the local `videodraft_editor` MCP is available, do not use hosted production or export by default. Use hosted tools only for asset generation and optional script/storyboard stages, then import the results and finish with the native editor reference linked from SKILL.md. Continue through `produce_project` and `export_video` only when the user explicitly requests a hosted web production or the native editor is unavailable.\\n\\nUse direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable. Script-only uses a script-stage project and stops at the script. In VideoDraft ADE with editor tools present, stop before hosted production, import the generated assets, and build/export the native project.\\n\\n## Stages and their tools\\n\\n| Stage                                   | CLI                                                                         | Underlying tool                            |\\n| --------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------ |\\n| Idea \u2192 full storyboard project          | `videodraft create \\"<idea>\\"`                                                | `generate_storyboard_from_idea`            |\\n| Idea \u2192 script only (stop there)         | `videodraft create \\"<idea>\\" --script-only`                                  | `generate_script_from_idea`                |\\n| Footage IS the video                    | `videodraft call generate_storyboard_from_media`                            | `generate_storyboard_from_media`           |\\n| Batch shot images                       | `videodraft shots <project>`                                                | `generate_shot_images`                     |\\n| One shot image                          | `videodraft generate image --project <id> --scene N --shot M`               | `generate_image`                           |\\n| Produce (voiceover, captions, timeline) | `videodraft produce <project>`                                              | `produce_project`                          |\\n| Per-shot motion prompts                 | `videodraft video-prompts <project>`                                        | `generate_video_prompts`                   |\\n| Motion clip for a shot                  | `videodraft generate video --project <id>`                                  | `generate_video`                           |\\n| Attach a finished clip to the timeline  | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot`                     |\\n| Background music                        | `videodraft generate music --attach <project>`                              | `generate_music` / `set_background_music`  |\\n| General or reference-driven audio       | `videodraft generate audio \\"...\\"`                                          | `generate_audio`                           |\\n| Sound effect                            | `videodraft generate sound-effect \\"...\\"`                                    | `generate_sound_effect`                    |\\n| Dialogue audio                          | `videodraft generate dialogue --line \\"voice:text\\"`                          | `generate_dialogue`                        |\\n| Voice changer                           | `videodraft generate voice-changer <audio>`                                 | `change_voice`                             |\\n| Dubbing                                 | `videodraft generate dub <audio_or_video>`                                  | `dub_media`                                |\\n| Scene voiceover                         | `videodraft generate voiceover --project <id> --scene N`                    | `generate_voiceover`                       |\\n| Avatar script                           | `videodraft avatar script \\"<idea>\\"`                                         | `generate_avatar_script`                   |\\n| Avatar + speech                         | `videodraft avatar create <portrait> --script \\"...\\"`                        | `create_avatar_video`                      |\\n| Talking-head render                     | `videodraft avatar render <avatar_video_id>`                                | `render_avatar_video` + `get_avatar_video` |\\n| Direct portrait + text/audio            | `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`      | `generate_veed_fabric_video`               |\\n| Existing video + replacement audio      | `videodraft avatar lipsync <video> --audio <file>`                          | `generate_sync_lipsync_video`              |\\n| Existing-video AI edit                  | `videodraft edit video <video> \\"<change>\\" --model <video-edit-model>`       | `edit_video`                               |\\n| Motion transfer                         | `videodraft edit motion <image> \\"<direction>\\" --motion-video <video>`       | `generate_motion_control_video`            |\\n| Image enhancement/upscale               | `videodraft upscale image <image>`                                          | `upscale_image`                            |\\n| Video enhancement/upscale               | `videodraft upscale video <video>`                                          | `upscale_video`                            |\\n| Final MP4                               | `videodraft export <project>`                                               | `export_video` + `check_export_status`     |\\n\\n## Rules that prevent broken results\\n\\n- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don\'t call `generate_storyboard_scenes` with a raw idea as the \\"script\\".\\n- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project\'s visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project\'s visual assets and/or the previous shot\'s image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.\\n- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.\\n- **Hold off generating shot images while the user is still iterating** on storyboard structure.\\n- **produce \u2192 export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.\\n- **Do not attach motion clips before production exists**: run `produce` successfully first, then attach finished motion clips to the production timeline. Attaching before `production_data` exists cannot place them in the final timeline.\\n- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:\\"video\\"`, include `duration_seconds`) \u2014 it replaces the production timeline clip while keeping the storyboard still.\\n- **Talking heads use dedicated avatar tools**: do not use `generate video`. Use managed `avatar create` and `avatar render` for reusable avatars, direct `avatar fabric` for a portrait plus text/audio, and `avatar lipsync` for an existing video plus replacement audio. Reuse a supplied person image or generate a clear front-facing portrait with the explicitly requested compatible image model, otherwise Nano Banana 2. Managed avatar creation and speech are bundled/free; direct Fabric, Sync, and render are paid.\\n- **Existing-video edits use their own category**: call `edit_video` or `videodraft edit video` with a `video_edit` model when transforming the source itself. Kling O3 and Wan 2.7 Ref/Edit are dual-mode: their reference-generation modes may use generic `generate_video` to create a new guided clip. Motion transfer similarly uses `generate_motion_control_video` or `videodraft edit motion` with a `motion_control` model.\\n- **Upscaling preserves rather than redesigns**: use Topaz when resolution, detail, or cleanup is the problem. Regenerate or edit when the subject, text, framing, continuity, or motion is wrong. Upscale a low-quality avatar portrait before Fabric; do not render a new avatar at 480p just to upscale the result.\\n- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side \u2014 `videodraft projects list`, take the most recent, and resume with its id. Don\'t start a duplicate.\\n\\n## User-attached media: classify roles first\\n\\nFor EACH attached file decide:\\n\\n- **visual_asset** \u2014 recurring reference (character / product / location / style). Upload, then pass in `visual_assets` of `generate_storyboard_from_idea` (via `videodraft call`), or add to an existing project with `add_visual_assets`. Type must be one of `character | object | location | style | custom` with a short name + concrete description.\\n- **shot** \u2014 the media IS footage for the video. Whole video = footage \u2192 `generate_storyboard_from_media`. Idea + footage \u2192 `generate_storyboard_from_idea` with `shot_media`. Existing storyboard \u2192 `attach_media_to_shots`.\\n- **reference** \u2014 inspiration only \u2192 fold a description into the idea/instructions; don\'t place it as a shot or asset.\\n\\nAmbiguous (e.g. a person holding a product)? Ask the user.\\n\\nUploads persist in the media library \u2014 recall later with `videodraft media list`.\\n\\n## Editing project data safely\\n\\n1. `videodraft call get_project_schema` \u2014 read the structure once per session.\\n2. `videodraft projects get <id> --raw` \u2014 the exact editable blob.\\n3. Modify; then `videodraft call update_project --stdin` with `{\\"project_id\\": \\"...\\", \\"data\\": {...}}`.\\n   - Objects deep-merge key-by-key; **arrays replace wholesale** \u2014 send the complete array you\'re changing (e.g. all of `storyboard.scenes`).\\n   - Scene shot arrays (`image_prompt` / `shot_types` / `shot_actions` / `search_prompt` / `preview_media`) are auto-aligned; fix-ups come back as warnings.\\n4. Snapshot before risky edits: `videodraft checkpoint create <id> --name \\"before re-script\\"`. Restore with `videodraft checkpoint restore <id> <version>`.\\n\\n## AI Studio sessions (standalone generations)\\n\\nProject generations group automatically. For standalone work in a long conversation, create one session up front and reuse it:\\n\\n```bash\\nSESSION=$(videodraft call create_ai_studio_session --arg name=\\"Fox brand explorations\\" --json | jq -r .session_id)\\nvideodraft generate image \\"...\\" --session \\"$SESSION\\"\\n```\\n"}') {
+    return JSON.parse('{"SKILL.md":"---\\nname: videodraft\\ndescription: Create and edit AI videos, images, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers the cloud `videodraft` CLI/MCP and local headless `videodraft_editor` MCP. When the editor MCP is exposed, prefer it for production, timeline assembly, and export; use cloud production/export only when explicitly requested or the editor is unavailable.\\n---\\n\\n# VideoDraft\\n\\nVideoDraft is an AI video creation platform where asset generation is the priority lane:\\n\\n- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.\\n- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.\\n- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane whenever `videodraft_editor` is available.\\n- **Hosted project production**: idea \u2192 script \u2192 storyboard \u2192 hosted production timeline \u2192 exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.\\n\\n## How to connect\\n\\nCloud generation has two equivalent surfaces (same backend, credits, and hosted projects). Native timeline editing is a separate local surface:\\n\\n1. **CLI** (preferred when you have a shell): run `videodraft` if it\'s on PATH; otherwise `npx -y videodraft@latest` runs it with no install (needs Node \u226520; the `-y` skips npx\'s install prompt so it runs non-interactively; the package is fetched on first use and cached). For heavy use, `npm install -g videodraft`. If there\'s no Node/shell here but the MCP connector below is available, use that instead; if neither works, tell the user how to install (https://videodraft.ai/cli).\\n   - Auth \u2014 pick by context, don\'t guess:\\n     \u2022 INTERACTIVE (a human is in the session, e.g. Claude Code / Codex): on exit code 3 (\\"not authenticated\\"), tell the user to run `videodraft login` in their terminal \u2014 it opens their browser for a one-click VideoDraft sign-in (OAuth), no key to copy. Wait for them to confirm it succeeded, then retry the command. This is the preferred path when the user is present.\\n     \u2022 HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).\\n     \u2022 SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat \u2014 use browser `login` or the env var so the token never lands in the transcript.\\n   - Every command accepts `--json` (parse this, don\'t scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (\u2192 tell the user, don\'t retry).\\n   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.\\n   - Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft upload`, and `videodraft download`.\\n   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args \'<json>\'`.\\n2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly \u2014 the CLI\'s curated commands map 1:1 onto these tools.\\n3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export. Inside VideoDraft ADE on a supported Mac, Claude and Codex receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_control` (`list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.\\n\\nNative editor mutations are revision-guarded. Send them serially and carry forward each result\'s fresh revision. See [references/editor.md](references/editor.md) for project selection, media import, timing units, mutation deltas, verification, export, and the `videodraft-editor` terminal bridge.\\n\\nIf you are reading this skill through `videodraft skills show skill`, run `videodraft skills show editor` before native editor work to load that reference.\\n\\n**VideoDraft ADE routing rule:** the presence of `videodraft_editor` means the native editor is ready, even when no editor window is visible. Use cloud tools to generate or source assets and, when helpful, scripts or storyboards. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` by default. Import the assets into the native project, assemble there, and call native `export_start`. Use hosted production/export only when the user explicitly asks for the web workflow or the native editor tools are unavailable. Do not silently fall back to hosted production after a native tool error.\\n\\n## First decision: asset, hosted project, or native edit?\\n\\n- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.\\n  - `videodraft generate image \\"a red fox in snow, cinematic\\" --ar 16:9 --download ./out/`\\n  - `videodraft generate video \\"slow dolly over a misty lake\\" --model gemini-omni-flash --duration 6 --download ./out/`\\n- **Any final video, production timeline, existing footage, local `.vdproject`, or hands-on edit**: use `videodraft_editor` when available. List or open the intended local project, or create a native project for a new production. The editor can work without showing its UI.\\n- **A small set of related assets**: still stay in the asset lane. Use an AI Studio session if you need to group related generations. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.\\n- **A generated multi-scene video / ad / explainer**: when the editor is available, use hosted tools only for any needed script, storyboard, shot planning, or generated assets; stop before hosted production, import the assets, and build/export the native timeline. A hosted project is optional unless the user wants the web project or its storyboard workflow.\\n- **A hosted web project or hosted export**: use the hosted pipeline only when the user explicitly asks for it or the native editor is unavailable.\\n- **Just a script** (no video asked for): A script-only request creates a script-stage project but stops at the script. Use `videodraft create \\"...\\" --script-only`; do not build a storyboard the user didn\'t ask for.\\n- **Iterating on existing work**: identify the surface first. Use `project_control` with `action:\'list\'` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.\\n\\n## Choose the model from the task\\n\\nIf the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.\\n\\n**Images:**\\n\\n- `nano-banana-2`: general default, editing, consistency, and references.\\n- `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.\\n- `gpt-image-2`: posters, logos, signs, title cards, readable text, or precise composition/editing.\\n\\n**Videos:**\\n\\n- `gemini-omni-flash`: general default up to 10s, first frame/image references, or editing one source video without extra media references. Fixed 720p with audio.\\n- `grok-imagine-video-1.5`: 1-15s text, first-frame, or 1-7 reference-image generation with native audio. Text/first-frame modes support 480p, 720p, and 1080p; reference mode supports 480p/720p. Cite references as `<IMAGE_0>` through `<IMAGE_6>`. It has no last frame, seed, negative prompt, quality tier, reference video, or reference audio.\\n- `minimax-h3`: fixed 2K, native stereo audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total. Cite them as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- `flux-3`: Black Forest Labs FLUX 3. 5-20s at 720p/1080p with 24fps native audio, from a prompt, a first frame, first + last frames, or up to 10 keyframes pinned to specific moments (`--keyframe shot.png@2.5`, repeatable). `--quality draft` renders the same shot at 720p for roughly a third of the cost \u2014 use it to check blocking before committing. Auto duration is text/first-frame only.\\n- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. Use `mini` for cost, `fast` for speed, `standard` for quality or 1080p/4K.\\n- `kling-v3-turbo`: fast polished 3-15s with first frame, multi-prompt, and audio. `kling-o3`: image references, first/last frames, multi-prompt, audio control, or 4K. `kling-3.0`: similar without reference-image mode.\\n- Existing-video edits use `videodraft edit video`, not generic generation. Choose from the `video_edit` catalog category: Grok for simple prompt edits, Wan 2.7 for one style reference or source-matching duration, Happy Horse for up to 5 references, and Kling O3 for controlled reference-image edits.\\n- Kling O3 and Wan 2.7 Ref/Edit also have reference-generation modes. Use `videodraft generate video --model <ref-edit-id>` with `--ref-video`/`--ref` to generate a new guided clip; use `videodraft edit video` when changing the source itself.\\n- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.\\n- Use Veo 3.1 when explicitly requested or as a fallback.\\n\\n**Audio and utilities:**\\n\\n- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and settles at 19 credits per actual minute, with up to 38 credits reserved during generation. The CLI automatically retries transient responses with one operation key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- Prefer ElevenLabs for voiceover, dialogue, voice changing, dubbing, and sound effects. Honor an explicitly selected supported TTS voice/provider. Use Lyria for instrumental music and ElevenLabs Music for vocals, lyrics, or exact timing.\\n- Talking head/presenter: choose by source. Use managed `avatar create` then `avatar render` when the user wants a reusable avatar record and bundled speech. Use `avatar fabric` for a one-off portrait plus text or existing audio. Use `avatar lipsync` when both the source video and replacement audio already exist.\\n- Enhancement: use Topaz image/video upscaling only when the content is already correct. Use image 1x for cleanup, 2x by default, 4x when justified; use video 2x by default. Edit or regenerate creative errors.\\n\\nSee [references/models.md](references/models.md) for the detailed routing table and exact capability limits.\\n\\n## Prefer references when continuity matters\\n\\nPure text-to-image or text-to-video is fine for a generic one-off asset. When a specific character, product, location, style, composition, or brand identity must survive generation, use references instead of hoping the prompt recreates it.\\n\\n- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.\\n- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.\\n- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the native editor instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.\\n\\n## Cost and credits\\n\\nDo not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.\\n\\nFor expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user\'s confirmation preference for the session.\\n\\nMiniMax H3 costs 26 credits per output second. In reference mode the first 5 images are included, each additional image costs 8 credits, and reference video costs 26 credits per verified input second. Audio references are included. For a pre-upload estimate, pass `--ref-video-seconds <total>`; the server measures the actual uploaded video duration before charging.\\n\\nGrok Imagine Video 1.5 costs 8 credits per output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native audio is always generated.\\n\\n`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` lists TTS voices. Consult them instead of guessing capabilities.\\n\\n## Async jobs\\n\\nImage/video generation is asynchronous: commands submit a job and **wait by default**, printing output URLs (and saving files with `--download`). Large downloaded images also get a downscaled copy in `previews/` next to them (the `preview` field / \\"inspect via preview\\" line in the output) \u2014 **look at the preview, deliver the original**; viewing full-resolution images bloats the chat permanently. In scripts/CI prefer explicit control:\\n\\n```bash\\nJOB=$(videodraft generate image \\"...\\" --no-wait --json | jq -r .job_id)\\nvideodraft wait \\"$JOB\\" --download \\"./outputs/{job_id}_{index}.{ext}\\" --json\\n```\\n\\nFor MANY jobs: submit each with `--no-wait`, collect ALL with one command \u2014 `videodraft wait <id1> <id2> ...` polls every job from one process with one batched request per tick. Do NOT spawn parallel `wait`/`generate --wait` processes for a batch.\\n\\nIf a wait times out, the job is still running server-side \u2014 `videodraft status <job_id>` later. Never re-submit just because a wait timed out (that double-spends credits).\\n\\n## Local files and reference images\\n\\nReference inputs must be public URLs. The CLI uploads local files automatically wherever a URL is expected (`--ref photo.jpg`, `--start-image frame.png`), or explicitly:\\n\\n```bash\\nURL=$(videodraft upload ./product.png --json | jq -r .url)\\n```\\n\\nNever silently drop a reference you couldn\'t upload \u2014 stop and tell the user. Never upload a user\'s file to a third-party host.\\n\\nWhen the user attaches media for a native production, import actual footage into the editor by default. For hosted generation/storyboarding, classify each item before acting: a recurring **visual asset** (character/product/location/style), actual **footage to place as shots**, or **inspiration only**. See [references/pipeline.md](references/pipeline.md) for the hosted role mapping.\\n\\n## Showing media to the user\\n\\nGenerated media is **not** displayed in the chat automatically \u2014 you decide what to show. To preview an asset inline, save it locally (use `--download` so it lands under `media/`) and reference its **local path** as a Markdown link with a **leading `./`**:\\n\\n```\\n[ferrari shot](./media/ferrari_01.png)     \u2190 image card\\n[the clip](./media/clip.mp4)               \u2190 video player\\n[voiceover](./media/vo.mp3)                \u2190 audio player\\n```\\n\\nPut the Markdown link **in your message text** \u2014 video and audio embed exactly like images. Do **not** use `SendUserFile` (or other file-send tools) to display media: that renders inside a collapsible tool card and gets buried in the tool list. The Markdown link in your prose is what produces the inline card.\\n\\nUse the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or `./<any-folder>/clip.mp4` \u2014 any folder in the workspace works), or the **absolute** path for a file outside the workspace (e.g. `/Users/you/Desktop/clip.mp4` or another workspace\'s path). Both render. Show the finished results worth showing (and only those \u2014 not every intermediate job). A bare CDN URL or a JSON dump of output URLs does **not** render; the local-path Markdown link is what produces an inline card.\\n\\n## Native-first VideoDraft ADE pipeline (idea \u2192 MP4)\\n\\nWhen `videodraft_editor` is present:\\n\\n1. Generate or source the script, storyboard, shot images, clips, voiceovers, music, and other assets through the cloud CLI/MCP as needed.\\n2. Call native `project_control` to open or create the `.vdproject`.\\n3. Call native `media_import`, wait for imports to become ready, then assemble and refine the timeline with editor tools.\\n4. Call native `export_start` and use `export_status` for progress and results.\\n\\nDo not run the hosted production or export steps in this path unless the user explicitly asks for a web production.\\n\\n## Hosted fallback pipeline (idea \u2192 MP4)\\n\\nUse this only when there is NO native editor at all, or the user explicitly requests the hosted web\\nworkflow. The native surface is not only the injected `videodraft_editor` MCP: a `videodraft-editor`\\nexecutable on PATH is the same editor reached through its terminal bridge, and\\n[references/editor.md](references/editor.md) covers driving it that way. Treating a missing MCP as\\n\\"no editor\\" sends sessions that have the binary into hosted production for no reason.\\n\\n```bash\\nvideodraft create \\"<idea>\\" --ar 9:16            # project: script \u2192 visual assets \u2192 storyboard\\nvideodraft shots <project_id> --grid --estimate # cost preview, confirm with user\\nvideodraft shots <project_id> --grid            # batch shot images (waits, writes onto shot cards)\\nvideodraft produce <project_id>                 # voiceovers + captions + production timeline\\nvideodraft export <project_id> --download final.mp4\\n```\\n\\nOptional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music \\"...\\" --attach <project_id>`), and standalone audio assets (`generate audio`, `generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).\\n\\n## Avatar and talking-head videos (both surfaces)\\n\\nAvatar generation is cloud-only \u2014 the native editor has no avatar or lipsync tools \u2014 so this applies whether or not `videodraft_editor` is present. Generate the avatar in the cloud; in VideoDraft ADE, import the rendered clip and cut it on the native timeline like any other footage.\\n\\nAvatar/talking-head videos use dedicated commands. For a reusable managed avatar, obtain or generate a clear portrait \u2192 `videodraft avatar script` when needed \u2192 `videodraft avatar create` \u2192 `videodraft avatar render --resolution 720p`. For a one-off portrait, use `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.\\n\\n## Working with hosted project data\\n\\nA hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` \u2014 objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace native editor tools when `videodraft_editor` is available for the production itself.\\n\\n## More\\n\\n- [references/pipeline.md](references/pipeline.md) \u2014 hosted fallback data model and production workflow\\n- [references/editor.md](references/editor.md) \u2014 native headless editor routing, project selection, import, timeline edits, verification, and export\\n- [references/models.md](references/models.md) \u2014 choosing image/video models, pricing patterns, voices and styles\\n- [references/examples.md](references/examples.md) \u2014 recipes: batch product videos from a CSV, talking-head from a script, changelog video in CI\\n","references/editor.md":"# Native VideoDraft Editor reference\\n\\nUse this reference when the user wants to assemble, cut, caption, mix, lay out, inspect, or export a local VideoDraft Editor project. The native editor is deterministic and local. Cloud generation remains in the `videodraft` CLI or hosted MCP.\\n\\n## VideoDraft ADE preference rule\\n\\nWhen `videodraft_editor` tools are exposed, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.\\n\\nUse cloud tools for asset generation and optional script/storyboard work, then import the results. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` unless the user explicitly requests an editable web production or the native editor tools are unavailable. If a native tool call fails after the editor was available, report or recover that native failure rather than silently switching surfaces.\\n\\n## Choose the correct surface\\n\\n- `videodraft` and the hosted VideoDraft MCP generate assets and can manage hosted web projects. They use the user\'s VideoDraft account and credits. In VideoDraft ADE, use them mainly as the source of generated media and optional storyboards for the native production.\\n- `videodraft_editor` edits local `.vdproject` packages. It has no generation, account, model, or credit tools.\\n- Inside VideoDraft ADE on a supported Mac, the editor MCP is injected automatically for Claude and Codex in both Code and VideoDraft modes. It starts headlessly before the chat opens. The user does not need to click Open Editor, and closing or hiding the editor window does not stop headless editing.\\n- Outside that environment, use the editor only if `videodraft_editor` MCP tools are already exposed or the `videodraft-editor` executable is on PATH. Do not confuse the public `videodraft` cloud CLI with the separate native editor executable.\\n\\nPrefer the direct MCP tools when they are available. The terminal bridge is useful for scripts, diagnostics, or an agent session where the MCP was not injected.\\n\\n## Start with the intended project\\n\\nAn MCP session can begin without a project selected. Project selection belongs to the session, not to whichever editor window happens to be frontmost.\\n\\n1. If the user named an existing project but its identity is unclear, call `project_control` with `action:\'list\'`.\\n2. Open the exact project by the returned `id`, unambiguous `name`, or `.vdproject` `path`.\\n3. Create only when the user wants a new local edit. `action:\'create\'` accepts optional `name`, `fps`, `aspectRatio`, and `quality`.\\n4. Treat `isActive` as this MCP session\'s target and `isVisible` as the project shown in the UI. Headless editing only needs the session target.\\n5. Use `action:\'close\'` only when closing is part of the task. It saves first and never deletes the project.\\n\\nDo not substitute a hosted project ID for a native project. A hosted project can supply scripts, storyboards, and generated media, but the native edit is a separate `.vdproject` package.\\n\\n## Keep a reliable editing model\\n\\n- Call `timeline_read` once after opening or creating a project, after switching timelines, or after an out-of-band user edit. It returns the revision and current clip/track state.\\n- Call `media_list` before using a `mediaRef`. Poll imports with a filtered read (`ids` for a known asset, `pending:true` for a batch) instead of repeatedly loading the full library.\\n- Timeline placement uses project frames. Source spans, media durations, transcript segments, and search hits use seconds. Pass those values to the relevant tools as returned; do not multiply by fps yourself.\\n- IDs are short stable prefixes. Pass them back exactly as returned. Tracks use stable `trackId` values; indexes can change.\\n- Send project mutations serially. Pass `ifRevision` from the latest read or mutation when available, then replace it with the fresh revision from the next result. Parallel edits against one project can race or invalidate each other\'s revision.\\n- Every mutation returns a delta in `timeline_read` vocabulary. Patch your working model from that delta instead of re-reading after every successful call. Re-read after a stale-state failure or an out-of-band change.\\n- Use `canvas_arrange` for split screens, picture-in-picture, grids, and canvas placement. Use `tracks_edit` to fix stacking. Do not synthesize layouts from generic transforms or keyframes.\\n- Use `media_view` before describing source content, and `transcript_read` to locate a spoken moment. Use `timeline_view` to verify the composited result the viewer will actually see.\\n- Volume inputs, including volume keyframes, are linear values from `0` to `1`. Timeline reads return the same linear scale.\\n\\n## Bring generated or local media into the editor\\n\\nUse cloud generation for new assets, save or download the outputs, then call native `media_import`:\\n\\n- `source.path`: absolute local file or directory. A directory imports recursively and preserves its folder structure.\\n- `source.url`: HTTPS asset URL. Set `mimeType` when a signed URL has no usable extension.\\n- `source.bytes`: small base64 media with a required `mimeType`.\\n- `source.matte`: generated solid-color image.\\n\\nReadiness differs by source, and so does the poll that detects it:\\n\\n- **URL and single-file path** imports return `status:\'downloading\'` with one `mediaRef`. Poll `media_list` with `ids:[mediaRef]` until `generationStatus` is absent.\\n- **Directory** imports return `status:\'preparing\'` once the batch is registered \u2014 not ready. A batch has no single `mediaRef` to poll by, so poll `media_list` with `pending:true` until it reports no unresolved imports.\\n- **Inline bytes and matte** imports finish inline and come back `status:\'ready\'`; no polling needed.\\n\\nNever place a pending asset on the timeline. `generationStatus` is the signal: `preparing` and\\n`downloading` mean keep polling, absent means usable, and **`failed` is terminal** \u2014 report it or\\nretry the import explicitly, never poll on. Do not treat \\"not downloading\\" as ready.\\n\\nFor a batch of local outputs, download them into one workspace directory and import that directory once when practical. This is safer and faster than racing many import calls; just remember it is the `pending:true` poll that tells you when the batch is usable.\\n\\n## Edit and verify\\n\\nUse the tool descriptions as the exact schema. A dependable sequence is:\\n\\n1. `project_control` to select or create the local project.\\n2. `timeline_read` and `media_list` to establish current state.\\n3. `media_view` when content selection matters.\\n4. Serialized clip, track, layout, text, caption, audio, color, effect, or cut mutations using the current revision.\\n5. `timeline_view` when visual composition or layer order matters.\\n6. `undo` if the requested result is wrong and the next mutation would not cleanly correct it.\\n\\nEdits are undoable. Do not ask for confirmation before each ordinary edit. Ask one focused question only when the user\'s creative direction is materially ambiguous.\\n\\n## Export\\n\\n`export_start` queues work in the background and returns a `jobId`, destination, and `started` or `queued` status.\\n\\n- Use `video` for H.264, H.265, or ProRes.\\n- Use `xml` for Premiere Pro.\\n- Use `xml` (XMEML) for Premiere Pro **and DaVinci Resolve** \u2014 Resolve reads XMEML natively.\\n  Use `fcpxml` only for Final Cut Pro. Sending Resolve an FCPXML produces a package it cannot\\n  open cleanly, so the target matters more than the file extension suggests.\\n- Use `videodraft` for a self-contained project package.\\n- Omit `outputPath` unless the user named a destination; the default is `~/Downloads`.\\n- Use `export_status` to list progress, warnings, and results. Cancel only when the user asks or the just-queued settings were wrong. Do not infer that an export is stuck from elapsed time alone.\\n\\n## Terminal bridge\\n\\nVideoDraft desktop terminals expose `videodraft-editor`, which controls the same process and MCP surface:\\n\\n```bash\\nvideodraft-editor status\\nvideodraft-editor list-tools\\nvideodraft-editor tool project_control --json \'{\\"action\\":\\"list\\"}\'\\nvideodraft-editor tool timeline_read --json \'{}\'\\nvideodraft-editor show\\nvideodraft-editor hide\\n```\\n\\nControl and tool commands auto-start a headless editor if none is running. `show` only reveals the already-running UI. Use `videodraft-editor tool <name> --json -` to read a JSON object from stdin when shell quoting would be fragile. Never read, copy, or expose the editor\'s rotating local authentication secret.\\n","references/examples.md":"# Recipes\\n\\nWorking patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.\\n\\nInside VideoDraft ADE, if a native editor is available, use these recipes for asset generation and\\noptional script/storyboard stages. Hand the results to the editor for production and export ONLY\\nwhen the deliverable the user asked for is a composed production. A standalone output \u2014 the batch\\nproduct clips in recipe 1, the upscale in recipe 7 \u2014 is finished when it is generated; importing it\\ninto a project and exporting a timeline builds an edit nobody asked for. Recipes below that call `videodraft produce` or `videodraft export` are hosted fallbacks only. Do not choose them over the available native editor unless the user explicitly asks for the hosted web workflow.\\n\\n## 1. Batch product videos from a CSV\\n\\nOne 9:16 product clip per row of `products.csv` (`name,image_url,tagline`):\\n\\n```bash\\n#!/usr/bin/env bash\\nset -euo pipefail\\nmkdir -p outputs\\n\\nwhile IFS=, read -r name image tagline; do\\n  job=$(videodraft generate video \\\\\\n    \\"Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting.\\" \\\\\\n    --model gemini-omni-flash --ar 9:16 --duration 6 \\\\\\n    --start-image \\"$image\\" \\\\\\n    --no-wait --json | jq -r .job_id)\\n  echo \\"$name,$job\\" >> outputs/jobs.csv\\ndone < <(tail -n +2 products.csv)\\n\\n# Collect ALL results with ONE process (batched polling \u2014 one request per tick)\\nvideodraft wait $(cut -d, -f2 outputs/jobs.csv) \\\\\\n  --download \\"outputs/{job_id}_{index}.{ext}\\" --json > outputs/results.json\\n# map job ids back to product names via outputs/jobs.csv\\n```\\n\\nSubmit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Gemini Omni Flash is selected because these are six-second first-frame product clips. Estimate first: `videodraft costs gemini-omni-flash --type video --duration 6 --resolution 720p --audio` \xD7 rows, and confirm with the user.\\n\\n## 2. Hosted full marketing video from one idea (fallback)\\n\\n```bash\\nvideodraft create \\"30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette.\\" \\\\\\n  --ar 9:16 --style cinematic --json > project.json\\nPROJECT=$(jq -r .project_id project.json)\\n\\nvideodraft shots \\"$PROJECT\\" --grid --estimate          # show the user the cost; get a go-ahead\\nvideodraft shots \\"$PROJECT\\" --grid\\nvideodraft produce \\"$PROJECT\\"\\nvideodraft generate music \\"minimal ambient, warm pads, 60 BPM\\" --attach \\"$PROJECT\\"\\nvideodraft generate audio \\"Extend @Audio1 into a 20-second transition\\" --ref-audio ./intro.wav --format wav --download ./transition.wav\\nvideodraft export \\"$PROJECT\\" --download solace-launch.mp4\\n```\\n\\nUse this complete hosted path only when the user requested a web project or the native editor is unavailable. Otherwise stop after the storyboard/assets, import them into the native `.vdproject`, and export with `export_start`. The hosted project stays editable at the URL in `project.json` (`.urls`).\\n\\n## 3. Talking-head (avatar) video\\n\\nWhen the user has no portrait, generate a clear front-facing avatar image first. Skip this step when they supplied one or an existing character should be reused.\\n\\n```bash\\nvideodraft generate image \\\\\\n  \\"Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background\\" \\\\\\n  --model nano-banana-2 --ar 9:16 --download ./media/avatar.png\\n\\nSCRIPT=$(videodraft avatar script \\"why our espresso subscription saves you money\\" --style ad-style --json | jq -r .script)\\nAVATAR=$(videodraft avatar create ./media/avatar.png --script \\"$SCRIPT\\" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)\\nvideodraft avatar render \\"$AVATAR\\" --resolution 720p   # VEED Fabric paid step; confirm cost first (~20 credits/sec)\\n```\\n\\n`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.\\n\\nIf the portrait is low resolution, enhance it before `avatar create`:\\n\\n```bash\\nvideodraft upscale image ./founder-small.jpg --scale 2x --download ./media/founder-upscaled.png\\n```\\n\\nFor a one-off portrait animation without creating a managed avatar record:\\n\\n```bash\\nvideodraft avatar fabric ./founder.jpg \\\\\\n  --text \\"Welcome to the weekly product update.\\" \\\\\\n  --voice-description \\"warm, confident American presenter\\" \\\\\\n  --resolution 720p --download ./media/presenter.mp4\\n```\\n\\nWhen the user already has both the video and replacement speech:\\n\\n```bash\\nvideodraft avatar lipsync ./presenter.mp4 \\\\\\n  --audio ./localized-voiceover.mp3 \\\\\\n  --sync-mode loop --download ./media/presenter-localized.mp4\\n```\\n\\nEdit an existing video with a dedicated edit model:\\n\\n```bash\\nvideodraft models video --category video_edit\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Turn the room into a warm evening scene while preserving the product and camera motion\\" \\\\\\n  --model wan-2.7-ref-edit --ref ./evening-style.jpg \\\\\\n  --preserve-audio --download ./media/product-demo-evening.mp4\\n```\\n\\nTransfer motion from a reference clip onto a character image:\\n\\n```bash\\nvideodraft edit motion ./character.png \\\\\\n  \\"Apply the dancer\'s movement to this character while preserving identity\\" \\\\\\n  --motion-video ./dance-reference.mp4 \\\\\\n  --model kling-v3-motion-control --quality pro \\\\\\n  --download ./media/character-dance.mp4\\n```\\n\\n## 4. Hosted changelog video in CI\\n\\nIn a GitHub Action with `VIDEODRAFT_API_KEY` set as a secret:\\n\\n```bash\\nNOTES=$(git log --oneline v1.2.0..HEAD | head -20)\\nvideodraft create \\"Weekly product update video. Energetic, 20 seconds. Changes: ${NOTES}\\" --ar 16:9 --json > p.json\\nPROJECT=$(jq -r .project_id p.json)\\nvideodraft shots \\"$PROJECT\\" && videodraft produce \\"$PROJECT\\"\\nvideodraft export \\"$PROJECT\\" --download changelog.mp4 --wait-timeout 30m\\n```\\n\\n## 5. Variations and picking a winner\\n\\n```bash\\nvideodraft generate image \\"logo concept: minimalist fox, geometric\\" --num 4 --download \\"./concepts/{job_id}_{index}.{ext}\\" --json\\n# Show all 4 to the user; regenerate the chosen one at higher res:\\nvideodraft generate image \\"<same prompt>\\" --model nano-banana-pro --resolution 4K\\n```\\n\\n## 6. Reaching tools without a curated command\\n\\n```bash\\nvideodraft tools list --json | jq -r \'.[].name\'\\nvideodraft tools schema attach_media_to_shot --json\\nvideodraft call attach_media_to_shot --args \'{\\"project_id\\":\\"...\\",\\"scene_index\\":0,\\"shot_index\\":1,\\"media_url\\":\\"https://...\\",\\"media_type\\":\\"video\\",\\"duration_seconds\\":6}\'\\n```\\n\\nAnything the hosted VideoDraft MCP exposes, including character studio, product studio, and hosted project data, is reachable this way even before it gets a curated command. Native `.vdproject` editing uses the separate `videodraft_editor` MCP described in SKILL.md.\\n\\n## 7. Enhance an existing asset without changing it\\n\\n```bash\\n# Light image cleanup, no enlargement\\nvideodraft upscale image ./poster.png --scale 1x --download ./media/poster-enhanced.png\\n\\n# General image and video enlargement\\nvideodraft upscale image ./frame.png --scale 2x --download ./media/frame-2x.png\\nvideodraft upscale video ./clip.mp4 --scale 2x --download ./media/clip-2x.mp4\\n```\\n\\nUse these when the content is correct and only quality or resolution needs improvement. If the poster text, composition, subject, or motion is wrong, edit or regenerate instead.\\n","references/models.md":"# Choosing models (and predicting cost)\\n\\nAlways consult the live catalog instead of memorizing this page \u2014 models change weekly:\\n\\n```bash\\nvideodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)\\nvideodraft models video --json     # every video model + inputs + per-second pricing metadata\\nvideodraft models audio --json     # standalone audio/media models + pricing inputs\\nvideodraft models voices --json    # TTS voices\\nvideodraft models styles --json    # visual style presets\\n```\\n\\n## Task-based model selection\\n\\nHonor an explicitly named model when it supports the request. Otherwise choose from the task\'s inputs, duration, audio, quality, speed, and cost. Pass the chosen model explicitly instead of relying on a blind platform fallback.\\n\\n### Images\\n\\n| Need                                                                                   | Choose               | Why                                                               |\\n| -------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------- |\\n| Most generation, editing, character consistency, or reference work                     | `nano-banana-2`      | Best general default; 1K/2K/4K and up to 14 reference images      |\\n| Highest-quality complex generation or reasoning                                        | `nano-banana-pro`    | Premium Nano Banana quality and reasoning                         |\\n| Fast, inexpensive drafts and iteration                                                 | `nano-banana-2-lite` | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |\\n| Posters, title cards, signs, logos, or any image with important readable text          | `gpt-image-2`        | Strong text rendering; up to 16 image inputs and 1K/2K/4K output  |\\n| Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2`        | Strong non-Nano alternative with multi-image input                |\\n\\nUse `--num 1..4` for variations of one prompt in a single call. Never loop separate paid calls for variations that fit in one request.\\n\\n### Videos\\n\\n| Need                                                                                                       | Choose              | Important limits                                                                                    |\\n| ---------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |\\n| Most text, first-frame, image-reference, or source-video-edit requests up to 10s                           | `gemini-omni-flash` | 720p, 3-10s or auto, audio always on, up to 10 total image inputs, one source video                 |\\n| Grok 1.5 text, first-frame, or 1-7 image-reference clips with native audio and optional 1080p              | `grok-imagine-video-1.5` | 1-15s; 480p/720p/1080p for text/first-frame; references are 480p/720p only; no last frame       |\\n| Fixed 2K with native stereo audio, first/last frames, or mixed image/video/audio references                | `minimax-h3`        | 5-15s; up to 9 image, 3 video, 3 audio refs, 12 files total; reference video/audio each total <=15s |\\n| Images pinned to specific moments (keyframes), 16-20s clips, or a cheap draft pass before committing       | `flux-3`            | 5-20s (auto for text/first-frame only); 720p/1080p; up to 10 keyframes; `--quality draft` is 720p-only at ~1/3 the cost |\\n| Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2`        | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only |\\n| Fast polished 3-15s video with first frame, multi-prompt, and native audio                                 | `kling-v3-turbo`    | Audio always on; Pro default; no end frame or reference-media mode                                  |\\n| Cinematic 3-15s with image references, first+last frame, multi-prompt, audio control, or 4K                | `kling-o3`          | Up to 7 image refs; Standard/Pro/4K; audio toggle                                                   |\\n| Kling 3-15s with first+last frame, multi-prompt, optional audio, or 4K, without reference-image mode       | `kling-3.0`         | Standard/Pro/4K; audio toggle                                                                       |\\n| User explicitly requests Veo, or the selected workflow specifically needs Veo                              | `google-veo3.1`     | Good fallback, but not the preferred general model                                                  |\\n\\nRouting rules:\\n\\n- Fixed 2K with native stereo audio: use MiniMax H3.\\n- Grok 1.5 reference mode accepts 1-7 images only. Address them in array order as `<IMAGE_0>` through `<IMAGE_6>`. Do not combine reference images with `--start-image`, `--end-image`, `--ref-video`, or `--ref-audio`.\\n- Grok 1.5 first-frame mode accepts one `--start-image`, derives the output aspect ratio from that image, and does not support `--end-image`. Text and first-frame modes support 480p, 720p, or 1080p. Reference mode supports 480p or 720p.\\n- Grok 1.5 always generates native audio. Do not pass `--no-audio`, `--seed`, `--negative`, or `--quality`.\\n- Around 11-15 seconds with native audio: use MiniMax H3, Kling, or Seedance, not Gemini.\\n- One existing source video that should be edited, with an output up to 10 seconds and no additional media references to preserve: use Gemini Omni Flash.\\n- Video or audio supplied as creative reference: use MiniMax H3 for fixed 2K/native audio, or Seedance 2.0 when resolution/quality tier or audio-toggle control matters.\\n- A video plus any image/audio references that must all be preserved: use MiniMax H3 or Seedance 2.0. Do not promise that Gemini will preserve mixed source media; its Fal BYOK edit mode accepts only the source video and prompt.\\n- First and last frame control: use MiniMax H3, Seedance, Kling O3, or Kling 3.0. Gemini supports a first frame but not a last frame.\\n- MiniMax H3 reference mode and first-plus-last-frame mode are separate. Audio cannot be the only reference. Address references as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.\\n- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.\\n- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K.\\n\\n### Video edit and motion-control categories\\n\\nUse `videodraft models video --category video_edit` for existing-video transforms and `--category motion_control` for motion transfer.\\n\\n| Need                                  | Command/model                                                         | Important limits                                                                 |\\n| ------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |\\n| Simple prompt edit of one video       | `videodraft edit video <video> \\"...\\" --model grok-imagine-video-edit` | No image refs; source truncated to 8s; auto/480p/720p                            |\\n| Edit with one style/reference image   | `--model wan-2.7-ref-edit --ref <image>`                              | One image ref; 2-10s or match source                                             |\\n| Edit with several image references    | `--model happy-horse-video-edit --ref ...`                            | Up to 5 refs; 720p/1080p; source capped at 15s                                   |\\n| Controlled Kling edit                 | `--model kling-o3-video-ref-edit --ref ...`                           | Up to 4 refs; Standard/Pro; source clamped to 3-10s                              |\\n| Transfer reference motion to an image | `videodraft edit motion <image> \\"...\\" --motion-video <video>`         | Kling V3 default; image orientation caps motion at 10s, video orientation at 30s |\\n\\nIf the user explicitly names one of these models, preserve it. The CLI uploads local source videos and reference images automatically. Editing returns an async job and waits by default.\\n\\nKling O3 and Wan 2.7 Ref/Edit are dual-mode cards. `videodraft edit video` uses edit mode. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. `--model wan-2.7-ref-edit` generates a new clip from one or more `--ref`/`--ref-video` inputs.\\n\\n### Reference-first video workflow\\n\\n- Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.\\n- If the user gives a reference, pass it. Never silently replace it with a text description.\\n- If no reference exists and continuity matters, generate a still first with the user\'s explicitly requested compatible image model, otherwise use Nano Banana 2. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.\\n- For multi-shot scenes, generate shot images with `videodraft shots <project_id> --model <selected-image-model> --grid`. Preserve an explicitly requested compatible image model; otherwise use `nano-banana-2`. The grid establishes the scene and characters together, then decodes into individual shot images.\\n- Animate the decoded shot images as per-shot start frames or references. Do not independently text-generate each video clip when the shots need to match.\\n- Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.\\n\\n### Audio\\n\\n- **Seed Audio 1.0**: use `videodraft generate audio` for open-ended speech, sound, music, or prompt-driven audio editing. It accepts up to three audio references or one image. Address audio references as `@Audio1`, `@Audio2`, and `@Audio3`. Preset and custom cloned voice IDs are supported. Output is up to 120 seconds. There is no requested-duration input. The CLI automatically retries transient responses with one idempotency key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- **Voiceover/TTS**: prefer ElevenLabs. Brittney is the platform default voice; under ElevenLabs BYOK, use a compatible voice from the user\'s account. Honor another supported voice/provider when the user explicitly selects it.\\n- **Dialogue, voice changing, and dubbing**: ElevenLabs only.\\n- **Sound effects**: ElevenLabs Sound Effects only.\\n- **Music**: use `lyria-3-clip-preview` for a short instrumental/background score, `lyria-3-pro-preview` for a longer or higher-quality instrumental score, and `elevenlabs-music` when vocals/lyrics or a specified 10-120 second length matter.\\n- Voice Changer and Dubbing require the source media duration and currently accept source media up to 300 seconds.\\n\\n### Avatar / talking head\\n\\nChoose the dedicated path from the media the user already has:\\n\\n| Starting media                            | Command                                                                   | Use                                                 |\\n| ----------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |\\n| Portrait + script, reusable avatar record | `videodraft avatar create <portrait> --script \\"...\\"` then `avatar render` | Managed avatar flow with bundled speech preparation |\\n| Portrait + text                           | `videodraft avatar fabric <portrait> --text \\"...\\"`                        | One-off direct VEED Fabric text mode                |\\n| Portrait + existing audio                 | `videodraft avatar fabric <portrait> --audio <audio>`                     | One-off direct VEED Fabric audio lip sync           |\\n| Existing video + existing audio           | `videodraft avatar lipsync <video> --audio <audio>`                       | Sync Labs Lipsync 2                                 |\\n\\nThe managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric and Sync Labs are paid AI Studio generations and return async job IDs.\\n\\n1. Obtain the avatar image. Prefer the user\'s supplied portrait or an existing character. If none exists, use the user\'s explicitly requested compatible image model, otherwise generate a front-facing head-and-shoulders portrait with `nano-banana-2`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.\\n2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.\\n3. Generate a script only if needed: `videodraft avatar script \\"<idea>\\"`.\\n4. Create the avatar record and speech: `videodraft avatar create <portrait-url-or-file> --script \\"...\\" --voice <id> --ar 9:16`. Prefer ElevenLabs when unspecified, but honor another explicitly selected supported voice/provider.\\n5. Render with VEED Fabric: `videodraft avatar render <avatar_video_id> --resolution 720p`.\\n\\nThe portrait is passed as the avatar\'s character image, not as a generic video\'s start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.\\n\\nDirect Fabric text/audio and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. Sync costs 5 credits per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.\\n\\n### Upscaling / enhancement\\n\\n- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The result is synchronous.\\n- **Videos**: Topaz via `videodraft upscale video <url-or-file> --scale 2x`. Use 2x by default. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.\\n- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems.\\n- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.\\n\\n## Capability gotchas\\n\\n- Each model\'s `inputs` block is authoritative: supported `aspect_ratios`, `resolutions`, `quality_options`, `start_frame`/`end_frame`, `max_reference_images/videos/audio`, `multi_prompt`, `audio_toggle`. Passing an unsupported input fails with a clear error \u2014 check first, don\'t trial-and-error paid calls.\\n- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.\\n- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4); everything else ignores it. You do not need a seed for variation \u2014 `--num` already varies.\\n- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost \u2014 pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.\\n- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.\\n- Reference inputs: `--ref <img>` (images, including up to 7 for Grok 1.5), `--ref-video <v>` (Gemini Omni Flash, MiniMax H3, Seedance 2, Wan 2.7), `--ref-audio <a>` (MiniMax H3, Seedance 2). The CLI uploads local files for all of these, so you can pass a path or a URL. For an exact MiniMax H3 pre-upload estimate, add `--ref-video-seconds <combined-seconds>`; the server measures actual duration before charging a real job. `--segment \\"<prompt>:<seconds>\\"` (repeatable) drives multi-prompt models (Kling 3.0 / 3.0 Turbo / O3); total 3-15s. `generate image --video-ref` is the nano-banana-2 video reference.\\n- The top-level prompt is OPTIONAL for `generate video` with multi-prompt models and for Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video \u2014 a `--segment`-only or `--start-image`-only call is valid. Every other model still needs a prompt; the server enforces per-model rules.\\n- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.\\n\\n## Cost model\\n\\n- Images: per image (\xD7 `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.\\n- Video: usually credits/second \xD7 duration; rate depends on model + resolution + quality + native audio on/off.\\n- MiniMax H3: 26 credits/output second. The first 5 reference images are included, then 8 credits for each additional image. Reference video adds 26 credits/input second; reference audio is included.\\n- Grok Imagine Video 1.5: 8 credits/output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native generated audio is part of every output.\\n- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) \u2014 the largest single spend in the pipeline.\\n- VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.\\n- Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.\\n- Sync Labs Lipsync 2: 5 credits per verified audio second.\\n- Voiceover TTS: 10 credits per 1000 characters for standard voices, 30 per 1000 for cloned `custom-*` voices (min 1, pro-rated); applies to standalone voiceovers AND per-scene narration during `produce`. Silent tracks are free. Voice cloning itself is a flat 150 credits per clone.\\n- Lyria music: flat per track, 10 credits (clip) / 15 credits (pro).\\n- Seed Audio 1.0: 19 credits per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum of 38 credits and refunds the unused portion after generation. Fal BYOK is free.\\n- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. Voice changer and dubbing reject source media above 300s in the current synchronous flow.\\n- Upscales: priced by scale and source size.\\n\\nQuote before spending:\\n\\n```bash\\nvideodraft costs gemini-omni-flash --type video --duration 8 --resolution 720p --audio\\nvideodraft costs minimax-h3 --type video --duration 10 --ref-images 7 --ref-video-seconds 5\\nvideodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio\\nvideodraft costs elevenlabs-dubbing --type audio --duration 60\\nvideodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length\\nvideodraft costs elevenlabs-dialogue --type audio --chars 350\\nvideodraft costs voiceover --type audio --chars 800    # TTS: 10 cr / 1000 chars\\nvideodraft generate video \\"...\\" --model gemini-omni-flash --estimate # same quote, inline\\n```\\n","references/pipeline.md":"# VideoDraft pipeline reference\\n\\nEverything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks). When the local `videodraft_editor` MCP is available, do not use hosted production or export by default. Use hosted tools only for asset generation and optional script/storyboard stages, then import the results and finish with the native editor reference linked from SKILL.md. Continue through `produce_project` and `export_video` only when the user explicitly requests a hosted web production or the native editor is unavailable.\\n\\nUse direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable. Script-only uses a script-stage project and stops at the script. In VideoDraft ADE with editor tools present, stop before hosted production, import the generated assets, and build/export the native project.\\n\\n## Stages and their tools\\n\\n| Stage                                   | CLI                                                                         | Underlying tool                            |\\n| --------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------ |\\n| Idea \u2192 full storyboard project          | `videodraft create \\"<idea>\\"`                                                | `generate_storyboard_from_idea`            |\\n| Idea \u2192 script only (stop there)         | `videodraft create \\"<idea>\\" --script-only`                                  | `generate_script_from_idea`                |\\n| Footage IS the video                    | `videodraft call generate_storyboard_from_media`                            | `generate_storyboard_from_media`           |\\n| Batch shot images                       | `videodraft shots <project>`                                                | `generate_shot_images`                     |\\n| One shot image                          | `videodraft generate image --project <id> --scene N --shot M`               | `generate_image`                           |\\n| Produce (voiceover, captions, timeline) | `videodraft produce <project>`                                              | `produce_project`                          |\\n| Per-shot motion prompts                 | `videodraft video-prompts <project>`                                        | `generate_video_prompts`                   |\\n| Motion clip for a shot                  | `videodraft generate video --project <id>`                                  | `generate_video`                           |\\n| Attach a finished clip to the timeline  | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot`                     |\\n| Background music                        | `videodraft generate music --attach <project>`                              | `generate_music` / `set_background_music`  |\\n| General or reference-driven audio       | `videodraft generate audio \\"...\\"`                                          | `generate_audio`                           |\\n| Sound effect                            | `videodraft generate sound-effect \\"...\\"`                                    | `generate_sound_effect`                    |\\n| Dialogue audio                          | `videodraft generate dialogue --line \\"voice:text\\"`                          | `generate_dialogue`                        |\\n| Voice changer                           | `videodraft generate voice-changer <audio>`                                 | `change_voice`                             |\\n| Dubbing                                 | `videodraft generate dub <audio_or_video>`                                  | `dub_media`                                |\\n| Scene voiceover                         | `videodraft generate voiceover --project <id> --scene N`                    | `generate_voiceover`                       |\\n| Avatar script                           | `videodraft avatar script \\"<idea>\\"`                                         | `generate_avatar_script`                   |\\n| Avatar + speech                         | `videodraft avatar create <portrait> --script \\"...\\"`                        | `create_avatar_video`                      |\\n| Talking-head render                     | `videodraft avatar render <avatar_video_id>`                                | `render_avatar_video` + `get_avatar_video` |\\n| Direct portrait + text/audio            | `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`      | `generate_veed_fabric_video`               |\\n| Existing video + replacement audio      | `videodraft avatar lipsync <video> --audio <file>`                          | `generate_sync_lipsync_video`              |\\n| Existing-video AI edit                  | `videodraft edit video <video> \\"<change>\\" --model <video-edit-model>`       | `edit_video`                               |\\n| Motion transfer                         | `videodraft edit motion <image> \\"<direction>\\" --motion-video <video>`       | `generate_motion_control_video`            |\\n| Image enhancement/upscale               | `videodraft upscale image <image>`                                          | `upscale_image`                            |\\n| Video enhancement/upscale               | `videodraft upscale video <video>`                                          | `upscale_video`                            |\\n| Final MP4                               | `videodraft export <project>`                                               | `export_video` + `check_export_status`     |\\n\\n## Rules that prevent broken results\\n\\n- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don\'t call `generate_storyboard_scenes` with a raw idea as the \\"script\\".\\n- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project\'s visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project\'s visual assets and/or the previous shot\'s image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.\\n- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.\\n- **Hold off generating shot images while the user is still iterating** on storyboard structure.\\n- **produce \u2192 export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.\\n- **Do not attach motion clips before production exists**: run `produce` successfully first, then attach finished motion clips to the production timeline. Attaching before `production_data` exists cannot place them in the final timeline.\\n- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:\\"video\\"`, include `duration_seconds`) \u2014 it replaces the production timeline clip while keeping the storyboard still.\\n- **Talking heads use dedicated avatar tools**: do not use `generate video`. Use managed `avatar create` and `avatar render` for reusable avatars, direct `avatar fabric` for a portrait plus text/audio, and `avatar lipsync` for an existing video plus replacement audio. Reuse a supplied person image or generate a clear front-facing portrait with the explicitly requested compatible image model, otherwise Nano Banana 2. Managed avatar creation and speech are bundled/free; direct Fabric, Sync, and render are paid.\\n- **Existing-video edits use their own category**: call `edit_video` or `videodraft edit video` with a `video_edit` model when transforming the source itself. Kling O3 and Wan 2.7 Ref/Edit are dual-mode: their reference-generation modes may use generic `generate_video` to create a new guided clip. Motion transfer similarly uses `generate_motion_control_video` or `videodraft edit motion` with a `motion_control` model.\\n- **Upscaling preserves rather than redesigns**: use Topaz when resolution, detail, or cleanup is the problem. Regenerate or edit when the subject, text, framing, continuity, or motion is wrong. Upscale a low-quality avatar portrait before Fabric; do not render a new avatar at 480p just to upscale the result.\\n- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side \u2014 `videodraft projects list`, take the most recent, and resume with its id. Don\'t start a duplicate.\\n\\n## User-attached media: classify roles first\\n\\nFor EACH attached file decide:\\n\\n- **visual_asset** \u2014 recurring reference (character / product / location / style). Upload, then pass in `visual_assets` of `generate_storyboard_from_idea` (via `videodraft call`), or add to an existing project with `add_visual_assets`. Type must be one of `character | object | location | style | custom` with a short name + concrete description.\\n- **shot** \u2014 the media IS footage for the video. Whole video = footage \u2192 `generate_storyboard_from_media`. Idea + footage \u2192 `generate_storyboard_from_idea` with `shot_media`. Existing storyboard \u2192 `attach_media_to_shots`.\\n- **reference** \u2014 inspiration only \u2192 fold a description into the idea/instructions; don\'t place it as a shot or asset.\\n\\nAmbiguous (e.g. a person holding a product)? Ask the user.\\n\\nUploads persist in the media library \u2014 recall later with `videodraft media list`.\\n\\n## Editing project data safely\\n\\n1. `videodraft call get_project_schema` \u2014 read the structure once per session.\\n2. `videodraft projects get <id> --raw` \u2014 the exact editable blob.\\n3. Modify; then `videodraft call update_project --stdin` with `{\\"project_id\\": \\"...\\", \\"data\\": {...}}`.\\n   - Objects deep-merge key-by-key; **arrays replace wholesale** \u2014 send the complete array you\'re changing (e.g. all of `storyboard.scenes`).\\n   - Scene shot arrays (`image_prompt` / `shot_types` / `shot_actions` / `search_prompt` / `preview_media`) are auto-aligned; fix-ups come back as warnings.\\n4. Snapshot before risky edits: `videodraft checkpoint create <id> --name \\"before re-script\\"`. Restore with `videodraft checkpoint restore <id> <version>`.\\n\\n## AI Studio sessions (standalone generations)\\n\\nProject generations group automatically. For standalone work in a long conversation, create one session up front and reuse it:\\n\\n```bash\\nSESSION=$(videodraft call create_ai_studio_session --arg name=\\"Fox brand explorations\\" --json | jq -r .session_id)\\nvideodraft generate image \\"...\\" --session \\"$SESSION\\"\\n```\\n"}');
   }
   const root = bundledSkillDir();
   const files = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "videodraft",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Official VideoDraft CLI — create AI videos, images and audio from your terminal. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
   "license": "MIT",
   "type": "module",

package/skills/index.json

@@ -17,8 +17,8 @@
         },
         {
           "path": "references/models.md",
-          "sha256": "51c61783ed264ddf9df67d730c161d8de11c3aa2f68e995f60201c144bc698df",
-          "bytes": 18320
+          "sha256": "9933e8e6ebdb0eaa83e87383eb25656e3b4f38b8dca9c5f28b10b5d1eabb3f91",
+          "bytes": 20777
         },
         {
           "path": "references/pipeline.md",
@@ -27,8 +27,8 @@
         },
         {
           "path": "SKILL.md",
-          "sha256": "37846a8fe780f9ec024b1e08ddd243f01cc410dd7749664b4ac5bd11f3bf165d",
-          "bytes": 20689
+          "sha256": "05be71c73fe565ef1b42d4c0bdb0e2113fdce25c4a8e6a428aa965cc3664b034",
+          "bytes": 22250
         }
       ]
     }

package/skills/videodraft/SKILL.md

@@ -59,6 +59,9 @@ If the user names a model, use it when compatible. If it cannot handle the reque
 **Videos:**
 
 - `gemini-omni-flash`: general default up to 10s, first frame/image references, or editing one source video without extra media references. Fixed 720p with audio.
+- `grok-imagine-video-1.5`: 1-15s text, first-frame, or 1-7 reference-image generation with native audio. Text/first-frame modes support 480p, 720p, and 1080p; reference mode supports 480p/720p. Cite references as `<IMAGE_0>` through `<IMAGE_6>`. It has no last frame, seed, negative prompt, quality tier, reference video, or reference audio.
+- `minimax-h3`: fixed 2K, native stereo audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total. Cite them as `Image 1`, `Video 1`, and `Audio 1` in array order.
+- `flux-3`: Black Forest Labs FLUX 3. 5-20s at 720p/1080p with 24fps native audio, from a prompt, a first frame, first + last frames, or up to 10 keyframes pinned to specific moments (`--keyframe shot.png@2.5`, repeatable). `--quality draft` renders the same shot at 720p for roughly a third of the cost — use it to check blocking before committing. Auto duration is text/first-frame only.
 - `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. Use `mini` for cost, `fast` for speed, `standard` for quality or 1080p/4K.
 - `kling-v3-turbo`: fast polished 3-15s with first frame, multi-prompt, and audio. `kling-o3`: image references, first/last frames, multi-prompt, audio control, or 4K. `kling-3.0`: similar without reference-image mode.
 - Existing-video edits use `videodraft edit video`, not generic generation. Choose from the `video_edit` catalog category: Grok for simple prompt edits, Wan 2.7 for one style reference or source-matching duration, Happy Horse for up to 5 references, and Kling O3 for controlled reference-image edits.
@@ -89,6 +92,10 @@ Do not call `videodraft credits` before routine generations. Paid endpoints vali
 
 For expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user's confirmation preference for the session.
 
+MiniMax H3 costs 26 credits per output second. In reference mode the first 5 images are included, each additional image costs 8 credits, and reference video costs 26 credits per verified input second. Audio references are included. For a pre-upload estimate, pass `--ref-video-seconds <total>`; the server measures the actual uploaded video duration before charging.
+
+Grok Imagine Video 1.5 costs 8 credits per output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native audio is always generated.
+
 `videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` lists TTS voices. Consult them instead of guessing capabilities.
 
 ## Async jobs

package/skills/videodraft/references/models.md

@@ -31,6 +31,9 @@ Use `--num 1..4` for variations of one prompt in a single call. Never loop separ
 | Need                                                                                                       | Choose              | Important limits                                                                                    |
 | ---------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
 | Most text, first-frame, image-reference, or source-video-edit requests up to 10s                           | `gemini-omni-flash` | 720p, 3-10s or auto, audio always on, up to 10 total image inputs, one source video                 |
+| Grok 1.5 text, first-frame, or 1-7 image-reference clips with native audio and optional 1080p              | `grok-imagine-video-1.5` | 1-15s; 480p/720p/1080p for text/first-frame; references are 480p/720p only; no last frame       |
+| Fixed 2K with native stereo audio, first/last frames, or mixed image/video/audio references                | `minimax-h3`        | 5-15s; up to 9 image, 3 video, 3 audio refs, 12 files total; reference video/audio each total <=15s |
+| Images pinned to specific moments (keyframes), 16-20s clips, or a cheap draft pass before committing       | `flux-3`            | 5-20s (auto for text/first-frame only); 720p/1080p; up to 10 keyframes; `--quality draft` is 720p-only at ~1/3 the cost |
 | Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2`        | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only |
 | Fast polished 3-15s video with first frame, multi-prompt, and native audio                                 | `kling-v3-turbo`    | Audio always on; Pro default; no end frame or reference-media mode                                  |
 | Cinematic 3-15s with image references, first+last frame, multi-prompt, audio control, or 4K                | `kling-o3`          | Up to 7 image refs; Standard/Pro/4K; audio toggle                                                   |
@@ -39,11 +42,16 @@ Use `--num 1..4` for variations of one prompt in a single call. Never loop separ
 
 Routing rules:
 
-- Around 11-15 seconds with native audio: use Kling or Seedance, not Gemini.
+- Fixed 2K with native stereo audio: use MiniMax H3.
+- Grok 1.5 reference mode accepts 1-7 images only. Address them in array order as `<IMAGE_0>` through `<IMAGE_6>`. Do not combine reference images with `--start-image`, `--end-image`, `--ref-video`, or `--ref-audio`.
+- Grok 1.5 first-frame mode accepts one `--start-image`, derives the output aspect ratio from that image, and does not support `--end-image`. Text and first-frame modes support 480p, 720p, or 1080p. Reference mode supports 480p or 720p.
+- Grok 1.5 always generates native audio. Do not pass `--no-audio`, `--seed`, `--negative`, or `--quality`.
+- Around 11-15 seconds with native audio: use MiniMax H3, Kling, or Seedance, not Gemini.
 - One existing source video that should be edited, with an output up to 10 seconds and no additional media references to preserve: use Gemini Omni Flash.
-- Video or audio supplied as creative reference: use Seedance 2.0.
-- A video plus any image/audio references that must all be preserved: use Seedance 2.0. Do not promise that Gemini will preserve mixed source media; its Fal BYOK edit mode accepts only the source video and prompt.
-- First and last frame control: use Seedance, Kling O3, or Kling 3.0. Gemini supports a first frame but not a last frame.
+- Video or audio supplied as creative reference: use MiniMax H3 for fixed 2K/native audio, or Seedance 2.0 when resolution/quality tier or audio-toggle control matters.
+- A video plus any image/audio references that must all be preserved: use MiniMax H3 or Seedance 2.0. Do not promise that Gemini will preserve mixed source media; its Fal BYOK edit mode accepts only the source video and prompt.
+- First and last frame control: use MiniMax H3, Seedance, Kling O3, or Kling 3.0. Gemini supports a first frame but not a last frame.
+- MiniMax H3 reference mode and first-plus-last-frame mode are separate. Audio cannot be the only reference. Address references as `Image 1`, `Video 1`, and `Audio 1` in array order.
 - Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.
 - Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.
 - Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K.
@@ -119,7 +127,7 @@ Direct Fabric text/audio and Sync Labs do not use the managed avatar record. The
 - `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4); everything else ignores it. You do not need a seed for variation — `--num` already varies.
 - `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost — pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.
 - `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.
-- Reference inputs: `--ref <img>` (images), `--ref-video <v>` (Gemini Omni Flash, Seedance 2, Wan 2.7), `--ref-audio <a>` (Seedance 2). The CLI uploads local files for all of these, so you can pass a path or a URL. `--segment "<prompt>:<seconds>"` (repeatable) drives multi-prompt models (Kling 3.0 / 3.0 Turbo / O3); total 3-15s. `generate image --video-ref` is the nano-banana-2 video reference.
+- Reference inputs: `--ref <img>` (images, including up to 7 for Grok 1.5), `--ref-video <v>` (Gemini Omni Flash, MiniMax H3, Seedance 2, Wan 2.7), `--ref-audio <a>` (MiniMax H3, Seedance 2). The CLI uploads local files for all of these, so you can pass a path or a URL. For an exact MiniMax H3 pre-upload estimate, add `--ref-video-seconds <combined-seconds>`; the server measures actual duration before charging a real job. `--segment "<prompt>:<seconds>"` (repeatable) drives multi-prompt models (Kling 3.0 / 3.0 Turbo / O3); total 3-15s. `generate image --video-ref` is the nano-banana-2 video reference.
 - The top-level prompt is OPTIONAL for `generate video` with multi-prompt models and for Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video — a `--segment`-only or `--start-image`-only call is valid. Every other model still needs a prompt; the server enforces per-model rules.
 - Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.
 
@@ -127,6 +135,8 @@ Direct Fabric text/audio and Sync Labs do not use the managed avatar record. The
 
 - Images: per image (× `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.
 - Video: usually credits/second × duration; rate depends on model + resolution + quality + native audio on/off.
+- MiniMax H3: 26 credits/output second. The first 5 reference images are included, then 8 credits for each additional image. Reference video adds 26 credits/input second; reference audio is included.
+- Grok Imagine Video 1.5: 8 credits/output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native generated audio is part of every output.
 - Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) — the largest single spend in the pipeline.
 - VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.
 - Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.
@@ -141,6 +151,8 @@ Quote before spending:
 
 ```bash
 videodraft costs gemini-omni-flash --type video --duration 8 --resolution 720p --audio
+videodraft costs minimax-h3 --type video --duration 10 --ref-images 7 --ref-video-seconds 5
+videodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4
 videodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio
 videodraft costs elevenlabs-dubbing --type audio --duration 60
 videodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length