@slatesvideo/shared 0.5.5 → 0.5.6

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

@@ -27,12 +27,14 @@ Slates generates **one identity sheet per character**, bound as the character's
 | Panel | What it carries |
 |---|---|
 | **Chest-up portrait, three-quarter angle, largest panel (~25–30% of the sheet)** | The face. **This is the only place the model reads facial identity from** — every detail it will ever know comes from those pixels, so it gets the resolution. Off-frontal, never dead-on: an angled head reads its volume instantly. |
-| **Full-body front, relaxed A-pose — framed from the collarbone down, head not shown** | Build, proportion, wardrobe. Headless on purpose: a front-facing body panel renders a ~40px face that can't match the portrait's, so the sheet would carry two competing identities and the model averages them. |
+| **Full-body front, relaxed A-pose — cropped at the collarbone, just the face cropped out** | Build, proportion, wardrobe. The face is cropped off on purpose: a front-facing body panel renders a ~40px face that can't match the portrait's, so the sheet would carry two competing identities and the model averages them. **Only the face** — neck, arms and hands render as skin. |
 | **Full-body back, head and hair visible** | Hair fall and the back of the outfit — the only panel where either reads. Keeps its head because there's no face to compete with. |
 
 The rule is **kill every competing rendering of the FACE, not every head** — which is why exactly one body panel is headless.
 
-On a deep neutral-grey plate (`#3a3a3c`), flat and shadowless, with catchlights in the eyes, irises never crushed to black, surface texture at the medium's own natural level of detail, broken symmetry, and no over-clean 3D-game-model look. Quadrupeds and non-bipedal characters are carved out — natural standing stance, head shown on both body panels.
+On a deep neutral-grey plate (hex `3a3a3c`, emitted without the `#` — see the sigil warning in Don'ts), flat and shadowless, with catchlights in the eyes, irises never crushed to black, surface texture at the medium's own natural level of detail, broken symmetry, and no over-clean 3D-game-model look. Expression is **a slight natural smile with the teeth just visible** — a closed mouth carries no dental information, so every downstream smiling shot invents teeth, and teeth are person-specific.
+
+**Two carve-outs, scoped differently on purpose.** Non-human characters get a natural neutral expression instead of a smile — that one is scoped by *having a human mouth*, so a bipedal robot or humanoid alien is covered. Quadrupeds and non-bipedal characters get a natural standing stance with the head shown on both body panels — that one is *anatomical*. **Both are conditionals the image model evaluates against your reference; neither is a code branch, because the op has no character-kind input.**
 
 **The sheet inherits the source's medium** — photo, anime, illustration, painterly, 3D render — unless the user explicitly asks for a transform. None of the craft clauses above override that: they ask for *readable* eyes and *material-looking* surfaces within whatever medium the character is in, not for photorealism.
 
@@ -53,7 +55,8 @@ If text only: generate from prompt-only — less consistent, so warn the user.
 - Default to Nano Banana 2 at 2K. **Never 4K** — no identity gain at sheet scale, wasted spend.
 - When the result returns inline, **evaluate it before binding**:
   - Is the portrait clearly the largest panel, and is it off-frontal?
-  - **Is the front body panel cleanly headless** — an empty collar with the garment holding its shape, no partial face, no floating jaw, no smeared neck stump? A botched crop is worse than no crop.
+  - **Is the front body panel cleanly headless** — an empty collar above a normally rendered body, no partial face, no floating jaw, no smeared neck stump? A botched crop is worse than no crop.
+  - **Is the body still there?** Neck, forearms and hands rendered as skin, not an empty outfit floating on nothing. A hollow garment means the invisible-mannequin genre ran unbounded.
   - Do the body panels read as the same build, wardrobe and hair as the portrait?
   - Catchlights present, irises readable rather than black holes?
   - Is it in the source's medium, and does it read as *that* medium done well — or has it drifted toward the over-clean game-model look?
@@ -73,6 +76,8 @@ Critically, the app injects **no** wardrobe, expression, or lighting directive.
 - **Don't** create a second character image. One canonical identity is what the storyboard pipeline reads.
 - **Don't** skip binding. An unbound asset doesn't help downstream.
 - **Don't** invent character details. Stick to what's in the reference image and the user's description.
-- **Don't** describe the headless front panel as removal or decapitation — in `userNotes` or any hand-written variant. The template asks for it as *framing* — "cropped at the collarbone, head not shown, invisible-mannequin presentation" — which is a standard e-commerce genre with deep training data. Removal phrasing is untested and invites a refusal.
+- **Don't** describe the front panel's crop as an absent head — in `userNotes` or any hand-written variant. The template asks for it as *framing*: **"cropped at the collarbone, an invisible-mannequin presentation with just the face cropped out"**, a standard e-commerce genre with deep training data. **"the head not shown" is a hard 422 on gpt-image-2** — fal returns `content_policy_violation` with `loc: ["body","prompt"]`, so the text is rejected before any image is read, because an anatomical absence reads as gore to OpenAI's classifier. It passed NB2, which is why the original receipt looked safe: **it was model-scoped.** State an exclusion as a framing choice, never as a missing body part.
+- **Don't** invoke the invisible-mannequin genre without bounding it to the face. **"an invisible-mannequin presentation where the clothing holds its own shape" removed all the skin** — no neck, no hands, no forearms, a garment floating on nothing — because that *is* the e-commerce genre in full: an empty outfit. **"with just the face cropped out"** keeps the anchor and bounds it. Generalises: a genre anchor imports the whole genre, so name what STAYS, not only what goes.
+- **Don't** put `#` or `@` anywhere in prompt text. Both are reference-token sigils in the desktop prompt composer and an unresolved one is **silently deleted** — no error, no log, just missing words. `#3a3a3c` reached fal as `background ()` on a real 2026-07-30 request, meaning the plate value had never been delivered to any model since the composer shipped. Write hex values bare.
 - **Don't** use 4K — wastes credits, no quality gain at sheet scale.
 - **Don't** feed a multi-view sheet into a Seedance shot that has **several characters in frame** without binding each character to its image and appending the anti-twin constraint — ByteDance documents multi-view assets as a cause of duplicate characters. See `reference-seedance.md`.

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

@@ -8,7 +8,7 @@
     },
     {
       "path": "skills/slates-character-identity.md",
-      "sha256": "cc0387b21c83bbf0840524e5b124db889d5ee584cbacd19ffaf5fd2ec132bd20"
+      "sha256": "52191db058ada8096297e97958268548b352a5f81739d1bfd01da340867f2d35"
     },
     {
       "path": "skills/slates-prompting-seedance.md",
@@ -28,7 +28,7 @@
     },
     {
       "path": "src/prompts/model-facts.ts",
-      "sha256": "3bdc599838204334e0dcbdb076c1d866b5eba2eed17c5de8f5077cfaa5f6fe0b"
+      "sha256": "f3ac5db676a96d1dbdbe7aaa364ca5df3c4739637ef7d61840ad10a585931a62"
     }
   ],
   "outputs": [
@@ -39,8 +39,8 @@
     },
     {
       "path": "reference-character.md",
-      "bytes": 7950,
-      "sha256": "3f9af66752811a355225db039aeda9c724b685ede071900c51e61624c9e05622"
+      "bytes": 10081,
+      "sha256": "7dd5b693f3095b6678106c1a41c1303d57b3d7a30da0eeffc867fc5000fd6c74"
     },
     {
       "path": "reference-seedance.md",
@@ -65,8 +65,8 @@
   ],
   "archive": {
     "path": "slates-prompt-builder.skill",
-    "bytes": 37054,
-    "sha256": "823cbb640eb6f64afceec8665f20685cf851527d2b886e1443bccca0ead4afeb",
+    "bytes": 37938,
+    "sha256": "48331704f54f422542f7a1a164915f3739b925e3f225a3710dbd8ecb2963ce68",
     "entries": [
       "SKILL.md",
       "reference-character.md",

package/package.json

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

package/skills/slates-character-identity.md

@@ -28,12 +28,14 @@ Slates generates **one identity sheet per character**, bound as the character's
 | Panel | What it carries |
 |---|---|
 | **Chest-up portrait, three-quarter angle, largest panel (~25–30% of the sheet)** | The face. **This is the only place the model reads facial identity from** — every detail it will ever know comes from those pixels, so it gets the resolution. Off-frontal, never dead-on: an angled head reads its volume instantly. |
-| **Full-body front, relaxed A-pose — framed from the collarbone down, head not shown** | Build, proportion, wardrobe. Headless on purpose: a front-facing body panel renders a ~40px face that can't match the portrait's, so the sheet would carry two competing identities and the model averages them. |
+| **Full-body front, relaxed A-pose — cropped at the collarbone, just the face cropped out** | Build, proportion, wardrobe. The face is cropped off on purpose: a front-facing body panel renders a ~40px face that can't match the portrait's, so the sheet would carry two competing identities and the model averages them. **Only the face** — neck, arms and hands render as skin. |
 | **Full-body back, head and hair visible** | Hair fall and the back of the outfit — the only panel where either reads. Keeps its head because there's no face to compete with. |
 
 The rule is **kill every competing rendering of the FACE, not every head** — which is why exactly one body panel is headless.
 
-On a deep neutral-grey plate (`#3a3a3c`), flat and shadowless, with catchlights in the eyes, irises never crushed to black, surface texture at the medium's own natural level of detail, broken symmetry, and no over-clean 3D-game-model look. Quadrupeds and non-bipedal characters are carved out — natural standing stance, head shown on both body panels.
+On a deep neutral-grey plate (hex `3a3a3c`, emitted without the `#` — see the sigil warning in Don'ts), flat and shadowless, with catchlights in the eyes, irises never crushed to black, surface texture at the medium's own natural level of detail, broken symmetry, and no over-clean 3D-game-model look. Expression is **a slight natural smile with the teeth just visible** — a closed mouth carries no dental information, so every downstream smiling shot invents teeth, and teeth are person-specific.
+
+**Two carve-outs, scoped differently on purpose.** Non-human characters get a natural neutral expression instead of a smile — that one is scoped by *having a human mouth*, so a bipedal robot or humanoid alien is covered. Quadrupeds and non-bipedal characters get a natural standing stance with the head shown on both body panels — that one is *anatomical*. **Both are conditionals the image model evaluates against your reference; neither is a code branch, because the op has no character-kind input.**
 
 **The sheet inherits the source's medium** — photo, anime, illustration, painterly, 3D render — unless the user explicitly asks for a transform. None of the craft clauses above override that: they ask for *readable* eyes and *material-looking* surfaces within whatever medium the character is in, not for photorealism.
 
@@ -69,7 +71,8 @@ If text only: generate from prompt-only — less consistent, so warn the user.
 - Default to Nano Banana 2 at 2K. **Never 4K** — no identity gain at sheet scale, wasted spend.
 - When the result returns inline, **evaluate it before binding**:
   - Is the portrait clearly the largest panel, and is it off-frontal?
-  - **Is the front body panel cleanly headless** — an empty collar with the garment holding its shape, no partial face, no floating jaw, no smeared neck stump? A botched crop is worse than no crop.
+  - **Is the front body panel cleanly headless** — an empty collar above a normally rendered body, no partial face, no floating jaw, no smeared neck stump? A botched crop is worse than no crop.
+  - **Is the body still there?** Neck, forearms and hands rendered as skin, not an empty outfit floating on nothing. A hollow garment means the invisible-mannequin genre ran unbounded.
   - Do the body panels read as the same build, wardrobe and hair as the portrait?
   - Catchlights present, irises readable rather than black holes?
   - Is it in the source's medium, and does it read as *that* medium done well — or has it drifted toward the over-clean game-model look?
@@ -95,6 +98,8 @@ Critically, the app injects **no** wardrobe, expression, or lighting directive.
 - **Don't** create a second character image. One canonical identity is what the storyboard pipeline reads.
 - **Don't** skip binding. An unbound asset doesn't help downstream.
 - **Don't** invent character details. Stick to what's in the reference image and the user's description.
-- **Don't** describe the headless front panel as removal or decapitation — in `userNotes` or any hand-written variant. The template asks for it as *framing* — "cropped at the collarbone, head not shown, invisible-mannequin presentation" — which is a standard e-commerce genre with deep training data. Removal phrasing is untested and invites a refusal.
+- **Don't** describe the front panel's crop as an absent head — in `userNotes` or any hand-written variant. The template asks for it as *framing*: **"cropped at the collarbone, an invisible-mannequin presentation with just the face cropped out"**, a standard e-commerce genre with deep training data. **"the head not shown" is a hard 422 on gpt-image-2** — fal returns `content_policy_violation` with `loc: ["body","prompt"]`, so the text is rejected before any image is read, because an anatomical absence reads as gore to OpenAI's classifier. It passed NB2, which is why the original receipt looked safe: **it was model-scoped.** State an exclusion as a framing choice, never as a missing body part.
+- **Don't** invoke the invisible-mannequin genre without bounding it to the face. **"an invisible-mannequin presentation where the clothing holds its own shape" removed all the skin** — no neck, no hands, no forearms, a garment floating on nothing — because that *is* the e-commerce genre in full: an empty outfit. **"with just the face cropped out"** keeps the anchor and bounds it. Generalises: a genre anchor imports the whole genre, so name what STAYS, not only what goes.
+- **Don't** put `#` or `@` anywhere in prompt text. Both are reference-token sigils in the desktop prompt composer and an unresolved one is **silently deleted** — no error, no log, just missing words. `#3a3a3c` reached fal as `background ()` on a real 2026-07-30 request, meaning the plate value had never been delivered to any model since the composer shipped. Write hex values bare.
 - **Don't** use 4K — wastes credits, no quality gain at sheet scale.
 - **Don't** feed a multi-view sheet into a Seedance shot that has **several characters in frame** without binding each character to its image and appending the anti-twin constraint — ByteDance documents multi-view assets as a cause of duplicate characters. See `slates-prompting-seedance`.

package/skills/slates-model-selection.md

@@ -91,6 +91,32 @@ Both tools have a cheap Kling utility lane and a premium Seedance lane. The capa
 
 **Split rule of thumb:** readable text / panels / UI → GPT Image 2; photoreal, character-locked, widescreen, or edit-heavy → the Banana line; drafts → NB2 Lite; uncensored or odd resolutions → Seedream/FLUX.
 
+## Audio routing
+
+**Image and video models cannot generate standalone audio, and none of the four audio models can generate images or video.** A shot that needs synced audio generated WITH the picture is still a video job (Kling omni / Veo / Omni Flash / Seedance all carry native audio); the models below produce audio *as its own asset*, to lay on the timeline.
+
+| Job | Model | Why |
+|---|---|---|
+| **Default — a whole audio scene in one pass**: room tone, ambience beds, crowds, nature, layered dialogue + effects | **Seed Audio 1.0** (`seed-audio`) | One plain sentence in, a complete scene out. 1–120s. The continuity-bed workhorse. |
+| **The exact words, in a repeatable named voice** — ad reads, narration, character lines to lip-sync against | **Eleven v3** (`eleven-v3`) | Verbatim text, 20 preset voices, re-renderable after a copy tweak without the performance drifting. Billed per 100 characters. |
+| **One effect that lands on a known frame**, or a seamless loop | **Sound Effects v2** (`eleven-sfx`) | The only surface with an exact duration control (0.5–22s) and a real loop mode. |
+| **A song or a score** | **Suno** (`suno`) | Full music with structure. Two variations per call for one flat price, and duration is free to 360s. |
+
+### Named audio escalation triggers
+
+- **"It needs to sound like a place"** → Seed Audio. Three separate SFX generations layered on the timeline is the wrong shape and costs more.
+- **"Read this line"** with copy that a client can still change → Eleven v3. Scratch dialogue while the script is moving can stay on Seed Audio.
+- **"That needs a thump right there"** → Sound Effects, with the duration set to roughly the length of the event.
+- **"Give it a track"** → Suno, `instrumental: true` unless a vocal is genuinely wanted (an unasked-for vocal fights dialogue).
+
+**Rules:**
+
+- **🚨 Seed Audio has NO duration parameter.** Length comes from the prompt text, so Slates writes the requested duration into the prompt and **bills what you asked for**. Choose the duration deliberately and never write a second, different length into the sentence. Full doctrine: `slates-prompting-seed-audio`.
+- **Kling's audio syntax does not transfer.** `SFX:` / `Ambient noise:` / `Background music:` prefixes are Kling 3.0 *video* prompt syntax. Seed Audio reads them as literal words and the result degrades.
+- **Beds outlast the cut.** Always ask for more seconds than the clip needs so the edit has fade handles — on Suno the extra seconds are literally free.
+- **Audio inside the video vs audio as an asset.** If the sound must be locked to what happens on screen, generate it with the video (Kling omni / Seedance / Omni Flash / Veo). If it needs to be moved, trimmed, re-used, or layered, generate it here and drop it on an audio track.
+- Per-model prompting: `slates-prompting-seed-audio`, `slates-prompting-elevenlabs`, `slates-prompting-suno`.
+
 ## Cost is a tiebreaker, not the router
 
 Route by capability first, then pick the cheapest tier that serves the job (per `slates-cost-discipline`). Never pick a model because its per-second price looked lowest — a cheap clip that has to be regenerated on the right model costs more than routing correctly once.

package/skills/slates-prompting-elevenlabs.md

@@ -0,0 +1,131 @@
+---
+name: slates-prompting-elevenlabs
+description: How to prompt the two ElevenLabs surfaces in Slates. Read before calling slates_generate_audio with model eleven-v3 (Eleven v3 text-to-speech - controlled, repeatable, named-voice voiceover, billed per 100 characters) or eleven-sfx (Sound Effects v2 - one short effect with an EXACT duration, 0.5-22s, billed per second). Covers the "the text field is spoken verbatim" rule, punctuation as the only timing control, stability, describing an effect by its physical cause, and when to use Seed Audio instead.
+---
+
+# ElevenLabs — prompting (Eleven v3 TTS + Sound Effects v2)
+
+Two separate surfaces from the same vendor, carried on fal (`fal-ai/elevenlabs/tts/eleven-v3`, `fal-ai/elevenlabs/sound-effects/v2`). They share nothing but a bill — treat them as different tools.
+
+## Where they route
+
+- **`eleven-v3`** — the exact words matter and the read must be **repeatable**: ad reads, narration, character lines you will lip-sync against, anything a client will ask you to re-render after a copy tweak. Billed per 100 characters of text, rounded up.
+- **`eleven-sfx`** — a single sound that has to land on a known frame, or a seamless loop. Billed per second, 0.5–22s.
+- **Neither** for layered scenes. A room with dialogue *and* clatter *and* ambience is one `seed-audio` pass, not three ElevenLabs generations.
+- **AUDIO-ONLY.** Neither can produce images or video.
+
+---
+
+## Eleven v3 (`eleven-v3`) — THE RULES
+
+### 1. 🚨 The text field is the script. Every character is spoken.
+
+```
+✗  (excited) Read this fast — "Grab yours today!"
+✓  Grab yours today!
+```
+
+Stage directions, speaker names, bracketed emotion tags and markdown all get read out loud. There is no instruction channel — direction lives in `stability` and in how you punctuate.
+
+### 2. Punctuation is the only timing control
+
+| You want | Write |
+|---|---|
+| a hard stop | `It works. Every time.` |
+| a beat, not a stop | `It works — every time.` |
+| a trailing hesitation | `It works… mostly.` |
+| a list rhythm | `Faster, cheaper, and yours.` |
+
+Rewrite the punctuation before you touch a setting. It moves the read more than `stability` does.
+
+### 3. Pick a voice and keep it
+
+20 presets: Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill. Default `Rachel`.
+
+One voice per character, one per piece. A series that swaps voices between shots reads as an accident. There is **no voice cloning on this route** — a cloned ElevenLabs voice ID is not supported and must not be assumed to pass through.
+
+### 4. Stability
+
+| Value | Behavior | Use for |
+|---|---|---|
+| ~0.3 | expressive, varies take-to-take | one dramatic line, character dialogue |
+| 0.5 (default) | balanced | most reads |
+| ~0.8 | flat, highly repeatable | long narration, anything you will re-render |
+
+Raise it when re-rolls keep giving you a different performance. Lower it when the read is lifeless.
+
+### 5. Spell out what TTS gets wrong
+
+Acronyms, product names, prices, years and URLs are where it embarrasses itself. Write the pronunciation:
+
+```
+SKU        → "ess kay you"
+2026       → "twenty twenty six"
+$19.99     → "nineteen ninety nine"
+slates.video → "slates dot video"
+```
+
+Set `languageCode` (ISO 639-1) to force a language when the text is ambiguous or code-switched.
+
+### 6. Length is money, honestly
+
+1–5000 characters, billed in 100-character buckets rounded up. A tightened sentence costs less; a pasted stray paragraph costs more. This is the one Slates surface where editing the copy is also a cost control.
+
+### 7. Timestamps are free — leave them on
+
+Word-level timestamps come back with every generation at no extra charge. They are exactly what a caption/subtitle pass consumes. There is no reason to disable them.
+
+---
+
+## Sound Effects v2 (`eleven-sfx`) — THE RULES
+
+### 1. Describe the physical CAUSE, not the label
+
+```
+✗  door sound
+✓  heavy oak door slams shut in a stone hallway
+
+✗  whoosh
+✓  a thick rope swung fast past a microphone, low air displacement
+
+✗  footsteps
+✓  boots on wet gravel, slow, one person
+```
+
+Material + weight + surface + room. Naming all four is the difference between a usable effect and a stock-library shrug. Cap is 450 characters — you will not need them.
+
+### 2. One sound per generation
+
+This surface makes a single event. A door, then footsteps, then a siren is three generations layered on the timeline — or one `seed-audio` scene, which is usually cheaper and always more coherent.
+
+### 3. Duration is always explicit, and it is the price
+
+`durationSeconds` is 0.5–22 and Slates **always sends it**. (Left null the model picks, which makes the charge non-deterministic — so it is never left null.)
+
+| Kind of sound | Ask for |
+|---|---|
+| impact, hit, click | 0.5–1s |
+| whoosh, riser, transition | 2–4s |
+| loopable bed | 8–22s + `loop: true` |
+
+Over-asking pads the tail with room tone you then trim. Under-asking clips the decay.
+
+### 4. Loops
+
+`loop: true` tiles without a seam — rain, engine hum, crowd murmur, machine noise. Combine with a longer duration so the loop point is not obvious.
+
+### 5. Prompt influence
+
+`promptInfluence` 0–1, default 0.3. Higher hugs your wording with less variation between takes; lower explores. Raise it when a re-roll keeps wandering off the brief; lower it when every take sounds like the same take.
+
+---
+
+## Iterating on either surface
+
+- TTS re-rolls that keep drifting = raise `stability`. TTS reads that sound robotic = lower it, then fix the punctuation.
+- SFX re-rolls that keep missing = the prompt named a label instead of a cause. Rewrite it as a physical event.
+- Three failed takes means the prompt is wrong, not the seed.
+
+## Content notes
+
+ElevenLabs applies its own moderation, and voice likeness of real people is restricted by their terms. See slates-content-policy.

package/skills/slates-prompting-seed-audio.md

@@ -0,0 +1,110 @@
+---
+name: slates-prompting-seed-audio
+description: How to prompt Seed Audio 1.0 (ByteDance, via fal). Read before calling slates_generate_audio with model seed-audio. The one-pass audio SCENE model — dialogue, SFX and ambience together from ONE plain sentence. CRITICAL - it has NO duration parameter, so length must be named IN THE PROMPT TEXT and Slates bills the duration you request. Covers the one-sentence doctrine, the crowd-size rule, why Kling "SFX:" syntax hurts here, and the audio-refs-XOR-image input rule.
+---
+
+# Seed Audio 1.0 — prompting
+
+ByteDance's one-pass audio scene model, carried on fal (`bytedance/seed-audio-1.0`). It generates dialogue, sound effects and ambience **together**, from a single plain sentence. 1–120 seconds. It is the default audio model in Slates and the workhorse for continuity beds.
+
+## Where it routes
+
+- **Scene audio, room tone, ambience beds, crowd/nature soundscapes** — anything where several sounds share a space. One generation, not three layered ones.
+- **Fast scratch dialogue** when the exact wording is still moving. Once the script locks and the read has to be repeatable, switch to `eleven-v3`.
+- **NOT** a single effect that must land on a known frame — that is `eleven-sfx`, which takes an exact duration.
+- **NOT** music — that is `suno`.
+- **AUDIO-ONLY.** It cannot produce images or video.
+
+## THE RULES
+
+### 1. 🚨 There is no duration parameter — the words set the length
+
+This is the single most important fact about this model. Output length is driven by the prompt text ("… 15 seconds"), capped at 120s.
+
+**Slates handles this for you:** the `durationSeconds` param appends the duration to the prompt and **bills that number of seconds**. So:
+
+- Set `durationSeconds` to what you actually want.
+- **Do not also write a different length into your sentence.** Two numbers fight, and you pay for the one you selected, not the one you got.
+- If the returned clip is shorter than requested you still paid for the request — that is the deal that keeps the displayed price equal to the charge. Ask for what you need.
+
+<!-- slates-only -->
+The server re-derives the billed key from `durationSeconds` (a client cannot under-bill), probes the returned `audio.duration` after completion, and logs `SEED AUDIO BILLING DRIFT` if the model overshot. No auto-charge, no refund — the request is the contract.
+<!-- /slates-only -->
+
+### 2. One plain sentence. No production jargon.
+
+Field-proven (Higgsfield sprint, 2026-07-27/28). Working prompts look like this:
+
+```
+tiny applause of 2 or 3 people at an open mic. 15 seconds
+nature soundscape, wide open field cicadas and birds and a loon.
+a diner at 2am, one coffee machine hissing, cutlery somewhere behind the counter
+```
+
+Not this:
+
+```
+✗ AMBIENCE: interior diner, night. SFX: espresso machine (hiss, 2s), cutlery.
+✗ Wide shot of a diner. Slow push in. Warm tungsten. Ambient noise: ...
+```
+
+Shot language, camera moves and lighting belong to video prompts. Here they are just words the model has to ignore.
+
+### 3. Never bring Kling's audio syntax to this model
+
+`SFX:` and `Ambient noise:` prefixes and `Background music:` labels are **Kling 3.0 video** syntax. Seed Audio has no parser for them — it reads them as text in the scene and the output gets measurably worse. Describe the sounds directly instead.
+
+### 4. Name the crowd size, the room size, the distance
+
+The highest-leverage single edit on any bed. Unqualified nouns default big:
+
+| Vague | What it returns | Fixed |
+|---|---|---|
+| `applause` | a full auditorium | `tiny applause of 2 or 3 people` |
+| `traffic` | a highway | `one car passing on a wet residential street` |
+| `crowd` | a stadium | `four people talking at the next table` |
+
+Distance words (`far off`, `muffled through a wall`, `right next to the mic`) work the same way and are how you build depth in one sentence.
+
+### 5. Beds must outlast the cut
+
+Ask for a few seconds more than the clip needs so the edit has handles to fade through. A bed that ends exactly on the cut always sounds clipped. This is a product requirement, not a preference — it is why the duration control exists at all.
+
+### 6. Dialogue goes in quotes, inside the same sentence as the room
+
+```
+a tired bartender says, "we closed twenty minutes ago", glasses clinking behind him
+```
+
+Pick a preset voice when a specific speaker matters. Leave `voice` unset and the scene casts itself — which is usually right for crowd and background dialogue.
+
+Preset voices (20): `vivi_mixed_en_zh_ja_es_id`, `mindy_en_es_id_pt_zh`, `kian_en_zh`, `cedric_en_zh`, `sophie_en_zh`, `jean_en_zh`, `magnus_en_zh`, `mabel_en_zh`, `nadia_en_zh`, `opal_en_zh`, `pearl_en_zh`, `quentin_en_zh`, `corinne_mixed_en_zh`, `esther_mixed_en_zh`, `lyla_mixed_en_zh`, `tracy_es_zh`, `sandy_es_mixed_en_zh`, `felix_zh`, `celeste_zh`, `monkey_king_zh`.
+
+Set `multilingual: true` for non-English or mixed-language lines.
+
+### 7. Inputs: up to 3 audio clips **XOR** one image. Never both.
+
+- **Audio references** — up to 3 clips, each ≤30s and ≤10MB (wav/mp3/pcm/ogg_opus). Refer to them in the prompt as `@Audio1`, `@Audio2`, `@Audio3`: *"match the room tone of @Audio1"*.
+- **Image reference** — one image (jpeg/png/webp ≤10MB). The model scores what it sees.
+- Sending both is rejected by the API. Pick the one that carries the intent.
+
+### 8. The knobs, and when to touch them
+
+| Param | Range | Reach for it when |
+|---|---|---|
+| `speed` | 0.5–2.0 | Dialogue is racing or dragging against picture. |
+| `volume` | 0.5–2.0 | Rarely — normalize on the timeline instead. |
+| `pitch` | −12…+12 semitones | Ageing or shifting a voice. Small moves only; ±3 is already a lot. |
+| `multilingual` | bool | Non-English or code-switched lines. |
+| `sampleRate` | 8k–48k | Leave at 24000 unless you are matching an existing stem. |
+| `outputFormat` | mp3 / wav / pcm / ogg_opus | wav when this is going into a mix; mp3 otherwise. |
+
+## Iterating
+
+- A bed that came back wrong is almost always a **scale** problem (crowd/room too big) or a **jargon** problem (the sentence reads like a spec). Fix those two before touching `speed`/`pitch`.
+- Three failed takes on the same sentence means the sentence is wrong, not the seed. Rewrite it the way you would say it out loud.
+- Generations are cheap enough at short durations that auditioning two phrasings beats agonizing over one.
+
+## Content notes
+
+Provider-side moderation applies to voices and to recognizable real people. See slates-content-policy.

package/skills/slates-prompting-suno.md

@@ -0,0 +1,110 @@
+---
+name: slates-prompting-suno
+description: How to prompt Suno in Slates. Read before calling slates_generate_audio with model suno. Full music tracks - EVERY call returns TWO variations for one flat price and duration is FREE up to 360 seconds. The rule that decides everything - in CUSTOM mode the prompt field is the EXACT LYRICS (sung as written), in DESCRIPTION mode it is a description and the lyrics get written for you. Covers the mode matrix, style vs prompt steering, instrumental scoring, negative tags, and the character caps.
+---
+
+# Suno — prompting
+
+Full music generation, reached through the sunoapi.org wrapper. Models `V4`, `V4_5`, `V4_5PLUS`, `V4_5ALL`, `V5`, `V5_5`.
+
+**Two facts that should shape every decision:**
+
+1. **Every call returns TWO songs** — two genuinely different takes on the same brief, for one flat price. Audition both before re-rolling.
+2. **Length is free.** A 360-second track costs exactly what a default one costs (measured against the live provider balance 2026-07-31: a default call and a `duration: 240` call both debited the same). There is never a reason to generate a bed shorter than your edit.
+
+## Where it routes
+
+- **Anything a listener would call a song or a score** — theme, underscore, needle-drop, montage bed, end-card sting.
+- **NOT** ambience or room tone — that is `seed-audio`, which is cheaper and better at it.
+- **NOT** a single effect — that is `eleven-sfx`.
+- **AUDIO-ONLY.**
+
+## 🚨 THE RULE: which mode you are in changes what `prompt` means
+
+| `customMode` | `instrumental` | Required | What `prompt` means |
+|---|---|---|---|
+| `false` | either | `prompt` only (≤500 chars) | **A description.** Lyrics get written for you. |
+| `true` | `true` | `style`, `title` | **Unused.** Style + title do all the steering. |
+| `true` | `false` | `style`, `title`, `prompt` | **THE EXACT LYRICS**, sung as written. |
+
+Putting a description in the prompt field while `customMode: true` and `instrumental: false` gets your description **sung back at you**. This is the single most common Suno mistake and it costs a full generation every time.
+
+## Description mode — the fast path
+
+```
+customMode: false
+prompt: "brooding synthwave for a night drive, analog bass, no vocals, 90 bpm"
+```
+
+Use it when you need a mood and do not care about specific words. 500-character cap. This is the right default for background beds.
+
+## Custom mode — when the words matter
+
+```
+customMode: true
+instrumental: false
+style:  "dream pop, hazy, reverb-heavy guitars, female vocal, 100 bpm"
+title:  "Blue Hour"
+prompt: "[Verse 1]\nThe lights come on before we're ready\n..."
+```
+
+Structure tags (`[Verse]`, `[Chorus]`, `[Bridge]`, `[Outro]`) inside the lyrics are how you control the arrangement. Everything that is not a structure tag will be sung.
+
+## Instrumental scoring
+
+```
+customMode: true
+instrumental: true
+style: "tense orchestral strings, low brass swells, no percussion"
+title: "Approach"
+```
+
+`instrumental: true` is the right answer for almost every film bed — a vocal you did not ask for will fight your dialogue.
+
+## Steer with `style`, not with adjective piles
+
+Genre + era + instrumentation + tempo belong in `style`, not stuffed into `prompt`.
+
+```
+✓ style: "90s trip-hop, dusty breakbeat, Rhodes piano, upright bass, 85 bpm"
+✗ prompt: "a really cool dusty 90s trip hop song with a Rhodes and..."
+```
+
+`negativeTags` removes what keeps creeping in: `"brass, EDM drop, male vocal"`.
+
+## The steering knobs
+
+| Param | Range | Reach for it when |
+|---|---|---|
+| `duration` | 10–360s (**V5_5 + custom mode only**) | Always, when the bed must outlast the cut. It is free. |
+| `vocalGender` | `m` / `f` — **the wire values, not "male"/"female"** | A specific voice is required. |
+| `styleWeight` | 0–1 | The style field is being ignored (raise) or strangling the song (lower). |
+| `weirdnessConstraint` | 0–1 | Takes are too safe (raise) or falling apart (lower). |
+| `audioWeight` | 0–1 | Balancing an audio input against the prompt. |
+| `personaId` / `personaModel` | — | A series needs the same voice/sound across episodes. |
+
+## Character caps
+
+| Field | V4 | V4_5 / V4_5PLUS / V5 / V5_5 | V4_5ALL |
+|---|---|---|---|
+| prompt (custom = literal lyrics) | 3000 | 5000 | 5000 |
+| prompt (non-custom = description) | 500 | 500 | 500 |
+| style | 200 | 1000 | 1000 |
+| title | 80 | 100 | 80 |
+
+## Iterating
+
+- **Audition both returned songs first.** A re-roll costs a full generation; the second variation is already paid for.
+- Wrong genre → fix `style`. Wrong words → you are in the wrong mode, check the matrix above.
+- Something keeps appearing that you do not want → `negativeTags`, not more prompt.
+- Three failed generations on the same brief means the style field is too vague, not that the seed is unlucky.
+
+## Ops notes
+
+- Tracks take 2–3 minutes; a streamable preview exists ~30–40s in. Use `background: true` and poll.
+- The provider hosts files for a limited window — **Slates downloads and stores them locally as soon as the track finishes**, so nothing expires out from under a project.
+- Suno has **no official public API**; this rides an unofficial wrapper. Treat availability as best-effort and do not build a deadline around it.
+
+## Content notes
+
+Provider-side moderation rejects lyrics and style prompts naming real artists or protected material (`SENSITIVE_WORD_ERROR`). Describe the sound, not the artist. See slates-content-policy.