1 files changed, 15 insertions, 0 deletions

diff --git a/CONTEXT.md b/CONTEXT.md
index e272a7a..bdd2790 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -32,3 +32,18 @@ holds no implementation decisions or specs (those live in `docs/adr/`).
   afk). Paged at 10 entries, descending by default.
 - **Tracked guild** — the guild containing `status_channel_id`. Message counts
   are only tracked in this guild.
+
+## TTS
+
+- **Synthesize** — convert text to audio via local Piper TTS (ONNX model
+  loaded in-process via `piper-rs`). No external fallback. Output is f32 PCM
+  at the model's native sample rate (typically 22050 Hz mono), resampled to
+  48 kHz stereo via inline linear interpolation before playback. Songbird does
+  not resample — playing un-resampled audio results in wrong playback speed.
+- **TtsState** — struct held in poise `Data`: `OnceCell<Mutex<Piper>>` for the
+  model instance, `DashMap<String, (Vec<u8>, Instant)>` for the text→audio cache.
+  Piper loaded lazily on first TTS call. Cache keyed by full phrase string,
+  evicted by TTL. No Google TTS fallback.
+- **Pre-generation** — on first voice event for a user, synthesize all 6 event
+  phrases (join/leave/deafen/undeafen/mute/unmute) with their display name and
+  cache them. ~120ms first time, instant after. Lazy — no startup cost.