@slatesvideo/shared 0.6.11 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/dist/auth.js +2 -2
  2. package/dist/clients/cloud.js +1 -1
  3. package/dist/index.d.ts +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/manual/content.d.ts +1 -1
  6. package/dist/manual/content.js +1 -1
  7. package/dist/operations/index.d.ts +817 -16
  8. package/dist/operations/index.js +1413 -360
  9. package/dist/operations/surface.d.ts +4 -1
  10. package/dist/operations/surface.js +41 -10
  11. package/dist/prompts/ad-presets.d.ts +77 -0
  12. package/dist/prompts/ad-presets.js +43 -0
  13. package/dist/prompts/agent-doctrine.js +27 -5
  14. package/dist/prompts/banned-tokens.d.ts +4 -29
  15. package/dist/prompts/banned-tokens.js +29 -204
  16. package/dist/prompts/craft-cards.js +2 -2
  17. package/dist/prompts/generation-policy.d.ts +41 -0
  18. package/dist/prompts/generation-policy.js +53 -0
  19. package/dist/prompts/guide-retrieval.d.ts +9 -0
  20. package/dist/prompts/guide-retrieval.js +53 -0
  21. package/dist/prompts/index.d.ts +1 -0
  22. package/dist/prompts/index.js +1 -0
  23. package/dist/prompts/model-capabilities.d.ts +18 -1
  24. package/dist/prompts/model-capabilities.js +72 -19
  25. package/dist/prompts/model-facts.d.ts +34 -2
  26. package/dist/prompts/model-facts.js +66 -5
  27. package/dist/prompts/partials.generated.js +8 -2
  28. package/dist/prompts/prompting-tips.d.ts +1 -1
  29. package/dist/prompts/prompting-tips.js +61 -16
  30. package/dist/prompts/reference-composer.d.ts +2 -0
  31. package/dist/prompts/reference-composer.js +51 -50
  32. package/dist/prompts/script-document.d.ts +165 -0
  33. package/dist/prompts/script-document.js +11 -0
  34. package/dist/prompts/shot-grammar.d.ts +4 -4
  35. package/dist/prompts/shot-grammar.js +3 -3
  36. package/dist/prompts/shot-spec.d.ts +13 -0
  37. package/dist/prompts/shot-spec.js +23 -5
  38. package/dist/skills/content.js +27 -24
  39. package/exports/slates-chatgpt-images/generated/SKILL.md +107 -0
  40. package/exports/slates-chatgpt-images/generated/slates-chatgpt-images.skill +0 -0
  41. package/exports/slates-prompt-builder/generated/SKILL.md +1 -1
  42. package/exports/slates-prompt-builder/generated/reference-character.md +9 -1
  43. package/exports/slates-prompt-builder/generated/reference-kling.md +3 -3
  44. package/exports/slates-prompt-builder/generated/reference-nano-banana.md +22 -10
  45. package/exports/slates-prompt-builder/generated/reference-seedance.md +4 -4
  46. package/exports/slates-prompt-builder/generated/slates-prompt-builder-manifest.json +17 -17
  47. package/exports/slates-prompt-builder/generated/slates-prompt-builder.skill +0 -0
  48. package/package.json +9 -3
  49. package/skills/_partials/cinematic-card.md +8 -0
  50. package/skills/_partials/cinematic-routes-short.md +2 -0
  51. package/skills/_partials/cinematic-tips-short.md +2 -0
  52. package/skills/_partials/decision-log.md +1 -13
  53. package/skills/_partials/image-defaults.md +11 -0
  54. package/skills/_partials/lens-video-split.md +1 -0
  55. package/skills/_partials/reference-rules-core.md +1 -1
  56. package/skills/_partials/sheet-tool-defaults.md +6 -0
  57. package/skills/slates-character-identity.md +9 -1
  58. package/skills/slates-chatgpt-images.md +107 -0
  59. package/skills/slates-cinematic-look.md +237 -0
  60. package/skills/slates-cost-discipline.md +18 -12
  61. package/skills/slates-direct-response-ad.md +13 -53
  62. package/skills/slates-edit-and-iterate.md +1 -1
  63. package/skills/slates-model-selection.md +20 -14
  64. package/skills/slates-one-prompt-film.md +19 -77
  65. package/skills/slates-project-organization.md +7 -3
  66. package/skills/slates-prompting-flux-2-max.md +15 -4
  67. package/skills/slates-prompting-gpt-image-2-5.md +41 -28
  68. package/skills/slates-prompting-inworld-tts.md +174 -174
  69. package/skills/slates-prompting-kling-v3.md +3 -3
  70. package/skills/slates-prompting-lip-sync.md +1 -1
  71. package/skills/slates-prompting-minimax-h3.md +30 -17
  72. package/skills/slates-prompting-motion-transfer.md +1 -1
  73. package/skills/slates-prompting-nano-banana-2.md +24 -11
  74. package/skills/slates-prompting-seedance-2-5.md +7 -6
  75. package/skills/slates-prompting-seedance.md +5 -5
  76. package/skills/slates-prompting-seedream-5-lite.md +14 -3
  77. package/skills/slates-prompting-veo-3.md +1 -1
  78. package/skills/slates-script-craft.md +45 -0
  79. package/skills/slates-shot-variety.md +11 -40
  80. package/skills/slates-storyboard-from-script.md +14 -66
  81. package/skills/slates-style-prompting.md +4 -4
  82. package/skills/slates-ugc-influencer-ad.md +32 -309
  83. package/skills/slates-vision-feedback-loop.md +2 -1
@@ -18,20 +18,27 @@ description: How to write prompts that produce cinematic, photorealistic results
18
18
  **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].`
19
19
 
20
20
  **The five levers**
21
- 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`.
21
+ 1. **Named lens + aperture** beats "shallow depth of field" — `85mm f/1.4`, `135mm f/2.8`, `Panavision anamorphic`, `400mm telephoto`.
22
22
  2. **Light by direction and quality**, never "good lighting" — `hard sidelight from a single window, deep falloff`, `overcast north light`, `practical tungsten spill`.
23
23
  3. **A named film stock or sensor** carries a whole palette — `Kodak Portra 400`, `Cinestill 800T`, `ARRI Alexa 65`.
24
24
  4. **Composition as a shot** — `low angle`, `aerial view`, `rule of thirds with the subject camera-left`, `foreground occlusion`.
25
25
  5. **Positive framing only.** Describe what is there. "Empty street", never "no cars"; "unstaged documentary photography", never "not anime".
26
26
 
27
- **Examples**
28
- - `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.`
29
- - `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.`
27
+ <!-- @inject:cinematic-card -->
28
+ **For a photographic look, use only what this frame needs.** Image models default to clean, evenly lit and fully exposed. Describe what the camera sees, not just gear or mood:
29
+ - **Inspect every reference first.** Write its grade and imperfections in words: darkness, contrast, muddy or true blacks, colour, softness/noise, subject separation. Never grade cleaner or brighter than the look reference unless asked.
30
+ - **One light system** — `low sun behind her`, `her face falls into deep shadow`, `no light in front of her`.
31
+ - **Visible exposure** — `the sky burns out to white`, `dense, slightly crushed shadows`.
32
+ - **Lens name plus effect** — `200mm telephoto`, `peaks loom huge behind her and melt into soft shapes`.
33
+ - **Name every garment and close the foreground.** Omissions invite reference leakage or invented props.
34
+ Bind references inline. A scene reference owns the grade; for a look-only reference, write the new scene's light. References are optional. For owned-frame edits, describe only the change and what stays.
35
+ <!-- slates-only -->Use `slates-cinematic-look` with a technique ID or section query for more.<!-- /slates-only -->
36
+ <!-- @end:cinematic-card -->
30
37
 
31
38
  **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.
32
39
  <!-- @card:end -->
33
40
 
34
- Nano Banana 2 is **Gemini 3.1 Flash Image**.<!-- slates-only --> It is the default model behind `slates_generate_image` — the op also exposes `flux-2-max` and `seedream-5-lite`, each with its own prompting skill.<!-- /slates-only --> It is **not** Gemini 3 Pro Image; that is Nano Banana **Pro** (`nano-banana-pro`), a separate model with its own seat.<!-- slates-only --> Verified against the runtime slug map in `slate/src/main/api/google.ts`.<!-- /slates-only --> 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**.
41
+ Nano Banana 2 is **Gemini 3.1 Flash Image**.<!-- slates-only --> It is the headless image model used when `projectId` is omitted — the op also exposes `flux-2-max` and `seedream-5-lite`, each with its own prompting skill.<!-- /slates-only --> It is **not** Gemini 3 Pro Image; that is Nano Banana **Pro** (`nano-banana-pro`), a separate model with its own seat.<!-- slates-only --> Verified against the runtime slug map in `slate/src/main/api/google.ts`.<!-- /slates-only --> 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**.
35
42
 
36
43
  Knowledge cutoff: January 2025. Anything after needs explicit reference images.
37
44
 
@@ -56,12 +63,14 @@ Film still from [DIRECTOR] [GENRE]. Shot on [CAMERA] with [LENS]. [SUBJECT and a
56
63
 
57
64
  ## Photorealism positives — what consistently works
58
65
 
59
- > ⚠️ **This vocabulary is an IMAGE-model lever and a video-model anti-pattern — do not carry it across.**
60
- > Named lenses, apertures, film stocks and camera bodies (`85mm f/1.4`, `Kodak Portra 400`, `ARRI Alexa 65`) are correct and encouraged **here**. They are a **Seedance anti-pattern**: ByteDance's own guide uses shot sizes, camera moves, pacing words and its image-quality vocabulary throughout, and never once mentions fps, shutter angle, f-stop, or lens millimetres.
61
- > The leak happens in one specific way — you write an NB2 start frame, then write the video prompt to animate it and carry the look description straight across. **Translate instead of copying:** `85mm f/1.4, Portra 400` → `close-up, shallow depth of field, warm natural colors, cinematic texture, film-grain texture`. Full rule and the receipts: `slates-prompting-seedance` (Part 3, "Don't cross-pollinate image-model syntax").
66
+ ⚠️ **This vocabulary is correct here and does not carry into a video prompt.** The leak happens one way: you write an NB2 start frame, then carry its look description straight into the prompt that animates it.
67
+
68
+ <!-- @inject:lens-video-split -->
69
+ Named lenses, apertures, film stocks and camera bodies (`85mm f/1.4`, `Kodak Portra 400`, `ARRI Alexa 65`) are an image-model lever. On a video model, translate the look instead of pasting the gear list: `85mm f/1.4, Portra 400` becomes `close-up, shallow depth of field, warm natural colors, cinematic texture, film-grain texture`. ByteDance's Seedance 2.0 guide never mentions fps, shutter angle, f-stop or lens millimetres. Its Seedance 2.5 guide does, once: the visual-style line of its own storyboard example names one camera body and one 35 mm cinema lens. On 2.5 a single line like that is vendor-sanctioned; a stacked gear list still is not.
70
+ <!-- @end:lens-video-split -->
62
71
 
63
72
  **Named lenses + apertures** beat generic "shallow depth of field":
64
- - `85mm f/1.4`, `135mm f/2.8` (the cheat code for skin texture), `50mm f/1.2`, `35mm f/2`
73
+ - `85mm f/1.4`, `135mm f/2.8`, `50mm f/1.2`, `35mm f/2`
65
74
  - `Panavision anamorphic` for horizontal flares + cinematic width
66
75
  - `400mm telephoto` for compression + isolation
67
76
  - `24mm` for environmental interiors
@@ -86,6 +95,7 @@ Film still from [DIRECTOR] [GENRE]. Shot on [CAMERA] with [LENS]. [SUBJECT and a
86
95
  - `visible pores`, `natural skin grain`, `peach fuzz`, `slight hyperpigmentation`
87
96
  - `unretouched raw photography`, `ISO noise`, `sweat beading`
88
97
  - `crisp catchlights in the eyes`, `skin micro-detail`
98
+ - Lead with the kind of photograph and the conditions on the skin (sun, wind, sweat), then add one or two of these. A bare list of flaw words read as tokens and produced plastic skin on GPT Image 2 (2026-08-24).<!-- slates-only --> Technique: `slates-cinematic-look` → `name-the-capture-context`.<!-- /slates-only -->
89
99
 
90
100
  **Director references** (use when locking style):
91
101
  | Director | Tone | Visual signature |
@@ -123,6 +133,9 @@ These are Stable-Diffusion-era tag soup. The model treats them as low-signal noi
123
133
  - `not anime, not cartoon, not 3D` — negation tag soup, replace with a positive style cue
124
134
  <!-- @banned:end -->
125
135
 
136
+ **Examples**
137
+ - `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.`
138
+
126
139
  ## Negative prompting — there is no field
127
140
 
128
141
  Nano Banana 2 has **no `negativePrompt` parameter**. Three patterns to suppress unwanted content:
@@ -136,7 +149,7 @@ Default to #1. Reach for #2 only when positive framing can't suppress the unwant
136
149
  ## Reference images
137
150
 
138
151
  - **Hard limit: 14 images** (10 object-fidelity + 4 character-consistency). Categories don't trade — you can't use 14 object slots even if no characters are referenced.
139
- - **Name each reference inline — Slates does this for you.** When you `@mention` a subject/environment or `#mention` a style<!-- slates-only --> (or pass `referenceAssetIds`)<!-- /slates-only -->, Slates composes the prompt so each reference is named inline as "image N" — e.g. `Marcus (image 1) sits across from the woman (image 2) in the cafe (image 3)`, with a trailing `Render in the visual style of image 4.` The model does NOT infer a reference's role from its position; the NAME carries it. NB2's own consistency lever is literally **"assign a distinct name to each character/object"**. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render the scene's expression") — that drags the sheet's wardrobe + studio lighting into the scene. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
152
+ - **Name each reference inline — Slates does this for you.** When you `@mention` a subject/environment or `#mention` a style<!-- slates-only --> (or pass `referenceAssetIds`)<!-- /slates-only -->, Slates composes the prompt so each reference is named inline as "image N" — e.g. `Marcus (image 1) sits across from the woman (image 2) in the cafe (image 3)`, or `lit and graded like image 4` where you placed the style mention. An unmentioned style attachment gets a short fallback clause The model does NOT infer a reference's role from its position; the NAME carries it. NB2's own consistency lever is literally **"assign a distinct name to each character/object"**. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render the scene's expression") — that drags the sheet's wardrobe + studio lighting into the scene. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
140
153
 
141
154
  ### Reference rules (the verified ones)
142
155
 
@@ -158,7 +171,7 @@ Every reference rule below is a corollary of that one sentence, which is why "pr
158
171
  Identity = a few flat-lit neutral angles; one reference per role, named inline; 2-4 refs not 12; describe environments instead of feeding a grid.
159
172
 
160
173
  1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each one adds context AND another variable to balance.
161
- 2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.
174
+ 2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates resolves `@mentions` / `#tags` into numbered citations. You can also bind references directly in scene prose, naming what each image supplies.
162
175
  3. **One identity sheet per character, named inline.** A character's identity is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render a neutral expression") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
163
176
  4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.
164
177
  5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — never a multi-panel grid fed whole.
@@ -40,7 +40,7 @@ description: How to prompt Seedance 2.5 and Seedance 2.5 Edit. Read before calli
40
40
  <!-- /slates-only -->
41
41
  **Never use** (2.5 reclassifies the task and fails a fresh generation on these):
42
42
  - `edit`, `extend`, `continue the video`, `same video but` — they make the provider read a fresh generation as an edit
43
- - `85mm`, `f/1.4`, `Portra 400` and any other lens, aperture, film-stock or camera-body token — image-model vocabulary, a Seedance anti-pattern on both seats
43
+ - `f/1.4`, `Portra 400` and any other aperture or film-stock token, or a stacked list of gear — image-model vocabulary. The 2.5 guide's own example names one camera body and one 35 mm lens in a single style line, so a lone lens there is not on this list
44
44
  <!-- @banned:end -->
45
45
 
46
46
  **Read `slates-prompting-seedance` first.** The prompt GRAMMAR is the same model family: the
@@ -127,11 +127,11 @@ Worked, at the shipped rates:
127
127
  |---|---|
128
128
  | 2.5 · 480p · 5s · faceless | 26 |
129
129
  | 2.5 · 720p · 5s · faceless | 58 |
130
- | 2.5 · 1080p · 5s · faceless | 103 |
130
+ | 2.5 · 1080p · 5s · faceless | 142 |
131
131
  | 2.5 · 720p · 30s · faceless | 347 |
132
132
  | 2.5 · 720p · 30s · AI-face route | **489** |
133
133
  | 2.5 · 720p · 30s · consented real-face route | **710** |
134
- | 2.5 · 1080p · 30s · faceless | **614** |
134
+ | 2.5 · 1080p · 30s · faceless | **853** |
135
135
  | 2.5 · 1080p · 30s · consented real-face route | **1,749** |
136
136
  | *(for scale)* 2.0 · 1080p · 15s · AI-face route | 411 |
137
137
 
@@ -364,7 +364,7 @@ not a lip-sync job. Bill it like any other edit — on the source clip's length.
364
364
 
365
365
  The three-tier face routing is identical to 2.0 — faceless → default route, an AI character's face →
366
366
  `seedanceFace: true` (the relaxed provider, a real cost premium), a real person's photo → the
367
- consent-gated premium route after a `[REAL_FACE_DETECTED]` rejection, with `realFaceConsent: true`
367
+ consent-gated real-person route after a `[REAL_FACE_DETECTED]` rejection, with `realFaceConsent: true`
368
368
  set **only** after the user explicitly confirms they hold the rights to the likeness. The full rules,
369
369
  including why the real-vs-AI call is the provider's and not yours, are in
370
370
  `slates-prompting-seedance`.
@@ -372,8 +372,9 @@ including why the real-vs-AI call is the provider's and not yours, are in
372
372
  Also unchanged, and worth restating because 2.5's length makes each one more expensive to get wrong:
373
373
 
374
374
  - **One primary camera move per shot.**
375
- - **No lens / aperture / film-stock vocabulary.** That is image-model syntax and a Seedance
376
- anti-pattern.
375
+ - **No stacked lens / aperture / film-stock vocabulary.** One camera-and-lens style line is the
376
+ most the 2.5 guide itself uses; the full rule is in `slates-prompting-seedance` → "Don't
377
+ cross-pollinate image-model syntax".
377
378
  - **No `negativePrompt` field** — constraints go inline, and 2.5 acts on negative phrasing in
378
379
  exactly two dimensions: subtitles (*"no subtitles"*) and audio (*"no BGM; environmental and
379
380
  action sounds only"*, *"no audio"*). Everywhere else, describe what you want, not what you don't.
@@ -266,7 +266,7 @@ Seedance routes through **three tiers** depending on the face in the reference,
266
266
 
267
267
  - **Faceless / object / environment refs → default route (cheapest).** Leave `seedanceFace` off.
268
268
  - **An AI-character's FACE in a reference → `seedanceFace: true`.** The default route's baseline moderation rejects or degrades faces, so this reroutes to the face-capable provider. It costs **~45% more** — the cost key becomes `seedance-2-face-{res}-{N}s`, so the pre-flight quote already reflects it. Announce the face-route price, not the faceless one.
269
- - **A REAL person's photo (the user themselves, an actor) → the consent-gated premium route.** If a `seedanceFace` gen fails with `[REAL_FACE_DETECTED]`, the provider classified the reference as a real person: confirm with the user that (a) they hold the rights/consent to the likeness and (b) they accept the higher price (cost key `seedance-2-realface-{res}-{N}s`, roughly 2× the AI-face rate — quote via `slates_estimate_generation_cost`), then retry with `seedanceRealFace: true` + `realFaceConsent: true`. Never set `realFaceConsent` without the user's explicit confirmation.
269
+ - **A REAL person's photo (the user themselves, an actor) → the consent-gated real-person route.** If a `seedanceFace` gen fails with `[REAL_FACE_DETECTED]`, the provider classified the reference as a real person: confirm with the user that (a) they hold the rights/consent to the likeness and (b) they accept the higher price (cost key `seedance-2-realface-{res}-{N}s`, roughly 2× the AI-face rate — quote via `slates_estimate_generation_cost`), then retry with `seedanceRealFace: true` + `realFaceConsent: true`. Never set `realFaceConsent` without the user's explicit confirmation.
270
270
 
271
271
  Rules:
272
272
  - **The real-vs-AI call is the PROVIDER'S, not yours.** ByteDance's classifier is probabilistic — some real photos pass the standard face route (billed at the cheap rate; fine), others get rejected with `[REAL_FACE_DETECTED]` (auto-refunded). Don't preemptively route to the real-face tier just because a photo looks real; try `seedanceFace: true` first and escalate only on the marked rejection. Public figures / celebrities fail on every route.
@@ -294,7 +294,7 @@ Every reference rule below is a corollary of that one sentence, which is why "pr
294
294
  Identity = a few flat-lit neutral angles; one reference per role, named inline; 2-4 refs not 12; describe environments instead of feeding a grid.
295
295
 
296
296
  1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each one adds context AND another variable to balance.
297
- 2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.
297
+ 2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates resolves `@mentions` / `#tags` into numbered citations. You can also bind references directly in scene prose, naming what each image supplies.
298
298
  3. **One identity sheet per character, named inline.** A character's identity is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render a neutral expression") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
299
299
  4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.
300
300
  5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — never a multi-panel grid fed whole.
@@ -384,9 +384,9 @@ One primary anchor + 2-3 supporting details, as the trailing paragraph (both off
384
384
 
385
385
  ## ⚠️ Don't cross-pollinate image-model syntax
386
386
 
387
- Named **lenses, apertures, film stocks, and camera bodies** — `85mm f/1.4`, `Kodak Portra 400`, `ARRI Alexa 65`, `shot on Sony A7S3` — are an **image-model lever** (correct and encouraged in `slates-prompting-nano-banana-2`) and a **Seedance anti-pattern**. ByteDance's guide uses shot sizes, camera moves, pacing words, and the image-quality/style vocabulary throughout, and never once mentions fps, shutter angle, f-stop, or lens millimetres.
388
-
389
- If you are carrying a look over from an NB2 start frame, translate it: `85mm f/1.4, Portra 400` → `close-up, shallow depth of field, warm natural colors, cinematic texture, film-grain texture`.
387
+ <!-- @inject:lens-video-split -->
388
+ Named lenses, apertures, film stocks and camera bodies (`85mm f/1.4`, `Kodak Portra 400`, `ARRI Alexa 65`) are an image-model lever. On a video model, translate the look instead of pasting the gear list: `85mm f/1.4, Portra 400` becomes `close-up, shallow depth of field, warm natural colors, cinematic texture, film-grain texture`. ByteDance's Seedance 2.0 guide never mentions fps, shutter angle, f-stop or lens millimetres. Its Seedance 2.5 guide does, once: the visual-style line of its own storyboard example names one camera body and one 35 mm cinema lens. On 2.5 a single line like that is vendor-sanctioned; a stacked gear list still is not.
389
+ <!-- @end:lens-video-split -->
390
390
 
391
391
  ## Negative prompting — inline only
392
392
 
@@ -24,9 +24,16 @@ description: How to prompt Seedream 5 Lite (ByteDance image model — the cheap
24
24
  4. **Name the light as a named condition** — `golden hour`, `dramatic side lighting`, `soft diffused light`, `moody low-key`, `bright high-key`.
25
25
  5. **Quote in-image text.** It takes quoted strings for posters and layouts, which is half of why it is the drafting seat.
26
26
 
27
- **Examples**
28
- - `Professional headshot of a female CEO, short blonde hair, confident expression, navy suit, neutral office background. Studio lighting, shallow depth of field, high-end corporate photography, shot on 85mm.`
29
- - `A rain-soaked night market stall, cinematic, rule of thirds with the vendor camera-right, foreground steam blurred, moody low-key lighting with practical neon, shot on 35mm.`
27
+ <!-- @inject:cinematic-card -->
28
+ **For a photographic look, use only what this frame needs.** Image models default to clean, evenly lit and fully exposed. Describe what the camera sees, not just gear or mood:
29
+ - **Inspect every reference first.** Write its grade and imperfections in words: darkness, contrast, muddy or true blacks, colour, softness/noise, subject separation. Never grade cleaner or brighter than the look reference unless asked.
30
+ - **One light system** — `low sun behind her`, `her face falls into deep shadow`, `no light in front of her`.
31
+ - **Visible exposure** — `the sky burns out to white`, `dense, slightly crushed shadows`.
32
+ - **Lens name plus effect** — `200mm telephoto`, `peaks loom huge behind her and melt into soft shapes`.
33
+ - **Name every garment and close the foreground.** Omissions invite reference leakage or invented props.
34
+ Bind references inline. A scene reference owns the grade; for a look-only reference, write the new scene's light. References are optional. For owned-frame edits, describe only the change and what stays.
35
+ <!-- slates-only -->Use `slates-cinematic-look` with a technique ID or section query for more.<!-- /slates-only -->
36
+ <!-- @end:cinematic-card -->
30
37
 
31
38
  **Hard constraint:** it is the DRAFTING seat, not the hero seat. Explore here, then re-run the winner on Nano Banana 2 or FLUX.2 Max for the locked shot.
32
39
  <!-- @card:end -->
@@ -43,6 +50,10 @@ description: How to prompt Seedream 5 Lite (ByteDance image model — the cheap
43
50
  - a prompt past about 100 words: this model gets confused by very long prompts, and focused beats exhaustive
44
51
  <!-- @banned:end -->
45
52
 
53
+ **Examples**
54
+ - `Professional headshot of a female CEO, short blonde hair, confident expression, navy suit, neutral office background. Studio lighting, shallow depth of field, high-end corporate photography, shot on 85mm.`
55
+ - `A rain-soaked night market stall, cinematic, rule of thirds with the vendor camera-right, foreground steam blurred, moody low-key lighting with practical neon, shot on 35mm.`
56
+
46
57
  ByteDance's Seedream image model, Lite tier, routed via fal.ai. In Slates: `slates_generate_image` with `model: seedream-5-lite` (REQUIRES projectId — no headless path). **Flat-priced regardless of resolution** — the cheapest image model in Slates, which makes it the right default for high-volume drafting, storyboard exploration, and variant grids. Call `slates_estimate_generation_cost` for the current number; never quote prices from memory. Less censored than Nano Banana 2.
47
58
 
48
59
  **When to pick it:** lots of frames cheap (storyboard passes, 3-4 variant exploration), posters/layouts with text, quick look-dev. Step up to NB2 or FLUX.2 Max for the locked hero shot.
@@ -155,7 +155,7 @@ Every reference rule below is a corollary of that one sentence, which is why "pr
155
155
  Identity = a few flat-lit neutral angles; one reference per role, named inline; 2-4 refs not 12; describe environments instead of feeding a grid.
156
156
 
157
157
  1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each one adds context AND another variable to balance.
158
- 2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.
158
+ 2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two "identity" refs of different people blend into a third face). Slates resolves `@mentions` / `#tags` into numbered citations. You can also bind references directly in scene prose, naming what each image supplies.
159
159
  3. **One identity sheet per character, named inline.** A character's identity is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **Do NOT hand-write a "Reference Image Instructions" block or role essays** ("use for identity, ignore the outfit, render a neutral expression") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.
160
160
  4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.
161
161
  5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — never a multi-panel grid fed whole.
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: slates-script-craft
3
+ description: Write or revise script passages, develop distinct openings and bridges, and compare section variations while preserving the user's format, voice and fixed material. This is writing craft, not a request to generate media.
4
+ ---
5
+
6
+ # Script craft and variations
7
+
8
+ Work in the user's document. Read its revision, requested passage and neighboring context. Keep supplied facts, deliberate cadence and fixed sections intact. A script may be silent, a conversation, one continuous sentence, independent scenes, or any mixture. These are tools to choose from, not required stages.
9
+
10
+ <!-- @evidence: script-craft-20260922 sc-event sc-proof sc-exchange sc-callback sc-modular sc-bridge sc-offer sc-flow -->
11
+
12
+ ## Opening, argument and payoff
13
+
14
+ | Technique | Evidence | What it does | Reach for · skip | Say |
15
+ |---|---|---|---|---|
16
+ | `sc-event` | Observed creative pattern; conversion unmeasured | Start with an event or consequence, including sound or silence. | Useful when the product can participate; skip spectacle unrelated to its promise. | `Keys slide toward the table edge; the tray catches them.` |
17
+ | `sc-proof` | Observed demonstration pattern | Show the specific claim being tested. Speech may direct attention to the visible evidence. | Useful for observable behavior; skip claims the demonstration cannot establish. | `Watch the rim.` |
18
+ | `sc-exchange` | Observed multi-speaker pattern | Let another speaker question, react or misunderstand. Preserve the answering context. | Useful for objections and comedy; do not isolate a dependent answer. | `A: You bought a tray for that? B: Look where my keys used to land.` |
19
+ | `sc-callback` | Observed repeated-character comedy | Repeat deliberately, escalate, then resolve or change the meaning. | Useful for recognition and payoff; skip repetition without a purpose. | `The same searching hand finally reaches straight for the tray.` |
20
+ | `sc-modular` | Scoped house-format technique | Make selected passages self-contained so they can move independently. | Useful for reorderable demonstrations; do not flatten continuing dialogue. | `At the door, it catches the keys. On the desk, it holds the loose change.` |
21
+ | `sc-bridge` | Variation craft synthesis | Vary an opening together with any transition it requires. | Check pronouns, promise, reveal order and offer; preserve the chosen body. | `Where do your keys land? Mine used to land wherever my hand stopped. Now they land here.` |
22
+ | `sc-offer` | Claim-control synthesis | Make the next action understandable and supported by the brief. | Use supplied destinations and terms; never invent price, savings, scarcity or guarantees. | `See the available finishes.` |
23
+ | `sc-flow` | Spoken-writing synthesis | Clarify subject, action and causal connection before removing stylistic patterns. | Keep intentional rhythm and jokes; skip mechanical fragmenting. | `Put your keys here when you come in.` |
24
+
25
+ ## Distinct openings and compatible bridges
26
+
27
+ Change the idea: an event, question, objection, proof, audience situation or reveal. Merely swapping adjectives is not a useful comparison. Name what stays fixed for this operation. A dependency belongs in the selected passage: if an opening changes what “that” means, include its bridge in the version.
28
+
29
+ Read each candidate as a complete piece with the same body. Check unanswered promises, introduced speakers, incompatible offers and repeated reveals. Suggestions remain editable; no required Hook/Body/CTA fields.
30
+
31
+ Use `slates_get_script_document`, `slates_get_script_sections` and revision-checked `slates_update_script_document` / `slates_update_script_section`. Save versions before switching. Preview one requested combination before materializing it; never expand every possible combination automatically. Reference substitutions are explicit IDs, not name replacements in prose. Keep voice retention deliberate.
32
+
33
+ ## Spoken flow and pacing
34
+
35
+ Prefer a concrete actor doing something over abstract benefit language. “Seamlessly elevate your daily carry” becomes “Put your keys here when you come in.” Connect causes where needed: “I put them down, then forget where” is clearer than mechanically shortening it to “Keys. Gone. Again.”
36
+
37
+ Preserve the user's or reference's cadence when it carries character, comedy or comprehension. A repeated sentence or triplet is not inherently an error. Personal voice preferences apply only to the person who supplied them. Never invent testimonials or measurable results.
38
+
39
+ Read the canonical fit analysis supplied with the shots. Its corpus estimate uses total ad runtime, including silence, and an opt-in register sample. It is not measured articulation speed; the observed maximum is not a universal human limit. Plan for pauses, reactions and sound. Once a voice/video take exists, its measured performance governs the cut. Model clip duration, estimated script duration and actual speech duration are separate facts.
40
+
41
+ ## Apply the requested scope
42
+
43
+ For suggestions, propose each replacement with `slates_update_script_suggestions` (action `create`), quoting the exact words it replaces at the revision you read; the creator accepts or dismisses it in the document, and `slates_get_script_suggestions` reports what became of it. For an explicit edit request, apply the scoped edit and read it back; do not add an approval ceremony. On a stale revision, reread and preserve both authors' changes. Do not replace the whole script to change one opening.
44
+
45
+ Headings and directions are non-spoken metadata. Shots are optional production bindings. Script-driven recipes compile the active words; custom prompts retain their bytes and need a visible alignment review. Existing takes remain historical media. Writing, switching versions and importing templates do not generate anything. Load production and cost guidance only when production is requested.
@@ -1,53 +1,24 @@
1
1
  ---
2
2
  name: slates-shot-variety
3
- description: Use when planning a set of shots, before firing a batch, when the variety counts on a shot list show one bucket dominating, or when a finished piece reads as flat, samey or repetitive despite each shot being individually fine.
3
+ description: Diagnose unintended visual sameness across a shot sequence while preserving deliberate repetition, continuing performance and the user's chosen format.
4
4
  ---
5
5
 
6
- # Shot variety — why it all starts to look the same
6
+ # Visual rhythm across a sequence
7
7
 
8
- The failure this skill exists for is mechanical, not artistic: **every shot is fine and the sequence is dead.** It happens because a model asked ten times in a row, from ten similar prompts, returns ten similar framings — and because the person writing those prompts is thinking about *what is in the shot* rather than *how this shot differs from the one before it*.
8
+ `slates_list_shots` supplies distributions and repeated runs from authored shot fields. Read across the sequence, then decide whether repetition serves the intended effect. A dominant bucket is a question, not a defect or generation barrier.
9
9
 
10
- Slates counts the sameness for you. It does not judge it. **`slates_list_shots` returns the distribution with every listing** — shot sizes, camera moves, models, durations, and any bucket repeating three or more times in a row — so the numbers are in front of you before you spend anything. Reading them is the job; deciding what to do is yours.
10
+ ## Compare neighboring cuts
11
11
 
12
- ## Read the table as a COLUMN, not as rows
12
+ Look at framing, camera behavior, duration, subject distance, location and cast. Change the dimension that carries the meaning of the next beat. A wider view may reveal geography; a close view may make a small action legible. Do not add camera motion simply because another shot is static.
13
13
 
14
- This is the whole technique, and it is one sentence:
14
+ Repeated frames can establish a joke, a comparison or a calm observational register. Recurring people and locations can carry a conversation. A later change often works because the earlier pattern held. State that purpose briefly when a count flags an intentional choice.
15
15
 
16
- > Sort the list by shot size and count. Sort it by camera move and count. **If push-in is the plurality, or every row says wide, the batch is wrong before a single credit is spent.**
16
+ ## Re-cut only for a reason
17
17
 
18
- A shot list read row by row always looks fine, because each row was written to be good on its own. The sameness only shows up in the column. That is why the counts ship in the op result rather than in your head.
18
+ Merge when performance and picture should continue together. Split when the image needs to change while speech continues, or when the intended read needs another placement. Preserve sentence continuity and references across the split. Price the resulting requests; do not assume splitting is free or merging is cheaper.
19
19
 
20
- ## What to vary, in order of how much it matters
20
+ The script fit signal derives from an opt-in ad corpus measured over whole runtime. Above-sample pace deserves inspection; it does not prove a line impossible. Measure the actual spoken take when available, including pauses and reactions. No fixed cut length or shot count is a universal rule.
21
21
 
22
- 1. **Shot size.** The single biggest lever, and the one that collapses first. A sequence of seven mediums reads as a slideshow no matter what is in them. Wide → close is a cut; medium → medium is a dissolve nobody asked for.
23
- 2. **Camera move.** Second-biggest, and the one models default to: ask for "cinematic" and you get a slow push-in, every time. If five of seven cuts push in, four of them should not.
24
- 3. **Duration.** Rhythm is not decoration. Seven identical 8-second cuts is a metronome. A 3-second cut lands differently *because* the one before it ran twelve.
25
- 4. **Distance between subjects and lens.** A long lens on a close-up and a wide lens on a close-up are different shots, and the model will render the difference.
26
- 5. **Location and cast.** If three cuts happen in the same room with the same person, that is a scene — fine. If *nine* do, the piece has one idea.
22
+ Multi-shot generations can contain several visual cuts. Compare their internal rhythm as well as the boundaries between generated clips. The app counts only authored information: an unknown framing bucket is missing description, not evidence about the pixels.
27
23
 
28
- ## When repetition is deliberate — and it often is
29
-
30
- Do not treat the counts as a defect list. Repetition is a technique with two real uses:
31
-
32
- - **A repeated frame IS the joke, or the point.** Three identical wides with one thing changed each time is a gag structure, and varying them would destroy it.
33
- - **A locked-off frame is a choice.** Static, static, static, then a move — the move only lands because the first three did not have one.
34
-
35
- The check catches a bucket dominating. It cannot tell whether you meant it. If you did, say so and move on; the counts do not block anything and never will.
36
-
37
- ## Choosing the chop: one long take or several short ones
38
-
39
- This is the decision that owns the rhythm, and Slates puts the price next to it: `slates_split_shot` and `slates_merge_shots` re-cut a board, and the row's duration and quote move as you do it.
40
-
41
- - **Merge** when the words run continuously and the picture has no reason to change. One 16-second take on a model that holds up is cheaper to *make* than two 8-second cuts and reads calmer.
42
- - **Split** when the words keep going and the picture should not. This is the strongest move in the format: one spoken line running unbroken while the visual hard-cuts mid-clause to a new world. Split at a word boundary mid-sentence and both rows carry the same sentence — Slates marks the second as continuing the first, so the script still reads as one line.
43
- - **Split** also when a line will not fit its cut. Slates flags only lines that cannot be read at *any* plausible pace (above the fastest read in a corpus of 71 real ads), so a flag is never a matter of taste — the chop is genuinely wrong. Splitting the line across two cuts or merging into a longer one both fix it.
44
-
45
- ## Multi-shot generations count as their cuts, not as one
46
-
47
- A model that puts three cuts inside one generation contributes **three** rows to the distribution. That is deliberate: counting generations would score a three-cut clip as a single wide shot and miss exactly the sequences this check exists to catch. Money is counted per generation; rhythm is counted per cut, and the header says which is which.
48
-
49
- ## What this cannot tell you
50
-
51
- It measures buckets, not taste. Seven varied shot sizes can still be seven boring shots, and a piece that scores perfectly can still be flat. It catches the one mechanical failure — everything starting to look the same — and nothing else.
52
-
53
- It also only sees what is filled in. A board where nobody wrote `shotSize` reports `other` for every cut and tells you nothing. That is correct rather than a gap: inferring a shot size from a prompt would be Slates guessing at your work, and the counts are trustworthy precisely because they are arithmetic on what you actually wrote.
24
+ This guide improves deliberate visual decisions. It does not measure taste, conversion or the quality of a finished performance. Use `slates-script-craft` for the argument, exchanges and setup/payoff that the picture supports.
@@ -1,84 +1,32 @@
1
1
  ---
2
2
  name: slates-storyboard-from-script
3
- description: Turn a script or treatment into a Slates storyboard with scenes and frames. Use when the user has a script, treatment, shot list, or scene-by-scene description and wants to materialize it as a Slates storyboard, optionally generating frame images per shot.
3
+ description: Put supplied script or treatment into an editable Slates document and bind requested passages to production shots. Preserve the words and structure; generate media only within the user's requested scope.
4
4
  ---
5
5
 
6
- # Storyboard from script — Slates workflow
6
+ # Script into editable production
7
7
 
8
- The user has a script, treatment, or shot list. You're turning it into a Slates storyboard with scene → frame structure, optionally generating images for each frame.
8
+ Read the existing document and its revision before writing. Preserve supplied words, speaker context, headings, non-spoken direction and any explicit shot list. A heading formats a document; creating a production scene is a separate choice. Paragraph count does not determine shot count.
9
9
 
10
- ## Workflow
10
+ ## Save the words once
11
11
 
12
- ### 1. Parse the script
13
- Read the user's script. Decide:
12
+ Use `slates_get_script_document` and `slates_update_script_document` for ordered, revision-checked text and structure edits. Scene strings own spoken words. Paragraph blocks hold offsets and marks; headings/directions own only their non-spoken text. Do not keep an independently editable master body beside the document.
14
13
 
15
- - **Scene count** — usually 1 scene per location/setting change. Don't fragment into one-frame scenes.
16
- - **Frames per scene** — match the shot list. Default is 3-6 frames per scene unless the script specifies more.
17
- - **Shot labels** — pull them from the script (e.g., "Wide", "Close-up", "Over-the-shoulder").
14
+ Create a board or scene only when needed for the requested destination. Use the current project unless the user asks for another. Writing a script needs no image, character record or generation.
18
15
 
19
- If the user hasn't named the storyboard, suggest one based on the project tone.
16
+ ## Bind production where wanted
20
17
 
21
- ### 2. Materialize the structure first (no generation yet)
22
- - `slates_create_storyboard` with the chosen name.
23
- - For each scene: `slates_add_scene` with a descriptive name and order.
24
- - For each shot: `slates_create_shot` with a *visual-only* prompt, the model, the params, and whatever character / environment / style references the project already holds. **Don't generate yet.**
18
+ Select an intended production passage and use the script-to-shot operation. It can make, attach, extend, split or merge according to the existing bindings. Read back the resulting shots and ranges. A silent shot is equally valid and needs no fabricated dialogue.
25
19
 
26
- 🚨 **A Shot needs no image, and that is the point.** `slates_add_frame` requires an `assetId`, so before Shots existed there was nowhere to put a planned shot until it had been paid for — the plan lived in chat and the user had to trust your memory of it. A Shot is a row: named, listed, priced, forkable, and readable back COMPOSED with `slates_get_shot` before a single credit is spent. Write the plan as Shots, not as sentences you will have to re-type later.
20
+ A new document-created recipe is script-driven: its prompt compiles from the active passage. Text with no speaker and no delivery goes to the model as written (most script text is action); a speaker, VO included, or a delivery note makes it quoted speech. Keep action, delivery, framing and references in their own controls. Do not write the dialogue a second time in a custom prompt. When the creator explicitly chooses a custom prompt, preserve its bytes and review alignment after script changes.
27
21
 
28
- 🚨 **A Shot files itself, so pass `sceneId` (or `frameId`) when you know where it goes.** Omit both and it lands in the scene the user has open, else the most recently updated storyboard's last scene, creating a storyboard named after the project if there is none. Nothing you save is ever unfiled — but naming the scene is how the board comes out in the order you wrote it.
22
+ Shots file through the existing filing service. Pass the scene or frame destination when known and use the returned shot codes. Keep recurring identities in existing Library references; a working speaker name does not require a placeholder character.
29
23
 
30
- 🚨 **Shots are addressed by CODE.** Every one comes back as `SHOT-A1`, `SHOT-A2` … per project, monotonic, never reused — the same vocabulary the gallery gives assets. Speak to the user in codes, and pass a code anywhere a `shotId` is taken. It is for pointing at a row THIS session, not for retrieval later: there is no shot search and no shot library, because a Shot is workspace state.
24
+ ## Review without imposing a format
31
25
 
32
- ### 2a. Write the SCRIPT COLUMNS as well as the prompt
26
+ Read composed requests, actual reference roles and the current quote. Explain only consequential decisions not already visible in the document or shot. Variety counts are suggestions: intentional repeated frames, continuing sentences and recurring cast may be exactly right. `slates-script-craft` covers passages and versions; `slates-shot-variety` covers deliberate visual rhythm.
33
27
 
34
- `slates_create_shot` takes the beat itself, not only the prompt: `line` (what is said, verbatim), `speaker` (a character id, a bare name, or `VO`), `delivery` (the parenthetical), `action` (what happens, screenplay-style), `prop`, `shotSize` and `camera`. All are optional, all are free text, and none of them is sent to a model — they are what the user READS and what the variety check COUNTS.
35
-
36
- ⚠️ **In this version you state dialogue TWICE, and that is deliberate rather than an oversight.** `line` is the readable script and the input to the fit check; the model only receives what is in the Shot's *prompt*, so the spoken words still go inside that prompt verbatim, with their delivery, in the body on the beat. **Write both in the same call** — then they agree at authoring time and can only drift if a human edits one side.
37
-
38
- A speaker who matches no saved character is a working state, not an error: it renders as plain text and groups its lines. Do not create a placeholder character to avoid it.
39
-
40
- Surface the planned structure back to the user as a tight summary — `slates_list_shots` gives you the count and the total in one call:
41
- > Storyboard "X" • 4 scenes • 12 shots • 340 credits to fire them all
42
- > Scene 1: Forest opening (3 shots)
43
- > Scene 2: Confrontation (4 shots)
44
- > ...
45
-
46
- **Surface a decision log alongside that summary.**
28
+ If generation is requested, follow `slates-cost-discipline` for the exact set. On an uncertain timeout inspect existing generation IDs before retrying. Preserve takes and inspect the landed results. Named cuts keep independent edits separate; writing alone does not require a cut, export or paid call.
47
29
 
48
30
  <!-- @inject:decision-log -->
49
- 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**:
50
-
51
- ```
52
- source phrase or declared default → what you wrote → what it resolves
53
- "in a diner" → warm, and the light is the reason → why the anchor was chosen, not what it is
54
- (no time of day) → late afternoon, low warm key → default; say the word and it changes
55
- ```
56
-
57
- 🚨 **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.
58
-
59
- **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.
60
-
61
- > ❌ **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.
31
+ Record production choices in the editable shot fields. Explain only consequential judgments the user did not specify and no field already records: for example, why a particular light or performance register supports the brief. Do not repeat the shot list in prose or turn this explanation into an approval gate. Follow the separate generation authorization policy before spending.
62
32
  <!-- @end:decision-log -->
63
-
64
- Turning a script into *visual* frame prompts means resolving things the script left open — what the room looks like, where the light comes from, how the shot is framed. Those are your decisions, not the writer's; name them.
65
-
66
- Ask: **"Generate frame images now? (y/N)"**
67
-
68
- ### 3. Generate frames if requested
69
- - `slates_generate_from_shots` with every image Shot's id and no `confirm` — it returns ONE itemised quote for the set plus the largest single item. Show that total, get an explicit OK, then re-call with `confirm: true`.
70
- - It fires the Shots one after another and BLOCKS until the last one lands, so it can outlast the HTTP timeout on a long set. If that happens the run is still going: poll `slates_get_shot` for each Shot's `generationIds` rather than re-firing, which double-spends.
71
- - Each result returns inline. Evaluate. If one is wrong, fix that Shot (`slates_update_shot`) and re-fire only it — never the set.
72
- - Bind the keeper to a frame with `slates_add_frame`, then `slates_update_shot` with `attachFrameId` so the recipe and the picture stay together.
73
-
74
- ### 4. Hand back
75
- - Total frames generated, total credits spent, storyboard id.
76
- - Suggest next steps: review via `slates_get_storyboard_with_frames` (it returns every scene, every Shot in order, and the variety distribution), or take the frames to motion — fork each image Shot with `slates_duplicate_shot` (`model:` the video model), give the copy its frame with `slates_update_shot` (`firstFrameAssetId`), then fire the set with `slates_generate_from_shots`. Assemble with `slates_add_clip_to_timeline` in story order and `slates_export_video`. The full frames-to-film pipeline (batch cost authorization, model mixing) is `slates-one-prompt-film`.
77
-
78
- ## Anti-patterns
79
-
80
- - **Don't** auto-generate without asking. Generation is the expensive step. Always confirm first.
81
- - **Don't** invent shot details the script doesn't mention. If the script says "they argue," ask what the shot looks like, don't fabricate "she clenches her fists in a wide shot."
82
- - **Don't** mix scene structure and frame generation in one pass — building the skeleton first lets the user catch errors before spending credits.
83
- - **Don't** write the plan into chat when a Shot can hold it. A Shot is the whole recipe AND the beat — line, speaker, action, prop, framing, references, model, params — and it is the only form of the plan the user can open, price, re-chop and re-fire without you.
84
- - **Don't** fire a set without reading its variety counts first. `slates_list_shots` returns them with every listing; if one shot size is the plurality or three cuts in a row share a camera move, fix the board before spending. `slates-shot-variety` is the craft behind that.
@@ -9,13 +9,13 @@ The style library (`slates_create_style` / the app's style ids) defines what eac
9
9
 
10
10
  ## The four ground rules (all styles)
11
11
 
12
- 1. **Reference beats adjectives.** A style reference image outperforms prose style instructions. If the user has an on-style image — or you can cheaply generate one — attach it and let the default `inherit` behavior match it. Prose styling is the fallback.
13
- 2. **Style lives in ONE slot per model:**
12
+ 1. **Assign references where they contribute.** Describe the scene with inline bindings, such as "the woman from image 1, lit and graded like image 2." Preserve an existing scene reference when its look should stay. A look-only reference may need light and exposure described for the new scene; prose and references can work together.
13
+ 2. **Use each model’s language, without imposing a fixed prompt template:**
14
14
  - **Nano Banana 2** — narrative prose; the style is the opening framing of the sentence ("A hand-drawn 2D anime cel illustration of…"), never a comma tag.
15
15
  - **Seedance 2.0** — the 8-part formula reserves "visual style" (slot 6) and "image quality" (slot 7). One clause each. Don't scatter style words through the action text.
16
16
  - **Kling V3** — prose scene direction; style rides the lighting/style tail of Scene → Subject → Action → Camera → Lighting/Style. Tag soup underperforms badly.
17
- 3. **Multi-shot consistency = the SAME style clause, byte-identical, in every shot's prompt** (plus shared references). Paraphrasing the style clause between shots invites drift.
18
- 4. **The styled start-frame is the cheapest reliable style lever for video.** Compose the styled frame in NB2 (cheap), hand it to Seedance/Kling image-to-video, and describe only what CHANGES (motion). Never re-describe the style in the i2v prompt — the frame already encodes it.
17
+ 3. **Keep the intended look consistent across shots.** Reuse relevant references and stable descriptions, adapting the wording to each scene.
18
+ 4. **A styled start frame is one video control.** Generate it with the image seat suited to the brief, then describe the motion. Preserve its look unless the user wants the light or grade to change.
19
19
 
20
20
  Never stack style buzzwords ("ARRI ALEXA, 35mm, film grain, depth-of-field mastery…"). One or two register tokens maximum — piles of specs dull the image.
21
21