@slatesvideo/shared 0.7.2 → 0.7.3

package/skills/slates-prompting-seedance-2-5.md

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-seedance-2-5
-description: How to prompt Seedance 2.5 and Seedance 2.5 Edit. Read before calling slates_generate_video with model seedance-2.5, or slates_edit_video with model seedance-2.5-edit. 2.5 is the DEFAULT video model (Eric, 2026-09-13) — against 2.0 it buys 30-second takes, 30 image references, audio-only references and INTEGER-SECOND TIMESTAMPS, and it gives up native 4K and costs more than 2.0 at every resolution they share. Timestamps are the one grammar difference that matters: 2.0 ignores them and answers only to shot numbers, 2.5 acts on them. Otherwise it shares 2.0's grammar (read slates-prompting-seedance for subject binding, camera and constraint vocabulary); this file covers what is different, plus the two hazards unique to 2.5 — the prompt-intent task classifier and the cost trap that comes with 30-second takes.
+description: "Prompt Seedance 2.5 generation (seedance-2.5) or edits (seedance-2.5-edit). Covers whole-second timing, shared Seedance craft, reference inputs, task-classifier hazards and long-take spend."
 ---
 
 # Seedance 2.5 — prompting
@@ -18,15 +18,15 @@ description: How to prompt Seedance 2.5 and Seedance 2.5 Edit. Read before calli
 **Card — Seedance 2.5.** Shares 2.0's grammar exactly (subject binding, camera vocabulary, externalised emotion, inline constraints — read `slates-prompting-seedance` for those). Two things are different, and both matter.
 
 **The five levers**
-1. **Timestamps work here** — integer seconds, and the model acts on them: `[0-4] she reads the letter. [4-9] she folds it and looks up.` 2.0 ignores exactly this syntax.
-2. **Length is the reason to be here** — takes up to 30 seconds, where 2.0 stops at 15. Write the beats as `[0-6]`, `[6-12]`, `[12-18]`; do not hope for them.
+1. **Timestamps work here**: integer seconds, and the model acts on them: `[0s-4s] she reads the letter. [4s-9s] she folds it and looks up.` 2.0 ignores exactly this syntax.
+2. **Length is the reason to be here**: takes up to 30 seconds, where 2.0 stops at 15. Write the beats as `[0s-6s]`, `[6s-12s]`, `[12s-18s]`; do not hope for them.
 3. **Up to 30 image references**, and a multi-view image can serve as ONE subject reference (up to 5 subjects). 2.0 cannot do either.
 4. **Audio-only references are accepted** without an image or video alongside — the only Seedance seat that takes one.
 5. **Keep the 2.0 discipline**: one camera move per beat (`slow track right`, `handheld follow`), physical action instead of stated emotion, and quality asked for in the image-quality slot vocabulary — `rich details`, `natural colors`, `cinematic texture`, `soft lighting`.
 
 **Examples**
-- `[0-6] Wide shot, <Subject_1>@<Image_1> crosses an empty car park toward a idling van, slow track right. [6-12] Medium, she stops as the driver's window comes down. [12-18] Close-up, she looks off past the lens and does not answer. Rich details, natural colors. Keep it subtitle-free.`
-- `[0-10] A single continuous handheld follow behind a courier climbing a fire escape, rain. [10-20] She reaches the landing, turns, and the city opens behind her. Cinematic texture, soft lighting.`
+- `[0s-6s] Wide shot, <Subject_1>@<Image_1> crosses an empty car park toward a idling van, slow track right. [6s-12s] Medium, she stops as the driver's window comes down. [12s-18s] Close-up, she looks off past the lens and does not answer. Rich details, natural colors. Keep it subtitle-free.`
+- `[0s-10s] A single continuous handheld follow behind a courier climbing a fire escape, rain. [10s-20s] She reaches the landing, turns, and the city opens behind her. Cinematic texture, soft lighting.`
 
 **Hard constraint:** it is the default AND the dearer seat, and it has NO 4K — 480p/720p/1080p only, dearer than 2.0 at every resolution they share. Long takes multiply cost linearly: quote a 30-second take before you fire it.
 <!-- @card:end -->
@@ -38,7 +38,7 @@ description: How to prompt Seedance 2.5 and Seedance 2.5 Edit. Read before calli
      estimate, and every submitted prompt is matched against it. Keep entries
      backticked and prose outside the backticks. -->
 <!-- /slates-only -->
-**Never use** (2.5 reclassifies the task and fails a fresh generation on these):
+**Never use** (with a reference video, 2.5 can reclassify the task and fail a fresh generation on these):
 - `edit`, `extend`, `continue the video`, `same video but` — they make the provider read a fresh generation as an edit
 - `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
 <!-- @banned:end -->
@@ -64,7 +64,7 @@ So 2.5 does not replace 2.0; it sits beside it, and you pay for what it buys:
 | Resolution | 480p / 720p / 1080p / **native 4K** | 480p / 720p / 1080p — **no 4K** |
 | Price at 720p (faceless) | **$0.15/s** | $0.231/s |
 | Length | 4–15s | **4–30s in one take** |
-| Reference budget | 15 (9 image + 3 video + 3 audio) | **50 (30 image + 10 video + 10 audio)** |
+| Reference budget | 12 files total (9 image / 3 video / 3 audio caps) | **50 (30 image + 10 video + 10 audio)** |
 | Combined reference video/audio | ≤15s | **≤30s** |
 | Audio-only reference | ✗ (needs an image or video alongside) | **✓** |
 | **Timestamps in the prompt** | **✗ — ignored; shot numbers only** | **✓ — integer seconds, acted on** |
@@ -94,19 +94,19 @@ The trigger words are ordinary English:
 | **video edit** | `edit video` · `add` · `insert` · `remove` · `delete` · `modify` · `replace` · `change to` |
 | **video extend** | `extend forward` · `extend backward` · `continue` · `continue from` · `extend the story` |
 
-So a perfectly legitimate reference-to-video prompt — *"a wide shot of the workshop, **remove** the
+So a perfectly legitimate prompt with a reference video, *"a wide shot of the workshop, **remove** the
 tripod from frame"* — gets classified as an edit and fails on constraints it never set.
 
 **What to do:**
 
-1. **If you mean to edit an existing clip, say so with the MODEL, not the sentence.** Call
-   `slates_edit_video` with `model: 'seedance-2.5-edit'`. That routes to a dedicated
-   task-typed endpoint and the classifier never has to guess.
+1. **If you mean to edit an existing clip, choose its dedicated video-edit endpoint.** The
+   task-typed endpoint removes the classifier's ambiguity. <!-- slates-only -->In Slates, call
+   `slates_edit_video` with `model: 'seedance-2.5-edit'`.<!-- /slates-only -->
 2. **If you mean a fresh shot, describe the finished frame rather than an instruction to change
    one.** Not *"remove the tripod"* → *"the workshop bench, clear and uncluttered"*. Not
    *"add rain"* → *"heavy rain falling through the streetlight"*. This is better prompting anyway:
    the model renders what you describe, it does not take edits to an imagined draft.
-3. The trigger only fires when **references are attached**. A plain text-to-video prompt is safe
+3. The trigger needs **a reference video plus edit or extend intent**. Image references alone do not trigger it. A plain text-to-video prompt is safe
    however it is worded.
 
 **Slates will warn you, and it will never rewrite your prompt.** When a 2.5 reference generation's
@@ -142,8 +142,10 @@ real-face route has spent 71% of their welcome grant on one clip; **on the real-
 
 **Discipline:**
 
+<!-- slates-only -->
 - **Always quote with `slates_estimate_generation_cost` before a take over ~10 seconds,** and say
   the number out loud before generating.
+<!-- /slates-only -->
 - **Find the shot at short LENGTH, not at low resolution.** Length is what moves the price, so cut
   seconds while you are still exploring — 4–8s — and stay at the resolution you actually want.
   **A 480p pass does not de-risk a 720p or 1080p render.** Generation is stochastic: the higher-
@@ -153,7 +155,7 @@ real-face route has spent 71% of their welcome grant on one clip; **on the real-
 - **Length is a creative decision, not a default.** 30 seconds is available; it is rarely the right
   answer for a single shot. Multi-shot storyboards inside one 30s generation are what the length is
   actually for.
-- Read `slates-cost-discipline` — all of it applies, more sharply here.
+<!-- slates-only -->- Read `slates-cost-discipline` — all of it applies, more sharply here.<!-- /slates-only -->
 
 ---
 
@@ -192,8 +194,8 @@ pacing you are happy to leave to the model, timestamps when a beat has to land a
   from 4-6 seconds in Video 1, and leave the rest of the content unchanged."* Without a range, a
   whole-clip instruction is applied to the whole clip.
 
-Do **not** carry this back to 2.0, and do not carry Veo's `[00:00-00:02]` bracket syntax into
-either — 2.0 ignores time entirely, and the cross-model syntax swap is its own known failure.
+Do **not** carry this back to 2.0, and do not write `[00:00-00:02]` minute-second brackets (another
+vendor's syntax) into either — 2.0 ignores time entirely, and the cross-model syntax swap is its own known failure.
 <!-- @end:seedance-25-timestamps -->
 
 ---
@@ -235,7 +237,8 @@ billing dimension** on any Seedance route: audio is included.
 ### Video references
 
 Up to 10 clips, ≤30s combined (2.0: 3 clips, ≤15s). A reference VIDEO switches the cost key to
-`seedance-2.5*-vref-{res}-{T}s`, where **T = Σ input seconds + output seconds** — the sum is across
+`seedance-2.5*-vref-{res}-{T}s`, where **T = Σ input seconds + output seconds** on faceless and real-face routes;
+on the AI-face route, **T = max(Σ input seconds, output seconds) + output seconds** on both 2.0 and 2.5. The sum is across
 **every** clip attached, not just the longest. Three 6-second references on a 12-second output bills
 30 seconds, not 12 and not 18. Quote before confirming.
 
@@ -292,17 +295,22 @@ the citation, not a fallback — *"use her face and wardrobe from image 1, not i
 background"* is a stronger instruction than naming the positive alone, because an unscoped reference
 brings its whole frame with it.
 
-🚨 **The vendor writes `@Image 1`; Slates writes `image 1`, and that difference is deliberate.**
-BytePlus's API tutorial says *"Use `@Image 1`, `@Video 1`, and `@Audio 1`"*, while its own 2.5 prompt
-guide states the bare form (`Image 1 / Video 1 / Audio 1`) in the one normative sentence it has.
-**Two first-party docs, two forms** — the disagreement is recorded, not resolved, in
-`second-brain/business/projects/slates/research/model-prompting-research.md`. What settles it FOR US
-is neither: **`@` is a reference-token sigil in the Slates prompt composer, and an unresolved one is
-silently deleted from the prompt before it is sent.** Typing `@Image 1` here does not produce
-`@Image 1`, it produces nothing. The bare form is confirmed working on both models. Never hand-type
-the sigil.
+**BytePlus documents disagree on reference sigils.** Its API tutorial says *"Use `@Image 1`,
+`@Video 1`, and `@Audio 1`"*, while its 2.5 prompt guide uses the bare form
+(`Image 1 / Video 1 / Audio 1`) in its normative sentence. Both are first-party sources; the
+bare form is confirmed working on both Seedance models. Use the syntax accepted by the endpoint
+you are calling, and preserve each asset's role and scope.
 
-## Seedance 2.5 Edit (`slates_edit_video`, `model: 'seedance-2.5-edit'`)
+<!-- slates-only -->
+The disagreement is recorded in
+`second-brain/business/projects/slates/research/model-prompting-research.md`. Slates composes
+resolved reference tokens for the chosen model and now preserves unresolved sigils verbatim.
+The earlier composer silently deleted unresolved `@Image 1` tokens; that receipt explained the
+old bare-form workaround, and the fix removes its blanket prohibition. Prefer actual bound
+references when available so the composer supplies the canonical citation.
+<!-- /slates-only -->
+
+## Seedance 2.5 Edit (<!-- slates-only -->`slates_edit_video`, <!-- /slates-only -->`model: 'seedance-2.5-edit'`)
 
 Its own picker row and its own op call, deliberately: the task type is **the model you chose**,
 never something inferred from your sentence.
@@ -323,14 +331,14 @@ Kling O3 Edit is the one that takes element and style reference images.
   will need more attempts.
 - **The aspect ratio follows the source clip too.** No ratio control; the frame is the clip's frame.
 - **480p, 720p or 1080p output**, native audio — and an edit bills the video-reference tier ×2,
-  so 1080p on this row is the most expensive second in the app. Quote it.
+  so quote the 1080p edit before confirming.
 - **Prompt and source clip only** on this op. The MODEL takes reference images on an edit
   (ByteDance recommends 1–5 — *"replace the man in dark clothing in @Video 1 with @Image 2"*);
   **Slates has not wired that path**, so today an edit that must lock an identity from a photo
   goes to Kling O3 Edit. Constraint of our build, not of the model — worth revisiting.
-- **An edit bills roughly DOUBLE a plain 2.5 generation of the same length**, because every provider
-  charges an edit on input + output seconds. Read the confirm gate's number; do not reason from the
-  generation rate.
+- **An edit costs about 1.2x a plain 2.5 generation of the same length**: every Seedance provider
+  charges an edit on input + output seconds, at the reduced video-reference rate. Read the confirm
+  gate's number; do not reason from the generation rate.
 - **Set `seedanceFace: true` when a character's face is visible in the clip.** The faceless provider
   blocks faces outright — this is not a price optimisation, it is whether the job runs at all.
 - **There is no consented-real-face route for editing.** Real-person footage that the AI-face route
@@ -362,12 +370,14 @@ not a lip-sync job. Bill it like any other edit — on the source clip's length.
 
 ## Faces, and what does NOT change
 
+<!-- slates-only -->
 The three-tier face routing is identical to 2.0 — faceless → default route, an AI character's face →
 `seedanceFace: true` (the relaxed provider, a real cost premium), a real person's photo → the
 consent-gated real-person route after a `[REAL_FACE_DETECTED]` rejection, with `realFaceConsent: true`
 set **only** after the user explicitly confirms they hold the rights to the likeness. The full rules,
 including why the real-vs-AI call is the provider's and not yours, are in
 `slates-prompting-seedance`.
+<!-- /slates-only -->
 
 Also unchanged, and worth restating because 2.5's length makes each one more expensive to get wrong:
 

package/skills/slates-prompting-seedance.md

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-seedance
-description: How to prompt Seedance 2.0 (ByteDance video model). Read before calling slates_generate_video with model seedance-2. Seedance 2.0 structures multi-beat prompts as a "Shot 1 / Shot 2 / Shot 3" storyboard against an 8-slot advanced formula — never per-second time stamps, which 2.0 does not respond to (Seedance 2.5 does; see slates-prompting-seedance-2-5). Its syntax differs from Kling, Veo and the image models; don't cross-pollinate (in particular, no lens / aperture / film-stock vocabulary).
+description: "Prompt Seedance 2.0 (seedance-2), and retrieve the shared Seedance craft used by 2.5. Covers subject binding, shot-number storyboards, camera moves, physical action and inline constraints."
 ---
 
 # Seedance 2.0 — prompting
@@ -250,13 +250,13 @@ using the voice timbre from audio 1. Preserve his identity, appearance and outfi
 
 ### Motion transfer & lip-sync recipes (reference video / audio)
 
-These aren't separate Seedance features — they're prompting strategies over reference media.<!-- slates-only --> The Slates tools (`slates_generate_motion_transfer` / `slates_generate_lip_sync` with the seedance engine) compose them for you. When driving them by hand through `slates_generate_video`:<!-- /slates-only -->
+These aren't separate Seedance features; they're prompting strategies over reference media.<!-- slates-only --> Run `slates_generate_video` with the clip as a video reference and write the motion or dialogue into the prompt:<!-- /slates-only -->
 
 - **Motion transfer:** subject image as a reference + the driving clip<!-- slates-only --> via `videoReferenceAssetId`<!-- /slates-only --> (2–15s) + `The character from image 1 performs the exact motion, choreography, and camera movement from video 1. Preserve the character's identity, appearance, and outfit.`
 - **Lip-sync / dialogue:** write the line in the prompt — `The person in video 1 says: "…"` — with audio generation on (always on in Slates). A **video** source's own voice is cloned natively; an **audio** reference (≤15s) drives speech from an existing recording: `…speaks the dialogue from audio 1 with accurate lip sync.`
 - **Voice + face from one clip (the talking-head recipe):** ONE unedited 2–15s clip of the person speaking (clear voice, no music, no cuts) as the video reference + prompt with the new script → their likeness AND voice deliver the new line.
 <!-- slates-only -->
-- **Billing:** a reference VIDEO switches the cost key to `seedance-2*-vref-{res}-{T}s` where T = clip seconds + output seconds — quote before confirming. Audio references are free (audio is included on every route).
+- **Billing:** a reference VIDEO switches the cost key to `seedance-2*-vref-{res}-{T}s` where T = combined clip seconds + output seconds on faceless and real-face routes. The AI-face route bills max(combined input, output) + output on both 2.0 and 2.5; quote before confirming. Audio references are free (audio is included on every route).
 <!-- /slates-only -->
 
 <!-- slates-only -->
@@ -266,7 +266,7 @@ Seedance routes through **three tiers** depending on the face in the reference,
 
 - **Faceless / object / environment refs → default route (cheapest).** Leave `seedanceFace` off.
 - **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.
-- **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.
+- **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`, about 1.4× the AI-face rate, about 2× faceless; quote via `slates_estimate_generation_cost`), then retry with `seedanceRealFace: true` + `realFaceConsent: true`. Never set `realFaceConsent` without the user's explicit confirmation.
 
 Rules:
 - **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.

package/skills/slates-prompting-seedream-5-lite.md

@@ -1,6 +1,6 @@
 ---
 name: slates-prompting-seedream-5-lite
-description: How to prompt Seedream 5 Lite (ByteDance image model — the cheap volume option in Slates). Read before calling slates_generate_image with model seedream-5-lite, or slates_edit_image with editModel seedream-5-lite. Seedream front-loads attention, likes 30-100 focused words, and takes quoted strings for in-image text.
+description: "Prompt or edit images with Seedream 5 Lite (seedream-5-lite). Use with slates_generate_image or slates_edit_image on this model; covers attention order, focused descriptions, layout and quoted text."
 ---
 
 # Seedream 5 Lite — prompting
@@ -15,7 +15,7 @@ description: How to prompt Seedream 5 Lite (ByteDance image model — the cheap
      Keep it under 2,400 characters (the build fails above that) and keep the
      rationale, the receipts and the worked examples in the body below. -->
 <!-- /slates-only -->
-**Card — Seedream 5 Lite.** The cheap volume seat: flat-priced at every resolution, which makes it the right default for storyboard passes, variant grids and look-dev. Structure, most important first: `Subject + Style + Composition + Lighting/Atmosphere + Technical`.
+**Card — Seedream 5 Lite.** The cheap volume seat: flat-priced at every resolution, which makes it useful for storyboard passes, variant grids and look-dev when volume is the requirement. Structure, most important first: `Subject + Style + Composition + Lighting/Atmosphere + Technical`.
 
 **The five levers**
 1. **Lead with the subject.** Earlier words weigh more; close with the camera and technical detail.
@@ -35,7 +35,7 @@ Bind references inline. A scene reference owns the grade; for a look-only refere
 <!-- slates-only -->Use `slates-cinematic-look` with a technique ID or section query for more.<!-- /slates-only -->
 <!-- @end:cinematic-card -->
 
-**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.
+**Selection:** it is a volume option. Re-render a keeper on another image model only when an observed shortfall or the delivery brief justifies it; use the current catalogue for that choice.
 <!-- @card:end -->
 
 <!-- @banned:start -->
@@ -54,7 +54,7 @@ Bind references inline. A scene reference owns the grade; for a look-only refere
 - `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.`
 - `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.`
 
-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.
+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 flat-priced seat in Slates, which makes it a useful choice 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.
 
 **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.
 
@@ -101,7 +101,7 @@ Via `slates_edit_image` with `editModel: seedream-5-lite`. Seedream edits respon
 Change the bag to brown leather. Keep the person's face, pose, and the room unchanged.
 ```
 
-Note: Seedream edits in Slates ignore extra `referenceAssetIds` — that path is Nano Banana 2 only.
+Seedream edits accept extra `referenceAssetIds` within the current edit-reference cap, with the source occupying the first image slot. Read the tool schema for the cap. An older desktop without that capability refuses the request: update the desktop rather than claiming the extra references were sent.
 
 ## Common failure modes + fixes
 
@@ -115,7 +115,7 @@ Note: Seedream edits in Slates ignore extra `referenceAssetIds` — that path is
 
 ## Iterate cheap, lock expensive
 
-Flat pricing makes Seedream the iterate-fast model: run the 3-strike loop here (draft → evaluate inline → one specific delta → regenerate), and only re-render the winning composition on a pricier model if the project's hero shot demands it. Cost rules live in `slates-cost-discipline` — the batch-authorization pattern applies when generating variant grids.
+Flat pricing supports iteration: draft, evaluate inline, diagnose one specific delta, then generate only within the authorized set. Repeated failures trigger diagnosis rather than unchanged re-rolls; only re-render the winning composition on another model when the delivery requires it. Cost rules live in `slates-cost-discipline` — the batch-authorization pattern applies when generating variant grids.
 
 ## Sources
 

package/skills/slates-restyle-from-blocking.md

@@ -1,6 +1,6 @@
 ---
 name: slates-restyle-from-blocking
-description: Render one blocking pass as several different visual worlds — live action, 2.5D painted, 2D ink, toybox — matching cut for cut. Use when a client needs style options, when someone wants to see the same edit in another look, or when an approved edit needs a new treatment without re-blocking.
+description: "Generate different visual treatments from one blocking pass while preserving its camera, cuts and choreography. Use when comparing looks or restyling an approved structure without rebuilding it."
 ---
 
 # Restyle — one edit, many worlds
@@ -27,7 +27,7 @@ You need a blocking clip whose structure you are happy with, and a finished prom
 Copy these across every style **verbatim**. Changing them is what desynchronises the outputs:
 
 - The blocking reference's own contract — that it is the master for all movement, the placement-only clause, the tie-break clause, the disambiguation clause
-- The shot count and every timestamp
+- The shot count and measured cut boundaries; translate prompt timestamps once to the chosen model's syntax and keep that translation across treatments
 - Every shot's camera position, angle, framing and cut point
 - Screen direction and seating
 - The `HOLD FOR THE FULL TIMELINE` block

package/skills/slates-script-craft.md

@@ -1,6 +1,6 @@
 ---
 name: slates-script-craft
-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.
+description: "Write or revise script passages, openings, bridges and saved variations while preserving voice, format and fixed material. Use for writing within a production brief or a writing-only request."
 ---
 
 # Script craft and variations

package/skills/slates-shot-variety.md

@@ -1,6 +1,6 @@
 ---
 name: slates-shot-variety
-description: Diagnose unintended visual sameness across a shot sequence while preserving deliberate repetition, continuing performance and the user's chosen format.
+description: "Shape visual rhythm across a shot sequence or diagnose unintended sameness. Use while planning or reviewing cuts; preserve deliberate repetition, continuing performance and the chosen format."
 ---
 
 # Visual rhythm across a sequence

package/skills/slates-storyboard-from-script.md

@@ -1,6 +1,6 @@
 ---
 name: slates-storyboard-from-script
-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.
+description: "Save a supplied script or treatment as an editable Slates document and bind production passages to shots. Use when preparing a storyboard while preserving the words, structure and requested scope."
 ---
 
 # Script into editable production

package/skills/slates-style-prompting.md

@@ -1,54 +1,56 @@
----
-name: slates-style-prompting
-description: Use when the user asks for a visual style ("make it anime", "painterly look", "like a Pixar film"), or when a style has to hold across several shots. Covers how photoreal, anime, painterly and 3d-render are prompted DIFFERENTLY per model, and the style-routing recipe (reference-first, styled start-frame → i2v).
----
-
-# Per-style prompting (photoreal · anime · painterly · 3d-render)
-
-The style library (`slates_create_style` / the app's style ids) defines what each style IS. This guide is how to PROMPT each style per model. Derived from `research/style-prompting-research.md` (second-brain) — claims marked *(hypothesis)* are untested; don't present them to users as fact.
-
-## The four ground rules (all styles)
-
-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.
-2. **Use each model’s language, without imposing a fixed prompt template:**
-   - **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.
-   - **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.
-   - **Kling V3** — prose scene direction; style rides the lighting/style tail of Scene → Subject → Action → Camera → Lighting/Style. Tag soup underperforms badly.
-3. **Keep the intended look consistent across shots.** Reuse relevant references and stable descriptions, adapting the wording to each scene.
-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.
-
-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.
-
-## Photoreal
-
-- **NB2:** never the literal word "photorealistic". Describe *a real photograph*: natural skin texture and imperfection, motivated lighting, one lens/film register ("shot on a 50mm, soft window light"). Photographic composition terms: wide-angle / macro / low-angle.
-- **Seedance:** put "sharp focus, natural color, high detail" in the image-quality slot and always include a lighting clause. Keep motion slow and coherent — fast/burst action is the #1 quality killer and reads most fake in photoreal.
-- **Kling:** the photoreal-PEOPLE lane — convincing acting, dialogue, lip-sync. It breaks on close-up hands, fine fluids, and crowds beyond ~5 faces: route those beats to Seedance or reframe.
-- **Faces on Seedance:** photoreal humans trigger the face-tier routing (AI face vs consented real face — see slates-prompting-seedance §Faces). Set the face flags honestly; never skip them to save credits.
-
-## Anime
-
-- **NB2:** open with the medium — "A hand-drawn 2D anime cel illustration of…" — then normal narrative Subject/Setting/Action. Clean line art, flat-shaded color, expressive eyes. NB2 has no negative prompt: phrase exclusions positively ("flat cel shading with uniform focus", not "no depth of field").
-- **Seedance:** visual-style slot = "2D anime style, clean line art, flat cel shading". The slow/coherent-motion preference still applies — burst sakuga actions are the same instability trap as in photoreal.
-- **Kling:** weakest anime lane (its strength is live-action-like acting); expect style drift on long prose-only shots. Prefer ground rule 4: NB2 anime start-frame → i2v with a motion-only prompt. *(hypothesis: refs hold Kling's anime better than prose — verify before promising.)*
-- Anime faces drift under multiple references faster than photoreal — the named-entity two-sheet doctrine applies unchanged.
-
-## Painterly
-
-- **NB2:** medium + technique in the style framing: "digital concept-art painting, visible brushwork, painted edges". At most ONE school/era register ("classic gouache illustration") — a register, not an artist-name pile.
-- **Video:** the least-supported style lane. Use ground rule 4 (painterly NB2 frame → i2v, motion-only prompt) and expect some cleanup of painterliness over the clip *(hypothesis — set user expectations, don't promise a perfectly painterly clip)*.
-- Camera language still applies — painterly ≠ static; "slow push-in" works the same.
-
-## 3D render
-
-- **NB2:** name the lineage register in the style framing: "stylized 3D render, soft global illumination, subsurface skin". Lighting vocabulary (GI, rim light) is unusually load-bearing for the 3D read.
-- **Seedance:** the physics/effects lane flatters 3D content — visual-style slot "stylized 3D animation", image-quality slot "clean render, high detail".
-- **Kling:** same start-frame preference as anime.
-- *(hypothesis)* An engine token ("Unreal Engine 5 render") may help NB2; if used, ONE token, style slot only — never on Seedance where spec-stuffing hurts.
-
-## Routing recipe (what to actually do)
-
-1. Style reference available → attach it, rely on inherit. Done.
-2. No reference, image request → styled NB2 prose per the section above.
-3. No reference, video request → NB2 styled start-frame first, then i2v with motion-only prompt. Direct styled text-to-video is the fallback when a start frame doesn't fit (e.g. dialogue-first Kling shots).
-4. Multi-shot run → byte-identical style clause per shot + shared references.
+---
+name: slates-style-prompting
+description: "Translate a visual-style brief into model-specific image or video direction and maintain the look across shots. Covers photoreal, anime, painterly and 3D styles, references and optional start-frame control."
+---
+
+# Per-style prompting (photoreal · anime · painterly · 3d-render)
+
+The style library (`slates_create_style` / the app's style ids) defines what each style IS. This guide is how to PROMPT each style per model. Derived from `research/style-prompting-research.md` (second-brain) — claims marked *(hypothesis)* are untested; don't present them to users as fact.
+
+## The four ground rules (all styles)
+
+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.
+2. **Use each model’s language, without imposing a fixed prompt template:**
+   - **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.
+   - **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.
+   - **Kling V3** — prose scene direction; style rides the lighting/style tail of Scene → Subject → Action → Camera → Lighting/Style. Tag soup underperforms badly.
+3. **Keep the intended look consistent across shots.** Reuse relevant references and stable descriptions, adapting the wording to each scene.
+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.
+
+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.
+
+## Photoreal
+
+- **NB2:** never the literal word "photorealistic". Describe *a real photograph*: natural skin texture and imperfection, motivated lighting, one lens/film register ("shot on a 50mm, soft window light"). Photographic composition terms: wide-angle / macro / low-angle.
+- **Seedance:** put "sharp focus, natural color, high detail" in the image-quality slot and always include a lighting clause. Keep motion slow and coherent — fast/burst action is the #1 quality killer and reads most fake in photoreal.
+- **Kling:** the photoreal-PEOPLE lane — convincing acting, dialogue, lip-sync. It breaks on close-up hands, fine fluids, and crowds beyond ~5 faces: route those beats to Seedance or reframe.
+- **Faces on Seedance:** photoreal humans trigger the face-tier routing (AI face vs consented real face — see slates-prompting-seedance §Faces). Set the face flags honestly; never skip them to save credits.
+
+## Anime
+
+- **NB2:** open with the medium — "A hand-drawn 2D anime cel illustration of…" — then normal narrative Subject/Setting/Action. Clean line art, flat-shaded color, expressive eyes. NB2 has no negative prompt: phrase exclusions positively ("flat cel shading with uniform focus", not "no depth of field").
+- **Seedance:** visual-style slot = "2D anime style, clean line art, flat cel shading". The slow/coherent-motion preference still applies — burst sakuga actions are the same instability trap as in photoreal.
+- **Kling:** weakest anime lane (its strength is live-action-like acting); expect style drift on long prose-only shots. Prefer ground rule 4: NB2 anime start-frame → i2v with a motion-only prompt. *(hypothesis: refs hold Kling's anime better than prose — verify before promising.)*
+- Anime faces drift under multiple references faster than photoreal; the named-entity one-sheet doctrine applies unchanged.
+
+## Painterly
+
+- **NB2:** medium + technique in the style framing: "digital concept-art painting, visible brushwork, painted edges". At most ONE school/era register ("classic gouache illustration") — a register, not an artist-name pile.
+- **Video:** the least-supported style lane. Use ground rule 4 (painterly NB2 frame → i2v, motion-only prompt) and expect some cleanup of painterliness over the clip *(hypothesis — set user expectations, don't promise a perfectly painterly clip)*.
+- Camera language still applies — painterly ≠ static; "slow push-in" works the same.
+
+## 3D render
+
+- **NB2:** name the lineage register in the style framing: "stylized 3D render, soft global illumination, subsurface skin". Lighting vocabulary (GI, rim light) is unusually load-bearing for the 3D read.
+- **Seedance:** the physics/effects lane flatters 3D content — visual-style slot "stylized 3D animation", image-quality slot "clean render, high detail".
+- **Kling:** same start-frame preference as anime.
+- *(hypothesis)* An engine token ("Unreal Engine 5 render") may help NB2; if used, ONE token, style slot only — never on Seedance where spec-stuffing hurts.
+
+## Routing recipe (what to actually do)
+
+1. Style reference available → inspect it, bind its look role, and describe any light or exposure needed in the new scene.
+2. Image request → use the current image default unless the brief supplies a reason for another seat; load that model's craft. The NB2 examples above apply when NB2 is selected, not to every image model.
+3. Video request → choose a styled start frame when composition, exact text or an approved look must hold. Use the image seat suited to that job, then the chosen video model's motion and sound grammar. Direct styled text-to-video is also valid when it serves the brief; an image pass is not mandatory.
+4. Multi-shot run → retain stable style references and descriptors, adapting action, light and model-specific wording to each scene.
+
+`slates-model-selection` and the current catalogue own routing. These style techniques supply craft after the production choice; no user needs to select a skill or workflow.

package/skills/slates-ugc-influencer-ad.md

@@ -1,6 +1,6 @@
 ---
 name: slates-ugc-influencer-ad
-description: Direct a creator-style spoken performance when the brief calls for an ordinary camera-facing person or exchange. Use for performance and phone-camera craft, not as a universal rule for ads.
+description: "Direct a creator-style spoken ad when the brief calls for a camera-facing person or exchange. Covers activity, performance, phone-camera handling, speech, interaction and sound."
 ---
 
 # Creator-style performance