@sogni-ai/sogni-creative-agent-skill 2.1.3 → 2.3.0

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: sogni-creative-agent-skill
-version: "2.1.3"
-description: Sogni Creative Agent Skill: agent skill and CLI for image and video generation using Sogni AI's decentralized GPU network. Supports personas (named people with saved reference photos and voice clips), persistent memories (user preferences across sessions), custom personality, style transfer, angle synthesis, and multi-step creative workflows. Ask the agent to "draw", "generate", "create an image", "make a video/animate", "apply a style", or "generate me as a superhero".
-homepage: https://sogni.ai
+description: "Sogni Creative Agent Skill: agent skill and CLI for image, video, and music generation using Sogni AI's decentralized GPU network. Supports personas (named people with saved reference photos and voice clips), persistent memories (user preferences across sessions), custom personality, style transfer, angle synthesis, and multi-step creative workflows. Ask the agent to \"draw\", \"generate\", \"create an image\", \"make a video/animate\", \"make music\", \"apply a style\", or \"generate me as a superhero\"."
 metadata:
+  version: "2.3.0"
+  homepage: https://sogni.ai
   clawdbot:
     emoji: "🎨"
     primaryEnv: "SOGNI_API_KEY"
@@ -13,8 +13,6 @@ metadata:
       anyBins: ["ffmpeg"]
       env:
         - "SOGNI_API_KEY"
-        - "SOGNI_USERNAME"
-        - "SOGNI_PASSWORD"
         - "SOGNI_CREDENTIALS_PATH"
         - "SOGNI_LAST_RENDER_PATH"
         - "SOGNI_MEDIA_INBOUND_DIR"
@@ -34,9 +32,11 @@ metadata:
         label: "Prepare runtime dependencies"
 ---
 
-# Sogni Image & Video Generation
+# Sogni Image, Video & Music Generation
 
-Generate **images and videos** using Sogni AI's decentralized GPU network.
+Generate **images, videos, and music** using Sogni AI's decentralized GPU network.
+
+> **Per-skill view**: hosts that want to load focused capabilities rather than this monolith can read [`skills/README.md`](./skills/README.md) for the per-skill index — one markdown file per skill (`image_generation`, `image_editing`, `video_generation`, `video_editing`, `music_generation`, `media_analysis`, `persona_management`, `app_settings`, plus the always-loaded `quality_audit`, `session_control`, `asset_reference_management`). Each file mirrors the canonical manifest in `@sogni/creative-agent`. The whole-monolith load below stays the default for OpenClaw / Claude Code / Hermes Agent / Manus AI integrations.
 
 ## Install Request Policy
 
@@ -72,20 +72,17 @@ If that checkout does not exist, prefer the npm-based local skill install below,
 
 ## Setup
 
-1. **Get Sogni credentials** at https://app.sogni.ai/
-2. **Create credentials file:**
+1. **Get your Sogni API key** by logging into https://dashboard.sogni.ai and opening the account menu.
+2. **Create an API key credentials file:**
 ```bash
 mkdir -p ~/.config/sogni
 cat > ~/.config/sogni/credentials << 'EOF'
 SOGNI_API_KEY=your_api_key
-# or:
-# SOGNI_USERNAME=your_username
-# SOGNI_PASSWORD=your_password
 EOF
 chmod 600 ~/.config/sogni/credentials
 ```
 
-You can also export `SOGNI_API_KEY`, or `SOGNI_USERNAME` + `SOGNI_PASSWORD`, instead of writing the file.
+You can also export `SOGNI_API_KEY` instead of writing the file. The API key can always be found by logging into https://dashboard.sogni.ai and opening the account menu.
 
 3. **Install the CLI and skill by default:**
 ```bash
@@ -115,7 +112,7 @@ When this skill is distributed via ClawHub, it bootstraps its local runtime depe
 
 Default file paths used by this skill:
 
-- Credentials file (read): `~/.config/sogni/credentials`
+- API key credentials file (read): `~/.config/sogni/credentials`
 - Last render metadata (read/write): `~/.config/sogni/last-render.json`
 - OpenClaw config (read): `~/.openclaw/openclaw.json`
 - Media listing for `--list-media` (read): `~/.clawdbot/media/inbound`
@@ -127,7 +124,7 @@ Path override environment variables:
 - `SOGNI_MEDIA_INBOUND_DIR`
 - `OPENCLAW_CONFIG_PATH`
 
-## Usage (Images & Video)
+## Usage (Images, Video & Music)
 
 ```bash
 # Generate and get URL
@@ -159,8 +156,94 @@ node sogni-agent.mjs --json --balance
 
 # Quiet mode (suppress progress)
 node sogni-agent.mjs -q -o /tmp/cat.png "a cat wearing a hat"
+
+# Direct music/audio generation
+node sogni-agent.mjs --music --duration 30 \
+  "uplifting cinematic synthwave theme for a product launch"
+
+# Song with lyrics and musical controls
+node sogni-agent.mjs --music --lyrics "Rise with the morning light" --bpm 128 \
+  --keyscale "C major" --output-format mp3 "bright indie pop chorus"
+
+# Hosted API chat: natural-language creative-agent tool execution
+node sogni-agent.mjs --api-chat "Create a 4-shot product video concept for a red sneaker"
+
+# Hosted API chat with image vision and media-reference metadata
+node sogni-agent.mjs --api-chat --ref product.jpg \
+  "Turn this into a launch poster and describe the edit plan"
+
+# Sogni Intelligence model/replay utilities
+node sogni-agent.mjs --list-api-models
+node sogni-agent.mjs --api-chat --task-profile reasoning --no-thinking \
+  "Plan a concise multi-step product launch workflow"
+node sogni-agent.mjs --list-replays 20
+node sogni-agent.mjs --get-replay run_abc123 --json
+
+# Durable API workflow: async image-to-video with resumable workflow record
+node sogni-agent.mjs --api-workflow image-to-video \
+  --video-prompt "The camera slowly pushes in as the sketch comes alive" \
+  "A graphite robot sketch on a drafting table"
+
+# Durable API workflow with media reference and cost controls
+node sogni-agent.mjs --api-workflow image-to-video \
+  --ref https://cdn.example.com/sketch.png \
+  --workflow-max-cost 25 --confirm-cost \
+  --video-prompt "The camera slowly pushes in as the sketch comes alive" \
+  "Animate the referenced sketch"
+
+# Shared CreativeWorkflowPlan: API compiles and validates through @sogni/creative-agent
+node sogni-agent.mjs --api-workflow creative-plan --workflow-input @plan.json
+
+# Durable storyboard-video workflow: storyline -> GPT Image 2 storyboard -> Seedance
+node sogni-agent.mjs --api-workflow storyboard-video --storyboard-frames 6 --duration 12 -Q hq \
+  "Create a 9:16 bakery launch video with a neon street-window reveal"
 ```
 
+Use `--api-chat` for text-first natural-language workflows that should go through
+Sogni API's OpenAI-compatible `/v1/chat/completions` tool loop. This path
+sanitizes prompt-injection markers before forwarding messages and uses the
+current hosted creative-agent tool surface. Use `--api-workflow` when the caller
+already knows it wants an async durable workflow record under
+`/v1/creative-agent/workflows`. Use `--api-workflow creative-plan` when the
+caller already has a shared `CreativeWorkflowPlan`; the skill forwards it as
+`kind: "creative_plan"` and lets Sogni API compile, validate, and persist it
+through `@sogni/creative-agent`. This is the preferred hosted path for exact
+multi-step plans, including repeated `replace_video_segment` operations with
+`replacementStartSeconds` / `replacementEndSeconds` when interleaving existing
+video slices. Use `--api-workflow storyboard-video`
+when the caller wants the hosted sequence to generate a storyline, create one GPT
+Image 2 storyboard sheet, and feed that image artifact into Seedance as the video
+reference. The `-Q fast|hq|pro` preset maps to GPT Image 2 low|medium|high
+quality for the storyboard sheet. Hosted API requests forward media references
+from `-c`, `--ref`, `--ref-end`, `--ref-audio`,
+`--reference-audio-identity`, and `--ref-video` as `media_references`
+metadata; workflow JSON can bind them into step arguments with
+`sourceStepId: "$input_media"`, and API chat also attaches image refs as vision
+inputs. Local file references are uploaded to Sogni media storage first, then
+forwarded as retrievable URLs for hosted chat and durable workflows. Use the
+direct CLI path for private media that must not leave the local machine.
+Use `--workflow-max-cost <n>` plus `--confirm-cost` / `--no-confirm-cost` to
+forward explicit workflow cost policy.
+Sogni Intelligence utilities are exposed through the same API key path:
+`--list-api-models` / `--get-api-model <id>` read `/v1/models`,
+`--task-profile`, `--max-tokens`, and `--thinking` / `--no-thinking` tune
+`/v1/chat/completions`, and `--list-replays`, `--get-replay`, and
+`--ingest-replay` manage `/v1/replay/records` RunRecords for replay/debug
+viewers.
+Hosted API modes require `SOGNI_API_KEY`; this skill's CLI uses API-key
+authentication.
+
+When changing hosted API chat/workflow behavior, keep reusable validation,
+workflow compilation, repair-control, and guard telemetry logic in
+`../sogni-creative-agent` first. The public skill should consume generated or
+copied shared contracts instead of adding skill-local regex guards. Media-routing
+decisions should come from typed planner/runtime contracts such as
+`CreativeTurnPlannerFields`, `classifyMediaTurnIntent()`, `videoContinuation`,
+`videoModification`, `outputGrouping`, `imageSelectionPolicy`, and
+`pendingStitchAfterBatch`; regex is appropriate only for bounded CLI/fact
+extraction such as paths, URLs, extensions, dimensions, durations, and explicit
+positions.
+
 ## Options
 
 | Flag | Description | Default |
@@ -185,7 +268,7 @@ node sogni-agent.mjs -q -o /tmp/cat.png "a cat wearing a hat"
 | `--angle-description <text>` | Optional subject description | - |
 | `--steps <num>` | Override steps (model-dependent) | - |
 | `--guidance <num>` | Override guidance (model-dependent) | - |
-| `--output-format <f>` | Image output format: png\|jpg | png |
+| `--output-format <f>` | Image output format: png\|jpg, or webp for gpt-image-2 | png |
 | `--sampler <name>` | Sampler (model-dependent) | - |
 | `--scheduler <name>` | Scheduler (model-dependent) | - |
 | `--lora <id>` | LoRA id (repeatable, edit only) | - |
@@ -196,10 +279,22 @@ node sogni-agent.mjs -q -o /tmp/cat.png "a cat wearing a hat"
 | `--balance, --balances` | Show SPARK/SOGNI balances and exit | - |
 | `-c, --context <path>` | Context image for editing | - |
 | `--last-image` | Use last generated image as context/ref | - |
+| `--music` | Generate music/audio instead of image | - |
+| `--music-model <id>` | Music model: turbo\|sft\|ace_step_1.5_turbo\|ace_step_1.5_sft | ace_step_1.5_turbo |
+| `--lyrics <text>` | Optional lyrics for song generation | - |
+| `--language <code>` | Lyrics language code | en |
+| `--bpm <num>` | Music tempo, 30-300 BPM | server default |
+| `--keyscale <text>` | Music key/scale, e.g. C major | - |
+| `--timesig <n>` | Time signature: 2\|3\|4\|6 | server default |
+| `--composer-mode`, `--no-composer-mode` | Toggle AI composer mode | server default |
+| `--prompt-strength <n>` | Music prompt adherence, 0-10 | server default |
+| `--creativity <n>` | Music variation/temperature, 0-2 | server default |
+| `--music-shift <n>` | Audio model shift parameter, 1-6 | 3 |
+| `--audio-format <f>` | Alias for music output format: mp3\|flac\|wav | mp3 |
 | `--video, -v` | Generate video instead of image | - |
 | `--workflow <type>` | Video workflow (t2v\|i2v\|s2v\|ia2v\|a2v\|v2v\|animate-move\|animate-replace) | inferred |
 | `--fps <num>` | Frames per second (video) | model default |
-| `--duration <sec>` | Duration in seconds (video) | 5 |
+| `--duration <sec>` | Duration in seconds (video or music) | video 5, music 30 |
 | `--frames <num>` | Override total frames (video) | - |
 | `--target-resolution <px>` | Short-side video target preserving aspect ratio | - |
 | `--auto-resize-assets` | Auto-resize video assets | true |
@@ -232,6 +327,28 @@ node sogni-agent.mjs -q -o /tmp/cat.png "a cat wearing a hat"
 | `--concat-audio <path>` | Optional audio track to mux over `--concat-videos` output | - |
 | `--concat-audio-start <sec>` | Start offset into `--concat-audio` | - |
 | `--list-media [type]` | List recent inbound media (images\|audio\|all) | images |
+| `--api-chat` | Call `/v1/chat/completions` with Sogni creative-agent tool injection | - |
+| `--api-tools <mode>` | API tool mode: creative-agent\|creative-tools\|none | creative-agent |
+| `--no-api-tool-execution` | Plan/tool-call via API chat without executing Sogni tools | - |
+| `--llm-model <id>` | LLM model for `--api-chat` | qwen3.6-35b-a3b-gguf-iq4xs |
+| `--task-profile <profile>` | Sogni Intelligence task profile: general\|coding\|reasoning | - |
+| `--max-tokens <n>` | Max hosted chat completion tokens | 1600 |
+| `--thinking`, `--no-thinking` | Toggle `chat_template_kwargs.enable_thinking` for hosted chat | server default |
+| `--list-api-models`, `--get-api-model <id>` | Inspect Sogni Intelligence LLM model metadata | - |
+| `--list-replays [n]`, `--get-replay <id>`, `--ingest-replay <json\|path\|@path>` | Manage Sogni Intelligence replay RunRecords | - |
+| `--api-workflow <kind>` | Start durable workflow: image-to-video\|hosted-tool-sequence\|creative-plan\|storyboard-video | - |
+| `--workflow-input <json\|path\|@path>` | Workflow input JSON for hosted tool sequences/custom starts | - |
+| `--workflow-title <text>` | Title for hosted-tool-sequence, creative-plan, or storyboard-video workflow input | - |
+| `--workflow-max-cost <n>` | Reject hosted workflow starts above this estimated capacity-unit ceiling | - |
+| `--confirm-cost`, `--no-confirm-cost` | Forward explicit hosted workflow cost confirmation | - |
+| `--storyboard-frames <n>` | Beat count for storyboard-video workflow | - |
+| `--video-prompt <text>` | Motion prompt for durable image-to-video workflow | - |
+| `--negative-prompt <text>` | Negative prompt for durable image-to-video workflow | - |
+| `--generate-audio`, `--no-generate-audio` | Toggle audio generation for durable image-to-video | - |
+| `--expand-prompt`, `--no-expand-prompt` | Toggle prompt expansion for durable image-to-video | - |
+| `--watch-workflow` | Stream durable workflow events after start | - |
+| `--list-workflows`, `--get-workflow <id>`, `--workflow-events <id>`, `--stream-workflow <id>`, `--cancel-workflow <id>` | Durable workflow management helpers | - |
+| `--api-base-url <url>` | Sogni API base for hosted API modes. Credentials are only sent to `https://api.sogni.ai` by default; use `SOGNI_API_ALLOWED_HOSTS` for trusted custom hosts or `SOGNI_ALLOW_UNSAFE_API_BASE_URL=1` for isolated local testing. | https://api.sogni.ai |
 | `--no-filter` | Disable NSFW content filter | - |
 | `--memory-set <key> <value>` | Save a user preference | - |
 | `--memory-get <key>` | Get a specific memory | - |
@@ -264,6 +381,7 @@ When installed as an OpenClaw plugin, Sogni Creative Agent Skill will read defau
           "defaultImageModel": "z_image_turbo_bf16",
           "defaultEditModel": "qwen_image_edit_2511_fp8_lightning",
           "defaultPhotoboothModel": "coreml-sogniXLturbo_alpha1_ad",
+          "defaultMusicModel": "ace_step_1.5_turbo",
           "videoModels": {
             "t2v": "ltx23-22b-fp8_t2v_distilled",
             "i2v": "wan_v2.2-14b-fp8_i2v_lightx2v",
@@ -277,6 +395,14 @@ When installed as an OpenClaw plugin, Sogni Creative Agent Skill will read defau
           "defaultVideoWorkflow": "t2v",
           "defaultNetwork": "fast",
           "defaultTokenType": "spark",
+          "apiBaseUrl": "https://api.sogni.ai",
+          "defaultLlmModel": "qwen3.6-35b-a3b-gguf-iq4xs",
+          "defaultTaskProfile": "general",
+          "defaultApiMaxTokens": 1600,
+          "defaultApiThinking": false,
+          "defaultApiToolMode": "creative-agent",
+          "defaultWorkflowMaxCost": 25,
+          "defaultWorkflowConfirmCost": false,
           "seedStrategy": "prompt-hash",
           "modelDefaults": {
             "flux1-schnell-fp8": { "steps": 4, "guidance": 3.5 },
@@ -289,6 +415,8 @@ When installed as an OpenClaw plugin, Sogni Creative Agent Skill will read defau
           "defaultDurationSec": 5,
           "defaultImageTimeoutSec": 30,
           "defaultVideoTimeoutSec": 300,
+          "defaultMusicDurationSec": 30,
+          "defaultMusicTimeoutSec": 600,
           "credentialsPath": "~/.config/sogni/credentials",
           "lastRenderPath": "~/.config/sogni/last-render.json",
           "mediaInboundDir": "~/.clawdbot/media/inbound"
@@ -308,6 +436,7 @@ Seed strategies: `prompt-hash` (deterministic) or `random`.
 | Model | Speed | Use Case |
 |-------|-------|----------|
 | `z_image_turbo_bf16` | Fast (~5-10s) | General purpose, default |
+| `gpt-image-2` | Variable | OpenAI GPT Image 2 text-to-image and edit, strong prompt and text rendering |
 | `flux1-schnell-fp8` | Very fast | Quick iterations |
 | `flux2_dev_fp8` | Slow (~2min) | High quality |
 | `chroma-v.46-flash_fp8` | Medium | Balanced |
@@ -315,9 +444,23 @@ Seed strategies: `prompt-hash` (deterministic) or `random`.
 | `qwen_image_edit_2511_fp8_lightning` | Fast | Quick image editing |
 | `coreml-sogniXLturbo_alpha1_ad` | Fast | Photobooth face transfer (SDXL Turbo) |
 
+`gpt-image-2` supports flexible OpenAI image sizes up to `3840px` on either edge, max `3:1` aspect ratio, and total pixels from `655,360` through `8,294,400`; the API snaps dimensions to valid multiples of 16.
+
+## Music Models
+
+| Model | Use Case |
+|-------|----------|
+| `ace_step_1.5_turbo` | Default direct music generation model |
+| `ace_step_1.5_sft` | Experimental option with stronger lyric handling |
+
+Use `--music` for direct audio-only generation. Defaults are 30 seconds, `mp3`,
+`ace_step_1.5_turbo`, 8 steps, `euler` sampler, and `simple` scheduler. Keep
+`--audio` for video reference audio (`--ref-audio` alias); do not use it for
+direct music generation.
+
 ## Video Models
 
-### WAN 2.2 Models
+### Current Video Model Selectors
 
 | Model | Speed | Use Case |
 |-------|-------|----------|
@@ -326,10 +469,10 @@ Seed strategies: `prompt-hash` (deterministic) or `random`.
 | `ltx23-22b-fp8_ia2v_distilled` | Fast (~2-3min) | Image+audio-to-video |
 | `ltx23-22b-fp8_a2v_distilled` | Fast (~2-3min) | Audio-to-video |
 | `ltx23-22b-fp8_v2v_distilled` | Fast (~3min) | Video-to-video with ControlNet |
-| `seedance2` | Variable | Seedance 2.0 text-to-video alias, 4-15s, native audio |
-| `seedance2-fast` | Variable | Fast Seedance 2.0 text-to-video alias |
-| `seedance2-ia2v` | Variable | Seedance 2.0 image+audio-to-video alias |
-| `seedance2-v2v` | Variable | Seedance 2.0 video-to-video alias, no ControlNet |
+| `seedance2` | Variable | Seedance 2.0 text-to-video, 4-15s, native audio |
+| `seedance2-fast` | Variable | Fast Seedance 2.0 text-to-video |
+| `seedance2-ia2v` | Variable | Seedance 2.0 image+audio-to-video |
+| `seedance2-v2v` | Variable | Seedance 2.0 video-to-video, no ControlNet |
 | `wan_v2.2-14b-fp8_i2v_lightx2v` | Fast | Simple image-to-video |
 | `wan_v2.2-14b-fp8_i2v` | Slow | Higher quality video |
 | `wan_v2.2-14b-fp8_t2v_lightx2v` | Fast | Text-to-video |
@@ -352,7 +495,7 @@ Seed strategies: `prompt-hash` (deterministic) or `random`.
 
 ## Image Editing with Context
 
-Edit images using reference images (Qwen models support up to 3):
+Edit images using reference images. Qwen models support up to 3 context images; GPT Image 2 edit supports up to 16 when selected with `-m gpt-image-2`:
 
 ```bash
 # Single context image
@@ -361,11 +504,14 @@ node sogni-agent.mjs -c photo.jpg "make the background a beach"
 # Multiple context images (subject + style)
 node sogni-agent.mjs -c subject.jpg -c style.jpg "apply the style to the subject"
 
+# GPT Image 2 multi-reference edit
+node sogni-agent.mjs -m gpt-image-2 -c subject.jpg -c outfit.jpg -c room.jpg "place the subject in the room wearing the outfit"
+
 # Use last generated image as context
 node sogni-agent.mjs --last-image "make it more vibrant"
 ```
 
-When context images are provided without `-m`, defaults to `qwen_image_edit_2511_fp8_lightning`.
+When context images are provided without `-m`, defaults to `qwen_image_edit_2511_fp8_lightning`. Select `-m gpt-image-2` for GPT Image 2's higher reference-image limit and OpenAI-backed image editing.
 
 ## Photobooth (Face Transfer)
 
@@ -477,7 +623,11 @@ node sogni-agent.mjs --video --ref scene.png --duration 10 --fps 24 "zoom out sl
 node sogni-agent.mjs --video --target-resolution 768 \
   "A calm cinematic shot of lanterns drifting across a night lake"
 
-# Seedance 2.0 explicit text-to-video alias
+# Natural-language aspect and resolution inference
+node sogni-agent.mjs --video \
+  "Make a 720p 9:16 video of ocean waves at sunset"
+
+# Seedance 2.0 text-to-video
 node sogni-agent.mjs --video -m seedance2 --duration 8 \
   "A polished product reveal with native ambient sound"
 
@@ -504,6 +654,9 @@ node sogni-agent.mjs --video --ref-audio song.mp3 \
 node sogni-agent.mjs --video --reference-audio-identity voice.webm \
   "NARRATOR: \"This is my voice.\""
 
+# Prefer .webm, .m4a, or .mp3 voice clips. Local .wav clips are normalized
+# to .m4a before upload when ffmpeg is available.
+
 # LTX-2.3 text-to-video
 node sogni-agent.mjs --video -m ltx23-22b-fp8_t2v_distilled --duration 20 \
   "A wide cinematic aerial shot opens over steep tropical cliffs at golden hour, warm sunlight grazing the rock faces while sea mist drifts above the water below. Palm trees bend gently along the ridge as waves roll against the shoreline, leaving bright bands of foam across the dark stone. The camera glides forward in one continuous pass, revealing more of the coastline as sunlight flickers across wet surfaces and distant birds wheel through the haze. The scene holds a calm, upscale travel-film mood with smooth stabilized motion and crisp environmental detail."
@@ -537,7 +690,7 @@ node sogni-agent.mjs --video --workflow v2v --ref-video scene.mp4 \
 ```
 
 ControlNet types: `canny` (edge detection), `pose` (body pose), `depth` (depth map), `detailer` (detail enhancement).
-Default V2V strengths are tuned from Sogni Chat: `canny`/`pose`/`depth` use `0.85` plus detailer assist, while `detailer` uses `1.0` for preservation. For Seedance V2V, use `-m seedance2-v2v` and omit ControlNet. Seedance accepts public HTTPS image, video, and audio references as URL context; audio references must be paired with an image or video reference.
+Default V2V strengths are tuned from Sogni Chat: `canny`/`pose`/`depth` use `0.85` plus detailer assist, while `detailer` uses `1.0` for preservation. For Seedance V2V, use `-m seedance2-v2v` and omit ControlNet. Seedance accepts public HTTPS image, video, and audio references as URL context when they pass the CLI URL safety checks; localhost and private-network URLs are rejected before forwarding. Audio references must be paired with an image or video reference.
 
 ```bash
 # Seedance V2V without ControlNet
@@ -650,6 +803,9 @@ node {{skillDir}}/sogni-agent.mjs -q --video --ref /path/to/image.png -o /tmp/vi
 # Generate text-to-video
 node {{skillDir}}/sogni-agent.mjs -q --video -o /tmp/video.mp4 "A wide cinematic shot opens on ocean waves rolling toward a rocky shoreline at sunset, golden light spreading across the water while sea mist drifts through the air. Foam patterns form and recede over the dark sand as the horizon glows orange and pink in the distance. The camera glides forward in one continuous movement, holding smooth stabilized motion and calm environmental detail throughout the scene."
 
+# Generate direct music/audio
+node {{skillDir}}/sogni-agent.mjs -q --music --duration 30 -o /tmp/music.mp3 "uplifting cinematic synthwave theme for a product launch"
+
 # HD / "4K" text-to-video: prefer LTX-2.3
 node {{skillDir}}/sogni-agent.mjs -q --video -m ltx23-22b-fp8_t2v_distilled -w 1920 -h 1088 -o /tmp/video.mp4 "A wide cinematic aerial shot opens over a rugged ocean coastline at golden hour, warm sunlight catching the cliff faces while white surf breaks against dark rock below. Low sea mist hangs over the water and bands of foam trace the shoreline as gulls wheel through the distance. The camera glides forward in one continuous pass, revealing the curve of the coast while wet stone flashes with reflected light and the scene keeps smooth stabilized motion from start to finish. The overall mood feels expansive and polished, with crisp environmental detail and steady travel-film energy."
 
@@ -709,6 +865,7 @@ When the user asks for video in **"hd"**, **"1080p"**, **"4k"**, **"uhd"**, or *
 - For **image-to-video**, use `-m ltx23-22b-fp8_i2v_distilled`.
 - Prefer LTX-sized dimensions such as `-w 1920 -h 1088`.
 - For bare named resolutions such as "720p" without orientation or exact pixels, prefer `--target-resolution 768` or the closest requested short side instead of forcing landscape dimensions.
+- When the prompt combines a named resolution with an aspect ratio, such as "720p 9:16", let the CLI infer both instead of forcing manual `-w`/`-h` unless the user gave exact pixels.
 - If the user explicitly asks for `vertical`, `portrait`, `story`, `reel`, `tiktok`, `square`, or `4:3`, apply the matching dimensions from the **Orientation Mapping** rules instead of defaulting to 16:9.
 - Rewrite the user's request using the **LTX-2.3 Prompt Rule** before invoking the command. Do not send short slogan-style prompts to LTX.
 - Treat "4k" as a signal to use the highest practical LTX path exposed by this skill, even though the current wrapper caps non-WAN video dimensions at 2048px on the long side.
@@ -773,6 +930,9 @@ On error (with `--json`), the script returns a single JSON object like:
   "success": false,
   "error": "Reference image 2314x1200 would resize to 512x266, but both dimensions must be divisible by 16.",
   "errorCode": "INVALID_VIDEO_SIZE",
+  "errorType": "PARAMETER_INVALID",
+  "errorCategory": "schema_validation",
+  "retryable": false,
   "hint": "Try: --width 1296 --height 672 (or omit --strict-size)"
 }
 ```
@@ -944,7 +1104,7 @@ node {{skillDir}}/sogni-agent.mjs --angles-360 -c subject.jpg "same subject"
 
 ## Troubleshooting
 
-- **Auth errors**: Check `SOGNI_API_KEY` or the credentials in `~/.config/sogni/credentials`
+- **Auth errors**: Check `SOGNI_API_KEY` or the API key in `~/.config/sogni/credentials`
 - **i2v sizing gotchas**: Video sizes are model-specific. WAN uses min 480px, max 1536px, divisible by 16. LTX uses divisible-by-64 dimensions, and the current wrapper caps non-WAN video dimensions at 2048px on the long side. For i2v, the client wrapper resizes the reference (`fit: inside`) and uses the resized dimensions as the final video size. Because this uses rounding, a requested size can still yield an invalid final size.
 - **Auto-adjustment**: With a local `--ref`, the script will auto-adjust the requested size to avoid resized reference dimensions that miss the model divisor.
 - **If the script adjusts your size but you want to fail instead**: pass `--strict-size` and it will print a suggested `--width/--height`.