kokoro: persist custom voices across container recreate

Wrapper only enumerates one voice directory (settings.voices_dir,
default /app/api/src/voices/v1_0 — inside the container's writable
layer, not bind-mounted). Override via VOICES_DIR=/app/user_voices
(host bind mount) and add a command shim that cp -r's built-ins from
the in-image v1_0 into user_voices on every start. Built-ins re-seed
fresh from the image (so upgrades that add voices propagate); custom
.pt files in user_voices are preserved (cp -r is additive).

Also adds scripts/blend_kokoro_voice.py + a playbook around it that
mirrors the wrapper's request-time voice="a(w)+b(w)" math but writes
the result as a named .pt to user_voices, making it discoverable via
GET /v1/audio/voices and persistent across recreate. Defaults to
athena = af_bella(2)+af_aoede(1) normalized.

stacks/kokoro/README.md

@@ -59,10 +59,36 @@ Supported `response_format`: `mp3 | wav | opus | flac | pcm`.
   Discoverable via `GET /v1/audio/voices` — naming convention is
   `<lang_code><gender_letter>_<name>` (e.g. `af_bella`, `am_adam`,
   `jf_alpha`, `zf_xiaobei`).
-- **Custom**: drop `.pt` voicepacks into `/worktank/kokoro/user_voices/`
-  on the host. Wrapper auto-discovers them on next request (no
-  restart). Training Kokoro voices is non-trivial — consult the
-  hexgrad community for how-to.
+- **Custom blends**: weighted-average existing voicepacks into a new
+  named voice using `playbooks/blend-kokoro-voice.yaml` (script:
+  `scripts/blend_kokoro_voice.py`). Mirrors the wrapper's request-time
+  `voice="a(w)+b(w)"` math but persists the result so it shows up in
+  `/v1/audio/voices`. Example shipped: `athena = af_bella(2)+af_aoede(1)`
+  normalized.
+
+  ```bash
+  scripts/elway irv-ml1 --playbook playbooks/blend-kokoro-voice.yaml \
+    --var 'recipe=af_bella(1)+am_adam(1)' --var out_name=androgyne
+  # add --var force=1 to overwrite an existing voice
+  ```
+
+  Persistence design: the wrapper enumerates exactly one directory
+  (`VOICES_DIR`, default in-image `/app/api/src/voices/v1_0`).
+  compose.yaml overrides `VOICES_DIR=/app/user_voices` (host bind
+  mount `/worktank/kokoro/user_voices`) and adds a `command:` shim
+  that `cp -r`'s the in-image built-ins into that dir on every
+  container start. Result:
+  * built-in voicepacks re-seed on each start, so image upgrades that
+    add/change built-ins propagate automatically
+  * custom blends written by the script live on the host bind mount —
+    survive `docker restart`, `up --force-recreate`, image upgrade,
+    and host reboot
+  * one-time prereq: the host dir must be chowned to `1001:1001`
+    (uid of `appuser` inside the container) so the shim's cp can
+    write — handled by `playbooks/deploy-kokoro.yaml`
+- **Cloned voices**: training a Kokoro voice from samples is non-
+  trivial — consult the hexgrad community for how-to. For voice
+  cloning use Chatterbox Turbo or IndexTTS-2 instead.
 
 ## Deploy