@slatesvideo/shared 0.6.0 → 0.6.2

package/exports/slates-prompt-builder/generated/slates-prompt-builder-manifest.json

@@ -28,7 +28,7 @@
     },
     {
       "path": "src/prompts/model-facts.ts",
-      "sha256": "98f77646a75ae2078c5015638c416d1eb84de4fe057079f705439f1a16e30631"
+      "sha256": "89a899444c021975df0a03a87b446217cdfc3b9086ef501e9e847936d7cfec2d"
     }
   ],
   "outputs": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slatesvideo/shared",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Shared operations layer for the Slates MCP server and CLI: auth, cloud/desktop clients, and the single tool surface both consume. Most users want @slatesvideo/mcp-server or @slatesvideo/cli instead.",
   "license": "MIT",
   "type": "module",

package/skills/slates-blocking-to-prompt.md

@@ -0,0 +1,250 @@
+---
+name: slates-blocking-to-prompt
+description: Write the generation prompt that matches a blocking clip second by second, so the reference video and the text agree instead of fighting. Use after rendering a previs blocking pass, when a generated shot ignores the reference video, when timings drift, or when the model invents shots and camera angles that are not in the blocking.
+---
+
+# Blocking → prompt
+
+You have a blocking clip. This is how you write the prompt that goes with it.
+
+## The one idea
+
+The clip already contains the camera, the cuts and the timing. **The prompt's job is to say what everything looks like — and, where the grey boxes are ambiguous, to disambiguate them.** It is not a second, competing description of the motion.
+
+State that contract inside the prompt, because the model needs it as much as you do:
+
+> Where a timeline line below names a camera position or move, it is a restatement of what the reference video already does at that timestamp — a disambiguation, never a new instruction.
+
+And give it a tie-break, because ambiguity is guaranteed:
+
+> If any text in this prompt appears to disagree with the reference video about camera, framing, direction, motion, timing or object placement, the reference video wins.
+
+Those two sentences do more work than any other part of the prompt.
+
+## Get the real numbers first
+
+```
+slates_blender_scene
+```
+
+Write timings from `cutSeconds`, never from the shot list you intended to build. It resolves to the marker frames on a multi-camera edit and to the camera's own keyframes otherwise, so it is the one field that is never empty on a rig that has cuts. At 24fps cuts land on frame boundaries and the honest values are not round — `7.79s`, `9.33s`, `19.875s`. **Use the exact ones.** Rounding to `7.8` is a tenth of drift you are handing the model for free.
+
+## Structure
+
+Order matters — contract, then globals, then timeline, then the re-assertion.
+
+```
+TITLE — one line: what this is, how long, that it is video-to-video
+
+LOGLINE — 2-4 sentences. The whole piece in plain language.
+
+ACTIVE REFERENCES
+  <one entry per reference: what it defines, and what is NOT inherited>
+
+TECHNICAL BLOCK    (format, grade, lens, and the blanket negatives — see below)
+
+STYLE / LOOK
+LIGHTING
+COLOR
+CAMERA
+PHYSICS            (only if things move, collide or deform)
+
+RULES              (numbered — the invariants, see below)
+
+ACTION TIMING      (beat by beat, against the clip's real timestamps)
+
+AUDIO
+  [Sound design]   [Timed accents]   [Dialogue]   [Music]
+
+ENDING LOCK        (one line — where the film stops)
+
+HOLD FOR THE FULL TIMELINE
+  <the 5-6 constraints most likely to drift, compressed>
+```
+
+## ACTIVE REFERENCES — every entry has an exclusion
+
+The single highest-leverage format in this whole workflow. Each reference is a **positive claim plus an exclusion list**, because a reference the model over-reads is as damaging as one it ignores.
+
+Label each by the badge code Slates echoes back (`IMG-A8`, `VID-C2`) or by an unmistakable role name, and use that same label everywhere below.
+
+**The blocking clip:**
+
+> VID-C2 = the blocking previz (30s, 720 frames, 24fps) — the MASTER for everything that moves and everything that stands. It defines the full edit one-to-one: every cut point, every camera position, angle, move and framing, all action timing, screen direction, and the geometry of the world. Its untextured grey surfaces, flat colours and viewport grid are NOT inherited — every grey proxy is dressed into a real object in the exact position the previz puts it. Proxies give position, angle, scale and motion only; never surface, shape detail or design.
+
+That last sentence is the **placement-only clause** and it is not optional. Without it the model renders grey boxes.
+
+**A character sheet:**
+
+> IMG-A8 = the driver — defines his face, hair and wardrobe. Identity 100% consistent at every distance and through every motion blur. Background, lighting and pose are NOT inherited.
+
+**A location/style reference:**
+
+> IMG-B3 = the tunnel — defines location geometry, look and grade. Camera angle, framing and any people in it are NOT inherited; the camera comes exclusively from VID-C2.
+
+**An atmosphere or style master — a reference that is never a shot:**
+
+> IMG-D9 = ATMOSPHERE MASTER — NOT a keyframe, NOT a location to reproduce, NOT a frame that ever appears in the film: its own subject, framing and composition are never seen in any shot. It defines ONLY the weather, light, colour and grade: deep clean night just after rain, wet asphalt as a dark mirror, cool white-cyan lamps as the ambient key, teal-and-amber grade, deep clean blacks. Every shot is lit and graded in this regime for all 30 seconds.
+
+Without those three NOTs the model reproduces the reference's composition as an actual shot — you get its street corner in your film. The same wording covers a rendering-style master; see `slates-restyle-from-blocking`.
+
+**References can be scheduled.** If something is only true for part of the timeline, say so: *the hooded panel applies only to 0–7.0s and 27.5–30s*, or per-reference: *Active for 00:03.3–00:06.7 only.* On a piece that travels through several locations, every location still carries its own window and the model stops blending two sets into one shot.
+
+## Translate the blocking's artifacts
+
+Your grey-box render contains things that are *notation*, not content. Every one needs an explicit reinterpretation or it gets rendered literally:
+
+| In the blocking | Say in the prompt |
+|---|---|
+| Colour-coded bodies | `red = the boss, green = the kid, blue = the driver` |
+| A marked face on a proxy | `RED face = the direction he faces, BLACK = his back` |
+| A checkered floor or wall | `the checkerboard is a scale reference, not a surface — it becomes <the real material>` |
+| Flat black background | `a PLACEHOLDER — replace with the location assigned below` |
+| A floor grid | `a motion-tracking aid — render as light on the surface, never as wireframe or tiles` |
+| A deliberate black gap | `CUT 7 (14.5-17.0, black gap in the reference) — <what fills it>` |
+| Frame goes dark mid-move | `the camera is passing through the ground — a doorway to the NEXT location, never back to a previous one` |
+| The source hard-resets mid-move | `each reset begins a NEW, completely different room — never a replay of one already seen` |
+| A proxy that is a PROP or VEHICLE | `the low-poly flying model in SHOT 18 is THE HELICOPTER · blocks on the rear bench are the luggage · the small dark block in his hand IS the pistol` |
+| A blocky proxy limb in a tight insert | `the blocky low-poly leg is a stand-in and must NOT be replicated — generate complete human anatomy: a real boot, a real trouser leg, a correct ankle at this exact camera angle` |
+| A stray object at the frame edge | `ignore it completely — never blend two sets into one shot` |
+
+## TECHNICAL BLOCK — format, lens, and the blanket negatives
+
+One paragraph, before the timeline. It carries the things that are true of every frame and that no beat should have to repeat:
+
+> Cinematic, photoreal. 21:9. 30s. SFX only, no music. Kodak 500T film look, natural 35mm grain, organic colour, soft highlight roll-off, anamorphic lens character with oval bokeh and gentle barrel distortion at the edges, chromatic aberration creeping in at the frame edges, natural motion blur on every fast move, faint bloom on hot speculars. Every location well exposed — night interiors bright and readable, open shadows, no crushed blacks, no murk. NO CGI. NON-IP, no brand badges or logos anywhere, no text, no watermark.
+
+Three parts worth naming:
+
+- **Lens realism is a list, not an adjective.** Aberration, motion blur, depth of field, barrel distortion, bloom, grain. "Cinematic" buys you nothing; these buy you the look.
+- **Exposure needs saying on dark work.** Models crush night scenes into murk. *Night interiors bright and readable, open shadows, no crushed blacks* is what keeps a scene legible.
+- **The blanket negatives go here once** — `NON-IP`, no logos, no on-screen text, no subtitles, no watermark — rather than being scattered through the beats.
+
+## RULES — the invariants
+
+Numbered, short, absolute. These are the things that must hold in every frame, and they are where you put anything that has already gone wrong once.
+
+Two patterns worth stealing outright:
+
+**Countable state.** Give the model arithmetic it can check itself against:
+
+> At every second: standing + fallen + on the lintel = 6. Never a seventh figure — no extras, no duplicates, no distant silhouettes, no half-bodies at frame edges.
+
+> Bodies on the ground count exactly: 0 before 12s → 1 → 2 → 3 → 4 at 12/13/14/16s → 5 at 20s → 6 at 26s. Never more.
+
+**Every mass is dressed, and nothing is invented.** The blocking is authority over what EXISTS, not just what moves — otherwise the model deletes the masses it finds boring and adds architecture you never blocked:
+
+> Every lamppost, guardrail, road and terrain mass visible in the reference exists in the output in the same place, at the same scale, in the same position in frame — the opening blocks are dark-brick warehouse facades, the roadside masses are the waterfront skyline, the finale rocks are the city's tower walls. Nothing is deleted, and no structure is invented where the reference shows none.
+
+**Anatomy is never inherited from a proxy.** Tight inserts on hands and feet are where blocking leaks straight into the render:
+
+> The reference shows only WHERE hands and feet are. In the output they are always complete human anatomy — a five-fingered gloved hand with natural knuckles, a real leg in wool trousers, a real foot in a leather shoe — never the proxy's blocky shape.
+
+**A ledger for anything that happens a countable number of times.** A ritual, a reload, a set of falls: state it as a linear sequence, each step exactly once, and close with the tally:
+
+> Strictly linear, six steps in fixed order, each happening EXACTLY ONCE and never repeating; once a step is done it is done for good, and the sequence only ever moves FORWARD, never backward. Count of weapon events in the entire video: one draw, one magazine insertion, one slide rack, one shot.
+
+Without the ledger the model loops the most cinematic beat — it will rack the slide four times because racking looks good.
+
+**Named misreads.** When a generation gets something specifically wrong, do not rewrite the description — **name the wrong reading and kill it**:
+
+> The lamp is a man-made steel structure — NOT an animal, NOT a snake, NOT any living or organic shape.
+
+> The rear of the car and its tail lights are NOT visible in this shot.
+
+This is the highest-value edit available after a failed roll, and it is why the prompt grows rather than changes between takes.
+
+## ACTION TIMING — the beats
+
+One block per shot or beat. Two notations; pick one and hold it.
+
+**For a continuous take**, ranges with a camera note and a closing state audit:
+
+```
+8-12s — THE SWEEP (per VID-C2: elevated rear push, swinging to profile by 12s):
+<what happens, in prose, with sub-beats on tenths and → chaining cause to effect>
+END 12s: bodies 1 (behind him as he steps past) · standing — four ahead, holding.
+```
+
+**For a cut edit**, numbered shots ending on their cut:
+
+```
+9.33-10.33s — SHOT 10 — Interior over the centre console as in VID-C2: <what the
+frame contains>. Hard cut at 10.33s.
+```
+
+Three habits that separate a beat that works from one that does not:
+
+- **Declare the frame's contents as a closed set** when the shot is tight: *the frame holds exactly the console, the lever, his hand, and the edges of both seats.* An open description invites additions.
+- **Chain cause to effect inside one sentence** with `→`. `he overcommits a lunge → the Hero drops low and sweeps his standing leg → he hits the earth at 12s`.
+- **Put events on tenths.** `11.7s`, `19.5s`, `22.5s`. Vague beats generate vague timing.
+
+Density: roughly 60–130 words per second of screen time is what these prompts actually run at. That is much denser than a normal video prompt, and it is the point.
+
+## AUDIO
+
+`[Timed accents]` uses the same timestamps as the beats:
+
+> 3.1s tyres light up into the burnout squeal · 7.0s drift-entry screech · 10.1s hard mechanical shifter clack · 20.3s full-speed pass-by whoosh
+
+`[Dialogue]` is a closed list — count the lines, give each a window, quote it verbatim, and forbid everything else:
+
+> Exactly TWO vocal events in the entire 30 seconds, both screamed, in English, VERBATIM: 1. 17.3-18.6s "STOOOOOP!!" 2. 23.4-24.0s "You crazy!" Nothing else is ever spoken.
+
+**Then forbid the lines it will invent anyway.** A closed list is a rule; an enumerated blacklist is enforcement, and the phrases to list are the clichés the scene invites:
+
+> FORBIDDEN — she never says any of these and no one else says anything: "they're behind us", "cops", "go go go", "are you crazy", "you're insane", or ANY other invented phrase. All other human voice is wordless screaming or laughing.
+
+**When lines are lip-synced, give each one a timestamp** in the same list, and say that they change nothing else:
+
+> Timing: "You wind up for this one?" ~18.2s · "Three full turns." ~19.0s · "Company." ~24.3s. Every line lip-synced; the lines never change the camera.
+
+Two rules that stop dialogue from breaking the edit:
+
+> DIALOGUE NEVER CREATES SHOTS: spoken lines happen inside the reference's takes exactly as blocked — no cutaways to a speaker, no reverse shots, no added close-ups. If a line plays while the camera is elsewhere, the line stays off-screen audio.
+
+> A line marked off-screen must STAY off-screen — never show the speaker, never move him into frame, never route the camera to him because he spoke.
+
+Model note: dialogue direction as separate layers is minimax-h3's seat; native synced audio is Veo's. Route per `slates-model-selection` and read the model's own prompting skill before writing the audio block.
+
+## ENDING LOCK
+
+One line, and it is the cheapest fix in the document. Models drift at the end — they hold a frame too long, add a beat after the last one, or fade somewhere the reference does not:
+
+> The film ends exactly where the reference ends: the final take runs unbroken to its last frame, and that source frame IS the final frame of the film. Nothing follows. The last five seconds follow the source exactly as strictly as the first five.
+
+## HOLD FOR THE FULL TIMELINE
+
+Close with a terminal re-assertion of only the constraints most prone to drift — five or six lines, compressed, no new information:
+
+```
+HOLD FOR THE FULL TIMELINE
+- VID-C2 camera path 1:1 — any deviation = failure.
+- Six and only six figures; the count above holds at every second.
+- IMG-A8 identity constant at every distance and through motion blur.
+- The IMG-B3 location in every frame; no subtitles, no watermarks.
+```
+
+Restating is not redundancy here. It is the last thing the model reads.
+
+## Checklist before you generate
+
+- [ ] Timings taken from `slates_blender_scene`'s `cutSeconds`, frame-exact, not rounded
+- [ ] Every reference has an explicit "NOT inherited"
+- [ ] The placement-only clause is present
+- [ ] The tie-break clause is present
+- [ ] The disambiguation clause is present
+- [ ] Every blocking artifact is translated — colours, marked faces, checkers, grid, black background, gaps, dark dips, resets, prop proxies, proxy limbs, strays
+- [ ] Any style/weather reference is declared NOT a keyframe and never a shot
+- [ ] The every-mass-is-dressed / nothing-invented rule is present
+- [ ] Tight inserts on hands or feet demand complete anatomy
+- [ ] Counts are stated where anything is countable, and repeatable actions carry a ledger
+- [ ] A TECHNICAL BLOCK carries format, lens realism, exposure and the blanket negatives
+- [ ] `[Dialogue]` is a closed list with a FORBIDDEN blacklist
+- [ ] An ENDING LOCK says where the film stops
+- [ ] `videoReferenceSecondsEach` matches the clip's real duration
+- [ ] A HOLD block closes it
+
+## Related
+
+`slates-previs-blocking` (producing the clip) · `slates-camera-language` (the moves being described) · `slates-dialogue-blocking` (multi-character continuity) · `slates-restyle-from-blocking` (reusing this prompt across styles) · `slates-prompting-seedance-2-5` / `slates-prompting-minimax-h3` (model-specific rules)

package/skills/slates-camera-language.md

@@ -0,0 +1,196 @@
+---
+name: slates-camera-language
+description: Turn director vocabulary into real Blender camera rigs — orbits, floor rises, robo-arm whips, handheld, speed ramps, over-the-shoulder cuts — as bpy code. Use when building or refining the camera on a previs blocking pass, when a move needs to accelerate/hold/snap, or when someone asks for a "cinematic" camera and you need to convert that into an actual shot list.
+---
+
+# Camera language — from a shot list to a rig
+
+Companion to `slates-previs-blocking`. That skill owns the workflow; this one owns the camera.
+
+## The first rule
+
+🚨 **Never build "a cinematic camera move." Brief the camera the way you would brief an operator:** rails, target, height, lens, and the frame each move starts and ends on. "Cinematic" is not a specification, and asking for one produces the drifting slop the whole blocking workflow exists to avoid.
+
+Bad: *a dynamic cinematic orbit around the subject.*
+Good: *a 3/4 orbit starting rear-left at 1.6m, ending front-right at 0.9m, frames 1–96, 35mm, easing out of the start and holding hard on the last 8 frames.*
+
+If the user gives you the first, convert it to the second and say what you assumed.
+
+## Look it up, don't recall it
+
+Before any constraint or operator you are not certain of, call `slates_blender_docs` (e.g. `bpy.types.FollowPathConstraint`) or `slates_blender_search_docs`. Invented enum values are the most common failure here and they often fail *quietly* — the constraint gets added, the axis is wrong, and the camera points at nothing.
+
+## The two primitives everything is built from
+
+### Target-based aiming
+
+Almost every move in this skill is *position on a path* plus *aim at a target*. Separating them is what lets framing vary while the subject stays in frame.
+
+```python
+import bpy
+
+target = bpy.data.objects.new("CAM_TARGET", None)   # an Empty
+target.empty_display_type = 'PLAIN_AXES'
+bpy.context.collection.objects.link(target)
+
+con = cam.constraints.new('TRACK_TO')
+con.target = target
+con.track_axis = 'TRACK_NEGATIVE_Z'   # cameras look down -Z
+con.up_axis = 'UP_Y'
+```
+
+**Aim at a separate target, not at the subject's head.** A camera locked to the head produces dead, centred framing. Offset the target beside or ahead of the subject and the shot breathes — that small offset is most of what reads as "real operator."
+
+For a subject that should notice the camera, keyframe the target's follow with a **few frames of lag** behind each camera move. Heads catch up; they don't teleport.
+
+### Path-based movement
+
+```python
+curve = bpy.data.curves.new("CAM_PATH", 'CURVE')
+curve.dimensions = '3D'
+spline = curve.splines.new('BEZIER')
+spline.bezier_points.add(len(points) - 1)
+for bp, co in zip(spline.bezier_points, points):
+    bp.co = co
+    bp.handle_left_type = bp.handle_right_type = 'AUTO'
+
+path = bpy.data.objects.new("CAM_PATH", curve)
+bpy.context.collection.objects.link(path)
+
+con = cam.constraints.new('FOLLOW_PATH')
+con.target = path
+con.use_curve_follow = False   # aiming is the Track To constraint's job
+
+# Animate progress explicitly rather than relying on the default path animation.
+curve.path_duration = 96
+curve.eval_time = 0
+curve.keyframe_insert("eval_time", frame=1)
+curve.eval_time = 96
+curve.keyframe_insert("eval_time", frame=96)
+```
+
+**Why a path and not raw location keys:** the user can drag a control point to retime or reshape the move without you regenerating anything. That is the difference between "re-prompt and hope" and "nudge it."
+
+## Speed — the part that reads as production value
+
+Movement at one constant speed is the tell of a machine. Real moves accelerate, hold, and snap.
+
+Speed lives in the **f-curve handles** of `eval_time` (or of location, if you keyed it directly):
+
+- **Long, near-horizontal handle** at a key → slow near that key.
+- **Short, steep handle** → fast.
+- `interpolation = 'CONSTANT'` → no movement at all until the next key. This is how you get an absolute dead stop.
+
+```python
+fc = curve.animation_data.action.fcurves.find("eval_time")
+for kp in fc.keyframe_points:
+    kp.interpolation = 'BEZIER'
+    kp.handle_left_type = kp.handle_right_type = 'FREE'
+
+a, b, c = fc.keyframe_points          # start, middle, end
+# Speed ramp: fast in, sag in the middle, accelerate out.
+a.handle_right = (a.co.x + 2,  a.co.y + 18)    # steep = launches fast
+b.handle_left  = (b.co.x - 14, b.co.y)         # flat  = holds
+b.handle_right = (b.co.x + 14, b.co.y)
+c.handle_left  = (c.co.x - 2,  c.co.y - 18)    # steep = arrives fast
+```
+
+**Zero drift at a stop.** If a move is supposed to be locked off, it must be *actually* locked — a slow crawl at a "stop" reads as a mistake. Hold with `CONSTANT` interpolation, or duplicate the key so the segment is genuinely flat.
+
+## The moves
+
+### Orbit
+
+Circle the subject on a path, target at subject height. Vary radius and height across the move so it does not read as a turntable. Half-orbits and 3/4 orbits look more intentional than full ones.
+
+For a multi-scene continuous orbit, keep one unbroken `eval_time` curve and move the *world* under it — the camera never cuts, the set changes.
+
+### Floor rise
+
+Pure vertical translation, **no rotation**, smooth acceleration with a slow middle. Each "floor" is a different set stacked on Z at a fixed interval; the subject sits centre-frame at each pass.
+
+```python
+FLOOR_H = 4.0
+for i in range(4):
+    cam.location = (0, -6, i * FLOOR_H)
+    cam.keyframe_insert("location", frame=1 + i * 48)
+```
+
+Rotation during a rise destroys the effect. Leave it out.
+
+### Robo-arm
+
+The whip-and-lock commercial move: a fast flight along a curved arc, an **absolute** dead stop at a completely different angle, repeat. Each relocation is roughly a third of a second; each stop is a distinct, readable frame.
+
+Build it as a path with a control point per stop, then make the stops real:
+
+```python
+HOLD_FRAMES = 10
+for kp in fc.keyframe_points:
+    kp.interpolation = 'CONSTANT'      # hold dead still between flights
+```
+
+Keep the target separate and slightly offset per stop, so each lock-off is a different composition of the same subject rather than six centred portraits.
+
+### Handheld
+
+Applied **last**, on top of a finished move. Slow organic sway, not jitter: long waves plus a barely-perceptible tremor.
+
+```python
+for path in ("location", "rotation_euler"):
+    for i in range(3):
+        fc = cam.animation_data.action.fcurves.find(path, index=i)
+        if fc is None:
+            continue
+        n = fc.modifiers.new('NOISE')
+        n.scale = 120        # large scale = long lazy waves (4-6s at 24fps)
+        n.strength = 0.035   # small; raise for rotation, lower for location
+        n.phase = i * 7.3    # decorrelate the axes or it reads as a slide
+```
+
+**Never fast jitter, wobble or snap corrections.** Wrong-flavour handheld is more damaging than none.
+
+### Over-the-shoulder cuts
+
+Per cut: a camera position below shoulder height, a near-foreground body mass, and a target on the far face. Move barely — a slow sideways crawl. See `slates-dialogue-blocking` for who may occupy the foreground and why it matters.
+
+### Lens
+
+Animate focal length like any other channel; a slow lens breath under a move adds a lot for nothing.
+
+```python
+cam.data.lens = 35
+cam.data.keyframe_insert("lens", frame=1)
+cam.data.lens = 50
+cam.data.keyframe_insert("lens", frame=96)
+```
+
+**But the lens must not drift across a cut.** Within a cut it can animate; on the cut frame it changes instantly with everything else.
+
+## Multiple cameras and cuts
+
+Two ways, and only one of them survives contact with a 19-shot edit:
+
+- **One camera, jump-cut it.** Keyframe location/rotation/lens with `CONSTANT` interpolation on the cut frames. Fine up to a handful of cuts.
+- **A camera per setup, bound to timeline markers.** Correct for anything bigger, because each setup stays independently editable.
+
+```python
+marker = bpy.context.scene.timeline_markers.new("SHOT_04", frame=188)
+marker.camera = cam_shot_04
+```
+
+Either way the invariant is the same: **camera, target and lens all change on the cut frame, and no frame between two setups is interpolated.** One transition frame reads as a whip-pan, and the model will reproduce it faithfully.
+
+## Verify before you render
+
+```
+slates_blender_scene
+```
+
+`cutSeconds` is your actual cut list in seconds. Check it against the shot list you were given — mismatches here become mismatched prompt timings, and the prompt is what you write next.
+
+⚠️ **On a marker-bound rig, read `cutSeconds` or `markers`, never `camera.keyframeSeconds`.** The per-setup cameras are usually static (a Track To constraint does the aiming), so the active camera's action is empty and that field reads `[]` on a perfectly good three-cut edit. `cutSeconds` resolves to whichever the scene actually used.
+
+## Related
+
+`slates-previs-blocking` (the workflow) · `slates-blocking-to-prompt` (turning these moves into prompt text) · `slates-dialogue-blocking` (OTS and eyelines)

package/skills/slates-dialogue-blocking.md

@@ -0,0 +1,134 @@
+---
+name: slates-dialogue-blocking
+description: Keep multiple characters spatially consistent across cuts — seating, screen direction, eyelines, the 180-degree rule — by blocking the scene in 3D first. Use for any multi-character dialogue scene, conversations around a table or in a car, or when generated characters swap seats, change sides, or look the wrong way between shots.
+---
+
+# Dialogue blocking — six people who stay where you put them
+
+The hardest thing to generate, and the case where previs beats raw prompting by the widest margin.
+
+## Why this is hard
+
+Every cut is an independent guess unless something forces agreement. Prompt a six-person conversation four times and you get four different seating charts: characters swap places, the 180-degree line breaks, and nothing cuts together. The failure is not aesthetic — the shots are simply unusable as an edit, and you find out only after paying for all four.
+
+**The blocking fixes it structurally.** Positions exist in 3D, so every camera sees the same arrangement, and consistency stops being something the model has to remember.
+
+## Build
+
+Follow `slates-previs-blocking` and add these.
+
+### Seated proxies, colour-coded
+
+Simple seated shapes. **Do not animate the heads** — a proxy head turning the wrong way is worse than one that never turns.
+
+Give each character a distinct viewport colour and write the mapping down. This is the identity channel:
+
+> red = the boss · green = the kid · blue = the driver · yellow = the fixer · purple = the cousin · cyan = the nephew
+
+That mapping goes verbatim into the generation prompt. It is what lets the model bind a grey body to a character sheet across four cuts.
+
+Give every proxy a material and set `mat.diffuse_color` to its identity colour — the blocking render pins Workbench to `MATERIAL` shading, so **the material's `diffuse_color` is what reaches the clip**. Set `object.color` to the same value too, so the user's viewport matches what renders. See `slates-previs-blocking` for the snippet.
+
+### Fix the geography, then never move it
+
+Place people once. Write down who sits where relative to the camera's opening position, in words, because that sentence is going into the prompt:
+
+> Across the table, facing camera: yellow dead centre, purple far left, blue and green to the right.
+
+### The camera plan
+
+Per `slates-camera-language`, with two things specific to dialogue:
+
+- **Below shoulder height, slow rail glides.** Eye-level-and-above reads as surveillance.
+- **Decide who owns the near foreground in each cut and honour it.** A shoulder in frame is a spatial anchor; a different shoulder in the next cut relocates the whole room.
+
+The move that earns the most: **a gaze handoff without a cut** — the camera keeps gliding while the target hands off across the table, face to face, slowing on each but never stopping. Build it by keyframing the Track To target's position between subjects.
+
+### Crossing behind someone
+
+A head wiping frame during a move is a strong depth cue. It is also a spatial claim, so pick who gets crossed and say so — *the camera crosses directly behind cyan's back mid-shot and his head wipes the frame once.*
+
+## The prompt
+
+Everything in `slates-blocking-to-prompt`, plus these blocks.
+
+### Geography — restate it as a rule
+
+> TABLE GEOGRAPHY — do not deviate: the camera is never parked behind red. Only in the opening seconds does his dark shoulder hang at the near frame RIGHT edge, and it slides out as the camera travels LEFT. The true near-foreground of this shot is cyan: the camera crosses directly behind him mid-shot. After the opening seconds red is gone from the foreground, and the camera never travels behind anyone except cyan.
+
+### Screen direction, and the mirror that is not a swap
+
+The 180-degree rule survives on its own in the blocking. What breaks is the model **"correcting" a legitimate mirror** — when the camera faces back through a scene, sides invert, and that inversion is correct. Say so explicitly or it gets flipped:
+
+> The driver's seat is on the LEFT for the entire timeline; this layout never mirrors or flips. When a camera faces BACKWARD into the car, screen sides mirror naturally: the driver reads on the RIGHT of frame, the passenger on the LEFT — that is correct left-hand drive, not a swap. They never swap seats or roles anywhere in the timeline.
+
+Then compress it into the HOLD block: *(backward camera mirrors them: he right of frame, she left)*.
+
+### Presence
+
+> A seated person stays drawn even when partially occluded — in every interior frame some part of each seat's owner is visible: a hand, an arm, a shoulder, a head above the bolster. Every occupied seat visibly holds its person.
+
+### Keep everyone alive
+
+Three orthogonal layers. Without them, whoever is not speaking freezes:
+
+- **ONGOING BUSINESS** — a small continuous physical action per character, running whether or not they are speaking. *turns his glass a quarter every few seconds · thumbs a lighter without lighting it.*
+- **BACKGROUND LIFE** — soft-focus, low contrast, never pulls attention, never crosses in front of a speaking face.
+- **SCENE EVENT** — the unnamed thing everyone is playing but nobody says. One line, repeated verbatim in every character's direction: *keep tomorrow sounding like a fishing trip.*
+
+### Acting, per character
+
+Same six slots each. Terse:
+
+```
+ACTING TASK — <character>
+  SCENE DIRECTION (shared, unspoken): <the same line for everyone>
+  MOTIVE (his fuel): <what he wants underneath>
+  GOAL: <what he wants in this scene>
+  OBSTACLE: <what is in the way>
+  TACTIC: <how he goes about it>
+  Moment to moment: <2-3 beats keyed to timestamps>
+  (Safety: gaze always engaged in the task — never a frozen, glassy,
+   unfocused stare; natural blink cadence.)
+```
+
+That safety line is not filler. Dead eyes are the characteristic failure of generated faces in dialogue, and naming it is what prevents it.
+
+### Split any strong emotion into phases
+
+The other characteristic failure is a face that strikes one extreme expression and holds it for the whole shot — a mouth stuck open for three seconds. Give the beat two phases with a hinge, and name the failure you are excluding:
+
+> PHASE 1 (17.3-18.6s) — she SCREAMS at him, mouth wide, eyes huge, hand clamped on the grab handle. PHASE 2 (18.6-19.9s) — the scream breaks off: she shuts her eyes tight and CLOSES her mouth, both hands now on the handle, head ducked, braced. Scream, then brace — never one frozen open mouth held through the whole shot.
+
+The hinge timestamp is what makes it a performance instead of a pose.
+
+### Dialogue must not restructure the edit
+
+Both of these, verbatim, every time:
+
+> DIALOGUE NEVER CREATES SHOTS: spoken lines happen inside the reference's takes exactly as blocked — no cutaways to a speaker, no reverse shots, no added close-ups. If a line plays while the camera is elsewhere, the line stays off-screen audio.
+
+> OFF-SCREEN VOICES RULE: a line marked off-screen must STAY off-screen — never show the speaker, never move him into frame, never route the camera behind him because he spoke.
+
+A sentence may cross a cut. Say so where it does: *the sentence does not pause for the edit.*
+
+## Model routing
+
+Dialogue directed as separate layers (voices, scene sound, score) is **minimax-h3**'s seat; it also takes declared reference relationships, which suits a colour-coded cast. Native synced audio is **Veo**'s niche. seedance-2.5 carries the reference-video capacity. Route per `slates-model-selection` and read the chosen model's prompting skill before writing the audio block.
+
+## Checklist
+
+- [ ] Colour→character mapping written down and pasted into the prompt
+- [ ] Heads not animated in the blocking
+- [ ] Seating stated as a geography rule
+- [ ] Foreground owner named per cut
+- [ ] Mirror-is-not-a-swap clause present if any camera faces back through the scene
+- [ ] Presence rule present
+- [ ] Ongoing business, background life and scene event all specified
+- [ ] Acting task per character, safety line included
+- [ ] Any strong emotion split into phases with a hinge timestamp
+- [ ] Dialogue-never-creates-shots and off-screen-voices rules present
+
+## Related
+
+`slates-previs-blocking` · `slates-camera-language` · `slates-blocking-to-prompt` · `slates-character-identity` (the sheets) · `slates-prompting-minimax-h3`

package/skills/slates-model-selection.md

@@ -31,7 +31,7 @@ The tables below are a snapshot. This roster churns constantly (NB2 Lite, Omni F
 | **One take longer than 15 seconds**, or a shot needing more than 9 image references, or an AUDIO-ONLY reference, or **beats that have to land at a named second** | **Seedance 2.5** | A SECOND SEAT beside 2.0, never an upgrade: 4–30s in one take, 30 image + 10 video + 10 audio references, audio-only refs, and the only Seedance seat that **acts on timestamps** (rules in `slates-prompting-seedance-2-5` § Timestamps) — 480p / 720p / 1080p, **no 4K**, and **dearer than 2.0 at every shared resolution** (720p $0.231/s vs $0.15/s, +54%). If you want 4K, or the same resolution cheaper, stay on 2.0. 🚨 Two live hazards: (a) with references attached, the words *add / remove / replace / change / extend / continue* make it reclassify the request as a video EDIT and fail AFTER the job queues — describe the finished frame, or use `seedance-2.5-edit`; (b) LENGTH is the price dial, not resolution — a 30s 720p face gen is 489 credits and a 30s 1080p faceless gen is 614, against a 1,000-credit welcome grant. Quote before any take over ~10s. |
 | **The SOUND has to be directed, not just present** — a specific line delivered a specific way, scene sound that has to sit under it, and score that must stay out of the characters' world | **MiniMax H3** | The only seat where audio is authored in three separate layers in ONE pass (synchronised events in the body, ambience in a soundscape section, audience-only score in its own) rather than toggled on. 5–15s, 480p / 768p / 2K / 4K, 24fps, 32kHz stereo, 11 languages. Rules in `slates-prompting-minimax-h3`. |
 | **A reference has to keep a DECLARED amount of itself** — especially moving one subject's characteristic onto a *different* subject | **MiniMax H3** | The only seat that understands a stated retention relationship (kept whole / kept in part / transferred onto another subject / loose echo). 9 images + 3 video + 3 audio, 12 files total. 🚨 The first 5 reference images are free and every one after that costs 4 credits — pass `referenceImages` to `slates_estimate_generation_cost` before a reference-heavy job. |
-| **Turnaround is the requirement** on a text-to-video or start-frame shot at 480p/768p | **MiniMax H3 Max** | fal's self-hosted post-train of H3. **Measured 2026-08-27: a 5s 768p clip finished in 4.8s against 57s on base H3 — about 12x faster**, same prompt, queue to file. When turnaround is the requirement this is not a marginal win. 🚨 It is the PREMIUM seat, not a cheap H3 — $0.080/s at 768p against base H3's $0.060/s, 33% more, and it tops out at 768p with NO references of any kind. Never the default; never reach for it to save money. |
+| **Turnaround is the requirement** on a text-to-video or start-frame shot at 480p/768p | **MiniMax H3 Max** | fal's self-hosted post-train of H3. **Measured 2026-08-27: a 5s 768p clip finished in 4.8s against 57s on base H3 — about 12x faster**, same prompt, queue to file. When turnaround is the requirement this is not a marginal win. 🚨 It is the PREMIUM seat, not a cheap H3 — $0.080/s at 768p against base H3's $0.060/s, 33% more, and it tops out at 768p. It still animates a start frame and an end frame — image-to-video is one of the two things it is for — but it has no reference-to-video endpoint, so the omni-reference set (9 images + video + audio) is base-H3 only. Never the default; never reach for it to save money. |
 | Native synchronized audio (dialogue + SFX generated WITH the video in one gen), 16:9, ≤8s | Veo 3.1 | Narrow, and now narrower: if the sound needs DIRECTING rather than merely existing, MiniMax H3 is the better seat. |
 
 ### Named Seedance escalation triggers