Review UI Storyboard Workflow

This guide is the operator runbook for the human-in-the-loop storyboard review station. It is designed for the still-image phase only: characters, references, storyboard stills, 4k still handoff, and motion planning. It does not generate final videos.

Reference method: docs/REFERENCE_VIDEO_SEEDANCE_MOTION_DESIGN_WORKFLOW.md.

Start The Review Station

vclaw video review-ui --project <slug> --root .

Open:

http://127.0.0.1:4317/review-ui?project=<slug>

The UI loads the project inventory from /api/review-inventory?project=<slug> and saves decisions through /api/review-decision?project=<slug>.

Let The Agent Do It

When the project already has storyboard still candidates, use the autopilot handoff:

vclaw video review-autopilot --project <slug> --root .

The autopilot path is for "just do it" operation. It selects the best available completed still per scene, locks those stills, creates artifact-backed upscaled handoff candidates from local still assets when possible, fills the Seedance reference roles, approves the assembly checks, and writes the same artifacts as the browser review station. It does not submit video jobs.

Use the browser afterward only to inspect or override the agent's choices.

What The User Provides

The user should provide:

• Project slug, for example launch-teaser.
• Character choice, either an existing saved character or a Go Bananas character iteration request.
• Reference intent: which references control identity, pose, lookdev, background, prop, start frame, and end frame.
• Storyboard template, for example product-commercial-4.
• Generated storyboard still URLs or local image paths returned by Go Bananas or another image provider.
• Upscaled 4k still URLs or local paths for every locked scene.
• Final assembly approvals: voiceover fit, continuity cuts, retiming polish, logo/payoff reveal, and review report readiness.

The UI handles the sequence, gate checks, artifact writing, and handoff summaries.

Step-By-Step Operator Flow

1. Inventory Check that the project, saved characters, templates, prompt references, schemas, and media assets are visible. This gate confirms the local project context is loaded.

2. Characters Select a saved character such as Proofy, or queue a Go Bananas character iteration request. For reusable character identity, prefer a saved Go Bananas character ID over one-off image prompts.

3. References Assign each reference one job. Identity should point to the character, lookdev/background/prop/UI structure can point to prompt references, and start/end frame roles should point to locked still candidates.

4. Storyboard Pick a template, then work scene by scene. For each scene:

   • Queue or create a Go Bananas still prompt.
   • Paste the returned image URL or local image path.
   • Review all candidates.
   • Reject wrong-character or placeholder candidates.
   • Lock the best generated still.
   • Attach the artifact-backed 4k/upscaled still.

5. Motion Plan Confirm the plan only. The review pass records Seedance instructions such as control-pass, control-plus-short-variant, start-end-frame-chain, and bridge-hard-actions. It does not prove video clips exist yet.

6. Assembly Approve pacing and final handoff checks. A completed review should show:

   pass · locked 4/4 · character mismatches 0 · 4k assets 4/4 · publish ready

Go Bananas Usage

Use Go Bananas for two distinct jobs:

• Character iterations: create or refine reusable character identity, then save it as a character profile.
• Storyboard stills: generate scene images with the saved character, using 16:9 still-image prompts.

For the checked-in Proofy example, the canonical character is:

Proofy, Go Bananas character ID 249

Komo is a separate existing character identity and should not be reused for Proofy scenes.

Repeatable Image-Only E2E

Use the packaged E2E when you need to replay the storyboard image workflow without submitting video jobs:

npm run e2e:image-storyboard:examples

When npm is not on PATH, run the same steps manually:

node -e "const fs=require('fs'); fs.rmSync('dist',{recursive:true,force:true});"
./node_modules/.bin/tsc
node -e "require('fs').chmodSync('dist/cli/vclaw.js', 0o755); require('fs').chmodSync('dist/cli/provider-adapter.js', 0o755)"
node scripts/e2e-image-storyboard-workflow.mjs --project e2e-proofy-image-storyboard --run-id 2026-05-06-proofy-image-e2e --include-examples --verify-server --port 4322

The default manifest is examples/image-storyboard/proofy-e2e-stills.json. It records the four Go Bananas image IDs and prompts used for the current Proofy storyboard test:

• Scene 0: 6657
• Scene 1: 6658
• Scene 2: 6659
• Scene 3: 6660

The script downloads those images into the project, adds them as storyboard still candidates, selects one candidate per scene, chains scenes 1-3 from the previous scene, binds a Proofy identity reference sheet, runs readiness, director preflight, plan, storyboard review, doctor, status, and Obsidian export.

With --verify-server, it also starts the Review UI server and exercises the human-in-the-loop API surfaces that the browser uses:

• /api/review-inventory
• /api/media-proxy
• /api/storyboard-still-request
• /api/storyboard-still-candidate
• /api/character-iteration-request
• /api/upscaled-still-candidate
• /api/review-decision

The server check must finish with review-report.json verdict pass, publishReady: true, four locked stills, and four artifact-backed upscaled still candidates. It intentionally stops before produce, execute, provider submission, post-production, or final-video checks.

By default, the script creates a temporary root outside the repository so repeat runs do not dirty the tracked example project. The JSON output prints the exact history paths. Pass --root "$PWD" --reset only when you intentionally want to refresh the checked-in example project.

Run history is stored under the chosen root:

projects/e2e-proofy-image-storyboard/artifacts/e2e-image-storyboard-history/

Use latest.md for the human-readable command and prompt ledger, or the timestamped JSON file for automation evidence.

Saved Artifacts

Saving the review writes:

• review-ui-ledger.json
• reference-board.json
• director-seedance-plan.json
• storyboard-stills-plan.json
• scene-selection.json
• gobananas-character-brief.json
• post-plan.json
• review-report.json
• asset-manifest.json

For a completed image handoff, asset-manifest.json must promote the artifact-backed upscaled-storyboard-still assets, not the original source still URLs.

Completion Criteria

A storyboard handoff is ready when:

• The review ledger has activeGate: assembly.
• review-report.json has verdict: pass.
• review-report.json has metrics.publishReady: true.
• Every scene has a locked still.
• Every locked still has an artifact-backed *-4k still.
• characterMismatchCount is 0.
• rejectedCandidateCount is 0 in the current handoff artifacts.
• Browser UI shows 0 open gates and Ready for publish handoff. from the saved publish-ready review-report.json, not from local gate completion alone.

Proofy Example State

As of the current verified handoff:

• Character: Proofy
• Locked stills: scene-0-take-5, scene-1-take-3, scene-2-take-2, scene-3-take-2
• 4k stills: scene-0-take-5-4k, scene-1-take-3-4k, scene-2-take-2-4k, scene-3-take-2-4k
• Review verdict: pass
• Publish readiness: true
• Video generation: not run yet