@sogni-ai/sogni-creative-agent-skill 3.3.4 → 3.4.0

package/README.md

@@ -70,14 +70,23 @@ With this skill, an agent can:
 ## Quick Start
 
 1. Get a Sogni API key from [dashboard.sogni.ai](https://dashboard.sogni.ai) (open the account menu) and save it — see [Setup](#setup-sogni-api-key).
-2. Install the CLI:
+2. Install (one command):
+
+   ```bash
+   npx setup-sogni-agent-skill
+   ```
+
+   This auto-detects Claude Code, Codex CLI, and Hermes; installs the CLI globally;
+   registers the skill into each detected runtime; and prompts for your API key.
+
+   Prefer to do it manually? Install the CLI directly:
 
    ```bash
    npm install -g @sogni-ai/sogni-creative-agent-skill@latest
    sogni-agent --version
    ```
 
-3. Point your agent runtime at this repository's [`SKILL.md`](./SKILL.md).
+   Then point your agent runtime at this repository's [`SKILL.md`](./SKILL.md).
 
 Then ask your agent to do something:
 
@@ -133,6 +142,8 @@ openclaw plugins install sogni-creative-agent-skill
 
 The installed plugin loads its behavior from [`SKILL.md`](./SKILL.md) via [`openclaw.plugin.json`](./openclaw.plugin.json).
 
+> **API key under OpenClaw:** the plugin config holds non-secret defaults only (models, timeouts, paths) — it does **not** carry your API key. Provide `SOGNI_API_KEY` via the environment the OpenClaw gateway passes to the CLI, or save it to `~/.config/sogni/credentials` (`SOGNI_API_KEY=<your-key>`). This keeps your key out of plugin config files.
+
 For a local checkout that you want to update continuously, link the minimal OpenClaw surface (`.openclaw-link/`) — not the repository root, which contains development tests that OpenClaw correctly blocks during plugin safety scanning:
 
 ```bash
@@ -322,9 +333,9 @@ sogni-agent --api-workflow storyboard-video "10s neon city flyover"
 
 # Local segment + concat with external soundtrack
 sogni-agent --video --workflow v2v --ref-video dance.mp4 \
-  --video-start 10 --duration 8 --controlnet-name pose -o /tmp/clip-2.mp4 \
+  --video-start 10 --duration 8 --controlnet-name pose -o ./clip-2.mp4 \
   "robot dancing"
-sogni-agent --concat-videos /tmp/final.mp4 /tmp/clip-1.mp4 /tmp/clip-2.mp4 \
+sogni-agent --concat-videos ./final.mp4 ./clip-1.mp4 ./clip-2.mp4 \
   --concat-audio song.mp3 --concat-audio-start 0
 
 # Balances and help
@@ -451,7 +462,7 @@ LTX-2.3 prompt: "A medium cinematic shot frames a woman in her 30s standing in a
 
 ## Photobooth (Face Transfer)
 
-Generate stylized portraits from a face photo using InstantID ControlNet:
+Generate new stylized portraits from a face photo using InstantID ControlNet:
 
 ```bash
 sogni-agent --photobooth --ref face.jpg "80s fashion portrait"
@@ -460,6 +471,8 @@ sogni-agent --photobooth --ref face.jpg -n 4 "LinkedIn professional headshot"
 
 Uses SDXL Turbo (`coreml-sogniXLturbo_alpha1_ad`) at 1024×1024 by default. The face image is passed via `--ref` and styled by the prompt. Cannot be combined with `--video` or `-c` / `--context`.
 
+`--photobooth` is face-reference generation, not full-image editing. If the request is "same image, different style" — for example an anime version that must keep the same face, pose, clothing, background, framing, and composition — use Qwen image editing with `-c/--context` instead.
+
 Multi-angle mode (`--multi-angle` / `--angles-360`) auto-builds the `<sks>` prompt and applies the `multiple_angles` LoRA. `--angles-360-video` generates i2v clips between consecutive angles (including last → first) and concatenates them with `ffmpeg` into a seamless loop.
 
 `--balance` / `--balances` does not require a prompt and prints current `SPARK` and `SOGNI` balances before exiting.
@@ -577,7 +590,7 @@ Use `--token-type auto` to retry native Sogni models with SOGNI tokens when SPAR
 sogni-agent --token-type auto "a dragon eating tacos"
 ```
 
-Tries SPARK first (free daily tokens), then falls back to SOGNI if the balance is too low. Vendor models such as Seedance and GPT Image 2 require Premium Spark eligibility and never use SOGNI fallback.
+Tries SPARK first, then falls back to SOGNI if the balance is too low. Vendor models such as Seedance and GPT Image 2 require Premium Spark eligibility and never use SOGNI fallback. If usable balance is still insufficient, buy Spark Packs at https://docs.sogni.ai/pricing/#spark-packs.
 
 ---
 
@@ -632,6 +645,15 @@ Reusable workflow rules should come from the shared Sogni runtime before they ar
 
 Public-skill regex should stay limited to CLI argument/fact extraction such as file paths, URLs, extensions, dimensions, durations, and explicit positions. Hosted-style decisions such as latest-video continuation, uploaded-video modification, image-selection waits, stitch-after-batch state, and repair/control routing belong upstream in typed planner/runtime fields before they are synced here.
 
+### Execution boundaries: local CLI vs. hosted surfaces
+
+`sogni-agent.mjs` is a **local command-line tool** (`#!/usr/bin/env node`, the package `bin`). It is the only place that may assume a local filesystem and a local `ffmpeg`/`ffprobe` binary. Flags like `--concat-videos`, `--remix-audio`, `--extract-first-frame`, `--extract-last-frame`, and `--angles-360-video` shell out to ffmpeg behind `ensureFfmpegAvailable()` and run only when those flags are passed.
+
+Hosted surfaces — including the chat.sogni.ai web app — do **not** run `sogni-agent.mjs`. They consume `@sogni-ai/sogni-intelligence-client` and the hosted `/v1/chat/completions` and `/v1/creative-agent/workflows` APIs, where there is no local ffmpeg and no local filesystem. Therefore:
+
+- Keep ffmpeg- and filesystem-dependent helpers (frame extraction, concat, audio remux, media listing) **local to `sogni-agent.mjs`**. Do not move them into the shared runtime or `@sogni-ai/sogni-intelligence-client`, and never make hosted code paths depend on a local binary.
+- Server-side equivalents of these capabilities (e.g. `stitch_video`, `overlay_video`, `extend_video`) live in the hosted creative-agent tool surface and belong upstream, not in the CLI.
+
 Issues and feature requests: [github.com/Sogni-AI/sogni-creative-agent-skill/issues](https://github.com/Sogni-AI/sogni-creative-agent-skill/issues).
 
 ---

package/SKILL.md

@@ -2,7 +2,7 @@
 name: sogni-creative-agent-skill
 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, custom personality, style transfer, angle synthesis, Seedance/LTX/WAN video, music/lyrics, hosted chat, durable workflows, replay records, 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: "3.3.4"
+  version: "3.4.0"
   homepage: https://sogni.ai
   clawdbot:
     emoji: "🎨"
@@ -72,6 +72,10 @@ npm --prefix "$DEST" install
 
 If that checkout does not exist, prefer the npm-based local skill install below, or ask before cloning.
 
+## Uninstall Request Policy
+
+When a user asks to uninstall, run `npx setup-sogni-agent-skill --uninstall --remove-cli --purge`. This removes the skill files, the global CLI, and the user's data in `~/.config/sogni/` after backing it up to `~/.config/sogni.backup-<timestamp>.tar.gz`. Always tell the user the backup path and that it contains their API key. To keep their data, omit `--purge`.
+
 ## Setup
 
 1. **Get your Sogni API key** by logging into https://dashboard.sogni.ai and opening the account menu.
@@ -110,6 +114,18 @@ ln -sfn node_modules/@sogni-ai/sogni-creative-agent-skill sogni-creative-agent-s
 
 When this skill is distributed via ClawHub, it bootstraps its local runtime dependencies from `skill-package.json` during install. That avoids relying on a root `package.json` being present in the published skill artifact.
 
+## Output Path Convention
+
+**Always save generated images, videos, and music to the user's current working directory (PWD), not `/tmp`.** Pass a relative path or bare filename to `-o`/`--output`:
+
+```bash
+sogni-agent -o ./cat.png "a cat wearing a hat"       # ✓ lands in PWD
+sogni-agent -o cat.png "a cat wearing a hat"         # ✓ lands in PWD
+sogni-agent -o /tmp/cat.png "a cat wearing a hat"    # ✗ avoid — user can't easily find it
+```
+
+`/tmp` (and `mkdtempSync(...)`) is reserved internally for transient intermediate files the CLI cleans up itself (audio re-encodes, intermediate clips during stitching). Final renders the user is asking for must remain inside their working directory unless they explicitly request a different location.
+
 ## Filesystem Paths and Overrides
 
 Default file paths used by this skill:
@@ -172,8 +188,8 @@ sogni-agent --video --ref hero.png -n 3 --duration 5 \
 # Token auto-fallback for native Sogni models (tries SPARK, falls back to SOGNI)
 sogni-agent --token-type auto "a cat wearing a hat"
 
-# Save to file
-sogni-agent -o /tmp/cat.png "a cat wearing a hat"
+# Save to file (relative paths land in the current working directory)
+sogni-agent -o ./cat.png "a cat wearing a hat"
 
 # JSON output (for scripting)
 sogni-agent --json "a cat wearing a hat"
@@ -185,7 +201,7 @@ sogni-agent --balance
 sogni-agent --json --balance
 
 # Quiet mode (suppress progress)
-sogni-agent -q -o /tmp/cat.png "a cat wearing a hat"
+sogni-agent -q -o ./cat.png "a cat wearing a hat"
 
 # Direct music/audio generation
 sogni-agent --music --duration 30 \
@@ -451,9 +467,19 @@ positions.
 | `--strict-size` | Do not auto-adjust i2v video size for reference resizing constraints | false |
 | `-q, --quiet` | No progress output | false |
 | `--extract-last-frame <video> <image>` | Extract last frame from video (safe ffmpeg wrapper) | - |
-| `--concat-videos <out> <clips...>` | Concatenate video clips (safe ffmpeg wrapper) | - |
+| `--extract-first-frame <video> <image>` | Extract first frame from video (safe ffmpeg wrapper) | - |
+| `--concat-videos <out> <clips...>` | Concatenate video clips; normalizes fps/size and fills silent audio so mismatched clips stitch cleanly (safe ffmpeg wrapper) | - |
+| `--concat-fps <n>` | Override target fps for `--concat-videos` | highest clip fps |
 | `--concat-audio <path>` | Optional audio track to mux over `--concat-videos` output | - |
 | `--concat-audio-start <sec>` | Start offset into `--concat-audio` | - |
+| `--remix-audio <in> <out>` | Rebuild a video's audio (loop/fade/mix) without re-encoding video (safe ffmpeg wrapper) | - |
+| `--bed-audio <path>` | Audio bed for `--remix-audio` (path or video; defaults to input's own audio) | - |
+| `--audio-loop` | Loop the bed to cover the full video duration (`--remix-audio`) | false |
+| `--audio-fade-in <sec>` | Fade the bed in over `<sec>` (`--remix-audio`) | - |
+| `--audio-fade-out <sec>` | Fade the bed out over `<sec>` at the tail (`--remix-audio`) | - |
+| `--mix-audio <path>` | Overlay one extra audio track, mixed with the bed (`--remix-audio`) | - |
+| `--mix-at <sec>` | Start offset for `--mix-audio` | 0 |
+| `--mix-gain <db>` | Gain in dB applied to `--mix-audio` | 0 |
 | `--list-media [type]` | List recent inbound media (images\|audio\|all) | images |
 | `--api-chat` | Call OpenAI-compatible `/v1/chat/completions`; CLI default sends the hosted `creative-agent` tool surface | - |
 | `--durable-chat` | Start and stream a durable `/v1/chat/runs` record through SDK transport; requires `SOGNI_SKILL_USE_SDK_TRANSPORT=1` | - |
@@ -653,9 +679,17 @@ sogni-agent --last-image "make it more vibrant"
 
 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.
 
+Use context-image editing for source-preserving edits. If the user says "use this image as the base", "keep everything the same", "only change the style", "anime version of this image", or asks to preserve pose, clothing, background, framing, or composition, use `-c/--context` with a Qwen image edit model instead of `--photobooth`. For stronger preservation than the lightning default, prefer:
+
+```bash
+sogni-agent -c photo.jpg -m qwen_image_edit_2511_fp8 "turn this into anime style; keep the same face, pose, clothing, background, framing, and composition"
+```
+
 ## Photobooth (Face Transfer)
 
-Generate stylized portraits from a face photo using InstantID ControlNet. When a user mentions "photobooth", wants a stylized portrait of themselves, or asks to transfer their face into a style, use `--photobooth` with `--ref` pointing to their face image.
+Generate new stylized portraits from a face photo using InstantID ControlNet. Use `--photobooth` with `--ref` when the user explicitly asks for photobooth/face-transfer mode, wants a new portrait or headshot based on their face, or asks to place their face identity into a different portrait concept.
+
+Do not use `--photobooth` for full-image style edits where the original photo must stay intact. `--photobooth` treats the input as a face reference, not as a base image, so it can change pose, clothing, background, framing, and composition. For "same image, different style" requests, route to Qwen context editing with `-c/--context`.
 
 ```bash
 # Basic photobooth
@@ -673,10 +707,10 @@ Uses SDXL Turbo (`coreml-sogniXLturbo_alpha1_ad`) at 1024x1024 by default. The f
 **Agent usage:**
 ```bash
 # Photobooth: stylize a face photo
-sogni-agent -q --photobooth --ref /path/to/face.jpg -o /tmp/stylized.png "80s fashion portrait"
+sogni-agent -q --photobooth --ref /path/to/face.jpg -o ./stylized.png "80s fashion portrait"
 
 # Multiple photobooth outputs
-sogni-agent -q --photobooth --ref /path/to/face.jpg -n 4 -o /tmp/stylized.png "LinkedIn professional headshot"
+sogni-agent -q --photobooth --ref /path/to/face.jpg -n 4 -o ./stylized.png "LinkedIn professional headshot"
 ```
 
 ## Multiple Angles (Turnaround)
@@ -695,7 +729,7 @@ sogni-agent --angles-360 -c subject.jpg --distance medium --elevation eye-level
   "studio portrait, same person"
 
 # 360 sweep video (looping mp4, uses i2v between angles; requires ffmpeg)
-sogni-agent --angles-360 --angles-360-video /tmp/turntable.mp4 \
+sogni-agent --angles-360 --angles-360-video ./turntable.mp4 \
   -c subject.jpg --distance medium --elevation eye-level \
   "studio portrait, same person"
 ```
@@ -725,14 +759,14 @@ When a user requests a "360 video", follow this workflow:
 
 4. **Example command**:
    ```bash
-   sogni-agent --angles-360 --angles-360-video /tmp/output.mp4 \
+   sogni-agent --angles-360 --angles-360-video ./output.mp4 \
      -c /path/to/image.png --elevation eye-level --distance medium \
      "description of subject"
    ```
 
 ### Transition Video Rule
 
-For **any transition video work**, always use the **Sogni skill/plugin** (not raw ffmpeg or other shell commands). Use the built-in `--extract-last-frame`, `--concat-videos`, and `--looping` flags for video manipulation.
+For **any transition video work**, always use the **Sogni skill/plugin** (not raw ffmpeg or other shell commands). Use the built-in `--extract-last-frame`, `--extract-first-frame`, `--concat-videos`, `--remix-audio`, and `--looping` flags for video and audio manipulation.
 
 ### Insufficient Funds Handling
 
@@ -740,7 +774,9 @@ Use `--token-type auto` to automatically retry native Sogni models with SOGNI to
 
 When you see **"Debit Error: Insufficient funds"** even with auto-fallback, reply:
 
-"Insufficient funds. Claim 50 free daily Spark points at https://app.sogni.ai/"
+"Insufficient funds. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
+
+Do not collect payment details, quote a custom price, or simulate a purchase in the terminal.
 
 ## Video Generation
 
@@ -865,10 +901,11 @@ sogni-agent --json --list-media images
 
 **Do NOT use `ls`, `cp`, or other shell commands to browse user files.** Always use `--list-media` to find inbound media.
 
-## IMPORTANT KEYWORD RULE
+## Photobooth Routing Rule
 
-- If the user message includes the word "photobooth" (case-insensitive), always use `--photobooth` mode with `--ref` set to the user-provided face image.
-- Prioritize this rule over generic image-edit flows (`-c`) for that request.
+- If the user explicitly asks to use "photobooth", "photobooth path", or "face transfer", use `--photobooth` with `--ref` set to the user-provided face image.
+- If the same request also requires preserving the whole source image (same pose, clothes, background, framing, composition, or "keep everything the same"), explain that photobooth is face-reference generation and prefer Qwen context editing unless the user insists on photobooth.
+- Do not route to `--photobooth` merely because the user asks to preserve a face in a style edit. Face-preserving full-image edits should use `-c/--context` with Qwen image edit.
 
 ## LTX-2.3 Prompt Rule
 
@@ -929,35 +966,35 @@ When user asks to generate/draw/create an image:
 
 ```bash
 # Generate and save locally (use -Q for quality presets instead of memorizing model IDs)
-sogni-agent -q -Q fast -o /tmp/generated.png "user's prompt"
-sogni-agent -q -Q pro -o /tmp/generated.png "user's prompt"
+sogni-agent -q -Q fast -o ./generated.png "user's prompt"
+sogni-agent -q -Q pro -o ./generated.png "user's prompt"
 
 # Generate with prompt variations (diverse images in one call)
-sogni-agent -q -n 3 -o /tmp/cars.png "a {red|blue|green} sports car"
+sogni-agent -q -n 3 -o ./cars.png "a {red|blue|green} sports car"
 
 # Edit an existing image
-sogni-agent -q -c /path/to/input.jpg -o /tmp/edited.png "make it pop art style"
+sogni-agent -q -c /path/to/input.jpg -o ./edited.png "make it pop art style"
 
 # Generate video from image
-sogni-agent -q --video --ref /path/to/image.png -o /tmp/video.mp4 "A medium shot holds on the subject in soft late-afternoon light as fabric edges and background details remain clear and stable. The camera performs a slow push-in while the subject shifts weight subtly and turns slightly toward the lens, keeping the motion gentle and continuous. Leaves rustle softly in the background and the scene maintains smooth cinematic movement with no abrupt action changes."
+sogni-agent -q --video --ref /path/to/image.png -o ./video.mp4 "A medium shot holds on the subject in soft late-afternoon light as fabric edges and background details remain clear and stable. The camera performs a slow push-in while the subject shifts weight subtly and turns slightly toward the lens, keeping the motion gentle and continuous. Leaves rustle softly in the background and the scene maintains smooth cinematic movement with no abrupt action changes."
 
 # Generate text-to-video
-sogni-agent -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."
+sogni-agent -q --video -o ./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
-sogni-agent -q --music --duration 30 -o /tmp/music.mp3 "uplifting cinematic synthwave theme for a product launch"
+sogni-agent -q --music --duration 30 -o ./music.mp3 "uplifting cinematic synthwave theme for a product launch"
 
 # HD / "4K" text-to-video: prefer LTX-2.3
-sogni-agent -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."
+sogni-agent -q --video -m ltx23-22b-fp8_t2v_distilled -w 1920 -h 1088 -o ./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."
 
 # HD / "4K" image-to-video: prefer LTX i2v
-sogni-agent -q --video --ref /path/to/image.png -m ltx23-22b-fp8_i2v_distilled -w 1920 -h 1088 -o /tmp/video.mp4 "A medium cinematic shot holds on the scene with clean subject separation and stable environmental detail as directional light shapes the surfaces and background depth. The camera performs a slow push-in while the main subject makes one subtle continuous movement, keeping posture and identity consistent from start to finish. Ambient motion in the background stays gentle and the overall clip remains smooth, stabilized, and visually coherent."
+sogni-agent -q --video --ref /path/to/image.png -m ltx23-22b-fp8_i2v_distilled -w 1920 -h 1088 -o ./video.mp4 "A medium cinematic shot holds on the scene with clean subject separation and stable environmental detail as directional light shapes the surfaces and background depth. The camera performs a slow push-in while the main subject makes one subtle continuous movement, keeping posture and identity consistent from start to finish. Ambient motion in the background stays gentle and the overall clip remains smooth, stabilized, and visually coherent."
 
 # Photobooth: stylize a face photo
-sogni-agent -q --photobooth --ref /path/to/face.jpg -o /tmp/stylized.png "80s fashion portrait"
+sogni-agent -q --photobooth --ref /path/to/face.jpg -o ./stylized.png "80s fashion portrait"
 
 # Token auto-fallback for native Sogni models (tries SPARK first, retries with SOGNI on insufficient balance)
-sogni-agent -q --token-type auto -o /tmp/generated.png "user's prompt"
+sogni-agent -q --token-type auto -o ./generated.png "user's prompt"
 
 # Check current SPARK/SOGNI balances (no prompt required)
 sogni-agent --json --balance
@@ -1005,7 +1042,7 @@ If clips need different source images, end frames, durations, audio windows, or
 
 ### Token Auto-Fallback
 
-Use `--token-type auto` when the user's SPARK balance might be low. It tries SPARK first (free daily tokens) and automatically retries with SOGNI if insufficient.
+Use `--token-type auto` when the user's SPARK balance might be low. It tries SPARK first and automatically retries with SOGNI if insufficient.
 
 ## High-Res Video Routing
 
@@ -1020,7 +1057,7 @@ When the user asks for video in **"hd"**, **"1080p"**, **"4k"**, **"uhd"**, or *
 - 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.
 
-**Security:** Agents must use the CLI's built-in flags (`--extract-last-frame`, `--concat-videos`, `--list-media`) for all file operations and video manipulation. Never run raw shell commands (`ffmpeg`, `ls`, `cp`, etc.) directly.
+**Security:** Agents must use the CLI's built-in flags (`--extract-last-frame`, `--extract-first-frame`, `--concat-videos`, `--remix-audio`, `--list-media`) for all file operations and video/audio manipulation. Never run raw shell commands (`ffmpeg`, `ls`, `cp`, etc.) directly.
 
 ## Animate Between Two Images (First-Frame / Last-Frame)
 
@@ -1028,7 +1065,7 @@ When a user asks to **animate between two images**, use `--ref` (first frame) an
 
 ```bash
 # Animate from image A to image B
-sogni-agent -q --video --ref /tmp/imageA.png --ref-end /tmp/imageB.png -o /tmp/transition.mp4 "descriptive prompt of the transition"
+sogni-agent -q --video --ref ./imageA.png --ref-end ./imageB.png -o ./transition.mp4 "descriptive prompt of the transition"
 ```
 
 ### Animate a Video to an Image (Scene Continuation)
@@ -1037,15 +1074,15 @@ When a user asks to **animate from a video to an image** (or "continue" a video
 
 1. **Extract the last frame** of the existing video using the built-in safe wrapper:
    ```bash
-   sogni-agent --extract-last-frame /tmp/existing.mp4 /tmp/lastframe.png
+   sogni-agent --extract-last-frame ./existing.mp4 ./lastframe.png
    ```
 2. **Generate a new video** using the last frame as `--ref` and the target image as `--ref-end`:
    ```bash
-   sogni-agent -q --video --ref /tmp/lastframe.png --ref-end /tmp/target.png -o /tmp/continuation.mp4 "scene transition prompt"
+   sogni-agent -q --video --ref ./lastframe.png --ref-end ./target.png -o ./continuation.mp4 "scene transition prompt"
    ```
 3. **Concatenate the videos** using the built-in safe wrapper:
    ```bash
-   sogni-agent --concat-videos /tmp/full_sequence.mp4 /tmp/existing.mp4 /tmp/continuation.mp4
+   sogni-agent --concat-videos ./full_sequence.mp4 ./existing.mp4 ./continuation.mp4
    ```
 
 This ensures visual continuity — the new clip picks up exactly where the previous one ended.
@@ -1059,6 +1096,50 @@ When the final stitched output needs a single external soundtrack, add `--concat
 - User says "animate this video to this image" → extract last frame, use as `--ref`, target image as `--ref-end`, then stitch
 - User says "continue this video" with a target image → same as above
 
+### Transition Between Two Videos (Bridge Clip)
+
+When a user asks to **create a transition between two existing videos** (A → B), bridge them with a generated clip anchored on both boundary frames:
+
+1. **Extract the last frame of video A** and the **first frame of video B**:
+   ```bash
+   sogni-agent --extract-last-frame ./videoA.mp4 ./A_last.png
+   sogni-agent --extract-first-frame ./videoB.mp4 ./B_first.png
+   ```
+2. **Generate the transition** with i2v, anchoring start→end so both seams are clean. Match `--fps` to the surrounding clips:
+   ```bash
+   sogni-agent -q --video -m wan_v2.2-14b-fp8_i2v_lightx2v \
+     --ref ./A_last.png --ref-end ./B_first.png --fps 24 \
+     -o ./transition.mp4 "descriptive morph between the two scenes"
+   ```
+3. **Concatenate A → transition → B**:
+   ```bash
+   sogni-agent --concat-videos ./merged.mp4 ./videoA.mp4 ./transition.mp4 ./videoB.mp4
+   ```
+
+> **i2v clips are silent and use the model's own frame rate** (often not 24). `--concat-videos` now normalizes fps/size and fills silent audio automatically, so mismatched clips stitch correctly — but passing `--fps` to the transition generation keeps things clean from the start. Use `--concat-fps <n>` to force a specific output frame rate.
+
+### Remix / Layer Audio After Stitching
+
+After concatenating, use `--remix-audio` to rebuild the audio track **without re-encoding the video** (it is stream-copied, so it is fast and lossless on the picture). Combine the audio flags:
+
+```bash
+# Loop one clip's audio across the whole merged video and fade it out at the end
+sogni-agent --remix-audio ./merged.mp4 ./final.mp4 \
+  --bed-audio ./clip1.mp4 --audio-loop --audio-fade-out 2
+
+# Same, but also layer a second clip's original audio back in starting at 18s
+sogni-agent --remix-audio ./merged.mp4 ./final.mp4 \
+  --bed-audio ./clip1.mp4 --audio-loop --audio-fade-out 2 \
+  --mix-audio ./clip3.mp4 --mix-at 18.01 --mix-gain -3
+```
+
+- `--bed-audio` accepts a video or audio file; if omitted, the input video's own audio is the bed.
+- `--audio-loop` loops the bed to cover the full video; `--audio-fade-in` / `--audio-fade-out` fade it.
+- `--mix-audio` overlays one extra track (mixed at full level with a peak limiter so it never clips); position it with `--mix-at` and adjust level with `--mix-gain` (dB).
+- To mix more than two layers, chain `--remix-audio` passes (each only re-encodes audio).
+
+**Do NOT run raw `ffmpeg` commands** for any of this. Use `--extract-first-frame`, `--extract-last-frame`, `--concat-videos`, and `--remix-audio`.
+
 ## JSON Output
 
 ```json
@@ -1069,7 +1150,7 @@ When the final stitched output needs a single external soundtrack, add `--concat
   "width": 512,
   "height": 512,
   "urls": ["https://..."],
-  "localPath": "/tmp/cat.png"
+  "localPath": "./cat.png"
 }
 ```
 
@@ -1122,7 +1203,7 @@ sogni-agent --persona-list --json
 sogni-agent --persona-resolve "me" --json
 
 # Generate using a persona (auto-injects photo as context)
-sogni-agent --persona "Mark" -o /tmp/hero.png "superhero in dramatic lighting"
+sogni-agent --persona "Mark" -o ./hero.png "superhero in dramatic lighting"
 
 # Remove a persona
 sogni-agent --persona-remove "Mark"
@@ -1183,13 +1264,13 @@ Apply artistic styles to existing images:
 
 ```bash
 # Apply a named artist style
-sogni-agent -c photo.jpg -o /tmp/styled.png "Apply style: Andy Warhol pop art with bold primary colors"
+sogni-agent -c photo.jpg -o ./styled.png "Apply style: Andy Warhol pop art with bold primary colors"
 
 # Studio Ghibli transformation
-sogni-agent -c photo.jpg -o /tmp/ghibli.png "Apply style: Studio Ghibli watercolor with soft pastel sky and lush greenery"
+sogni-agent -c photo.jpg -o ./ghibli.png "Apply style: Studio Ghibli watercolor with soft pastel sky and lush greenery"
 
 # For photos with people, always preserve identity
-sogni-agent -c portrait.jpg -o /tmp/styled.png "Apply style: oil painting in the style of Vermeer. Preserve all facial features, expressions, and identity."
+sogni-agent -c portrait.jpg -o ./styled.png "Apply style: oil painting in the style of Vermeer. Preserve all facial features, expressions, and identity."
 ```
 
 **Tips:** Reference artists and styles BY NAME for best results. Use positive phrasing. For photos with people, always append identity preservation instructions.

package/generated/creative-agent-runtime.mjs

@@ -556,7 +556,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "edit_image.cost_limit_exceeded",
@@ -565,7 +565,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "restore_photo.cost_limit_exceeded",
@@ -574,7 +574,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "apply_style.cost_limit_exceeded",
@@ -583,7 +583,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "refine_result.cost_limit_exceeded",
@@ -592,7 +592,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "animate_photo.cost_limit_exceeded",
@@ -601,7 +601,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "change_angle.cost_limit_exceeded",
@@ -610,7 +610,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "generate_video.cost_limit_exceeded",
@@ -619,7 +619,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "sound_to_video.cost_limit_exceeded",
@@ -628,7 +628,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "video_to_video.cost_limit_exceeded",
@@ -637,7 +637,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "generate_music.cost_limit_exceeded",
@@ -646,7 +646,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "extend_video.cost_limit_exceeded",
@@ -655,7 +655,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "replace_video_segment.cost_limit_exceeded",
@@ -664,7 +664,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "overlay_video.cost_limit_exceeded",
@@ -673,7 +673,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "add_subtitles.cost_limit_exceeded",
@@ -682,7 +682,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "stitch_video.cost_limit_exceeded",
@@ -691,7 +691,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "orbit_video.cost_limit_exceeded",
@@ -700,7 +700,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "dance_montage.cost_limit_exceeded",
@@ -709,7 +709,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "generate_image.asset_not_found",
@@ -2550,6 +2550,38 @@ const PROMPT_CONTRACTS = [
 // '../public-skill-runtime/index.js' (and downstream consumers that still
 // reference the creative-agent subpath) keep working unchanged.
 export * from '@sogni-ai/sogni-intelligence-client/public-skill-runtime';
+
+// PUBLIC_SKILL_SPARK_PACKS_COST_LIMIT_OVERRIDE
+import {
+  PUBLIC_SKILL_DEFAULT_POLICIES as SOGNI_PUBLIC_SKILL_DEFAULT_POLICIES,
+  PUBLIC_SKILL_DEFAULT_PROMPT_CONTRACTS as SOGNI_PUBLIC_SKILL_DEFAULT_PROMPT_CONTRACTS,
+  PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES as SOGNI_PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES,
+  createPublicSkillContractRuntime as createSogniPublicSkillContractRuntime,
+} from '@sogni-ai/sogni-intelligence-client/public-skill-runtime';
+
+export const PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES = SOGNI_PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES.map((recipe) =>
+  recipe.errorCode === 'COST_LIMIT_EXCEEDED'
+    ? { ...recipe, message: "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs" }
+    : recipe
+);
+
+export function createPublicSkillDefaultContractRuntime(input = {}) {
+  return createSogniPublicSkillContractRuntime({
+    policies: [
+      ...SOGNI_PUBLIC_SKILL_DEFAULT_POLICIES,
+      ...(input.policies ?? []),
+    ],
+    promptContracts: [
+      ...SOGNI_PUBLIC_SKILL_DEFAULT_PROMPT_CONTRACTS,
+      ...(input.promptContracts ?? []),
+    ],
+    repairRecipes: [
+      ...PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES,
+      ...(input.repairRecipes ?? []),
+    ],
+  });
+}
+
 // Moved to @sogni-ai/sogni-intelligence-client/skill-runtime-source in Phase 8.4 follow-up.
 // This file is kept as a thin re-export so existing internal `testing/`
 // callers keep working. New code should import from the public mid-tier: