makaron-cli 0.6.2 → 0.7.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "makaron-cli",
+  "version": "0.6.2",
+  "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",
+    "url": "https://www.makaron.app"
+  },
+  "homepage": "https://www.makaron.app/agent",
+  "repository": "https://github.com/vegekyd/ai-image-editor",
+  "skills": "./skills/"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "makaron-cli",
+  "version": "0.6.2",
+  "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",
+  "longDescription": "makaron.app is for humans. makaron-cli is for AI agents. Talk to Makaron Agent from the terminal — create projects, edit images, generate videos, and compose music. Zero dependencies, single file, works with npx. Agents can self-register to get an API key without human intervention.",
+  "author": {
+    "name": "Makaron AI",
+    "url": "https://www.makaron.app"
+  },
+  "homepage": "https://www.makaron.app/agent",
+  "repository": "https://github.com/vegekyd/ai-image-editor",
+  "license": "MIT",
+  "keywords": ["ai", "image-editing", "video", "music", "agent", "creative"],
+  "category": "Creative Tools",
+  "capabilities": ["image-editing", "video-generation", "music-creation", "text-to-image"],
+  "skills": "./skills/",
+  "websiteURL": "https://www.makaron.app",
+  "brandColor": "#d946ef"
+}

package/SKILL.md

@@ -86,6 +86,21 @@ Returns immediately:
 npx makaron-cli chat --project <id> --image ref1.jpg --image ref2.jpg -b "use these as style reference"
 ```
 
+### With video input
+
+```bash
+# Upload a video file — Agent can analyze, edit, or use it as reference
+npx makaron-cli chat --project <id> --video clip.mp4 -b "edit this video to be more cinematic"
+
+# Video URL (public, downloadable)
+npx makaron-cli chat --project auto --video https://example.com/video.mp4 -b "make a 10s highlight reel"
+
+# Mix images + video
+npx makaron-cli chat --project auto --image photo.jpg --video clip.mp4 -b "combine the photo style with this video"
+```
+
+Supported formats: MP4, MOV, WebM (max 200MB). Videos are uploaded to the project timeline and available to the Agent for analysis and editing.
+
 ### Check status (single query)
 
 ```bash
@@ -184,7 +199,7 @@ 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 }
   | { id: string; type: "music"; status: "queued"|"rendering"|"completed"|"failed"; task_id: string; url?: string; elapsed_seconds?: number }
 ```
 

package/bin/makaron.mjs

@@ -217,6 +217,11 @@ async function streamAgent(baseUrl, headers, projectId, prompt) {
           process.stderr.write(`\n🎬 Video submitted: ${event.taskId}\n`);
           break;
 
+        case 'video_snapshot':
+          results.animationTasks.push({ taskId: event.taskId, snapshotId: event.snapshotId });
+          process.stderr.write(`\n🎬 Video submitted: ${event.taskId} (snapshot: ${event.snapshotId})\n`);
+          break;
+
         case 'music_task':
           results.musicTasks.push({ taskId: event.taskId });
           process.stderr.write(`\n🎵 Music submitted: ${event.taskId}\n`);
@@ -325,6 +330,9 @@ async function pollRun(baseUrl, headers, runId, opts = {}) {
           case 'animation_task':
             process.stderr.write(`\n🎬 Video submitted: ${ev.data?.taskId}\n`);
             break;
+          case 'video_snapshot':
+            process.stderr.write(`\n🎬 Video submitted: ${ev.data?.taskId} (snapshot: ${ev.data?.snapshotId})\n`);
+            break;
           case 'music_task':
             process.stderr.write(`\n🎵 Music submitted: ${ev.data?.taskId}\n`);
             break;
@@ -444,18 +452,23 @@ async function watchRun(baseUrl, headers, runId, opts = {}) {
 
 // ─── Async Task Polling ──────────────────────────────────────────────────────
 
-async function pollVideo(baseUrl, headers, taskId) {
-  process.stderr.write(`🎬 Waiting for video ${taskId}...\n`);
+async function pollVideo(baseUrl, headers, taskId, snapshotId) {
+  const label = snapshotId ? (taskId ? `${taskId} (snapshot)` : snapshotId) : taskId;
+  process.stderr.write(`🎬 Waiting for video ${label}...\n`);
   const start = Date.now();
+  // v2: poll /api/video-snapshot/[snapshotId]; v1: poll /api/animate/[taskId]
+  const endpoint = snapshotId
+    ? `${baseUrl}/api/video-snapshot/${snapshotId}`
+    : `${baseUrl}/api/animate/${taskId}`;
   while (true) {
     await new Promise(r => setTimeout(r, 10_000));
     const elapsed = Math.round((Date.now() - start) / 1000);
     try {
-      const res = await fetch(`${baseUrl}/api/animate/${taskId}`, { headers });
+      const res = await fetch(endpoint, { headers });
       if (!res.ok) continue;
       const data = await res.json();
       if (data.videoUrl) { process.stderr.write(`\r🎬 Video done (${elapsed}s): ${data.videoUrl}\n`); return data.videoUrl; }
-      if (data.status === 'failed') { process.stderr.write(`\r🎬 Video failed (${elapsed}s)\n`); return null; }
+      if (data.status === 'failed' || data.status === 'abandoned') { process.stderr.write(`\r🎬 Video ${data.status} (${elapsed}s)\n`); return null; }
       process.stderr.write(`\r🎬 Video rendering... ${elapsed}s`);
     } catch { /* retry */ }
     if (elapsed > 600) { process.stderr.write(`\r🎬 Video timeout (${elapsed}s)\n`); return null; }
@@ -597,6 +610,43 @@ function readImageAsDataUrl(filePath) {
   return `data:${v.mime};base64,${buf.toString('base64')}`;
 }
 
+/**
+ * Upload a local file via signed URL (works for both images and videos).
+ * 1. POST /api/storage/upload-url → get signed URL + public URL
+ * 2. PUT file directly to Supabase Storage (no Vercel body limit)
+ * Returns public URL on success, null on failure.
+ */
+async function uploadFileViaSignedUrl(baseUrl, headers, projectId, filePath, contentType) {
+  const filename = path.basename(filePath);
+  // Step 1: get signed upload URL
+  const urlRes = await fetch(`${baseUrl}/api/storage/upload-url`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify({ projectId, filename, contentType }),
+  });
+  if (!urlRes.ok) {
+    process.stderr.write(`⚠️ Failed to get upload URL: ${await urlRes.text()}\n`);
+    return null;
+  }
+  const { uploadUrl, token, publicUrl } = await urlRes.json();
+
+  // Step 2: PUT file directly to Supabase Storage
+  const buf = fs.readFileSync(filePath);
+  const putRes = await fetch(uploadUrl, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': contentType,
+      'Authorization': `Bearer ${token}`,
+    },
+    body: buf,
+  });
+  if (!putRes.ok) {
+    process.stderr.write(`⚠️ Failed to upload file: ${await putRes.text()}\n`);
+    return null;
+  }
+  return publicUrl;
+}
+
 function imageToArg(imgPath) {
   if (imgPath.startsWith('http://') || imgPath.startsWith('https://')) return imgPath;
   return readImageAsDataUrl(imgPath);
@@ -643,6 +693,7 @@ if (command === 'login') {
   const { headers, baseUrl } = getAuth();
   let projectId = null;
   const chatImages = [];
+  const chatVideos = [];
   const promptParts = [];
   let useStream = false;
   let background = false;
@@ -651,11 +702,12 @@ if (command === 'login') {
   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>] [--stream] [--background|-b] [--json] "your message"');
+      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];
     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] === '--stream') useStream = true;
     else if (args[i] === '--background' || args[i] === '-b') background = true;
     else if (args[i] === '--json') jsonOutput = true;
@@ -665,13 +717,17 @@ if (command === 'login') {
   }
   const prompt = promptParts.join(' ');
   if (!prompt) {
-    console.error('Usage: makaron chat --project <id|auto> [--image <file>] [--stream] [--background|-b] [--json] "your message"');
+    console.error('Usage: makaron chat --project <id|auto> [--image <file>] [--video <file|url>] [--stream] [--background|-b] [--json] "your message"');
     process.exit(1);
   }
-  // --project auto: create a new project (with images if provided)
+  // 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://'));
+
+  // --project auto: create a new project (with images/videos if provided)
   if (!projectId || projectId === 'auto') {
     if (chatImages.length === 0) {
-      // Create empty project
+      // Create empty project (videos will be uploaded separately after)
       process.stderr.write(`📦 Creating new project...\n`);
       const res = await fetch(`${baseUrl}/api/projects/create`, {
         method: 'POST',
@@ -683,33 +739,43 @@ if (command === 'login') {
       projectId = data.projectId;
       process.stderr.write(`📦 Project created: ${projectId}\n`);
     } else {
-      // Create project with images
-      const base64s = chatImages.map(imgPath => {
+      // Create project with images (URLs and/or local files)
+      const base64s = imageFileList.map(imgPath => {
         process.stderr.write(`📤 Uploading ${path.basename(imgPath)}...\n`);
         return readImageAsDataUrl(imgPath);
       });
+      if (imageUrlList.length) process.stderr.write(`📤 Attaching ${imageUrlList.length} URL image(s)...\n`);
+      const body = {};
+      if (base64s.length) body.imageBase64s = base64s;
+      if (imageUrlList.length) body.imageUrls = imageUrlList;
       const res = await fetch(`${baseUrl}/api/projects/create`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', ...headers },
-        body: JSON.stringify({ imageBase64s: base64s }),
+        body: JSON.stringify(body),
       });
       if (!res.ok) { process.stderr.write(`❌ Failed to create project: ${await res.text()}\n`); process.exit(1); }
       const data = await res.json();
       projectId = data.projectId;
       process.stderr.write(`📦 Project created: ${projectId} (${data.snapshots?.length || 0} images)\n`);
     }
-    chatImages.length = 0; // already uploaded
+    chatImages.length = 0;
+    imageUrlList.length = 0;
+    imageFileList.length = 0;
   }
   // Upload additional images to existing project
-  if (chatImages.length > 0) {
-    const base64s = chatImages.map(imgPath => {
+  if (imageFileList.length > 0 || imageUrlList.length > 0) {
+    const base64s = imageFileList.map(imgPath => {
       process.stderr.write(`📤 Uploading ${path.basename(imgPath)}...\n`);
       return readImageAsDataUrl(imgPath);
     });
+    if (imageUrlList.length) process.stderr.write(`📤 Attaching ${imageUrlList.length} URL image(s)...\n`);
+    const body = { _addToProject: projectId };
+    if (base64s.length) body.imageBase64s = base64s;
+    if (imageUrlList.length) body.imageUrls = imageUrlList;
     const res = await fetch(`${baseUrl}/api/projects/create`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', ...headers },
-      body: JSON.stringify({ imageBase64s: base64s, _addToProject: projectId }),
+      body: JSON.stringify(body),
     });
     if (res.ok) {
       const data = await res.json();
@@ -719,18 +785,70 @@ if (command === 'login') {
     }
   }
 
+  // Upload videos to project timeline (via /api/projects/create with videoUrls)
+  let finalPrompt = prompt;
+  if (chatVideos.length > 0) {
+    const videoUrlList = chatVideos.filter(p => p.startsWith('http://') || p.startsWith('https://'));
+    const videoFileList = chatVideos.filter(p => !p.startsWith('http://') && !p.startsWith('https://'));
+
+    // Validate local video files
+    const validVideoFiles = [];
+    for (const videoPath of videoFileList) {
+      if (!fs.existsSync(videoPath)) { process.stderr.write(`⚠️ Video file not found: ${videoPath}\n`); continue; }
+      const stat = fs.statSync(videoPath);
+      if (stat.size > 200 * 1024 * 1024) { process.stderr.write(`⚠️ Video too large: ${(stat.size/1024/1024).toFixed(1)}MB (max 200MB)\n`); continue; }
+      const ext = path.extname(videoPath).slice(1).toLowerCase();
+      if (!['mp4', 'mov', 'webm'].includes(ext)) { process.stderr.write(`⚠️ Unsupported video format: .${ext}. Use MP4, MOV, or WebM.\n`); continue; }
+      validVideoFiles.push(videoPath);
+    }
+
+    // Upload local files via signed URL (no size limit, works with API key auth)
+    const uploadedVideoUrls = [...videoUrlList];
+    for (const videoPath of validVideoFiles) {
+      process.stderr.write(`📹 Uploading ${path.basename(videoPath)} (${(fs.statSync(videoPath).size/1024/1024).toFixed(1)}MB)...\n`);
+      const ext = path.extname(videoPath).slice(1).toLowerCase();
+      const mime = ext === 'mov' ? 'video/quicktime' : ext === 'webm' ? 'video/webm' : 'video/mp4';
+      const url = await uploadFileViaSignedUrl(baseUrl, headers, projectId, videoPath, mime);
+      if (url) {
+        uploadedVideoUrls.push(url);
+        process.stderr.write(`📹 Uploaded: ${path.basename(videoPath)}\n`);
+      }
+    }
+
+    // Add videos to project via projects/create (same as images)
+    if (uploadedVideoUrls.length > 0) {
+      if (videoUrlList.length) process.stderr.write(`📹 Adding ${uploadedVideoUrls.length} video(s) to timeline...\n`);
+      const res = await fetch(`${baseUrl}/api/projects/create`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...headers },
+        body: JSON.stringify({ _addToProject: projectId, videoUrls: uploadedVideoUrls }),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        const videoSnaps = (data.snapshots || []).filter(s => s.type === 'video');
+        process.stderr.write(`📹 Added ${videoSnaps.length} video(s) to timeline\n`);
+      } else {
+        process.stderr.write(`⚠️ Failed to add videos: ${await res.text()}\n`);
+      }
+    }
+
+    // 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}`;
+  }
+
   if (useStream) {
     // Legacy SSE mode
-    const { results } = await streamAgent(baseUrl, headers, projectId, prompt);
+    const { results } = await streamAgent(baseUrl, headers, projectId, finalPrompt);
     process.stderr.write('\n━━━ Results ━━━\n');
     for (const img of results.images) process.stderr.write(`🖼️  Image: ${img.imageUrl}\n`);
     for (const d of results.designs) process.stderr.write(`🎨  ${d.desc}\n`);
     process.stderr.write(`🔗  ${APP_URL}/projects/${projectId}\n`);
-    for (const task of results.animationTasks) await pollVideo(baseUrl, headers, task.taskId);
+    for (const task of results.animationTasks) await pollVideo(baseUrl, headers, task.taskId, task.snapshotId);
     for (const task of results.musicTasks) await pollMusic(baseUrl, headers, task.taskId);
   } else {
     // Default: fire-and-forget + poll
-    const { runId } = await submitRun(baseUrl, headers, projectId, prompt, { videoModel, preferredModel });
+    const { runId } = await submitRun(baseUrl, headers, projectId, finalPrompt, { videoModel, preferredModel });
     if (background) {
       // Just print runId and exit
       if (jsonOutput) {
@@ -873,7 +991,7 @@ if (command === 'login') {
 
   } else if (sub === 'create') {
     const images = [];
-    let script = '', duration = undefined, aspectRatio = undefined, videoModel = undefined;
+    let script = '', duration = undefined, aspectRatio = undefined, videoModel = undefined, projectId = null, wait = false;
     for (let i = 2; i < args.length; i++) {
       if (args[i] === '--image' && args[i + 1]) images.push(args[++i]);
       else if (args[i] === '--script' && args[i + 1]) script = args[++i];
@@ -881,29 +999,83 @@ if (command === 'login') {
       else if (args[i] === '--duration' && args[i + 1]) duration = Number(args[++i]);
       else if (args[i] === '--aspect' && args[i + 1]) aspectRatio = args[++i];
       else if (args[i] === '--model' && args[i + 1]) videoModel = args[++i];
+      else if (args[i] === '--project' && args[i + 1]) projectId = args[++i];
+      else if (args[i] === '--wait') wait = true;
+    }
+    if (!images.length || !script) { console.error('Usage: makaron video create --script "..." --image <url> [--project <id>] [--duration 10] [--aspect 9:16] [--model kling|seedance] [--wait]'); process.exit(1); }
+
+    if (projectId) {
+      // v2: submit to /api/video-snapshot → writes into timeline
+      process.stderr.write('🎬 Submitting video to timeline...\n');
+      const body = { projectId, imageUrls: images, prompt: script };
+      if (duration) body.duration = duration;
+      if (aspectRatio) body.aspectRatio = aspectRatio;
+      if (videoModel) body.videoModel = videoModel;
+      const res = await fetch(`${baseUrl}/api/video-snapshot`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) { console.error(`Error ${res.status}:`, await res.text()); process.exit(1); }
+      const data = await res.json();
+      process.stderr.write(`✅ Video snapshot: ${data.snapshotId} (task: ${data.taskId})\n`);
+      if (wait) {
+        const url = await pollVideo(baseUrl, headers, data.taskId, data.snapshotId);
+        if (url) console.log(url);
+      } else {
+        console.log(JSON.stringify(data, null, 2));
+      }
+    } else {
+      // No project: use MCP tool (standalone, no timeline write)
+      process.stderr.write('🎬 Submitting video...\n');
+      const vArgs = { script, images };
+      if (duration) vArgs.duration = duration;
+      if (aspectRatio) vArgs.aspectRatio = aspectRatio;
+      if (videoModel) vArgs.videoModel = videoModel;
+      const result = await callMcpTool(baseUrl, headers, 'makaron_create_video', vArgs);
+      const text = result?.content?.find(c => c.type === 'text')?.text;
+      if (text) console.log(text);
     }
-    if (!images.length || !script) { console.error('Usage: makaron video create --script "..." --image <url> [--duration 10] [--aspect 9:16] [--model kling|seedance]'); process.exit(1); }
-    process.stderr.write('🎬 Submitting video...\n');
-    const vArgs = { script, images };
-    if (duration) vArgs.duration = duration;
-    if (aspectRatio) vArgs.aspectRatio = aspectRatio;
-    if (videoModel) vArgs.videoModel = videoModel;
-    const result = await callMcpTool(baseUrl, headers, 'makaron_create_video', vArgs);
-    const text = result?.content?.find(c => c.type === 'text')?.text;
-    if (text) console.log(text);
 
   } else if (sub === 'status') {
-    const taskId = args[2];
-    if (!taskId) { console.error('Usage: makaron video status <taskId>'); process.exit(1); }
-    const result = await callMcpTool(baseUrl, headers, 'makaron_get_video_status', { taskId });
-    const text = result?.content?.find(c => c.type === 'text')?.text;
-    if (text) console.log(text);
+    let taskId = null, snapshotId = null, wait = false;
+    for (let i = 2; i < args.length; i++) {
+      if (args[i] === '--snapshot' && args[i + 1]) snapshotId = args[++i];
+      else if (args[i] === '--wait') wait = true;
+      else if (!taskId) taskId = args[i];
+    }
+    if (!taskId && !snapshotId) { console.error('Usage: makaron video status <taskId> | --snapshot <snapshotId> [--wait]'); process.exit(1); }
+
+    if (snapshotId || (taskId && taskId.length === 36 && taskId.includes('-'))) {
+      // v2: poll /api/video-snapshot/[snapshotId]
+      const id = snapshotId || taskId;
+      if (wait) {
+        const url = await pollVideo(baseUrl, headers, null, id);
+        if (url) console.log(url);
+      } else {
+        const res = await fetch(`${baseUrl}/api/video-snapshot/${id}`, { headers });
+        if (!res.ok) { console.error(`Error ${res.status}:`, await res.text()); process.exit(1); }
+        const data = await res.json();
+        console.log(JSON.stringify(data, null, 2));
+      }
+    } else {
+      // v1: MCP get_video_status
+      if (wait) {
+        const url = await pollVideo(baseUrl, headers, taskId);
+        if (url) console.log(url);
+      } else {
+        const result = await callMcpTool(baseUrl, headers, 'makaron_get_video_status', { taskId });
+        const text = result?.content?.find(c => c.type === 'text')?.text;
+        if (text) console.log(text);
+      }
+    }
 
   } 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 status <taskId>                                      Check video status
+  video status --snapshot <snapshotId> [--wait]              Check v2 video snapshot
 `);
   }
 
@@ -1158,6 +1330,7 @@ Commands:
   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
@@ -1168,7 +1341,7 @@ Commands:
   abort <runId>                      Abort a running Agent
 
   edit [--image <file>] "prompt"     AI image edit / text-to-image
-  video script|create|status         Video generation
+  video script|create|status         Video generation (v2 timeline support)
   music create|status                Music generation
 
   admin                              Admin commands (skills, upload, set-admin)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
   "bin": {
@@ -8,6 +8,9 @@
   },
   "files": [
     "bin/",
+    "skills/",
+    ".codex-plugin/",
+    ".claude-plugin/",
     "SKILL.md",
     "README.md"
   ],

package/skills/makaron/SKILL.md

@@ -0,0 +1,271 @@
+---
+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")
+
+# Watch until all artifacts are ready
+npx makaron-cli responses watch $RUN_ID --jsonl
+```
+
+Or with an existing project:
+```bash
+RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID -b "make a 5s video")
+npx makaron-cli responses watch $RUN_ID --jsonl
+```
+
+## 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"
+```
+
+### Check status (single query)
+
+```bash
+npx makaron-cli responses get <runId> --json
+```
+
+### Watch until done (streaming 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` — Video generation (3 steps)
+
+```bash
+# 1. Write script from images
+npx makaron-cli video script --image img1.jpg "cinematic story"
+
+# 2. Submit 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
+
+# 3. Check status
+npx makaron-cli video status <taskId>
+```
+
+Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to 7), `--duration 3|5|7|10|15`, `--aspect 9:16|16:9|1:1`, `--model kling|seedance`
+
+### `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; url?: string; elapsed_seconds?: 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. Watch and send each artifact as it appears
+npx makaron-cli responses watch $RUN_ID --jsonl | while read -r line; do
+  EVENT=$(echo "$line" | jq -r '.event')
+  TYPE=$(echo "$line" | jq -r '.item.type // empty')
+  URL=$(echo "$line" | jq -r '.item.url // empty')
+  STATUS=$(echo "$line" | jq -r '.item.status // empty')
+
+  if [ "$EVENT" = "output.added" ] && [ "$TYPE" = "image" ]; then
+    # Send image immediately as media (not just link)
+    send_image "$URL"
+  elif [ "$EVENT" = "output.updated" ] && [ "$TYPE" = "video" ] && [ "$STATUS" = "completed" ]; then
+    # Video ready — send as media
+    send_video "$URL"
+  elif [ "$EVENT" = "done" ]; then
+    send_message "All done!"
+  fi
+done
+```
+
+**Key principles for service agents:**
+- **Proactive, not reactive**: Don't wait for the full run to finish. Send progress messages and artifacts as they appear.
+- **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.
+- **Stream artifacts**: Use `watch --jsonl` to push each artifact the moment it's ready. An image at 15s should reach the user at 15s, not after the video finishes at 5 minutes.
+
+## 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 `watch` to get URL when ready.
+- 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.