cue-ai 0.9.2 → 0.9.4

package/resources/skills/skills/design/banana/scripts/setup_mcp.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+Setup script for Banana Claude MCP server in Claude Code.
+
+Configures @ycse/nanobanana-mcp in Claude Code's settings.json
+with the user's Google AI API key.
+
+Usage:
+    python3 setup_mcp.py                    # Interactive (prompts for key)
+    python3 setup_mcp.py --key YOUR_KEY     # Non-interactive
+    python3 setup_mcp.py --check            # Verify existing setup
+    python3 setup_mcp.py --remove           # Remove MCP config
+    python3 setup_mcp.py --help             # Show usage
+"""
+
+import json
+import sys
+import os
+from pathlib import Path
+
+SETTINGS_PATH = Path.home() / ".claude" / "settings.json"
+MCP_NAME = "nanobanana-mcp"
+MCP_PACKAGE = "@ycse/nanobanana-mcp"
+DEFAULT_MODEL = "gemini-3.1-flash-image-preview"
+
+
+def load_settings() -> dict:
+    """Load Claude Code settings.json."""
+    if not SETTINGS_PATH.exists():
+        return {}
+    with open(SETTINGS_PATH, "r") as f:
+        return json.load(f)
+
+
+def save_settings(settings: dict) -> None:
+    """Save Claude Code settings.json."""
+    SETTINGS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(SETTINGS_PATH, "w") as f:
+        json.dump(settings, f, indent=2)
+    print(f"Settings saved to {SETTINGS_PATH}")
+
+
+def check_setup() -> bool:
+    """Check if MCP is already configured."""
+    settings = load_settings()
+    servers = settings.get("mcpServers", {})
+    if MCP_NAME in servers:
+        env = servers[MCP_NAME].get("env", {})
+        key = env.get("GOOGLE_AI_API_KEY", "")
+        masked = key[:8] + "..." + key[-4:] if len(key) > 12 else "(not set)"
+        print(f"MCP server '{MCP_NAME}' is configured.")
+        print(f"  Package: {MCP_PACKAGE}")
+        print(f"  API Key: {masked}")
+        print(f"  Model:   {env.get('NANOBANANA_MODEL', DEFAULT_MODEL)}")
+        return True
+    print(f"MCP server '{MCP_NAME}' is NOT configured.")
+    return False
+
+
+def remove_mcp() -> None:
+    """Remove MCP configuration."""
+    settings = load_settings()
+    servers = settings.get("mcpServers", {})
+    if MCP_NAME in servers:
+        del servers[MCP_NAME]
+        settings["mcpServers"] = servers
+        save_settings(settings)
+        print(f"Removed '{MCP_NAME}' from Claude Code settings.")
+    else:
+        print(f"'{MCP_NAME}' not found in settings.")
+
+
+def setup_mcp(api_key: str) -> None:
+    """Configure MCP server in Claude Code settings."""
+    if not api_key or not api_key.strip():
+        print("Error: API key cannot be empty.")
+        sys.exit(1)
+
+    api_key = api_key.strip()
+    settings = load_settings()
+
+    if "mcpServers" not in settings:
+        settings["mcpServers"] = {}
+
+    settings["mcpServers"][MCP_NAME] = {
+        "command": "npx",
+        "args": ["-y", MCP_PACKAGE],
+        "env": {
+            "GOOGLE_AI_API_KEY": api_key,
+            "NANOBANANA_MODEL": DEFAULT_MODEL,
+        },
+    }
+
+    save_settings(settings)
+    print(f"\nMCP server '{MCP_NAME}' configured successfully!")
+    print(f"  Package: {MCP_PACKAGE}")
+    print(f"  Model:   {DEFAULT_MODEL}")
+    print(f"\nRestart Claude Code for changes to take effect.")
+    print(f"Generated images will be saved to: ~/Documents/nanobanana_generated/")
+
+
+def main() -> None:
+    args = sys.argv[1:]
+
+    if "--help" in args or "-h" in args:
+        print("Usage: python3 setup_mcp.py [OPTIONS]")
+        print()
+        print("Options:")
+        print("  --key KEY        Provide API key non-interactively")
+        print("  --check          Verify existing setup")
+        print("  --remove         Remove MCP configuration")
+        print("  --help, -h       Show this help message")
+        print()
+        print("Get a free API key at: https://aistudio.google.com/apikey")
+        sys.exit(0)
+
+    if "--check" in args:
+        check_setup()
+        return
+
+    if "--remove" in args:
+        remove_mcp()
+        return
+
+    # Get API key
+    api_key = None
+    for i, arg in enumerate(args):
+        if arg == "--key" and i + 1 < len(args):
+            api_key = args[i + 1]
+            break
+
+    if not api_key:
+        # Check environment
+        api_key = os.environ.get("GOOGLE_AI_API_KEY")
+
+    if not api_key:
+        print("Banana Claude -- MCP Setup")
+        print("=" * 40)
+        print(f"\nGet your free API key at: https://aistudio.google.com/apikey")
+        print()
+        try:
+            api_key = input("Enter your Google AI API key: ")
+        except (EOFError, KeyboardInterrupt):
+            print("\nError: No input received. Provide a key with --key or set GOOGLE_AI_API_KEY env var.")
+            sys.exit(1)
+
+    setup_mcp(api_key)
+
+
+if __name__ == "__main__":
+    main()

package/resources/skills/skills/design/banana/scripts/validate_setup.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+Validate that the Banana Claude MCP server is properly configured.
+
+Checks:
+1. Claude Code settings.json has the MCP entry
+2. API key is present
+3. Node.js/npx is available
+4. Output directory exists or can be created
+
+Usage:
+    python3 validate_setup.py
+"""
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+SETTINGS_PATH = Path.home() / ".claude" / "settings.json"
+MCP_NAME = "nanobanana-mcp"
+OUTPUT_DIR = Path.home() / "Documents" / "nanobanana_generated"
+
+
+def check(label: str, passed: bool, detail: str = "") -> bool:
+    status = "PASS" if passed else "FAIL"
+    msg = f"  [{status}] {label}"
+    if detail:
+        msg += f" -- {detail}"
+    print(msg)
+    return passed
+
+
+def main() -> int:
+    print("Banana Claude -- Setup Validation")
+    print("=" * 40)
+    results = []
+
+    # 1. Settings file exists
+    results.append(check(
+        "Claude Code settings.json exists",
+        SETTINGS_PATH.exists(),
+        str(SETTINGS_PATH),
+    ))
+
+    if not SETTINGS_PATH.exists():
+        print("\nCannot continue without settings.json.")
+        return 1
+
+    # 2. Load and parse settings
+    try:
+        with open(SETTINGS_PATH) as f:
+            settings = json.load(f)
+        results.append(check("settings.json is valid JSON", True))
+    except json.JSONDecodeError as e:
+        results.append(check("settings.json is valid JSON", False, str(e)))
+        return 1
+
+    # 3. MCP entry exists
+    servers = settings.get("mcpServers", {})
+    has_mcp = MCP_NAME in servers
+    results.append(check(f"MCP server '{MCP_NAME}' configured", has_mcp))
+
+    if has_mcp:
+        mcp = servers[MCP_NAME]
+
+        # 4. Command is npx
+        results.append(check(
+            "Command is 'npx'",
+            mcp.get("command") == "npx",
+            mcp.get("command", "(missing)"),
+        ))
+
+        # 5. Package is correct
+        args = mcp.get("args", [])
+        has_pkg = "@ycse/nanobanana-mcp" in args
+        results.append(check(
+            "Package is @ycse/nanobanana-mcp",
+            has_pkg,
+            str(args),
+        ))
+
+        # 6. API key present
+        env = mcp.get("env", {})
+        key = env.get("GOOGLE_AI_API_KEY", "")
+        results.append(check(
+            "GOOGLE_AI_API_KEY is set",
+            bool(key),
+            f"{key[:8]}...{key[-4:]}" if len(key) > 12 else "(empty or short)",
+        ))
+
+        # 7. Model configured
+        model = env.get("NANOBANANA_MODEL", "")
+        results.append(check(
+            "NANOBANANA_MODEL is set",
+            bool(model),
+            model or "(not set, will use package default)",
+        ))
+
+    # 8. Node.js/npx available
+    has_npx = shutil.which("npx") is not None
+    results.append(check(
+        "npx is available in PATH",
+        has_npx,
+        shutil.which("npx") or "not found",
+    ))
+
+    # 9. Output directory
+    if OUTPUT_DIR.exists():
+        results.append(check("Output directory exists", True, str(OUTPUT_DIR)))
+    else:
+        try:
+            OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+            results.append(check("Output directory created", True, str(OUTPUT_DIR)))
+        except OSError as e:
+            results.append(check("Output directory writable", False, str(e)))
+
+    # Summary
+    passed = sum(1 for r in results if r)
+    total = len(results)
+    print(f"\n{'=' * 40}")
+    print(f"Results: {passed}/{total} checks passed")
+
+    if passed == total:
+        print("Status: Ready to generate images!")
+        return 0
+    else:
+        print("Status: Some checks failed. Fix the issues above.")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/resources/skills/skills/gstack/ship/SKILL.md

@@ -1154,6 +1154,19 @@ Before reviewing code quality, check: **did they build what was requested — no
 
 Review the diff for structural issues that tests don't catch.
 
+0. **Supply-chain gate (Trivy, always first).** Run the `security/trivy-scan`
+   gate before the manual review. Code review does not catch a known CVE in a
+   transitive dependency, a committed secret, or a Dockerfile/IaC misconfig.
+
+   ```bash
+   trivy fs --scanners vuln,secret,misconfig --severity HIGH,CRITICAL --exit-code 1 --no-progress --skip-dirs "**/node_modules" --skip-dirs "**/_cache" --skip-dirs "**/dist" --skip-dirs "**/.next" --skip-dirs "**/vendor" .
+   ```
+
+   Exit 1 (HIGH/CRITICAL) is a **P0 ship blocker**: report the rows +
+   remediation and STOP, same as a critical review finding. Trivy missing →
+   install via `security/trivy-scan`'s `scripts/ensure-trivy.sh`; a gate that
+   could not run is a block, not a silent pass. Exit 0 → continue.
+
 1. Read `.claude/skills/review/checklist.md`. If the file cannot be read, **STOP** and report the error.
 
 2. Run `git diff origin/<base>` to get the full diff (scoped to feature changes against the freshly-fetched base branch).

package/resources/skills/skills/media/3d-logo-animation/SKILL.md

@@ -0,0 +1,59 @@
+---
+slug: muapi-3d-logo-animation
+name: muapi-3d-logo-animation
+version: "1.0.0"
+description: Transform a 2D logo into a premium 3D version and animate it with professional cinematic effects.
+acceptLicenseTerms: true
+---
+
+
+# 3D Logo Animation
+
+**Transform a 2D logo into a premium 3D version and animate it with professional cinematic effects.**
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|:---|:---|:---|:---|:---|
+| `logo_image` | image_url | yes | — | A clear 2D image of the logo to be converted to 3D. |
+| `material_style` | text | no | glossy glass and chrome | The material style for the 3D logo (e.g., gold, matte plastic, holographic). |
+
+
+## Steps
+
+### Phase A — 3D Logo Transformation
+
+If `{{logo_image}}` is not provided, ask the user to upload their logo.
+
+Once the logo is available, submit the plan with ONE step to convert it to 3D:
+
+1. **3D Logo Generation** — `muapi image edit` (model=`nano-banana-2-edit`):
+   - Reference Image: `{{logo_image}}`
+   - Prompt: `Transform this 2D logo into a premium, high-quality 3D version. The logo should have depth and be made of {{material_style}}. Smooth edges, realistic reflections, and professional studio lighting. The logo is centered on a clean, minimal, out-of-focus background. High-end graphic design aesthetic, 8k resolution.`
+   - Aspect ratio: 1:1 or 4:3
+
+Present the 3D logo to the user for approval.
+
+### Phase B — Cinematic Logo Animation
+
+Once the 3D logo is ready, submit the plan to animate it:
+
+1. **Logo Animation** — `muapi video from-image` (model=`veo3.1-fast-image-to-video`):
+   - Reference Image: The 3D logo from Phase A.
+   - Prompt: `A professional cinematic logo reveal animation. The 3D logo rotates slowly with dynamic light sweeps reflecting off its {{material_style}} surface. Subtle camera movement, particle effects in the background, high-quality motion graphics style.`
+   - Aspect ratio: 16:9 or 1:1
+
+After generation, present the final 3D logo animation to the user.
+
+## Trigger Keywords
+
+`3d logo`, `logo animation`, `2d to 3d logo`, `animated logo`, `cinematic logo`
+
+
+---
+
+## Notes for the Executing Agent
+
+- This recipe is LLM-orchestrated: read each phase, gather any missing inputs from the user, then call `muapi` CLI commands. Use `muapi auth configure` first if `MUAPI_API_KEY` is unset.
+- For model IDs without a CLI alias yet, fall back to the raw endpoint via `curl -X POST https://api.muapi.ai/api/v1/<endpoint> -H "x-api-key: $MUAPI_API_KEY" -H 'content-type: application/json' -d '{...}'` and poll with `muapi predict wait <request_id>`.
+- Substitute `{{input_name}}` placeholders with the user's actual inputs before issuing each call.

package/resources/skills/skills/media/action-figure-generator/SKILL.md

@@ -0,0 +1,48 @@
+---
+slug: muapi-action-figure-generator
+name: muapi-action-figure-generator
+version: "1.0.0"
+description: Convert a photo of a person into a custom 3D action figure, complete with collectible toy packaging.
+acceptLicenseTerms: true
+---
+
+
+# Action Figure Generator
+
+**Convert a photo of a person into a custom 3D action figure, complete with collectible toy packaging.**
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|:---|:---|:---|:---|:---|
+| `user_image` | image_url | yes | — | A clear photo of the person to be turned into an action figure. |
+| `toy_theme` | text | no | superhero | The theme of the action figure (e.g. superhero, doctor, explorer, sci-fi). |
+
+
+## Steps
+
+### Phase A — Action Figure Creation
+
+If `{{user_image}}` is not provided, ask the user to upload their photo.
+
+Once the photo is available, submit the plan with ONE step to generate the action figure:
+
+1. **Action Figure Generation** — `muapi image edit` (model=`nano-banana-2-edit`):
+   - Reference Image: `{{user_image}}`
+   - Prompt: `A high-quality 3D stylized action figure based on the person in the input image. The action figure should maintain the person's likeness (face, hairstyle, skin tone) but be rendered as a plastic toy with visible joints and a semi-glossy finish. The character is dressed in a {{toy_theme}} outfit. The figure is displayed inside its original collectible cardboard and plastic blister packaging. The packaging has the person's name printed on it and features clean, modern graphic design. Soft studio lighting, realistic plastic textures, 8k resolution, cinematic look.`
+   - Aspect ratio: 1:1 or 4:5
+
+Present the generated action figure to the user. You can also suggest creating different themes (e.g., changing the character from a doctor to a space explorer).
+
+## Trigger Keywords
+
+`action figure`, `custom toy`, `toy packaging`, `character toy`, `collectible figure`
+
+
+---
+
+## Notes for the Executing Agent
+
+- This recipe is LLM-orchestrated: read each phase, gather any missing inputs from the user, then call `muapi` CLI commands. Use `muapi auth configure` first if `MUAPI_API_KEY` is unset.
+- For model IDs without a CLI alias yet, fall back to the raw endpoint via `curl -X POST https://api.muapi.ai/api/v1/<endpoint> -H "x-api-key: $MUAPI_API_KEY" -H 'content-type: application/json' -d '{...}'` and poll with `muapi predict wait <request_id>`.
+- Substitute `{{input_name}}` placeholders with the user's actual inputs before issuing each call.

package/resources/skills/skills/media/ad-creative/SKILL.md

@@ -0,0 +1,79 @@
+---
+slug: muapi-ad-creative
+name: muapi-ad-creative
+version: "1.0.0"
+description: Generate a high-converting ad creative set — hero image, ad copy variations, and platform-optimized crops for Meta, Google Display, and LinkedIn.
+acceptLicenseTerms: true
+---
+
+
+# Ad Creative Set
+
+**Generate a high-converting ad creative set — hero image, ad copy variations, and platform-optimized crops for Meta, Google Display, and LinkedIn.**
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|:---|:---|:---|:---|:---|
+| `product_or_service` | text | yes | — | What is being advertised (e.g. "SaaS project management tool for remote teams"). |
+| `target_audience` | text | yes | — | Who the ad is for (e.g. "startup founders aged 25–40, tech-savvy"). |
+| `campaign_goal` | text | no | awareness | Campaign objective — "awareness", "consideration", or "conversion". |
+| `tone` | text | no | professional, clean, modern | Creative tone and visual style (e.g. "bold and disruptive", "luxury minimal", "friendly and approachable"). |
+| `product_image` | image_url | no | — | Optional product or brand image URL already in the session. |
+
+
+## Steps
+
+This skill has TWO phases. Phase A creates the hero concept for approval; Phase B fans out to platform formats.
+
+### Phase A — Hero image + Ad copy
+
+Submit ONE the plan with:
+
+1. **Hero image** — `muapi image generate` (model=nano-banana-pro) or `muapi image edit` (model=nano-banana-pro-edit) if `{{product_image}}` is provided:
+   - Aspect ratio: 1:1 (universal starting point).
+   - Prompt must capture: product/service benefit, target audience lifestyle cue, campaign tone.
+   - Style: `{{tone}}, advertising photography, clean background, product focus, ultra detailed, commercial quality`.
+   - Tier: quality.
+
+After the plan executes, present the hero asset and 3 ad copy variations:
+- **Variation A** — Problem-aware hook: "Tired of X? [Product] fixes that."
+- **Variation B** — Benefit-led: "[Feature] → [Outcome] for [Audience]."
+- **Variation C** — Social proof / urgency: "X teams already use [Product]."
+Each variation includes: Headline (6 words max), Body (20–30 words), CTA button text.
+
+Ask which copy variation to use for Phase B. Wait for user confirmation.
+
+### Phase B — Platform crops
+
+Once the user picks a copy direction, submit a SECOND the plan with parallel crops:
+
+1. `muapi image edit` → 1:1 (Facebook/Instagram feed, 1080×1080)
+2. `muapi image edit` → 9:16 (Story/Reels, 1080×1920)
+3. `muapi image edit` → 1.91:1 (Facebook feed wide, 1200×628)
+4. `muapi image edit` → 1:1 (LinkedIn feed, same as FB)
+
+For each crop:
+- Prompt: "Reframe for [platform] ad format. Keep product/subject centered and uncropped. Maintain original palette and tone. Leave headroom/footroom for text overlays."
+- All crops run in parallel.
+
+Return one asset per format with the recommended copy overlay placement for each.
+
+## Notes
+- If `campaign_goal` is "conversion", emphasize urgency and direct CTA in copy.
+- If `campaign_goal` is "awareness", prioritize visual impact over text density.
+- Reference `product_image` via `$nX.url` syntax in Phase B nodes to ensure consistency.
+- Do NOT auto-confirm Phase B without user picking a copy variation.
+
+## Trigger Keywords
+
+`ad creative`, `advertisement`, `facebook ad`, `meta ad`, `google ad`, `linkedin ad`, `paid ad`, `ad banner`, `display ad`
+
+
+---
+
+## Notes for the Executing Agent
+
+- This recipe is LLM-orchestrated: read each phase, gather any missing inputs from the user, then call `muapi` CLI commands. Use `muapi auth configure` first if `MUAPI_API_KEY` is unset.
+- For model IDs without a CLI alias yet, fall back to the raw endpoint via `curl -X POST https://api.muapi.ai/api/v1/<endpoint> -H "x-api-key: $MUAPI_API_KEY" -H 'content-type: application/json' -d '{...}'` and poll with `muapi predict wait <request_id>`.
+- Substitute `{{input_name}}` placeholders with the user's actual inputs before issuing each call.

package/resources/skills/skills/media/ai-clipping/SKILL.md

@@ -0,0 +1,194 @@
+---
+slug: muapi-ai-clipping
+name: muapi-ai-clipping
+version: "1.0.0"
+description: Turn a long video into N viral-ready short clips with a single managed API call. Wraps muapi.ai's `/ai-clipping` endpoint, which handles transcription, highlight ranking through a virality framework (hook / emotional peak / opinion bomb / revelation / conflict / quotable / story peak / practical value), overlap dedupe, and vertical face-tracking auto-crop server-side. No local Whisper, no local LLM, no GPU.
+acceptLicenseTerms: true
+---
+
+# AI Clipping
+
+**One API call: long video in → ranked vertical short clips out.**
+
+Each clip ships with a viral score (0–100), an opening hook line, a one-sentence "why it works" reason, and a hosted mp4 URL.
+
+Underlying API: https://muapi.ai/playground/ai-clipping
+Reference implementation (open source): https://github.com/SamurAIGPT/AI-Youtube-Shorts-Generator
+
+---
+
+## When to Use
+
+- Auto-clip a podcast, interview, lecture, vlog, or stream into TikTok / Reels / Shorts.
+- Extract the best 30–75s moments from any hosted video URL.
+- Get face-tracked vertical (9:16), square (1:1), or portrait (4:5) crops without running ffmpeg locally.
+
+If you only need raw timestamps for your own renderer, set `--coords-only` to skip cropping and just get the highlight ranges.
+
+---
+
+## Agent Execution Protocol
+
+### Step 1 — Collect Inputs
+
+| Input | Required | Default | Notes |
+|:---|:---|:---|:---|
+| `--video` | yes | — | Hosted mp4 URL, or local file path (auto-uploaded), or YouTube URL (if backend supports it) |
+| `--num-clips` | no | `3` | Number of highlights to extract |
+| `--aspect-ratio` | no | `9:16` | `9:16` \| `1:1` \| `4:5` |
+| `--coords-only` | no | off | Return just the highlight time ranges, skip cropping |
+
+If the user gave only a video URL, run with defaults — don't block on questions.
+
+---
+
+### Step 2 — Verify Prerequisites
+
+- `muapi-cli` installed and authed (`muapi auth configure`)
+- `MUAPI_API_KEY` available (env var or `muapi auth status` passes)
+
+That's it. No `ffmpeg`, no Python, no Whisper install, no LLM keys. Everything runs server-side.
+
+---
+
+### Step 3 — Run the Skill
+
+```bash
+bash library/edit/ai-clipping/scripts/run-ai-clipping.sh \
+  --video "https://example.com/podcast.mp4" \
+  --num-clips 5 \
+  --aspect-ratio 9:16 \
+  --view
+```
+
+The script:
+1. Resolves `--video` to a hosted URL (uploads local files via `muapi upload file` if needed).
+2. Calls `muapi edit clipping` with the supported parameters.
+3. Polls until the job is done (or returns the `request_id` immediately under `--async`).
+4. Prints a ranked summary and, if `--output-json` is set, writes the full result.
+
+---
+
+## What Happens Server-Side
+
+The `/ai-clipping` endpoint internally runs the full pipeline so the agent doesn't have to:
+
+- **Transcribe** with Whisper.
+- **Classify content type** (podcast / interview / tutorial / vlog / lecture / monologue).
+- **Rank highlights** through the virality framework:
+  - **Hook moments** — strong opening line that stops the scroll
+  - **Emotional peaks** — laughter, anger, vulnerability, awe
+  - **Opinion bombs** — spicy, contrarian, debate-bait takes
+  - **Revelation moments** — "wait, what?" reframes
+  - **Conflict** — disagreement, tension, callouts
+  - **Quotable lines** — tight, screenshot-worthy phrasing
+  - **Story peaks** — climax of a narrative arc
+  - **Practical value** — actionable insight a viewer will save
+- **Dedupe** overlapping candidates by score.
+- **Top-N select** and **face-track auto-crop** to the requested aspect ratio.
+
+This is why the skill is small: the heavy lifting is on the API.
+
+---
+
+## Quick Invocation Patterns
+
+**Defaults — three 9:16 clips:**
+```bash
+bash run-ai-clipping.sh --video "https://example.com/long.mp4"
+```
+
+**Podcast — more clips, view in player:**
+```bash
+bash run-ai-clipping.sh --video "<URL>" --num-clips 8 --view
+```
+
+**Square clips for Instagram feed:**
+```bash
+bash run-ai-clipping.sh --video "<URL>" --aspect-ratio 1:1 --num-clips 3
+```
+
+**Just the timestamps (build your own renderer):**
+```bash
+bash run-ai-clipping.sh --video "<URL>" --coords-only --output-json result.json
+```
+
+**Async submit (returns request_id, poll later):**
+```bash
+REQUEST_ID=$(bash run-ai-clipping.sh --video "<URL>" --async --output-json - | jq -r '.request_id')
+muapi predict wait "$REQUEST_ID" --download ./outputs
+```
+
+**Local file:**
+```bash
+bash run-ai-clipping.sh --video ./recording.mp4 --num-clips 5 --view
+```
+
+**Batch — `urls.txt` with one URL per line:**
+```bash
+xargs -a urls.txt -I{} bash run-ai-clipping.sh --video "{}"
+```
+
+---
+
+## Aspect Ratio Picker
+
+| Platform | Ratio | Sweet-spot duration |
+|:---|:---|:---|
+| TikTok / Reels / YouTube Shorts | `9:16` | 30–75s |
+| Instagram Feed | `1:1` | 15–45s |
+| Pinterest / portrait | `4:5` | 30–60s |
+
+Default to `9:16` unless the platform is specified.
+
+---
+
+## Output Schema
+
+```json
+{
+  "source_video_url": "...",
+  "shorts": [
+    {
+      "title": "The one mistake that cost me $50K",
+      "start_time": 124.3,
+      "end_time": 187.6,
+      "score": 92,
+      "hook_sentence": "Nobody talks about this, but it killed my first startup...",
+      "virality_reason": "Opens with a number + regret, peaks on a contrarian lesson",
+      "clip_url": "https://.../short_1.mp4"
+    }
+  ]
+}
+```
+
+When `--coords-only` is set, each entry has `start_time`/`end_time` but no `clip_url` — render locally with ffmpeg.
+
+When reporting back to the user, surface for each clip: rank, score, time range, title, hook, and clip URL.
+
+---
+
+## Common Mistakes to Avoid
+
+1. **Wrong aspect ratio for the platform** — Shorts / TikTok / Reels are `9:16`. Default to that.
+2. **Padding to hit `num_clips`** — if the API returns fewer survivors than requested, return what you have. Don't pretend.
+3. **Re-running on a 404'd clip URL** — the same `request_id` can be re-fetched with `muapi predict wait <id>` rather than re-clipping.
+4. **Trying to tune Whisper / chunk size / LLM prompts** — those knobs aren't exposed; the endpoint handles them.
+
+---
+
+## Failure Modes
+
+- **API key missing or rejected** — surface the exact error; never fabricate a key.
+- **Job timed out** — bump poll timeout (`--poll-timeout`) and retry.
+- **Source URL not reachable from the backend** — upload locally with `muapi upload file <path>` first, then pass the returned URL.
+- **Fewer clips returned than requested** — the source had fewer rankable highlights. Return what came back with a note.
+
+---
+
+## Done Criteria
+
+The skill is done when:
+1. `result.shorts` has up to `num_clips` entries, each with a working `clip_url` (or `start_time`/`end_time` under `--coords-only`).
+2. The user has been shown the ranked list (score, time range, title, hook, URL).
+3. If `--output-json` was set, the file exists and parses.