videoclaw 3.0.0-alpha.1

package/skills/video-framework/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: video-framework
+description: Unified vclaw-native front door for creating videos by routing across copy, create, narrated, presentation, long-form, film, and UGC workflows over the canonical `vclaw video` commands.
+---
+
+<Purpose>
+Video Framework is the flagship vclaw-native video production surface. It gives users one place to start — “make me a video” — and then internally routes to the appropriate workflow mode while keeping the public experience inside the `vclaw` CLI.
+</Purpose>
+
+<Use_When>
+- The user wants to make a video, copy an ad, generate a product video, create a narrated explainer, restyle a presentation, or run a longer-form cinematic workflow
+- The user wants a unified vclaw-native experience instead of raw Python/Bun scripts
+- The task should run through the canonical `vclaw video` pipeline commands
+</Use_When>
+
+<Do_Not_Use_When>
+- The user only wants a single static image
+- The user wants low-level backend debugging on a specific legacy script without the vclaw product surface
+- The user is asking for a generic non-video orchestration task
+</Do_Not_Use_When>
+
+<Current_Product_Boundary>
+This skill is the new front door. It should:
+- classify requests into internal modes such as COPY, CREATE, COPY NARRATED, PRESENTATION, LONG-FORM, FILM, and UGC
+- gather missing inputs and preferences
+- prefer vclaw-native orchestration and the on-disk `projects/<slug>/` state
+- drive the canonical `vclaw video` commands instead of exposing raw scripts directly
+
+Initial migration direction:
+- `veo-cli` is treated as a backend/service adapter source
+- the imported `skills/video-replicator/` tree is treated as the legacy
+  workflow/phase-engine reference set
+- the public UX should not leak `.claude` path assumptions, printed MCP commands, or raw Python/Bun entrypoints
+- CLI planning surface: prefer `vclaw studio --dry-run` when the user wants a guided menu-like experience. Studio should produce the command plan; this skill remains the agent reasoning layer that interprets creative intent.
+
+Reference guides:
+- `references/checkpoint-protocol.md`
+- `references/stage-directors.md`
+- repo-local follow-on skills:
+  - `skills/video-analyze-template/SKILL.md`
+  - `skills/video-clone-ad/SKILL.md`
+  - `skills/video-storyboard/SKILL.md`
+  - `skills/character-creator/SKILL.md` — REQUIRED SUB-SKILL for any cast/character work (drives `vclaw video character-auto-create`)
+</Current_Product_Boundary>
+
+<Example_Requests>
+- "make me a product ad video from these assets"
+- "copy this ad with a new subject"
+- "create a narrated explainer video"
+- "turn this presentation into an animated video"
+- "start a cinematic film workflow for this concept"
+</Example_Requests>
+
+## Intake mode (formerly `creative-brief`)
+
+When the user's request is too vague to route directly — they describe
+the video in creative terms ("I want a luxury resort ad", "make
+something like a Nike spot", "short film about loneliness") rather than
+in pipeline / CLI terms — drop into intake mode and ask the 7 questions
+below. Ask one at a time, stop after each answer, and skip questions
+whose answer is already clear from the original request.
+
+> **Hard rule:** do NOT generate any video, image, or audio until the
+> user has reviewed and approved the full plan that comes out of intake.
+> Show the complete command set first, then ask "Does this plan look
+> right? Shall I proceed?" before any execution.
+
+<!-- Folded in from skills/creative-brief/SKILL.md in Slice 2 (2026-05-25). -->
+
+### The 7 questions
+
+1. **What is this for?** "What are we making? (e.g. product ad, brand
+   film, social reel, explainer, short film)" — maps to pipeline mode
+   selection and scene count.
+2. **What's the feeling / vibe?** "Describe the vibe in 3 words or
+   less. Or name a reference (brand, film, director)." — maps to
+   SEALCAM Metatokens, Go Bananas style, color-grade preset. See
+   `references/visual-styles.md` (was folded from creative-brief).
+3. **What assets do you have?** "Do you have: product images, character
+   references, a logo, a reference video to copy, or starting from
+   scratch?" — maps to:
+   - Product images → `--backend seedance --mode frames-to-video` + product_ref
+   - Character refs → Go Bananas `character_id` + `--chained`
+   - Reference video → COPY mode (analyze → rewrite prompts)
+   - Scratch → `--mode text-to-video` or generated storyboard
+4. **How long and how fast?** "Total duration? Pacing: slow / medium /
+   fast?" — maps to scene count, quality flag, backend. See
+   `references/pacing-guide.md`.
+5. **Camera style?** "Camera energy: steady & cinematic / fluid &
+   handheld / dynamic & whippy / intimate close-ups / epic & sweeping" —
+   maps to journey-template, SEALCAM C-layer, and transitions. See
+   `references/camera-archetypes.md`.
+6. **Audio?** "Audio plan: narration (voiceover) / presenter talking to
+   camera / background music only / sound effects only / no audio" —
+   maps to `--lip-sync`, `--voiceover`, `vclaw video create`,
+   `--audio-ref`. See `references/audio-strategy.md`.
+7. **Backend preference?** "Speed vs quality: Fast (`veo-3.1-fast`,
+   default) / Quality (`veo-3.1-quality`, 8s-only) / Lite
+   (`veo-3.1-lite`, cheapest) / Free (`veo-3.1-lite-low-priority`,
+   Ultra plan only) / Omni Flash (`omni-flash`, audio-native voice
+   narration)" — maps to `--quality fast|quality|lite|free|omni-flash`
+   and `--backend useapi|direct|seedance`. Credit reference:
+   `vclaw-cli/docs/GOOGLE-FLOW-V1.md`.
+
+### Backend decision table
+
+| Situation | Backend | Mode |
+|-----------|---------|------|
+| Product ad, has product images | `seedance` | `frames-to-video` |
+| Character-driven, has character refs | `useapi` | `frames-to-video` + `--chained` |
+| Copy a reference video | `useapi` | COPY mode |
+| Lip-sync / talking presenter | `seedance` | `audio-lipsync` |
+| BGM clone from audio reference | `seedance` | `omni_reference` + `--audio-ref` |
+| Pure concept, no assets | `useapi` | `text-to-video` |
+| Audio-native / voice narration brief | `useapi` | `omni-flash` |
+| Budget-sensitive / development | `direct` | any |
+
+### After all 7 answers: present the plan, then dispatch
+
+Map the answers onto a concrete `vclaw video brief` invocation along
+the lines of:
+
+```
+vclaw video brief \
+  --project <slug> \
+  --title "<concept>" \
+  --intent "<one-sentence brief>" \
+  --aspect-ratio <16:9|9:16|1:1> \
+  --quality <fast|quality|lite|free|omni-flash>
+```
+
+Then show the user the full plan in this shape:
+
+```
+## Your Video Brief
+
+**Concept**: [1-sentence summary]
+**Duration**: [N]s across [N] scenes
+**Style**: [vibe words] → [metatokens]
+**Camera**: [archetype] → [journey-template or SEALCAM C-layer]
+**Audio**: [plan] → [TTS / lipsync / music flags]
+**Backend**: [backend] ([reason])
+
+## Scene Breakdown
+Scene 1: [description + camera move]
+Scene 2: [description + camera move]
+...
+
+## Commands
+
+### Phase 3: Generate images
+vclaw video gen-image --project "{slug}" --prompt "..." --kind prop
+# for cast/characters, delegate to the character-creator sub-skill → vclaw video character-auto-create
+
+### Phase 4: Generate videos
+vclaw video create "[intent expanded into scene prompts]" \
+  --project "{slug}" \
+  --platform [platform] \
+  --aspect-ratio [16:9|9:16|1:1] \
+  --quality [fast|quality] \
+  --audio [on|off] \
+  --execute
+
+### Phase 5: Audio
+[Narration / post-production pass if needed]
+
+### Phase 6: Stitch
+vclaw video remix-narrated --project "{slug}"
+```
+
+Ask **"Does this plan look right? Shall I proceed?"** and only then
+hand off to the regular video-framework dispatch (COPY / CREATE /
+NARRATED / PRESENTATION / LONG-FORM / FILM / UGC).
+
+### Sound direction (required for every scene)
+
+Every scene prompt must end with a sound direction in the mandatory
+format:
+
+```
+Sound: [specific SFX matching the visual]. [No music / No background music.]
+```
+
+Examples:
+- `"Sound: ocean waves crashing, distant seagulls. No music."`
+- `"Sound: product unboxing crinkle, soft tap sounds. No background music."`
+- `"Sound: crowd cheering, sneaker squeak on court. No background music."`
+
+Generic instructions like "ambient sounds" are insufficient — be
+specific to the visual.
+
+### Intake reference files
+
+The intake question set is backed by reference notes in this skill's
+`references/` directory (folded in from the former `creative-brief`
+skill in Slice 2):
+
+- `references/visual-styles.md` — vibe/style → SEALCAM Metatokens + Go Bananas presets
+- `references/camera-archetypes.md` — 5 camera archetypes → CLI flags + transition IDs
+- `references/pacing-guide.md` — duration × pace → scene count + quality heuristics
+- `references/audio-strategy.md` — voice type decision tree → TTS / lipsync / music flags

package/skills/video-portfolio-ops/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: video-portfolio-ops
+description: Portfolio operations workflow for vclaw-video-core. Use when managing multiple video projects, reporting blocked work, exporting CSV/Obsidian dashboards, assigning metadata, or checking portfolio-level review and publish readiness.
+---
+
+# Video Portfolio Ops
+
+Use this skill when the question is about the whole production slate rather than
+one project. It turns the advanced reporting commands into a repeatable operator
+loop.
+
+## Daily Operator Loop
+
+```bash
+vclaw video metrics [--root <path>]
+vclaw video next-actions [--root <path>]
+vclaw video doctor-portfolio [--root <path>]
+vclaw video report [--root <path>]
+vclaw video report-snapshot [--root <path>]
+vclaw video sync-obsidian [--root <path>] [--output-dir <path>]
+```
+
+Use `metrics` for the headline, `next-actions` for the work queue,
+`doctor-portfolio` for health, `report` for machine-readable state, snapshots
+for history, and Obsidian sync for the human dashboard.
+
+## Spreadsheet Handoff
+
+```bash
+vclaw video export-csv [--root <path>] [--output-dir <path>]
+```
+
+CSV exports must carry the same project truth as the CLI:
+
+1. `reviewReportVerdict`
+2. `reviewPublishReady`
+3. stale review state
+4. next stage
+5. owner, priority, due date, tags, blockers, and blocked reason
+
+Do not tell an operator that a project is ready to publish unless the exported
+state agrees with `status` and `review-report.json`.
+
+## Triage And Ownership
+
+Use metadata to make the queue actionable:
+
+```bash
+vclaw video set-meta --project <slug> \
+  --owner <name> \
+  --priority high \
+  --due YYYY-MM-DD \
+  --tag <value> \
+  --blocked-by <slug> \
+  --blocked-reason "<reason>"
+```
+
+Then rerun:
+
+```bash
+vclaw video workload [--root <path>]
+vclaw video dependencies [--root <path>]
+vclaw video next-actions [--root <path>]
+```
+
+## History And Change Review
+
+For portfolio reviews, create and compare snapshots:
+
+```bash
+vclaw video report-snapshot [--root <path>]
+vclaw video report-history [--root <path>]
+vclaw video report-diff [--root <path>] --from <snapshot-path> --to <snapshot-path>
+vclaw video trends [--root <path>]
+```
+
+Use this when proving whether a release, cleanup pass, or production push
+improved the slate instead of only changing one project.
+
+## Blockers
+
+Escalate only when the next action needs an external provider, irreversible
+deletion/archive cleanup, or publishing outside the repo. Otherwise, repair the
+local artifact, metadata, or docs path and rerun the loop.

package/skills/video-post/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: video-post
+description: Post-production workflow for clean-room VideoClaw outputs. Verify final renders, create social variants, extract thumbnails, build loop-friendly cuts, and archive finished projects.
+---
+
+# Video Post
+
+Use this skill after a project has produced a final render and needs packaging
+for review, publishing, or archive.
+
+## When To Use
+
+Trigger on:
+
+- "make a vertical version"
+- "verify this final render"
+- "generate a thumbnail"
+- "archive this project"
+- "what do I do after render"
+
+## Scope
+
+This skill is intentionally generic and repo-local.
+
+- it works against any final `.mp4`
+- it prefers `ffmpeg` and `ffprobe`
+- it does not assume a fixed project root
+- it complements `movie-director` and `video-framework`
+
+## Standard Sequence
+
+1. Verify the source output.
+2. Generate platform variants as needed.
+3. Extract or annotate a thumbnail.
+4. Archive the project once deliverables are stable.
+
+## Verify
+
+```bash
+vclaw video verify-final --file /path/to/final.mp4
+vclaw video verify-final --project <slug> --root <path>
+```
+
+This returns machine-readable metadata plus a midpoint review frame.
+
+## Variants
+
+### Vertical
+
+```bash
+vclaw video make-vertical --file input.mp4 [--output output-vertical.mp4]
+vclaw video make-vertical --project <slug> [--root <path>] [--output output-vertical.mp4]
+```
+
+### Square
+
+```bash
+vclaw video make-square --file input.mp4 [--output output-square.mp4]
+vclaw video make-square --project <slug> [--root <path>] [--output output-square.mp4]
+```
+
+### Loop
+
+```bash
+vclaw video make-loop --file input.mp4 [--output output-loop.mp4]
+vclaw video make-loop --project <slug> [--root <path>] [--output output-loop.mp4]
+```
+
+## Thumbnail
+
+```bash
+vclaw video thumbnail --file input.mp4 [--output thumbnail.jpg]
+vclaw video thumbnail --file input.mp4 --output thumbnail.jpg --text "Hook Line"
+vclaw video thumbnail --project <slug> [--root <path>] [--text "Hook Line"]
+```
+
+If a title is supplied, the command attempts a simple `drawtext` overlay and
+falls back to exporting a clean frame when that filter is unavailable.
+
+## Archive
+
+```bash
+vclaw video archive-project --project <slug> [--root <path>]
+vclaw video archive-project --project <slug> [--root <path>] [--archive-dir <path>] [--cleanup]
+```
+
+## Notes
+
+1. Verify before generating variants so bad source renders do not propagate.
+2. Keep post outputs next to the project or in a dedicated delivery folder.
+3. Archive only once the project state and outputs are reproducible.
+
+## Related Skills
+
+- `skills/video-framework/SKILL.md`
+- `skills/movie-director/SKILL.md`
+- `skills/video-thumbnail-lab/SKILL.md`

package/skills/video-production-handoff/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: video-production-handoff
+description: Production handoff workflow for vclaw-video-core projects. Use when a video project needs to move from create/storyboard/assets into Review UI, review-autopilot, status, doctor-project, publish readiness, or operator handoff with canonical review-report truth.
+---
+
+# Video Production Handoff
+
+Use this skill when the operator or agent needs to decide whether a VideoClaw
+project is ready for execution, review, publish, or the next human handoff.
+
+This is a workflow skill, not a command wrapper. Prefer it after
+`video-framework`, `movie-director`, or `video-storyboard` has created or
+updated a project.
+
+## Core Rule
+
+Publish handoff is ready only when `review-report.json` has:
+
+1. `verdict: "pass"`
+2. `metrics.publishReady: true`
+
+Do not infer readiness from local UI checkboxes, a stale checkpoint, a publish
+artifact, or a legacy pass verdict without `metrics.publishReady`.
+
+## Standard Flow
+
+```bash
+vclaw video status --project <slug> [--root <path>]
+vclaw video next-actions [--root <path>]
+vclaw video doctor-project --project <slug> [--root <path>]
+```
+
+If the project needs visual handoff decisions:
+
+```bash
+vclaw video review-ui --project <slug> [--root <path>]
+```
+
+If completed storyboard still candidates already exist and the operator wants an
+agent-driven handoff:
+
+```bash
+vclaw video review-autopilot --project <slug> [--root <path>]
+```
+
+Then verify the same truth from the CLI:
+
+```bash
+vclaw video status --project <slug> [--root <path>]
+vclaw video doctor-project --project <slug> [--root <path>]
+vclaw video plan --project <slug> [--root <path>]
+```
+
+## Review Path Selection
+
+- Use `review-ui` when a human needs to inspect or fix storyboard stills,
+  character references, artifact-backed 4K handoff assets, or final assembly
+  checks.
+- Use `review-autopilot` only when completed storyboard still candidates already
+  exist and an agent should lock the best available handoff.
+- Use `video review --verdict pass` only when equivalent review evidence already
+  exists outside the browser station.
+- Use `video portal` to generate the standardized HTML handoff surfaces from the
+  on-disk project instead of hand-writing them per project:
+
+  ```bash
+  vclaw video portal --project <slug> --surface client-review [--client <name>] [--run <id>]
+  vclaw video portal --project <slug> --surface preview [--run <id>]
+  ```
+
+  `--surface client-review` is the lightweight client approve/decline/comment
+  page; `--surface preview` is the polished final showcase. The `preview`
+  surface auto-discovers a project soundtrack (an explicit `soundtrack`/`audio`
+  field in `project.json`, else the first project-local audio asset) and renders
+  an inline `<audio>` player, and every production image is lightbox-enabled
+  (click to view full screen). Ship a surface with `video publish-preview`.
+
+## Expected Outputs
+
+Successful production handoff should leave:
+
+1. `projects/<slug>/artifacts/review-ui-ledger.json`
+2. `projects/<slug>/artifacts/scene-selection.json`
+3. `projects/<slug>/artifacts/post-plan.json`
+4. `projects/<slug>/artifacts/review-report.json`
+5. checkpoint state that makes `status` and `doctor-project` agree
+
+For portfolio handoff, also use:
+
+```bash
+vclaw video metrics [--root <path>]
+vclaw video report [--root <path>]
+vclaw video export-csv [--root <path>]
+vclaw video sync-obsidian [--root <path>]
+```
+
+CSV and Obsidian surfaces should expose the same `reviewReportVerdict` and
+`reviewPublishReady` truth as `status`.
+
+## Verification
+
+Before reporting production readiness, run the smallest proof that covers the
+change:
+
+```bash
+npm run check:release-readiness-lite
+```
+
+For docs-only or skill-only edits, also run:
+
+```bash
+npm run check:cleanroom-docs
+npm pack --dry-run --json
+git diff --check
+```
+
+Keep generated verification artifacts separate from source changes. Local
+`outputs/`, `.playwright-mcp/`, Review UI screenshots, nested project outputs,
+and `.tgz` package archives should stay ignored unless a fixture refresh is
+explicitly intentional.
+
+## Stop Conditions
+
+Stop and report a blocker only when:
+
+1. `doctor-project` reports malformed or missing canonical artifacts that cannot
+   be repaired from local context.
+2. provider execution would require external production action or credentials.
+3. the next step is destructive, such as deleting a project, clearing outputs, or
+   publishing to npm/Homebrew.

package/skills/video-release-readiness/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: video-release-readiness
+description: Release-readiness workflow for vclaw-video-core. Use when preparing a local source checkout, package dry-run, npm release handoff, or verification report for the video CLI, Review UI, skills, docs, and generated-artifact boundaries.
+---
+
+# Video Release Readiness
+
+Use this skill when the repo needs a release handoff, packaging check, or
+confidence report. This is a verification workflow, not a publish command.
+
+Do not publish to npm, Homebrew, GitHub releases, or any external production
+channel unless the user explicitly asks for that external action.
+
+## Release Gate
+
+Run the fast all-in-one local gate first:
+
+```bash
+npm run check:release-readiness-lite
+```
+
+That gate should build once, run the Node test suite, execute the main smoke
+checks, run the isolated image-storyboard E2E, and verify release guardrails.
+
+If the change is narrower, keep the focused checks as supporting evidence:
+
+```bash
+npm run build
+npm test
+npm run check:cleanroom-docs
+npm run check:skill-frontdoor
+npm pack --dry-run --json
+git diff --check
+```
+
+## Package Shape
+
+Before a handoff, prove the package ships:
+
+1. `dist/cli/`
+2. `dist/video/`
+3. `tmp/review-station/index.html`
+4. `docs/*.md` and `docs/assets/*`
+5. `schemas/`
+6. `skills/README.md`, `skills/catalog.json`, and `skills/*/SKILL.md`
+
+Also prove it excludes:
+
+1. `projects/`
+2. `src/tests/`
+3. `dist/tests/`
+4. generated `.tgz` archives
+5. local verification output such as `.playwright-mcp/` and `outputs/`
+
+## Review Truth
+
+Release readiness must preserve the same publish truth everywhere:
+
+1. `review-report.json` has `verdict: "pass"`
+2. `review-report.json` has `metrics.publishReady: true`
+3. `status`, `doctor-project`, `next-actions`, Review UI, CSV, and Obsidian
+   surfaces derive from that same truth
+
+If a UI label, CLI next action, or report field disagrees, treat it as a release
+blocker until the canonical artifact or derived surface is fixed.
+
+## Source Checkout Vs Installed CLI
+
+When verifying from this repo, use source checkout commands:
+
+```bash
+node dist/cli/vclaw.js video providers
+node dist/cli/vclaw.js video plan --project <slug>
+```
+
+When writing installed-user handoff docs, use:
+
+```bash
+vclaw video providers
+vclaw video plan --project <slug>
+```
+
+Do not mix these two contexts without explaining the difference.
+
+## Evidence To Report
+
+Report concise evidence:
+
+1. changed files
+2. checks run and pass/fail status
+3. package dry-run inclusion/exclusion result
+4. Review UI and CLI truth-alignment result when relevant
+5. remaining risks or untested external-production paths