venice-video-harness 2.11.2 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/.claude/agents/prompt-engineer.md +7 -2
  2. package/.claude/agents/storyboard-qa.md +10 -2
  3. package/.claude/commands/qa-storyboard.md +13 -5
  4. package/.claude/commands/workshop-episode.md +12 -0
  5. package/.claude/skills/character-consistency/SKILL.md +27 -2
  6. package/.claude/skills/shot-composition/SKILL.md +25 -0
  7. package/.claude/skills/venice-agent-guide/SKILL.md +2 -1
  8. package/.claude/skills/venice-video-model-routing/README.md +2 -1
  9. package/.claude/skills/venice-video-model-routing/SKILL.md +22 -5
  10. package/.claude/skills/venice-video-model-routing/references/decision-trees.md +11 -3
  11. package/AGENTS.md +10 -3
  12. package/CHANGELOG.md +106 -0
  13. package/README.md +20 -13
  14. package/dist/agent/guide.d.ts.map +1 -1
  15. package/dist/agent/guide.js +3 -2
  16. package/dist/agent/guide.js.map +1 -1
  17. package/dist/mini-drama/cli.d.ts.map +1 -1
  18. package/dist/mini-drama/cli.js +103 -14
  19. package/dist/mini-drama/cli.js.map +1 -1
  20. package/dist/mini-drama/generation-planner.d.ts.map +1 -1
  21. package/dist/mini-drama/generation-planner.js +25 -10
  22. package/dist/mini-drama/generation-planner.js.map +1 -1
  23. package/dist/mini-drama/location-generator.d.ts.map +1 -1
  24. package/dist/mini-drama/location-generator.js +4 -0
  25. package/dist/mini-drama/location-generator.js.map +1 -1
  26. package/dist/mini-drama/prompt-builder.d.ts +20 -1
  27. package/dist/mini-drama/prompt-builder.d.ts.map +1 -1
  28. package/dist/mini-drama/prompt-builder.js +272 -18
  29. package/dist/mini-drama/prompt-builder.js.map +1 -1
  30. package/dist/mini-drama/storyboard-reference-generator.d.ts.map +1 -1
  31. package/dist/mini-drama/storyboard-reference-generator.js +14 -1
  32. package/dist/mini-drama/storyboard-reference-generator.js.map +1 -1
  33. package/dist/mini-drama/video-generator.d.ts.map +1 -1
  34. package/dist/mini-drama/video-generator.js +40 -7
  35. package/dist/mini-drama/video-generator.js.map +1 -1
  36. package/dist/mini-drama/workshop.d.ts.map +1 -1
  37. package/dist/mini-drama/workshop.js +4 -2
  38. package/dist/mini-drama/workshop.js.map +1 -1
  39. package/dist/series/types.d.ts +71 -2
  40. package/dist/series/types.d.ts.map +1 -1
  41. package/dist/series/types.js +24 -0
  42. package/dist/series/types.js.map +1 -1
  43. package/package.json +1 -1
@@ -11,6 +11,8 @@ If the **Seedance 2.0 Skill OS** is installed (see this repo's README "Directing
11
11
 
12
12
  **Division of labor with the harness:** identity is locked by R2V references + the Seedance → Wan keyframe pass, and durations/model routing are decided at generation time. So direct **intention/camera/light/blocking/performance/sound**; let the pipeline own identity, duration, and routing.
13
13
 
14
+ **Blocking is geometry, not vibes (rule 49).** Identity references lock what things look like, not where they are — placement is re-inferred on every generation unless the prompt states it. Every prompt with characters or key objects must say, in concrete spatial terms: WHERE each subject is relative to the location's named landmarks (`Location.spatialAnchors`), WHERE they sit in the frame (screen left/center/right; foreground/background), and WHICH WAY they face (eyeline target). Across a scene's shots, keep screen sides, relative positions, and eyelines constant (180-degree rule) unless a movement is written into the action. The shot's authored `blocking` field is injected verbatim by the pipeline — when writing prompts by hand, restate it, never paraphrase it differently per shot.
15
+
14
16
  ## Role
15
17
  Build optimized Venice AI image generation prompts that maintain character consistency across all storyboard panels.
16
18
 
@@ -28,13 +30,15 @@ Build optimized Venice AI image generation prompts that maintain character consi
28
30
 
29
31
  [SHOT] {shot type}, {camera angle}, {lens mm}, {camera movement}
30
32
 
31
- [SETTING] {location} - {time of day}, {atmosphere details from scene action}
33
+ [SETTING] {location} - {time of day}, {atmosphere details from scene action}, fixed layout: {location spatialAnchors — named landmarks and their relative positions}
32
34
 
33
35
  [CHARACTERS]
34
- - {NAME} ({position}, {facing}): {FULL description - age, ethnicity, hair, eyes, face, build, height}, wearing {wardrobe}, expression: {emotion from context}
36
+ - {NAME} ({position relative to a named landmark}, {screen side + depth}, {facing/eyeline}): {FULL description - age, ethnicity, hair, eyes, face, build, height}, wearing {wardrobe}, expression: {emotion from context}
35
37
 
36
38
  [ACTION] {what's happening in this specific shot}
37
39
 
40
+ [BLOCKING] {the shot's authored blocking, verbatim — who is where relative to which anchor, frame side, depth, facing; consistent with adjacent shots in the scene}
41
+
38
42
  [MOOD] {scene mood}
39
43
 
40
44
  [LIGHTING] {lighting setup based on location + time + mood}
@@ -62,6 +66,7 @@ In addition to image prompts, build video-generation prompts for each shot. Vide
62
66
 
63
67
  1. **Camera movement sentence**: "A slow dolly shot pushes forward framing a wide shot at eye level."
64
68
  2. **Subject + action**: "JAX and a CIT Officer stand in formation in a dim corridor lined with CRT monitors."
69
+ - **Include the blocking geometry**: "JAX screen left at the security desk, facing right; the Officer screen right in the doorway, facing him." State each subject's position vs a named landmark, frame side, depth, and eyeline — and keep it identical to the adjacent shots' geometry unless the action moves someone.
65
70
  3. **Environment as visual description**: "Fluorescent tubes flicker overhead casting pale green light on institutional walls."
66
71
  4. **Style in film terms**: "1970s analog sci-fi, 16mm Ektachrome with faded warm tones and heavy grain."
67
72
  5. **Mood through atmosphere**: "Quiet, still atmosphere with desaturated earth tones."
@@ -18,6 +18,13 @@ Analyze generated storyboard panels for character consistency and setting contin
18
18
  - **Location**: architectural style, neon signs, background elements should be consistent
19
19
  - **Color palette**: should match the locked aesthetic profile
20
20
 
21
+ ### Spatial Continuity (against the shot's blocking + prior same-location panels)
22
+ - **Stated blocking honored**: each character/object is on the stated frame side, at the stated depth, facing the stated direction, positioned correctly relative to the location's named landmarks (`Location.spatialAnchors`)
23
+ - **Screen sides held across coverage**: characters keep the side of frame they had in the previous same-location panel unless the script moves them
24
+ - **Eyelines / screen direction (180-degree rule)**: if A looks right at B in one panel, A keeps looking right and B keeps looking left in the coverage that follows
25
+ - **Landmark stability**: doors, windows, counters, and key props have not moved, mirrored, vanished, or rearranged between panels of the same location
26
+ - A side-swap or mirrored geography that breaks the scene is **CRITICAL**; a single character on the wrong frame side vs stated blocking, or a relocated landmark, is **MODERATE**
27
+
21
28
  ### Aesthetic Adherence
22
29
  - **Style**: panels should match the series aesthetic (webtoon, anime noir, etc.)
23
30
  - **Palette**: color grading should be consistent with the locked palette
@@ -40,10 +47,11 @@ Summarize with:
40
47
  ## How To Invoke
41
48
 
42
49
  This agent is called automatically after `storyboard-episode` generates panels. It reads:
43
- 1. `series.json` for character descriptions, wardrobe, and aesthetic
44
- 2. `script.json` for which characters appear in which shots
50
+ 1. `series.json` for character descriptions, wardrobe, aesthetic, and each location's `spatialAnchors`
51
+ 2. `script.json` for which characters appear in which shots and each shot's `blocking`
45
52
  3. The generated panel PNGs in `scene-001/`
46
53
  4. Character reference images in `characters/<name>/front.png` for comparison
54
+ 5. The nearest prior panel from the same location (attached automatically by `qa-storyboard`) for spatial-continuity comparison
47
55
 
48
56
  ## Integration
49
57
  - Runs as a sub-agent via the Task tool after panel generation
@@ -32,11 +32,18 @@ Run a visual QA analysis on generated storyboard panels for character and settin
32
32
  - Art style matches locked aesthetic?
33
33
  - Color grading consistent?
34
34
 
35
+ **Spatial Continuity** (compare against the shot's `blocking`, the location's `spatialAnchors`, and the nearest prior panel in the same location):
36
+ - Each character/object on the stated frame side, at the stated depth, facing the stated direction?
37
+ - Positions correct relative to the location's named landmarks?
38
+ - Screen sides held from the previous same-location panel (no side-swaps)?
39
+ - Eyelines / screen direction preserved (180-degree rule)?
40
+ - Landmarks (doors, windows, counters, key props) unmoved — no mirroring, vanishing, or rearranging?
41
+
35
42
  5. Rate each panel:
36
- - **PASS**: Character and setting match descriptions
37
- - **FLAG-CRITICAL**: Character appearance is wrong (wrong hair, wrong outfit, wrong body type)
38
- - **FLAG-MODERATE**: Minor drift but recognizable (slightly different shade, small detail off)
39
- - **FLAG-LOW**: Stylistic variance within acceptable range
43
+ - **PASS**: Character, setting, and spatial geometry match descriptions
44
+ - **FLAG-CRITICAL**: Character appearance is wrong (wrong hair, wrong outfit, wrong body type) OR a spatial flip that breaks the scene (characters swapped sides, geography mirrored/rearranged vs the previous panel)
45
+ - **FLAG-MODERATE**: Minor drift but recognizable (slightly different shade, small detail off); character on the wrong frame side vs stated blocking; a relocated landmark
46
+ - **FLAG-LOW**: Stylistic variance or small placement deviation within acceptable range
40
47
 
41
48
  6. Present the QA report to the user:
42
49
  - Show each flagged panel inline with the specific issues
@@ -52,5 +59,6 @@ Run a visual QA analysis on generated storyboard panels for character and settin
52
59
  ## Important
53
60
  - Always load and show the character reference images alongside flagged panels for visual comparison
54
61
  - Be specific about what's wrong: "Sera's hair is shoulder-length bob in shot 4 but should be long flowing dark hair per her description"
55
- - Focus most on CRITICAL issues (wrong appearance) -- these break immersion across episodes
62
+ - Be equally specific about spatial issues: "JAX was screen left at the counter in shot 3 but is screen right in shot 4 with no scripted movement — side-swap, regenerate"
63
+ - Focus most on CRITICAL issues (wrong appearance, broken scene geography) -- these break immersion across episodes
56
64
  - Run this QA automatically after every storyboard-episode generation
@@ -2,6 +2,16 @@ Workshop an episode script collaboratively with the user.
2
2
 
3
3
  **Direct before you draft.** If the idea is vague, run the Seedance 2.0 Skill OS `seedance-interview` (short form for a fast brief); for a longer or multi-clip story run `seedance-sequence` to set the story spine and one directorial voice. Then, for every shot, name **one intention** and derive camera/light/blocking/performance/sound from it — do NOT stack "cinematic" adjectives. Read each drafted `description` back through `directing-engine`, and strip empty quality-boosters with `seedance-antislop` + `vocab/*`. If Seedance OS isn't installed, apply the same principle from memory (see this repo's README "Directing layer"). The in-code workshop system prompt (`src/mini-drama/cli.ts`) already carries this instruction; a directed concept from the user is what makes it land.
4
4
 
5
+ **Author the geometry, not just the action (rule 49).** Spatial consistency is
6
+ built into the script, not patched at generation time. Give every location a
7
+ `spatialAnchors` field (3-5 named landmarks and their fixed relative positions)
8
+ and every character shot a `blocking` field: each character/object's position
9
+ relative to those named anchors, their frame side (screen left/center/right),
10
+ depth (foreground/background), and facing/eyeline. Across consecutive shots in
11
+ a scene, characters keep their screen sides and relative positions unless a
12
+ movement is written into the action; preserve screen direction and eyelines
13
+ (180-degree rule); close-ups still name what's behind/beside the subject.
14
+
5
15
  1. Ask the user for the episode concept/outline (what happens in this episode?)
6
16
  2. Draft a shot-by-shot script in the EpisodeScript JSON format
7
17
  3. Each shot should specify:
@@ -9,6 +19,8 @@ Workshop an episode script collaboratively with the user.
9
19
  - duration (3s/5s/8s/10s/13s/15s)
10
20
  - videoModel ("action" for movement/dialogue, "atmosphere" for establishing/static)
11
21
  - description (visual scene description)
22
+ - location (slug of a defined location)
23
+ - blocking (concrete geometry: positions vs named location anchors, frame side, depth, facing/eyeline — consistent with adjacent shots)
12
24
  - characters present
13
25
  - dialogue (if any)
14
26
  - sfx (optional sound effects hint)
@@ -95,8 +95,8 @@ The most critical consistency layer for video generation. **R2V models are the o
95
95
  - **Prompt integration:** Character names replaced with `@Element1`, `@Element2` tokens
96
96
 
97
97
  ### Critical Rules
98
- 1. **Only R2V models support elements/reference_image_urls.** The Kling multi-shot model (`kling-o3-pro-image-to-video`), Kling V3 Pro, Veo 3.1, and all other non-R2V models have ZERO reference support.
99
- 2. **Never group shots with different characters into multi-shot units.** Multi-shot units use non-R2V models. Characters lose all identity anchoring.
98
+ 1. **Only R2V models support elements/reference_image_urls.** Kling V3 Pro, Veo 3.1, `kling-o3-pro-image-to-video`, and all other non-R2V models have ZERO reference support.
99
+ 2. **Never group shots with different characters into multi-shot units.** Multi-shot units render on Seedance R2V Enhanced by default (2026-08-05) with ONE slot plan per generation — disjoint characters can't all anchor correctly. (Legacy `videoDefaults.multiShotModel: kling-o3-pro-image-to-video` overrides have no references at all.)
100
100
  3. **For talk shows, interviews, and panel formats:** Set `mustStaySingle: true` on all shots to force R2V singles.
101
101
 
102
102
  ### Format-Specific Guidance
@@ -107,6 +107,31 @@ The most critical consistency layer for video generation. **R2V models are the o
107
107
  | Continuous action scene | Multi-shot OK if same characters | Temporal continuity benefits outweigh |
108
108
  | Drama with cuts | Singles for close-ups/reactions, multi-shot for continuous action | Balance both |
109
109
 
110
+ ## Layer 5: Spatial Anchoring (placement, not just appearance)
111
+
112
+ Identity references lock what a character LOOKS like; they say nothing about
113
+ WHERE the character is. Placement is re-inferred on every generation unless
114
+ each prompt states the geometry the same way (rule 49):
115
+
116
+ - **`Location.spatialAnchors`** locks a place's geography: 3-5 named landmarks
117
+ and their fixed relative positions. Injected as "Fixed layout (never
118
+ rearrange): …" into every panel/plate/video prompt for shots in that
119
+ location, and baked into the location's reference angles.
120
+ - **`ShotScript.blocking`** locks the shot's geometry: each character/object's
121
+ position relative to the named anchors, frame side (screen left/center/
122
+ right), depth, and facing/eyeline. Injected verbatim (with @ImageN name
123
+ substitution) into panel, plate, and video prompts.
124
+ - **Storyboard blocking plates** encode the same geometry visually and carry a
125
+ role clause restricting them to composition/blocking authority; the video
126
+ prompt additionally forbids mirroring/swapping who stands where.
127
+ - **Continuity rules:** characters keep their screen sides and relative
128
+ positions across a scene's shots unless a movement is scripted; eyelines
129
+ and screen direction obey the 180-degree rule; close-ups still name what's
130
+ behind/beside the subject.
131
+ - **QA:** `qa-storyboard` checks a SPATIAL CONTINUITY dimension against the
132
+ stated blocking and the previous same-location panel; a side-swap or
133
+ mirrored geography is FLAG-CRITICAL.
134
+
110
135
  ## Usage
111
136
  ```typescript
112
137
  import { buildCharacterReferencePrompt } from './mini-drama/prompt-builder.js';
@@ -47,6 +47,31 @@ When the **Seedance 2.0 Skill OS** is installed (`.claude/skills/seedance-20/`),
47
47
  5. Transitions between scenes match the screenplay's indicated transition
48
48
  6. Insert shots for objects mentioned prominently in action lines
49
49
 
50
+ ## Spatial Blocking Rules (rule 49 — placement is authored, not inferred)
51
+
52
+ AI video models re-infer placement on every generation, so shot plans must
53
+ state the geometry explicitly and keep it stable across a scene's coverage:
54
+
55
+ 1. **Anchor to the location's named landmarks.** Each `Location` carries
56
+ `spatialAnchors` (3-5 landmarks with fixed relative positions). Blocking
57
+ language must reference those names ("at the bar counter", "in the
58
+ doorway") so "by the window" means one specific window in every shot.
59
+ 2. **Every character shot gets a `blocking` field**: each character/key
60
+ object's position relative to the named anchors, their frame side (screen
61
+ left / center / right), depth (foreground / midground / background), and
62
+ facing/eyeline direction.
63
+ 3. **Hold screen sides across coverage.** Characters keep the side of frame
64
+ they had in the master unless a movement is scripted — and if they move,
65
+ the movement is the shot's action, written into the description.
66
+ 4. **Respect the 180-degree rule.** Pick the scene's axis at the master and
67
+ keep eyelines/screen direction consistent in every single and reaction:
68
+ if A looks right at B, A keeps looking right and B keeps looking left.
69
+ 5. **Close-ups still name the geography.** State what is behind/beside the
70
+ subject so backgrounds match the wide ("the neon window behind her
71
+ shoulder"), or backgrounds will drift per generation.
72
+ 6. **Establishing shots restate the full landmark layout** so the scene's
73
+ geography is re-locked at every scene boundary.
74
+
50
75
  ## Transition Types
51
76
  - **CUT**: Standard, default between shots
52
77
  - **DISSOLVE**: Time passage, dream, memory
@@ -35,10 +35,11 @@ in the other.
35
35
  - Front-load style at the START of every prompt; keep Seedance prompts under ~60 words with the 5-part structure (Subject, Action, Camera, Style, Constraints).
36
36
  - Direct the beat, do not decorate it: name one intention and derive camera/light/blocking/performance from it. Do not stack "cinematic / epic / 4k" adjectives.
37
37
  - Re-anchor every separately-rendered shot to the SAME locked references and restate the character invariant traits (including relative size) in every prompt.
38
+ - State placement explicitly in every prompt: lock each location's landmark geography (`spatialAnchors`) and give every character shot a `blocking` field (position vs named anchors, screen side, depth, facing/eyeline). Keep screen sides and eyelines constant across a scene unless a movement is scripted.
38
39
  - Prefer native model dialogue (Seedance 2.0, HappyHorse 1.1 with voice-donor references) over exact TTS lip-sync.
39
40
 
40
41
  ## Where the full knowledge lives
41
- - `AGENTS.md` — 47 rules and 27 production anti-patterns, shipped in the package.
42
+ - `AGENTS.md` — 49 rules and 28 production anti-patterns, shipped in the package.
42
43
  - `.claude/skills/` — `venice-api`, `venice-video-model-routing`, `character-consistency`, `shot-composition`, `burn-in-subtitles`, `video-editing`, and more.
43
44
  - `.claude/commands/` — 20 step-by-step playbooks; `.claude/agents/` — 10 sub-agent roles.
44
45
  - Read the relevant playbook before running a workflow. Validate model capabilities against `src/venice/models.ts` before an API call.
@@ -119,7 +119,8 @@ venice-video-model-routing/
119
119
  - `veo3.1-fast-image-to-video` -- atmosphere tier (establishing shots, inserts)
120
120
  - `kling-o3-standard-reference-to-video` -- character consistency tier (identity-critical shots, default)
121
121
  - `kling-o3-pro-reference-to-video` -- character consistency tier (higher quality, slower)
122
- - `kling-o3-pro-image-to-video` -- multi-shot units
122
+ - `seedance-2-0-enhanced-reference-to-video` -- multi-shot units (default since 2026-08-05; reference-first with `Lens switch.` separators)
123
+ - `kling-o3-pro-image-to-video` -- legacy multi-shot lane (explicit `videoDefaults.multiShotModel` override only; no reference support)
123
124
  - `vidu-q3-image-to-video` -- 1080p output with reference image support
124
125
  - `wan-2.6-image-to-video` -- configurable audio, various durations
125
126
  - `sora-2-image-to-video` -- high quality, requires aspect ratio
@@ -162,7 +162,9 @@ ACTION_MODEL = 'seedance-2-0-image-to-video'
162
162
  ATMOSPHERE_MODEL = 'seedance-2-0-image-to-video'
163
163
  CHARACTER_CONSISTENCY_MODEL = 'seedance-2-0-reference-to-video'
164
164
  KLING_R2V_MODEL = 'kling-o3-standard-reference-to-video' (fallback for 3+ chars)
165
- MULTISHOT_MODEL = 'kling-o3-pro-image-to-video'
165
+ MULTISHOT_MODEL = 'seedance-2-0-enhanced-reference-to-video' (default since 2026-08-05; resolveMultiShotModel())
166
+ # Legacy: 'kling-o3-pro-image-to-video' — explicit videoDefaults.multiShotModel override only.
167
+ # It has NO elements and NO reference_image_urls, so it drops all identity anchoring.
166
168
 
167
169
  # Single image default for ALL panels (Venice removed the Seedance face restriction, 2026-07)
168
170
  IMAGE_GENERATION = 'nano-banana-2' # character + faceless panels alike
@@ -318,6 +320,8 @@ Construct prompts differently depending on the resolved model's capabilities:
318
320
  - Dialogue speaker uses image ref: `[@Image1, voice description, delivery]: "dialogue line"`
319
321
  - Attach `reference_image_urls` at the API layer in the slot-planner order (up to 9: character primaries → storyboard blocking plate → location angles → second character angles)
320
322
  - Emit a role clause per non-character slot: location angles ("@Image4 is a second angle of the same location"), blocking plates ("use ONLY for composition, blocking, and spatial relationships")
323
+ - Carry the shot's authored `blocking` verbatim (`Blocking: @Image1 at the bar counter, screen left, facing right; …`) and the location's `spatialAnchors` ("Fixed layout (never rearrange): …") — placement is stated per shot, never left to the model (rule 49)
324
+ - With a blocking plate bound, the prompt also pins geometry to it: characters keep their side of the scene and position relative to the plate's landmarks — no mirroring, swapping, or rearranging; plateless location shots pin geography to the first location `@ImageN` slot instead
321
325
  - **Pure reference mode:** no `image_url` start frame when the slot plan is populated — references carry all consistency
322
326
  - Keep prompts concise. Use the 5-part structure: Subject, Action, Camera, Style, Constraints.
323
327
  - Use physics-aware language: describe forces and materials, not just actions
@@ -345,9 +349,22 @@ Construct prompts differently depending on the resolved model's capabilities:
345
349
  - Structure: camera term first, then description, then dialogue with delivery cues
346
350
  - Veo requires `resolution: '720p'`; Kling does NOT accept `resolution`/`aspect_ratio` (derived from input image)
347
351
 
348
- ### Native Multi-Shot (Kling 3.0, up to 6 shots, 15s max)
352
+ ### Native Multi-Shot (default: Seedance R2V Enhanced with `Lens switch.`)
349
353
 
350
- Kling 3.0 supports native multi-shot generation — a single prompt produces a single video with multiple distinct shots and automatic cuts between them. This works with the R2V model (`kling-o3-standard-reference-to-video`) which supports `elements` for identity anchoring across all shots.
354
+ **Multi-shot units render on `seedance-2-0-enhanced-reference-to-video` by default (2026-08-05)** — the same reference-first lane as singles. `buildMultiShotPrompt()` produces ONE Seedance generation covering the window's beats:
355
+
356
+ 1. **Identity declarations up front** from the unit's @Image slot plan: `@Image1 is Bob — wearing …`
357
+ 2. **Role clauses** for the non-character slots (blocking plate, location angles) — identical clause text to singles
358
+ 3. **Per-beat blocks** labeled `Shot N (Xs):` with camera, description (names → `@ImageN`), authored `Blocking:` restated per beat (rule 49), and `[@ImageN, voice, delivery]: "line"` dialogue
359
+ 4. **Literal `Lens switch.` lines** between beats (rule 21)
360
+ 5. **Geometry hold** pinned to the plate (or first location angle): no mirroring/swapping across the internal cuts
361
+ 6. Compact aesthetic + audio-exclusion suffix; ≤2500 chars
362
+
363
+ The unit renders in **pure reference mode** — `reference_image_urls` pushed in slot-plan order, no `image_url` start frame — and takes voice-donor `reference_audio_urls` (@AudioN) for its dialogue speakers. Grouping windows never span locations (one slot plan per generation).
364
+
365
+ ### Legacy Multi-Shot Format (Kling 3.0 — explicit override only)
366
+
367
+ Used only when `videoDefaults.multiShotModel` is explicitly set to a non-@Image-tag model (e.g. `kling-o3-pro-image-to-video`, which has NO reference support — identity is prompt-text only).
351
368
 
352
369
  **Prompt structure (per [Kling 3.0 Prompting Guide](https://blog.fal.ai/kling-3-0-prompting-guide/)):**
353
370
  1. **Define subjects up front** with `@Element` refs and traits — Kling locks these across all shots
@@ -400,7 +417,7 @@ For formats with **frequent speaker cuts** (talk shows, interviews, debate panel
400
417
 
401
418
  ### All Character Shots Must Be R2V Singles
402
419
 
403
- - **Never group shots with different speakers into multi-shot units.** The Kling multi-shot model (`kling-o3-pro-image-to-video`) does NOT support `elements` or `reference_image_urls` — characters lose all identity anchoring.
420
+ - **Never group shots with different speakers into multi-shot units.** Even on the reference-first Seedance multi-shot default, a unit builds ONE slot plan for the window — disjoint speakers mean the plan can't anchor everyone correctly. (On the legacy Kling override the failure is total: `kling-o3-pro-image-to-video` has NO `elements` or `reference_image_urls`, so characters lose all identity anchoring.)
404
421
  - **Set `mustStaySingle: true`** on all shots in talk show scripts, or ensure the generation planner only groups shots that share the same characters.
405
422
  - **Every character shot uses R2V** — `seedance-2-0-reference-to-video` for 1-2 character shots (flat `reference_image_urls` with `@Image` tags), auto-fallback to `kling-o3-standard-reference-to-video` for 3+ characters (structured `elements`).
406
423
 
@@ -443,7 +460,7 @@ Seedance 2.0 (now the default for both atmosphere and character shots) accepts *
443
460
 
444
461
  ### Identity Failures
445
462
 
446
- - **Grouping different-character shots into multi-shot units:** The Kling multi-shot model has no reference image support. Characters rendered in a multi-shot unit with no `elements` lose identity completely. Always verify pairwise character overlap before grouping.
463
+ - **Grouping different-character shots into multi-shot units:** A multi-shot unit builds ONE reference slot plan for the window — disjoint characters can't all anchor correctly (and on the legacy Kling override there are no references at all). Always verify pairwise character overlap before grouping.
447
464
  - **Frame chaining when new character enters:** The video model invents the new character's appearance from nothing. Always use the panel image (which was refined against character references) as the start frame when a new character appears.
448
465
  - **Multi-edit with more than 2 character references:** The multi-edit endpoint accepts max 3 images total (base + 2 refs). Exceeding this drops references silently.
449
466
  - **Sequential action in image descriptions:** Causes comic-panel layouts instead of single frames. Separate the single-frame panel description from the full video action description.
@@ -202,7 +202,12 @@ Legend: Y = supported, X = not supported, (400) = returns HTTP 400 error
202
202
 
203
203
  ## 7. Multi-Shot Grouping Decision Tree
204
204
 
205
- Determines whether consecutive shots should be grouped into a single Kling multi-shot unit or rendered as individual R2V singles.
205
+ Determines whether consecutive shots should be grouped into a single native
206
+ multi-shot unit or rendered as individual R2V singles. Multi-shot units render
207
+ on `seedance-2-0-enhanced-reference-to-video` by default (2026-08-05) — one
208
+ reference-first generation with `Lens switch.` separators, carrying the full
209
+ @Image slot plan. The Kling i2v lane is an explicit
210
+ `videoDefaults.multiShotModel` override only.
206
211
 
207
212
  ```
208
213
  INPUT: window of consecutive shots
@@ -216,13 +221,16 @@ START
216
221
  | -> SINGLES (these should always render independently)
217
222
  |
218
223
  +-- total duration exceeds 15s?
219
- | -> SINGLES (exceeds Kling multi-shot limit)
224
+ | -> SINGLES (exceeds the single-generation limit on both lanes)
225
+ |
226
+ +-- shots span more than one location?
227
+ | -> SINGLES (one slot plan per generation — rule 21b)
220
228
  |
221
229
  +-- do consecutive pairs share at least one character?
222
230
  | |
223
231
  | NO -> SINGLES (different characters lose R2V anchoring)
224
232
  | |
225
- | YES -> GROUP (temporal continuity benefits outweigh)
233
+ | YES -> GROUP (identity/environment/lighting hold inside one generation)
226
234
  |
227
235
  +-- CRITICAL: for talk shows / interviews / panels:
228
236
  -> PREFER SINGLES (identity anchoring > temporal continuity)
package/AGENTS.md CHANGED
@@ -383,7 +383,7 @@ Use `POST /video/quote` (via `quoteVideo()`) to estimate costs before committing
383
383
  15. **Match lighting across consecutive shots in the same location.** When generating panels for sequential shots in the same environment, style-match later shots against earlier ones. Explicitly describe the established lighting in each subsequent prompt.
384
384
  16. **Use `silhouetteCharacters` for distant/silhouetted figures.** Characters visible only as silhouettes (e.g., figure in doorway) go in `silhouetteCharacters`, not `characters`. This ensures they appear in panels without triggering R2V routing or "no people" negative prompts.
385
385
  17. **Describe the Venice AI logo as crossed-keys, never as "triple-V" or "VVV".** The actual logo is two ornate skeleton keys crossed in an X with a chevron/book at top. Use the full geometric description in prompts, or multi-edit with the logo PNG as reference.
386
- 18. **Use Kling 3.0 native multi-shot for sequences within a single generation.** Structure: define subjects with `@Element` refs up front, label shots as `Shot N (Xs):`, use `[Character, voice description]: "dialogue"` format, and separate shots with `Immediately, cut to:`. This produces a single video with multiple shots — no concatenation needed. Max 6 shots, 15s total. See [Kling 3.0 Prompting Guide](https://blog.fal.ai/kling-3-0-prompting-guide/).
386
+ 18. **Multi-shot units render on Seedance 2.0 R2V Enhanced by default (2026-08-05) — the Kling multi-shot lane is an explicit override only.** `DEFAULT_MULTISHOT_MODEL` / `resolveMultiShotModel()` in `src/series/types.ts` route every multi-shot generation unit to the SAME reference-first lane as singles: one Seedance native multi-shot generation with `Lens switch.` separators (rule 21), anchored to the full @Image slot plan (character sheets, blocking plate, location angles) in pure reference mode — no start frame. `buildMultiShotPrompt()` dispatches on the resolved model. The old default, `kling-o3-pro-image-to-video`, has NO `elements` and NO `reference_image_urls` support, so every multi-shot unit silently dropped ALL identity anchoring (anti-pattern 1's trap, and the reason grouping rules had to police characters so hard). To deliberately use the Kling format anyway, set `videoDefaults.multiShotModel: "kling-o3-pro-image-to-video"` — the legacy Kling 3.0 structure (subjects up front, `Shot N (Xs):` labels, `[Character, voice]: "dialogue"`, `Immediately, cut to:` separators, max 6 shots / 15s; see the [Kling 3.0 Prompting Guide](https://blog.fal.ai/kling-3-0-prompting-guide/)) is kept behind that override.
387
387
  19. **Seedance 2.0 R2V uses `@Image` tags, not `@Element` tags.** When the resolved model is Seedance R2V, replace character names with `@Image1`, `@Image2` in prompts. Do NOT use `@Element` tags — Seedance does not support structured elements. The prompt builder handles this automatically via `useImageTags`.
388
388
  20. **Keep Seedance prompts under 60 words for best results.** Seedance responds to precision, not volume. Use the 5-part structure: Subject, Action (present tense, one verb), Camera (shot size + movement), Style (lighting, color), Constraints (what to exclude). See [Seedance prompting guide](https://venice.ai/blog/seedance-sota-video-generation-live-on-venice).
389
389
  21. **Default to Seedance native multi-shot for any 2–3 beat scene.** Before planning a bundle of separate Seedance renders, first ask whether the beats can fit into ONE generation up to 15s with `Lens switch.` separators between them. The native multi-shot path is the default; bundled separate renders are the fallback. Identity, environment, and lighting hold across the lens switches inside a single generation, and the result costs and takes ~3× less than three separate renders. Reach for a bundle only when (a) a beat needs Wan 2.7 lip-sync to a specific dialogue MP3, (b) beats span different locations or non-overlapping characters, or (c) total runtime > 15s. Prompt structure: one front-loaded STYLE + character anchor at the top, then per-beat `Shot N (Xs): ...` blocks with the 5-part structure (Subject, Action, Camera, Style, Constraints) kept under ~50 words each, separated by literal `Lens switch.` lines. Pass character refs once via `reference_image_urls` and reference them inline as `@Image1`, `@Image2`, etc. in every beat.
@@ -422,14 +422,16 @@ Use `POST /video/quote` (via `quoteVideo()`) to estimate costs before committing
422
422
 
423
423
  48. **The CLI is self-describing — discover state and order from it, do not guess.** `venice-video agent-guide [--json]` prints the core operating rules (this section in miniature) and ships inside the binary, so it is available even on a bare global install with no `AGENTS.md`. `venice-video pipeline [--json]` prints the ordered stages, their gates, and the command that advances each; it mirrors `classifyEpisode` in `src/session/status.ts` (rule 45 — change both together). `venice-video status -p <project> [--json]` reports where a project stands and the next command. `--json` is supported on `status`, `pipeline`, `agent-guide`, `doctor`, and `queue` (and globally as `venice-video --json <command>`); it prints exactly one JSON object on stdout, and the human text rendering is unchanged. Exit codes are honest — `status` with no project exits non-zero — and ordinary errors are a clean `error:` line, not a stack trace (`VENICE_VIDEO_DEBUG=1` for the stack). The condensed guide is kept in `src/agent/guide.ts` and duplicated as an installable skill at `.claude/skills/venice-agent-guide/`; when a non-negotiable here changes, change those two as well.
424
424
 
425
+ 49. **Spatial consistency is authored, not inferred — every prompt states placement relative to locked anchors (2026-08-05).** Visual consistency (identity, wardrobe, palette) is handled by the reference stack, but *spatial* consistency — who stands where, which side of frame, facing which way, relative to which landmark — drifts unless it is stated the same way in every generation. The harness now carries geometry as first-class data: (a) **`Location.spatialAnchors`** is the locked geography of a place — 3-5 named landmarks and their fixed relative positions ("bar counter along the back wall; entrance door opposite it; neon window left of the door as seen from the counter"). It is baked into the location reference angles at generation time, injected as "Fixed layout (never rearrange): …" into every panel and video prompt for shots tagged with the location, and is sticky on merge — an existing anchor set is never overwritten by a later script part. (b) **`ShotScript.blocking`** is the shot's authored geometry — 1-2 sentences placing each character/object relative to the named anchors, the frame (screen left/right, foreground/background), and their facing/eyeline. The workshop and script LLM prompts require it for every character shot, with continuity rules: characters keep their screen side and relative positions across consecutive shots unless a movement is written into the action; screen direction and eyelines are preserved (180-degree rule); close-ups still name what is behind/beside the subject. It is injected verbatim (with @ImageN/@ElementN name substitution) into the panel prompt (`BLOCKING: …`), the video prompt (`Blocking: …`), the multi-shot per-beat blocks (both the Seedance native lane and the legacy Kling format), and it seeds the beat's storyboard blocking-plate description. (c) The video prompt's plate clause now forbids mirroring/swapping ("each character stays on the same side of the scene… do not mirror, swap, or rearrange who stands where"), and plateless location shots get a geography-hold clause anchored to the location's first `@ImageN` slot. (d) **QA reads geometry**: `qa-storyboard` evaluates a fourth SPATIAL CONTINUITY dimension against the shot's stated blocking and the location's landmarks, and attaches the nearest prior panel from the same location so side-swaps, mirrored geography, and moved landmarks are caught against real coverage — a spatial flip that breaks the scene is FLAG-CRITICAL. (e) `workshop-episode` warns when character shots are missing `blocking` or locations are missing `spatialAnchors`; `insert-shot` inherits the anchor shot's location and blocking (same-scene splices keep the established geography) and takes `--location` / `--blocking` overrides; `add-location` takes `--spatial-anchors`. The failure mode this kills: characters teleporting across the room, swapping frame sides between coverage, and set geography silently mirroring between shots that read as the same scene (see anti-patterns 20 and 26).
426
+
425
427
  ## Learned Anti-Patterns (Production Issues Log)
426
428
 
427
429
  Issues discovered during production and their fixes. The agent should internalize these to avoid repeating them.
428
430
 
429
431
  ### 1. Multi-Shot Grouping Bug: Wrong Character Overlap Check
430
- **Symptom:** Shots cutting between different characters (e.g., Chad-only → Vivienne-only) were grouped into Kling multi-shot units, which use `kling-o3-pro-image-to-video` — a model with NO `elements` or `reference_image_urls` support. Characters lost all identity anchoring.
432
+ **Symptom:** Shots cutting between different characters (e.g., Chad-only → Vivienne-only) were grouped into multi-shot units, which at the time used `kling-o3-pro-image-to-video` — a model with NO `elements` or `reference_image_urls` support. Characters lost all identity anchoring.
431
433
  **Root cause:** `hasOverlappingCharacters()` checked each shot's characters against the union pool instead of requiring pairwise overlap between consecutive shots.
432
- **Fix:** Rewrote to require every consecutive pair of shots to share at least one character. Shots with disjoint characters now always render as singles with R2V.
434
+ **Fix:** Rewrote to require every consecutive pair of shots to share at least one character. Shots with disjoint characters now always render as singles with R2V. (2026-08-05: the referenceless-model half of this trap was removed at the root — multi-shot units now default to Seedance R2V Enhanced with the full reference slot plan, see rule 18. The pairwise-overlap check remains because grouping disjoint characters is still wrong on any lane.)
433
435
  **File:** `src/mini-drama/generation-planner.ts`
434
436
 
435
437
  ### 2. Character Reference Style Inconsistency Across Angles
@@ -594,6 +596,11 @@ Issues discovered during production and their fixes. The agent should internaliz
594
596
  **Symptom:** (a) R2V/i2v requests with human-face references returned 409 `needs_consent`. (b) After ~20 failed queue attempts, the account tripped a 30s 429.
595
597
  **Fix:** (a) Attach `consents.seedance: { confirmed_terms_and_privacy: true, confirmed_legal_right: true, confirmed_screening_acknowledged: true }` to `/video/queue` for face-bearing requests — surface the policy text once per session for the user to ack, then auto-attach. (b) Back off on repeated 4xx; don't hammer the queue endpoint.
596
598
 
599
+ ### 28. Spatial Drift Across Shots: Side-Swaps, Teleporting Props, Mirrored Geography
600
+ **Symptom:** Two shots that read as the same scene disagree spatially — a character who was screen-left in the master is screen-right in coverage; a prop on the table has moved or vanished; the room's layout is mirrored (door now on the other side); eyelines cross the 180-degree line so speakers appear to look the same way.
601
+ **Root cause:** Prompts described the *action* but left placement implicit, so every generation re-inferred the geometry from scratch. Identity references lock what things look like, not where they are; the blocking plate helps, but a plate alone (without matching placement language in the prompt) is a weak anchor the model can reinterpret or mirror.
602
+ **Fix:** Author the geometry once and restate it identically everywhere (rule 49): lock each location's landmark layout in `Location.spatialAnchors`, write per-shot `blocking` (position vs named anchors + frame side + depth + facing/eyeline), and let the harness inject both into panel, plate, and video prompts verbatim. Keep screen sides and eyelines constant across a scene's shots unless a movement is scripted. QA panels for spatial continuity against the previous same-location panel (the fourth `qa-storyboard` dimension); treat a side-swap or mirrored geography as FLAG-CRITICAL and re-roll before rendering video.
603
+
597
604
  ## Output
598
605
 
599
606
  Generated project output belongs in:
package/CHANGELOG.md CHANGED
@@ -1,5 +1,111 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.13.0 — 2026-08-05
4
+
5
+ ### Changed
6
+
7
+ - **Multi-shot units now default to Seedance 2.0 R2V Enhanced — the Kling i2v
8
+ lane is an explicit override only.** `DEFAULT_MULTISHOT_MODEL` /
9
+ `resolveMultiShotModel()` (new, `src/series/types.ts`) route every
10
+ multi-shot generation unit to `seedance-2-0-enhanced-reference-to-video`,
11
+ the same reference-first lane as singles. The old default,
12
+ `kling-o3-pro-image-to-video`, has NO `elements` and NO
13
+ `reference_image_urls` support, so every multi-shot unit silently dropped
14
+ all identity anchoring (anti-pattern 1's underlying trap). Specifics:
15
+ - **New `buildMultiShotPrompt()`** dispatches on the resolved model. The
16
+ Seedance path builds ONE native multi-shot generation per rule 21:
17
+ identity declarations from the unit's @Image slot plan up front, role
18
+ clauses for the blocking plate and location angles, per-beat
19
+ `Shot N (Xs):` blocks (names → `@ImageN`, authored `Blocking:` restated
20
+ per beat, `[@ImageN, voice, delivery]: "line"` dialogue), literal
21
+ `Lens switch.` separators, and a geometry-hold clause pinned to the plate
22
+ (rule 49). ≤2500-char video prompt cap with aesthetic-first trimming.
23
+ - **Pure reference mode for the whole unit:** `reference_image_urls` pushed
24
+ in slot-plan order (union of the window's characters + the beat's plate +
25
+ location angles), no `image_url` start frame, no `end_image_url`. The
26
+ unit also carries voice-donor `reference_audio_urls` (@AudioN) for its
27
+ dialogue speakers, deduped across beats within Venice's 3-clip budget.
28
+ - **Planner:** unit type renamed `kling-multishot` → `multishot` (the old
29
+ name still parses from existing generation-plan.json files); units carry
30
+ the resolved model; multi-shot windows can no longer span locations
31
+ (rule 21b — one slot plan per generation); the 15s window limit message
32
+ no longer names Kling (both lanes cap at 15s).
33
+ - **Override:** `videoDefaults.multiShotModel` (new) selects another lane
34
+ explicitly — setting it to `kling-o3-pro-image-to-video` restores the
35
+ legacy Kling 3.0 format (`buildKlingMultiShotPrompt` is retained and
36
+ still exported). `KLING_MULTISHOT_MODEL` is deprecated but resolvable.
37
+ - **Docs:** AGENTS.md rule 18 rewritten (Seedance default, Kling as
38
+ override), anti-pattern 1 annotated, `venice-video-model-routing`
39
+ (SKILL/README/decision trees) and `character-consistency` updated.
40
+ - **Tests:** `test-spatial-consistency.mjs` now covers the dispatcher —
41
+ default resolution, Lens-switch structure, slot plan (plate + location),
42
+ per-beat blocking with @ImageN substitution, geometry hold, and the
43
+ explicit Kling override path; `audio-routing.test.mjs` asserts the
44
+ grouped unit renders on Seedance R2V.
45
+
46
+ ## 2.12.0 — 2026-08-05
47
+
48
+ ### Added
49
+
50
+ - **Spatial consistency is now authored data, not per-generation inference
51
+ (rule 49).** Visual consistency was already reference-anchored, but *where*
52
+ characters and objects sit — screen side, depth, facing, position relative to
53
+ the set — was re-inferred by the model on every generation, which is where
54
+ side-swaps, teleporting props, and mirrored geography came from
55
+ (anti-pattern 28). Two new fields carry the geometry through the whole
56
+ pipeline:
57
+ - **`Location.spatialAnchors`** — the locked geography of a place: 3-5 named
58
+ landmarks and their fixed relative positions. Baked into the location's
59
+ reference angles at generation time, injected as
60
+ `Fixed layout (never rearrange): …` into every panel and video prompt for
61
+ shots tagged with the location, and sticky on merge (an existing anchor
62
+ set is never overwritten by a later script part). `add-location` takes
63
+ `--spatial-anchors`.
64
+ - **`ShotScript.blocking`** — the shot's authored geometry: 1-2 sentences
65
+ placing each character/object relative to the named anchors, the frame
66
+ (screen left/right, foreground/background), and their facing/eyeline.
67
+ Injected verbatim (with `@ImageN`/`@ElementN` name substitution) into the
68
+ panel prompt (`BLOCKING: …`), the video prompt (`Blocking: …`), and the
69
+ Kling multi-shot per-shot blocks; it also seeds the beat's storyboard
70
+ blocking-plate description. `insert-shot` inherits the anchor shot's
71
+ location and blocking for same-scene splices and takes `--location` /
72
+ `--blocking` overrides.
73
+ - **The script LLM is now required to author the geometry.** Both workshop
74
+ system prompts (`workshop` in `workshop.ts` and `workshop-script` in
75
+ `cli.ts`) demand `spatialAnchors` per location and `blocking` per character
76
+ shot, with continuity rules: characters keep their screen sides and relative
77
+ positions across consecutive shots unless a movement is written into the
78
+ action, screen direction and eyelines obey the 180-degree rule, and blocking
79
+ always references the location's named anchors. `workshop-script` warns when
80
+ character shots are missing `blocking` or locations are missing
81
+ `spatialAnchors` (post-condition advisory, same pattern as the duration and
82
+ no-music checks).
83
+ - **`qa-storyboard` reads geometry.** A fourth SPATIAL CONTINUITY dimension
84
+ checks each panel against the shot's stated blocking and the location's
85
+ landmarks, and the command now attaches the nearest prior panel from the
86
+ same location so side-swaps, mirrored geography, and moved landmarks are
87
+ caught against real coverage instead of prose alone. A spatial flip that
88
+ breaks the scene is FLAG-CRITICAL; a wrong frame side or relocated landmark
89
+ is FLAG-MODERATE.
90
+ - **Stronger geometry clauses in video prompts.** The blocking-plate clause now
91
+ explicitly forbids mirroring/swapping ("each character stays on the same
92
+ side of the scene… do not mirror, swap, or rearrange who stands where"), and
93
+ plateless location shots get a geography-hold clause pinned to the location's
94
+ first `@ImageN` slot. Blocking plates themselves are prompted for legible
95
+ placement (screen side, distance, facing, landmark relations readable in one
96
+ look) and carry the location's fixed layout.
97
+ - **Docs and knowledge pack updated together:** AGENTS.md rule 49 +
98
+ anti-pattern 28, README "carry these" rule 8, `agent-guide` (binary +
99
+ `venice-agent-guide` skill), `shot-composition` (spatial blocking rules),
100
+ `character-consistency` (Layer 5: spatial anchoring),
101
+ `venice-video-model-routing` (blocking/fixed-layout prompt lines),
102
+ `prompt-engineer` ([BLOCKING] template section), `storyboard-qa`, and the
103
+ `qa-storyboard` / `workshop-episode` playbooks.
104
+ - **Tests:** `tests/test-spatial-consistency.mjs` covers blocking injection in
105
+ panel/video/multi-shot prompts, `@ImageN` substitution inside blocking,
106
+ fixed-layout injection, the no-mirroring and geography-hold clauses, plate
107
+ descriptions inheriting blocking, and the workshop prompt contract.
108
+
3
109
  ## 2.11.2 — 2026-08-05
4
110
 
5
111
  ### Changed
package/README.md CHANGED
@@ -40,7 +40,7 @@ knowledge reaches you, which is the single largest predictor of output quality.
40
40
 
41
41
  | Surface | How it runs | What you get | Use when |
42
42
  |---|---|---|---|
43
- | **Repo-resident agent** | Agent's cwd is a clone of this repo | Everything: `AGENTS.md` (47 rules, 20 anti-patterns), `.claude/commands/`, `.claude/agents/`, `.claude/skills/`, `.cursor/rules/` | Authoring and iteration — the best results by a wide margin |
43
+ | **Repo-resident agent** | Agent's cwd is a clone of this repo | Everything: `AGENTS.md` (49 rules, 28 anti-patterns), `.claude/commands/`, `.claude/agents/`, `.claude/skills/`, `.cursor/rules/` | Authoring and iteration — the best results by a wide margin |
44
44
  | **MCP** | `venice-video-mcp` (on npm) shells out to this CLI | 7 action-discriminated tools, structured JSON responses, progress notifications, plus 4 companion skills carrying the pipeline order | Any agent that supports MCP — Hermes, OpenClaw, Cursor, Claude — with no clone required |
45
45
  | **Bare global CLI** | `npm install -g`, shell tool, `--help` | The compiled CLI, this README, `AGENTS.md`, `.claude/skills/`, and the self-describing commands below (`agent-guide`, `pipeline`) | When your runner has a shell but no MCP — start with `venice-video agent-guide` |
46
46
 
@@ -420,8 +420,8 @@ everything else falls back to a default rather than prompting.
420
420
 
421
421
  ### The rules that most affect output quality
422
422
 
423
- Full text lives in `AGENTS.md` > "Agent Rules" (47 rules) and "Learned
424
- Anti-Patterns" (20 entries). If you can only carry a few, carry these:
423
+ Full text lives in `AGENTS.md` > "Agent Rules" (49 rules) and "Learned
424
+ Anti-Patterns" (28 entries). If you can only carry a few, carry these:
425
425
 
426
426
  1. **Direct the scene, don't decorate it.** Name one intention for the beat and
427
427
  derive camera, light, blocking, performance, and sound from it. Stacking
@@ -443,16 +443,23 @@ Anti-Patterns" (20 entries). If you can only carry a few, carry these:
443
443
  7. **Re-anchor every separately-rendered shot to the same locked references** and
444
444
  restate the character's invariant traits — including relative size — in every
445
445
  prompt.
446
- 8. **Pass `aspectRatio` explicitly** on reference-to-video generation.
447
- 9. **Never multi-edit close-up face shots on 16:9 panels.** The square-to-16:9
448
- crop removes roughly 25% top and bottom, losing foreheads and chins.
449
- 10. **Archive prior renders; never delete generated shot assets.**
450
- 11. **Validate model capabilities before sending** `elements`,
446
+ 8. **State placement explicitly — spatial consistency is authored, not
447
+ inferred.** Lock each location's landmark geography in
448
+ `Location.spatialAnchors` and give every character shot a `blocking` field:
449
+ each subject's position relative to the named anchors, screen side, depth,
450
+ and facing/eyeline. Keep screen sides and eyelines constant across a scene's
451
+ shots unless a movement is scripted (180-degree rule). The harness injects
452
+ both verbatim into panel, blocking-plate, and video prompts.
453
+ 9. **Pass `aspectRatio` explicitly** on reference-to-video generation.
454
+ 10. **Never multi-edit close-up face shots on 16:9 panels.** The square-to-16:9
455
+ crop removes roughly 25% top and bottom, losing foreheads and chins.
456
+ 11. **Archive prior renders; never delete generated shot assets.**
457
+ 12. **Validate model capabilities before sending** `elements`,
451
458
  `reference_image_urls`, `scene_image_urls`, `end_image_url`, or `audio_url`.
452
459
  The registry is `src/venice/models.ts` in a clone; from a global install use
453
460
  `.claude/skills/venice-video-model-routing/SKILL.md` or the model tables
454
461
  below.
455
- 12. **Ask before burning in subtitles**, and derive caption timings from
462
+ 13. **Ask before burning in subtitles**, and derive caption timings from
456
463
  `ffmpeg silencedetect` on the rendered voiceover rather than estimating them.
457
464
 
458
465
  ### Checkpoints where you should stop and ask
@@ -463,11 +470,11 @@ with TTS, burning in subtitles, upscaling to a 4K master, and any run whose
463
470
  quote you have not shown the operator. Post a short summary of what you are
464
471
  about to do and wait.
465
472
 
466
- ## Supported Venice Models (April 2026)
473
+ ## Supported Venice Models
467
474
 
468
475
  ### Video Models
469
476
 
470
- Live catalog as of **2026-05-20** (synced against `GET /api/v1/models?type=video` — 103 entries). Families the harness routes to today; private / `-video-to-video` / `-extend-video` variants exist in the live catalog but aren't surfaced here.
477
+ Live catalog (synced against `GET /api/v1/models?type=video` — 103 entries). Families the harness routes to today; private / `-video-to-video` / `-extend-video` variants exist in the live catalog but aren't surfaced here.
471
478
 
472
479
  | Family | Image-to-Video | Text-to-Video | Max Duration | Audio | Special Features |
473
480
  |--------|---------------|---------------|-------------|-------|-----------------|
@@ -501,7 +508,7 @@ Live catalog as of **2026-05-20** (synced against `GET /api/v1/models?type=video
501
508
 
502
509
  > **Seedance face rule (removed 2026-07):** Seedance 2.0 used to reject face-bearing input images that weren't produced by `seedream-v5-lite` / `seedream-v5-lite-edit`. Venice removed that restriction — any image family now works for face-bearing inputs, so the harness uses `nano-banana-2` for all panels. See [Image / Video Family Pairing](#image--video-family-pairing) below.
503
510
 
504
- ### Image Models (28 entries, 2026-05-20 sync)
511
+ ### Image Models (28 entries)
505
512
 
506
513
  `nano-banana-pro`, `nano-banana-2`, `gpt-image-2` (high-quality alternative to `nano-banana-pro`), `gpt-image-1-5`, `flux-2-pro`, `flux-2-max`, `grok-imagine-image`, `grok-imagine-image-quality`, `hunyuan-image-v3`, `imagineart-1.5-pro`, `qwen-image-2`, `qwen-image-2-pro`, `recraft-v4`, `recraft-v4-pro`, `seedream-v4`, `seedream-v5-lite`, `chroma`, `hidream`, `venice-sd35`, `lustify-sdxl`, `lustify-v7`, `lustify-v8`, `wai-Illustrious`, `z-image-turbo`, `ernie-image`, `ernie-image-turbo`, `wan-2-7-text-to-image`, `wan-2-7-pro-text-to-image`, `bria-bg-remover`
507
514
 
@@ -519,7 +526,7 @@ New since the last sync: `grok-imagine-image`, `grok-imagine-image-quality`, `lu
519
526
  - **SFX**: `elevenlabs-sound-effects-v2`, `mmaudio-v2-text-to-audio`
520
527
  - **TTS (ElevenLabs)**: `elevenlabs-tts-v3`, `elevenlabs-tts-multilingual-v2`
521
528
 
522
- ### The intelligence model (2026-08-05 sync)
529
+ ### The intelligence model
523
530
 
524
531
  Three steps in the pipeline reason rather than render: the **workshop** develops
525
532
  the project, **workshop-script** writes the shot script, and **qa-storyboard**
@@ -1 +1 @@
1
- {"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/agent/guide.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,WAAW,EAAE,SAAS,YAAY,EAoD9C,CAAC;AAEF,wBAAgB,WAAW,IAAI;IAAE,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,CAE/E;AAED,wBAAgB,WAAW,IAAI,MAAM,CAWpC"}
1
+ {"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/agent/guide.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,WAAW,EAAE,SAAS,YAAY,EAqD9C,CAAC;AAEF,wBAAgB,WAAW,IAAI;IAAE,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,CAE/E;AAED,wBAAgB,WAAW,IAAI,MAAM,CAWpC"}