cue-ai 0.9.2 → 0.9.3

package/resources/skills/skills/media/ui-design/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: muapi-ui-design
+version: 0.1.0
+description: Generate high-fidelity UI/UX mockups for mobile and web apps using Atomic Design principles — creates wireframes and design systems via muapi.ai
+---
+
+# 🎨 UI/UX Design Mockup Skill
+
+**A specialized skill for AI Agents to architect high-fidelity digital interfaces.**
+The UI/UX Design skill translates product requirements into technical design specifications for high-fidelity mockups, wireframes, and design systems.
+
+## Core Competencies
+
+1. **Atomic Design Orchestration**: Structuring interfaces from Atoms (buttons) to Organisms (headers) for system consistency.
+2. **Platform-Specific Layouts**: Designing for responsive breakpoints across Mobile (iOS/Android) and Web (SaaS/E-commerce).
+3. **Design System Integration**: Specifying typography scales, spacing tokens, and color palettes (Hex/HSL).
+4. **Heuristic Awareness**: Ensuring designs follow established usability principles (Nielsen's 10 Heuristics).
+
+---
+
+## 🏗️ Technical Specification
+
+### 1. Intent Mapping Table
+
+| Creative Intent | Style | Layout Pattern | Focus |
+| :--- | :--- | :--- | :--- |
+| **Enterprise SaaS** | Modern/Clean | Dashboard/Grid | Data Density |
+| **Consumer App** | Glassmorphism | F-Pattern / Cards | Visual Flair |
+| **E-commerce** | Minimalist | Z-Pattern / Product Grid | Conversion |
+| **Portfolio** | Brutalist | Asymmetric | Identity |
+| **Utility/Tool** | Neomorphism | Control Panel | Tactile Feedback |
+
+### 2. Design Tokens & Variables
+- `Typography`: Geometric Sans (Inter/Roboto) for tech; Serif (Playfair) for luxury.
+- `Spacing`: 8pt grid system for consistent rhythmic spacing.
+- `Color`: High-contrast accessible palettes (WCAG 2.1 compliant).
+- `Elevation`: Shadow-based depth vs. Flat design layers.
+
+---
+
+## 🧠 Prompt Optimization Protocol (Agent Instruction)
+
+**Before calling the script, the Agent MUST expand the user's requirements into a Design Specification:**
+
+1. **ATOMIC STRUCTURE**: Mention specific components (Atoms): *Glassmorphic buttons*, *Input fields with 4px radius*, *Iconic sidebars*.
+2. **HIERARCHY**: Use layout patterns: *F-Pattern* for content-heavy sites, *Z-Pattern* for landing pages, *Grid-based Dashboards*.
+3. **TYPOGRAPHY & TOKENS**: Injected design tokens: *Inter Sans-serif*, *8pt spacing system*, *WCAG high-contrast colors*.
+4. **NO SKEUOMORPHISM**: Ensure the prompt enforces *Flat Design* or *Glassmorphism* to avoid "photograph-of-screen" results.
+
+---
+
+## 🚀 Protocol: Using the UI Designer
+
+### Step 1: Define the Product Brief
+Provide the agent with a feature list and target audience.
+
+### Step 2: Invoke the Script
+The `generate-mockup.sh` script expands the brief using internal knowledge of design systems.
+
+```bash
+# Designing a Fintech Mobile App
+bash scripts/generate-mockup.sh \
+  --desc "crypto wallet home with price charts" \
+  --platform mobile \
+  --theme dark \
+  --style glassmorphism
+```
+
+---
+
+## ⚠️ Constraints & Guardrails
+
+- **Device Realism**: **MANDATORY** - Do not show hands, physical phones, or desks. Generate pure UI/UX mockups only.
+- **Accessibility**: Avoid low-contrast text on bright backgrounds.
+- **Complexity**: Keep "Atoms" consistent across a single page generation.
+- **Text Rendering**: Use Flux for legible headers; specify placeholder text for smaller body copy.
+
+---
+
+## ⚙️ Implementation Details
+This skill translates a high-level `DESCRIPTION` into a `UX_BRIEF` that specifies layout patterns, design tokens, and aesthetic constraints for the `core/media/generate-image.sh` primitive.

package/resources/skills/skills/media/ui-design/scripts/generate-mockup.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Expert Skill: UI/UX Design Mockup Generator
+# Translates product requirements into design system directives.
+
+PLATFORM="mobile"
+STYLE="modern"
+THEME="light"
+DESCRIPTION=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --platform) PLATFORM="$2"; shift 2 ;;
+        --style) STYLE="$2"; shift 2 ;;
+        --theme) THEME="$2"; shift 2 ;;
+        --desc) DESCRIPTION="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+if [ -z "$DESCRIPTION" ]; then
+    echo "Usage: bash generate-mockup.sh --desc 'travel app' [--platform mobile|web] [--style glassmorphism|brutalist] [--theme light|dark]"
+    exit 1
+fi
+
+# Design System Logic
+if [ "$PLATFORM" == "mobile" ]; then
+    AR_FLAG="--aspect-ratio 9:16"
+    LAYOUT="Card-based, bottom navigation bar, 8pt grid system"
+    SYSTEM="iOS Human Interface Guidelines style"
+else
+    AR_FLAG="--aspect-ratio 16:9"
+    LAYOUT="Sidebar navigation, grid layout, F-pattern hierarchy"
+    SYSTEM="Modern SaaS Design System style"
+fi
+
+# Technical UX Brief
+EXPERT_PROMPT="[UX_BRIEF]
+PLATFORM: $PLATFORM
+CONTEXT: $DESCRIPTION
+DESIGN_SYSTEM: $SYSTEM, $THEME mode
+STYLE_TOKENS: $STYLE aesthetic, geometric sans-serif (Inter), high-contrast accessibility
+LAYOUT_PATTERN: $LAYOUT, professional whitespace, vector icons
+[EXECUTE] Generate a high-fidelity flat UI mockup. NO hands, NO physical devices, NO background clutter. Pure digital interface only."
+
+# Call Core Primitive
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+CORE_SCRIPT="$SCRIPT_DIR/../../core-media/generate-image.sh"
+
+bash "$CORE_SCRIPT" --prompt "$EXPERT_PROMPT" --model flux-dev $AR_FLAG --json

package/resources/skills/skills/media/url-to-design/SKILL.md

@@ -0,0 +1,61 @@
+---
+slug: muapi-url-to-design
+name: muapi-url-to-design
+version: "1.0.0"
+description: Analyze a website URL and generate a redesigned, improved UI — recreate the visual design with modern aesthetics, better hierarchy, and fresh brand direction.
+acceptLicenseTerms: true
+---
+
+
+# URL to Design
+
+**Analyze a website URL and generate a redesigned, improved UI — recreate the visual design with modern aesthetics, better hierarchy, and fresh brand direction.**
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|:---|:---|:---|:---|:---|
+| `url` | text | yes | — | The website URL to analyze and redesign (e.g. "https://example.com/pricing"). |
+| `page_type` | text | no | landing page | Type of page — "landing page", "pricing page", "product page", "dashboard", "about page". |
+| `redesign_style` | text | no | modern, minimal, premium, dark mode | The target visual style for the redesign (e.g. "glassmorphism, vibrant gradient", "clean corporate, light mode"). |
+| `keep_brand` | text | no | yes | Whether to keep existing brand colors/logo — "yes" or "no" (fully reimagine). |
+| `screenshot` | image_url | no | — | Optional screenshot of the current page if URL cannot be crawled. |
+
+
+## Steps
+
+### Phase A — Redesign Generation
+
+Submit the plan with TWO parallel steps:
+
+
+1. **Full-page redesign mockup** — If `{{screenshot}}` is provided, use `muapi image edit` (model=`gpt4o-edit`); otherwise use `muapi image generate` (model=`gpt4o-text-to-image`):
+   - Prompt: `Professional UI/UX redesign of a {{page_type}} for the website at {{url}}. {{redesign_style}} design. Modern web design, 2025 aesthetic. Includes: hero section with clear headline and CTA button, features/benefits section, social proof, clean footer. Pixel-perfect, Figma-quality mockup. Desktop viewport, 1440px width design.`
+   - If `{{keep_brand}}` is "no", add: `Completely reimagined brand identity, new color palette.`
+   - Aspect ratio: 9:16 (tall to show full page sections)
+
+2. **Mobile version mockup** — `muapi image generate` (model=`bytedance-seedream-v4.5`):
+   - Prompt: `Mobile-first responsive redesign of the same {{page_type}} — {{redesign_style}} style. iPhone 15 Pro frame, scrollable layout. Clean mobile navigation, thumb-friendly CTAs, optimized for 390px width. Modern 2025 mobile UI design.`
+   - Aspect ratio: 9:19.5
+
+After generation:
+- Present both desktop and mobile mockups side by side
+- Provide a written summary of design improvements made
+- Offer to generate specific sections (hero, pricing cards, testimonials) as separate assets
+
+## Notes
+- If the URL is unreachable, ask the user to provide a screenshot or describe the current design.
+- Always improve: typography hierarchy, whitespace, CTA visibility, and mobile responsiveness.
+
+## Trigger Keywords
+
+`url to design`, `redesign website`, `website redesign`, `ui redesign`, `landing page design`, `page redesign`, `website to design`, `convert url to design`
+
+
+---
+
+## 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/workflow/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: muapi-workflow
+version: 0.1.0
+description: Build, run, and visualize multi-step AI generation workflows. The AI architect translates natural language descriptions into connected node graphs — chain image generation, video creation, enhancement, and editing into automated pipelines.
+---
+
+# AI Workflow Builder
+
+Chain any combination of muapi.ai generation steps into automated pipelines. The AI architect converts your plain-language description into a runnable node graph.
+
+## Prerequisites
+
+Always ensure the `muapi` CLI is up-to-date before running any commands. Reinstall from source at the start of every session:
+
+```bash
+pip install --upgrade /path/to/muapi-cli
+```
+
+Replace `/path/to/muapi-cli` with the actual path to the `muapi-cli` directory in the workspace (the directory containing `pyproject.toml`).
+
+## Core Operations
+
+1. **Generate** (`generate-workflow.sh`) — AI architect creates a workflow from a description
+2. **Discover** (`discover-workflow.sh`) — Find a relevant existing workflow by natural language
+3. **Edit** (`generate-workflow.sh --workflow-id`) — Modify an existing workflow with a prompt
+4. **Interactive Run** (`interactive-run.sh`) — Prompt for inputs and execute a workflow
+5. **Run** (`run-workflow.sh`) — Execute a workflow, poll node-by-node, collect outputs
+6. **CLI** (`muapi workflow`) — Full CRUD + visualization directly from the terminal
+
+---
+
+## Agent Guided Discovery & Selection
+
+As an AI agent, you have the ability to read and understand the purpose of available workflows to select the best one for the user's task (e.g., "create a UGC video").
+
+1. **Discover**: Fetch the catalog of available workflows and their descriptions in JSON format.
+   ```bash
+   muapi workflow discover --output-json
+   ```
+2. **Match (Internal Reasoning)**: Use your LLM capabilities to analyze the `name`, `category`, and `description` fields of the returned workflows. Find the best match for the user's intent.
+3. **Analyze**: If you find a promising candidate, inspect its structure to ensure it has the necessary nodes and parameters.
+   ```bash
+   muapi workflow get <workflow_id>
+   ```
+   **CRITICAL RULE**: The output of `muapi workflow get` will include an "API Inputs" table. You MUST read this table to understand what inputs are required.
+4. **Choose & Confirm & Prompt User**:
+   - If one workflow is a perfect match, you MUST ask the user to provide the exact values for the required API inputs before executing it. **Never invent or guess input values (like prompts, URLs, etc.) on your own.**
+   - If multiple workflows are highly relevant, present the options to the user with their descriptions and ask them to confirm which one to use, and also ask for the required inputs.
+   - If no workflow matches the user's complex request, offer to **architect** a new one using `muapi workflow create`.
+
+### Example Agent Reasoning
+> "The user wants a product promo video. I fetched the catalog using `discover`. I see two potential workflows:
+> 1. `wf_123`: 'Product promo with background music'
+> 2. `wf_456`: 'Simple video gen'
+> I will analyze `wf_123` with `get`. It has the required nodes. I will suggest `wf_123` or just run it if the match is precise."
+
+---
+
+## Protocol: Building a Workflow
+
+### Step 1 — Describe your pipeline
+
+```bash
+muapi workflow create "take a text prompt, generate an image with flux-dev, then upscale it to 4K"
+```
+
+The architect returns a workflow with a unique ID and a node graph. Save the ID.
+
+### Step 2 — Inspect and visualize
+
+```bash
+# Rich ASCII node graph in the terminal
+muapi workflow get <workflow_id>
+
+# Or raw JSON
+muapi workflow get <workflow_id> --output-json
+```
+
+### Step 3 — Run it
+
+```bash
+# Run with specific inputs
+muapi workflow execute <workflow_id> \
+  --input "node1.prompt=a glowing crystal cave at midnight"
+
+# Use --download to pull results locally
+muapi workflow execute <workflow_id> \
+  --input "node1.prompt=a sunset" \
+  --download ./outputs
+```
+
+### Step 4 — Discovery (Optional)
+If you want to reuse an existing workflow instead of creating a new one:
+
+```bash
+# Search by keywords
+muapi workflow discover "ugc video"
+```
+
+### Step 5 — Interactive Execution
+Run a workflow and have the CLI prompt you for each required input:
+
+```bash
+muapi workflow run-interactive <workflow_id>
+```
+
+---
+
+## Workflow Examples
+
+### Image Pipelines
+
+```bash
+# Text → Image → Upscale
+muapi workflow create "take a text prompt, generate with flux-dev, upscale the result"
+
+# Text → Image → Background removal → Product shot
+muapi workflow create "generate a product image with hidream, remove background, create professional product shot"
+```
+
+### Video Pipelines
+
+```bash
+# Text → Video
+muapi workflow create "generate a 10-second cinematic video from a text prompt using kling-master"
+
+# Image → Video → Lipsync
+muapi workflow create "animate an input image with seedance, then apply lipsync from an audio file"
+```
+
+---
+
+## Editing an Existing Workflow
+
+```bash
+# Add a step
+muapi workflow edit <id> --prompt "add a face-swap step after the image generation"
+
+# Swap a model
+muapi workflow edit <id> --prompt "change the video model from kling to veo3"
+```
+
+---
+
+## CLI Reference
+
+```bash
+# List all your workflows
+muapi workflow list
+
+# Browse templates
+muapi workflow templates
+
+# Generate new workflow
+muapi workflow create "text → flux image → upscale → face swap"
+
+# Visualize a workflow
+muapi workflow get <id>
+
+# Execute with inputs
+muapi workflow execute <id> --input "node1.prompt=a sunset"
+
+# Monitor a run
+muapi workflow status <run_id>
+
+# Get outputs
+muapi workflow outputs <run_id> --download ./results
+
+# Edit with AI
+muapi workflow edit <id> --prompt "add lipsync at the end"
+
+# Rename / delete
+muapi workflow rename <id> --name "Product Pipeline v2"
+muapi workflow delete <id>
+```
+
+---
+
+## MCP Tools (for AI agents)
+
+| Tool | Description |
+|------|-------------|
+| `muapi_workflow_list` | List user's workflows |
+| `muapi_workflow_create` | AI architect: prompt → workflow |
+| `muapi_workflow_get` | Get workflow definition + node graph |
+| `muapi_workflow_execute` | Run with specific inputs |
+| `muapi_workflow_status` | Node-by-node run status |
+| `muapi_workflow_outputs` | Final output URLs |
+
+---
+
+## Constraints
+
+- Workflows can contain any combination of muapi.ai nodes (image, video, audio, enhance, edit)
+- Node outputs are automatically wired as inputs to downstream nodes
+- `--sync` mode waits up to 120s for generation; use `--async` for complex workflows and poll separately
+- Run timeouts: 10 minutes maximum per workflow execution

package/resources/skills/skills/media/workflow/scripts/discover-workflow.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Assistant Skill: Discover Relevant Workflow
+# Thin wrapper around muapi CLI.
+
+QUERY=""
+LIMIT=5
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --query|-q) QUERY="$2"; shift 2 ;;
+        --limit)    LIMIT="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+if [ -z "$QUERY" ]; then echo "Error: --query is required" >&2; exit 1; fi
+
+muapi workflow discover "$QUERY" --limit "$LIMIT"

package/resources/skills/skills/media/workflow/scripts/generate-workflow.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Expert Skill: AI Workflow Architect
+# Thin wrapper around muapi CLI.
+
+PROMPT=""
+WORKFLOW_ID=""   # Set to edit an existing workflow
+ASYNC=false
+VIEW=false
+JSON_ONLY=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --prompt|-p)       PROMPT="$2"; shift 2 ;;
+        --workflow-id|-w)  WORKFLOW_ID="$2"; shift 2 ;;
+        --async)           ASYNC=true; shift ;;
+        --view)            VIEW=true; shift ;;
+        --json)            JSON_ONLY=true; shift ;;
+        *) shift ;;
+    esac
+done
+
+if [ -z "$PROMPT" ]; then echo "Error: --prompt is required" >&2; exit 1; fi
+
+ARGS=()
+[ "$ASYNC" = true ] && ARGS+=("--async")
+[ "$VIEW" = true ] && ARGS+=("--view")
+[ "$JSON_ONLY" = true ] && ARGS+=("--output-json")
+
+if [ -n "$WORKFLOW_ID" ]; then
+    muapi workflow edit "$WORKFLOW_ID" --prompt "$PROMPT" "${ARGS[@]}"
+else
+    muapi workflow create "$PROMPT" "${ARGS[@]}"
+fi

package/resources/skills/skills/media/workflow/scripts/interactive-run.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Assistant Skill: Interactive Workflow Runner
+# Thin wrapper around muapi CLI.
+
+WORKFLOW_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --workflow-id|-w) WORKFLOW_ID="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+if [ -z "$WORKFLOW_ID" ]; then echo "Error: --workflow-id is required" >&2; exit 1; fi
+
+muapi workflow run-interactive "$WORKFLOW_ID"

package/resources/skills/skills/media/workflow/scripts/list-workflows.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Assistant Skill: List Workflows
+# Thin wrapper around muapi CLI.
+
+JSON_ONLY=false
+LIMIT=20
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --json) JSON_ONLY=true; shift ;;
+        --limit) LIMIT="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+if [ "$JSON_ONLY" = true ]; then
+    muapi workflow list --output-json
+else
+    muapi workflow list | head -n $((LIMIT + 5))
+fi

package/resources/skills/skills/media/workflow/scripts/run-workflow.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Expert Skill: Run & Visualize an AI Workflow
+# Thin wrapper around muapi CLI.
+
+WORKFLOW_ID=""
+INPUT_ARGS=()
+WEBHOOK=""
+ASYNC=false
+DOWNLOAD_DIR=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --workflow-id|-w)  WORKFLOW_ID="$2"; shift 2 ;;
+        --input|-i)        INPUT_ARGS+=("$2"); shift 2 ;;
+        --webhook)         WEBHOOK="$2"; shift 2 ;;
+        --async)           ASYNC=true; shift ;;
+        --download|-d)     DOWNLOAD_DIR="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+if [ -z "$WORKFLOW_ID" ]; then echo "Error: --workflow-id is required" >&2; exit 1; fi
+
+ARGS=()
+for ITEM in "${INPUT_ARGS[@]}"; do ARGS+=("--input" "$ITEM"); done
+[ -n "$WEBHOOK" ] && ARGS+=("--webhook" "$WEBHOOK")
+[ "$ASYNC" = true ] && ARGS+=("--no-wait")
+[ -n "$DOWNLOAD_DIR" ] && ARGS+=("--download" "$DOWNLOAD_DIR")
+
+if [ ${#INPUT_ARGS[@]} -gt 0 ]; then
+    muapi workflow execute "$WORKFLOW_ID" "${ARGS[@]}"
+else
+    muapi workflow run "$WORKFLOW_ID" "${ARGS[@]}"
+fi

package/resources/skills/skills/media/youtube-shorts/SKILL.md

@@ -0,0 +1,173 @@
+---
+slug: muapi-youtube-shorts
+name: muapi-youtube-shorts
+version: "2.0.0"
+description: Auto-generate viral 9:16 YouTube Shorts (or TikTok / Reels clips) from a long-form video. Thin platform-aware wrapper around the AI Clipping skill — picks sensible defaults for short-form social platforms (9:16, 30–60s sweet spot) and delegates the actual highlight extraction + crop to muapi.ai's `/ai-clipping` endpoint.
+acceptLicenseTerms: true
+---
+
+# YouTube Shorts Generator
+
+**Long video → ranked vertical short clips, tuned for short-form social.**
+
+This skill is a platform-aware preset over the [AI Clipping](../../edit/ai-clipping/) primitive. It picks the right aspect ratio and clip count for the target platform and delegates highlight extraction, dedupe, and face-tracked auto-crop to muapi.ai's managed `/ai-clipping` endpoint.
+
+Reference implementation: https://github.com/SamurAIGPT/AI-Youtube-Shorts-Generator
+Underlying API: https://muapi.ai/playground/ai-clipping
+
+---
+
+## When to Use This vs. AI Clipping
+
+| Use this skill when… | Use [AI Clipping](../../edit/ai-clipping/) directly when… |
+|:---|:---|
+| Target is YouTube Shorts / TikTok / Reels | You want full control over aspect / count |
+| You want platform-tuned defaults | You want raw timestamps (`--coords-only`) |
+| You'd rather pass `--platform tiktok` than think about ratios | You're integrating into a custom renderer |
+
+---
+
+## Agent Execution Protocol
+
+### Step 1 — Collect Inputs
+
+| Input | Default | Notes |
+|:---|:---|:---|
+| `--source` | — | YouTube URL, hosted mp4 URL, or local file |
+| `--platform` | `shorts` | `shorts` \| `tiktok` \| `reels` \| `feed` (sets ratio + count defaults) |
+| `--num-clips` | platform default | Override clip count |
+| `--aspect-ratio` | platform default | Override aspect ratio |
+
+If the user gave only a URL, run with platform defaults — don't block.
+
+---
+
+### Step 2 — Verify Prerequisites
+
+- `muapi-cli` installed and authed (`muapi auth configure`)
+- `MUAPI_API_KEY` available
+
+That's it. Transcription, highlight ranking, dedupe, and cropping all run server-side — no `ffmpeg`, no Python, no Whisper, no LLM keys needed locally.
+
+---
+
+### Step 3 — Run the Pipeline
+
+```bash
+bash library/social/youtube-shorts/scripts/run-youtube-shorts.sh \
+  --source "<YOUTUBE_URL>" \
+  --platform shorts \
+  --num-clips 5 \
+  --view
+```
+
+The script:
+1. Resolves the source (uploads local files to muapi CDN if needed).
+2. Picks platform defaults if `--aspect-ratio` / `--num-clips` aren't passed.
+3. Calls `muapi edit clipping` (the `/ai-clipping` endpoint) with the chosen params.
+4. Polls until done, prints a ranked summary, optionally downloads / opens clips.
+
+---
+
+## What Happens Server-Side
+
+The `/ai-clipping` endpoint runs the full pipeline:
+
+- **Transcribes** the audio.
+- **Ranks highlights** through a virality framework — hook moments, emotional peaks, opinion bombs, revelation moments, conflict, quotable lines, story peaks, practical value.
+- **Dedupes** overlapping candidates by score.
+- **Top-N selects** and **face-tracks** vertical crops.
+
+Each clip ships with score (0–100), opening hook line, and a one-sentence "why it works" reason.
+
+---
+
+## Platform Defaults
+
+| Platform | Flag | Aspect | Default clips | Notes |
+|:---|:---|:---|:---|:---|
+| YouTube Shorts | `--platform shorts` | `9:16` | 3 | Hook in first 1s |
+| TikTok | `--platform tiktok` | `9:16` | 5 | Higher energy, longer ok |
+| Instagram Reels | `--platform reels` | `9:16` | 3 | Hook in first 1s |
+| Instagram Feed | `--platform feed` | `1:1` | 3 | Static-feel works well |
+
+Override any default with `--aspect-ratio` / `--num-clips`.
+
+---
+
+## Quick Invocation Patterns
+
+**Single video, defaults:**
+```bash
+bash run-youtube-shorts.sh --source "https://youtube.com/watch?v=VIDEO_ID"
+```
+
+**TikTok preset — 5 clips, view in player:**
+```bash
+bash run-youtube-shorts.sh --source "<URL>" --platform tiktok --view
+```
+
+**Square Instagram feed clips:**
+```bash
+bash run-youtube-shorts.sh --source "<URL>" --platform feed --num-clips 3
+```
+
+**Batch — `urls.txt` with one URL per line:**
+```bash
+xargs -a urls.txt -I{} bash run-youtube-shorts.sh --source "{}"
+```
+
+**Async submit (returns request_id, poll later):**
+```bash
+REQUEST_ID=$(bash run-youtube-shorts.sh --source "<URL>" --async --output-json - | jq -r '.request_id')
+muapi predict wait "$REQUEST_ID" --download ./outputs
+```
+
+---
+
+## 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 reporting back, 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`. The platform preset handles this; only override if you know why.
+2. **Padding to hit `--num-clips`** — if the API returns fewer survivors, return what you have. Don't ship low-score filler.
+3. **Re-running on a 404'd clip URL** — re-fetch the same `request_id` with `muapi predict wait <id>` rather than re-clipping.
+
+---
+
+## Failure Modes
+
+- **API key missing or rejected** — surface the error; don't fabricate a key.
+- **Job timed out** — bump `--poll-timeout` and retry.
+- **Source URL not reachable** — upload the file via `muapi upload file` and pass the returned URL.
+- **Fewer clips returned than requested** — 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`.
+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.