Cinematic reference workflow

Use cinematic-face-first when controlled photographic identity matters. Existing commands keep their legacy defaults so stylised and established projects remain usable. The named profile selects staged character creation, three-panel working sheets and final prompt validation.

Save the workflow once per project

vclaw video cinema-profile --project film --reference-profile cinematic-face-first

Later character creation and filmmaking commands inherit this choice, including its review gates and final validation. An explicit command-level --reference-profile legacy overrides it for that invocation. Projects without a saved choice retain their existing defaults.

Review the face, then the outfit

Start with a cast file:

[{"name":"Maya-v1","description":"Woman with dark curls and green eyes","outfit":"Blue wool coat"}]

vclaw video character-auto-create --project film --input cast.json --reference-profile cinematic-face-first

This uses the Go Bananas server API and its configured provider billing. Obtain the existing generation/cost approval before running it. --dry-run generates no images. This is separate from the interactive Codex subscription workflow, where Codex generates a local image and Go Bananas uploads/stores that result. Do not switch between those lanes automatically or describe either as unlimited without account evidence.

1. The first run returns a face candidate and awaiting-face-approval. Inspect the actual image for identity, facial detail and neutral expression.
2. Add its returned Go Bananas ID as approvedFaceImageId after review. The next run uses that face to generate an outfit candidate and returns awaiting-outfit-approval.
3. Add the reviewed outfit ID as approvedOutfitImageId. The next run creates a managed character anchored to the approved face and a working three-panel sheet. The outfit reference controls wardrobe and proportions separately.
4. Inspect the sheet. Its pending review state prevents it being treated as a ready reference. Mark it approved through reference-sheet-add --id <sheet-id> --type identity --name <name> --review-status approved after visual review.

Interrupted cinematic creation records each provider operation under references/character-recovery/. Repeating the same input reuses confirmed IDs and results and resumes safe local download/import work. Changed input under the same stage/name is a conflict. An uncertain provider response returns the receipt path and completed operation IDs for reconciliation; it never silently resubmits the possibly accepted request. Existing reviewed sheets and character traits survive an unchanged retry.

Use a distinct character name for a new identity version. The cinematic profile rejects an existing same-named character instead of silently rebinding to another face. It also rejects --no-sheet and legacy --sheet-preset overrides.

The working three-panel image is not a Cinema-approved character sheet. Cinema also requires its existing single-face/headless-body validation and hash-bound evidence approval. Do not claim those checks passed because generation succeeded.

Compose the video prompts

vclaw video filmmaking-prompts --project film --reference-profile cinematic-face-first --flat-grade --write

Delivery aspect ratio comes from the project brief unless explicitly overridden. Working sheets default to 16:9 independently; use --sheet-aspect-ratio to change them. An explicit --sheet layout wins over the profile. --flat-grade affects the character references; scene lighting stays cinematic. Sheet layout directions are kept out of the scene's character identity description.

Store explicit voice, movement and stillness in the story bible. Prompt composition uses the relevant scene cast's traits; absent traits are left unspecified. These are performance directions, not proof of voice identity or successful lip sync.

The named profile writes a cinematic-v1 validation marker. Before submission, VideoClaw checks the final prompt after runtime additions, confirms that required references are ready and still attached, and runs the existing prompt linter with the recorded prose/numeric register. Fix rejected requests and regenerate their packets. Old unmarked prompt artifacts keep their existing compatibility behaviour.

Bring external images into Cinema

The following commands run locally and generate no images. Save an image job:

{
  "jobId":"maya-face-v1",
  "subjectId":"maya",
  "characterVersionId":"maya-v1",
  "role":"identity_face",
  "prompt":"Neutral chest-up portrait of Maya, readable facial detail.",
  "sources":[]
}

vclaw video cinema-image-plan --project film --input image-job.json
vclaw video cinema-image-ingest --project film --job maya-face-v1 --file /absolute/path/face.png --lane codex-subscription --image-id 123
vclaw video cinema-image-review --project film --job maya-face-v1 --result-hash <returned-sha256> --face-count 1 --verdict approved --reviewer <reviewer> --note "Inspected the face and accepted this identity"

Choose gobananas-api when the image came from the server API; that lane requires its Go Bananas image ID. codex-subscription records a local Codex image, with an optional ID after Go Bananas upload. These labels record provenance, not a billing entitlement or an automated provider connection.

Source entries contain path and role; their hashes are recorded when planning. Roles distinguish identity_face, wardrobe, body_front_headless, body_back_headless, environment and prop. Reuse the actual character version from your Cinema planning artifacts. When an active Cinema plan exists, the job validates those IDs and records the planning receipt hash. A changed plan makes that job stale. Use a new job ID for each iteration.

Ingestion leaves the result pending. After inspecting its pixels, review the exact returned hash. Declare the observed --face-count: one for an identity face, zero for headless body plates. Changed source/result files invalidate the review request. An approved review returns a reference entry that can be used in Cinema's existing reference-pack/sheet workflow. Cinema's separate character-sheet evidence and preflight gates still apply. Sheet approval and loading recheck image-job review, current character version and exact bytes; exporting a reference does not bypass those checks. An approved image alone does not approve a character sheet or authorise a video render.

Run a manager loop for long work

An external manager assigns bounded phases with acceptance criteria. The implementer completes one phase and reports changed artifacts and test evidence. The manager reviews the evidence before marking that phase complete and assigning the next useful step. VideoClaw remains an external-agent target; it does not silently launch its own agent service.

Keep a durable checklist, accepted-phase counter and timestamped history. Plot accepted phases over elapsed time, rather than counting messages or attempted actions as progress. After repeated failed checks or ten minutes without useful evidence, reassess the blocker and narrow or change the next step. Visual approval still requires inspection of the rendered pixels. Completion requires the intended output and its acceptance checks, not merely an exhausted time budget.