@slatesvideo/shared 0.6.3 → 0.6.5

package/exports/slates-prompt-builder/generated/reference-content-policy.md

@@ -4,6 +4,12 @@
 
 # Content-policy-safe construction — read before any risk-surface prompt
 
+**Never use** — each one is a filter tripwire with a substitution in the table above:
+- `civilians in panic`, `crowds fleeing`, `blood`, `gore`, `corpse`
+- `ignite`, `catch fire`, `on fire` applied to a person — frame body-contact effects as magical or harmless VFX
+- `candle-like`, `flame-like` and any real object used as a metaphor for an effect
+- a real, named public figure
+
 Don't depict the harm — depict the energy, the aftermath, the threat, or the scale. Build the scene safe from the first word.
 
 Write scenes that hit full cinematic impact without ever *needing* to depict prohibited content. This is a craft move, not a compromise — the substitutions below usually read as more cinematic, not less, and they keep your generation from getting silently rejected or degraded by the model's filter. A standoff is more tense than a massacre; an evacuated city is eerier than a crowd in panic; a roar lands harder than a kill. Load this whenever a prompt involves conflict, creatures, crowds, destruction, weapons, or young characters.

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

@@ -4,6 +4,28 @@
 
 # Kling V3.0 — prompting
 
+<!-- @card:start -->
+**Card — Kling V3.0.** The general default. Define the core subjects clearly at the START and keep those descriptions identical across shots. Up to 15s, up to 6 cuts, and the strongest image-to-video identity hold in the catalogue.
+
+**The five levers**
+1. **Dialogue in quotes** — `Character says, "exact words here"`. On Omni, direct the voice with `Gender + Age + Voice quality + Speech rate + Emotional tone + Language`: `[Character A: Detective, mid-40s, raspy, slow cadence, weary]: "I've seen this before."`
+2. **Unique speaker labels, no pronouns after the introduction.** `he`, `the agent`, any synonym causes voice drift.
+3. **Sound has real syntax** — `SFX: heavy boots on wet pavement, distant siren wailing`, `Ambient noise: city traffic`, `Background music: low cello`. Always physical-cause specific; `SFX: footsteps` is not enough.
+4. **Motion adverbs modulate energy directly** — `slowly`, `rapidly`, `gently`, `explosively`. One primary camera move per shot, never stacked.
+5. **On image-to-video, do NOT re-describe the image.** It is an anchor; prompt how the scene EVOLVES from it — movement, camera, environmental change.
+
+**Examples**
+- `A detective in a wet grey overcoat stands under a stairwell light. He steps forward slowly as the light flickers. [Character A: Detective, mid-40s, raspy voice, slow cadence, weary]: "I've seen this before." SFX: heavy boots on wet concrete, distant siren wailing. Ambient noise: rain on metal.`
+- `Camera tracks right alongside a cyclist crossing a bridge at dusk. She rises out of the saddle rapidly as the grade steepens. Ambient noise: wind, tyres on wet asphalt, distant traffic.`
+
+**Hard constraint:** `Immediately` (Omni only) removes the natural conversational beat between speakers — use it when timing matters and leave it out when it does not. Kling has a real `negativePrompt` field, unlike Seedance; start from the standard block and layer scene-specific suppressions.
+<!-- @card:end -->
+
+**Never use:**
+- `SFX: footsteps` and any label-only effect — physical-cause specificity or nothing
+- a pronoun or synonym for a speaker after the first introduction (`he`, `the agent`) — it causes voice drift; repeat the full label
+- `single continuous take` — Seedance's phrase, and it fights Kling's multi-shot
+
 Kuaishou's video model. Three tiers: `kling-v3.0-std` (general use, no audio), `kling-v3.0-pro` (higher visual quality, no audio), `kling-v3.0-omni` (multi-character dialogue + audio-visual co-generation).
 
 Up to 15s. Multi-shot supported (up to 6 cuts in 15s total). Strong on image-to-video — preserves identity, layout, and text from the input image well.

package/exports/slates-prompt-builder/generated/reference-nano-banana.md

@@ -4,6 +4,23 @@
 
 # Nano Banana 2 — cinematic & photorealistic prompting
 
+<!-- @card:start -->
+**Card — Nano Banana 2 (Gemini 3.1 Flash Image).** Brief it like a creative director, not a tag list. Structure: `Film still from [director] [genre]. Shot on [camera] with [lens]. [Subject and action]. [3-5 specific visual details]. [Lighting — direction + quality]. [Color palette]. [Film stock]. [1-2 word tone].`
+
+**The five levers**
+1. **Named lens + aperture** beats "shallow depth of field" — `85mm f/1.4`, `135mm f/2.8` (the cheat code for skin), `Panavision anamorphic`, `400mm telephoto`.
+2. **Light by direction and quality**, never "good lighting" — `hard sidelight from a single window, deep falloff`, `overcast north light`, `practical tungsten spill`.
+3. **A named film stock or sensor** carries a whole palette — `Kodak Portra 400`, `Cinestill 800T`, `ARRI Alexa 65`.
+4. **Composition as a shot** — `low angle`, `aerial view`, `rule of thirds with the subject camera-left`, `foreground occlusion`.
+5. **Positive framing only.** Describe what is there. "Empty street", never "no cars"; "unstaged documentary photography", never "not anime".
+
+**Examples**
+- `Film still from a Denis Villeneuve thriller. Shot on ARRI Alexa 65, 85mm f/1.4. A woman in a charcoal wool coat stands at a rain-slick bus stop, breath visible. Hard sodium light from a single overhead lamp, deep falloff into blue night. Kodak Vision3 500T. Isolated.`
+- `Editorial still life on seamless bone paper. 100mm macro, f/8. A cracked ceramic bowl holding three figs. Soft north light from camera-left, one gentle shadow. Muted earth palette. Portra 400 grain. Quiet.`
+
+**Hard constraint:** there is no `negativePrompt` field. Suppress by reframing positively, or inline `without` / `free of`. Knowledge cutoff January 2025 — anything later needs reference images.
+<!-- @card:end -->
+
 Nano Banana 2 is **Gemini 3.1 Flash Image**. It is **not** Gemini 3 Pro Image; that is Nano Banana **Pro** (`nano-banana-pro`), a separate model with its own seat. NB2 is a language model that outputs pixels — brief it like a creative director, not like a Stable-Diffusion tag-soup tool. The single biggest lever for realism: **specificity that mimics how real photographers and cinematographers describe their work**.
 
 Knowledge cutoff: January 2025. Anything after needs explicit reference images.

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

@@ -4,6 +4,23 @@
 
 # Seedance 2.0 — prompting
 
+<!-- @card:start -->
+**Card — Seedance 2.0.** Not copywriting — an ENGINEERING instruction to a spatial layer and a temporal layer: who, in what scene, doing what, how the camera moves, and in what order. Multi-beat work is a `Shot 1 / Shot 2 / Shot 3` storyboard.
+
+**The five levers**
+1. **Bind every subject to its reference** — `<Subject_1>@<Image_1>` — and keep the descriptions identical across shots. Unbound subjects are where twins come from.
+2. **Shot sizes and camera MOVES, not lens data** — `medium close-up`, `slow push in`, `handheld follow`, `whip pan`. One primary move per shot.
+3. **Externalise emotion as physical action.** Not "she is nervous": `she turns the ring on her finger twice, then stops`.
+4. **Use the image-quality slot vocabulary** for quality — `HD`, `rich details`, `cinematic texture`, `natural colors`, `soft lighting`. That is the officially sanctioned way to ask.
+5. **Constraints go INLINE**, led by the official templates — `keep it subtitle-free`, `do not generate a watermark`, `avoid jitter and bent limbs`, `avoid temporal flicker`.
+
+**Examples**
+- `Shot 1: medium shot, <Subject_1>@<Image_1> steps out of the freight lift into a wet loading bay, slow push in. Shot 2: close-up, she turns the ring on her finger twice and stops, handheld. Rich details, cinematic texture, natural colors. Keep it subtitle-free.`
+- `Single continuous take. Wide shot of a fishing skiff crossing a grey swell, camera tracks from the starboard rail. Spray hits the lens once. Soft lighting, natural colors, film-grain texture. Avoid jitter and bent limbs.`
+
+**Hard constraint:** NO timestamps — 2.0 ignores them and answers only to shot numbers (2.5 acts on them). No lens, aperture, film stock or camera body: that is image-model vocabulary and a Seedance anti-pattern. There is no negativePrompt field.
+<!-- @card:end -->
+
 ByteDance's video model — first-party via **BytePlus ModelArk** (credits only, no BYOK). Audio always generated alongside the video. Single model `seedance-2` across the full resolution ladder (480p / 720p / 1080p / native 4K — 4K video is Pro-only, default 1080p), 4–15s, first+last frame, and up to 9 reference images / 3 videos / 3 audio clips.
 
 > **How to read this file.**

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

@@ -12,23 +12,23 @@
     },
     {
       "path": "skills/slates-prompting-seedance.md",
-      "sha256": "c82ecbd6e169f74146e2553479bdc3115d550a332ee6ebb23a1068d6fe977d02"
+      "sha256": "46d1657b967e2b518bf350e4ad937b45ee0f8253c18d017f3df06ff8ec642244"
     },
     {
       "path": "skills/slates-prompting-kling-v3.md",
-      "sha256": "629b9490103a1a7961b584b7e125faa45375265dd941d8aae466cf6b195d5884"
+      "sha256": "81edd7b060648c97d914017101345b0f0e122660a2050389c80f58f24b48aa9c"
     },
     {
       "path": "skills/slates-prompting-nano-banana-2.md",
-      "sha256": "302c316ab7ce562a56db28ed480c4ed6bbffea1dd44ec468d122873b98491661"
+      "sha256": "824499adf1188cd86a84fff1de6a02311f87ffb4d1dda73ef46e813c7ef89000"
     },
     {
       "path": "skills/slates-content-policy.md",
-      "sha256": "ee5afd3e0d276d75c08b1747f551878be28d22151a369c969c55e58fda3f5710"
+      "sha256": "68566e6431864f075f6397013f040fb41e0559b19b11a15e860a4da80068a9a6"
     },
     {
       "path": "src/prompts/model-facts.ts",
-      "sha256": "1d6a8144643ab4ecd91fce7b16160b2152602c7de7079eab93eac700db433afc"
+      "sha256": "b098e77bc1c8574f826be80ca701aa024920f31a7b51a3c15c7f03d59e573fc5"
     }
   ],
   "outputs": [
@@ -44,29 +44,29 @@
     },
     {
       "path": "reference-seedance.md",
-      "bytes": 32558,
-      "sha256": "c206db40577838baaaf7bc27ce0adfb1e0feb275ed9a8aea5fed377a74f0dacf"
+      "bytes": 34423,
+      "sha256": "50c3f1fc54fa1229f3dcadb9e0af1a070e0fbfa4f42bfc024460762bb56d2a1b"
     },
     {
       "path": "reference-kling.md",
-      "bytes": 13592,
-      "sha256": "3689d7a285cc8845bc41c5ffbed7b727a43cd3c108a2a46b8028c3528ef44ed5"
+      "bytes": 15908,
+      "sha256": "99430d96af4461404bb55a6e56e1c3581a2cae817f0e337d0046cbee41dbb0bf"
     },
     {
       "path": "reference-nano-banana.md",
-      "bytes": 16437,
-      "sha256": "69fe636c780d6ddf9fe97e23b7d82d8961cac0037b985e3500a9485f295e211d"
+      "bytes": 18239,
+      "sha256": "7efcaed812a39ddb5a88ba6f7029f975640b5ccc166002d620324d214944125b"
     },
     {
       "path": "reference-content-policy.md",
-      "bytes": 6785,
-      "sha256": "4c0fe7cd7d3d6b854af6702133fd81a3338a5cb01f48e4a626165c4eb9667b06"
+      "bytes": 7169,
+      "sha256": "26439b2948313ee9eed10cbbe9e3ede60d53a453c41af96c3928840b0a4f6212"
     }
   ],
   "archive": {
     "path": "slates-prompt-builder.skill",
-    "bytes": 38089,
-    "sha256": "4abe20453ab78bf4193db69d14a21f0a328238fec0b7e7dcb75bcffec160daee",
+    "bytes": 40145,
+    "sha256": "69ddf61a8e056df58b27f9a0332d4f0a50506f0296d21ce00302a2bb0adfa209",
     "entries": [
       "SKILL.md",
       "reference-character.md",

package/package.json

@@ -1,73 +1,83 @@
-{
-  "name": "@slatesvideo/shared",
-  "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",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./auth": "./dist/auth.js",
-    "./clients/cloud": "./dist/clients/cloud.js",
-    "./clients/desktop": "./dist/clients/desktop.js",
-    "./operations": "./dist/operations/index.js",
-    "./prompts": {
-      "import": "./dist/prompts/index.js",
-      "types": "./dist/prompts/index.d.ts"
-    },
-    "./model-capabilities": {
-      "types": "./dist/prompts/model-capabilities.d.ts",
-      "default": "./dist/prompts/model-capabilities.js"
-    }
-  },
-  "files": [
-    "dist",
-    "!dist/**/*.map",
-    "skills",
-    "exports/slates-prompt-builder/generated",
-    "README.md"
-  ],
-  "scripts": {
-    "sync-partials": "node scripts/sync-partials.mjs",
-    "build-prompt-builder": "node scripts/build-prompt-builder.mjs",
-    "check-prompt-builder": "node scripts/build-prompt-builder.mjs --check",
-    "build": "node scripts/sync-partials.mjs --check && node scripts/build-prompt-builder.mjs --check && node scripts/embed-skills.mjs && tsc",
-    "typecheck": "node scripts/sync-partials.mjs --check && node scripts/build-prompt-builder.mjs --check && node scripts/embed-skills.mjs && tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/EricDisero/slates-mcp.git",
-    "directory": "packages/shared"
-  },
-  "homepage": "https://slates.video",
-  "bugs": {
-    "url": "https://github.com/EricDisero/slates-mcp/issues"
-  },
-  "keywords": [
-    "slates",
-    "mcp",
-    "model-context-protocol",
-    "ai-video",
-    "video-generation",
-    "image-generation",
-    "claude",
-    "veo",
-    "kling",
-    "seedance"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "fflate": "^0.8.3",
-    "typescript": "^5.7.0"
-  }
-}
+{
+  "name": "@slatesvideo/shared",
+  "version": "0.6.5",
+  "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",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./auth": "./dist/auth.js",
+    "./clients/cloud": "./dist/clients/cloud.js",
+    "./clients/desktop": "./dist/clients/desktop.js",
+    "./operations": "./dist/operations/index.js",
+    "./prompts": {
+      "import": "./dist/prompts/index.js",
+      "types": "./dist/prompts/index.d.ts"
+    },
+    "./model-capabilities": {
+      "types": "./dist/prompts/model-capabilities.d.ts",
+      "default": "./dist/prompts/model-capabilities.js"
+    },
+    "./shot-grammar": {
+      "types": "./dist/prompts/shot-grammar.d.ts",
+      "default": "./dist/prompts/shot-grammar.js"
+    },
+    "./asset-label": {
+      "types": "./dist/prompts/asset-label.d.ts",
+      "default": "./dist/prompts/asset-label.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "skills",
+    "exports/slates-prompt-builder/generated",
+    "README.md"
+  ],
+  "scripts": {
+    "sync-partials": "node scripts/sync-partials.mjs",
+    "build-prompt-builder": "node scripts/build-prompt-builder.mjs",
+    "check-prompt-builder": "node scripts/build-prompt-builder.mjs --check",
+    "build": "node scripts/sync-partials.mjs --check && node scripts/build-prompt-builder.mjs --check && node scripts/embed-skills.mjs && tsc && node scripts/render-capability-partials.mjs --check",
+    "typecheck": "node scripts/sync-partials.mjs --check && node scripts/build-prompt-builder.mjs --check && node scripts/embed-skills.mjs && tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "render-partials": "node scripts/render-capability-partials.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EricDisero/slates-mcp.git",
+    "directory": "packages/shared"
+  },
+  "homepage": "https://slates.video",
+  "bugs": {
+    "url": "https://github.com/EricDisero/slates-mcp/issues"
+  },
+  "keywords": [
+    "slates",
+    "mcp",
+    "model-context-protocol",
+    "ai-video",
+    "video-generation",
+    "image-generation",
+    "claude",
+    "veo",
+    "kling",
+    "seedance"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.23.0"
+  },
+  "devDependencies": {
+    "fflate": "^0.8.3",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/_partials/decision-log.md

@@ -1,12 +1,13 @@
-When you surface the plan, include a short **decision log** — one line per decision *you* made that the user did not specify:
+When you surface the plan, include a short **decision log** — one line per decision *you* made that the user did not specify **and that no row already records**:
 
 ```
 source phrase or declared default → what you wrote → what it resolves
-"in a diner"        → chrome-and-vinyl booth, 3/4 on the counter   → fixes the anchor so blocking is repeatable
+"in a diner"        → warm, and the light is the reason           → why the anchor was chosen, not what it is
 (no time of day)    → late afternoon, low warm key                 → default; say the word and it changes
-(no camera)         → slow push-in, single move                    → one move per shot; stacking increases instability
 ```
 
-**Hard rule: never silently add weather, props, style, or camera movement.** If it wasn't in the brief and you added it, it goes in the log. This is the "why did you add that?" affordance — for an agent that writes prompts on the user's behalf and spends their credits, it is what keeps the model in assembly and the user in the director's chair.
+🚨 **Keep it to what is NOT already data — and almost everything now IS.** A Shot holds the references and their roles, the model, every param, the shot size, the camera, the prop, the action and the spoken line, and `slates_list_shots` reads the whole board back in order with its variety counts. Narrating any of those is retelling a row the user can open. **Write the Shot, and let the log carry only the judgement no field holds** — why this world, why this light, why this register.
+
+**Hard rule: never silently add weather, props, style, or camera movement.** Four of those are now FIELDS: put the value on the Shot (`prop`, `camera`, `shotSize`, `action`) so the user can read and change it, and put the *reason* in the log only when you invented it rather than being told it. The rule has not softened — it moved from narration into data, which is stronger, because a field can be corrected and a sentence in chat cannot.
 
 > ❌ **Do NOT turn this into a question gate.** Clarifying questions before optimizing directly fight the locked fast-path rule: *if intent is clear, generate immediately with sane defaults, don't ask questions; only ask for production intent, and batch every question into one message.* Log the decisions, then go. The log is an **output**, not an interrogation — surfaced alongside the plan, never as a separate ceremony, and never as a reason to wait.

package/skills/_partials/thresholds.md

@@ -0,0 +1,19 @@
+<!-- GENERATED from @slatesvideo/shared — do not edit between the markers.
+     Source: CONFIRM_CREDITS, DEVIATION_FACTOR and the audio bounds in
+     packages/shared/src/operations/index.ts. Every number here is REFUSED by an
+     op when a prompt gets it wrong, which is why none of them is typed by hand
+     any more: this block replaced four claims that contradicted the code. -->
+
+**The thresholds, from the code that enforces them:**
+
+- **Confirm gate:** above **17 credits** an op returns `requires_confirm` and will not
+  proceed until you re-call with `confirm: true`. Below it, announce the cost once and go.
+- **Deviation pause:** the desktop Studio Agent stops and re-asks when projected generation spend
+  exceeds the approved plan by more than **20%**. You do not trigger this; the app does.
+- **Seed Audio duration:** **3–120 seconds.** There is no duration
+  parameter on the model — the number you pass is written into the prompt AND is what the user is
+  billed. Outside that range the op refuses rather than clamping.
+- **Sound Effects duration:** **1–22 seconds**, billed per second, never left for the
+  model to pick.
+
+Never quote a credit figure from memory: `slates_estimate_generation_cost` returns the real one.

package/skills/slates-content-policy.md

@@ -1,10 +1,24 @@
 ---
 name: slates-content-policy
-description: Content-policy-safe construction — build any scene safe from the first word so it hits full cinematic impact without depicting prohibited content (and without getting silently rejected or degraded by the model's filter). Read this before writing any prompt that involves conflict, creatures, crowds, destruction, weapons, or young characters. Mirror of @slatesvideo/shared/prompts content-policy fragment — SSOT: second-brain business/projects/slates/product/prompting-ssot.md.
+description: Read before writing any prompt involving conflict, creatures, crowds, destruction, weapons, or young characters. Builds the scene safe from the first word, so it hits full cinematic impact without depicting prohibited content — and without being silently rejected or degraded by the model's filter. Mirror of @slatesvideo/shared/prompts content-policy fragment — SSOT: second-brain business/projects/slates/product/prompting-ssot.md.
 ---
 
 # Content-policy-safe construction — read before any risk-surface prompt
 
+<!-- @banned:start -->
+<!-- slates-only -->
+<!-- MACHINE-READ. Every `backticked` token between the @banned markers is
+     extracted by src/prompts/banned-tokens.ts and returned on this model's cost
+     estimate, and every submitted prompt is matched against it. Keep entries
+     backticked and prose outside the backticks. -->
+<!-- /slates-only -->
+**Never use** — each one is a filter tripwire with a substitution in the table above:
+- `civilians in panic`, `crowds fleeing`, `blood`, `gore`, `corpse`
+- `ignite`, `catch fire`, `on fire` applied to a person — frame body-contact effects as magical or harmless VFX
+- `candle-like`, `flame-like` and any real object used as a metaphor for an effect
+- a real, named public figure
+<!-- @banned:end -->
+
 Don't depict the harm — depict the energy, the aftermath, the threat, or the scale. Build the scene safe from the first word.
 
 Write scenes that hit full cinematic impact without ever *needing* to depict prohibited content. This is a craft move, not a compromise — the substitutions below usually read as more cinematic, not less, and they keep your generation from getting silently rejected or degraded by the model's filter. A standoff is more tense than a massacre; an evacuated city is eerier than a crowd in panic; a roar lands harder than a kill. Load this whenever a prompt involves conflict, creatures, crowds, destruction, weapons, or young characters.

package/skills/slates-cost-discipline.md

@@ -13,7 +13,7 @@ Generation costs real money. Every call is on the user's credits. The user can't
 
 Before ANY `slates_generate_*` call, run `slates_estimate_generation_cost` first. Inputs you must lock before estimating:
 
-- **Model** — derived from the op (`slates_generate_image` → `nano-banana-2-{resolution}`)
+- **Model** — the id you are about to pass, whatever it is. `slates_estimate_generation_cost` takes the same base ids the generate ops take and resolves the billing key itself; do not build one by hand.
 - **Resolution** — never let the op default. Pick deliberately. Drafts → 1k. Hero → 2k. Print → 4k.
 - **Aspect ratio** — never let the op default to 1:1. Pick from the use case (cinematic → 16:9, mobile vertical → 9:16, square feed → 1:1).
 - **Count** — explicit. Don't generate 4 when 1 will tell you if the prompt works.
@@ -30,7 +30,29 @@ Examples:
 - `About to spend 4 credits on 1 image at 1k 16:9. Proceed?`
 - `About to spend 24 credits on 4 images at 2k 9:16 (variants). Proceed?`
 
-Below ~7 credits you can proceed silently after announcing once. Above ~7 credits wait for explicit confirmation. Above ~17 credits the server itself will gate with `requires_confirm` — pass `confirm: true` only after the user explicitly OKs.
+Announce the cost once, then proceed for anything small. For anything the user would notice on their balance, wait for an explicit yes. Where the LINE is, exactly:
+
+<!-- @inject:thresholds -->
+<!-- GENERATED from @slatesvideo/shared — do not edit between the markers.
+     Source: CONFIRM_CREDITS, DEVIATION_FACTOR and the audio bounds in
+     packages/shared/src/operations/index.ts. Every number here is REFUSED by an
+     op when a prompt gets it wrong, which is why none of them is typed by hand
+     any more: this block replaced four claims that contradicted the code. -->
+
+**The thresholds, from the code that enforces them:**
+
+- **Confirm gate:** above **17 credits** an op returns `requires_confirm` and will not
+  proceed until you re-call with `confirm: true`. Below it, announce the cost once and go.
+- **Deviation pause:** the desktop Studio Agent stops and re-asks when projected generation spend
+  exceeds the approved plan by more than **20%**. You do not trigger this; the app does.
+- **Seed Audio duration:** **3–120 seconds.** There is no duration
+  parameter on the model — the number you pass is written into the prompt AND is what the user is
+  billed. Outside that range the op refuses rather than clamping.
+- **Sound Effects duration:** **1–22 seconds**, billed per second, never left for the
+  model to pick.
+
+Never quote a credit figure from memory: `slates_estimate_generation_cost` returns the real one.
+<!-- @end:thresholds -->
 
 ### 3. Aggregate batches into ONE upfront announcement
 
@@ -46,7 +68,7 @@ When the user approves a batch plan with one aggregated cost total up front ("8
 
 Boundaries that re-trigger confirmation:
 
-- Any call's actual estimate exceeds what the announced plan implied for it by **>25%** → stop, surface the delta, get a fresh OK.
+- Any call's actual estimate exceeds what the announced plan implied → stop, surface the delta, get a fresh OK. The app enforces its own ceiling on top of this (see the thresholds above); do not wait for it to catch you.
 - New calls are added that weren't in the enumerated plan (extra variants, retries beyond the plan, a new scene) → those are NOT covered. Announce and confirm separately.
 - The batch scope changes (different model, resolution, or duration than announced) → re-announce, re-confirm.
 
@@ -87,7 +109,7 @@ If the user prompt mixes signals (e.g. "cinematic Instagram post"), ask. Don't g
 
 ## When the gate fires
 
-The server returns `requires_clarification` when aspect ratio or resolution is missing. The server returns `requires_confirm` when total spend exceeds ~17 credits. In both cases:
+The server returns `requires_clarification` when aspect ratio or resolution is missing, and `requires_confirm` when total spend crosses the gate above. In both cases:
 
 1. Surface the gate response to the user
 2. Get a clean answer

package/skills/slates-model-selection.md

@@ -105,10 +105,11 @@ Both tools are **Kling-only**. Every entry in them is a real Kling endpoint that
 
 | Job | Model | Why |
 |---|---|---|
-| **Default — a whole audio scene in one pass**: room tone, ambience beds, crowds, nature, layered dialogue + effects, spoken lines | **Seed Audio 1.0** (`seed-audio`) | One plain sentence in, a complete scene out. 1–120s. The continuity-bed workhorse and the only speech surface. |
-| **One effect that lands on a known frame**, or a seamless loop | **Sound Effects v2** (`eleven-sfx`) | The only surface with an exact duration control (0.5–22s) and a real loop mode. |
+| **Default — a whole audio scene in one pass**: room tone, ambience beds, crowds, nature, layered dialogue + effects, spoken lines inside a scene | **Seed Audio 1.0** (`seed-audio`) | One plain sentence in, a complete scene out. The continuity-bed workhorse; dialogue is performed inside the room, not cast. |
+| **One named voice saying one line** — a character's own voice, a narrator, a clean VO to lip-sync against | **Inworld TTS-2** (`inworld-tts-2`) | The prompt IS the words, spoken verbatim and billed per character. Voice = the character's clip (cloned for the take), a description, or a preset. No room tone — mix it on the timeline. |
+| **One effect that lands on a known frame**, or a seamless loop | **Sound Effects v2** (`eleven-sfx`) | The only surface with an exact duration control and a real loop mode. |
 
-**There is no music model and no cast-voiceover model.** A song is imported (Slates reads audio files and puts them on the timeline), not generated. A line that has to be spoken is generated on Seed Audio and lip-synced against.
+**There is no music model.** A song is imported (Slates reads audio files and puts them on the timeline), not generated. A line that has to be spoken in a SPECIFIC voice is generated on Inworld TTS-2 and lip-synced against; a line that belongs to a scene is performed by Seed Audio inside it.
 
 ### Named audio escalation triggers
 

package/skills/slates-one-prompt-film.md

@@ -1,6 +1,6 @@
 ---
 name: slates-one-prompt-film
-description: The full one-prompt-to-finished-film pipeline in Slates — script, project, characters, storyboard, frame images, video generation, timeline assembly, MP4 export. Use when the user gives one idea and wants a finished video out the other end - "make me a video about X", "turn this idea into an ad", "make a short film from this", "one prompt, finished film". This is the master recipe; other Slates skills are its sub-steps.
+description: Use when the user gives ONE idea and wants a finished video out the other end — "make me a video about X", "turn this idea into an ad", "make a short film from this". The full pipeline: script, project, characters, storyboard, frame images, video generation, timeline assembly, MP4 export. This is the master recipe; the other Slates skills are its sub-steps.
 ---
 
 # One prompt → finished film — Slates master pipeline
@@ -12,19 +12,22 @@ The user gives an idea. You hand back an MP4 on disk. Everything in between is y
 ### 1. Script the beats
 Turn the idea into a beat-level script: 4-10 shots, each with subject, action, setting, camera, and duration (4-8s per shot). Surface it as a tight table. Get the user's nod on the plan, format (aspect ratio — 16:9 vs 9:16 decides everything downstream), and rough budget appetite before touching any op.
 
+🚨 **Before you fire the set, read its variety counts.** `slates_list_shots` returns the distribution with every listing — shot sizes, camera moves, durations, and any bucket repeating three or more times in a row. Read the table as a COLUMN, not as rows: if push-in is the plurality or every row says wide, the batch is wrong before a credit is spent. The craft is `slates-shot-variety`.
+
 **Surface a decision log with the plan.**
 
 <!-- @inject:decision-log -->
-When you surface the plan, include a short **decision log** — one line per decision *you* made that the user did not specify:
+When you surface the plan, include a short **decision log** — one line per decision *you* made that the user did not specify **and that no row already records**:
 
 ```
 source phrase or declared default → what you wrote → what it resolves
-"in a diner"        → chrome-and-vinyl booth, 3/4 on the counter   → fixes the anchor so blocking is repeatable
+"in a diner"        → warm, and the light is the reason           → why the anchor was chosen, not what it is
 (no time of day)    → late afternoon, low warm key                 → default; say the word and it changes
-(no camera)         → slow push-in, single move                    → one move per shot; stacking increases instability
 ```
 
-**Hard rule: never silently add weather, props, style, or camera movement.** If it wasn't in the brief and you added it, it goes in the log. This is the "why did you add that?" affordance — for an agent that writes prompts on the user's behalf and spends their credits, it is what keeps the model in assembly and the user in the director's chair.
+🚨 **Keep it to what is NOT already data — and almost everything now IS.** A Shot holds the references and their roles, the model, every param, the shot size, the camera, the prop, the action and the spoken line, and `slates_list_shots` reads the whole board back in order with its variety counts. Narrating any of those is retelling a row the user can open. **Write the Shot, and let the log carry only the judgement no field holds** — why this world, why this light, why this register.
+
+**Hard rule: never silently add weather, props, style, or camera movement.** Four of those are now FIELDS: put the value on the Shot (`prop`, `camera`, `shotSize`, `action`) so the user can read and change it, and put the *reason* in the log only when you invented it rather than being told it. The rule has not softened — it moved from narration into data, which is stronger, because a field can be corrected and a sentence in chat cannot.
 
 > ❌ **Do NOT turn this into a question gate.** Clarifying questions before optimizing directly fight the locked fast-path rule: *if intent is clear, generate immediately with sane defaults, don't ask questions; only ask for production intent, and batch every question into one message.* Log the decisions, then go. The log is an **output**, not an interrogation — surfaced alongside the plan, never as a separate ceremony, and never as a reason to wait.
 <!-- @end:decision-log -->
@@ -37,24 +40,28 @@ A 4-10 shot script is where you invent the most on the user's behalf — time of
 - Recurring location? `slates_create_environment`.
 - One-off shots don't need character/environment records; skip the ceremony.
 
-### 3. Storyboard skeleton (no generation yet)
+### 3. Storyboard skeleton and the Shots (no generation yet)
 - `slates_create_storyboard`, `slates_add_scene` per script scene.
+- `slates_create_shot` per beat — the prompt, the model, the params and the references, with the roles they carry. **A Shot needs no image**, so the entire film exists as rows before anything is paid for.
+- `slates_get_shot` reads one back COMPOSED: the prompt the model will actually receive, its numbered references, and its exact quote. Audit your own work there — you cannot approve something the request will not contain.
 - Structure first, spend second — the user catches script problems on the free skeleton, not on burned credits.
 
 ### 4. ONE aggregated cost approval — then hands-off
-Price the whole batch before the first generation: frame images (count × model — `slates_estimate_generation_cost`) + video gens (count × model × duration). Present a single total:
+The Shots ARE the quote. `slates_generate_from_shots` without `confirm` returns one itemised total for the set plus the largest single item — no hand arithmetic, no `slates_estimate_generation_cost` per call:
 
-> Plan: 6 frames at 1k 16:9 + 5 × 8s Kling 3.0 std + 1 × 8s Seedance 2 hero shot ≈ $X.XX total. Proceed with the batch?
+> Plan: 6 frames at 1k 16:9 + 5 × 8s Kling 3.0 std + 1 × 8s Seedance 2 hero shot ≈ N credits total, largest single N. Proceed with the batch?
 
 Per `slates-cost-discipline` 3b: that single OK authorizes `confirm=true` for **every enumerated call in the batch** — no per-call re-asking. Re-confirm only if a call's price overruns the plan >25% or new calls get added (extra retakes, new shots).
 
 ### 5. Generate frame images
-Per shot: `slates_generate_image` with `referenceAssetIds` pointing at the character identity / environment / prior frames for consistency (Slates names each reference inline as "image N" — you don't hand-write role labels; reuse the same subject name across shots). Evaluate every result inline against the beat. Bind keepers via `slates_add_frame`.
+Fire the image Shots with `slates_generate_from_shots` (`confirm: true` — step 4 authorized it). Slates names each reference inline as "image N"; you never hand-write a role label or a number. Evaluate every result inline against the beat. Bind keepers via `slates_add_frame`, then `slates_update_shot` with `attachFrameId` so the recipe travels with the picture.
 
 **Multi-take where it matters:** for the hook shot and any shot the whole film hangs on, generate 2-4 variants (cheap model or 1k), pull them back with `slates_get_assets_batch`, pick the strongest on composition + identity, discard the rest. Don't multi-take filler shots.
 
-### 6. Generate video per frame — background mode
-`slates_generate_video` with `firstFrameAssetId` = the bound frame, `background: true`. Submit ALL shots, collect the generationIds, then poll `slates_get_generation_status` every 10-15s (1-5 min per gen; they survive app restarts). This parallelizes a 6-shot film into one wait instead of six.
+### 6. Generate video per Shot
+Fork each bound frame's image Shot with `slates_duplicate_shot` (`model:` the video model — that is the A/B lever the op takes inline), then `slates_update_shot` the copy with `firstFrameAssetId` = the bound frame. Two calls, because `slates_duplicate_shot` forks the prompt, the model and the params; **attachments are changed with `slates_update_shot`.** Then fire the set with `slates_generate_from_shots`.
+
+⚠️ **It runs SEQUENTIALLY and blocks until the last clip lands** — a 6-shot film is one long wait, and it will usually outlast the HTTP timeout while the run keeps going. When that happens, poll `slates_get_shot` for each Shot's `generationIds` and then `slates_get_generation_status`; **never re-fire, that double-spends.** (Concurrent batch firing needs a real queue — concurrency limiting, per-item failure isolation, partial-billing semantics — and is deliberately not built yet.)
 
 **Model mixing — route per `slates-model-selection`** (details in the per-model guides):
 - **Kling V3** (`slates-prompting-kling-v3`): the DEFAULT for most shots — 16:9 / 9:16 / 1:1, 3-15s, strong start-frame adherence; std is the workhorse, Omni for multi-character dialogue.
@@ -62,7 +69,7 @@ Per shot: `slates_generate_image` with `referenceAssetIds` pointing at the chara
 - **MiniMax H3** (`slates-prompting-minimax-h3`): route here when a shot's SOUND is part of the writing — a line delivered a particular way, scene sound under it, score that must stay outside the characters' world. It authors all three in one pass, which **collapses a shot's audio pass into its video pass** and removes the separate `slates_generate_audio` step for that shot. 5-15s, 480p/768p/2K/4K. Its sibling `minimax-h3-max` is faster but capped at 768p, takes no references, and costs MORE at 768p — a deliberate speed pick, never a saving.
 - **Veo 3.1** (`slates-prompting-veo-3`): niche, never the default — only when native synced audio must generate WITH the video in one gen; 16:9 or 9:16, 4/6/8s (8s only at 1080p/4K or with reference images).
 
-Failed gen? Check the error via `slates_get_generation_status`, fix the prompt, resubmit that one shot (a retry beyond the plan = announce the delta cost).
+Failed gen? The run continues past it and **nothing is retried automatically**. Read the per-Shot error in the result, fix that Shot with `slates_update_shot`, and re-fire only it (a retry beyond the plan = announce the delta cost).
 
 ### 7. Assemble the timeline
 - `slates_get_timeline` once to get the lay of the land.
@@ -85,3 +92,4 @@ Shots delivered, total spent vs. approved plan, the export path, and the single
 - **Look at everything.** Every image inline, every video via `slates_get_asset_video_frames` if a clip seems off. Never assemble a timeline from clips you haven't evaluated.
 - **3-strike rule per shot.** Three failed takes on one shot = stop, show the user what you tried, ask.
 - **Consistency comes from references, not luck.** Same identity asset on every character frame; same environment refs across a location's shots.
+- **Plan in Shots, not in chat.** Every decision that ends up in a sentence you have to remember is a decision the user cannot see, price, fork or re-fire. A Shot is a row: it survives the conversation, and the user can open it in the app and fix one reference without you.

package/skills/slates-project-organization.md

@@ -1,6 +1,6 @@
 ---
 name: slates-project-organization
-description: How a Slates project's assets are organized AND named — the asset short-code system (IMG-A12 / VID-V3 / AUD-S1 badges on every gallery card), folders for film STRUCTURE, the typed tabs for reusable references. Read when the user refers to an asset by code, asks what a code like IMG-A36 means, or when organizing/navigating a project.
+description: Use when the user names an asset by code ("use IMG-A36"), asks what a code means, or is organizing or navigating a project. Covers the asset short-code system (IMG-A12 / VID-V3 / AUD-S1 badges on every gallery card), folders for film STRUCTURE, and the typed tabs for reusable references.
 ---
 
 # Organizing a Slates project