makaron-cli 0.8.3 → 0.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "AI image editing, video generation, and music creation via CLI. Agents can self-register, create projects, and produce creative media.",
   "author": {
     "name": "Makaron AI",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "AI image editing, video generation, and music creation via CLI. Agents can self-register, create projects, and produce creative media.",
   "displayName": "Makaron",
   "shortDescription": "AI image/video/music creation from the terminal",

package/README.md

@@ -75,6 +75,10 @@ npx makaron-cli responses get $RUN_ID --wait --json
 
 Use `chat` for all creative tasks. Makaron Agent decides how to execute — it can edit images, generate videos, compose music, and create designs in a single conversation.
 
+```bash
+npx makaron-cli chat --help
+```
+
 ### Submit a request
 
 ```bash
@@ -91,6 +95,18 @@ Returns immediately:
 {"runId": "xxx", "projectId": "...", "projectUrl": "https://www.makaron.app/projects/...", "status": "running"}
 ```
 
+### Common workflows
+
+| What you want | Example |
+|--------------|---------|
+| Edit an image | `npx makaron-cli chat --project <id> --image photo.jpg "remove the person in the background"` |
+| Generate an image | `npx makaron-cli chat --project auto "generate a cinematic poster of a rainy Tokyo alley"` |
+| Make a video from the current project | `npx makaron-cli chat --project <id> "make this into a 5 second cinematic video"` |
+| Fix one moment in a video from a screenshot | `npx makaron-cli chat --project <id> --image screenshot.png "@4 this frame should be Paris; only fix this moment"` |
+| Cut or assemble video | `npx makaron-cli chat --project <id> --video clip.mp4 "cut out the dead air and keep the best 20 seconds"` |
+| Add music | `npx makaron-cli chat --project <id> "add calm piano background music"` |
+| Create motion design | `npx makaron-cli chat --project <id> "make an animated Instagram story with this image"` |
+
 ### With additional images (existing project)
 
 ```bash
@@ -124,6 +140,18 @@ Video files are uploaded via signed URL. CLI local video uploads support `.mp4`,
 The agent understands video content natively — it can analyze scenes, edit, extend, and compose videos. Seedance video-reference editing is still limited to ~15s provider references, so longer uploaded videos should be split/prepared by the agent before model submission; Kling remains the base/direct edit path.
 Use `chat --project <id|auto> --video ...` for any project/timeline video work. Direct `video create` is standalone and does not write timeline entries.
 
+### Fix one video moment from a screenshot
+
+When a video is mostly good but one moment needs a local fix, attach a screenshot of the problem frame and describe the correction in normal language:
+
+```bash
+npx makaron-cli chat --project <id> \
+  --image screenshot.png \
+  "@4 this frame should be Paris, keep the same style and only fix this moment"
+```
+
+Makaron can locate the screenshot in the video, regenerate only the nearby segment, and then print a `Next steps` command when the new clip should be stitched back into the full MP4.
+
 ### Check status (single query)
 
 ```bash
@@ -170,15 +198,14 @@ npx makaron-cli edit --image photo.jpg "add cinematic warm lighting"
 # Text-to-image (no input)
 npx makaron-cli edit "a cyberpunk cityscape at night"
 
-# With model/skill/reference
-npx makaron-cli edit --image photo.jpg --model openai --skill captions "add title"
+# With model/reference
 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"
 ```
 
-Options: `--image`, `--model gemini|qwen|openai|pony|wai`, `--skill enhance|creative|wild|captions`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--out <path>`
+Options: `--image`, `--model gemini|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--out <path>`
 
 ### `video` — Standalone video tools (no project timeline)
 
@@ -206,9 +233,9 @@ 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 7), `--video <file|url>`, `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--model kling|seedance`. SeeDance accepts integer output duration 4-15s (default 5s); Kling supports 5-10s.
+Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to 7), `--video <file|url>`, `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--model kling|seedance`. SeeDance accepts integer output duration 4-15s (default 5s); Kling supports 5-15s.
 
-Video edit model behavior: `--model kling --video` uses Kling base/direct edit internally; `--model seedance --video` uses the Seedance video-reference path and requires target <=15s, <=1080p input. Tiny metadata padding up to 15.5s is accepted and output duration is clamped to 15s.
+Video edit model behavior: `--model kling --video` uses Kling base/direct edit internally; `--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. Tiny metadata padding up to 15.5s is accepted and output duration is clamped to 15s.
 
 ### `music` — Music generation
 
@@ -237,8 +264,15 @@ type MakaronOutput =
   | { id: string; type: "text"; status: "completed"; content: string }
   | { id: string; type: "image"; status: "completed"; url: string; snapshot_id: string }
   | { id: string; type: "design"; status: "completed"; url: string; width: number; height: number; animated: boolean; duration?: number }
-  | { id: string; type: "video"; status: "queued"|"rendering"|"completed"|"failed"; task_id: string; url?: string; elapsed_seconds?: number }
+  | { id: string; type: "video"; status: "queued"|"rendering"|"completed"|"failed"; task_id: string; snapshot_id?: string; url?: string; elapsed_seconds?: number; width?: number; height?: number; error?: string; completion_actions?: CompletionAction[] }
   | { id: string; type: "music"; status: "queued"|"rendering"|"completed"|"failed"; task_id: string; url?: string; elapsed_seconds?: number }
+
+type CompletionAction = {
+  label: string
+  prompt: string
+  description?: string
+  policy?: "confirm" | "auto"
+}
 ```
 
 ## Polling Rules
@@ -247,6 +281,7 @@ type MakaronOutput =
 2. Use `next_poll_after_ms` as interval (default 5000ms)
 3. Stop when `status` is `"completed"`, `"failed"`, or `"aborted"`
 4. Top-level `status: "completed"` means ALL artifacts are ready (including rendered videos)
+5. If an async video fails, top-level `status` is `"failed"` and the failed video may include `completion_actions` for a safe retry or diagnosis. Agents can surface these as the next user-confirmed step.
 
 ## Exit Codes
 
@@ -266,6 +301,7 @@ type MakaronOutput =
 | Text-to-image | "generate a cyberpunk cityscape" |
 | Video from image | "create a 5 second video of her walking" |
 | Video with model | "use seedance model, make a 5s video" |
+| Real MP4 edits | `--video clip.mp4 "trim this to the best 20 seconds and preserve audio"` |
 | **Edit video** | **"put Iron Man armor on me in this video"** |
 | **Compose videos** | **"combine @1 and @2 into one party video"** |
 | **Extend video** | **"continue the story for 10 more seconds"** |
@@ -320,6 +356,7 @@ send_message "All done!"
 - stdout is always machine-readable JSON/text. Human-friendly logs go to stderr.
 - Always use `chat` as the primary interface — even for single image edits.
 - `edit`/`video`/`music` are fallback tools for when `chat` is unavailable or you need raw model access without project context.
+- The CLI checks npm for updates at most once per day and prints update notices to stderr. Set `MAKARON_DISABLE_UPDATE_CHECK=1` to disable it.
 
 ## Admin: Skill Marketplace Operations
 

package/bin/makaron.mjs

@@ -19,9 +19,13 @@ import { execFileSync } from 'child_process';
 // ─── Config ──────────────────────────────────────────────────────────────────
 
 const AUTH_FILE = path.join(process.env.HOME || '~', '.makaron', 'auth.json');
+const UPDATE_CHECK_FILE = path.join(process.env.HOME || '~', '.makaron', 'update-check.json');
 const DEFAULT_URL = 'https://www.makaron.app';
 const BASE_URL = process.env.MAKARON_URL || DEFAULT_URL;
 const APP_URL = process.env.MAKARON_APP_URL || DEFAULT_URL;
+const NPM_PACKAGE_NAME = 'makaron-cli';
+const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const UPDATE_CHECK_TIMEOUT_MS = 400;
 
 // Public anon key (safe to embed — only enables auth, not data access)
 const SUPABASE_URL = 'https://sdyrtztrjgmmpnirswxt.supabase.co';
@@ -34,6 +38,11 @@ const MAX_VIDEO_UPLOAD_DURATION_TOLERANCE = 1;
 const MAX_VIDEO_PROVIDER_REFERENCE_DURATION = 15;
 const MAX_VIDEO_PROVIDER_REFERENCE_DURATION_TOLERANCE = 0.5;
 const MAX_VIDEO_FRAME_PIXELS = 2_086_876;
+const SEEDANCE_MIN_VIDEO_FRAME_PIXELS = 409_600;
+const SEEDANCE_MIN_VIDEO_SIDE = 300;
+const SEEDANCE_MAX_VIDEO_SIDE = 6000;
+const SEEDANCE_MIN_VIDEO_ASPECT = 0.4;
+const SEEDANCE_MAX_VIDEO_ASPECT = 2.5;
 
 function getCliVersion() {
   try {
@@ -44,6 +53,84 @@ function getCliVersion() {
   }
 }
 
+function compareVersions(a, b) {
+  const parse = (version) => String(version || '')
+    .split('-')[0]
+    .split('.')
+    .map(part => Number.parseInt(part, 10) || 0);
+  const left = parse(a);
+  const right = parse(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+function readUpdateCache() {
+  try {
+    return JSON.parse(fs.readFileSync(UPDATE_CHECK_FILE, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeUpdateCache(data) {
+  try {
+    const dir = path.dirname(UPDATE_CHECK_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(UPDATE_CHECK_FILE, JSON.stringify(data, null, 2));
+  } catch { /* best effort */ }
+}
+
+function shouldCheckForUpdates(command, args) {
+  if (!command || command === '--version' || command === '-v' || command === 'version') return false;
+  if (args.includes('--help') || args.includes('-h')) return false;
+  if (args.includes('--json') || args.includes('--jsonl') || args.includes('--pick')) return false;
+  if (process.env.CI || process.env.NO_UPDATE_NOTIFIER || process.env.MAKARON_DISABLE_UPDATE_CHECK) return false;
+  return true;
+}
+
+async function maybeNotifyUpdate(command, args) {
+  if (!shouldCheckForUpdates(command, args)) return;
+  const currentVersion = getCliVersion();
+  const now = Date.now();
+  const cache = readUpdateCache();
+  if (cache?.checkedAt && now - cache.checkedAt < UPDATE_CHECK_INTERVAL_MS) {
+    if (cache.latestVersion && compareVersions(cache.latestVersion, currentVersion) > 0) {
+      printUpdateNotice(currentVersion, cache.latestVersion);
+    }
+    return;
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), UPDATE_CHECK_TIMEOUT_MS);
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`, {
+      signal: controller.signal,
+      headers: { 'Accept': 'application/json' },
+    });
+    if (!res.ok) return;
+    const data = await res.json();
+    const latestVersion = data?.version;
+    if (!latestVersion) return;
+    writeUpdateCache({ checkedAt: now, latestVersion });
+    if (compareVersions(latestVersion, currentVersion) > 0) {
+      printUpdateNotice(currentVersion, latestVersion);
+    }
+  } catch {
+    writeUpdateCache({ checkedAt: now, latestVersion: cache?.latestVersion || currentVersion });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function printUpdateNotice(currentVersion, latestVersion) {
+  process.stderr.write(`\nUpdate available: makaron-cli ${currentVersion} -> ${latestVersion}\n`);
+  process.stderr.write('Run: npm install -g makaron-cli@latest\n');
+  process.stderr.write('Or:  npx makaron-cli@latest ...\n\n');
+}
+
 function formatSeconds(seconds) {
   if (!Number.isFinite(seconds)) return String(seconds);
   return Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(1).replace(/\.0$/, '');
@@ -148,6 +235,80 @@ function normalizeRunResponse(data) {
   return data;
 }
 
+function collectCompletionActions(data) {
+  const items = [];
+  const add = (action, source) => {
+    if (!action?.label || !action?.prompt) return;
+    const key = `${action.label}\n${action.prompt}`;
+    if (items.some(i => i.key === key)) return;
+    items.push({ key, label: action.label, prompt: action.prompt, description: action.description, source });
+  };
+  for (const out of data.output || []) {
+    for (const action of out.completion_actions || out.completionActions || []) add(action, out.id || out.task_id);
+  }
+  for (const video of data.result?.videos || []) {
+    for (const action of video.completion_actions || video.completionActions || []) add(action, video.taskId);
+  }
+  return items;
+}
+
+function printCompletionActions(data) {
+  const projectId = data.projectId || data.project_id;
+  const actions = collectCompletionActions(data);
+  if (!projectId || actions.length === 0) return;
+  process.stderr.write('\nNext steps:\n');
+  for (const action of actions) {
+    process.stderr.write(`• ${action.label}${action.description ? ` — ${action.description}` : ''}\n`);
+    process.stderr.write(`  makaron chat --project ${projectId} ${JSON.stringify(action.prompt)}\n`);
+  }
+}
+
+function printChatHelp() {
+  console.log(`Makaron chat — create and edit with Makaron Agent
+
+Usage:
+  makaron chat --project <id|auto> [options] "your message"
+
+Options:
+  --project <id|auto>       Project to work in. Use "auto" to create one.
+  --image <file|url>        Attach a reference image or screenshot. Repeatable.
+  --video <file|url>        Attach a video to the project timeline. Repeatable.
+  --model <name>            Preferred image/model route.
+  --video-model <name>      Preferred video model.
+  --background, -b          Submit and print a runId.
+  --json                    Output structured JSON.
+  --stream                  Legacy live SSE stream.
+  --help, -h                Show this help.
+
+What you can ask:
+  Image edit
+    makaron chat --project <id> --image photo.jpg "remove the person in the background"
+
+  Image generation
+    makaron chat --project auto "generate a cinematic poster of a rainy Tokyo alley"
+
+  Video from image or timeline
+    makaron chat --project <id> "make this into a 5 second cinematic video"
+
+  Fix one video moment from a screenshot
+    makaron chat --project <id> --image screenshot.png "@4 this frame should be Paris; only fix this moment"
+
+  Video cuts and assembly
+    makaron chat --project <id> --video clip.mp4 "cut out the dead air and keep the best 20 seconds"
+
+  Music
+    makaron chat --project <id> "add calm piano background music"
+
+  Motion design
+    makaron chat --project <id> "make an animated Instagram story with this image"
+
+After async generation:
+  The CLI waits for video/music tasks. If the result has a natural next step, it prints:
+    Next steps:
+      makaron chat --project <id> "..."
+`);
+}
+
 // ─── SSE Consumer ────────────────────────────────────────────────────────────
 
 async function abortRun(baseUrl, headers, runId) {
@@ -394,6 +555,7 @@ async function pollRun(baseUrl, headers, runId, opts = {}) {
             else if (v.status === 'failed') process.stderr.write(`🎬  Video ${v.taskId}: failed${v.error ? ` — ${v.error}` : ''}\n`);
             else process.stderr.write(`🎬  Video ${v.taskId}: ${v.status || 'submitted'}\n`);
           }
+          printCompletionActions(data);
           for (const m of data.result.music || []) {
             if (m.audioUrl) process.stderr.write(`🎵  Music: ${m.audioUrl}\n`);
             else process.stderr.write(`🎵  Music ${m.taskId}: ${m.status || 'submitted'}\n`);
@@ -421,6 +583,12 @@ function applyPick(data, field) {
     case 'design_urls': return (data.output || []).filter(o => o.type === 'design' && o.url).map(o => o.url);
     case 'first_music_url': return data.output?.find(o => o.type === 'music' && o.url)?.url || null;
     case 'music_urls': return (data.output || []).filter(o => o.type === 'music' && o.url).map(o => o.url);
+    case 'next_steps': return collectCompletionActions(data).map(action => ({
+      label: action.label,
+      prompt: action.prompt,
+      description: action.description,
+      source: action.source,
+    }));
     case 'project_url': return data.project_url || data.projectUrl || null;
     case 'output': return data.output || [];
     case 'text': return data.output?.find(o => o.type === 'text')?.content || null;
@@ -768,6 +936,11 @@ function probeLocalVideo(videoPath) {
 function validateVideoFile(videoPath, options = {}) {
   const maxDuration = options.maxDuration ?? MAX_VIDEO_UPLOAD_DURATION;
   const durationTolerance = options.durationTolerance ?? MAX_VIDEO_UPLOAD_DURATION_TOLERANCE;
+  const minFramePixels = options.minFramePixels ?? 0;
+  const minSide = options.minSide ?? 0;
+  const maxSide = options.maxSide ?? Infinity;
+  const minAspect = options.minAspect ?? 0;
+  const maxAspect = options.maxAspect ?? Infinity;
   if (!fs.existsSync(videoPath)) {
     return { ok: false, error: `Video file not found: ${videoPath}` };
   }
@@ -789,6 +962,19 @@ function validateVideoFile(videoPath, options = {}) {
   if (meta.width * meta.height > MAX_VIDEO_FRAME_PIXELS) {
     return { ok: false, error: `Video resolution too high: ${meta.width}x${meta.height} (${meta.width * meta.height} px). Max is <=1080p (${MAX_VIDEO_FRAME_PIXELS} px). Re-upload through the frontend to transcode, or export a smaller video.` };
   }
+  const framePixels = meta.width * meta.height;
+  const aspect = meta.width / meta.height;
+  if (
+    framePixels < minFramePixels ||
+    meta.width < minSide ||
+    meta.height < minSide ||
+    meta.width > maxSide ||
+    meta.height > maxSide ||
+    aspect < minAspect ||
+    aspect > maxAspect
+  ) {
+    return { ok: false, error: `Video size does not meet provider limits: ${meta.width}x${meta.height} (${framePixels} px, aspect ${aspect.toFixed(2)}). Required: frame pixels >=${minFramePixels}, sides ${minSide}-${Number.isFinite(maxSide) ? maxSide : '∞'}px, aspect ${minAspect}-${Number.isFinite(maxAspect) ? maxAspect : '∞'}. Resize/pad with FFmpeg before submitting.` };
+  }
   const mime = ext === 'mov' ? 'video/quicktime' : ext === 'webm' ? 'video/webm' : 'video/mp4';
   return { ok: true, mime, meta };
 }
@@ -850,12 +1036,135 @@ async function analyzeVideoCli(baseUrl, headers, rawVideo, questionParts) {
   if (text) console.log(text);
 }
 
+// ─── Help ───────────────────────────────────────────────────────────────────
+
+function hasHelpFlag(values) {
+  return values.includes('--help') || values.includes('-h');
+}
+
+function printRootHelp() {
+  console.log(`Makaron CLI — Talk to Makaron Agent from the terminal
+
+Commands:
+  register --json                    Get challenge for agent self-registration
+  register --verify --challenge-id <id> --answer <n>  Verify and save API key
+  claim                              Get claim URL for human to link account
+  login                              Log in to Makaron (human interactive)
+  list (ls)                          List all projects
+  project media <projectId> --json    List timeline media for a project
+  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)
+
+  chat --project <id> "message"      Chat (non-blocking, polls for result)
+  chat --project <id> --video <file> Attach video to conversation
+  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
+
+  responses get <runId>              Get run status and results
+  responses get <runId> --wait       Poll until completed
+  responses list --project <id>      List runs for a project
+  abort <runId>                      Abort a running Agent
+
+  edit [--image <file>] "prompt"     AI image edit / text-to-image
+  analyze --video <file|url>         Analyze video content
+  video script|create|status         Video generation
+  music create|status                Music generation
+
+  admin                              Admin commands (skills, upload, set-admin)
+
+Environment:
+  MAKARON_API_KEY  API key (mk_live_xxx) — recommended for agents
+  MAKARON_URL      API base (default: ${DEFAULT_URL})
+`);
+}
+
+function printHelp(topic, subtopic) {
+  if (topic === 'login') {
+    console.log('Usage: makaron login');
+  } else if (topic === 'create') {
+    console.log('Usage: makaron create --image <file> [--image <file2>] | --image-url <url> | --title "name"');
+  } else if (topic === 'chat') {
+    console.log('Usage: makaron chat --project <id|auto> [--image <file>] [--video <file|url>] [--stream] [--background|-b] [--json] "your message"');
+  } else if (topic === 'responses' || topic === 'run') {
+    if (subtopic === 'get') console.log('Usage: makaron responses get <runId> [--wait] [--json] [--pick <field>]');
+    else if (subtopic === 'watch') console.log('Usage: makaron responses watch <runId> [--jsonl] [--interval <ms>]');
+    else if (subtopic === 'list') console.log('Usage: makaron responses list --project <id>');
+    else console.log(`Responses commands:
+  responses get <runId>                  Get status and output (JSON)
+  responses get <runId> --wait           Poll until completed
+  responses get <runId> --pick <field>   Extract: first_image_url, first_video_url, project_url, output
+  responses watch <runId> --jsonl        Watch until done (incremental events)
+  responses list --project <id>          List runs for a project
+`);
+  } else if (topic === 'list' || topic === 'ls') {
+    console.log('Usage: makaron list');
+  } else if (topic === 'project' || topic === 'projects') {
+    if (subtopic === 'media') console.log('Usage: makaron project media <projectId> [--json]');
+    else console.log(`Project commands:
+  project media <projectId> --json      List timeline media for a project
+`);
+  } else if (topic === 'abort') {
+    console.log('Usage: makaron abort <runId>');
+  } else if (topic === 'edit') {
+    console.log('Usage: makaron edit [--image <file|url>] [--model gemini|qwen|openai] [--skill enhance|creative|wild|captions] [--ref <file>] [--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 <public-url>) [--duration 10] [--aspect 9:16] [--model kling|seedance] [--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 "..." --image <url> [--duration 10]  Submit video task
+  video create --script "..." --video <public-url> [--model kling|seedance]  Edit a video (standalone)
+  video status <taskId>                                      Check video status
+  video status --snapshot <snapshotId> [--wait]              Check v2 video snapshot
+`);
+  } else if (topic === 'music') {
+    if (subtopic === 'create') console.log('Usage: makaron music create [--vocals] [--style "genre"] "description"');
+    else if (subtopic === 'status') console.log('Usage: makaron music status <taskId>');
+    else console.log(`Music commands:
+  music create [--vocals] [--style "genre"] "description"    Generate music
+  music status <taskId>                                      Check music status
+`);
+  } else if (topic === 'admin') {
+    if (subtopic === 'skills') console.log('Usage: makaron admin skills [add|update|delete] ...');
+    else if (subtopic === 'upload') console.log('Usage: makaron admin upload <local-file> <storage-path>');
+    else if (subtopic === 'fetch-skill') console.log('Usage: makaron admin fetch-skill <share-code|url>');
+    else if (subtopic === 'set-admin') console.log('Usage: makaron admin set-admin <email>');
+    else console.log(`Admin commands:
+  admin skills                         List all marketplace skills
+  admin skills add '<json>'            Add a new skill
+  admin skills update <id> '<json>'    Update a skill
+  admin skills delete <id>             Delete a skill
+  admin upload <file> <storage-path>   Upload file to Storage
+  admin fetch-skill <code|url>         Download skill from share link
+  admin set-admin <email>              Grant admin access to a user
+`);
+  } else if (topic === 'register') {
+    if (subtopic === '--verify') console.log('Usage: makaron register --verify --challenge-id <id> --answer <number>');
+    else console.log('Usage: makaron register --json | makaron register --verify --challenge-id <id> --answer <number>');
+  } else if (topic === 'claim') {
+    console.log('Usage: makaron claim');
+  } else {
+    printRootHelp();
+  }
+}
+
 // ─── Main ────────────────────────────────────────────────────────────────────
 
 const args = process.argv.slice(2);
 const command = args[0];
 
-if (command === '--version' || command === '-v' || command === 'version') {
+await maybeNotifyUpdate(command, args);
+
+if (!command || command === '--help' || command === '-h' || command === 'help') {
+  printRootHelp();
+} else if (hasHelpFlag(args)) {
+  printHelp(command, args[1]);
+} else if (command === '--version' || command === '-v' || command === 'version') {
   console.log(getCliVersion());
 } else if (command === 'login') {
   await login();
@@ -875,7 +1184,10 @@ if (command === '--version' || command === '-v' || command === 'version') {
   }
   await createProject(baseUrl, headers, opts);
 } else if (command === 'chat') {
-  const { headers, baseUrl } = getAuth();
+  if (args.includes('--help') || args.includes('-h')) {
+    printChatHelp();
+    process.exit(0);
+  }
   let projectId = null;
   const chatImages = [];
   const chatVideos = [];
@@ -883,16 +1195,14 @@ if (command === '--version' || command === '-v' || command === 'version') {
   let useStream = false;
   let background = false;
   let jsonOutput = false;
+  let activeSkill = undefined;
   let videoModel = undefined;
   let preferredModel = undefined;
   for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--help' || args[i] === '-h') {
-      console.error('Usage: makaron chat --project <id|auto> [--image <file>] [--video <file|url>] [--stream] [--background|-b] [--json] "your message"');
-      process.exit(0);
-    }
-    else if (args[i] === '--project' && args[i + 1]) projectId = args[++i];
+    if (args[i] === '--project' && args[i + 1]) projectId = args[++i];
     else if (args[i] === '--image' && args[i + 1]) chatImages.push(args[++i]);
     else if (args[i] === '--video' && args[i + 1]) chatVideos.push(args[++i]);
+    else if (args[i] === '--skill' && args[i + 1]) activeSkill = args[++i];
     else if (args[i] === '--stream') useStream = true;
     else if (args[i] === '--background' || args[i] === '-b') background = true;
     else if (args[i] === '--json') jsonOutput = true;
@@ -902,9 +1212,11 @@ if (command === '--version' || command === '-v' || command === 'version') {
   }
   const prompt = promptParts.join(' ');
   if (!prompt) {
-    console.error('Usage: makaron chat --project <id|auto> [--image <file>] [--video <file|url>] [--stream] [--background|-b] [--json] "your message"');
+    console.error('Usage: makaron chat --project <id|auto> [options] "your message"');
+    console.error('Run: makaron chat --help');
     process.exit(1);
   }
+  const { headers, baseUrl } = getAuth();
   // Split images into URLs vs local files
   const imageUrlList = chatImages.filter(p => p.startsWith('http://') || p.startsWith('https://'));
   const imageFileList = chatImages.filter(p => !p.startsWith('http://') && !p.startsWith('https://'));
@@ -982,7 +1294,7 @@ if (command === '--version' || command === '-v' || command === 'version') {
   }
 
   // Upload videos to project timeline (via /api/projects/create with videoUrls)
-  let finalPrompt = prompt;
+  let finalPrompt = activeSkill ? `[Active skill: ${activeSkill}]\n${prompt}` : prompt;
   if (chatVideos.length > 0) {
     // Upload local files via signed URL (no size limit, works with API key auth)
     const uploadedVideoUrls = [...prevalidatedVideoUrlList];
@@ -1026,7 +1338,7 @@ if (command === '--version' || command === '-v' || command === 'version') {
 
     // Inject hint so Agent knows videos are available
     const hint = `[User uploaded ${chatVideos.length === 1 ? 'a video' : `${chatVideos.length} videos`}. Use analyze_video to understand the content.]`;
-    finalPrompt = `${prompt}\n\n${hint}`;
+    finalPrompt = `${finalPrompt}\n\n${hint}`;
   }
 
   if (useStream) {
@@ -1171,7 +1483,7 @@ if (command === '--version' || command === '-v' || command === 'version') {
     else promptParts.push(args[i]);
   }
   editArgs.editPrompt = promptParts.join(' ');
-  if (!editArgs.editPrompt) { console.error('Usage: makaron edit [--image <file|url>] [--model gemini|qwen|openai] [--skill enhance|creative|wild|captions] [--ref <file>] [--out <file>] "prompt"'); process.exit(1); }
+  if (!editArgs.editPrompt) { console.error('Usage: makaron edit [--image <file|url>] [--model gemini|qwen|openai] [--ref <file>] [--out <file>] "prompt"'); process.exit(1); }
   process.stderr.write('🎨 Generating...\n');
   const result = await callMcpTool(baseUrl, headers, 'makaron_edit_image', editArgs);
   saveMcpImage(result, outputPath);
@@ -1236,13 +1548,21 @@ if (command === '--version' || command === '-v' || command === 'version') {
 
     let videoUrl = isHttpUrl(video) ? video : null;
     let inputVideoMeta = null;
+    const selectedVideoModel = videoModel || 'kling';
     if (videoUrl) {
-      process.stderr.write(`📹 Assuming public video URL already matches provider reference limits: ≤${MAX_VIDEO_PROVIDER_REFERENCE_DURATION}s, ≤${MAX_VIDEO_UPLOAD_FILE_SIZE_MB}MB, ≤1080p.\n`);
+      process.stderr.write(`📹 Assuming public video URL already matches provider reference limits. Seedance requires ≤${MAX_VIDEO_PROVIDER_REFERENCE_DURATION}s, ≤50MB, sides 300-6000px, frame pixels 409,600-${MAX_VIDEO_FRAME_PIXELS}; Kling requires ≤200MB and ≤2K.\n`);
     }
     if (video && !videoUrl) {
       const valid = validateVideoFile(video, {
         maxDuration: MAX_VIDEO_PROVIDER_REFERENCE_DURATION,
         durationTolerance: MAX_VIDEO_PROVIDER_REFERENCE_DURATION_TOLERANCE,
+        ...(selectedVideoModel === 'seedance' ? {
+          minFramePixels: SEEDANCE_MIN_VIDEO_FRAME_PIXELS,
+          minSide: SEEDANCE_MIN_VIDEO_SIDE,
+          maxSide: SEEDANCE_MAX_VIDEO_SIDE,
+          minAspect: SEEDANCE_MIN_VIDEO_ASPECT,
+          maxAspect: SEEDANCE_MAX_VIDEO_ASPECT,
+        } : {}),
       });
       if (!valid.ok) { console.error(`❌ ${valid.error}`); process.exit(1); }
       inputVideoMeta = valid.meta;
@@ -1254,7 +1574,7 @@ if (command === '--version' || command === '-v' || command === 'version') {
     // Standalone MCP tool (no project timeline write)
     process.stderr.write('🎬 Submitting video...\n');
     const vArgs = videoUrl
-      ? { videoUrl, editPrompt: script, images, videoModel: videoModel || 'kling', referType: (videoModel || 'kling') === 'seedance' ? 'feature' : 'base' }
+      ? { videoUrl, editPrompt: script, images, videoModel: selectedVideoModel, referType: selectedVideoModel === 'seedance' ? 'feature' : 'base' }
       : { script, images };
     const effectiveDuration = duration || (inputVideoMeta?.duration ? Math.min(MAX_VIDEO_PROVIDER_REFERENCE_DURATION, Math.round(inputVideoMeta.duration)) : undefined);
     if (effectiveDuration) vArgs.duration = effectiveDuration;
@@ -1549,39 +1869,5 @@ if (command === '--version' || command === '-v' || command === 'version') {
   console.log(JSON.stringify(data));
   console.error(`🔗 Share this link with a human: ${data.claim_url}`);
 } else {
-  console.log(`Makaron CLI — Talk to Makaron Agent from the terminal
-
-Commands:
-  register --json                    Get challenge for agent self-registration
-  register --verify --challenge-id <id> --answer <n>  Verify and save API key
-  claim                              Get claim URL for human to link account
-  login                              Log in to Makaron (human interactive)
-  list (ls)                          List all projects
-  project media <projectId> --json    List timeline media for a project
-  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)
-
-  chat --project <id> "message"      Chat (non-blocking, polls for result)
-  chat --project <id> --video <file> Attach video to conversation
-  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
-
-  responses get <runId>              Get run status and results
-  responses get <runId> --wait       Poll until completed
-  responses list --project <id>      List runs for a project
-  abort <runId>                      Abort a running Agent
-
-  edit [--image <file>] "prompt"     AI image edit / text-to-image
-  analyze --video <file|url>         Analyze video content
-  video script|create|status         Video generation
-  music create|status                Music generation
-
-  admin                              Admin commands (skills, upload, set-admin)
-
-Environment:
-  MAKARON_API_KEY  API key (mk_live_xxx) — recommended for agents
-  MAKARON_URL      API base (default: ${DEFAULT_URL})
-`);
+  printRootHelp();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
   "scripts": {
@@ -9,14 +9,13 @@
     "test:live": "MAKARON_LIVE=1 node test/live-smoke.mjs"
   },
   "bin": {
-    "makaron": "./bin/makaron.mjs"
+    "makaron": "bin/makaron.mjs"
   },
   "files": [
     "bin/",
     "skills/",
     ".codex-plugin/",
     ".claude-plugin/",
-    "SKILL.md",
     "README.md"
   ],
   "keywords": [
@@ -30,6 +29,6 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/vegekyd/ai-image-editor"
+    "url": "git+https://github.com/vegekyd/ai-image-editor.git"
   }
 }

package/skills/makaron/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: makaron
-description: Use Makaron CLI to generate AI images, videos, music, and motion designs. Trigger when user needs creative media production — photo editing, video generation, music composition, or design creation. Requires `npx makaron-cli` and MAKARON_API_KEY env var.
+description: Use Makaron CLI to generate AI images, videos, music, and motion designs. Trigger when user needs creative media production — photo editing, video generation, video editing, music composition, or design creation. Requires `npx makaron-cli` and MAKARON_API_KEY env var.
 ---
 
 # Makaron CLI — Agent Integration Skill
@@ -64,6 +64,10 @@ npx makaron-cli responses get $RUN_ID --wait --json
 
 Use `chat` for all creative tasks. Makaron Agent decides how to execute — it can edit images, generate videos, compose music, and create designs in a single conversation.
 
+```bash
+npx makaron-cli chat --help
+```
+
 ### Submit a request
 
 ```bash
@@ -80,6 +84,18 @@ Returns immediately:
 {"runId": "xxx", "projectId": "...", "projectUrl": "https://www.makaron.app/projects/...", "status": "running"}
 ```
 
+### Common workflows
+
+| What you want | Example |
+|--------------|---------|
+| Edit an image | `npx makaron-cli chat --project <id> --image photo.jpg "remove the person in the background"` |
+| Generate an image | `npx makaron-cli chat --project auto "generate a cinematic poster of a rainy Tokyo alley"` |
+| Make a video from the current project | `npx makaron-cli chat --project <id> "make this into a 5 second cinematic video"` |
+| Fix one moment in a video from a screenshot | `npx makaron-cli chat --project <id> --image screenshot.png "@4 this frame should be Paris; only fix this moment"` |
+| Cut or assemble video | `npx makaron-cli chat --project <id> --video clip.mp4 "cut out the dead air and keep the best 20 seconds"` |
+| Add music | `npx makaron-cli chat --project <id> "add calm piano background music"` |
+| Create motion design | `npx makaron-cli chat --project <id> "make an animated Instagram story with this image"` |
+
 ### With additional images (existing project)
 
 ```bash
@@ -116,6 +132,18 @@ Supported formats: MP4, MOV, WebM. CLI local video uploads support max 50MB, max
 
 Use `chat --project <id|auto> --video ...` for any project/timeline video work. Direct video commands are standalone raw-tool calls.
 
+### Fix one video moment from a screenshot
+
+When a video is mostly good but one moment needs a local fix, attach a screenshot of the problem frame and describe the correction in normal language:
+
+```bash
+npx makaron-cli chat --project <id> \
+  --image screenshot.png \
+  "@4 this frame should be Paris, keep the same style and only fix this moment"
+```
+
+Makaron can locate the screenshot in the video, regenerate only the nearby segment, and then print a `Next steps` command when the new clip should be stitched back into the full MP4.
+
 ### Check status (single query)
 
 ```bash
@@ -162,15 +190,14 @@ npx makaron-cli edit --image photo.jpg "add cinematic warm lighting"
 # Text-to-image (no input)
 npx makaron-cli edit "a cyberpunk cityscape at night"
 
-# With model/skill/reference
-npx makaron-cli edit --image photo.jpg --model openai --skill captions "add title"
+# With model/reference
 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"
 ```
 
-Options: `--image`, `--model gemini|qwen|openai|pony|wai`, `--skill enhance|creative|wild|captions`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--out <path>`
+Options: `--image`, `--model gemini|qwen|openai|pony|wai`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--out <path>`
 
 ### `video` — Standalone video tools (no project timeline)
 
@@ -198,9 +225,9 @@ 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 7), `--video <file|url>`, `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--model kling|seedance`. SeeDance accepts integer output duration 4-15s (default 5s); Kling supports 5-10s.
+Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to 7), `--video <file|url>`, `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--model kling|seedance`. SeeDance accepts integer output duration 4-15s (default 5s); Kling supports 5-15s.
 
-Video edit model behavior: `--model kling --video` uses Kling base/direct edit internally; `--model seedance --video` uses the Seedance video-reference path and requires target <=15s, <=1080p input. Tiny metadata padding up to 15.5s is accepted and output duration is clamped to 15s.
+Video edit model behavior: `--model kling --video` uses Kling base/direct edit internally; `--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. Tiny metadata padding up to 15.5s is accepted and output duration is clamped to 15s.
 
 ### `music` — Music generation
 
@@ -229,8 +256,15 @@ type MakaronOutput =
   | { id: string; type: "text"; status: "completed"; content: string }
   | { id: string; type: "image"; status: "completed"; url: string; snapshot_id: string }
   | { id: string; type: "design"; status: "completed"; url: string; width: number; height: number; animated: boolean; duration?: number }
-  | { id: string; type: "video"; status: "queued"|"rendering"|"completed"|"failed"; task_id: string; snapshot_id?: string; url?: string; elapsed_seconds?: number; width?: number; height?: number }
+  | { id: string; type: "video"; status: "queued"|"rendering"|"completed"|"failed"; task_id: string; snapshot_id?: string; url?: string; elapsed_seconds?: number; width?: number; height?: number; error?: string; completion_actions?: CompletionAction[] }
   | { id: string; type: "music"; status: "queued"|"rendering"|"completed"|"failed"; task_id: string; url?: string; elapsed_seconds?: number }
+
+type CompletionAction = {
+  label: string
+  prompt: string
+  description?: string
+  policy?: "confirm" | "auto"
+}
 ```
 
 ## Polling Rules
@@ -239,6 +273,7 @@ type MakaronOutput =
 2. Use `next_poll_after_ms` as interval (default 5000ms)
 3. Stop when `status` is `"completed"`, `"failed"`, or `"aborted"`
 4. Top-level `status: "completed"` means ALL artifacts are ready (including rendered videos)
+5. If an async video fails, top-level `status` is `"failed"` and the failed video may include `completion_actions` for a safe retry or diagnosis. Agents can surface these as the next user-confirmed step.
 
 ## Exit Codes
 
@@ -258,6 +293,7 @@ type MakaronOutput =
 | Text-to-image | "generate a cyberpunk cityscape" |
 | Video from image | "create a 5 second video of her walking" |
 | Video with model | "use seedance model, make a 5s video" |
+| Real MP4 edits | `--video clip.mp4 "trim this to the best 20 seconds and preserve audio"` |
 | Background music | "add calm piano music" |
 | Motion design | "create an Instagram story with animated text" |
 | Multi-step | "edit the photo then make a video from it" |

package/SKILL.md

@@ -1,311 +0,0 @@
----
-name: makaron
-description: Use Makaron CLI to generate AI images, videos, music, and motion designs. Trigger when user needs creative media production — photo editing, video generation, music composition, or design creation. Requires `npx makaron-cli` and MAKARON_API_KEY env var.
----
-
-# Makaron CLI — Agent Integration Skill
-
-> **makaron.app** is for humans. **makaron-cli** is for AI agents.
-
-Makaron is a multimodal AI creative agent. You talk to it via `makaron chat`, and it produces images, videos, music, and animated designs — all saved to a persistent project.
-
-## Setup
-
-### Get your API key
-
-**Option A: Human login**
-1. Go to [makaron.app](https://makaron.app) and log in
-2. Open the menu (top-right) → **Get API Key**
-3. Copy your `mk_live_...` key
-
-**Option B: Self-Registration (no human required)**
-```bash
-# Step 1: Get challenge
-npx makaron-cli register --json
-# → { "challenge_id": "...", "challenge": "...", "expected_format": "numeric, round to 2 decimal places" }
-
-# Step 2: Solve and verify
-npx makaron-cli register --verify --challenge-id <id> --answer 34.5
-# → Key saved to ~/.makaron/auth.json
-# → { "api_key": "mk_live_...", "credits": N, "claim_url": "..." }
-
-# (Optional) Let a human claim this account
-npx makaron-cli claim
-# → { "claim_url": "..." } — share with human to link key to their account (valid 7 days)
-```
-
-Discovery endpoint: `GET https://www.makaron.app/api/agent/register` — returns full registration flow + CLI usage as JSON.
-
-After self-registration the key is saved locally — no need to export `MAKARON_API_KEY`.
-
-```bash
-export MAKARON_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-```
-
-Verify: `npx makaron-cli list` should show projects.
-
-## Core Workflow
-
-```bash
-# One-shot: create project + upload image + submit prompt — all in one command
-RUN_ID=$(npx makaron-cli chat --project auto --image photo.jpg -b "make it cinematic and create a 5s video")
-
-# Wait for the final customer-ready result
-npx makaron-cli responses get $RUN_ID --wait --json
-```
-
-Or with an existing project:
-```bash
-RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID -b "make a 5s video")
-npx makaron-cli responses get $RUN_ID --wait --json
-```
-
-## Primary: `chat` (Agent-driven creative work)
-
-Use `chat` for all creative tasks. Makaron Agent decides how to execute — it can edit images, generate videos, compose music, and create designs in a single conversation.
-
-### Submit a request
-
-```bash
-# With existing project
-npx makaron-cli chat --project <id> --json -b "<prompt>"
-
-# Auto-create project (with or without images)
-npx makaron-cli chat --project auto --image photo.jpg --json -b "make it cinematic"
-npx makaron-cli chat --project auto --image img1.jpg --image img2.jpg --json -b "combine these"
-```
-
-Returns immediately:
-```json
-{"runId": "xxx", "projectId": "...", "projectUrl": "https://www.makaron.app/projects/...", "status": "running"}
-```
-
-### With additional images (existing project)
-
-```bash
-npx makaron-cli chat --project <id> --image ref1.jpg --image ref2.jpg -b "use these as style reference"
-```
-
-### Inspect existing timeline media
-
-Before starting a follow-up run on an existing project, list the current timeline media so you know what assets are available and which `<<<media_N>>>` references to use:
-
-```bash
-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.
-
-### With video input (edit, compose, extend)
-
-```bash
-# Upload a video and transform it — Agent understands video content natively
-npx makaron-cli chat --project auto --video selfie.mp4 -b "put Iron Man armor on me"
-
-# Combine a person's photo with a video scene
-npx makaron-cli chat --project <id> --video party.mp4 --image kid.jpg -b "make this kid join the party"
-
-# Multiple videos — compose or splice
-npx makaron-cli chat --project <id> --video clip1.mp4 --video clip2.mp4 -b "combine into one seamless video"
-
-# Video URL (public, downloadable)
-npx makaron-cli chat --project auto --video https://example.com/dance.mp4 -b "extend this to 15 seconds"
-```
-
-Supported formats: MP4, MOV, WebM. CLI local video uploads support max 50MB, max 120s with 1s metadata tolerance, and <=1080p / 2,086,876 frame pixels. The frontend can transcode larger videos before upload; the CLI uploads directly to Storage and rejects videos above those limits. Videos are uploaded to the project timeline. The Agent can analyze scenes, edit content, compose multiple clips, extend duration, and add effects — all via natural language. Seedance video-reference editing is still limited to ~15s provider references, so longer uploaded videos should be split/prepared by the agent before model submission; Kling remains the base/direct edit path.
-
-Use `chat --project <id|auto> --video ...` for any project/timeline video work. Direct video commands are standalone raw-tool calls.
-
-### Check status (single query)
-
-```bash
-npx makaron-cli responses get <runId> --json
-```
-
-### Advanced: stream incremental events
-
-```bash
-npx makaron-cli responses watch <runId> --jsonl
-```
-
-Outputs one JSON per line as artifacts appear:
-```
-{"event":"output.added","item":{"id":"out_1","type":"image","status":"completed","url":"https://..."}}
-{"event":"output.added","item":{"id":"out_2","type":"video","status":"rendering","task_id":"xxx"}}
-{"event":"output.updated","item":{"id":"out_2","type":"video","status":"completed","url":"https://..."}}
-{"event":"done","status":"completed"}
-```
-
-### Extract specific results
-
-```bash
-npx makaron-cli responses get <runId> --pick first_image_url
-npx makaron-cli responses get <runId> --pick image_urls        # all images (JSON array)
-npx makaron-cli responses get <runId> --pick first_video_url
-npx makaron-cli responses get <runId> --pick video_urls        # all videos
-npx makaron-cli responses get <runId> --pick project_url
-npx makaron-cli responses get <runId> --pick text              # agent's text reply
-npx makaron-cli responses get <runId> --pick output            # full output array
-npx makaron-cli responses get <runId> --pick status
-```
-
-## Fallback: Direct tool calls (no project context)
-
-Use these only when `chat` is unavailable or you need raw model access without project/conversation context.
-
-### `edit` — One-shot image editing
-
-```bash
-# Edit an existing image
-npx makaron-cli edit --image photo.jpg "add cinematic warm lighting"
-
-# Text-to-image (no input)
-npx makaron-cli edit "a cyberpunk cityscape at night"
-
-# With model/skill/reference
-npx makaron-cli edit --image photo.jpg --model openai --skill captions "add title"
-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"
-```
-
-Options: `--image`, `--model gemini|qwen|openai|pony|wai`, `--skill enhance|creative|wild|captions`, `--ref <file>` (up to 3), `--aspect <ratio>`, `--out <path>`
-
-### `video` — Standalone video tools (no project timeline)
-
-```bash
-# 1. Write script from images
-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)
-npx makaron-cli video create --script "Shot 1 (5s): <<<image_1>>> ..." --image https://...jpg --duration 5 --model kling
-
-# 3b. Edit a video from a local file or public URL
-npx makaron-cli video create --script "make it funny" --video input.mp4 --duration 5 --model seedance
-npx makaron-cli video create --script "make it warmer and cinematic" --video https://example.com/input.mp4 --duration 5 --model seedance
-
-# 4. Check status
-npx makaron-cli video status <taskId>
-```
-
-`video create` returns a provider task id and does not create or update a Makaron project timeline. For project/timeline video editing, use:
-
-```bash
-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 7), `--video <file|url>`, `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--model kling|seedance`. SeeDance accepts integer output duration 4-15s (default 5s); Kling supports 5-10s.
-
-Video edit model behavior: `--model kling --video` uses Kling base/direct edit internally; `--model seedance --video` uses the Seedance video-reference path and requires target <=15s, <=1080p input. Tiny metadata padding up to 15.5s is accepted and output duration is clamped to 15s.
-
-### `music` — Music generation
-
-```bash
-npx makaron-cli music create "gentle piano, warm strings, cinematic"
-npx makaron-cli music create --vocals --style "lo-fi" "rainy day vibes"
-npx makaron-cli music status <taskId>
-```
-
-Options: `--vocals` (include vocals), `--style "genre"`
-
-## Response Schema
-
-```typescript
-type MakaronRunResponse = {
-  id: string
-  status: "in_progress" | "completed" | "failed" | "aborted"
-  incomplete: boolean                // true = keep polling
-  project_id: string
-  project_url: string
-  next_poll_after_ms?: number        // suggested poll interval
-  output: MakaronOutput[]
-}
-
-type MakaronOutput =
-  | { id: string; type: "text"; status: "completed"; content: string }
-  | { id: string; type: "image"; status: "completed"; url: string; snapshot_id: string }
-  | { id: string; type: "design"; status: "completed"; url: string; width: number; height: number; animated: boolean; duration?: number }
-  | { id: string; type: "video"; status: "queued"|"rendering"|"completed"|"failed"; task_id: string; snapshot_id?: string; url?: string; elapsed_seconds?: number; width?: number; height?: number }
-  | { id: string; type: "music"; status: "queued"|"rendering"|"completed"|"failed"; task_id: string; url?: string; elapsed_seconds?: number }
-```
-
-## Polling Rules
-
-1. Poll while `incomplete: true` or `status` is `"in_progress"`
-2. Use `next_poll_after_ms` as interval (default 5000ms)
-3. Stop when `status` is `"completed"`, `"failed"`, or `"aborted"`
-4. Top-level `status: "completed"` means ALL artifacts are ready (including rendered videos)
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success (completed) or valid in-progress response |
-| 1 | Failed, aborted, or HTTP error |
-| 2 | Timeout (partial response still printed to stdout) |
-
-## What Makaron Agent Can Do
-
-| Task | Example prompt |
-|------|---------------|
-| Edit photo | "make it cinematic with warm tones" |
-| Style transfer | "convert to oil painting style" |
-| Add/remove elements | "add a cat on the table" / "remove background person" |
-| Text-to-image | "generate a cyberpunk cityscape" |
-| Video from image | "create a 5 second video of her walking" |
-| Video with model | "use seedance model, make a 5s video" |
-| Background music | "add calm piano music" |
-| Motion design | "create an Instagram story with animated text" |
-| Multi-step | "edit the photo then make a video from it" |
-
-## Recommended Pattern: Service Flow (Feishu/OpenClaw/Group Chat)
-
-When serving end-users in a chat environment (Feishu, Slack, Discord), use this proactive message pattern:
-
-```bash
-# 1. Immediately acknowledge the user
-send_message "Got it! Working on it now..."
-
-# 2. Create project + submit (one command)
-RUN_ID=$(npx makaron-cli chat --project auto --image photo.jpg -b "make it cinematic and create a 5s video")
-
-# 3. Send project link proactively
-PROJECT_URL=$(npx makaron-cli responses get $RUN_ID --pick project_url)
-send_message "Project created: $PROJECT_URL"
-
-# 4. Wait for the final customer-ready result
-RESULT=$(npx makaron-cli responses get $RUN_ID --wait --json)
-IMAGE_URLS=$(echo "$RESULT" | jq -r '[.result.images[]?.imageUrl, .output[]? | select(.type == "image") | .url] | map(select(. != null)) | unique | .[]')
-VIDEO_URLS=$(echo "$RESULT" | jq -r '[.result.videos[]?.videoUrl, .output[]? | select(.type == "video") | .url] | map(select(. != null)) | unique | .[]')
-
-for URL in $IMAGE_URLS; do
-  send_image "$URL"
-done
-for URL in $VIDEO_URLS; do
-  send_video "$URL"
-done
-send_message "All done!"
-```
-
-**Key principles for service agents:**
-- **Proactive, not silent**: Acknowledge immediately, send the project link early, then send the final customer-ready media when the run completes.
-- **Media over links**: When possible, send images/videos as native media in the chat (download URL and upload as attachment), not just paste the URL.
-- **Immediate acknowledgment**: Reply within 1 second of receiving user request. Don't make users wait for project creation.
-- **Project link early**: Send the project URL right after creation so users can check anytime.
-- **Use `get --wait --json` as the default service path**: reserve `watch --jsonl` for advanced streaming or debugging integrations that explicitly need incremental events.
-
-## Important Notes
-
-- One project = one conversation thread. All history is preserved.
-- One run at a time per project. New message interrupts previous run.
-- Multi-image: `create --image a.jpg --image b.jpg` or `chat --image ref.jpg`.
-- Videos take 2-5 minutes to render. Use `responses get <runId> --wait --json` for the default customer-service path.
-- 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.
-- Always use `chat` as the primary interface — even for single image edits.
-- `edit`/`video`/`music` are fallback tools for when `chat` is unavailable or you need raw model access without project context.