videoclaw 3.0.0-alpha.1

package/docs/PROVIDER_PLATFORM.md

@@ -0,0 +1,195 @@
+# Provider Platform
+
+This doc describes `videoclaw`'s provider/transport architecture as of
+2026-05-29, after the Phase 1c schema upgrade, the Phase 5b Runway port,
+and the Dreamina (Seedance 2.0 via useapi.net) route.
+
+## Routes at a glance
+
+| Route | Maturity | Native transport | Built-in adapter | Required env |
+|---|---|---|---|---|
+| `veo-useapi` | production | `native-veo.ts` (drives the local `vclaw-cli` Bun package) | `vclaw-provider-adapter --route veo-useapi` | `USEAPI_API_TOKEN`, `USEAPI_ACCOUNT_EMAIL` |
+| `seedance-direct` | production | `native-seedance.ts` (uses `SUTUI_API_KEY`) | `vclaw-provider-adapter --route seedance-direct` | `SUTUI_API_KEY` |
+| `runway-useapi` | production | `native-runway.ts` (pure Node fetch+fs) | `vclaw-provider-adapter --route runway-useapi` | `USEAPI_API_TOKEN`, `USEAPI_ACCOUNT_EMAIL` |
+| `dreamina-useapi` | production | `native-dreamina.ts` (pure Node fetch+fs) | `vclaw-provider-adapter --route dreamina-useapi` | `USEAPI_API_TOKEN`, `VCLAW_DREAMINA_ACCOUNT` (optional `VCLAW_DREAMINA_REGION` default `CA`, `VCLAW_DREAMINA_MODEL` default `seedance-2.0`) |
+
+`dreamina-useapi` reuses the **same** `USEAPI_API_TOKEN` as `runway-useapi`
+(no new token). Like Runway, Seedance content moderation rejects real human
+faces — describe stylized/illustrated characters or seed from a generated
+start frame.
+
+## Descriptor schema
+
+`src/video/provider-platform/registry.ts` defines `DEFAULT_PROVIDER_REGISTRY`
+as an array of `VideoProviderDescriptor` (from `./types.ts`). Each route
+descriptor has:
+
+```typescript
+interface VideoProviderDescriptor {
+  id: ProviderRouteId;                     // 'veo-useapi' | 'seedance-direct' | ...
+  provider: VideoProvider;                 // 'veo' | 'runway' | 'seedance'
+  displayName: string;
+  path: ProviderPath;                      // 'direct' | 'useapi'
+  summary: string;
+  controls: ProviderControl[];             // 'audio', 'first-frame', 'last-frame',
+                                           // 'reference-images', 'camera-grammar', ...
+  operationSupport: Array<{
+    operation: VideoOperationKind;         // 'text-to-video', 'image-to-video', ...
+    aspectRatios: NormalizedAspectRatio[];  // 'landscape' | 'portrait'
+    notes?: string[];                      // per-operation gotchas
+    maxReferenceImages?: number;
+  }>;
+  routingHints: {
+    latencyClass: 'low' | 'medium' | 'high';
+    costClass: 'free' | 'paid' | 'premium';
+    trustClass: 'direct' | 'aggregated';
+    preferredWorkflows: VideoWorkflowKind[];
+  };
+  escapeHatches?: Array<{
+    name: string;
+    description: string;
+    options: Array<{ name: string; description: string }>;
+  }>;
+  notes?: string[];                        // free-form per-route notes
+}
+```
+
+This rich schema came from videoclaw during the Phase 1c merge. It replaced
+the flat `supportedOperations[]` shape that `vclaw-video-core` had, and
+lets the router make capability-aware decisions per operation × aspect ratio
+rather than per route as a whole.
+
+## Routing
+
+`src/video/provider-platform/router.ts` exposes
+`chooseVideoProviderRoute(request, policy)`. Given a routing request with
+operation kind + aspect ratio + capability requirements, it filters routes
+that satisfy the operation × aspectRatio combination, ranks the remainders
+by the policy's preference (`trust-first`, `capability-first`, or
+`balanced`), and returns a `VideoProviderRouteDecision` with the chosen
+route + rationale.
+
+Routes marked `scaffold` in `provider-status.ts:ROUTE_MATURITY` are
+labeled `availability: 'degraded'` in the status report and the router
+will skip them under default policy unless explicitly requested.
+
+## Adapter contract
+
+Live execution goes through `src/video/execution-runtime.ts`, which calls
+`resolveAdapterCommand(routeId, env)`:
+
+1. Look for the user override env var (`VCLAW_<ROUTE>_ADAPTER`). If set,
+   that command runs as the adapter — `vclaw` invokes it with JSON on
+   stdin and expects JSON on stdout.
+2. Otherwise check `builtinAdapterCommandForRoute(routeId)`. Currently
+   returns a built-in adapter command for `seedance-direct`, `veo-useapi`,
+   `runway-useapi`, and `dreamina-useapi` (the bundled
+   `dist/cli/provider-adapter.js` binary invoked with `--route <id>`).
+3. Otherwise throw — the route doesn't have a usable adapter. (All four
+   live routes ship a built-in adapter; the removed `veo-direct` route was
+   the lone exception and no longer exists.)
+
+The adapter protocol:
+
+| Stage | Input (stdin) | Output (stdout) |
+|---|---|---|
+| submit | `{ scenes: [{ sceneIndex, prompt, ... }], outputDir, ... }` | `{ externalJobId, rawResult: {...} }` |
+| poll | `{ action: 'poll', outputDir, externalJobId }` | `{ status: 'pending' \| 'completed' \| 'failed', outputs?: [...], issues?: [...] }` |
+| cancel | `{ action: 'cancel', outputDir, externalJobId, workspaceRoot }` | `{ status: 'cancelled' \| 'unsupported', externalJobId?, issues?: [...] }` |
+
+The runtime is strict about the returned `status`: `pollExecutionPayload`
+throws unless poll status is exactly `pending` / `completed` / `failed`, and
+`cancelExecutionPayload` throws unless cancel status is exactly `cancelled` /
+`unsupported`. The cancel result is read into `VideoExecutionCancelResult`
+`{ status, externalJobId, issues, rawResult }` — note the field is `issues`,
+not `warnings`.
+
+The built-in adapter (`src/cli/provider-adapter.ts`) also honors per-route
+command shims for each of its four routes — `*_SUBMIT_CMD`, `*_POLL_CMD`,
+`*_CANCEL_CMD` (e.g. `VCLAW_DREAMINA_USEAPI_SUBMIT_CMD` /
+`VCLAW_DREAMINA_USEAPI_POLL_CMD` / `VCLAW_DREAMINA_USEAPI_CANCEL_CMD`). The
+action is chosen from `input.action`: `poll` → the poll shim, `cancel` → the
+cancel shim, anything else → the submit shim. Setting any shim (or the full
+`*_ADAPTER` override) marks the route as an execution override, which
+suppresses the runtime dependency probes for that route in the status report.
+
+## Native in-process transports
+
+Four routes have native TypeScript transports that bypass the adapter
+subprocess hop:
+
+- **`src/video/native-veo.ts`** — defaults to `<workspace>/vclaw-cli/flow.ts`
+  via `bun`. Looks for `cookie.json` for Google Labs Flow auth.
+  Customizable via `VCLAW_VEO_CLI_ROOT`, `VCLAW_VEO_OUTPUT_DIR`,
+  `VCLAW_VEO_BUN_BIN`, `VCLAW_VEO_COMMAND_TIMEOUT_MS`. Forwards optional
+  omni-flash fields to `flow.ts` when present (byte-identical when absent):
+  `executionProfile.veoModel` → `-m` (`omni-flash` unlocks audio/V2V),
+  per-scene `voicePreset` → `--voice` (omni-flash-only, gated in
+  `route-capabilities.ts`), allowlisted `durationSeconds` (4/6/8/10) →
+  `--duration`, and per-scene `referenceVideoMediaId` → `--ref-video`
+  (omni-flash-only V2V edit, distinct from the scene-chaining seed).
+
+- **`src/video/native-seedance.ts`** — direct Seedance API calls via
+  `SUTUI_API_KEY`. No subprocess hop, no external CLI dependency.
+
+- **`src/video/native-runway.ts`** — direct UseAPI REST calls via
+  `USEAPI_API_TOKEN` + `USEAPI_ACCOUNT_EMAIL`. Pure Node `fetch` + `fs`.
+  Supports both Gen-4.x (firstImageAssetId for i2v) and Seedance-2.0
+  (startFrameAssetId for keyframe-driven) modes via the unified
+  `/runwayml/videos/create` endpoint. Cancel marks scenes failed locally
+  and warns about remote tasks UseAPI free-tier cannot cancel server-side.
+
+- **`src/video/native-dreamina.ts`** — direct UseAPI Dreamina REST calls via
+  `USEAPI_API_TOKEN` + `VCLAW_DREAMINA_ACCOUNT`. Pure Node `fetch` + `fs`.
+  Reference routing: `referenceRole === 'character'`, OR more than one image,
+  OR any video/audio reference → Omni Reference
+  (`omni_N_imageRef`/`videoRef`/`audioRef`, multi-character lock); exactly one
+  image keyframe → `firstFrameRef` (first_frame image-to-video mode); else
+  text-to-video with the requested ratio. References are capped at 9 image /
+  3 video / 3 audio (`assertDreaminaReferenceBudget`), preflighted across ALL
+  tasks fail-fast before any upload. `Asset://` URIs are skipped with a warning
+  (those are ARK avatars, not Dreamina assetRefs). It reuses
+  `seedance-content-filter`: on a content-violation submit error it retries
+  with a level-1 then level-2 sanitized prompt. Cancel has no UseAPI verb, so
+  it marks local scenes failed, warns that the remote job keeps running and
+  consuming credits, and returns `status: 'cancelled'`.
+
+All four accept an optional `fetchImpl` parameter for test injection.
+The provider-level adapter functions in `src/video/providers/runway-useapi.ts`
+and `src/video/providers/dreamina-useapi.ts` also accept `fetchImpl`, so tests
+can mock the entire HTTP layer end-to-end.
+
+## Adding a new route
+
+When you want to add a working new provider route (for example a
+future `kling-useapi`):
+
+1. **Descriptor.** Add a `VideoProviderDescriptor` entry to
+   `DEFAULT_PROVIDER_REGISTRY` in `src/video/provider-platform/registry.ts`.
+   Use videoclaw's rich schema (controls, operationSupport, routingHints,
+   escapeHatches).
+2. **Provider HTTP code.** Add `src/video/providers/<route>.ts` with the
+   submit/poll/fetchResult functions. Accept `fetchImpl?: FetchLike` in
+   each input interface for test injection.
+3. **Native transport.** Add `src/video/native-<route>.ts` mirroring
+   `native-runway.ts`: own workspace/env/job-state, call into providers/
+   for HTTP. Accept `fetchImpl?: FetchLike` in the options.
+4. **Wire the dispatcher.** In `src/video/execution-runtime.ts`, add a
+   case for the new route in `builtinAdapterCommandForRoute()` and
+   `adapterEnvVarForRoute()`. In
+   `src/video/provider-adapter-runner.ts`, route the submit/poll/cancel
+   payloads to your native module.
+5. **Status.** In `src/video/provider-status.ts`, update
+   `ROUTE_MATURITY[<route>]` to `'production'`,
+   `ROUTE_REQUIRED_ENV_VARS[<route>]`, `ROUTE_REQUIRED_DEPENDENCIES[<route>]`,
+   and `ROUTE_ADAPTER_ENV_VAR[<route>]`.
+6. **Tests.** Add `src/tests/<route>.test.ts` (provider) and
+   `src/tests/native-<route>.test.ts` (native wrapper with scripted
+   fetch mock). The 4 runway tests are the reference pattern.
+7. **Docs.** Update the route table at the top of this file.
+
+`dreamina-useapi` is the most recent worked example — its
+`src/video/providers/dreamina-useapi.ts` + `src/video/native-dreamina.ts`
+landed after Runway and are the freshest reference for this checklist.
+`runway-useapi` (Phase 5b, `6e99443`) remains a good canonical reference but
+is no longer the newest. Read those files for the canonical structure.

package/docs/PUBLISHING.md

@@ -0,0 +1,175 @@
+# Publishing
+
+How to cut a release of `videoclaw` to npm and propagate it to the
+Homebrew tap. Keep this doc aligned with the actual release workflow.
+
+## Versioning
+
+Semantic versioning. Bump the `version` field in `package.json` and commit the
+bump as its own commit (`release: v0.2.0`) so the tag and the commit line up.
+
+## 1. npm publish
+
+Prereqs:
+
+- npm account with two-factor enabled
+- `npm login` on the release machine
+
+Release:
+
+```bash
+# Ensure clean state
+git status --porcelain           # must be empty
+git pull --rebase
+
+# Full gate before publish
+npm run check:release-readiness-lite
+
+# Bump version + tag (creates the v<ver> tag locally)
+npm version <patch|minor|major> -m "release: v%s"
+
+# Publish (runs prepublishOnly: npm test)
+npm publish
+
+# Push the commit + tag
+git push && git push --tags
+```
+
+The `files` field in `package.json` controls what ships:
+
+```
+AGENTS.md
+CLAUDE.md
+tsconfig.json
+docs/*.md
+docs/assets/*
+dist/cli/
+dist/video/
+dist/index.*
+schemas/
+src/video/
+skills/README.md
+skills/catalog.json
+skills/*/README.md
+skills/*/SKILL.md
+tmp/review-station/index.html
+```
+
+Plus npm always includes `README.md`, `LICENSE`, and `package.json`. The Review
+UI HTML is intentionally shipped because `vclaw video review-ui` defaults to the
+bundled package asset; `--ui-path` is only an override for local UI development.
+The package also ships `src/video/` because operator docs link to the domain
+modules for source-available inspection. Compiled tests, source tests, project
+workspaces, generated verification artifacts, and bulky skill assets/scripts
+must stay out of the package. Do **not** add a `.npmignore` — keep `files`
+authoritative.
+
+Verify:
+
+```bash
+npm view videoclaw version
+npx videoclaw@latest video providers
+npm pack --dry-run --json
+```
+
+The dry-run package should include `README.md`, `LICENSE`, `package.json`,
+`docs/PRODUCTION_WORKFLOW.md`, `docs/CLI_REFERENCE.md`, `docs/MIGRATION.md`,
+`docs/assets/demo-quickstart.{cast,gif}`, `dist/cli/vclaw.js`,
+`dist/video/review-ui.js`, schemas, and skills. It should exclude `projects/`,
+compiled/source tests, generated verification artifacts, and any nested `.tgz`
+archive.
+
+Latest local dry-run evidence on 2026-05-08:
+
+```json
+{
+  "entryCount": 521,
+  "hasReadme": true,
+  "hasLicense": true,
+  "hasPackage": true,
+  "hasCliReference": true,
+  "hasProductionWorkflow": true,
+  "hasMigration": true,
+  "hasPublishing": true,
+  "hasDemoGif": true,
+  "hasDemoCast": true,
+  "hasReviewUi": true,
+  "hasProjects": false,
+  "hasTests": false,
+  "hasTgz": false
+}
+```
+
+## 2. GitHub release
+
+After `git push --tags`:
+
+```bash
+gh release create v<ver> \
+  --title "v<ver>" \
+  --notes-file CHANGELOG.md \
+  # or --generate-notes
+```
+
+## 3. Homebrew tap
+
+A Homebrew tap is just a GitHub repo named `homebrew-<name>` that holds formula
+files under `Formula/`. Recommended: `davendra/homebrew-vclaw`.
+
+### One-time: create the tap repo
+
+```bash
+gh repo create davendra/homebrew-vclaw --public \
+  --description "Homebrew tap for videoclaw"
+git clone https://github.com/davendra/homebrew-vclaw.git
+mkdir -p homebrew-vclaw/Formula
+cp packaging/homebrew/vclaw.rb homebrew-vclaw/Formula/vclaw.rb
+cd homebrew-vclaw
+git add Formula/vclaw.rb
+git commit -m "add vclaw formula"
+git push
+```
+
+### Each release: bump the formula
+
+After `npm publish` succeeds:
+
+```bash
+VERSION=0.2.0
+TARBALL_URL="https://registry.npmjs.org/videoclaw/-/videoclaw-${VERSION}.tgz"
+SHA=$(curl -sL "$TARBALL_URL" | shasum -a 256 | awk '{print $1}')
+
+# In the tap repo, update Formula/vclaw.rb:
+#   url   "$TARBALL_URL"
+#   sha256 "$SHA"
+
+git commit -am "vclaw ${VERSION}"
+git push
+```
+
+### User install
+
+```bash
+brew tap davendra/vclaw
+brew install vclaw
+vclaw video providers
+```
+
+## 4. Post-publish smoke
+
+On a fresh machine or clean dir:
+
+```bash
+npx videoclaw@latest video providers
+# and
+brew tap davendra/vclaw && brew install vclaw && vclaw video providers
+```
+
+Both should produce a JSON provider report and exit `0`.
+
+## Rollback
+
+npm: `npm unpublish videoclaw@<ver>` within 72h, or publish a new patch.
+
+Homebrew tap: revert the formula commit — users will get the prior version on
+their next `brew update && brew upgrade vclaw`.

package/docs/PYTHON_PIPELINE.md

@@ -0,0 +1,139 @@
+# Python Pipeline (opt-in)
+
+The `skills/video-replicator/scripts/` directory ships an **optional** Python pipeline for
+Seedance-targeted prompt direction, character sheet generation, prompt
+critique, scene chaining via last-frame injection, and Omni Flash specific
+flows. It is **not** required for normal `vclaw` usage — the core CLI is
+pure Node/TypeScript. Use this pipeline when you want the deeper
+Seedance Prompt Director compose / chain / critique stack that originated
+in the legacy `videoclaw` repo.
+
+## Why it's opt-in
+
+- The main `vclaw` binary is a Node 20+ CLI with zero runtime Python
+  dependencies.
+- The Python pipeline targets Python 3.10+ and depends on third-party
+  packages (`google-genai`, `requests`, `yt-dlp`). Most users don't need
+  these.
+- Some files (notably `seedance_prompt_db.py`, 6.5k lines) carry forward
+  the legacy curated-prompt database. Newer users should prefer the
+  TypeScript surface (`vclaw video prompt-lib-list` / `prompt-lib-show`)
+  documented in `docs/CLI_REFERENCE.md`.
+
+## Setup
+
+```bash
+cd skills/video-replicator/scripts
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Requirements (`skills/video-replicator/scripts/requirements.txt`):
+
+- `google-genai>=1.0.0` — Gemini API for video analysis
+- `requests>=2.31.0` — HTTP
+- `yt-dlp>=2024.1.0` — Video downloading
+
+## What's included
+
+20 `.py` modules organized into four clusters:
+
+### Seedance Prompt Director (core)
+
+| Module | Role |
+|---|---|
+| `seedance_prompt_director.py` | 3-control-level prompt composer (foundation for the director workflow) |
+| `seedance_prompt_builder.py` | Lower-level prompt assembly utilities |
+| `seedance_prompt_critique.py` | Prompt critique with `auto_fix_prompt` rewrite suggestions |
+| `seedance_chain_manager.py` | Multi-scene continuation via last-frame injection |
+| `seedance_reference_validator.py` | Reference-image validation against scene needs |
+| `seedance_hooks.py` | 18 director hooks + 22 camera moves + 12 lighting presets + 4 timeline templates |
+| `seedance_consistency.py` | Character-consistency scoring across scenes |
+| `seedance_material_library.py` | Reusable material assets |
+| `seedance_platform_optimizer.py` | Target-platform aspect/duration tuning |
+| `seedance_omni.py` | Omni Flash specific T2V/R2V/V2V helpers |
+| `seedance_webhook.py` | Webhook receiver for async generation |
+| `seedance_client.py` | HTTP client + content-safety validators |
+| `seedance_prompt_db.py` | Curated prompt library (legacy; see note above) |
+
+### Character pipeline
+
+| Module | Role |
+|---|---|
+| `character_sheet_generator.py` | 8-field character sheet generation from descriptions |
+
+### Shared utilities
+
+| Module | Role |
+|---|---|
+| `config.py` | Centralized constants (timeouts, paths, model names) |
+| `exceptions.py` | Shared exception types (`SeedanceError`, `SeedanceTimeoutError`, `VideoProcessingError`, `MissingDependencyError`) |
+| `logging_config.py` | Logger initialization for the pipeline modules |
+| `ffmpeg_wrapper.py` | Thin wrapper around `ffmpeg` / `ffprobe` subprocesses |
+| `audio_utils.py` | Audio extraction, narration, mixing helpers |
+| `assembly_utils.py` | Concat / encode / package helpers |
+
+## Reference material
+
+`references/video/seedance-skills/` contains 15 genre-specific Seedance
+"skill" reference markdowns (cinematic, 3d-cgi, cartoon, comic-to-video,
+fight-scenes, motion-design-ad, ecommerce-ad, anime-action, product-360,
+music-video, social-hook, brand-story, fashion-lookbook, food-beverage,
+real-estate). These document compose / camera / lighting recipes per
+genre and are consumed by `seedance_prompt_director.py`.
+
+## Invoking from the TypeScript CLI
+
+The pipeline runs as subprocesses; nothing in `src/` imports Python.
+Typical pattern:
+
+```typescript
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+
+const { stdout } = await exec(
+  'python3',
+  ['skills/video-replicator/scripts/seedance_prompt_director.py', '--compose', JSON.stringify(input)],
+  { cwd: workspaceRoot, env: { ...process.env, PYTHONPATH: 'skills/video-replicator/scripts' } },
+);
+const result = JSON.parse(stdout);
+```
+
+A future Phase will surface this as a first-class `vclaw video
+director:compose` subcommand. For now the modules are scriptable
+end-to-end and can be invoked directly.
+
+## What this directory does NOT include
+
+Everything from `videoclaw/scripts/video/` that was either tightly
+coupled to the legacy orchestration layer (which v2 dropped) or
+duplicates functionality now in `vclaw-cli/`:
+
+- `db.py`, `db_unified.py`, `db_convex.py` — legacy SQLite/Convex DB
+  for the Python pipeline. The vclaw-cli SQLite store
+  (`vclaw-cli.db`) is the single source of truth for batch/job tracking.
+- `seedance_batch.py`, `seedance_backend.py` — overlap with vclaw-cli
+  backends.
+- `campaign_manifest.py`, `ugc_strategy.py`, `ugc_scripts.py` — the
+  legacy UGC scripts that the `ugc` skill rewrite explicitly moved
+  away from (`projects/<slug>/strategy/` directly + vclaw CLI now).
+- ~80 other one-off `.py` files that didn't make the curated list.
+
+If you need any of those, copy them in manually and add them here with
+a one-line note in this doc.
+
+## Tests
+
+A focused subset of the original Python test harness will be ported in
+a follow-up pass — the v2 plan defers `scripts/video/tests/` import to
+a phase-specific commit once we've decided which tests still apply.
+
+## Status
+
+- All 20 modules: import-clean (verified with
+  `python3 -c "import <module>"` for each).
+- No runtime smoke yet — that requires real provider credentials.
+- Subject to future cleanup: `seedance_prompt_db.py` will likely be
+  retired in favor of the TypeScript `vclaw video prompt-lib-*` surface.