makaron-cli 0.4.0 → 0.5.0

package/README.md

@@ -1,287 +1,198 @@
-# makaron-cli
+# Makaron CLI — Agent Integration Skill
 
-Talk to **Makaron Agent** from the terminal — create projects, edit images, generate videos, and compose music.
+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.
 
-Zero dependencies. Single file. Works with `npx`.
-
-## Install
+## Setup
 
 ```bash
-npx makaron-cli          # run directly (always latest)
-# or
 npm install -g makaron-cli
-```
-
-## Authentication
-
-### API Key (recommended for agents)
+# or use directly: npx makaron-cli
 
-Set the `MAKARON_API_KEY` environment variable. That's it — no login step needed.
-
-```bash
 export MAKARON_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-npx makaron-cli list
 ```
 
-Get your API key from the Makaron dashboard (Settings → API Keys), or ask your admin to generate one.
+Verify: `npx makaron-cli list` should show projects.
 
-### Interactive login (humans)
+## Core Workflow
 
 ```bash
-npx makaron-cli login
-# Enter email + password → token saved to ~/.makaron/auth.json
-```
+# 1. Create project with image(s)
+PROJECT_ID=$(npx makaron-cli create --image photo.jpg 2>/dev/null | grep "ID:" | awk '{print $2}')
 
-The CLI checks `MAKARON_API_KEY` first, then falls back to the saved session in `~/.makaron/auth.json`.
+# Multi-image project:
+PROJECT_ID=$(npx makaron-cli create --image img1.jpg --image img2.jpg 2>/dev/null | grep "ID:" | awk '{print $2}')
 
-## Commands
+# 2. Submit creative request (non-blocking)
+RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID -b "make it cinematic and create a 5s video")
 
-### `chat` — Send a message to Makaron Agent
-
-This is the main command. The Agent can edit images, generate videos, compose music, and create designs.
-
-**Default mode (non-blocking poll):**
-
-```bash
-npx makaron-cli chat --project <id> "make it look cinematic"
+# 3. Watch until all artifacts are ready
+npx makaron-cli responses watch $RUN_ID --jsonl
 ```
 
-The CLI submits the request and polls every 3s for results. No long-lived connection — you can Ctrl+C and come back later with `responses get`.
+## Primary: `chat` (Agent-driven creative work)
 
-**Background mode — submit and exit immediately:**
+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
-npx makaron-cli chat --project <id> --background "make a 5s video"
-# → prints runId and exits in <1s
+npx makaron-cli chat --project <id> --json -b "<prompt>"
+```
 
-# Later, check the result:
-npx makaron-cli responses get <runId> --wait
+Returns immediately:
+```json
+{"runId": "xxx", "projectId": "...", "projectUrl": "https://www.makaron.app/projects/...", "status": "running"}
 ```
 
-**Structured JSON output (for programmatic use):**
+### With additional images
 
 ```bash
-npx makaron-cli chat --project <id> --json --background "edit the photo"
-# → {"runId":"...","projectId":"...","projectUrl":"...","status":"running"}
+# Add reference images to project before chatting
+npx makaron-cli chat --project <id> --image ref1.jpg --image ref2.jpg -b "use these as style reference"
 ```
 
-**Legacy streaming mode (real-time SSE):**
+### Check status (single query)
 
 ```bash
-npx makaron-cli chat --project <id> --stream "hello"
+npx makaron-cli responses get <runId> --json
 ```
 
-**Options:**
-- `--project <id>` — target project (required)
-- `--image <file>` — upload image to project before chatting
-- `--background` / `-b` — submit and exit, print runId
-- `--json` — structured JSON output
-- `--stream` — legacy real-time SSE mode
-- `--video-model kling|seedance` — preferred video model
-- `--model <name>` — preferred image model
-
-### `responses` — Query run status and results
+### Watch until done (streaming events)
 
 ```bash
-# Get current status (single query)
-npx makaron-cli responses get <runId>
-
-# Poll until completed
-npx makaron-cli responses get <runId> --wait
-
-# Wait for video/music rendering too (not just Agent completion)
-npx makaron-cli responses get <runId> --wait --wait-artifacts
-
-# List runs for a project
-npx makaron-cli responses list --project <id>
+npx makaron-cli responses watch <runId> --jsonl
 ```
 
-**Result JSON structure:**
-
-```json
-{
-  "runId": "...",
-  "projectId": "...",
-  "status": "completed",
-  "eventCount": 31,
-  "result": {
-    "text": "Agent's text response...",
-    "images": [{ "snapshotId": "...", "imageUrl": "https://..." }],
-    "designs": [{
-      "snapshotId": "...",
-      "imageUrl": "https://...",
-      "width": 1080,
-      "height": 1920,
-      "animation": { "fps": 30, "durationInSeconds": 3 },
-      "props": { "title": "..." },
-      "code": "function Design(props) { ... }"
-    }],
-    "videos": [{ "taskId": "...", "status": "completed", "videoUrl": "https://..." }],
-    "music": [{ "taskId": "...", "status": "completed", "audioUrl": "https://..." }]
-  }
-}
+Outputs one JSON per line as artifacts appear:
 ```
-
-### `list` — Show all projects
-
-```bash
-npx makaron-cli list
+{"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"}
 ```
 
-### `create` — Create a new project
+### Extract specific results
 
 ```bash
-# From local image file(s)
-npx makaron-cli create --image photo.jpg
-npx makaron-cli create --image img1.jpg --image img2.jpg
-
-# From URL(s)
-npx makaron-cli create --image-url https://example.com/photo.jpg
-
-# Empty project (for text-to-image)
-npx makaron-cli create --title "My New Project"
+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
 ```
 
-### `abort` — Stop a running Agent
+## Fallback: Direct tool calls (no project context)
 
-```bash
-npx makaron-cli abort <runId>
-```
-
-### `edit` — AI image editing (direct MCP tool call)
+Use these only when `chat` is unavailable or you need raw model access without project/conversation context.
 
-Unlike `chat` (which uses the Agent with project context), `edit` directly calls the image generation model for one-shot results.
+### `edit` — One-shot image editing
 
 ```bash
-# Text-to-image (no input image)
-npx makaron-cli edit "a cyberpunk cityscape at night, neon reflections"
-
 # Edit an existing image
 npx makaron-cli edit --image photo.jpg "add cinematic warm lighting"
 
-# With model and skill
-npx makaron-cli edit --image photo.jpg --model openai --skill captions "add elegant title"
+# Text-to-image (no input)
+npx makaron-cli edit "a cyberpunk cityscape at night"
 
-# With reference images (up to 3)
-npx makaron-cli edit --image photo.jpg --ref style1.jpg --ref style2.jpg "match this style"
+# 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"
 
-# Specify output path and aspect ratio
-npx makaron-cli edit --out result.jpg --aspect 9:16 "vertical poster design"
+# Output to file
+npx makaron-cli edit --image photo.jpg --out result.jpg "make it dramatic"
 ```
 
-Options:
-- `--image <file|url>` — input image (omit for text-to-image)
-- `--model gemini|qwen|openai|pony|wai` — model selection (default: auto)
-- `--skill enhance|creative|wild|captions` — activate skill template
-- `--ref <file|url>` — reference image (repeatable, up to 3)
-- `--aspect <ratio>` — target aspect ratio (e.g. `4:5`, `1:1`, `16:9`)
-- `--out <path>` — output file path (default: `makaron-output-{timestamp}.jpg`)
+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
+### `video` — Video generation (3 steps)
 
 ```bash
-# Write a video script from images
-npx makaron-cli video script --image img1.jpg --image img2.jpg "cinematic story"
+# 1. Write script from images
+npx makaron-cli video script --image img1.jpg "cinematic story"
 
-# Submit video rendering (images must be public URLs)
-npx makaron-cli video create --script "Shot 1..." --image https://...img1.jpg --duration 10
+# 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
 
-# Check status
+# 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
-# Generate instrumental music
 npx makaron-cli music create "gentle piano, warm strings, cinematic"
-
-# With vocals and style
-npx makaron-cli music create --vocals --style "lo-fi, ambient" "rainy day vibes"
-
-# Check status
+npx makaron-cli music create --vocals --style "lo-fi" "rainy day vibes"
 npx makaron-cli music status <taskId>
 ```
 
-## Agent Integration Guide
-
-For AI agents (Claude Code, OpenClaw, etc.) calling this CLI programmatically:
-
-### Non-blocking workflow (recommended)
-
-```bash
-# 1. Submit task — returns immediately
-RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID --background "make a 5s video")
-
-# 2. Do other work while Makaron processes...
-
-# 3. Poll for result when ready
-npx makaron-cli responses get $RUN_ID --wait
-```
+Options: `--vocals` (include vocals), `--style "genre"`
 
-### JSON mode for structured parsing
+## Response Schema
 
-```bash
-# Submit
-RESULT=$(npx makaron-cli chat --project $ID --json --background "edit the photo")
-RUN_ID=$(echo $RESULT | jq -r .runId)
+```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[]
+}
 
-# Poll
-npx makaron-cli responses get $RUN_ID --wait
+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 }
 ```
 
-### Sequential multi-turn
+## Polling Rules
 
-```bash
-# Turn 1: edit image
-npx makaron-cli chat --project $ID "make it cinematic"
-# Wait for completion (default mode polls automatically)
+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)
 
-# Turn 2: make video from the edited image
-npx makaron-cli chat --project $ID "now make a 5s video from this"
-```
+## Exit Codes
 
-Note: One project runs one Agent at a time. A new message while the previous is still running will interrupt the first.
+| 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 the Agent can do
+## What Makaron Agent Can Do
 
-| Capability | Example prompt |
-|-----------|---------------|
-| Image editing | "make the sky more dramatic" |
+| Task | Example prompt |
+|------|---------------|
+| Edit photo | "make it cinematic with warm tones" |
 | Style transfer | "convert to oil painting style" |
-| Add elements | "add a cat sitting on the table" |
-| Remove elements | "remove the person in the background" |
-| Text-to-image | "generate a cyberpunk cityscape" (on empty project) |
-| Video from image | "create a 5 second video" |
-| Video with script | "make a video: camera slowly zooms in while leaves fall" |
+| 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 | "用seedance模型做5秒视频" |
 | Background music | "add calm piano music" |
-| Design/motion graphics | "create an Instagram story with animated text" |
-
-### Output types in result
-
-| Type | Field | Contains |
-|------|-------|----------|
-| Text | `result.text` | Agent's conversational response |
-| Image | `result.images[].imageUrl` | Generated/edited image URL |
-| Design (still) | `result.designs[].imageUrl` | Poster screenshot + code |
-| Design (animated) | `result.designs[].animation` | fps + duration + code |
-| Video | `result.videos[].videoUrl` | MP4 URL (after rendering) |
-| Music | `result.music[].audioUrl` | MP3 URL (after generating) |
-
-### Environment variables
-
-| Variable | Purpose | Default |
-|----------|---------|---------|
-| `MAKARON_API_KEY` | API key (`mk_live_xxx`) | — |
-| `MAKARON_URL` | API endpoint override | `https://www.makaron.app` |
-
-## Viewing results
-
-All generated content (images, videos, designs) is saved to the project and visible at:
-
-```
-https://www.makaron.app/projects/<project-id>
-```
+| Motion design | "create an Instagram story with animated text" |
+| Multi-step | "edit the photo then make a video from it" |
+
+## 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.
 
 ## Admin: Skill Marketplace Operations
 

package/SKILL.md

@@ -0,0 +1,197 @@
+---
+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 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
+
+```bash
+export MAKARON_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+Verify: `npx makaron-cli list` should show projects.
+
+## Core Workflow
+
+```bash
+# 1. Create project with image(s)
+PROJECT_ID=$(npx makaron-cli create --image photo.jpg 2>/dev/null | grep "ID:" | awk '{print $2}')
+
+# Multi-image project:
+PROJECT_ID=$(npx makaron-cli create --image img1.jpg --image img2.jpg 2>/dev/null | grep "ID:" | awk '{print $2}')
+
+# 2. Submit creative request (non-blocking)
+RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID -b "make it cinematic and create a 5s video")
+
+# 3. Watch until all artifacts are ready
+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
+npx makaron-cli chat --project <id> --json -b "<prompt>"
+```
+
+Returns immediately:
+```json
+{"runId": "xxx", "projectId": "...", "projectUrl": "https://www.makaron.app/projects/...", "status": "running"}
+```
+
+### With additional images
+
+```bash
+# Add reference images to project before chatting
+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 | "用seedance模型做5秒视频" |
+| 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" |
+
+## 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.

package/bin/makaron.mjs

@@ -360,6 +360,79 @@ async function pollRun(baseUrl, headers, runId, opts = {}) {
   }
 }
 
+// ─── Pick Helper ────────────────────────────────────────────────────────────
+
+function applyPick(data, field) {
+  switch (field) {
+    case 'first_image_url': return data.output?.find(o => o.type === 'image')?.url || null;
+    case 'image_urls': return (data.output || []).filter(o => o.type === 'image' && o.url).map(o => o.url);
+    case 'first_video_url': return data.output?.find(o => o.type === 'video' && o.url)?.url || null;
+    case 'video_urls': return (data.output || []).filter(o => o.type === 'video' && o.url).map(o => o.url);
+    case 'first_design_url': return data.output?.find(o => o.type === 'design')?.url || null;
+    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 'project_url': return data.project_url || null;
+    case 'output': return data.output || [];
+    case 'text': return data.output?.find(o => o.type === 'text')?.content || null;
+    case 'status': return data.status;
+    default: return data[field] !== undefined ? data[field] : null;
+  }
+}
+
+// ─── Watch (incremental event stream) ───────────────────────────────────────
+
+async function watchRun(baseUrl, headers, runId, opts = {}) {
+  const { interval = 5000, jsonl = true } = opts;
+  let lastOutput = [];
+  const start = Date.now();
+
+  while (true) {
+    const elapsed = Math.round((Date.now() - start) / 1000);
+    let data;
+    try {
+      const res = await fetch(`${baseUrl}/api/agent/run/${runId}`, { headers });
+      if (!res.ok) {
+        if (elapsed > 800) { process.stderr.write(`Timeout after ${elapsed}s\n`); process.exit(2); }
+        await new Promise(r => setTimeout(r, interval));
+        continue;
+      }
+      data = await res.json();
+    } catch {
+      await new Promise(r => setTimeout(r, interval));
+      continue;
+    }
+
+    const currentOutput = data.output || [];
+
+    // Diff: find new or updated items
+    for (const item of currentOutput) {
+      const prev = lastOutput.find(o => o.id === item.id);
+      if (!prev) {
+        // New item
+        if (jsonl) console.log(JSON.stringify({ event: 'output.added', item }));
+        else process.stderr.write(`+ [${item.type}] ${item.url || item.content?.slice(0, 60) || item.status}\n`);
+      } else if (JSON.stringify(prev) !== JSON.stringify(item)) {
+        // Updated item (e.g. video status changed)
+        if (jsonl) console.log(JSON.stringify({ event: 'output.updated', item }));
+        else process.stderr.write(`~ [${item.type}] ${item.status} ${item.url || ''}\n`);
+      }
+    }
+
+    lastOutput = currentOutput;
+
+    // Check terminal status
+    if (!data.incomplete && (data.status === 'completed' || data.status === 'failed' || data.status === 'aborted')) {
+      if (jsonl) console.log(JSON.stringify({ event: 'done', status: data.status }));
+      if (data.status === 'failed' || data.status === 'aborted') process.exit(1);
+      process.exit(0);
+    }
+
+    const waitMs = data.next_poll_after_ms || interval;
+    await new Promise(r => setTimeout(r, waitMs));
+  }
+}
+
 // ─── Async Task Polling ──────────────────────────────────────────────────────
 
 async function pollVideo(baseUrl, headers, taskId) {
@@ -605,34 +678,47 @@ if (command === 'login') {
 
   if (sub === 'get') {
     const runId = args[2];
-    if (!runId) { console.error('Usage: makaron responses get <runId> [--wait] [--json]'); process.exit(1); }
-    let wait = false, jsonOutput = false, waitForArtifacts = false;
+    if (!runId) { console.error('Usage: makaron responses get <runId> [--wait] [--json] [--pick <field>]'); process.exit(1); }
+    let wait = false, jsonOutput = false, pick = null;
     for (let i = 3; i < args.length; i++) {
       if (args[i] === '--wait') wait = true;
       if (args[i] === '--json') jsonOutput = true;
-      if (args[i] === '--wait-artifacts') waitForArtifacts = true;
+      if (args[i] === '--pick' && args[i + 1]) pick = args[++i];
     }
 
     if (wait) {
-      await pollRun(baseUrl, headers, runId, { json: jsonOutput, waitForArtifacts });
+      await pollRun(baseUrl, headers, runId, { json: true });
     } else {
-      const params = new URLSearchParams();
-      if (waitForArtifacts) params.set('wait_for_artifacts', 'true');
-      const res = await fetch(`${baseUrl}/api/agent/run/${runId}?${params}`, { headers });
-      if (!res.ok) { console.error(`Error ${res.status}:`, await res.text()); process.exit(1); }
+      const res = await fetch(`${baseUrl}/api/agent/run/${runId}`, { headers });
+      if (!res.ok) { process.stderr.write(`Error ${res.status}: ${await res.text()}\n`); process.exit(1); }
       const data = await res.json();
-      console.log(JSON.stringify(data, null, 2));
+      if (pick) {
+        const picked = applyPick(data, pick);
+        if (picked !== undefined) console.log(typeof picked === 'string' ? picked : JSON.stringify(picked));
+      } else {
+        console.log(JSON.stringify(data, null, 2));
+      }
+      if (data.status === 'failed' || data.status === 'aborted') process.exit(1);
     }
 
+  } else if (sub === 'watch') {
+    const runId = args[2];
+    if (!runId) { console.error('Usage: makaron responses watch <runId> [--jsonl] [--interval <ms>]'); process.exit(1); }
+    let interval = 5000, jsonl = false;
+    for (let i = 3; i < args.length; i++) {
+      if (args[i] === '--jsonl') jsonl = true;
+      if (args[i] === '--interval' && args[i + 1]) interval = parseInt(args[++i]);
+    }
+    await watchRun(baseUrl, headers, runId, { interval, jsonl });
+
   } else if (sub === 'list') {
     let projectId = null;
     for (let i = 2; i < args.length; i++) {
       if (args[i] === '--project' && args[i + 1]) projectId = args[++i];
     }
     if (!projectId) { console.error('Usage: makaron responses list --project <id>'); process.exit(1); }
-    // Query runs for project
     const res = await fetch(`${baseUrl}/api/agent/run?projectId=${projectId}`, { headers });
-    if (!res.ok) { console.error(`Error ${res.status}:`, await res.text()); process.exit(1); }
+    if (!res.ok) { process.stderr.write(`Error ${res.status}: ${await res.text()}\n`); process.exit(1); }
     const data = await res.json();
     if (data.runs?.length) {
       for (const r of data.runs) {
@@ -645,9 +731,10 @@ if (command === 'login') {
 
   } else {
     console.log(`Responses commands:
-  responses get <runId>                  Get run status and results
+  responses get <runId>                  Get status and output (JSON)
   responses get <runId> --wait           Poll until completed
-  responses get <runId> --wait-artifacts Wait for video/music too
+  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
 `);
   }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "makaron-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
   "bin": {
     "makaron": "./bin/makaron.mjs"
   },
   "files": [
-    "bin/"
+    "bin/",
+    "SKILL.md",
+    "README.md"
   ],
   "keywords": [
     "makaron",