Variants & Versioning¶

Once a workflow ships, you'll spend more time making variants of it than building new workflows from scratch. Different hooks, different wardrobes, different settings — all riffs on the same proven structure. This page covers the version system that keeps those variants organized, and the four variant levels at a glance.

What you'll learn¶

The three phases a workflow lives in: testing → approved → variants
The four variant levels and when each one applies
How versions are named (and why each rule exists)
What counts as a "meaningful change" worth a version bump
The cross-level rules that apply to every variant, regardless of level

The version system at a glance¶

A workflow lives in three phases. The first two are linear; the third (variants) branches.

Phase 1 → 2: testing graduates to approved¶

flowchart TD
    A[V0-1<br/>testing] --> B[V0-2<br/>testing]
    B --> C[V0-N<br/>testing]
    C -.user approves<br/>+ fan-out done.-> D[V1<br/>approved]

Phase 3: variants branch off an approved version¶

flowchart TD
    D[V1<br/>approved] --> E[Lvl 1/2 variant]
    D --> F[Lvl 3/4 variant]
    E --> G[V1-1<br/>approved]
    G --> H[V1-2<br/>approved]
    F --> I[V2-0-1<br/>testing]
    I --> J[V2-0-2<br/>testing]
    J -.user approves.-> K[V2<br/>approved]

Lvl ½ variants are auto-approved (decimal bumps land directly in approved/). Lvl ¾ variants go through their own testing phase under the next major's -0-N suffix.

Three phases:

Testing — new workflow: V0-1, V0-2, ..., V0-N. No upper bound. Lives in testing/. Every iteration during testing bumps the V0-N suffix.
Approved: V1. Reached only when you explicitly approve 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	Your input
Lvl 1	~20% script/dialogue rewrite	Decimal: `V1 → V1-1`	`approved/` (auto)	None — proceed
Lvl 2	Script + 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`	`testing/` until approved	Full direction
Lvl 4	Lvl 3 + structural changes (add / remove / split scenes, new prehook)	Testing: `V1 → V2-0-1 → ... → V2`	`testing/` until approved	Direction + explicit structural approval

Why Lvl ¾ get a testing phase

Lvl ½ changes are predictable — dialogue swaps and wardrobe tweaks don't break a workflow. Lvl ¾ changes involve new prompts or new structure, so they need validation on a test account before fanning out, just like a brand-new workflow does.

Which level is this change?¶

Pick the lowest level that fits your change. Lower = lighter, faster, auto-approved.

flowchart TD
    Start[The change you want]
    Start --> Q1{Is dialogue<br/>the only thing<br/>changing?}
    Q1 -->|Yes| L1[Lvl 1<br/>auto-approved]
    Q1 -->|No| Q2{Is it only<br/>wardrobe + styling<br/>on the avatars?}
    Q2 -->|Yes| L2[Lvl 2<br/>auto-approved]
    Q2 -->|No| Q3{Are you only<br/>swapping environment,<br/>camera, or setting?}
    Q3 -->|Yes| L3[Lvl 3<br/>testing required]
    Q3 -->|No| Q4{Adding, removing,<br/>or splitting<br/>scenes?}
    Q4 -->|Yes| L4[Lvl 4<br/>testing + structural approval]
    Q4 -->|No| Surgical[Smaller than a variant<br/>see surgical edits]

The boundaries are intentional — a Lvl 2 wardrobe variant won't trigger the testing phase because wardrobe doesn't break a workflow. A Lvl 3 environment swap will, because new prompts can produce unpredictable results that need validation per account.

A worked example¶

Here's a real progression for one workflow over several months:

V0-1 → V0-2 → V0-3        iterating during initial testing on Account A
V0-3 → V0-4 → V0-5        fan-out testing across Accounts B, C, D
V0-5 → V1                 you approve, all accounts shipped, graduates to approved/
V1   → V1-1               Lvl 1 — fresh hook variant, auto-approved
V1-1 → V1-2               Lvl 2 — wardrobe change, auto-approved
V1-2 → V2-0-1             Lvl 3 — environment swap (kitchen → garage), enters testing
V2-0-1 → V2-0-2           iterating during Lvl 3 testing
V2-0-2 → V2               you approve the Lvl 3 variant, graduates to approved/
V2   → V2-1               Lvl 1 — dialogue tweak on V2, auto-approved
V2-1 → V3-0-1             Lvl 4 — restructure: add a prehook clip, enters testing
V3-0-1 → V3-0-2           iterating during Lvl 4 testing
V3-0-2 → V3               you approve the Lvl 4 variant, graduates to approved/

Every arrow above is a version bump. Every previous version is preserved.

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

Any meaningful change bumps V0-N and archives the previous version. Never overwrite a version in place — the audit trail is half the value of the version system.

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 (decimal bump from approved V1+, auto-approved)
Variant Lvl ¾ iteration (-0-N suffix on 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

How a variant request goes¶

make a Lvl 1 variant of XYZS1-V1. Try a more personal hook — swap "Doctors don't want you to know" for something confessional.

Reading version registry... XYZS1 is at V1. Lvl 1 is auto-approved, so the next version is V1-1 landing in approved/.

Pulling the Script Writer to rewrite the dialogue rows... [returns variant dialogue]

Saving XYZS1-V1-1.nbflow in approved/. Updating version registry with history entry: "V1-1 — Lvl 1 dialogue rewrite (confessional hook)" Done. Ready for generation whenever you are.

What's happening behind the scenes during a version bump

Each variant request walks through a fixed protocol:

Read the version registry at manager/reference/version-registry.json to find the current version.
Compute the next version per the level rules above.
Move the existing file to backups/ as {workflow}-V0-N.nbflow.bak-{YYYY-MM-DD}-{reason} where reason is a short slug like pre-variant, pre-fanout, pre-qa-pass, or pre-collapse.
Write the new file to growth/testing/ for Lvl ¾ testing iterations, or approved/ for auto-approved Lvl ½ variants.
Update the internal name field inside the .nbflow JSON to match the new version (it must match the filename).
Append a history entry to the registry with date, new version, status, and a one-line description of what changed.
Update current_version and last_updated on the registry entry.

You'll never need to perform these steps yourself. They run automatically every time you ask for a variant — but knowing the protocol exists is useful when something goes sideways and you need to verify the registry stayed in sync.

Rules that apply across all variant levels¶

These rules hold for every variant, regardless of level. They're not protocol — they're physics. Bake them into your mental model whenever rewriting image or video prompts.

Avatar description when a character reference image is connected¶

The avatar reference sheet locks the face only. It does not lock body, gender, age, build, or wardrobe.

Do NOT repeat gender, age, face details, hair, or ethnicity in the prompt when a ref image is wired in. That competes with the reference and degrades face lock.
DO specify what the character is wearing and their build (slim / muscular / athletic / heavier). That's it.

Video prompt location rules¶

Veo's frames-to-video mode interpolates between start frame and end frame. It can't invent a location change inside one clip unless you provide both endpoints.

NEVER prompt the avatar to move to a new location mid-clip unless there's an explicit end frame showing the new location.
Without an end frame, location changes produce hallucinated transitions that look glitchy.
If the script calls for a location change, that's a new scene with a new image gen, not motion within one clip.

POV rule¶

In a first-person POV shot the camera is the subject's eye. You can't describe the subject's body angle, face, shoulders, or "three-quarter turn toward X" from inside their own view — those sentences only make sense from an external camera. Writing them in a POV prompt silently tells the generator to flip to third-person and render a visible subject body.

POV prompts should describe:

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

If the prompt describes the subject's body orientation at all, it's not a POV prompt — it's third-person framed as POV, which is the failure mode.

In-frame rule¶

Only describe what the camera will actually see. Before writing or reviewing any image or video prompt, check the declared framing/crop 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 include whatever the prompt describes. If you mention pants on a chest-up crop, the model either widens the crop to include them, invents them as hallucinated detail, or produces a contradiction. Out-of-frame mentions also cause --no list bloat that exists only because the positive prompt first raised the topic. Keep the positive prompt tight to what's in frame, and the --no list can stay focused on protecting the framing declaration itself.

When you're ready¶

→ Next: Lvl 1 — Dialogue Swap. Start with the lightest-weight variant; the rest of the chapter builds on it.