makaron-cli 0.8.4 → 0.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.8.4",
+  "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.8.4",
+  "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)
 
@@ -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';
@@ -49,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$/, '');
@@ -153,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) {
@@ -399,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`);
@@ -426,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;
@@ -995,6 +1158,8 @@ function printHelp(topic, subtopic) {
 const args = process.argv.slice(2);
 const command = args[0];
 
+await maybeNotifyUpdate(command, args);
+
 if (!command || command === '--help' || command === '-h' || command === 'help') {
   printRootHelp();
 } else if (hasHelpFlag(args)) {
@@ -1019,7 +1184,10 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   }
   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 = [];
@@ -1027,12 +1195,14 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   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] === '--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;
@@ -1042,9 +1212,11 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   }
   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://'));
@@ -1122,7 +1294,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   }
 
   // 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];
@@ -1166,7 +1338,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
 
     // 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) {
@@ -1311,7 +1483,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
   "scripts": {
@@ -16,7 +16,6 @@
     "skills/",
     ".codex-plugin/",
     ".claude-plugin/",
-    "SKILL.md",
     "README.md"
   ],
   "keywords": [

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)
 
@@ -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-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
-
-```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.