diff --git a/skill/SKILL.md b/skill/SKILL.md
index 273a92e..a6c3ee8 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -1,221 +1,458 @@
 ---
-name: mmx-h3-video
-description: Generate, monitor, and download MiniMax-H3 videos through the mmx CLI. Use for H3 text-to-video, first/last-frame video, multimodal reference image/video/audio generation, H3 prompt improvement, media preflight, Pay-as-you-go API key selection, task waiting, downloads, and H3 failure handling.
+name: mmx-cli
+description: Use mmx to generate text, images, video, speech, and music via the MiniMax AI platform. Use when the user wants to create media content, chat with MiniMax models, perform web search, or manage MiniMax API resources from the terminal.
 ---
 
-# MiniMax-H3 Video With MMX
+# MiniMax CLI — Agent Skill Guide
 
-Use this skill only for `MiniMax-H3` video generation. Do not handle text, image generation, speech, music, search, legacy Hailuo models, or unrelated MMX commands.
+Use `mmx` to generate text, images, video, speech, music, and perform web search via the MiniMax AI platform.
 
-Before a paid request, read `references/h3-video.md` for prompt construction, media constraints, waiting behavior, and failure handling.
+## Prerequisites
 
-## Required Rules
+```bash
+# Install
+npm install -g mmx-cli
+
+# Auth (OAuth persists to ~/.mmx/credentials.json, API key persists to ~/.mmx/config.json)
+mmx auth login --api-key sk-xxxxx
+
+# Verify active auth source
+mmx auth status
+
+# Or pass per-call
+mmx text chat --api-key sk-xxxxx --message "Hello"
+```
+
+Region is auto-detected. Override with `--region global` or `--region cn`.
+
+---
+
+## Agent Flags
+
+Always use these flags in non-interactive (agent/CI) contexts:
+
+| Flag | Purpose |
+|---|---|
+| `--non-interactive` | Fail fast on missing args instead of prompting |
+| `--quiet` | Suppress spinners/progress; stdout is pure data |
+| `--output json` | Machine-readable JSON output |
+| `--async` | Return task ID immediately (video generation) |
+| `--dry-run` | Preview the API request without executing |
+| `--yes` | Skip confirmation prompts |
+
+---
 
-1. Use a Pay-as-you-go/Credit API Key. H3 does not use OAuth or Token Plan Subscription Keys.
-2. Reuse a saved MMX API key when available. Never print, repeat, or place a literal API key in a command transcript.
-3. Always pass `--model MiniMax-H3`; never rely on the configured default model.
-4. For a completed video, run one direct blocking `mmx video generate` command. Do not use Bash wrappers or hand-written polling loops.
-5. If the terminal command remains active, wait on that exact execution session. Do not run `ps`, scrape process arguments, inspect the output repeatedly, kill the process, or submit another task.
-6. Treat `Detecting region... cn` or `Detecting region... global` as normal stderr progress, not a submission failure.
-7. Never submit a replacement paid task because terminal waiting, status polling, or downloading was interrupted.
-8. Retry the alternate region at most once, and only when the first command clearly failed before task creation because of region detection, endpoint, or authentication routing.
-9. Use `--async` only when the user explicitly wants a task ID without waiting or downloading.
+## Commands
 
-## Resolve The CLI
+### text chat
 
-Inside the `minimax-cli` repository, build changes and use the local artifact:
+Chat completion. Default model: `MiniMax-M3`.
 
 ```bash
-bun run build
-node ./dist/mmx.mjs video generate --help
+mmx text chat --message <text> [flags]
 ```
 
-Outside the repository, use the installed `mmx` executable. Do not install or update MMX unless the user asks.
+| Flag | Type | Description |
+|---|---|---|
+| `--message <text>` | string, **required**, repeatable | Message text. Prefix with `role:` to set role (e.g. `"system:You are helpful"`, `"user:Hello"`) |
+| `--messages-file <path>` | string | JSON file with messages array. Use `-` for stdin |
+| `--system <text>` | string | System prompt |
+| `--model <model>` | string | Model ID (default: `MiniMax-M3`) |
+| `--max-tokens <n>` | number | Max tokens (default: 4096) |
+| `--temperature <n>` | number | Sampling temperature (0.0, 1.0] |
+| `--top-p <n>` | number | Nucleus sampling threshold |
+| `--stream` | boolean | Stream tokens (default: on in TTY) |
+| `--tool <json-or-path>` | string, repeatable | Tool definition JSON or file path |
 
-In commands below, replace `mmx` with `node ./dist/mmx.mjs` when testing the local repository build.
+```bash
+# Single message
+mmx text chat --message "user:What is MiniMax?" --output json --quiet
+
+# Multi-turn
+mmx text chat \
+  --system "You are a coding assistant." \
+  --message "user:Write fizzbuzz in Python" \
+  --output json
+
+# From file
+cat conversation.json | mmx text chat --messages-file - --output json
+```
+
+**stdout**: response text (text mode) or full response object (json mode).
+
+---
 
-## Resolve And Save The API Key
+### image generate
 
-Before the first paid H3 request, inspect the active credential without exposing it:
+Generate images. Model: `image-01`.
 
 ```bash
-mmx auth status --output json --quiet
+mmx image generate --prompt <text> [flags]
 ```
 
-- If `method` is `api-key`, reuse it from MMX config. Do not add `--api-key` to generation commands.
-- If the user already supplied a key and the runtime holds it securely as `MINIMAX_API_KEY`, save it once, then use MMX config:
+| Flag | Type | Description |
+|---|---|---|
+| `--prompt <text>` | string, **required** | Image description |
+| `--aspect-ratio <ratio>` | string | e.g. `16:9`, `1:1`. Ignored if `--width` and `--height` are both set |
+| `--n <count>` | number | Number of images (default: 1) |
+| `--seed <n>` | number | Random seed for reproducible generation |
+| `--width <px>` | number | Width in pixels (512–2048, multiple of 8). Requires `--height` |
+| `--height <px>` | number | Height in pixels (512–2048, multiple of 8). Requires `--width` |
+| `--prompt-optimizer` | boolean | Optimize prompt before generation |
+| `--aigc-watermark` | boolean | Embed AI-generated content watermark |
+| `--subject-ref <params>` | string | Subject reference: `type=character,image=path-or-url` |
+| `--response-format <format>` | string | `url` (default) or `base64`. Base64 bypasses CDN download |
+| `--out-dir <dir>` | string | Download images to directory |
+| `--out-prefix <prefix>` | string | Filename prefix (default: `image`) |
 
 ```bash
-mmx config set --key api_key --value "$MINIMAX_API_KEY" --quiet
+mmx image generate --prompt "A cat in a spacesuit" --output json --quiet
+# stdout: image URLs (one per line in quiet mode)
+
+mmx image generate --prompt "Logo" --n 3 --out-dir ./gen/ --quiet
+# stdout: saved file paths (one per line)
 ```
 
-- Saving `api_key` replaces stale OAuth credentials, clears the cached region, and stores the key in `~/.mmx/config.json` with owner-only permissions.
-- Never reconstruct a previously supplied key into visible shell text. Use the runtime's secret/environment injection when available.
-- If no saved API key or securely injected variable is available, ask the user to run `mmx auth login` and choose API key. Do not ask them to paste the key into chat again.
-- After saving, future Agent commands must omit both the literal key and `--api-key`.
+---
 
-## Default Completed-Video Path
+### video generate
 
-Use this path when the user wants the final file:
+Generate video. Default model: `MiniMax-Hailuo-2.3`. Select `MiniMax-H3` to use the Video Generation V2 multimodal API. This is an async task — by default it polls until completion.
 
 ```bash
-mmx video generate \
-  --model MiniMax-H3 \
-  --prompt "<video prompt>" \
-  --duration <4-15> \
-  --download <output.mp4> \
-  --poll-interval 10 \
-  --timeout 1800 \
-  --non-interactive
+mmx video generate --prompt <text> [flags]
 ```
 
-This one CLI process submits exactly one task, waits internally between status checks, and downloads the completed video. When the execution tool returns a running session or cell ID, continue waiting on that same session until it exits.
+| Flag | Type | Description |
+|---|---|---|
+| `--prompt <text>` | string, **required** | Video description |
+| `--model <model>` | string | `MiniMax-Hailuo-2.3` (default), `MiniMax-Hailuo-2.3-Fast`, or `MiniMax-H3` |
+| `--image <path-or-url>` | string | Input image for image-to-video |
+| `--last-frame <path-or-url>` | string | Last frame image; H3 supports last-frame-only input |
+| `--reference-image <path-or-url>` | string, repeatable | H3 reference image |
+| `--reference-video <path-or-url>` | string, repeatable | H3 reference video |
+| `--reference-audio <path-or-url>` | string, repeatable | H3 reference audio; requires a reference image or video |
+| `--duration <seconds>` | number | H3 duration, 4-15 seconds (default: 5) |
+| `--ratio <ratio>` | string | H3 output ratio; T2V cannot use `adaptive` |
+| `--callback-url <url>` | string | Webhook URL for completion |
+| `--download <path>` | string | Save video to specific file |
+| `--async` | boolean | Return task ID immediately |
+| `--no-wait` | boolean | Same as `--async` |
+| `--poll-interval <seconds>` | number | Polling interval (default: 5) |
 
-Do not add `--async` to this command. Async mode returns before download handling.
+```bash
+# Non-blocking: get task ID
+mmx video generate --prompt "A robot." --async --quiet
+# stdout: {"taskId":"..."}
+
+# H3 text-to-video
+mmx video generate --model MiniMax-H3 --prompt "Ocean waves." --async --quiet
 
-## Input Modes
+# H3 image-to-video
+mmx video generate --model MiniMax-H3 --prompt "The subject walks forward." \
+  --image start.jpg --async --quiet
 
-Use exactly one mode per request.
+# H3 reference-to-video
+mmx video generate --model MiniMax-H3 --prompt "Keep the same character." \
+  --reference-image character.png \
+  --reference-video motion.mp4 --async --quiet
 
-### Text-To-Video
+# Blocking: wait and get file path
+mmx video generate --prompt "Ocean waves." --download ocean.mp4 --quiet
+# stdout: ocean.mp4
+```
+
+### video task get
+
+Query status of a video generation task.
 
 ```bash
-mmx video generate \
-  --model MiniMax-H3 \
-  --prompt "A cinematic coastal sunset, slow dolly forward" \
-  --duration 15 \
-  --ratio 16:9 \
-  --download ./result.mp4 \
-  --poll-interval 10 \
-  --timeout 1800 \
-  --non-interactive
+mmx video task get --task-id <id> [--output json]
 ```
 
-### First/Last-Frame Video
+### video download
 
-`--image` is the first frame. It may be combined with one `--last-frame`.
+Download a completed video by task ID.
 
 ```bash
-mmx video generate \
-  --model MiniMax-H3 \
-  --prompt "The subject walks naturally from the starting pose to the ending pose" \
-  --image ./start.png \
-  --last-frame ./end.png \
-  --duration 15 \
-  --download ./result.mp4 \
-  --poll-interval 10 \
-  --timeout 1800 \
-  --non-interactive
+mmx video download --file-id <id> [--out <path>]
 ```
 
-Do not use the hidden `--first-frame` compatibility alias in new commands.
+---
+
+### speech synthesize
+
+Text-to-speech. Default model: `speech-2.8-hd`. Max 10k chars.
 
-### Multimodal Reference Video
+```bash
+mmx speech synthesize --text <text> [flags]
+```
 
-Repeat each reference flag to pass multiple inputs. Do not comma-separate paths.
+| Flag | Type | Description |
+|---|---|---|
+| `--text <text>` | string | Text to synthesize |
+| `--text-file <path>` | string | Read text from file. Use `-` for stdin |
+| `--model <model>` | string | `speech-2.8-hd` (default), `speech-2.6`, `speech-02` |
+| `--voice <id>` | string | Voice ID (default: `English_expressive_narrator`) |
+| `--speed <n>` | number | Speed multiplier |
+| `--volume <n>` | number | Volume level |
+| `--pitch <n>` | number | Pitch adjustment |
+| `--format <fmt>` | string | Audio format (default: `mp3`) |
+| `--sample-rate <hz>` | number | Sample rate (default: 32000) |
+| `--bitrate <bps>` | number | Bitrate (default: 128000) |
+| `--channels <n>` | number | Audio channels (default: 1) |
+| `--language <code>` | string | Language boost |
+| `--subtitles` | boolean | Download and save subtitles as `.srt` file (alongside `--out` audio file). API must support subtitles for the selected model.
+| `--pronunciation <from/to>` | string, repeatable | Custom pronunciation |
+| `--sound-effect <effect>` | string | Add sound effect |
+| `--out <path>` | string | Save audio to file |
+| `--stream` | boolean | Stream raw audio to stdout |
 
 ```bash
-mmx video generate \
-  --model MiniMax-H3 \
-  --prompt "Preserve the referenced character, follow the motion and audio rhythm" \
-  --reference-image ./character-1.png \
-  --reference-image ./character-2.png \
-  --reference-video ./motion.mp4 \
-  --reference-audio ./rhythm.mp3 \
-  --duration 15 \
-  --download ./result.mp4 \
-  --poll-interval 10 \
-  --timeout 1800 \
-  --non-interactive
+mmx speech synthesize --text "Hello world" --out hello.mp3 --quiet
+# stdout: hello.mp3
+
+mmx speech synthesize --text "Hello" --subtitles --out hello.mp3
+# saves hello.mp3 + hello.srt (SRT subtitle file)
+
+echo "Breaking news." | mmx speech synthesize --text-file - --out news.mp3
 ```
 
-Frame mode cannot be mixed with reference mode. Reference audio requires at least one reference image or reference video.
+---
+
+### music generate
 
-## Region Recovery
+Generate music. Responds well to rich, structured descriptions.
 
-Omit `--region` on the first request so MMX can use or detect the key's region. If that command fails, retry the same request once with the alternate region only when all of these are true:
+**Model:** `music-3.0` — default model.
 
-1. No `taskId` was returned.
-2. `[Model: MiniMax-H3]` was not printed, so the CLI did not confirm task creation.
-3. The error explicitly concerns region detection, a regional endpoint, or a pre-submission 401/403 authentication-routing mismatch.
+```bash
+mmx music generate --prompt <text> [--lyrics <text>] [flags]
+```
 
-Use `--region global` after a failed `cn` attempt, or `--region cn` after a failed `global` attempt. Keep every generation argument unchanged. If the alternate region succeeds, persist it without exposing credentials:
+| Flag | Type | Description |
+|---|---|---|
+| `--prompt <text>` | string | Music style description (can be detailed) |
+| `--lyrics <text>` | string | Song lyrics with structure tags. Required unless `--instrumental` or `--lyrics-optimizer` is used. |
+| `--lyrics-file <path>` | string | Read lyrics from file. Use `-` for stdin |
+| `--lyrics-optimizer` | boolean | Auto-generate lyrics from prompt. Cannot be used with `--lyrics` or `--instrumental`. |
+| `--instrumental` | boolean | Generate instrumental music (no vocals). Cannot be used with `--lyrics`. |
+| `--vocals <text>` | string | Vocal style, e.g. `"warm male baritone"`, `"bright female soprano"`, `"duet with harmonies"` |
+| `--genre <text>` | string | Music genre, e.g. folk, pop, jazz |
+| `--mood <text>` | string | Mood or emotion, e.g. warm, melancholic, uplifting |
+| `--instruments <text>` | string | Instruments to feature, e.g. `"acoustic guitar, piano"` |
+| `--tempo <text>` | string | Tempo description, e.g. fast, slow, moderate |
+| `--bpm <number>` | number | Exact tempo in beats per minute |
+| `--key <text>` | string | Musical key, e.g. C major, A minor, G sharp |
+| `--avoid <text>` | string | Elements to avoid in the generated music |
+| `--use-case <text>` | string | Use case context, e.g. `"background music for video"`, `"theme song"` |
+| `--structure <text>` | string | Song structure, e.g. `"verse-chorus-verse-bridge-chorus"` |
+| `--references <text>` | string | Reference tracks or artists, e.g. `"similar to Ed Sheeran"` |
+| `--extra <text>` | string | Additional fine-grained requirements |
+| `--aigc-watermark` | boolean | Embed AI-generated content watermark |
+| `--format <fmt>` | string | Audio format (default: `mp3`) |
+| `--sample-rate <hz>` | number | Sample rate (default: 44100) |
+| `--bitrate <bps>` | number | Bitrate (default: 256000) |
+| `--out <path>` | string | Save audio to file |
+| `--stream` | boolean | Stream raw audio to stdout |
+
+At least one of `--prompt` or `--lyrics` is required.
 
 ```bash
-mmx config set --key region --value <global-or-cn> --quiet
+# With lyrics
+mmx music generate --prompt "Upbeat pop" --lyrics "La la la..." --out song.mp3 --quiet
+
+# Auto-generate lyrics from prompt
+mmx music generate --prompt "Upbeat pop about summer" --lyrics-optimizer --out summer.mp3 --quiet
+
+# Instrumental
+mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.mp3 --quiet
+
+# Detailed prompt with vocal characteristics
+mmx music generate --prompt "Warm morning folk" \
+  --vocals "male and female duet, harmonies in chorus" \
+  --instruments "acoustic guitar, piano" \
+  --bpm 95 \
+  --lyrics-file song.txt \
+  --out duet.mp3
 ```
 
-Do not perform region fallback for validation errors, error `2013`, billing, rate limits, sensitive content, generic service errors, or an ambiguous timeout. Never region-retry after task creation, during polling, or during download.
+---
 
-## Core Limits
+### music cover
 
-- Prompt: at most 7000 characters.
-- Output duration: integer from 4 through 15 seconds.
-- Resolution: 2K.
-- Reference images: at most 9.
-- Reference videos: at most 3.
-- Reference audios: at most 3.
-- Mixed reference items: at most 12 total.
-- Local image: at most 30 MB each.
-- Local video: MP4, at most 50 MB each.
-- Local audio: MP3 or WAV, at most 15 MB each.
-- Complete local Base64 request body: at most 64 MB.
+Generate a cover version of a song based on reference audio.
 
-Use URLs or `mm_file://<file-id>` for large or numerous assets. Read `references/h3-video.md` for official duration, codec, frame-rate, dimension, and aspect-ratio limits that are not fully validated by the CLI.
+**Model:** `music-cover-free` — unlimited for API key users, RPM = 3.
 
-## Async Task-ID Path
+```bash
+mmx music cover --prompt <text> (--audio <url> | --audio-file <path>) [flags]
+```
 
-Use this only when the user wants immediate submission and a task ID:
+| Flag | Type | Description |
+|---|---|---|
+| `--prompt <text>` | string, **required** | Target cover style, e.g. `"Indie folk, acoustic guitar, warm male vocal"` |
+| `--audio <url>` | string | URL of reference audio (mp3, wav, flac, etc. — 6s to 6min, max 50MB) |
+| `--audio-file <path>` | string | Local reference audio file (auto base64-encoded) |
+| `--lyrics <text>` | string | Cover lyrics. If omitted, extracted from reference audio via ASR. |
+| `--lyrics-file <path>` | string | Read lyrics from file. Use `-` for stdin |
+| `--seed <number>` | number | Random seed 0–1000000 for reproducible results |
+| `--format <fmt>` | string | Audio format: `mp3`, `wav`, `pcm` (default: `mp3`) |
+| `--sample-rate <hz>` | number | Sample rate (default: 44100) |
+| `--bitrate <bps>` | number | Bitrate (default: 256000) |
+| `--channel <n>` | number | Channels: `1` (mono) or `2` (stereo, default) |
+| `--out <path>` | string | Save audio to file |
+| `--stream` | boolean | Stream raw audio to stdout |
 
 ```bash
-mmx video generate \
-  --model MiniMax-H3 \
-  --prompt "<video prompt>" \
-  --duration <4-15> \
-  --async \
-  --output json \
-  --non-interactive
+# Cover from URL
+mmx music cover --prompt "Indie folk, acoustic guitar, warm male vocal" \
+  --audio https://filecdn.minimax.chat/public/d20eda57-2e36-45bf-9e12-82d9f2e69a86.mp3 --out cover.mp3 --quiet
+
+# Cover from local file with custom lyrics
+mmx music cover --prompt "Jazz, piano, slow" \
+  --audio-file original.mp3 --lyrics-file lyrics.txt --out jazz_cover.mp3 --quiet
+
+# Reproducible result with seed
+mmx music cover --prompt "Pop, upbeat" --audio https://filecdn.minimax.chat/public/d20eda57-2e36-45bf-9e12-82d9f2e69a86.mp3 --seed 42 --out cover.mp3
 ```
 
-Return and retain the `taskId`, then stop. Do not automatically monitor or download it. MMX does not provide a task-list command or persist local task history.
+---
 
-## Prompt Handling
+### vision describe
 
-Preserve the user's intent. Write the prompt in the user's language. When a prompt is too short, expand it once using:
+Image understanding via VLM. Provide either `--image` or `--file-id`, not both.
 
-1. Duration, ratio, and use case.
-2. Subjects and reference mapping.
-3. Chronological actions.
-4. Scene, lighting, weather, and background.
-5. Shot size, angle, camera motion, focus, and cuts.
-6. Style, color, mood, and pacing.
-7. Dialogue, ambience, music, and audio synchronization.
-8. Elements to preserve and artifacts to avoid.
+```bash
+mmx vision describe (--image <path-or-url> | --file-id <id>) [flags]
+```
 
-For two or more ordered reference images, use a structured storyboard prompt instead of one prose paragraph:
+| Flag | Type | Description |
+|---|---|---|
+| `--image <path-or-url>` | string | Local path or URL (auto base64-encoded) |
+| `--file-id <id>` | string | Pre-uploaded file ID (skips base64) |
+| `--prompt <text>` | string | Question about the image (default: `"Describe the image."`) |
 
-1. Output specification and ordered reference count.
-2. Global visual style and continuity rules.
-3. Locked character identity, wardrobe, position, and props.
-4. A contiguous master timeline mapped to `reference image 1`, `reference image 2`, and so on.
-5. A micro-timeline inside each shot: establish, prepare, execute, settle/hold, and end-state lock.
-6. Explicit action and object-state transitions for handoffs or other precise motion.
-7. Sound requirements and a final negative-constraint block.
+```bash
+mmx vision describe --image photo.jpg --prompt "What breed?" --output json
+```
 
-Use two timeline levels. The master timeline divides the full clip into shots. Each shot then divides its own interval into timestamped micro-beats. A shot may contain several phases, but they must form one causal action beat. Every shot must state its exact range, duration, reference image, initial state, camera behavior, micro-beats, and locked end state. The next shot's initial state must equal the previous locked end state.
+**stdout**: description text (text mode) or full response (json mode).
 
-Master and micro intervals must cover their parent duration without gaps or overlaps, and reference numbering must match the repeated `--reference-image` flag order. Keep the action achievable within 4-15 seconds. Do not silently add brands, celebrities, dialogue, text overlays, or unsafe content. Use the detailed Chinese and English templates in `references/h3-video.md`.
+---
 
-If the user already provides a complete structured storyboard prompt, do not summarize, shorten, translate, or stylistically rewrite it. Check only the 7000-character limit, duration coverage, reference count/order, media-mode compatibility, and contradictory constraints; preserve the original wording unless a correction is required.
+### search query
 
-## Failure Handling
+Web search via MiniMax.
 
-- Wrong Token Plan/OAuth credential or H3 error `2013`: stop and request a compatible Pay-as-you-go API Key.
-- Clear pre-submission region-routing failure: retry the unchanged command once with the alternate `--region`; never retry after task creation.
-- Authentication, balance, or sensitive-content errors: stop and report the exact error without retrying or silently changing the request.
-- A running terminal session: keep waiting on the same session; absence of a final path is not failure.
-- Terminal task status `failed`, `cancelled`, or `expired`: report the status and task error; require approval before another paid submission.
-- Polling timeout: report the task ID when available; do not submit a duplicate.
-- Download failure after success: retry the same result download only; never regenerate the video.
+```bash
+mmx search query --q <query>
+```
+
+| Flag | Type | Description |
+|---|---|---|
+| `--q <query>` | string, **required** | Search query |
+
+```bash
+mmx search query --q "MiniMax AI" --output json --quiet
+```
+
+---
+
+### quota show
+
+Display Token Plan usage and remaining quotas.
+
+```bash
+mmx quota show [--output json]
+```
+
+---
+
+## Tool Schema Export
+
+Export all commands as Anthropic/OpenAI-compatible JSON tool schemas:
+
+```bash
+# All tool-worthy commands (excludes auth/config/update)
+mmx config export-schema
+
+# Single command
+mmx config export-schema --command "video generate"
+```
+
+Use this to dynamically register mmx commands as tools in your agent framework.
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | General error |
+| 2 | Usage error (bad flags, missing args) |
+| 3 | Authentication error |
+| 4 | Quota exceeded |
+| 5 | Timeout |
+| 10 | Content filter triggered |
+
+---
+
+## Piping Patterns
+
+```bash
+# stdout is always clean data — safe to pipe
+mmx text chat --message "Hi" --output json | jq '.content'
+
+# stderr has progress/spinners — discard if needed
+mmx video generate --prompt "Waves" 2>/dev/null
+
+# Chain: generate image → describe it
+URL=$(mmx image generate --prompt "A sunset" --quiet)
+mmx vision describe --image "$URL" --quiet
+
+# Async video workflow
+TASK=$(mmx video generate --prompt "A robot" --async --quiet | jq -r '.taskId')
+mmx video task get --task-id "$TASK" --output json
+mmx video download --task-id "$TASK" --out robot.mp4
+```
+
+---
+
+## Configuration Precedence
+
+CLI flags → environment variables → `~/.mmx/config.json` → defaults.
+
+```bash
+# Persistent config
+mmx config set --key region --value cn
+mmx config show
+
+# Environment
+export MINIMAX_API_KEY=sk-xxxxx
+export MINIMAX_REGION=cn
+```
+
+### Default Model Configuration
+
+Set per-modality defaults so you don't need `--model` every time:
+
+```bash
+# Set defaults
+mmx config set --key default-text-model --value MiniMax-M3
+mmx config set --key default-speech-model --value speech-2.8-hd
+mmx config set --key default-video-model --value MiniMax-Hailuo-2.3
+mmx config set --key default-music-model --value music-3.0
+
+# Use without --model
+mmx text chat --message "Hello"
+mmx speech synthesize --text "Hello" --out hello.mp3
+mmx video generate --prompt "Ocean waves"
+mmx music generate --prompt "Upbeat pop" --instrumental
+
+# --model still overrides per-call
+mmx text chat --model MiniMax-M3 --message "Hello"
+```
 
-Read the complete failure matrix in `references/h3-video.md` before recovery.
+**Resolution priority**: `--model` flag > config default > hardcoded fallback.
diff --git a/skill/agents/openai.yaml b/skill/agents/openai.yaml
deleted file mode 100644
index 19c948f..0000000
--- a/skill/agents/openai.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-interface:
-  display_name: "MiniMax H3 Video"
-  short_description: "Generate MiniMax-H3 video with the MMX CLI"
-  default_prompt: "Use $mmx-h3-video to generate this MiniMax-H3 video with one direct MMX command, reuse the saved API key without exposing it, and wait on the same terminal session."
diff --git a/skill/references/h3-video.md b/skill/references/h3-video.md
deleted file mode 100644
index f88e3d0..0000000
--- a/skill/references/h3-video.md
+++ /dev/null
@@ -1,252 +0,0 @@
-# MiniMax-H3 Video Agent Guide
-
-Read this reference before submitting a `MiniMax-H3` request. It covers rules that are not fully exposed by CLI flags.
-
-## Credential Rule
-
-- Use a standard Pay-as-you-go/Credit API Key for H3.
-- Do not use an OAuth credential or Token Plan Subscription Key for H3.
-- Run `mmx auth status --output json --quiet` before the first paid request. It reports the credential method and only a masked key.
-- Prefer an API key already saved in MMX config. Generation commands should not contain `--api-key`.
-- If the runtime securely holds a previously supplied key as `MINIMAX_API_KEY`, save it once with `mmx config set --key api_key --value "$MINIMAX_API_KEY" --quiet`.
-- Never print, repeat, or reconstruct a literal key in shell text. If secure injection is unavailable, ask the user to run interactive `mmx auth login` instead of pasting the key into chat again.
-- MMX stores config with owner-only permissions. Saving `api_key` removes stale OAuth credentials and clears the cached region for fresh detection.
-- If error `2013` says TokenPlan or Credit does not support H3, stop. Select a compatible Pay-as-you-go API Key instead of changing the prompt or media.
-
-## Region Selection And Fallback
-
-- Omit `--region` initially. MMX uses the saved region or detects it after a new API key is saved.
-- `Detecting region... cn` and `Detecting region... global` are normal progress messages.
-- Retry the alternate region at most once only when the command clearly failed before task creation because of region detection, a regional endpoint, or a pre-submission 401/403 routing mismatch.
-- Absence of both a `taskId` and `[Model: MiniMax-H3]` is required before retrying creation. If either appeared, assume a paid task may exist and do not resubmit.
-- Keep the request identical and add only `--region global` after `cn`, or `--region cn` after `global`.
-- After a successful alternate-region request, persist it with `mmx config set --key region --value <global-or-cn> --quiet`.
-- Do not region-retry validation, `2013`, balance, rate-limit, sensitive-content, generic 5xx, terminal task failure, polling, download, or ambiguous timeout errors.
-
-## Waiting And Progress
-
-- The API does not publish a fixed completion ETA or progress percentage for each video.
-- Total time varies with queue load, requested duration, and reference-media complexity. Never promise that a task will finish in a specific number of minutes.
-- Poll no more frequently than once every 10 seconds.
-- Valid lifecycle statuses include `queued`, `running`, `succeeded`, `failed`, `cancelled`, and `expired`.
-- For a completed file, use one blocking `mmx video generate` command with `--download`, `--poll-interval 10`, and `--timeout 1800`. The CLI performs status polling internally.
-- If the terminal command remains active, wait on the same execution session. Do not start another command or infer failure from missing output while it is still running.
-- After 30 minutes, the CLI timeout may stop local polling. Preserve and report `taskId` when available; do not submit a duplicate task automatically.
-- MMX has no task-list command and does not persist local task history. Retain the returned task ID.
-
-## Prompt Construction
-
-Preserve the user's intent. When the prompt is underspecified, expand it into one production-oriented prompt in this order:
-
-1. Output goal: duration, aspect ratio, use case, and whether the clip should feel continuous or edited.
-2. Subjects and assets: identify people, products, locations, and how each reference image/video/audio should be used.
-3. Timeline: describe actions in chronological order with clear transitions.
-4. Scene: environment, time of day, lighting, weather, and important background details.
-5. Camera: shot size, angle, movement, focus behavior, and cuts.
-6. Look: visual style, color, texture, mood, and pacing.
-7. Sound: dialogue, ambience, music, sound effects, and synchronization to reference audio.
-8. Constraints: elements to preserve and artifacts to avoid, such as identity drift, flicker, text, logos, or abrupt cuts.
-
-When the user already supplies a complete structured storyboard, keep it intact. Do not condense, translate, or replace it with a generic prompt. Only check prompt length, timestamp coverage, reference numbering, media compatibility, and direct contradictions before submission.
-
-Operational heuristics for better results:
-
-- Keep actions physically achievable within the selected 4-15 second duration.
-- Prefer one clear action beat per shot instead of packing unrelated events into one block.
-- For multiple references, describe them in the same order as the repeated CLI flags: `reference image 1`, `reference image 2`, and so on.
-- Make timestamp ranges contiguous, with no gaps or overlaps, and make their final end time equal the requested duration.
-- Use a two-level timeline: a master shot range for every reference image, then micro-ranges inside that shot for preparation, execution, settling, and the final hold.
-- Use 0.5-second precision by default. Use finer timing only when a short, precise physical transition needs it.
-- Every shot must declare: exact range and duration, reference image number, initial state, shot/camera, micro-timeline, and locked end state.
-- The locked end state of shot N must be the initial state of shot N+1. Check character pose, gaze, occupied hand, prop owner/location, prop connections, and camera side.
-- State what must remain consistent and what may change. Example: preserve face, clothing, and product shape; change pose, camera angle, and background motion.
-- Lock persistent spatial relationships explicitly when important: left/right seat, foreground/background, screen direction, and which hand holds an object.
-- For handoffs and precise object motion, describe state transitions in causal order: initial owner and location, release condition, transfer, new owner, and final state. Do not compress these into one vague action.
-- Separate hard continuity constraints from aesthetic preferences and negative constraints. Repeat a critical invariant in the relevant timeline block when its failure would break the scene.
-- Use explicit camera language such as static shot, close-up, tracking shot, dolly in, pan, tilt, handheld, or aerial view.
-- Specify audio timing only when audio is supplied. State whether motion, cuts, lip movement, or effects should follow the beat or spoken words.
-- Do not silently add brands, dialogue, text overlays, or unsafe content that the user did not request.
-
-Timeline planning procedure:
-
-1. Read total duration `D` and ordered storyboard count `N`.
-2. Preserve user-supplied timestamps. Otherwise start with `D / N` seconds per storyboard; for example, 15 seconds with 6 images starts as six 2.5-second shots.
-3. Reallocate time by action complexity while keeping all ranges contiguous and totaling exactly `D`. Give precise handoffs or multi-stage physical actions more time; give static establishing or reaction shots less.
-4. Split each shot into 3-5 readable micro-beats: establish/hold, preparation, core action, settle/recovery, and optional final hold.
-5. Maintain a state ledger at every boundary: character position and pose, gaze, left/right hand state, prop owner and location, physical connections, and camera side.
-6. Verify that every reference is used exactly once in input order unless the user explicitly requests reuse, and that shot N's locked end state exactly matches shot N+1's initial state.
-7. If the requested actions cannot fit without becoming rushed or ambiguous, simplify the action plan or tell the user before making a paid request. Do not silently compress causal steps.
-
-For two or more ordered storyboard images, use the following structure. Do not flatten it into a single paragraph.
-
-Chinese structured storyboard template:
-
-```text
-【输出规格】
-生成一段{duration}秒、{ratio}的{用途}视频。使用{N}张分镜参考图，严格按输入顺序作为连续镜头参考。按时间轴依次生成，不跳镜，不改变已锁定的人物、服装、位置和核心道具。
-
-【整体风格】
-{真人/动画/产品等媒介}，{电影或视觉风格}，{光线、色彩、纹理、景深、节奏和运镜基调}。场景为{环境、时间、天气和背景运动}。声音为{对白、环境声、音乐或静音要求}。
-
-【人物与空间连续性】
-人物1：{外观、服装、气质}，始终位于{固定位置}。
-人物2：{外观、服装、气质}，始终位于{固定位置}。
-全程保持{脸、发型、服装、座位、朝向、比例和场景结构等硬约束}。
-
-【道具状态连续性】
-全片只有{道具数量和名称}。初始状态：{所有者、所在手、位置、连接关系}。过程中必须保持{形状、数量、连接、可见性和物理行为}，不得凭空出现、消失、复制、跳位或改变所有者。
-
-【两级时间轴与参考图映射】
-镜头1｜0:00-{T1}｜时长{D1}秒｜对应第1张图
-镜头与运镜：{景别、角度、镜头运动和对焦}。
-起始状态：{人物姿势、视线、双手状态、道具所有者/位置/连接关系}。
-镜头内微时间轴：
-- 0:00-{t1a}：建立画面，{可见状态和轻微环境运动}。
-- {t1a}-{t1b}：预备动作，{视线、重心、手部或道具开始变化}。
-- {t1b}-{t1c}：核心动作，{只执行本镜头的主要动作}。
-- {t1c}-{T1}：动作完成后稳定并保持，禁止提前执行下一镜头动作。
-结束状态锁定：{逐项写明人物、手、道具和连接关系，供镜头2直接继承}。
-
-镜头2｜{T1}-{T2}｜时长{D2}秒｜对应第2张图
-镜头与运镜：{景别、角度、镜头运动和对焦}。
-起始状态：必须与镜头1的结束状态完全一致。
-镜头内微时间轴：
-- {T1}-{t2a}：保持上一镜头状态，给动作留出可见停顿。
-- {t2a}-{t2b}：{预备动作}。
-- {t2b}-{t2c}：{核心动作}。
-- {t2c}-{T2}：{完成、回收或保持动作}。
-结束状态锁定：{明确状态}。
-
-{继续为每张参考图写一个完整镜头块。主时间轴和每个镜头内的微时间轴都必须连续无空档，最后一个时间点必须等于duration。}
-
-【严格动作顺序】
-{动作A} → {动作B} → {动作C} → {动作D}。不得合并、倒序或省略。每个镜头只完成一个明确动作；涉及交接时，先写谁保持不动，再写谁接触并拿稳，最后写原持有者何时松手。
-
-【负面约束】
-不要{不需要的视觉类型、剪辑风格和表演方式}。全程无{字幕、水印、多余人物或多余道具}，避免{身份漂移、变装、换位、闪烁、畸形手指、多余肢体、物体跳变、连接关系错误和突兀切镜}。
-```
-
-English structured storyboard template:
-
-```text
-[OUTPUT SPECIFICATION]
-Create a {duration}-second, {ratio} {use case} video using {N} storyboard reference images in their exact input order as consecutive shot references. Follow the timeline without skipping shots or changing locked characters, wardrobe, positions, or key props.
-
-[OVERALL LOOK]
-{Live action/animation/product medium}; {cinematic or visual style}; {lighting, color, texture, depth of field, pacing, and camera baseline}. Scene: {environment, time, weather, and background motion}. Sound: {dialogue, ambience, music, reference-audio synchronization, or silence}.
-
-[CHARACTER AND SPATIAL CONTINUITY]
-Character 1: {appearance, wardrobe, demeanor}; always at {fixed position}.
-Character 2: {appearance, wardrobe, demeanor}; always at {fixed position}.
-Preserve {faces, hair, wardrobe, seats, screen direction, proportions, and scene layout} throughout.
-
-[PROP STATE CONTINUITY]
-The entire video contains exactly {prop count and names}. Initial state: {owner, hand, location, and connection}. Preserve {shape, count, connection, visibility, and physical behavior}; never duplicate, remove, teleport, disconnect, or silently change ownership.
-
-[TWO-LEVEL TIMELINE AND REFERENCE MAPPING]
-Shot 1 | 0:00-{T1} | Duration {D1}s | Reference image 1
-Shot and camera: {framing, angle, movement, and focus}.
-Initial state: {poses, gazes, both-hand states, prop owner/location/connections}.
-In-shot micro-timeline:
-- 0:00-{t1a}: Establish the frame with {visible state and subtle environment motion}.
-- {t1a}-{t1b}: Preparation: {gaze, weight, hand, or prop begins to change}.
-- {t1b}-{t1c}: Core action: {perform only this shot's main action}.
-- {t1c}-{T1}: Settle and hold the completed action; do not begin the next shot's action early.
-Locked end state: {explicit character, hand, prop, and connection state inherited by shot 2}.
-
-Shot 2 | {T1}-{T2} | Duration {D2}s | Reference image 2
-Shot and camera: {framing, angle, movement, and focus}.
-Initial state: exactly match shot 1's locked end state.
-In-shot micro-timeline:
-- {T1}-{t2a}: Hold the inherited state long enough to remain readable.
-- {t2a}-{t2b}: {preparation}.
-- {t2b}-{t2c}: {core action}.
-- {t2c}-{T2}: {completion, recovery, or hold}.
-Locked end state: {explicit state}.
-
-{Continue with one complete shot block per reference image. Both the master timeline and every in-shot micro-timeline must be contiguous; the final timestamp must equal duration.}
-
-[STRICT ACTION ORDER]
-{Action A} -> {Action B} -> {Action C} -> {Action D}. Do not merge, reorder, or omit steps. Each shot completes one clear action. For a handoff, state who remains still, who establishes and secures contact, and only then when the original holder releases.
-
-[NEGATIVE CONSTRAINTS]
-No {unwanted visual genre, editing style, or performance}. No {subtitles, watermarks, extra people, or extra props}. Avoid {identity drift, wardrobe changes, position swaps, flicker, malformed fingers, extra limbs, prop teleportation, broken connections, and abrupt cuts}.
-```
-
-For a single text-to-video request or one loose reference, a concise paragraph is acceptable. Use the full storyboard structure when continuity, multiple ordered images, or precise physical interactions matter.
-
-### Detailed Timing Example: Earbud Removal And Handoff
-
-Chinese:
-
-```text
-镜头2｜0:02.5-0:05.0｜时长2.5秒｜对应第2张图
-起始状态：女生低头看手机，两只耳塞都在女生耳中；手机在女生手中；男生双手仍抱着书包。
-0:02.5-0:03.0：女生把手机稍微放低并短暂看向男生，其他状态不变。
-0:03.0-0:04.1：女生用靠近男生的手，以拇指和食指捏住耳机柄，缓慢从自己耳中取下一个耳塞。
-0:04.1-0:05.0：女生把耳塞停在两人之间、胸口高度；男生尚未伸手；耳塞与男生脸和耳朵之间保留明显空隙。
-结束状态锁定：女生仍捏着耳机柄，另一只耳塞仍在女生耳中，耳机线仍连接女生手机；男生双手仍在书包上。
-
-镜头3｜0:05.0-0:07.5｜时长2.5秒｜对应第3张图
-起始状态：完全继承镜头2的结束状态。
-0:05.0-0:05.5：女生保持手和耳塞不动；男生短暂停顿。
-0:05.5-0:06.4：男生抬起靠近女生的手，拇指和食指接近耳机柄，女生仍不松手。
-0:06.4-0:07.0：男生夹住并拿稳耳机柄；只有确认拿稳后，女生才松手。
-0:07.0-0:07.5：女生把手收回；男生持有耳塞，但尚未把它移向耳朵。
-结束状态锁定：耳塞所有者已变为男生，位于两人之间；女生手已退出交接区域；耳机线仍从女生手机自然连接到耳塞。
-```
-
-English:
-
-```text
-Shot 2 | 0:02.5-0:05.0 | Duration 2.5s | Reference image 2
-Initial state: the girl looks at her phone with both earbuds in her ears; she holds the phone; the boy still holds his bag with both hands.
-0:02.5-0:03.0: The girl lowers the phone slightly and briefly looks at the boy; all other states remain unchanged.
-0:03.0-0:04.1: With the hand closer to the boy, she pinches one earbud stem between thumb and index finger and slowly removes it from her ear.
-0:04.1-0:05.0: She holds the earbud at chest height between them; the boy has not reached for it; a visible gap remains between the earbud and his face and ear.
-Locked end state: the girl still holds the earbud stem; the other earbud remains in her ear; the cable remains connected to her phone; both of the boy's hands remain on his bag.
-
-Shot 3 | 0:05.0-0:07.5 | Duration 2.5s | Reference image 3
-Initial state: exactly inherit shot 2's locked end state.
-0:05.0-0:05.5: The girl keeps her hand and the earbud still; the boy pauses.
-0:05.5-0:06.4: The boy raises the hand closer to the girl and approaches the earbud stem with thumb and index finger; she does not release it.
-0:06.4-0:07.0: The boy grips and secures the earbud stem; only after his grip is stable does the girl release it.
-0:07.0-0:07.5: The girl withdraws her hand; the boy holds the earbud but does not move it toward his ear yet.
-Locked end state: ownership has transferred to the boy; the earbud remains between them; the girl's hand has left the handoff area; the cable still connects naturally to the girl's phone.
-```
-
-## Media Preflight
-
-Frame mode and reference mode cannot be mixed. Reference audio requires at least one reference image or reference video.
-
-| Input | Official count/technical limits | Current local CLI handling |
-|---|---|---|
-| First frame | At most 1 image | `--image`; at most 30 MB |
-| Last frame | At most 1 image | `--last-frame`; at most 30 MB |
-| Reference image | At most 9; JPEG/JPG/PNG/WebP; 256-5760 px sides; aspect ratio 0.4-2.5 | JPG/JPEG/PNG/WebP/HEIC/HEIF; at most 30 MB each |
-| Reference video | At most 3; MP4/MOV; H.264/H.265; 23.976-60 FPS; each 2-15 seconds; total at most 15 seconds | Local MP4 only; at most 50 MB each. Use URL or `mm_file://` for other supported API inputs |
-| Reference audio | At most 3; MP3/WAV; each 2-15 seconds; total at most 15 seconds | Local MP3/WAV; at most 15 MB each |
-
-The total number of reference images, videos, and audios in a mixed-reference request must not exceed 12. Local media is Base64-encoded, and MMX limits the complete request body to 64 MB. Use public URLs or `mm_file://<file-id>` for large or numerous media inputs.
-
-Before a paid request, inspect local video/audio duration and codec once when they are unknown. Do not transcode media unless it violates an actual format or duration rule.
-
-## Failure Handling
-
-Use the shortest non-duplicating response:
-
-| Failure | Action |
-|---|---|
-| Region detection/endpoint or pre-submission 401/403, with no `taskId` and no model marker | Retry the unchanged request once with the alternate `--region`; if it succeeds, save that region |
-| No `taskId` and validation/HTTP 400 | Correct the reported field once; do not alter unrelated parameters |
-| `2013` mentioning TokenPlan/Credit and H3 | Stop and use a compatible Pay-as-you-go API Key |
-| Authentication error (`1004`, `2049`, HTTP 401/403) | Stop and request a valid key; do not retry |
-| Insufficient balance (`1008`, HTTP 402) | Stop and report the billing problem |
-| Rate limit (`1002`, HTTP 429) | Wait 60 seconds using the agent runtime's wait capability, then retry the same safe query once. Retry creation only when the response clearly confirms no task was created |
-| Sensitive prompt/media (`1026`, `1027`, HTTP 422) | Report the rejected input and ask the user to revise it; do not silently rewrite |
-| Temporary service/query error (`1000`, `1001`, `1024`, `1033`, HTTP 5xx) | For an existing task, wait 10 seconds using the agent runtime's wait capability and retry the same status query up to 3 times. Do not submit a replacement task automatically |
-| Terminal `failed`, `cancelled`, or `expired` | Report `taskId`, status, and task error; require user approval before creating another paid task |
-| Polling exceeds 30 minutes | Let the direct CLI command return its timeout, preserve `taskId` when available, and report that the task may still complete later |
-| Download fails after `succeeded` | Retry the same result URL up to 3 times; never regenerate the video |
-
-Once a task ID exists, all recovery must operate on that task ID. Never create a second paid task merely because terminal-session handling, polling, or downloading failed.