makaron-cli 0.13.9 → 0.14.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.13.9",
+  "version": "0.14.1",
   "description": "Give Claude Code a creative agent. Pass complete creative requests and source media to Makaron Chat.",
   "author": {
     "name": "Versa AI",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.13.9",
+  "version": "0.14.1",
   "description": "Give Codex a creative agent. Pass complete creative requests and source media to Makaron Chat.",
   "author": {
     "name": "Versa AI",

package/README.md

@@ -98,11 +98,12 @@ npx makaron-cli chat --project auto --image photo.jpg --json -b "make it cinemat
 npx makaron-cli chat --project auto --image img1.jpg --image img2.jpg --json -b "combine these"
 ```
 
-`chat` routes image and video models automatically, but you may select the Agent LLM with `--agent-model`. Accepted values are exactly `auto`, `gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-5.6-luna`, `grok-4.5`, and `deepseek-v4-pro`; `auto` currently resolves to `gpt-5.6-terra`. This flag changes only the reasoning/tool-calling Agent LLM. The CLI still rejects `--image-model`, `--video-model`, and the legacy `--model` flag before starting a chat run, so image/video model names cannot be mistaken for Agent models.
+`chat` routes image and video models automatically, but you may select the Agent LLM with `--agent-model`. Accepted values are `auto`, the base model IDs (`gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-5.6-luna`, `grok-4.6`, `deepseek-v4-pro`), and the personal-plan routes (`gpt-5.6-terra-codex-subscription`, `gpt-5.6-sol-codex-subscription`, `gpt-5.6-luna-codex-subscription`). For the configured owner, `auto` resolves to GPT-5.6 Terra through the personal Codex plan. Base GPT-5.6 IDs select Azure API; the suffixed IDs select the personal plan explicitly. This flag changes only the reasoning/tool-calling Agent LLM.
 
 ```bash
 # Explicit lower-cost Agent LLM for a controlled comparison
 npx makaron-cli chat --project auto --agent-model deepseek-v4-pro --json -b "make a 20s badminton video"
+npx makaron-cli chat --project auto --agent-model gpt-5.6-sol-codex-subscription --json -b "reply with the active model"
 ```
 
 Returns immediately:
@@ -170,26 +171,37 @@ npx makaron-cli project media <projectId> --json
 
 This is project-scoped. `responses get <runId> --pick output` only returns artifacts from one run; `project media` returns the whole project timeline: original uploads, references, generated images, video snapshots, and editable compositions.
 
-External source ranges can be added without uploading either the original video or a derivative clip:
+Typed external images and video ranges can be added without uploading the original media:
 
 ```bash
 npx makaron-cli project media add <projectId> \
+  --type image \
+  --source-url "https://cdn.example.com/product.jpg" \
+  --description "Hero product image"
+
+npx makaron-cli project media add <projectId> \
+  --type video \
   --source-url "https://cdn.example.com/source.mp4" \
   --start 12.5 --end 19 \
   --description "Racket frame molding"
 
 # Batch form: a JSON array or {"clips": [...]}
-npx makaron-cli project media add <projectId> --input ranges.json --json
+npx makaron-cli project media add <projectId> --input media.json --json
 ```
 
-The returned `<<<media_N>>>` is immediately usable by a later Agent run. Its range remains non-destructive metadata; Remotion must trim the original URL to these exact source bounds.
+Every item must declare `type` as `image` or `video`. Images contain
+`source_url + type + description` and do not have a time range. Videos contain
+`source_url + type + start + end + description`; their ranges remain
+non-destructive metadata, and Remotion must trim the original URL to those exact
+source bounds. The returned `<<<media_N>>>` is immediately usable by a later
+Agent run.
 Use `description` as the provider-neutral media-understanding field. Put any
 already-known summary, editorial purpose, concrete scene evidence, confidence,
 and limitations there. Makaron exposes the full description in Media List
 context so the Agent can edit from it without repeating image/video analysis
 unless a required detail is missing or uncertain.
 
-For an agent-to-agent handoff, create the project, import the external ranges,
+For an agent-to-agent handoff, create the project, import the typed external media,
 and start the Agent in one command:
 
 ```bash
@@ -200,9 +212,9 @@ npx makaron-cli chat --project auto \
 ```
 
 The manifest is a JSON array or `{ "title": "...", "clips": [...] }`. Every
-clip contains exactly `source_url`, `start`, `end`, and `description`; the time
-values are seconds and array order is edit order. It is validated before project
-creation and supports up to 20 clips for one Makaron task. Batch planning remains
+item declares `type`. Images omit `start` and `end`; videos require both values
+in seconds. Array order is edit order. It is validated before project creation
+and supports up to 20 media items for one Makaron task. Batch planning remains
 the upstream orchestrator's responsibility: convert each plan into one manifest
 and start one independent Makaron task.
 
@@ -341,9 +353,12 @@ npx makaron-cli edit --image photo.jpg --ref style.jpg "match this style"
 
 # Output to file
 npx makaron-cli edit --image photo.jpg --out result.jpg "make it dramatic"
+
+# Strict transparent PNG/WebP output through GPT Image 2 (fails rather than returning opaque)
+npx makaron-cli edit --image-model openai --background transparent --out sticker.png "a magenta star sticker"
 ```
 
-Options: `--image`, `--image-model gemini|gemini-lite|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--out <path>`
+Options: `--image`, `--image-model gemini|gemini-lite|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--background auto|opaque|transparent`, `--out <path>`. Transparent output routes strictly to GPT Image 2 and is returned only when the provider supplies real PNG/WebP alpha.
 
 ### `video` — Standalone video tools (no project timeline)
 
@@ -354,18 +369,21 @@ npx makaron-cli video script --image img1.jpg "cinematic story"
 # 2. Analyze a video (standalone, no timeline write)
 npx makaron-cli analyze --video input.mp4 "describe the key actions and pacing"
 
-# 3a. Submit image-to-video rendering (images must be public URLs from step 1 or uploaded)
+# 3a. Submit reference-to-video rendering (images must be public URLs from step 1 or uploaded)
 npx makaron-cli video create --script "Shot 1 (5s): <<<image_1>>> ..." --image https://...jpg --duration 5 --video-model kling
 npx makaron-cli video create --script "Shot 1 (5s): <<<image_1>>> slow cinematic push-in with native ambience" --image https://...jpg --duration 5 --video-model grok
+npx makaron-cli video create --script "Keep both subjects recognizable as they enter the same studio" --image https://...jpg --image https://...webp --duration 5 --video-model grok --video-resolution 720p
 npx makaron-cli video create --script "Shot 1 (15s): <<<image_1>>> and <<<image_2>>> build a neon one-person studio" --image https://...jpg --image https://...webp --duration 15 --video-model seedance-mini --video-resolution 480p --aspect 9:16
 
-# 3b. Native SeeDance or MiniMax H3 text-to-video (no image required)
+# 3b. Native SeeDance, Wan 3.0, or MiniMax H3 text-to-video (no image required)
 npx makaron-cli video create --script "Shot 1 (5s): A neon one-person studio wakes at dawn" --duration 5 --video-model seedance-fast --aspect 16:9
 npx makaron-cli video create --script "Shot 1 (15s): A premium creative editor comes alive" --duration 15 --video-model minimax-h3 --aspect 16:9
 
 # 3c. Edit a video from a local file or public URL
 npx makaron-cli video create --script "make it funny" --video input.mp4 --duration 5 --video-model seedance-fast
 npx makaron-cli video create --script "make it warmer and cinematic" --video https://example.com/input.mp4 --duration 5 --video-model seedance --video-resolution 1080p
+npx makaron-cli video create --script "turn the light warm gold but preserve the action" --video input.mp4 --video-model grok --operation edit
+npx makaron-cli video create --script "continue the camera move into the next beat" --video input.mp4 --video-model grok --operation extend --duration 4
 
 # 4. Check status
 npx makaron-cli video status <taskId>
@@ -377,11 +395,13 @@ For project/timeline video editing, use:
 npx makaron-cli chat --project <id|auto> --video input.mp4 -b "make it funny"
 ```
 
-Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to the selected model limit), `--video <file|url>` and `--audio <file|url>` (repeatable where supported), `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|grok|google-omni|minimax-h3|sync-lipsync-v3`, `--video-resolution auto|480p|720p|768p|1080p|2k|4k`. Default model is `seedance-fast`. SeeDance accepts native text-to-video with no image and integer output duration 4-15s (default 5s); `seedance-mini` supports 480p/720p and is best for cheaper drafts/multi-size tests; MiniMax H3 accepts native text-to-video, 4-15s output, public 768p/2k resolution, and up to 9 image, up to 3 video, and up to 3 audio references through Makaron Agent/chat. `sync-lipsync-v3` requires exactly one video plus one MP3/WAV and preserves that replacement audio while aligning the mouth. H3 defaults to 768p; request 2k explicitly for maximum/final quality. Kling supports 5-15s; Grok 1.5 supports 1-15s single-image-to-video only; Gemini Omni supports 3-10s fast 720p image/video generation and editing with native generated audio, including up to 6 image references when no video reference is provided. For `--video-model grok`, forced `--aspect` is ignored to avoid xAI stretching the source image; pad/create the image at the target shape first or use another model.
+Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to the selected model limit), `--video <file|url>` and `--audio <file|url>` (repeatable where supported), `--voice <xai-preset-id>` (repeatable, Grok only), `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|wan-3.0|wan-3.0-pro|kling|grok|google-omni|minimax-h3|sync-lipsync-v3`, `--video-resolution auto|480p|720p|768p|1080p|2k|4k`. Default model is `seedance-fast`. SeeDance accepts native text-to-video with no image and integer output duration 4-15s (default 5s); every Seedance image input is submitted through reference-to-video, including one image. `seedance-mini` supports 480p/720p and is best for cheaper drafts/multi-size tests. Wan 3.0 Standard supports 480p/720p/1080p and Wan 3.0 Pro supports 1080p/2K/4K through MuleRouter. MiniMax H3 accepts native text-to-video, 4-15s output, public 768p/2k resolution, and up to 9 image, up to 3 video, and up to 3 audio feature references through Makaron Agent/chat; a single image keeps the `reference_image` role. `sync-lipsync-v3` requires exactly one video plus one MP3/WAV and preserves that replacement audio while aligning the mouth. H3 defaults to 768p; request 2k explicitly for maximum/final quality. Kling supports 5-15s. Grok generation uses `grok-imagine-video-1.5`: text-only generation supports 480p/720p/1080p, while any 1-7 image or preset voice input uses reference-to-video and is capped at 720p. Grok edit/extend uses `grok-imagine-video` internally under the same `grok` selector. Gemini Omni supports 3-10s fast image/video generation and editing with native generated audio; every image-only generation request uses `reference_to_video`, including a single image, with up to 6 images when no video reference is provided.
 
 Seedance 2.5: use `--video-model seedance-2.5` for 4-30 second output at 480p/720p. `--image` accepts local files or URLs (up to 30), while repeatable `--video` and `--audio` accept up to 10 each. Use `--video-operation generate|edit|extend`, `--extend-direction forward|backward`, `--output-format mp4|mov`, `--web-search`, `--generated-audio` / `--no-generated-audio`, and `--relaxed-content-filter`. Edit/extend require a video reference. The Evolink route does not currently expose 4K output.
 
-Video edit model behavior: `--video-model kling --video` uses Kling base/direct edit internally; `--video-model seedance-fast --video`, `--video-model seedance-mini --video`, or `--video-model seedance --video` uses the SeeDance video-reference path and requires target <=15s, <=50MB, width/height 300-6000px, aspect ratio 0.4-2.5, and frame pixels 409,600-2,086,876. `--video-model minimax-h3 --video` uses H3 feature/reference mode: up to 3 video references totaling <=15s, each <=50MB with width/height 256-5760px and aspect ratio 0.4-2.5. `--video-model google-omni --video` uses Gemini Omni direct video editing and accepts one reference video in Makaron. Output duration is clamped to 3-10s. Grok does not support video references.
+Wan 3.0: use `--video-model wan-3.0` for MuleRouter Standard at 480p/720p/1080p, or `--video-model wan-3.0-pro` for MuleRouter Pro super-resolution at 1080p/2K/4K. Both support 2-30 second generation with up to 10 images, 5 videos, and 5 audio references. Use generation mode with feature references; typed edit/extend and `--relaxed-content-filter` are not supported.
+
+Video edit model behavior: `--video-model kling --video` uses Kling base/direct edit internally; `--video-model seedance-fast --video`, `--video-model seedance-mini --video`, or `--video-model seedance --video` uses the SeeDance video-reference path and requires target <=15s, <=50MB, width/height 300-6000px, aspect ratio 0.4-2.5, and frame pixels 409,600-2,086,876. `--video-model minimax-h3 --video` uses H3 feature/reference mode: up to 3 video references totaling <=15s, each <=50MB with width/height 256-5760px and aspect ratio 0.4-2.5. `--video-model google-omni --video` uses Gemini Omni direct video editing and accepts one reference video in Makaron. Output duration is clamped to 3-10s. `--video-model grok --video --operation edit` accepts one MP4 up to 8.7s, retains duration/aspect, and caps output at 720p. `--operation extend` accepts one 2-15s MP4 and adds 2-10s (default 6s); the returned result includes the original plus extension.
 
 ### `music` — Music generation
 
@@ -497,7 +517,7 @@ send_message "All done!"
 - One project = one conversation thread. All history is preserved.
 - One active Agent Run at a time per project. A new message received while it is active is appended to that same Agent Run and processed at a durable work-unit boundary; it does not interrupt the execution or create a second owner for an in-progress Studio workflow.
 - Multi-image: `create --image a.jpg --image b.jpg` or `chat --image ref.jpg`.
-- Provider-generated videos can take 3-5 minutes; Grok is usually around 30-40 seconds; Gemini Omni is usually around 30-70 seconds plus Storage handoff. Remotion compositions should be converted with `materialize` / `responses get --materialize`, and timing should be read from `duration_seconds`, `render_seconds`, and `realtime_ratio`.
+- Provider-generated videos can take 3-5 minutes; current Grok generation/edit probes are usually around 15-60 seconds; Gemini Omni is usually around 30-70 seconds plus Storage handoff. Remotion compositions should be converted with `materialize` / `responses get --materialize`, and timing should be read from `duration_seconds`, `render_seconds`, and `realtime_ratio`.
 - Music takes ~60 seconds. Appears in output when done.
 - Images are typically ready in 15-30 seconds.
 - stdout is always machine-readable JSON/text. Human-friendly logs go to stderr.

package/bin/makaron.mjs

@@ -33,7 +33,10 @@ const CHAT_AGENT_MODELS = [
   'gpt-5.6-terra',
   'gpt-5.6-sol',
   'gpt-5.6-luna',
-  'grok-4.5',
+  'gpt-5.6-terra-codex-subscription',
+  'gpt-5.6-sol-codex-subscription',
+  'gpt-5.6-luna-codex-subscription',
+  'grok-4.6',
   'deepseek-v4-pro',
 ];
 
@@ -62,6 +65,8 @@ const SEEDANCE_MIN_VIDEO_ASPECT = 0.4;
 const SEEDANCE_MAX_VIDEO_ASPECT = 2.5;
 const MINIMAX_H3_MIN_VIDEO_SIDE = 256;
 const MINIMAX_H3_MAX_VIDEO_SIDE = 5760;
+const MULEROUTER_WAN_MAX_VIDEO_SIDE = 4096;
+const MULEROUTER_WAN_MAX_VIDEO_FILE_SIZE = 100 * 1024 * 1024;
 
 function warnLegacyModelFlag(replacement) {
   process.stderr.write(`⚠️  --model is deprecated here; use ${replacement}.\n`);
@@ -174,25 +179,19 @@ function readJsonInput(filePath) {
   return JSON.parse(raw);
 }
 
-const MAX_MEDIA_MANIFEST_RANGES = 20;
+const MAX_MEDIA_MANIFEST_ITEMS = 20;
 
 function normalizeMediaManifest(input) {
   const manifest = Array.isArray(input) ? { clips: input } : input;
   if (!manifest || typeof manifest !== 'object') {
-    throw new Error('Media manifest must be a JSON object or an array of source ranges.');
-  }
-  const rawRanges = Array.isArray(manifest.clips)
-    ? manifest.clips
-    : Array.isArray(manifest.source_ranges)
-      ? manifest.source_ranges
-      : Array.isArray(manifest.sourceRanges)
-        ? manifest.sourceRanges
-        : null;
+    throw new Error('Media manifest must be a JSON object or an array of media items.');
+  }
+  const rawRanges = Array.isArray(manifest.clips) ? manifest.clips : null;
   if (!rawRanges?.length) {
     throw new Error('Media manifest must contain a non-empty clips array.');
   }
-  if (rawRanges.length > MAX_MEDIA_MANIFEST_RANGES) {
-    throw new Error(`Media manifest supports at most ${MAX_MEDIA_MANIFEST_RANGES} source ranges per Makaron task.`);
+  if (rawRanges.length > MAX_MEDIA_MANIFEST_ITEMS) {
+    throw new Error(`Media manifest supports at most ${MAX_MEDIA_MANIFEST_ITEMS} media items per Makaron task.`);
   }
 
   const sourceRanges = rawRanges.map((raw, index) => {
@@ -207,8 +206,19 @@ function normalizeMediaManifest(input) {
     if (!['http:', 'https:'].includes(parsed.protocol)) {
       throw new Error(`clips[${index}].source_url must use HTTP or HTTPS.`);
     }
-    const start = Number(raw.start ?? raw.start_sec);
-    const end = Number(raw.end ?? raw.end_sec);
+    const declaredType = raw.type;
+    if (declaredType !== 'image' && declaredType !== 'video') {
+      throw new Error(`clips[${index}].type must be image or video.`);
+    }
+    const description = typeof raw.description === 'string' ? raw.description.trim() : '';
+    if (declaredType === 'image') {
+      if (raw.start !== undefined || raw.end !== undefined || raw.start_sec !== undefined || raw.end_sec !== undefined) {
+        throw new Error(`clips[${index}] image items must not include start or end.`);
+      }
+      return { source_url: sourceUrl, type: 'image', description };
+    }
+    const start = Number(raw.start);
+    const end = Number(raw.end);
     if (!Number.isFinite(start) || start < 0) {
       throw new Error(`clips[${index}].start must be a finite number >= 0.`);
     }
@@ -217,9 +227,10 @@ function normalizeMediaManifest(input) {
     }
     return {
       source_url: sourceUrl,
+      type: declaredType,
       start,
       end,
-      description: typeof raw.description === 'string' ? raw.description.trim() : '',
+      description,
     };
   });
 
@@ -447,17 +458,19 @@ Options:
   --image <file|url>        Attach a reference image or screenshot. Repeatable.
   --video <file|url>        Attach a video to the project timeline. Repeatable.
   --audio <file|url>        Attach a song, beat, or voice reference. MP3/WAV, repeatable.
-  --media-manifest <file|-> Import source_url + start + end + description clips before this run.
+  --media-manifest <file|-> Import typed image/video media before this run.
   --skill <id|label|name>   Use an installed skill or auto-install a matched marketplace skill.
   --agent-model <id>        Agent LLM only: auto, gpt-5.6-terra, gpt-5.6-sol,
-                            gpt-5.6-luna, grok-4.5, or deepseek-v4-pro.
+                            gpt-5.6-luna, grok-4.6, deepseek-v4-pro, or a
+                            gpt-5.6-*-codex-subscription personal-plan route.
   --background, -b          Submit and print a runId.
   --json                    Output structured JSON.
   --stream                  Legacy live SSE stream.
   --help, -h                Show this help.
 
-Agent LLM defaults to auto (currently gpt-5.6-terra). Image/video model routing
-stays automatic in chat; --image-model, --video-model, and --model are rejected.
+Agent LLM defaults to auto (GPT-5.6 Terra; the account owner uses the personal
+Codex plan). Base GPT-5.6 ids select Azure API; append -codex-subscription to
+select the personal plan explicitly. Image/video model routing stays automatic in chat.
 
 What you can ask:
   Image edit
@@ -489,6 +502,9 @@ What you can ask:
   Compare Agent LLMs with identical inputs
     makaron chat --project auto --agent-model deepseek-v4-pro -b --json "make a 20s badminton video"
 
+  Force the personal Codex plan
+    makaron chat --project auto --agent-model gpt-5.6-sol-codex-subscription -b --json "reply with the active model"
+
   Music
     makaron chat --project <id> "add calm piano background music"
 
@@ -1031,7 +1047,10 @@ async function addProjectMediaSourceRanges(baseUrl, headers, projectId, ranges,
   }
   if (!opts.silent) {
     for (const item of data.media || []) {
-      console.log(`${item.ref} ${item.source_url} ${formatSeconds(item.start_sec)}-${formatSeconds(item.end_sec)}s${item.created ? '' : ' (existing)'}`);
+      const range = item.type === 'video' && Number.isFinite(item.start_sec) && Number.isFinite(item.end_sec)
+        ? ` ${formatSeconds(item.start_sec)}-${formatSeconds(item.end_sec)}s`
+        : '';
+      console.log(`${item.ref} [${item.type || 'media'}] ${item.source_url}${range}${item.created ? '' : ' (existing)'}`);
     }
   }
   return data;
@@ -1787,7 +1806,22 @@ function saveMcpImage(result, outputPath) {
   const imageBlock = content.find(c => c.type === 'image');
   if (textBlock) process.stderr.write(`${textBlock.text}\n`);
   if (imageBlock) {
-    const out = outputPath || `makaron-output-${Date.now()}.jpg`;
+    const extension = imageBlock.mimeType === 'image/png'
+      ? 'png'
+      : imageBlock.mimeType === 'image/webp'
+        ? 'webp'
+        : 'jpg';
+    let out = outputPath || `makaron-output-${Date.now()}.${extension}`;
+    if (outputPath) {
+      const requestedExtension = path.extname(outputPath).slice(1).toLowerCase();
+      const compatible = extension === 'jpg'
+        ? ['jpg', 'jpeg'].includes(requestedExtension)
+        : requestedExtension === extension;
+      if (!compatible) {
+        out = `${outputPath.slice(0, outputPath.length - path.extname(outputPath).length)}.${extension}`;
+        process.stderr.write(`Output is ${imageBlock.mimeType}; saving as ${out} so bytes and filename agree.\n`);
+      }
+    }
     fs.writeFileSync(out, Buffer.from(imageBlock.data, 'base64'));
     console.log(out);
     return out;
@@ -1838,8 +1872,10 @@ Commands:
   credits                            Show current credit balance
   list (ls)                          List all projects
   project media <projectId> --json    List timeline media for a project
-  project media add <projectId> --source-url <url> --start <n> --end <n>
-                                     Add an external source range without uploading video
+  project media add <projectId> --type image --source-url <url>
+                                     Add an external image without uploading it
+  project media add <projectId> --type video --source-url <url> --start <n> --end <n>
+                                     Add an external video range without uploading it
   create --image <file>              Create project from local image
   create --image-url <url>           Create project from URL
   create --title "name"              Create empty project (text-to-image)
@@ -1851,7 +1887,7 @@ Commands:
   chat --project <id> --video <file> Attach video to conversation
   chat --project <id> --audio <file> Attach song/beat/voice reference
   chat --project auto --media-manifest <file> "message"
-                                     Create, import external ranges, and run Agent
+                                     Create, import typed external media, and run Agent
   chat --project <id> -b "message"   Background: submit and print runId
   chat --project <id> --stream "msg" Legacy: stream SSE in real-time
   chat --project <id> --json "msg"   Output structured JSON result
@@ -1961,11 +1997,12 @@ function printHelp(topic, subtopic) {
     console.log('Usage: makaron credits [--json]');
   } else if (topic === 'project' || topic === 'projects') {
     if (subtopic === 'media') console.log(`Usage: makaron project media <projectId> [--json]
-  makaron project media add <projectId> --source-url <url> --start <n> --end <n> [--description <text>] [--json]
-  makaron project media add <projectId> --input <ranges.json> [--json]`);
+  makaron project media add <projectId> --type image --source-url <url> [--description <text>] [--json]
+  makaron project media add <projectId> --type video --source-url <url> --start <n> --end <n> [--description <text>] [--json]
+  makaron project media add <projectId> --input <media.json> [--json]`);
     else console.log(`Project commands:
   project media <projectId> --json      List timeline media for a project
-  project media add <projectId> ...     Add external source_url + start + end media
+  project media add <projectId> ...     Add typed external image/video media
 `);
   } else if (topic === 'abort') {
     console.log('Usage: makaron abort <runId>');
@@ -2005,19 +2042,21 @@ Not sure which built-in skill to use? Start with:
   composition status <jobId> [--wait] [--json]
 `);
   } else if (topic === 'edit') {
-    console.log('Usage: makaron edit [--image <file|url>] [--image-model gemini|gemini-lite|qwen|openai|pony|wai] [--skill enhance|creative|wild|captions] [--ref <file>] [--out <file>] "prompt"');
+    console.log('Usage: makaron edit [--image <file|url>] [--image-model gemini|gemini-lite|qwen|openai|pony|wai] [--skill enhance|creative|wild|captions] [--ref <file>] [--aspect <ratio>] [--background auto|opaque|transparent] [--out <file>] "prompt"');
   } else if (topic === 'analyze') {
     console.log('Usage: makaron analyze --video <file|url> ["question"]');
   } else if (topic === 'video') {
     if (subtopic === 'script') console.log('Usage: makaron video script --image <file> [--image <file>] [--lang en|zh] "direction"');
-    else if (subtopic === 'create') console.log('Usage: makaron video create --script "..." [--image <url> ...] [--video <url> ...] [--audio <url> ...] [--duration 10] [--aspect 9:16] [--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|grok|google-omni|minimax-h3|sync-lipsync-v3] [--operation generate|edit|extend] [--video-resolution auto|480p|720p|768p|1080p|2k|4k] [--keep-original-sound]');
+    else if (subtopic === 'create') console.log('Usage: makaron video create --script "..." [--image <url> ...] [--video <url> ...] [--audio <url> ...] [--voice <xai-preset-id> ...] [--duration 10] [--aspect 9:16] [--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|wan-3.0|wan-3.0-pro|kling|grok|google-omni|minimax-h3|sync-lipsync-v3] [--operation generate|edit|extend] [--video-resolution auto|480p|720p|768p|1080p|2k|4k] [--keep-original-sound]');
     else if (subtopic === 'status') console.log('Usage: makaron video status <taskId> | --snapshot <snapshotId> [--wait]');
     else console.log(`Video commands:
   video script --image <file> [--image <file>] "direction"   Write video script
   video create --script "..." --video-model seedance-fast    Native text-to-video (no image required)
+  video create --script "..." --video-model wan-3.0          Wan 3.0 Standard via MuleRouter
+  video create --script "..." --video-model wan-3.0-pro      Wan 3.0 Pro super-resolution via MuleRouter
   video create --script "..." --video-model minimax-h3                          MiniMax H3 text-to-video (default 768P)
   video create --script "..." --image <url> [--duration 10]  Submit video task
-  video create --script "..." --video <public-url> [--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|google-omni|minimax-h3]  Edit/reference a video (Grok does not support video refs)
+  video create --script "..." --video <file|url> --video-model grok [--operation edit|extend]  Edit or extend one MP4 with Grok
   video create --script "Use the supplied audio" --video <url> --audio <url> --video-model sync-lipsync-v3  Lip-sync exact replacement audio
   video status <taskId>                                      Check video status
   video status --snapshot <snapshotId> [--wait]              Check v2 video snapshot
@@ -2269,12 +2308,12 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     );
     importedManifestMedia = imported.media || [];
     if (importedManifestMedia.length !== mediaManifest.sourceRanges.length) {
-      process.stderr.write(`❌ Imported ${importedManifestMedia.length}/${mediaManifest.sourceRanges.length} source range(s); aborting run.\n`);
+      process.stderr.write(`❌ Imported ${importedManifestMedia.length}/${mediaManifest.sourceRanges.length} media item(s); aborting run.\n`);
       process.exit(1);
     }
     uploadedTurnMediaCount += importedManifestMedia.length;
-    uploadedTurnVideoCount += importedManifestMedia.length;
-    process.stderr.write(`📎 Imported ${importedManifestMedia.length} external source range(s) from media manifest\n`);
+    uploadedTurnVideoCount += importedManifestMedia.filter(item => item.type === 'video').length;
+    process.stderr.write(`📎 Imported ${importedManifestMedia.length} typed external media item(s) from media manifest\n`);
   }
   // Upload additional images to existing project
   if (imageFileList.length > 0 || imageUrlList.length > 0) {
@@ -2432,9 +2471,12 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
           ...(importedManifestMedia.length ? {
             importedMedia: importedManifestMedia.map(item => ({
               ref: item.ref,
+              type: item.type,
               source_url: item.source_url,
-              start_sec: item.start_sec,
-              end_sec: item.end_sec,
+              ...(item.type === 'video' ? {
+                start_sec: item.start_sec,
+                end_sec: item.end_sec,
+              } : {}),
             })),
           } : {}),
         }));
@@ -2699,7 +2741,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     const jsonOutput = args.includes('--json');
     if (args[2] === 'add') {
       const projectId = args[3];
-      if (!projectId) { console.error('Usage: makaron project media add <projectId> --source-url <url> --start <n> --end <n>'); process.exit(1); }
+      if (!projectId) { console.error('Usage: makaron project media add <projectId> --type <image|video> --source-url <url> [--start <n> --end <n>]'); process.exit(1); }
       const readOption = (name) => {
         const index = args.indexOf(name);
         return index >= 0 ? args[index + 1] : undefined;
@@ -2707,26 +2749,25 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       const inputPath = readOption('--input');
       let ranges;
       if (inputPath) {
-        const input = readJsonInput(inputPath);
-        ranges = Array.isArray(input) ? input : input.clips || input.source_ranges || input.sourceRanges;
+        const normalized = normalizeMediaManifest(readJsonInput(inputPath));
+        ranges = normalized.sourceRanges;
       } else {
         const sourceUrl = readOption('--source-url');
-        const start = Number(readOption('--start') ?? readOption('--start-sec'));
-        const end = Number(readOption('--end') ?? readOption('--end-sec'));
-        if (!sourceUrl || !Number.isFinite(start) || !Number.isFinite(end)) {
-          console.error('Provide --source-url, --start, and --end, or --input <manifest.json>.');
+        const type = readOption('--type');
+        const start = readOption('--start');
+        const end = readOption('--end');
+        if (!sourceUrl || (type !== 'image' && type !== 'video')) {
+          console.error('Provide --type <image|video> and --source-url <url>, or --input <manifest.json>.');
           process.exit(1);
         }
-        ranges = [{
+        const normalized = normalizeMediaManifest([{
           source_url: sourceUrl,
-          start,
-          end,
+          type,
+          ...(start !== undefined ? { start } : {}),
+          ...(end !== undefined ? { end } : {}),
           ...(readOption('--description') ? { description: readOption('--description') } : {}),
-        }];
-      }
-      if (!Array.isArray(ranges) || !ranges.length) {
-        console.error('Input must contain a non-empty clips array.');
-        process.exit(1);
+        }]);
+        ranges = normalized.sourceRanges;
       }
       await addProjectMediaSourceRanges(baseUrl, headers, projectId, ranges, { json: jsonOutput });
     } else {
@@ -2737,7 +2778,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   } else {
     console.log(`Project commands:
   project media <projectId> --json      List timeline media for a project
-  project media add <projectId> ...     Add external source_url + start + end media
+  project media add <projectId> ...     Add typed external image/video media
 `);
   }
 } else if (command === 'abort') {
@@ -2775,11 +2816,19 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       editArgs.referenceImages.push(imageToArg(args[++i]));
     }
     else if (args[i] === '--aspect' && args[i + 1]) editArgs.aspectRatio = args[++i];
+    else if (args[i] === '--background' && args[i + 1]) {
+      const background = args[++i];
+      if (!['auto', 'opaque', 'transparent'].includes(background)) {
+        console.error('Invalid --background. Use auto, opaque, or transparent.');
+        process.exit(1);
+      }
+      editArgs.background = background;
+    }
     else if (args[i] === '--out' && args[i + 1]) outputPath = args[++i];
     else promptParts.push(args[i]);
   }
   editArgs.editPrompt = promptParts.join(' ');
-  if (!editArgs.editPrompt) { console.error('Usage: makaron edit [--image <file|url>] [--image-model gemini|gemini-lite|qwen|openai|pony|wai] [--ref <file>] [--out <file>] "prompt"'); process.exit(1); }
+  if (!editArgs.editPrompt) { console.error('Usage: makaron edit [--image <file|url>] [--image-model gemini|gemini-lite|qwen|openai|pony|wai] [--ref <file>] [--aspect <ratio>] [--background auto|opaque|transparent] [--out <file>] "prompt"'); process.exit(1); }
   process.stderr.write('🎨 Generating...\n');
   const result = await callMcpTool(baseUrl, headers, 'makaron_edit_image', editArgs);
   saveMcpImage(result, outputPath);
@@ -2814,9 +2863,10 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     if (text) console.log(text);
 
   } else if (sub === 'create') {
-    const images = [];
+    let images = [];
     const videos = [];
     const audios = [];
+    const referenceVoices = [];
     let script = '', duration = undefined, aspectRatio = undefined, videoModel = undefined, videoResolution = undefined, wait = false;
     let keepOriginalSound = false, videoOperation = undefined, extendDirection = undefined, outputFormat = undefined;
     let generateAudio = undefined, contentFilter = undefined, webSearch = false;
@@ -2824,6 +2874,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       if (args[i] === '--image' && args[i + 1]) images.push(args[++i]);
       else if (args[i] === '--video' && args[i + 1]) videos.push(args[++i]);
       else if (args[i] === '--audio' && args[i + 1]) audios.push(args[++i]);
+      else if (args[i] === '--voice' && args[i + 1]) referenceVoices.push(args[++i]);
       else if (args[i] === '--script' && args[i + 1]) script = args[++i];
       else if (args[i] === '--script-file' && args[i + 1]) script = fs.readFileSync(args[++i], 'utf-8');
       else if (args[i] === '--duration' && args[i + 1]) duration = Number(args[++i]);
@@ -2849,27 +2900,43 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       }
       else if (args[i] === '--wait') wait = true;
     }
-    const selectedVideoModel = videoModel || 'seedance-fast';
+    const selectedVideoModel = ['wan3', 'wan3.0', 'wan30', 'wan-3'].includes(videoModel)
+      ? 'wan-3.0'
+      : ['wan3-pro', 'wan3.0-pro', 'wan30-pro', 'wan-3-pro', 'berry-1.0-pro'].includes(videoModel)
+        ? 'wan-3.0-pro'
+        : (videoModel || 'seedance-fast');
     const isSeedance25 = selectedVideoModel === 'seedance-2.5';
+    const isWan30 = selectedVideoModel === 'wan-3.0' || selectedVideoModel === 'wan-3.0-pro';
     const isSeedanceModel = selectedVideoModel === 'seedance-fast' || selectedVideoModel === 'seedance-mini' || selectedVideoModel === 'seedance' || isSeedance25;
     const isMinimaxH3 = selectedVideoModel === 'minimax-h3';
+    const isGrok = selectedVideoModel === 'grok';
+    const isGoogleOmni = selectedVideoModel === 'google-omni';
     const isSyncLipsync = selectedVideoModel === 'sync-lipsync-v3';
-    const supportsNativeTextToVideo = isSeedanceModel || isMinimaxH3;
-    if (!script || (!images.length && !videos.length && !audios.length && !supportsNativeTextToVideo)) {
-      console.error('Usage: makaron video create --script "..." [--image <url>] [--video <file|url>] [--audio <file|url>] [--duration 30] [--video-model seedance-2.5|minimax-h3]');
+    const supportsNativeTextToVideo = isSeedanceModel || isWan30 || isMinimaxH3 || isGrok || isGoogleOmni;
+    if (!script || (!images.length && !videos.length && !audios.length && !referenceVoices.length && !supportsNativeTextToVideo)) {
+      console.error('Usage: makaron video create --script "..." [--image <url>] [--video <file|url>] [--audio <file|url>] [--duration 30] [--video-model seedance-2.5|wan-3.0|wan-3.0-pro|minimax-h3]');
       process.exit(1);
     }
     if (isSeedance25 && images.length > 30) { console.error('Seedance 2.5 supports at most 30 image references.'); process.exit(1); }
     if (isSeedance25 && videos.length > 10) { console.error('Seedance 2.5 supports at most 10 video references.'); process.exit(1); }
     if (isSeedance25 && audios.length > 10) { console.error('Seedance 2.5 supports at most 10 audio references.'); process.exit(1); }
+    if (isWan30 && images.length > 10) { console.error('Wan 3.0 supports at most 10 image references.'); process.exit(1); }
+    if (isWan30 && videos.length > 5) { console.error('Wan 3.0 supports at most 5 video references.'); process.exit(1); }
+    if (isWan30 && audios.length > 5) { console.error('Wan 3.0 supports at most 5 audio references.'); process.exit(1); }
     if (isMinimaxH3 && images.length > 9) { console.error('MiniMax H3 supports at most 9 image references.'); process.exit(1); }
     if (isMinimaxH3 && videos.length > 3) { console.error('MiniMax H3 supports at most 3 video references.'); process.exit(1); }
     if (isMinimaxH3 && audios.length > 3) { console.error('MiniMax H3 supports at most 3 audio references.'); process.exit(1); }
+    if (isGrok && images.length > 7) { console.error('Grok Imagine Video 1.5 supports at most 7 image references.'); process.exit(1); }
+    if (isGrok && videos.length > 1) { console.error('Grok video edit/extend accepts exactly one source video.'); process.exit(1); }
+    if (isGrok && referenceVoices.length > 3) { console.error('Grok Imagine Video 1.5 supports at most 3 preset voices.'); process.exit(1); }
+    if (!isGrok && referenceVoices.length) { console.error('--voice is currently supported only with --video-model grok.'); process.exit(1); }
     if (isSyncLipsync && (images.length !== 0 || videos.length !== 1 || audios.length !== 1)) { console.error('Sync Lipsync v3 requires exactly one --video and one --audio, with no --image.'); process.exit(1); }
     if (isSyncLipsync && !/<<<audio_1>>>/i.test(script)) {
       script += '\nUse <<<audio_1>>> as the exact replacement soundtrack.';
     }
     if (videoOperation && !['generate', 'edit', 'extend'].includes(videoOperation)) { console.error('--video-operation must be generate, edit, or extend.'); process.exit(1); }
+    if (isWan30 && videoOperation && videoOperation !== 'generate') { console.error('Wan 3.0 supports generation with feature references, not typed edit or extend.'); process.exit(1); }
+    if (!isSeedance25 && contentFilter === false) { console.error('--relaxed-content-filter is only supported with --video-model seedance-2.5.'); process.exit(1); }
     if (extendDirection && !['forward', 'backward'].includes(extendDirection)) { console.error('--extend-direction must be forward or backward.'); process.exit(1); }
     if (outputFormat && !['mp4', 'mov'].includes(outputFormat)) { console.error('--output-format must be mp4 or mov.'); process.exit(1); }
 
@@ -2878,9 +2945,11 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       process.exit(1);
     }
 
+    const inferredOperation = videoOperation || ((isSeedance25 || isGrok) && videos.length ? 'edit' : 'generate');
     let providerMaxDuration = isSeedance25 ? SEEDANCE25_MAX_VIDEO_REFERENCE_DURATION : MAX_VIDEO_PROVIDER_REFERENCE_DURATION;
+    if (isGrok) providerMaxDuration = inferredOperation === 'edit' ? 8.7 : 15;
     if (isSyncLipsync) providerMaxDuration = 60;
-    const providerMaxPixels = isSyncLipsync || isMinimaxH3 ? Infinity : isSeedance25 ? SEEDANCE25_MAX_VIDEO_FRAME_PIXELS : MAX_VIDEO_FRAME_PIXELS;
+    const providerMaxPixels = isSyncLipsync || isMinimaxH3 || isWan30 ? Infinity : isSeedance25 ? SEEDANCE25_MAX_VIDEO_FRAME_PIXELS : MAX_VIDEO_FRAME_PIXELS;
     const localImages = images.filter(image => !isHttpUrl(image));
     if (localImages.length) {
       const uploadedImages = await uploadImageFilesViaSignedUrl(baseUrl, headers, undefined, localImages);
@@ -2895,13 +2964,21 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
         maxDuration: providerMaxDuration,
         durationTolerance: MAX_VIDEO_PROVIDER_REFERENCE_DURATION_TOLERANCE,
         maxFramePixels: providerMaxPixels,
-        maxFileSize: isSeedance25 || isSyncLipsync ? 200 * 1024 * 1024 : MAX_VIDEO_UPLOAD_FILE_SIZE,
-        ...(selectedVideoModel === 'minimax-h3' ? {
+        maxFileSize: isWan30 ? MULEROUTER_WAN_MAX_VIDEO_FILE_SIZE : isSeedance25 || isSyncLipsync ? 200 * 1024 * 1024 : MAX_VIDEO_UPLOAD_FILE_SIZE,
+        ...(isGrok ? {
+          allowedExtensions: ['mp4'],
+        } : selectedVideoModel === 'minimax-h3' ? {
           allowedExtensions: ['mp4', 'mov'],
           minSide: MINIMAX_H3_MIN_VIDEO_SIDE,
           maxSide: MINIMAX_H3_MAX_VIDEO_SIDE,
           minAspect: SEEDANCE_MIN_VIDEO_ASPECT,
           maxAspect: SEEDANCE_MAX_VIDEO_ASPECT,
+        } : isWan30 ? {
+          minSide: 240,
+          maxSide: MULEROUTER_WAN_MAX_VIDEO_SIDE,
+          minAspect: 0.125,
+          maxAspect: 8,
+          allowedExtensions: ['mp4', 'mov'],
         } : isSeedanceModel ? {
           minFramePixels: SEEDANCE_MIN_VIDEO_FRAME_PIXELS,
           minSide: SEEDANCE_MIN_VIDEO_SIDE,
@@ -2930,21 +3007,22 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     }
     // Standalone MCP tool (no project timeline write)
     process.stderr.write('🎬 Submitting video...\n');
-    const resolvedOperation = videoOperation || (isSeedance25 && videoUrls.length ? 'edit' : 'generate');
+    const resolvedOperation = inferredOperation;
     const vArgs = isSyncLipsync
       ? { script, images, videoUrls, audioUrls, videoModel: selectedVideoModel, videoResolution }
-      : isSeedance25
-      ? { script, images, videoUrls, audioUrls, videoModel: selectedVideoModel, videoResolution, operation: resolvedOperation, extendDirection, outputFormat, generateAudio, contentFilter, webSearch }
+      : isSeedance25 || isWan30 || isGrok
+      ? { script, images, videoUrls, audioUrls, referenceVoiceIds: referenceVoices, videoModel: selectedVideoModel, videoResolution, operation: resolvedOperation, extendDirection, outputFormat, generateAudio, contentFilter, webSearch }
       : isMinimaxH3
         ? { script, images, videoUrls, audioUrls, videoModel: selectedVideoModel, videoResolution }
       : videoUrls[0]
         ? { videoUrl: videoUrls[0], editPrompt: script, images, videoModel: selectedVideoModel, videoResolution, referType: isSeedanceModel ? 'feature' : 'base' }
         : { script, images, videoModel: selectedVideoModel, videoResolution };
+    if (inputVideoMeta?.duration) vArgs.referenceVideoDuration = inputVideoMeta.duration;
     const effectiveDuration = resolvedOperation === 'edit' ? undefined : duration || (inputVideoMeta?.duration ? Math.min(providerMaxDuration, Math.round(inputVideoMeta.duration)) : undefined);
     if (effectiveDuration) vArgs.duration = effectiveDuration;
     if (aspectRatio) vArgs.aspectRatio = aspectRatio;
     if (keepOriginalSound && videoUrls.length && !isSeedance25) vArgs.keepOriginalSound = true;
-    const result = await callMcpTool(baseUrl, headers, videoUrls.length && !isSeedance25 && !isMinimaxH3 && !isSyncLipsync ? 'makaron_edit_video' : 'makaron_create_video', vArgs);
+    const result = await callMcpTool(baseUrl, headers, videoUrls.length && !isSeedance25 && !isWan30 && !isGrok && !isMinimaxH3 && !isSyncLipsync ? 'makaron_edit_video' : 'makaron_create_video', vArgs);
     const text = result?.content?.find(c => c.type === 'text')?.text;
     if (text) {
       console.log(text);
@@ -2988,9 +3066,11 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     console.log(`Video commands:
   video script --image <file> [--image <file>] "direction"   Write video script
   video create --script "..." --video-model seedance-fast    Native text-to-video (no image required)
+  video create --script "..." --video-model wan-3.0          Wan 3.0 Standard via MuleRouter
+  video create --script "..." --video-model wan-3.0-pro      Wan 3.0 Pro super-resolution via MuleRouter
   video create --script "..." --video-model minimax-h3                          MiniMax H3 text-to-video (default 768P)
   video create --script "..." --image <url> [--duration 10]  Submit video task
-  video create --script "..." --video <public-url> [--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|google-omni|minimax-h3]  Edit/reference a video (Grok does not support video refs)
+  video create --script "..." --video <file|url> --video-model grok [--operation edit|extend]  Edit or extend one MP4 with Grok
   video create --script "Use the supplied audio" --video <url> --audio <url> --video-model sync-lipsync-v3  Lip-sync exact replacement audio
   video status <taskId>                                      Check video status
   video status --snapshot <snapshotId> [--wait]              Check v2 video snapshot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.13.9",
+  "version": "0.14.1",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
   "scripts": {

package/skills/makaron/SKILL.md

@@ -85,10 +85,11 @@ npx makaron-cli chat --project auto --image photo.jpg --json -b "make it cinemat
 npx makaron-cli chat --project auto --image img1.jpg --image img2.jpg --json -b "combine these"
 ```
 
-`chat` routes image and video models automatically. Use `--agent-model` only when the user explicitly asks to select or compare the reasoning/tool-calling Agent LLM. Accepted values are exactly `auto`, `gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-5.6-luna`, `grok-4.5`, and `deepseek-v4-pro`; `auto` currently resolves to `gpt-5.6-terra`. Never put an image or video model ID in `--agent-model`. The CLI rejects unknown Agent IDs plus `--image-model`, `--video-model`, and legacy `--model` before starting a chat run.
+`chat` routes image and video models automatically. Use `--agent-model` only when the user explicitly asks to select or compare the reasoning/tool-calling Agent LLM. Accepted values are `auto`, the base model IDs (`gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-5.6-luna`, `grok-4.6`, `deepseek-v4-pro`), and the personal-plan routes (`gpt-5.6-terra-codex-subscription`, `gpt-5.6-sol-codex-subscription`, `gpt-5.6-luna-codex-subscription`). For the configured owner, `auto` uses GPT-5.6 Terra through the personal Codex plan; base GPT-5.6 IDs select Azure API, while suffixed IDs explicitly select the personal plan. Never put an image or video model ID in `--agent-model`.
 
 ```bash
 npx makaron-cli chat --project auto --agent-model deepseek-v4-pro --json -b "make a 20s badminton video"
+npx makaron-cli chat --project auto --agent-model gpt-5.6-sol-codex-subscription --json -b "reply with the active model"
 ```
 
 Returns immediately:
@@ -180,16 +181,17 @@ npx makaron-cli project media <projectId> --json
 
 This is project-scoped. `responses get <runId> --pick output` only returns artifacts from one run; `project media` returns the whole project timeline: original uploads, references, generated images, video snapshots, and editable compositions.
 
-Publish an external video interval directly into that Media List without uploading the original or a derivative MP4:
+Publish typed external images and video intervals directly into that Media List without uploading the original media:
 
 ```bash
-npx makaron-cli project media add <projectId> --source-url "https://cdn.example.com/source.mp4" --start 12.5 --end 19 --description "Racket frame molding"
-npx makaron-cli project media add <projectId> --input ranges.json --json
+npx makaron-cli project media add <projectId> --type image --source-url "https://cdn.example.com/product.jpg" --description "Hero product image"
+npx makaron-cli project media add <projectId> --type video --source-url "https://cdn.example.com/source.mp4" --start 12.5 --end 19 --description "Racket frame molding"
+npx makaron-cli project media add <projectId> --input media.json --json
 ```
 
-The JSON input may be an array or `{ "clips": [...] }`. Each clip has exactly `source_url + start + end + description`; `start` and `end` are seconds, array order is edit order, and `source_url` is opaque. Do not add or request provider-specific identity fields. Put existing media understanding (summary, editorial purpose, scene evidence, confidence, and limitations) in `description`. Makaron reads that provider-neutral Media List field before deciding whether any additional image/video analysis is needed.
+The JSON input may be an array or `{ "clips": [...] }`. Every item declares `type` as `image` or `video`. Images have `source_url + type + description` and no time range. Videos have `source_url + type + start + end + description`; `start` and `end` are seconds. Array order is edit order and `source_url` is opaque. Do not add or request provider-specific identity fields. Put existing media understanding (summary, editorial purpose, scene evidence, confidence, and limitations) in `description`. Makaron reads that provider-neutral Media List field before deciding whether any additional image/video analysis is needed.
 
-For one-call orchestration, use `chat --project auto --media-manifest plan.json`. Makaron validates the manifest, creates the project, imports its ranges, and starts the Agent. If an upstream service returns multiple plans, the caller should start one independent Makaron task per plan instead of passing the provider-specific batch response into Makaron.
+For one-call orchestration, use `chat --project auto --media-manifest plan.json`. Makaron validates the manifest, creates the project, imports its media, and starts the Agent. If an upstream service returns multiple plans, the caller should start one independent Makaron task per plan instead of passing the provider-specific batch response into Makaron.
 
 ```bash
 npx makaron-cli chat --project auto --media-manifest set-01.json --json -b "Make a 30-second 9:16 TikTok with English VO and captions"
@@ -292,9 +294,12 @@ npx makaron-cli edit --image photo.jpg --ref style.jpg "match this style"
 
 # Output to file
 npx makaron-cli edit --image photo.jpg --out result.jpg "make it dramatic"
+
+# Strict transparent output through GPT Image 2
+npx makaron-cli edit --image-model openai --background transparent --out sticker.png "a magenta star sticker"
 ```
 
-Options: `--image`, `--image-model gemini|gemini-lite|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--out <path>`
+Options: `--image`, `--image-model gemini|gemini-lite|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--background auto|opaque|transparent`, `--out <path>`. Transparent output routes strictly to GPT Image 2 and fails instead of returning an opaque fallback.
 
 ### `video` — Standalone video tools (no project timeline)
 
@@ -305,11 +310,11 @@ npx makaron-cli video script --image img1.jpg "cinematic story"
 # 2. Analyze a video (standalone, no timeline write)
 npx makaron-cli analyze --video input.mp4 "describe the key actions and pacing"
 
-# 3a. Submit image-to-video rendering (images must be public URLs from step 1 or uploaded)
+# 3a. Submit reference-to-video rendering (images must be public URLs from step 1 or uploaded)
 npx makaron-cli video create --script "Shot 1 (5s): <<<image_1>>> ..." --image https://...jpg --duration 5 --video-model kling
 npx makaron-cli video create --script "Shot 1 (15s): <<<image_1>>> and <<<image_2>>> build a neon one-person studio" --image https://...jpg --image https://...webp --duration 15 --video-model seedance-mini --video-resolution 480p --aspect 9:16
 
-# 3b. Native SeeDance or MiniMax H3 text-to-video (no image required)
+# 3b. Native SeeDance, Wan 3.0, or MiniMax H3 text-to-video (no image required)
 npx makaron-cli video create --script "Shot 1 (5s): A neon one-person studio wakes at dawn" --duration 5 --video-model seedance-fast --aspect 16:9
 npx makaron-cli video create --script "Shot 1 (15s): A premium creative editor comes alive" --duration 15 --video-model minimax-h3 --aspect 16:9
 
@@ -327,11 +332,15 @@ npx makaron-cli video status <taskId>
 npx makaron-cli chat --project <id|auto> --video input.mp4 -b "make it funny"
 ```
 
-Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to the selected model limit), `--video <file|url>` and `--audio <file|url>` (repeatable where supported), `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|grok|google-omni|minimax-h3|sync-lipsync-v3`, `--video-resolution auto|480p|720p|768p|1080p|2k|4k`. Default model is `seedance-fast`. SeeDance accepts native text-to-video with no image and integer output duration 4-15s (default 5s); `seedance-mini` supports 480p/720p and is best for cheaper drafts/multi-size tests; MiniMax H3 accepts native text-to-video, 4-15s output, public 768p/2k resolution, and up to 9 image, up to 3 video, and up to 3 audio references through Makaron Agent/chat. `sync-lipsync-v3` requires exactly one video plus one MP3/WAV and preserves that replacement audio while aligning the mouth. H3 defaults to 768p; request 2k explicitly for maximum/final quality. Kling supports 5-15s; Grok 1.5 supports 1-15s single-image-to-video only; Gemini Omni supports 3-10s fast 720p image/video generation and editing with native generated audio, including up to 6 image references when no video reference is provided. For `--video-model grok`, forced `--aspect` is ignored to avoid xAI stretching the source image; pad/create the image at the target shape first or use another model.
+Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to the selected model limit), `--video <file|url>` and `--audio <file|url>` (repeatable where supported), `--voice <xai-preset-id>` (repeatable, Grok only), `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|wan-3.0|wan-3.0-pro|kling|grok|google-omni|minimax-h3|sync-lipsync-v3`, `--video-resolution auto|480p|720p|768p|1080p|2k|4k`. Default model is `seedance-fast`. SeeDance accepts native text-to-video with no image and integer output duration 4-15s (default 5s); every Seedance image input uses reference-to-video, including one image. `seedance-mini` supports 480p/720p and is best for cheaper drafts/multi-size tests. Wan 3.0 Standard supports 480p/720p/1080p and Wan 3.0 Pro supports 1080p/2K/4K through MuleRouter. MiniMax H3 accepts native text-to-video, 4-15s output, public 768p/2k resolution, and up to 9 image, up to 3 video, and up to 3 audio feature references through Makaron Agent/chat; a single image keeps the `reference_image` role. `sync-lipsync-v3` requires exactly one video plus one MP3/WAV and preserves that replacement audio while aligning the mouth. H3 defaults to 768p; request 2k explicitly for maximum/final quality. Kling supports 5-15s. Grok text-only generation supports 480p/720p/1080p; any 1-7 image or preset voice input uses reference-to-video and is capped at 720p. Grok edit/extend uses `grok-imagine-video` internally. Gemini Omni image-only generation always uses `reference_to_video`, including one image, with up to 6 images when no video reference is provided.
+
+Provider integration contract: every image passed to video generation is a feature reference by default, even when there is exactly one image. Never infer image-to-video/first-frame mode from image count. A first-frame workflow may be added only as a separately declared model capability and an explicit caller request.
 
 Seedance 2.5 uses `--video-model seedance-2.5` and supports 4-30s at 480p/720p, up to 30 images + 10 videos + 10 audios, repeatable local/URL references, `--video-operation generate|edit|extend`, `--extend-direction`, `--output-format mp4|mov`, and `--web-search`. The Evolink route does not currently expose 4K output.
 
-Video edit model behavior: `--video-model kling --video` uses Kling base/direct edit internally; `--video-model seedance-fast --video`, `--video-model seedance-mini --video`, or `--video-model seedance --video` uses the SeeDance video-reference path and requires target <=15s, <=50MB, width/height 300-6000px, aspect ratio 0.4-2.5, and frame pixels 409,600-2,086,876. `--video-model minimax-h3 --video` uses H3 feature/reference mode: up to 3 video references totaling <=15s, each <=50MB with width/height 256-5760px and aspect ratio 0.4-2.5. `--video-model google-omni --video` uses Gemini Omni direct video editing and accepts one reference video in Makaron. Output duration is clamped to 3-10s. Grok does not support video references.
+Wan 3.0 uses `--video-model wan-3.0` for MuleRouter Standard at 480p/720p/1080p, or `--video-model wan-3.0-pro` for MuleRouter Pro super-resolution at 1080p/2K/4K. Both support 2-30s generation, up to 10 images + 5 videos + 5 audios, and native audio. Use generation mode with feature references; typed edit/extend and the relaxed content-filter flag are not supported.
+
+Video edit model behavior: `--video-model kling --video` uses Kling base/direct edit internally; `--video-model seedance-fast --video`, `--video-model seedance-mini --video`, or `--video-model seedance --video` uses the SeeDance video-reference path and requires target <=15s, <=50MB, width/height 300-6000px, aspect ratio 0.4-2.5, and frame pixels 409,600-2,086,876. `--video-model minimax-h3 --video` uses H3 feature/reference mode: up to 3 video references totaling <=15s, each <=50MB with width/height 256-5760px and aspect ratio 0.4-2.5. `--video-model google-omni --video` uses Gemini Omni direct video editing and accepts one reference video in Makaron. `--video-model grok --video --operation edit` accepts one MP4 up to 8.7s and caps output at 720p; `--operation extend` accepts one 2-15s MP4 and adds 2-10s.
 
 ### `music` — Music generation
 
@@ -465,7 +474,7 @@ send_message "All done!"
 - One project = one conversation thread. All history is preserved.
 - One active Agent Run at a time per project. A new message received while it is active is appended to that same Agent Run and processed at a durable work-unit boundary; it does not interrupt the execution or create a second owner for an in-progress Studio workflow.
 - Multi-image: `create --image a.jpg --image b.jpg` or `chat --image ref.jpg`.
-- Provider-generated videos can take 3-5 minutes; Grok is usually around 30-40 seconds; Gemini Omni is usually around 30-70 seconds plus Storage handoff. Remotion compositions should be converted with `materialize` / `responses get --materialize`, and timing should be read from `duration_seconds`, `render_seconds`, and `realtime_ratio`.
+- Provider-generated videos can take 3-5 minutes; current Grok generation/edit probes are usually around 15-60 seconds; Gemini Omni is usually around 30-70 seconds plus Storage handoff. Remotion compositions should be converted with `materialize` / `responses get --materialize`, and timing should be read from `duration_seconds`, `render_seconds`, and `realtime_ratio`.
 - Music takes ~60 seconds. Appears in output when done.
 - Images are typically ready in 15-30 seconds.
 - stdout is always machine-readable JSON/text. Human-friendly logs go to stderr.