videoclaw 3.0.0-alpha.1

package/schemas/video/pipeline-manifest.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "vclaw-video-core/video/pipeline-manifest",
+  "title": "Vclaw Video Pipeline Manifest",
+  "type": "object",
+  "required": ["name", "version", "productionMode", "stages"],
+  "properties": {
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "productionMode": {
+      "type": "string",
+      "enum": ["storyboard", "director"]
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "produces", "checkpointRequired", "humanApprovalDefault", "successCriteria"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "enum": ["brief", "storyboard", "assets", "review", "publish"]
+          },
+          "requiredArtifactsIn": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["brief", "storyboard", "asset-manifest", "review-report", "publish-report", "analyze-output"]
+            }
+          },
+          "produces": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["brief", "storyboard", "asset-manifest", "review-report", "publish-report", "analyze-output"]
+            }
+          },
+          "checkpointRequired": { "type": "boolean" },
+          "humanApprovalDefault": { "type": "boolean" },
+          "successCriteria": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/skills/README.md

@@ -0,0 +1,113 @@
+# Skills Catalog
+
+This repo now includes the legacy `videoclaw/skills` set, imported into the
+clean-room tree so the workflow surface is available locally instead of only in
+the old repo.
+
+## Start Here
+
+The imported library is no longer treated as a flat bag of equally-preferred
+entry points.
+
+Use these canonical surfaces first:
+
+| Goal | Start With | Then Specialize Into |
+|---|---|---|
+| "Help me make a video" — guided, novice-facing, menu-driven | `concierge` (speaks as **Clawbot**, the VideoClaw mascot; `clawbot` is a persona alias) | routes into any lane: `video-framework`, `brand-presenter`, `brand-agency`, `character-ad`, `ugc`, `movie-director`, `multi-shot-prompt`, `video-clone-ad` |
+| Generic video request | `video-framework` | `video-storyboard`, `video-analyze-template`, `video-clone-ad`, `video-replicator`, `movie-director`, `video-production-handoff`, `video-review-ui-qa`, `video-portfolio-ops`, `video-release-readiness`, `higgsfield-generate`, `ugc` |
+| Narrated presenter / host-led deck video | `brand-presenter` | `davendra-presenter`, `nex-presenter`, `bunty` |
+
+Compatibility/deep-reference surfaces remain available, but the preferred UX is:
+
+1. start at a canonical entry point
+2. specialize only when the mode is clearly known
+3. keep personal or legacy names as aliases rather than first-choice workflows
+
+## Video Production Skills
+
+- `video-framework`
+- `video-replicator`
+- `video-storyboard`
+- `video-analyze-template`
+- `video-clone-ad`
+- `video-production-handoff`
+- `video-review-ui-qa`
+- `video-portfolio-ops`
+- `video-release-readiness`
+- `movie-director`
+- `higgsfield-generate`
+- `seedance-prompts`
+- `ugc`
+- `character-library`
+- `character-creator`
+- `video-post`
+- `youtube-audio`
+- `brand-presenter`
+- compatibility aliases:
+  - `davendra-presenter`
+  - `nex-presenter`
+  - `bunty`
+
+## Workflow Skills
+
+Generic orchestration skills that duplicate the operator's global plugin set
+(`autopilot`, `ralph`/`ralph-init`/`ralplan`, `team`, `cancel`, `trace`, `hud`,
+`git-master`, `code-review`, `security-review`, and the removed-tooling
+`omx-setup`) have been culled from this repo — use the global versions. The
+remaining repo-local workflow skills:
+
+- `concierge`
+  - persona alias: `clawbot`
+- `improvement-run` — whole-codebase improvement pass (parallel audit → adversarial verification → plan gate → batched PRs with fresh verifiers)
+- `build-fix`
+- `deep-interview`
+- `deepsearch`
+- `doctor`
+- `graphify` — codebase knowledge-graph navigation (query/path/explain over a built graph; external graphify CLI + graphify-out/)
+- `help`
+- `note`
+- `pipeline`
+- `review`
+- `skill`
+- `studio-mode`
+- `web-clone`
+- `worker`
+- `configure-notifications`
+- `ai-slop-cleaner`
+
+## Import Notes
+
+1. The imported skill tree preserves legacy names for compatibility.
+2. Personal/brand-specific presenter skills are kept as aliases over the shared
+   `brand-presenter` surface so the repo stays generic while preserving
+   discoverability.
+3. `video-framework` and `brand-presenter` are the canonical entry points for
+   broad video and presenter requests; deeper skills now sit underneath them as
+   specialist or compatibility surfaces.
+4. `character-library` is the hygiene and repair companion to
+   `character-creator`; creation stays on the creator skill while audit, patch,
+   and delete operations live in the library lane.
+5. `video-post` closes the loop after render with verification, platform
+   variants, thumbnails, and archive helpers.
+6. `video-production-handoff` is the operator handoff lane for Review UI,
+   review-autopilot, canonical `review-report.json` truth, and release-ready
+   verification before publish.
+7. `video-review-ui-qa`, `video-portfolio-ops`, and
+   `video-release-readiness` split the production surface into browser QA,
+   slate management, and release handoff so advanced commands remain intact but
+   operators get clear workflows.
+8. `higgsfield-generate` is an external bridge over Higgsfield's MIT-licensed
+   public skills and official CLI. Keep it optional and thin; do not vendor the
+   upstream setup script or make Higgsfield a required runtime dependency.
+9. Local repo paths should be preferred over old `.claude/...` path assumptions
+   when adapting or extending these skills further.
+
+## Machine-Readable Catalog
+
+For tooling and maintenance, the repo now also carries:
+
+1. `skills/catalog.json`
+
+It records the imported skill ids, rough category, alias relationships, and the
+new canonical-entry/specialization structure so the skill surface can be
+audited without scraping markdown.

package/skills/ai-director/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: ai-director
+description: Act as an AI Animation Director — run the staged director system to lock a project-level visual blueprint (visual identity, master color system, lighting grammar, per-character blueprint, environment blueprint, project camera bible, performance rules) and persist it as projects/<slug>/artifacts/project-blueprint.json so every filmmaking-prompts scene packet inherits it. Trigger on "director blueprint", "project bible", "art-direct this", "camera bible", "lock the look".
+---
+
+<Purpose>
+The AI Director is the **director layer ABOVE** VideoClaw's existing camera
+reference — it does NOT replace `cinematography.ts` / `filmmaking-prompts`, it
+locks the film language they execute. You think, design, and direct: every visual
+decision serves an emotion, and you explain the WHY. The output is a single
+`project-blueprint.json` that `vclaw video director-blueprint` validates + stores,
+after which every Seedance/Veo/i2v scene packet automatically inherits the locked
+palette, lighting, per-character framing, environment atmosphere, and the camera
+bible's forbidden movements + the one rule.
+</Purpose>
+
+<Use_When>
+- The user wants strong, consistent cinematic direction across a multi-scene video or a series
+- The user asks to "lock the look", "art-direct", build a "camera bible" or "project bible"
+- A character/mascot needs a locked visual + camera + voice identity across episodes (improve the Omni character)
+- Before generating prompts/storyboards for a project that should feel directed, not random
+</Use_When>
+
+<Do_Not_Use_When>
+- The user only wants a single one-off image or clip
+- Pure continuity/cast tracking is needed (that is the `story-bible` artifact, not this)
+- The user wants the low-level prompt packets directly (`vclaw video filmmaking-prompts`)
+</Do_Not_Use_When>
+
+## Core director principles
+
+1. Every visual decision serves the emotion. Camera, color, light, costume — all of it.
+2. Consistency is the foundation of a believable world; lock the visual language before production.
+3. Character design is character psychology — how someone looks tells us who they are before they speak.
+4. Color is information, not decoration. Every color choice carries meaning.
+5. The camera is a character. Where it moves, stays still, and what it shows is directorial intent.
+6. Constraint produces creativity. A locked grammar forces every scene to speak the same language.
+7. Be concise and production-ready: short headings, bullets, a short reason for every major choice. No story prose.
+
+## Workflow
+
+**Stage 0 — Intake.** Ask in one message: (1) the idea in 2–5 sentences — who, where, and what it should FEEL like; (2) any video reference whose visual DNA to extract; (3) any character/style references; (4) target format (teaser 10–30s / short 30–60s / sequence 1–3min); (5) preferred style (realistic / stylized / anime / hybrid / cinematic live-action). Summarize in 3 lines, then proceed.
+
+**Stage 1 — Author the blueprint.** Design all 8 sections below, working backward from the intended feeling. Use the camera-bible vocabulary (`references/video/camera-bible.md`) — shot sizes by emotional trigger, the two-temperature lighting technique, the 5-sensory-words rule (1 smell + 1 texture + 1 sound + 2 feelings) — and prefer the registry ids the engine knows (lighting: `golden-hour`, `night-fire`, `neutral-studio`, `chiaroscuro`, …; grades: `teal-orange`, `bleach-bypass`, `warm-nostalgia`, `cool-isolation`, …; movements: `static-locked`, `dolly-in`, `crane-up`, `whip-pan`, `vertigo`, …).
+
+**Stage 2 — Persist + verify.** Write the JSON to a file, then run the CLI. The composer auto-reads it; confirm with `vclaw video filmmaking-prompts`.
+
+## The `project-blueprint.json` shape (matches the schema exactly)
+
+```json
+{
+  "title": "Meet VideoClaw",
+  "visualIdentity": {
+    "aesthetic": "3D hyper-real caricature",
+    "influences": [{ "name": "Pixar", "borrowed": "soft global illumination" }],
+    "texture": "glossy toy-like surfaces", "scale": "intimate studio",
+    "timeOfDay": "bright daylight", "thesis": "looks like a friendly toy world, feels upbeat, lit clean"
+  },
+  "colorSystem": {
+    "colors": [{ "name": "lime", "where": "mascot body", "emotion": "energy", "hex": "#d4ed5b" }],
+    "kelvinRange": "5200-5600K", "warmShiftMeaning": "warmth/friendliness", "coolShiftMeaning": "focus/tech",
+    "contrast": "medium", "saturation": "pushed", "gradeId": "teal-orange"
+  },
+  "lightingGrammar": {
+    "keyDirection": "soft front-left", "quality": "soft", "shadowStrategy": "gentle, never harsh",
+    "practicals": "studio panels",
+    "signatureSetups": { "intimate": "soft wrap", "tension": "hard side key", "hero": "rim + bloom" }
+  },
+  "characters": [{
+    "name": "Clawbot", "role": "host", "visualType": "stylized 3D mascot",
+    "silhouette": "egg-shaped lime body", "signatureDetail": "antenna + round PHYSICAL blue eyes",
+    "palette": ["lime", "blue", "rust-orange"], "costume": "cream arms with rust joints",
+    "communicates": "friendly, approachable",
+    "voice": { "ageGender": "warm neutral", "timbre": "bright", "rhythm": "upbeat", "accent": "neutral",
+               "emotionalLeak": "excitement", "anchors": ["enthusiastic", "reassuring"] },
+    "cameraLanguage": { "power": "low-angle MCU", "vulnerability": "high-angle CU", "signature": "eye-level MS" }
+  }],
+  "environments": [{
+    "name": "studio", "type": "interior", "emotionalFunction": "safe, focused",
+    "anchors": ["white cyclorama", "soft panels", "floor reflection"], "scale": "contained",
+    "lightColor": "neutral 5600K",
+    "sensory": { "smell": "clean plastic", "texture": "smooth floor", "sound": "soft room tone", "feelings": ["calm", "curious"] }
+  }],
+  "cameraBible": {
+    "relationship": "friendly observer at human distance", "whenMoves": "gentle push-in on a reveal",
+    "whenLocked": "most talking beats", "dominantShots": ["ms", "mcu", "cu"],
+    "rareShots": [{ "shot": "ews", "when": "episode opener only" }],
+    "primaryAngles": ["eye-level"], "primaryMovements": ["static-locked", "dolly-in"],
+    "forbiddenMovements": ["whip-pan", "vertigo"], "focalFeel": "35-50mm natural",
+    "depthStrategy": "medium, subject sharp", "oneRule": "never a flat screen-face, always the 3D egg body"
+  },
+  "performanceRules": {
+    "actingStyle": "expressive but warm", "dialogueEnergy": "upbeat", "silenceUsage": "brief beats",
+    "intensityScale": "low-to-medium", "castingPattern": "one consistent host voice", "avoid": "monotone flatness"
+  },
+  "output": {
+    "runtimeSeconds": 60, "aspectRatio": "16:9", "motionStyle": "smooth, friendly",
+    "editingRhythm": "medium, benefit-led",
+    "vibeKeywords": ["upbeat", "friendly", "clean", "modern", "playful", "confident", "bright", "crisp"]
+  }
+}
+```
+
+All 8 top-level sections (`visualIdentity`, `colorSystem`, `lightingGrammar`, `characters`,
+`environments`, `cameraBible`, `performanceRules`, `output`) plus `title` are REQUIRED — the
+validator throws a single error listing any missing ones. `characters`/`environments` may be
+empty arrays. `palette` is capped to 3; voice `anchors` to 2. Use shot-size ids from the camera
+bible (`ews|ws|mws|ms|mcu|cu|ecu|two-shot|ots|pov|dutch|birds-eye|worms-eye`) and movement ids
+(`static-locked|dolly-in|dolly-out|pan|tilt-up|tilt-down|orbit|tracking|handheld|crane-up|whip-pan|vertigo`).
+
+## Persist + verify (the CLI handoff)
+
+```bash
+# 1. Write the JSON you authored to a file, then validate + persist it:
+vclaw video director-blueprint --project <slug> --from-json <path-to-blueprint.json> --write
+
+# 2. Confirm it is inherited by the scene packets (look for the "DIRECTOR — …" addendum
+#    and any forbidden-camera-movement issue):
+vclaw video filmmaking-prompts --project <slug>
+
+# Inspect the persisted blueprint at any time:
+vclaw video director-blueprint --project <slug> --show
+```
+
+Once persisted, `vclaw video filmmaking-prompts` **auto-reads** `artifacts/project-blueprint.json`
+and appends a prose `DIRECTOR — Palette / Look / Lighting / Subject / Atmosphere / Rule` block to
+every scene packet, and flags any forbidden camera movement. No extra flag is needed.
+
+<Example_Requests>
+- "art-direct the Clawbot intro series — lock the look and camera bible"
+- "build a project bible for this music video"
+- "make a director blueprint so every scene stays on-model"
+- "lock the camera grammar and forbidden moves for this project"
+</Example_Requests>
+
+## References
+- `references/video/camera-bible.md` — shot sizes, angles, movements (with Seedance syntax), lighting, grades, the two-temperature technique, the 5-sensory-words rule.
+- `references/video/ai-director-blueprint.md` — the full staged director master-prompt.
+- `references/video/multi-shot-framework.md` — the downstream multi-shot prompt framework + anti-patterns.
+- `docs/DIRECTOR_BLUEPRINT.md` — how the artifact is consumed by the pipeline.

package/skills/ai-filmmaking/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: ai-filmmaking
+description: |
+  Generate production-grade prompts for AI filmmaking the videoclaw way: an
+  8-shot Character Sheet to lock identity, a 9-panel Cinematic Storyboard Grid
+  with CAM/MOVE/MOOD annotation strips to lock the scene, and Seedance 2.0
+  video prompts in three reference variants to render each shot. Use when the
+  user wants to create an AI-generated film, short, music video, commercial,
+  trailer, or scene; asks for a storyboard, shot list, or cinematic prompts;
+  or describes a character or story they want to render visually — even if
+  they never say the word "prompt". Front door for the chained
+  character-sheet → storyboard-grid → seedance-packets workflow.
+---
+
+# AI Filmmaking (character sheet → storyboard grid → Seedance prompts)
+
+Chain three templates over a videoclaw project: a **Character Sheet** locks
+identity, a **9-panel Storyboard Grid** designs one continuous scene with clear
+camera logic, and **Seedance 2.0 packets** render each shot. The identity
+flows: locked character description → sheet → grid (CHARACTER LOCK) →
+packet (`@imageN` reference + SUBJECT LOCK). The CLI owns every template; this
+skill drives the existing commands in order and never re-derives their logic.
+
+Most users want all three in sequence. Some arrive mid-pipeline ("I have a
+character sheet, just give me Seedance prompts") — read the project state,
+figure out where they are, and deliver only what they need.
+
+**Spend note:** everything through Phase 3 is free, deterministic prompt
+generation — proceed without asking. Phase 4 (rendering video) costs real
+credits: confirm the plan with the user once before the first paid render,
+then proceed without re-asking; pause again only for a real scope change.
+
+## When to use this vs other skills
+
+- **`ai-filmmaking`** — the full prompting chain for a cinematic scene or film:
+  character sheets + storyboard grid + Seedance shot packets.
+- `character-ad` — a finished character-led ad via native Flow R2V (renders
+  video end-to-end; no storyboard grid).
+- `brand-agency` — full brand launch; use it for brand systems, this skill for
+  cinematic scene work.
+- `multi-shot-prompt` — standalone timecoded shot-sequence prompts without the
+  character-sheet/grid chain.
+- `movie-director` / `ai-director` — authoring the project visual bible
+  (Director Blueprint); `filmmaking-prompts` reads it back automatically.
+
+## Phase 0 — Intake
+
+Identify the gaps in the creative spec before generating anything. The minimum:
+genre/visual style, one sentence per lead character (age range, build,
+wardrobe, key prop), setting, the scene's emotional beat, aspect ratio
+(default `16:9`; `9:16` for vertical/social), and exclusions. Ask 2-3 sharp
+questions only if the brief is genuinely vague — if the user already wrote a
+paragraph of detail, just start.
+
+Set up the project (skip whatever already exists):
+
+```bash
+vclaw video init <slug> --mode storyboard          # or --mode director
+vclaw video brief --project <slug> --title "<title>" --intent "<one-line intent>"
+vclaw video storyboard --project <slug> \
+  --scene "<beat 1, one declarative sentence>" --scene "<beat 2>"   # one --scene per beat
+vclaw video character-add --project <slug> --name "<Name>" \
+  --description "<30-60 word identity description>"
+```
+
+`character-add` stores a text-only profile. When you will actually **render**
+the character (Flow / Go Bananas), create it as a reusable **Go Bananas library
+character** instead — `vclaw video character-auto-create` generates the
+portrait, registers the character in the Go Bananas account (so it's reusable
+and visible there), and imports it into the project:
+
+```bash
+# input JSON (array): [{ "name": "<Name>", "description": "<identity>",
+#   "style": "photorealistic cinematic portrait, real photographed person, not 3D/CGI" }, ...]
+vclaw video character-auto-create --project <slug> --input <cast.json>
+```
+
+> **Drive every step through `vclaw`** — never the raw go-bananas MCP, `curl`,
+> or hand-rolled `ffmpeg`. A one-off image is not a library character and won't
+> appear in the Go Bananas account; `character-auto-create` is.
+
+Character descriptions are the identity anchor for the whole pipeline:
+comma-separated identity-locking traits (age range, build, skin, hair, eyes,
+wardrobe in brief, key prop). **30-60 words is the target; over 100 is a
+failure** — the CLI errors on it. No scene effects, no atmosphere, no
+narrative damage: those belong in the shot prompts, not the identity.
+
+## Phase 1 — Character sheets (lock identity first)
+
+```bash
+vclaw video filmmaking-prompts --project <slug> --phase storyboard --write [--genre <id>] [--aspect-ratio 16:9]
+```
+
+`--write` persists `artifacts/filmmaking-prompts.json` (character-sheet prompts
++ the storyboard-grid panel spec); Phase 2's `storyboard-grid` reads it, so the
+write is required here, not optional.
+
+`characterSheetPrompts` in the output carries one 8-shot sheet prompt per
+character (top row: four full-body views; bottom row: four matching close-ups;
+neutral studio lighting; simple background). Two modes, picked automatically:
+
+- **Mode A (reference image attached):** the image carries the visual — the
+  prompt only states the rendering style. Do not re-describe the character in
+  prose.
+- **Mode B (description only):** the stored 30-60 word description drives the
+  sheet.
+
+Render each sheet with an image model (`vclaw video gen-image` /
+go-bananas; GPT Image 2 for the highest sheet fidelity), then attach the
+results as character reference assets. Verify each rendered sheet by content
+(look at it) before moving on; report a failed render plainly.
+
+## Phase 2 — Storyboard grid (lock the scene)
+
+Two steps — the spec sheet, then the cinematic grid:
+
+```bash
+# 1. deterministic shot-spec sheet: locks panel order + camera language
+#    (reads the artifacts/filmmaking-prompts.json that Phase 1 --write persisted)
+vclaw video storyboard-grid --project <slug> --output artifacts/grid-spec.png
+
+# 2. the storyboardGridPrompt from Phase 1 is the image prompt for the REAL
+#    cinematic grid — render it with openai-gpt-image-2 (always, for
+#    multi-panel composites), then re-attach it:
+vclaw video filmmaking-prompts --project <slug> --phase video \
+  --storyboard-grid <rendered-grid.png> --write
+```
+
+The grid prompt already enforces the discipline: one continuous scene across
+sequential panels, CHARACTER LOCK with one tight sentence per character,
+CAM/MOVE/MOOD annotation strips as 2-6 word uppercase slug lines (VOICE for
+vlog/dialogue genres, STYLE for action — picked by `--genre`), framing that
+varies wide → medium → close and climaxes in the final third, and the aspect
+ratio on every panel. Photoreal faces trip provider content filters when the
+grid is used as a `reference_image` — pass `--no-faces` to render it in the
+silhouette register when that matters.
+
+## Phase 3 — Seedance packets + lint
+
+The `--write` run above persists `artifacts/filmmaking-prompts.json` with one
+Seedance packet per scene. The variant is picked from what's attached:
+text-driven (no grid), grid-reference (grid only), or character-sheets-plus-
+storyboard-grid (both — highest fidelity). `@imageN` numbering is unique per
+reference and renumbers automatically. Defaults baked in: 15 seconds, NO
+MUSIC, aspect ratio stated on every shot, the single-full-frame guard on every
+grid-bearing packet (otherwise the grid renders as a moving 9-panel
+split-screen).
+
+Spoken dialogue goes through the dialogue flags — never hand-edit it into a
+packet:
+
+```bash
+vclaw video filmmaking-prompts --project <slug> --phase video \
+  --storyboard-grid <grid.png> \
+  --dialogue 'Asha: This is the best gift I ever received. [excited] || He: I was not sure you would open it.' \
+  --emotion-cues --write
+```
+
+The second speaker renders as `replies:` (consecutive-order speech), and a
+speaker matching a stored character is emitted as their visual descriptor,
+never the proper name. `--dialogue` is a blanket over every scene; to put a
+line only where it happens, use the repeatable
+`--dialogue-scene '<sceneIndex>:<speaker>: <line> [|| ...]'` (a scene with its
+own entry ignores the blanket). For a multi-scene piece, prefer per-scene so an
+establishing shot doesn't carry the climax's exchange.
+
+Then lint, and fix anything it flags before delivering:
+
+```bash
+vclaw video prompt-lint --project <slug>
+```
+
+Exit 0 means clean; non-zero means error-severity findings (missing blocks,
+grid guard, >100-word identity descriptions). Framing-progression and
+annotation-slug advisories are warnings — surface them to the user with the
+fix, don't silently rewrite their panels.
+
+Deliver each prompt in its own fenced code block, labeled above the block
+(`### Panel 3 — Seedance prompt`); commentary stays outside the blocks. Fill
+every bracket — never ship `[PLACEHOLDER]` text.
+
+## Phase 4 — Render (optional, paid)
+
+Only after the user confirms spend:
+
+```bash
+vclaw video readiness --project <slug>
+vclaw video produce --project <slug> --dry-run     # plan first, always
+vclaw video produce --project <slug>               # real spend
+# optional music bed — flowmusic is the DEFAULT backend (free for us):
+vclaw video soundtrack --project <slug> --backends flowmusic --confirm-spend \
+  --prompt "<mood, instrumental, no vocals>" && \
+  vclaw video soundtrack --project <slug> --select flowmusic
+# stage the finished cut UNDER the project, then build the preview:
+#   projects/<slug>/final/{videos,images,audio}  (the portal scans there, NOT the workspace root)
+vclaw video portal --project <slug> --surface preview
+```
+
+On the `seedance-direct` route, lock character identity through the Asset
+Library first (`vclaw video seedance-register-assets`) — raw photoreal face
+URLs are rejected by moderation and don't hold identity. Director mode blocks
+before submission until the storyboard is approved; that gate is the point —
+don't work around it.
+
+## Standing rules
+
+- Reuse each character description **verbatim** in every template that
+  features that character — the text is the identity anchor; never paraphrase
+  between templates.
+- Visual descriptors, never proper names, inside prompt bodies.
+- Short, evocative writing beats exhaustive prose: panel beats are slug lines
+  ("Viper lunges, palm strike to sternum"), not novelist sentences.
+- Each reference image gets its own `@imageN` — two sheets are never both
+  `@image1`, or the characters fuse.
+- 15 seconds per Seedance generation unless the user explicitly asks for
+  less; NO MUSIC unless they ask for it.
+- Verify rendered images/clips by content, not exit codes, and report what
+  actually rendered — a failure is stated plainly, never papered over.
+- Drive every step through `vclaw` commands — never the raw go-bananas MCP,
+  `curl`, or hand-rolled `ffmpeg`. The project (and the Go Bananas library) only
+  see what `vclaw` writes.
+- Stage finals under `projects/<slug>/final/{videos,images,audio}` — the portal
+  scans there, not a `final/` at the workspace root, or the preview is empty.
+- Verify at the surface the user sees: after building the portal, confirm the
+  preview actually shows the media before declaring it done.
+- Music: `flowmusic` is the default music backend (free); don't reach for
+  lyria3/lyria first.
+
+## Resume
+
+On re-entry, read `projects/<slug>/` (characters, storyboard,
+`artifacts/filmmaking-prompts.json`, attached grid) and report which phases
+are complete, then continue from the first incomplete phase. Don't regenerate
+what's already locked — regenerating a character sheet breaks every
+downstream reference to it.
+
+See `docs/CLI_REFERENCE.md` for full flags and
+`references/video/multi-shot-framework.md` (Anti-patterns) for the
+production-learned failure modes this pipeline guards against.

package/skills/ai-slop-cleaner/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: ai-slop-cleaner
+description: Run an anti-slop cleanup/refactor/deslop workflow
+---
+
+# AI Slop Cleaner Skill
+
+Reduce AI-generated slop with a regression-tests-first, smell-by-smell cleanup workflow that preserves behavior and raises signal quality.
+
+## When to Use
+
+Use this skill when:
+- A code path works but feels bloated, noisy, repetitive, or over-abstracted
+- A user asks to “cleanup”, “refactor”, or “deslop” AI-generated output
+- Follow-up implementation left duplicate code, dead code, weak boundaries, missing tests, or unnecessary wrapper layers
+- You need a disciplined cleanup workflow without broad rewrites
+
+## GPT-5.4 Guidance Alignment
+
+- Keep outputs concise and evidence-dense unless risk or the user requests more detail.
+- Treat newer user instructions as local workflow updates without discarding earlier non-conflicting constraints.
+- Keep using inspection, tests, diagnostics, and verification until the cleanup is grounded.
+- Proceed automatically through clear, reversible cleanup steps; ask only when a choice materially changes scope or behavior.
+
+## Scoped File Lists and Ralph Workflow
+
+- This skill can accept a **file list scope** instead of a whole feature area.
+- When the caller provides a changed-files list (for example, Ralph session-owned edits), keep the cleanup strictly bounded to those files.
+- In the **Ralph workflow**, the mandatory deslop pass should run this skill on Ralph's changed files only, in standard mode unless the caller explicitly requests otherwise.
+
+## Procedure
+
+1. **Lock behavior with regression tests first**
+   - Identify the behavior that must not change
+   - Add or run targeted regression tests before editing cleanup candidates
+   - If behavior is currently untested, create the narrowest test coverage needed first
+
+2. **Create a cleanup plan before code**
+   - List the specific smells to remove
+   - Bound the pass to the requested files/scope
+   - If a file list scope is provided, keep the pass restricted to that changed-files list
+   - Order fixes from safest/highest-signal to riskiest
+   - Do not start coding until the cleanup plan is explicit
+
+3. **Categorize issues before editing**
+   - **Duplication** — repeated logic, copy-paste branches, redundant helpers
+   - **Dead code** — unused code, unreachable branches, stale flags, debug leftovers
+   - **Needless abstraction** — pass-through wrappers, speculative indirection, single-use helper layers
+   - **Boundary violations** — hidden coupling, leaky responsibilities, wrong-layer imports or side effects
+   - **Missing tests** — behavior not locked, weak regression coverage, gaps around edge cases
+
+4. **Execute passes one smell at a time**
+   - **Pass 1: Dead code deletion**
+   - **Pass 2: Duplicate removal**
+   - **Pass 3: Naming/error handling cleanup**
+   - **Pass 4: Test reinforcement**
+   - Re-run targeted verification after each pass
+   - Avoid bundling unrelated refactors into the same edit set
+
+5. **Run quality gates**
+   - Regression tests stay green
+   - Lint passes
+   - Typecheck passes
+   - Relevant unit/integration tests pass
+   - Static/security scan passes when available
+   - Diff stays minimal and scoped
+   - No new abstractions or dependencies unless explicitly required
+
+6. **Finish with an evidence-dense report**
+   - Changed files
+   - Simplifications made
+   - Tests/diagnostics/build checks run
+   - Remaining risks
+   - Residual follow-ups or consciously deferred cleanup
+
+## Output Format
+
+```text
+AI SLOP CLEANUP REPORT
+======================
+
+Scope: [files or feature area]
+Behavior Lock: [targeted regression tests added/run]
+Cleanup Plan: [bounded smells and order]
+
+Passes Completed:
+1. Pass 1: Dead code deletion - [concise fix]
+2. Pass 2: Duplicate removal - [concise fix]
+3. Pass 3: Naming/error handling cleanup - [concise fix]
+4. Pass 4: Test reinforcement - [concise fix]
+
+Quality Gates:
+- Regression tests: PASS/FAIL
+- Lint: PASS/FAIL
+- Typecheck: PASS/FAIL
+- Tests: PASS/FAIL
+- Static/security scan: PASS/FAIL or N/A
+
+Changed Files:
+- [path] - [simplification]
+
+Remaining Risks:
+- [none or short deferred item]
+```
+
+## Scenario Examples
+
+**Good:** The user says `continue` after tests already lock behavior and the next smell pass is clear. Continue with the next bounded cleanup pass.
+
+**Good:** The user narrows the scope to a specific file after planning. Keep the regression-tests-first workflow, but apply the new scope locally.
+
+**Bad:** Start rewriting architecture before protecting behavior with tests.
+
+**Bad:** Collapse multiple smell categories into one large refactor with no intermediate verification.