makaron-cli 0.5.2 → 0.5.4

package/README.md

@@ -1,5 +1,7 @@
 # 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
@@ -7,12 +9,23 @@ Makaron is a multimodal AI creative agent. You talk to it via `makaron chat`, an
 ```bash
 npm install -g makaron-cli
 # or use directly: npx makaron-cli
+```
+
+### Get your API key
+
+1. Go to [makaron.app](https://makaron.app) and log in
+2. Open the menu (top-right)
+3. Click **Get API Key**
+4. Copy your `mk_live_...` key
 
+```bash
 export MAKARON_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
 Verify: `npx makaron-cli list` should show projects.
 
+> **Agent Self-Registration**: Coming soon — agents will be able to register and obtain API keys programmatically without human login.
+
 ## Core Workflow
 
 ```bash
@@ -181,11 +194,52 @@ type MakaronOutput =
 | 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秒视频" |
+| 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.

package/SKILL.md

@@ -5,16 +5,27 @@ description: Use Makaron CLI to generate AI images, videos, music, and motion de
 
 # 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
+
+1. Go to [makaron.app](https://makaron.app) and log in
+2. Open the menu (top-right)
+3. Click **Get API Key**
+4. Copy your `mk_live_...` key
+
 ```bash
 export MAKARON_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
 Verify: `npx makaron-cli list` should show projects.
 
+> **Agent Self-Registration**: Coming soon — agents will be able to register and obtain API keys programmatically without human login.
+
 ## Core Workflow
 
 ```bash
@@ -183,11 +194,52 @@ type MakaronOutput =
 | 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秒视频" |
+| 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.

package/package.json

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