@slatesvideo/shared 0.6.1 → 0.6.3

package/exports/slates-prompt-builder/generated/SKILL.md

@@ -16,9 +16,9 @@ This portable skill is deliberately thin. Its reference files are generated dire
 <!-- @generated:model-routing -->
 | Model | Canonical route | Guide |
 |---|---|---|
-| **Kling 3.0** | DEFAULT general-purpose video model — cost-effective, strong start-frame adherence (identity/layout/text), acting, dialogue, lip-sync, any aspect ratio. Escalate to Seedance for physics. Kling is also the ONLY engine behind the Motion Transfer and Lip Sync tools (MC std/pro, lip-sync, avatar) — those two tools are Kling-only. | `reference-kling.md` |
-| **Seedance 2.0** | PREMIUM video tier and the DEFAULT video model — route here the moment physics, effects, destruction, or scale matter, and for hero shots. VIDEO-ONLY: cannot generate standalone images (use NB2/FLUX.2/Seedream for those). 4-15s, up to 9 ingredient images. Strong I2V / own-footage restyle. Native 4K, but 4K VIDEO is a Pro-only tier gate (base maxes at 1080p; server returns PRO_REQUIRED) — default 1080p unless the user is on Pro. Attaching a clip as a video reference (own-footage restyle, motion or dialogue conditioning) bills combined input+output seconds — at a DISCOUNTED per-second rate on every provider, roughly 0.6x the plain rate. 2.0 STAYS THE DEFAULT over 2.5 for two reasons, and neither is 1080p any more (2.5 gained 1080p on 2026-08-24): it is the only Seedance with native 4K, and it is cheaper at every shared tier (720p $0.15/s vs $0.231/s). | `reference-seedance.md` |
-| **Nano Banana 2 (Gemini 3.1 Flash Image)** | Default image model. 14 refs hard cap (10 object + 4 character). Brief it like a creative director, not tag soup. No negativePrompt field — use positive reframing. Best image start-frame for legible text. Knowledge cutoff Jan 2025. | `reference-nano-banana.md` |
+| **Kling 3.0** | DEFAULT general-purpose video model — cost-effective, strong start-frame adherence (identity, layout, text), acting, dialogue, lip-sync, and the widest aspect-ratio set. Escalate to Seedance for physics. Kling is also the ONLY engine behind the Motion Transfer and Lip Sync tools. | `reference-kling.md` |
+| **Seedance 2.0** | PREMIUM video tier and the DEFAULT video model — route here the moment physics, effects, destruction or scale matter, and for hero shots. VIDEO-ONLY. Strong image-to-video and own-footage restyle. 4K is Pro-gated (base accounts get PRO_REQUIRED). Stays the default over 2.5: it is the only Seedance with native 4K and it is cheaper at every tier the two share. | `reference-seedance.md` |
+| **Nano Banana 2 (Gemini 3.1 Flash Image)** | DEFAULT image model and the all-rounder — route here unless another seat's speciality is the point. Best start-frame for legible in-scene text. Knowledge cutoff Jan 2025: anything later needs reference images. | `reference-nano-banana.md` |
 <!-- @end:model-routing -->
 
 If the user names a model, use it. Otherwise route by the generated table above.

package/exports/slates-prompt-builder/generated/reference-seedance.md

@@ -304,7 +304,8 @@ Speed ramps and slow-motion are supported in natural language, and `fast` is wid
 the lid opens in slow-motion · the blade whips through the air
 ```
 
-**Slop tokens to avoid:** `epic`, `amazing`, `beautiful`, `lots of movement`, `8K`, `masterpiece`, `trending on artstation`. These are quality *incantations* — the officially sanctioned way to ask for quality is the image-quality slot vocabulary in Part 1 (`HD`, `rich details`, `cinematic texture`, `natural colors`, `soft lighting`).
+**Slop tokens to avoid:** `epic`, `amazing`, `beautiful`, `lots of movement`, `8K`, `masterpiece`, `trending on artstation`.
+These are quality *incantations* — the officially sanctioned way to ask for quality is the image-quality slot vocabulary in Part 1 (`HD`, `rich details`, `cinematic texture`, `natural colors`, `soft lighting`).
 
 ## Style block at the end
 

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

@@ -12,7 +12,7 @@
     },
     {
       "path": "skills/slates-prompting-seedance.md",
-      "sha256": "ad9f3d5a20ef3bf52ebe916c81f67b9570fe1a43b54d64819da8b73972eb1a8e"
+      "sha256": "c82ecbd6e169f74146e2553479bdc3115d550a332ee6ebb23a1068d6fe977d02"
     },
     {
       "path": "skills/slates-prompting-kling-v3.md",
@@ -20,7 +20,7 @@
     },
     {
       "path": "skills/slates-prompting-nano-banana-2.md",
-      "sha256": "fd47d89ffa5ac16c2d06e2d3c0e891813996dc15636a8988f7da6e8ee1816565"
+      "sha256": "302c316ab7ce562a56db28ed480c4ed6bbffea1dd44ec468d122873b98491661"
     },
     {
       "path": "skills/slates-content-policy.md",
@@ -28,14 +28,14 @@
     },
     {
       "path": "src/prompts/model-facts.ts",
-      "sha256": "89a899444c021975df0a03a87b446217cdfc3b9086ef501e9e847936d7cfec2d"
+      "sha256": "1d6a8144643ab4ecd91fce7b16160b2152602c7de7079eab93eac700db433afc"
     }
   ],
   "outputs": [
     {
       "path": "SKILL.md",
-      "bytes": 5174,
-      "sha256": "6fecadc73933aa9e5001b3561aec31b3ca9edcc5146d79302720f1225bad1215"
+      "bytes": 4598,
+      "sha256": "47cd166742efe1b15fb25603922695c5397ab9d24a839fb524d69cde426a6f89"
     },
     {
       "path": "reference-character.md",
@@ -45,7 +45,7 @@
     {
       "path": "reference-seedance.md",
       "bytes": 32558,
-      "sha256": "29b9408feec4ba91e5cd6f048ff6e6771fd2d96120378d4b6d52dec2a35eacd3"
+      "sha256": "c206db40577838baaaf7bc27ce0adfb1e0feb275ed9a8aea5fed377a74f0dacf"
     },
     {
       "path": "reference-kling.md",
@@ -65,8 +65,8 @@
   ],
   "archive": {
     "path": "slates-prompt-builder.skill",
-    "bytes": 38420,
-    "sha256": "869398265aaf8f8fba2987d1a0da24be8932f7d79bf7b67d9e866bd7ca6f134f",
+    "bytes": 38089,
+    "sha256": "4abe20453ab78bf4193db69d14a21f0a328238fec0b7e7dcb75bcffec160daee",
     "entries": [
       "SKILL.md",
       "reference-character.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slatesvideo/shared",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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)