# 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 ```bash 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: ```json [{"name":"Maya-v1","description":"Woman with dark curls and green eyes","outfit":"Blue wool coat"}] ``` ```bash 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 --type identity --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 ```bash 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: ```json { "jobId":"maya-face-v1", "subjectId":"maya", "characterVersionId":"maya-v1", "role":"identity_face", "prompt":"Neutral chest-up portrait of Maya, readable facial detail.", "sources":[] } ``` ```bash 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 --face-count 1 --verdict approved --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.