From 33bd85f1cbbf41e0c3baec0b93e450403bd4890c Mon Sep 17 00:00:00 2001
From: "russell@unturf.com" <russell@unturf.com>
Date: Fri, 5 Jun 2026 19:34:24 -0400
Subject: [PATCH] CLAUDE.md: document mispronunciation fix workflow

Records the pre_process_map.yaml respelling pattern we used for
Provenance so future blackops sessions don't have to rediscover
that preprocess() reads per-request and no restart is needed.
---
 CLAUDE.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 94b4231..4dbfee8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -157,6 +157,46 @@ F5-TTS `ref_text` values are generated by `make whisper-refs` (whisper-large-v3
 the actual wav files) — they match what the audio sounds like, not LibriSpeech ground-truth
 labels. Regenerate any time `cloned-voices/` changes.
 
+## Fixing Mispronunciations
+
+When a voice mispronounces a word (e.g., F5-TTS said "Provenance" wrong),
+patch via text pre-processing — our engines read what we feed them, so a
+phonetic respelling at the input layer is our fastest fix. No model retraining.
+
+**Where:**
+- `config/pre_process_map.yaml` — live, tracked. What `preprocess()` reads.
+- `pre_process_map.default.yaml` — seed for fresh installs. Edit both, keep them
+  in sync.
+
+**Pattern:** word-boundary, case-insensitive, respell phonetically. Hyphens act
+as syllable hints. Example:
+
+```yaml
+# F5-TTS mispronounces "Provenance" — respell phonetically (per fox)
+- - (?i)\bProvenance\b
+  - prahvanans
+```
+
+**Workflow:**
+
+1. Edit both yaml files locally with our respelling.
+2. `git add` both, commit, `git push`.
+3. On prod, `git pull` — **no restart needed**. `preprocess()` re-reads our
+   yaml on every request (`speech.py:646`), so toggles are live.
+   ```bash
+   tmux send-keys -t <4090-window> \
+     'cd /mnt/data/git/uncloseai-speech && sudo -u fox git pull' Enter
+   ```
+4. Smoke test via our prod curl (see Testing below). Save output to a temp
+   mp3 and listen.
+5. If it still sounds wrong, iterate our respelling (e.g., `Prov-uh-dence` →
+   `Prav-uh-dence` → `prahvadence`). Repeat 1–4 — fox is the ear, ask for the
+   target phonetics.
+
+**A/B trick:** commit both an active and a `#` commented-out variant so we can
+toggle on prod without redeploys. Strip stale stubs after fox confirms a
+respelling.
+
 ## TTS Engine Status
 
 `tts-1-f5` (F5-TTS) is what prod serves today. `tts-1-qwen` (Qwen3-TTS) is also wired up.