Review UI & Autopilot

A local browser station where a human approves, rejects, and re-generates every storyboard still before a single video credit is spent — and a one-command autopilot that lets an AI agent do the exact same approval pass and write the exact same artifacts, hands-free.

What it does

• Launches a tiny local web station (http://127.0.0.1:4317) for human-in-the-loop review: inspect every scene's candidate stills, reject wrong-character or placeholder takes, lock the best still per scene, and attach an upscaled 4k handoff still.
• Stays image-only on purpose. It plans motion and assembles the handoff — it never submits video jobs or spends provider credits.
• Records each decision as canonical JSON and drives the project lifecycle: a publish-ready review flips the project's review checkpoint to completed and advances the manifest toward publish.
• Gives agents a turn-key shortcut: review-autopilot auto-picks the best completed still per scene, locks them, fills the Seedance reference roles, approves the assembly checks, and writes the same artifacts as the browser — no clicking.
• Produces a single clear verdict line: pass · locked 4/4 · character mismatches 0 · 4k assets 4/4 · publish ready. "Ready" means verdict pass and publishReady: true.

How to use it

The CLI is invoked as node dist/cli/vclaw.js ... (installed, it's just vclaw ...).

node dist/cli/vclaw.js video review-ui --project launch-teaser --root .

Starts the local review station and prints the URL — open http://127.0.0.1:4317/review-ui?project=launch-teaser in your browser to approve, reject, lock stills, and save the decision.

node dist/cli/vclaw.js video review-autopilot --project launch-teaser --root .

Agent shortcut — auto-locks the best completed still per scene, builds 4k handoff candidates, approves assembly, and writes every review artifact. No video jobs are submitted.

node dist/cli/vclaw.js video review-autopilot --project launch-teaser --character proofy --template product-commercial-4 --root .

Same autopilot pass with an explicit character and storyboard template instead of letting the agent infer them from the locked stills' prompts.

node dist/cli/vclaw.js video review --project launch-teaser --root .

Runs the project review pass (verdict + findings) that the publish gate reads.

How it flows

Diagram source (live Mermaid)

Artifacts & outputs

Saving a review writes machine-readable JSON under projects/<slug>/artifacts/:

• review-ui-ledger.json — the raw decision record (activeGate, selections, notes, quality score).
• review-report.json — the canonical verdict (pass | retry | fail), findings, and metrics.publishReady. This is the gate the publish step reads.
• scene-selection.json — the locked candidate id per scene.
• asset-manifest.json — promotes the artifact-backed upscaled-storyboard-still assets (not the raw source URLs) for handoff.
• reference-board.json, director-seedance-plan.json, storyboard-stills-plan.json, gobananas-character-brief.json, post-plan.json — the reference, motion, and post-production plan.
• brief.json + storyboard.json are re-hydrated and their brief/storyboard/assets/review checkpoints marked completed once a review is publish-ready.

A publish-ready handoff also appends an artifact.review-report.written event to events/events.jsonl.

Tips & gotchas

Let the agent do it first

If the project already has completed scene-candidate stills, run review-autopilot for a hands-free pass, then open the browser only to inspect or override its choices.

"Locally green" is not "ready"

Closing every gate in the browser is not the same as ready. Ready requires the saved review-report.json to have verdict: pass and metrics.publishReady: true, every scene locked, and every locked still backed by an artifact *-4k upscale. A green UI with publishReady: false is retry-required.

Image-only by design

This station never generates final video. It stops before produce/execute and provider submission — describe characters by saved profile or visual descriptor, lock stills, then hand off to director mode for motion.

Driving it from an agent

review-autopilot is the agent entrypoint: it requires at least one completed storyboard still candidate (otherwise it throws) and emits JSON describing the locked stills, upscaled handoffs, and the resulting review-report. Treat the run as ready only when the returned report shows verdict: pass and metrics.publishReady: true — that pairing is what advances the project's review checkpoint and unblocks the publish gate. See also scene candidates, reference sheets, and director mode.