# Repository Guidelines ## Agent integration contract (v3) videoclaw v3 is designed as a target for external agents (Claude Code, Codex, Antigravity, Cursor, Warp), not as an orchestrator itself. The contract: 1. **Stdout is JSON when piped.** Pretty-printed when TTY. Progress goes to stderr. 2. **Exit codes follow a 0/1/2/3 taxonomy** — see `docs/CLI_REFERENCE.md` § Agent-friendly surface. 3. **Errors carry stable string codes** in their JSON envelope. The catalog: `schemas/video/errors.json`. 4. **One-call discovery: `vclaw schema --json`** dumps the full contract — commands, flags, artifact schemas, exit codes, error codes. 5. **Veo (Google Flow) access requires Bun.** `vclaw veo *` subcommands bridge to `bun run vclaw-cli/flow.ts` as a subprocess. Bun must be on PATH (`bun --version` to verify). 6. **MCP option.** `vclaw mcp serve` exposes read-only project introspection (list_projects, get_project_status, get_artifacts, get_event_log, list_provider_routes) over stdio MCP. Writes still go through the CLI. If you are an agent author wiring videoclaw into your tool: call `vclaw schema --json` once, then drive the CLI deterministically. Don't try to do natural-language intent classification inside videoclaw — that's your job. --- ## Autonomy Directive - Proceed by default. Do not stop to ask for confirmation on obvious next steps. - Treat user intent here as: build continuously, keep going, and only ask if the next action is destructive outside the repo or genuinely ambiguous. - Prefer making the change, running the verification, and continuing to the next slice rather than pausing for approval. - Keep work scoped to this repository and its generated project folders unless the task explicitly requires touching something else. - If a blocker is local and solvable, solve it. If a blocker is external and hard, note it in output/state and continue with the next meaningful lane. ## Production conduct (applies to every skill and workflow here) - **Spend checkpoint, once.** Before the first paid generation of a workflow, confirm the plan with the user (what's being rendered, roughly how much). After that approval, proceed through the remaining renders without re-asking; pause again only for a real scope change. - **Verify media by content, not exit code.** Before declaring a rendered image/clip done or building on it, look at it (extract a frame / view the image). Filenames and exit codes lie; pixels don't. - **Report faithfully.** A failed, skipped, or substituted render is stated plainly in your summary — never papered over. If tests fail, say so with output. - **Renders are long; don't block.** Run provider renders in the background and keep working on the next free step; check results when they land. ## Project Structure & Module Organization - `src/cli/` contains the `vclaw` CLI entrypoint and command parsing. - `src/video/` holds the core video workflow modules: artifacts, checkpoints, provider status, workspace helpers, and built-in pipeline manifests. - `src/tests/` contains Node test files; compiled tests run from `dist/tests/` after build. - `schemas/video/` stores JSON Schema contracts for artifacts and pipeline manifests. - `docs/ARCHITECTURE.md` explains the clean-room, video-first design. Treat `dist/` as generated output; edit `src/` instead. ## Build, Test, and Development Commands - `npm install` — install the Node 20+ toolchain. - `npm run build` — compile TypeScript to `dist/` and make `dist/cli/vclaw.js` executable. - `npm run dev` — run `tsc --watch` for local iteration. - `npm test` — full verification: rebuild, then run the Node test suite. - `npm run test:node` — rerun compiled tests only when `dist/` is already current. - Example CLI smoke check: `node dist/cli/vclaw.js video providers`. ## Coding Style & Naming Conventions - Use TypeScript with `strict` settings and NodeNext ESM conventions. - Match the existing 2-space indentation and keep modules small and single-purpose. - Use `camelCase` for functions/variables, `PascalCase` for types/interfaces, and `kebab-case` for filenames (for example, `provider-status.ts`). - Keep JSON artifacts machine-readable and deterministic; avoid silent fallback behavior across provider routes. - In TypeScript imports, keep the emitted `.js` extension style used throughout `src/`. ## Testing Guidelines - Tests use the built-in `node:test` runner with `assert/strict`. - Name tests `*.test.ts` and colocate them in `src/tests/` by feature area, such as `cli-full-flow.test.ts`. - Cover both module contracts and CLI flows, especially artifact writing, checkpoint transitions, and status/doctor behavior. - Prefer temp-directory-based tests (`mkdtemp`, `tmpdir`) so runs stay isolated and repeatable. ## Commit & Pull Request Guidelines - This repository has no published git history yet; use imperative, scope-aware commits that follow the repo Lore protocol. - Start with why, then add trailers when useful, such as `Constraint:`, `Confidence:`, `Scope-risk:`, `Tested:`, and `Not-tested:`. - PRs should summarize user-visible changes, list verification commands run, link related issues, and include sample CLI output when command behavior changes. ## Security & Configuration Tips - Do not commit secrets, `.env.local`, provider cookies, or local OMX state; `.omx/` is intentionally ignored. - Provider readiness depends on local tools like `python3`, `bun`, and `ffmpeg`, plus route-specific environment variables. # Memory Context # [videoclaw-v3] recent context, 2026-05-31 2:57pm GMT+1 Legend: 🎯session 🔴bugfix 🟣feature 🔄refactor ✅change 🔵discovery ⚖️decision 🚨security_alert 🔐security_note Format: ID TIME TYPE TITLE Fetch details: get_observations([IDs]) | Search: mem-search skill Stats: 50 obs (20,518t read) | 490,383t work | 96% savings ### May 31, 2026 S2188 Fixed grid-open regression bug in Runway/Dreamina video transports where single character sheet references became video first frames; corrected process errors in testing and build validation; prepared PR #1 for review with clean commit history and full test coverage. (May 31 at 8:03 AM) S2190 Dreamina auth check, PR #1 merge, and resume overnight Runway campaign sub-agent — session setup and state audit (May 31 at 12:54 PM) S2191 Diagnose and fix Dreamina video generation failures in videoclaw-v3 after merging a PR (May 31 at 1:03 PM) S2192 Dreamina 1080p consent gate cleared by user — re-fired probe and confirmed SUBMIT_OK; both paid 1080p lanes now unblocked (May 31 at 1:48 PM) S2193 Dreamina 1080p identity-lock lane fully diagnosed — RejectFace (4011) is documented Seedance moderation policy; ARK confirmed as the only viable identity-locked finals lane (May 31 at 1:58 PM) S2194 Overnight runway campaign video generation — ARK Seedance-2.0 finals delivery and pipeline status review (May 31 at 2:03 PM) S2195 Investigate and fix Dreamina Seedance 2.0 RejectFace / fail_code 4011 error blocking the dhuaan overnight video campaign (May 31 at 2:16 PM) 20181 2:21p 🔵 UseAPI.net Dreamina API v1 — Full Endpoint Map and Character Feature Gap 20182 " 🔵 Character Sheet Dimensions Confirmed as Multi-Panel; No Standalone Solo Portraits Found 20183 2:22p 🟣 Dreamina firstFrameRef i2v Test Script Created to Bypass RejectFace 20184 2:24p 🟣 Dreamina Single-Keyframe i2v Test Fired in Background 20185 " 🔵 Dreamina Single-Keyframe i2v Passed Face Moderation — SUBMIT_OK S2196 Cost-per-clip analysis + parallel ARK finals generation campaign for dhuaan music video (4 shots total) (May 31 at 2:25 PM) 20186 2:28p 🔵 Dreamina i2v Render Completed Successfully — Single Keyframe Workaround Confirmed 20187 " 🔵 Dreamina i2v Clip Validated — 1080p H.264, 5s, Audio Track Present 20188 2:29p 🔵 Dreamina i2v Mid-Clip Frame Shows Cinematic Desert Scene — Character Preserved 20189 " 🔵 Ark Direct API Recipe Uses Multi-Sheet References — Different Path from UseAPI.net 20190 " ✅ Memory Recipe Updated: ARK is Primary Finals Lane, Dreamina Demoted to Working Fallback 20191 2:31p 🔵 ARK Seedance 1080p/5s Clip Cost: ~1,353 Credits; Current Balance ~148,728 20192 2:32p 🟣 ARK Desert-Ridge-Dawn Trio Final Launched as Background Agent 20193 " 🔵 ARK Finals Pipeline — Proven Script Pattern Documented 20194 " 🟣 Two More ARK Finals Launched in Parallel — Desert-Ridge and Outpost-Breach S2197 User confronted premature "impossible" conclusions on Dreamina and ARK lanes; session continued with ARK finals campaign and outpost-breach generation now live (May 31 at 2:32 PM) 20195 2:33p 🟣 ark-final-desert-ridge.mjs Created and Passed Inspect Sanity Check 20196 2:34p 🔵 Desert-Ridge Background Agent Stuck in Inspect Loop — FIRE=1 Not Yet Set by Either Path 20197 " 🔵 Dreamina Seedance 2.0 Pricing via PiAPI: $0.08/s Base, Per-Second Model 20198 " 🔵 Seedance 2.0 API Pricing Survey — Market Rate Context for ARK xskill Credits 20199 2:35p 🔵 Both Desert-Ridge and Outpost-Breach Scripts Validated — Awaiting FIRE=1 from Background Agents 20200 " 🟣 Outpost-Breach ARK Final Submitted with FIRE=1 — Background Task b2pls1kds 20201 " 🟣 Outpost-Breach ARK Job Submitted — task_id=13bc834e, Balance Now 147,374 20202 2:37p ⚖️ Image Generation Testing Scoped to Exclude Video Creation 20203 " 🔵 videoclaw-v3 Build Succeeds Clean in 3.5s 20204 " 🔵 Image-Only Story Bible Test: Content Fixes Work, Execution Blocked on Image-to-Video Route 20205 2:38p 🔵 Dry-Run Completes Successfully With Fake Credentials and Storyboard Approval Bypass 20206 " 🟣 Desert-Ridge ARK Final Fired with FIRE=1 — EXIT=0 20207 2:44p 🔵 smoke-assemble.mjs Integration Smoke Test Structure 20208 2:45p 🔵 smoke-runtime.mjs Full Pipeline Coverage 20209 " 🔵 Smoke and Check Script Inventory in package.json 20210 " 🔵 vclaw video create CLI Test — Director Mode with Character Hydration 20211 " 🟣 New smoke:story-bible-image Smoke Test Added 20212 " 🔴 smoke-story-bible-image: Missing --clip-duration on brief Caused Timeline 0s Assertion Failure 20213 2:46p 🔵 --clip-duration Fix Did Not Resolve story-bible totalDurationSeconds=0 Bug 20214 " 🔵 video brief Does NOT Accept --clip-duration; Flag Is Silently Ignored 20215 " 🔴 smoke-story-bible-image Refactored to Use video create Instead of Separate init/brief/storyboard 20216 2:47p 🔵 video create Leaves Storyboard in awaiting-approval; video assets Blocked 20217 " 🔴 smoke-story-bible-image: Pass VIDEOCLAW_APPROVE_STORYBOARD=1 to video assets to Bypass Stage Gate 20218 " 🔵 VIDEOCLAW_APPROVE_STORYBOARD Does Not Bypass Stage Gate for video assets 20219 " 🔵 VIDEOCLAW_APPROVE_STORYBOARD Read Only in storyboard-markdown.ts and execute.ts 20220 2:48p 🔵 assertStageReady Mechanics: Reads Pipeline Manifest + Checkpoint from Disk, No Env Var Path 20221 " 🔄 smoke-story-bible-image Split Into Two Projects: image-bible (storyboard) and fixed-bible (director) 20222 " 🟣 ARK Seedance 2.0 Sunset-Walkaway Video Generated and Downloaded 20223 " 🔵 Patch Application Failed: smoke-story-bible-image-only.mjs Still Has Pre-Refactor Content 20224 2:49p 🔵 Post-Generation Visual QA Workflow for ARK Video 20225 " 🔵 totalDurationSeconds=0 Persists in Storyboard Mode Despite --clip-duration 15 20226 2:50p 🔵 ARK 1080p Finals Inventory — 5 Videos Complete for Overnight Runway Campaign 20228 " 🔵 Runway Free Campaign Status: 25/30 Clips Complete, Daemon Running 20227 " 🔵 Content Fix Not Propagating to Story Bible in director Mode create 20229 " 🔴 smoke:story-bible-image Passes — Scoped Content Fix Check to story-bible scenes Array 20230 " 🟣 All 31 Tests Pass; smoke-story-bible-image Work Summarized in git Status S2198 ARK Seedance 1080p campaign finals delivery — 5 clips rendered, verified, and campaign status checked for the Dhuaan overnight runway campaign (May 31 at 2:51 PM) **Investigated**: All five ARK Seedance 2.0 1080p final clips were inspected visually via mid-frame extraction. Character reference sheets (Meera, Rani, Tara 2K JPEGs from the 2026-05-27 music video project) were reviewed alongside generated frames to confirm identity lock and single-full-frame composition. Campaign daemon and Runway free-tier progress were checked. ARK account balance and git state were audited. **Learned**: ARK Seedance 2.0 renders 5-second 1080p clips at approximately 1,353 credits each. The API uses Asset:// URI references for character sheets uploaded to the ARK Asset Library — this is the correct ingestion path that avoids multi-panel face policy issues. Render time for a single 1080p clip averages ~3.5–4 minutes (13 polling cycles at ~16s). A safety guard preventing duplicate submissions (FIRE=1 single-submit, no retry loop) is essential after a previous subagent double-fired on outpost-breach. The sunset-walkaway clip successfully depicts the trio walking away into a burning sunset — confirmed as a clean closer shot for the sequence. **Completed**: All five ARK Seedance 1080p final clips delivered and visually verified: desert-ridge (6.1MB), outpost-breach (6.3MB), firelit-trio (4.1MB), burning-outpost (5.3MB), sunset-walkaway (6.1MB). Each clip: H.264, 1920x1080, 5.04s, no audio, no watermark. Mid-frame QA extracted at 2.4s for sunset-walkaway and compared against source character sheets. Task IDs logged for all renders. ARK balance confirmed at 143,315 credits. videoclaw-v3 main HEAD at 7c55840 with 0 open PRs. Runway free-tier daemon running with 25/30 scene clips complete. **Next Steps**: Build the finals preview.html containing all 5 ARK 1080p clips plus the Dreamina fallback test clip, open in Chrome for full review. Then move to step 4: productize the ARK pipeline (batch character ref ingestion, cost tracking, anti-duplicate guard as a shared utility). Access 490k tokens of past work via get_observations([IDs]) or mem-search skill.