videoclaw 3.0.0-alpha.1

package/skills/runway/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: runway
+description: |
+  Render video on Runway (Runway ML) the right way: through the FREE explore-credit
+  queue, end-to-end. Use whenever the user says "use Runway", "Runway ML",
+  "RunwayML", "run it on Runway", "put it on the Runway queue", or asks to
+  backfill / draft clips on Runway. Default to free explore credits, submit to
+  the queue, then poll and wait (hours is normal) and download clips as they
+  land. Never spend paid credits unless the user explicitly asks for them.
+---
+
+# Runway (free explore queue)
+
+Runway on videoclaw is a **free explore-credit queue**, not an instant renderer.
+The whole point is to never spend paid credits and to let jobs sit in the queue
+until they finish. Drive it through the `vclaw video batch-*` commands.
+
+## The one rule: explore is free, and it is the default
+
+- Explore mode is already the default (`runway-useapi` route, `mode=explore`).
+  **Do not** set `VCLAW_RUNWAY_MODE=credits` — that switches to PAID credits.
+  Only do so if the user explicitly says "use paid credits", and treat that as a
+  spend action (confirm first).
+- Because explore is free, batch-submit/monitor need **no `--confirm-spend`** —
+  just run them.
+- Free-lane ceiling: **720p, ≤10s** per clip, model `seedance-2.0` (image-to-video
+  keyframe + all aspect ratios + 5/8/10/15s durations). 1080p or longer than 10s
+  needs **paid** credits — stop and ask before doing that.
+
+## It is a queue — wait, don't give up
+
+Explore allows roughly **one concurrent job**; the rest queue server-side and can
+take **hours**. This is normal and expected.
+
+- Never use a short poll timeout. Never report a still-queued job as done or
+  failed. A pending job stays pending — say so, keep polling, do not abandon it.
+- Submit is **non-blocking and resumable**: a submit places what the queue will
+  accept, then reports the rest as `pending` for a later pass. Re-running never
+  re-fires an already-submitted scene.
+- Don't block a turn polling. Run the monitor in the background (or on a
+  schedule) and keep working; re-check on a ~20-minute cadence, not every minute.
+
+## Setup
+
+```bash
+set -a && source .env.local && set +a   # USEAPI_API_TOKEN (required) + USEAPI_ACCOUNT_EMAIL
+npm run build                            # run from a built dist/
+```
+
+## End-to-end
+
+1. **Write a batch manifest** (`batch.json`). `route` defaults to the free
+   `runway-useapi`; `id` + `prompt` are required per job; `keyframe` (first-frame
+   seed) or `characterRefs` (identity-lock) are optional and mutually exclusive.
+
+   ```json
+   {
+     "schemaVersion": 1,
+     "route": "runway-useapi",
+     "defaults": { "seconds": 10, "aspectRatio": "16:9", "resolution": "720p" },
+     "jobs": [
+       { "id": "forest", "prompt": "a quiet pine forest at dawn", "keyframe": "/refs/forest.jpg" },
+       { "id": "desert", "prompt": "a desert dune ridge under hard noon sun", "aspectRatio": "9:16" }
+     ]
+   }
+   ```
+
+2. **Submit** (free explore by default). Writes `<dir>/batch-queue.json`.
+
+   ```bash
+   vclaw video batch-submit --manifest batch.json --out runs/overnight
+   ```
+
+   It reports `{ submitted, pending, throttled }`. The explore throttle is NOT a
+   failure — re-run the same command against the same `--out` to drain the queue
+   one slot at a time (idempotent; never re-fires scene 0). Loop until
+   `pending` is `0`.
+
+3. **Monitor** — one poll pass, downloads finished clips to `<dir>/clips/<id>.mp4`,
+   writes `<dir>/batch-status.json`. Safe to re-run (never re-downloads).
+
+   ```bash
+   vclaw video batch-monitor --out runs/overnight --once
+   ```
+
+   Or loop in the foreground until terminal (or the time budget elapses):
+
+   ```bash
+   vclaw video batch-monitor --out runs/overnight --interval 1200 --max-minutes 600
+   ```
+
+4. **Unattended overnight** — schedule the `--once` pass on a launchd agent at a
+   1200s `StartInterval`. Each tick advances the queue and exits; once the rollup
+   is terminal, further ticks are no-ops. Clips collect in `<dir>/clips/` by
+   morning.
+
+5. **Status** — read-only rollup, never polls:
+
+   ```bash
+   vclaw video batch-status --out runs/overnight
+   ```
+
+## When the queue wedges or stalls
+
+A free queue can leave a scene stuck `submitted`. These are opt-in:
+
+- `--stall-minutes <n>` flags any scene still `submitted` past `n` minutes as
+  **wedged** (surfaced in `batch-status.json`).
+- `--fail-wedged` marks wedged scenes `failed` so the monitor can reach terminal
+  and exit; re-run just those ids as a fresh small batch.
+- `--auto-resubmit` (with `--stall-minutes`, bounded by `--max-resubmits`, default
+  2) re-submits wedged scenes — **only on the free `runway-useapi` route**;
+  refused on paid routes, so it can never spend credits.
+- Throttle backoff is automatic: when explore is saturated the monitor widens its
+  poll interval (exponential, capped) instead of hammering.
+
+## Prompt gotchas (Runway / Seedance moderation)
+
+- **No photoreal human faces as references** — the "real person" content filter
+  rejects them. Describe stylized characters by visual descriptor, never a proper
+  name, and pass them as `characterRefs` (they fill the reference slot, never the
+  first frame — avoids the 9-panel grid-open).
+- Soften violent phrasing: `open fire` / `firing guns` → `weapons raised, muzzle
+  flashes`. A failed-with-no-reason result is almost always moderation — retry
+  once or twice with softened wording, then drop the scene and report it.
+
+## Reporting
+
+Report exactly what rendered. A queued job is queued; a downloaded clip exists on
+disk under `<dir>/clips/`. Never claim a clip is ready before it has downloaded,
+and state any failed or dropped scene plainly.

package/skills/seedance-prompts/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: seedance-prompts
+description: >
+  Browse the clean-room Seedance prompt reference library and apply the current
+  provider guidance to Seedance-targeted scene writing. Use when you need
+  Seedance formulas, examples, prompt structure guidance, or prompt-library
+  references that actually exist in this repo.
+triggers:
+  - "seedance prompt"
+  - "generate seedance prompt"
+  - "expand prompt for seedance"
+  - "search seedance prompts"
+  - "find seedance examples"
+  - "seed prompts"
+  - "prompt quality"
+  - "seedance music video"
+  - "music video prompt"
+  - "lip sync prompt"
+  - "beat sync prompt"
+  - "mira style seedance"
+---
+
+# Seedance Prompts
+
+Use this skill to inspect and apply the clean-room Seedance prompt references
+that ship with `vclaw-video-core`.
+
+## Current Scope
+
+This repo currently supports a **reference-first** Seedance workflow, not the
+older Python prompt-database workflow.
+
+What exists now:
+
+1. `vclaw video prompt-lib-list`
+2. `vclaw video prompt-lib-show --name seedance-ugc-formulas`
+3. `vclaw video execution-plan --project <slug>`
+4. `vclaw video storyboard-review --project <slug>`
+
+What does not exist in this repo:
+
+1. `scripts/video/seedance_prompt_db.py`
+2. `scripts/video/seed_skill_prompts.py`
+3. a local SQLite prompt database under `scripts/video/data/`
+
+Do not tell users to run those old paths from this clean-room repo.
+
+## Canonical Commands
+
+### List prompt references
+
+```bash
+vclaw video prompt-lib-list
+```
+
+### Show the Seedance reference
+
+```bash
+vclaw video prompt-lib-show --name seedance-ugc-formulas
+```
+
+### Get project-specific prompt guidance
+
+```bash
+vclaw video execution-plan --project <slug> [--root <path>] [--mode storyboard|director]
+```
+
+This returns the current prompt-guidance set chosen for the project, including
+Seedance-specific references when the route or mode calls for them.
+
+## Workflow
+
+When the user asks for Seedance prompting help:
+
+1. Inspect the current library:
+   `vclaw video prompt-lib-list`
+2. Read the Seedance reference:
+   `vclaw video prompt-lib-show --name seedance-ugc-formulas`
+3. If the prompt needs project context, inspect:
+   `vclaw video execution-plan --project <slug>`
+4. Apply the reference patterns to the user’s scene prose or storyboard beats.
+
+## Output Expectations
+
+A good answer or workflow result should give the user:
+
+1. a concise Seedance-ready scene prompt
+2. camera and pacing guidance grounded in the reference docs
+3. negative / exclusion language when useful
+4. any relevant warning about duration, continuity, or character consistency
+
+## Notes
+
+- Seedance prompting in this repo is currently **doc-and-guidance driven**.
+- The canonical Seedance reference is `seedance-ugc-formulas` in the prompt library.
+- When a user needs a full project-aware recommendation, prefer the execution
+  plan and storyboard review outputs over freehand prompt invention.
+
+## Music-video prompts (formerly seedance-music-video-prompts)
+
+When the user wants a music video specifically — beat-synced visuals,
+lyric-driven scene changes, performance shots — use the music-video
+prompt patterns below in addition to the general Seedance prompt
+patterns above.
+
+<!-- Folded in from skills/seedance-music-video-prompts/SKILL.md in Slice 2 (2026-05-25). -->
+
+Create prompt packs for Seedance music videos that use a reference artist
+image (`@Image1`, `@Image2`) and a music/audio track (`@Audio1`). This
+section is narrower than the general Seedance guidance above: it is for
+music-video shot design, not general scene prompting.
+
+### When to use the music-video patterns
+
+- The user wants prompts for a music video using Seedance.
+- The prompt needs lip sync, beat sync, artist performance, or audio-native generation.
+- The user wants a reusable prompt pack with character sheets and multiple performance/world-building shots.
+- The user references Mira-style Seedance/Suno prompt examples.
+
+### Music-video workflow
+
+1. Identify the song context:
+   - genre, tempo, mood, vocal style, runtime target
+   - lead artist count and whether there is a love interest, dancers, band, or crowd
+   - desired aspect ratio and platform
+2. Create or request artist reference images:
+   - one character sheet per lead artist or recurring character
+   - consistent wardrobe anchors and distinctive features
+   - neutral background, multiple views, close-ups
+3. Build 6-12 Seedance video prompts:
+   - mix tight lip-sync performance shots, walking/track shots, and world-building shots
+   - keep each prompt one shot, one location, one primary action
+   - include exact references such as `@Image1` and `@Audio1`
+4. Add motion constraints:
+   - state what should remain still or restrained
+   - block unwanted subtitles, sudden zooms, excessive dance, background clutter, or identity drift
+5. Deliver a production-ready pack:
+   - character sheet prompts first
+   - Seedance video prompts next
+   - a short continuity checklist at the end
+
+### Music-video prompt structure
+
+Use this structure for every Seedance music-video prompt:
+
+```text
+[Shot size and subject] of [artist/reference] performing @Audio1 in [location].
+[Lip-sync or beat-sync instruction] throughout the entire shot.
+[Wardrobe, lighting, color palette, production design].
+[Movement: artist movement + camera movement + rhythm relationship to @Audio1].
+[Constraints: no subtitles, no extra actions, no sudden motion, no identity drift].
+[Aesthetic: genre, lens/film language, texture, mood].
+10 second duration. Audio-native generation; sync lip movement, body motion, and camera rhythm to @Audio1.
+```
+
+### Shot mix
+
+- **Character sheet**: build the visual identity before video generation.
+- **Tight lip sync**: extreme close-up or medium close-up for vocal precision.
+- **Beat-sync walk**: slow walk, track backward, steps locked to the beat.
+- **World-building performance**: artist performs inside a cinematic location while atmosphere moves around them.
+- **Secondary character scene**: include another character only when the relationship matters to the song.
+- **Chorus energy shot**: restrained dancers, crowd motion, rain, neon, or lights synced to the track.
+
+### Music-video reference
+
+For Mira-style patterns, read `references/mira-style-seedance-pack.md`.
+
+### Music-video output format
+
+```markdown
+# Seedance Music Video Prompt Pack
+
+## Inputs
+- Audio: @Audio1
+- Artist refs: @Image1, @Image2
+- Style:
+- Runtime/clip count:
+
+## Character Sheet Prompts
+...
+
+## Seedance Video Prompts
+### Prompt 1 - [shot purpose]
+Model: Seedance 2.0 (Video)
+...
+
+## Continuity Checklist
+- Same artist identity across clips
+- Wardrobe continuity intentional
+- Lip-sync shots explicitly say active singing/rapping
+- Movement is restrained and beat-aware
+- No subtitles
+```