Variants & Versioning¶

How to version a workflow and how the 4 variant levels work.

The version system at a glance¶

flowchart LR
    A[V0-1] --> B[V0-2]
    B --> C[V0-N]
    C -.user approves + fan-out done.-> D[V1]
    D --> E[V1-1<br/>Lvl 1/2 variant]
    E --> F[V1-2<br/>Lvl 1/2 variant]
    F --> G[V2-0-1<br/>Lvl 3/4 testing]
    G --> H[V2-0-2<br/>Lvl 3/4 testing]
    H -.user approves.-> I[V2]

Three phases:

Testing (new workflow) — V0-1, V0-2, ..., V0-N. No upper bound. Lives in testing/.
Approved — V1. Reached only when the user explicitly approves AND the workflow has shipped on all target accounts. Lives in approved/.
Variants — applied on top of an approved version. See variant levels below.

The four variant levels¶

Level	Scope	Version bump	Where it lands	User input needed
Lvl 1	~20% script/dialogue rewrite	Decimal: `V1 → V1-1`	`approved/` (auto)	None — proceed
Lvl 2	Script rewrite + wardrobe / styling	Decimal: `V1-1 → V1-2`	`approved/` (auto)	Confirm direction once
Lvl 3	Lvl 2 + prompt improvements (new environment, camera, setting)	Testing: `V1 → V2-0-1 → V2-0-2 → ... → V2`	`testing/` until approved	Complete direction
Lvl 4	Lvl 3 + structural changes (add / remove / split scenes, new prehook)	Testing: `V1 → V2-0-1 → V2-0-2 → ... → V2`	`testing/` until approved	Direction + explicit structural approval

Why Lvl ¾ get a testing phase

Lvl ½ changes are predictable (dialogue swaps, wardrobe). Lvl ¾ changes involve new prompts or new structure — they need validation on a test account before fanning out, just like a new workflow does.

Worked example¶

V0-1 → V0-2 → V0-3        iterating during testing on the test account
V0-3 → V0-4 → V0-5        fan-out testing across target accounts
V0-5 → V1                 user approves, all accounts shipped
V1   → V1-1               Lvl 1 script rewrite variant, auto-approved
V1-1 → V1-2               Lvl 2 wardrobe change variant, auto-approved
V1-2 → V2-0-1             Lvl 3 environment swap variant, enters testing
V2-0-1 → V2-0-2           iterating during Lvl 3 testing
V2-0-2 → V2               user approves the Lvl 3 variant
V2   → V2-1               Lvl 1 dialogue tweak, auto-approved
V2-1 → V3-0-1             Lvl 4 structural change, enters testing
V3-0-1 → V3-0-2           iterating during Lvl 4 testing
V3-0-2 → V3               user approves the Lvl 4 variant

What counts as a "meaningful change" (bump V0-N during testing)¶

ANY meaningful change to a workflow during testing bumps the V0-N counter and archives the previous version. Never overwrite a version in place.

Counts as meaningful:

Generation Runner pass that re-runs nodes
Realism / QA loop pass on existing image gens
Fan-out from one account tab to additional account tabs
Schema rebuild / structural fix
Node consolidation or expansion
Prompt edits (image prompt JSON, Veo template, dynamic dialogue rows)
Wardrobe / setting / persona swaps
Layout / position changes that touch most nodes
outputCount, model, or other property defaults updated in bulk
Avatar reference URL swaps
Variant Lvl ½ rewrite (lands as decimal bump from approved V1+, auto-approved)
Variant Lvl ¾ iteration (bumps -0-N suffix on the next major in testing/)

Does not count:

Scratchpad helper scripts written into Assets/{workflow}/
Read-only audits (sanity checks, link validators)
One-time registry metadata corrections (when the file content didn't change)
Renaming the workflow ID itself — version stays put

The version-bump protocol¶

Every meaningful change:

Read the version registry to find the current version.
Compute the next version per the rules above.
Move the existing file to backups/ as {workflow}-V0-N.nbflow.bak-{YYYY-MM-DD}-{reason} where reason is a short slug (pre-fanout, pre-qa-pass, pre-collapse, etc.).
Write the new file in growth/testing/ (or approved/ for auto-approved variants).
Update the internal name field in the .nbflow JSON to match the new version.
Append a history entry to the registry: date, new version, status, and a one-line note describing what changed.
Update current_version and last_updated on the registry entry.

Rules that apply across all variant levels¶

These apply whenever rewriting image or video prompts, regardless of level.

Avatar description when a character reference image is connected¶

Reference sheets only lock the face. Body, gender, age, build are NOT locked.
Keep avatar descriptions GENERAL. Do NOT repeat gender, age, face details, hair, or ethnicity in the prompt when a ref image is wired in.
DO specify: what the character is wearing and their build (slim / muscular / athletic / heavier). That's it.

Video prompt location rules¶

NEVER prompt the avatar to move to a new location mid-clip UNLESS there is an explicit end frame showing the new location.
Frames-to-video mode means Veo interpolates start → end. Without an end frame, location changes produce hallucinated transitions.
If the script calls for a location change, that's a new scene with a new image gen, not a movement within one clip.

POV rule¶

In a first-person POV shot the camera IS the subject's eye — you cannot describe the subject's body angle, face, shoulders, or "three-quarter turn toward X" from inside their own view. Those descriptions only make sense from an external camera.

POV prompts should describe:

What the camera is pointed at.
What extended body parts reach into frame (usually one hand and forearm holding the product).
What background / environment is visible.
Explicitly state what is NOT in frame (face, body, torso, shoulder, head).
Include third person view, external camera, camera facing the subject, selfie of the subject in the --no list.

In-frame rule¶

Only describe what the camera will see. Check the declared framing first, then walk every wardrobe item, prop, accessory, and environment element — ask "is this visible in the final frame?" If no, omit it entirely.

Applies to: wardrobe below the crop (pants / shoes on a chest-up selfie), background details behind a tight close-up, accessories on body parts that never enter frame.

Why the in-frame rule matters

NanoBanana and Veo try to include whatever the prompt describes. If you mention pants on a chest-up crop, the model either widens the crop, invents them as hallucinated detail, or produces a contradiction. Out-of-frame mentions also cause --no list bloat that only exists because the positive prompt first raised the topic.