From c71d5a8a77afb8fe029e0397038cd6effe19ee5c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 20 Dec 2025 21:43:03 +0100
Subject: [PATCH] docs: expand sag pronunciation rules

---
 skills/sag/SKILL.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/skills/sag/SKILL.md b/skills/sag/SKILL.md
index 9c1a5cca2..b94fd21a6 100644
--- a/skills/sag/SKILL.md
+++ b/skills/sag/SKILL.md
@@ -24,6 +24,19 @@ Model notes
 - Stable: `eleven_multilingual_v2`
 - Fast: `eleven_flash_v2_5`
 
+Pronunciation + delivery rules
+- First fix: respell (e.g. "key-note"), add hyphens, adjust casing.
+- Numbers/units/URLs: `--normalize auto` (or `off` if it harms names).
+- Language bias: `--lang en|de|fr|...` to guide normalization.
+- v3: SSML `<break>` not supported; use `[pause]`, `[short pause]`, `[long pause]`.
+- v2/v2.5: SSML `<break time="1.5s" />` supported; `<phoneme>` not exposed in `sag`.
+
+v3 audio tags (put at the entrance of a line)
+- `[whispers]`, `[shouts]`, `[sings]`
+- `[laughs]`, `[starts laughing]`, `[sighs]`, `[exhales]`
+- `[sarcastic]`, `[curious]`, `[excited]`, `[crying]`, `[mischievously]`
+- Example: `sag "[whispers] keep this quiet. [short pause] ok?"`
+
 Voice defaults
 - `ELEVENLABS_VOICE_ID` or `SAG_VOICE_ID`