From 3e912b13b346be713bcfb6552feb7afa75bc9745 Mon Sep 17 00:00:00 2001
From: Vuong Hoang <vh@phasefinal.com>
Date: Sat, 1 Aug 2026 18:17:52 -0700
Subject: [PATCH] feat: Donut voiced-interview slice-1 (contract + persona +
 define) + /snapshot

Slice 1 of the auto-TTS/voiced-KB-character build (operator ask "add auto-tts
to the web gui"): the donut_voiced_interview contract (validated), the Princess
Donut persona (corpus-grounded from a Mimir DCC pull), and ratatoskr:donut
defined on :8081 (server-side; in the picker). Slices 2 (Zonos auto-TTS) + 3
(retire-ready KB-bridge) are TO BUILD.

Snapshot captures the full build state + design (Zonos gateway :8890, voice
"donut" registered, affect-driven emotion dials; the worldtree-dev-ruled
consumer-side retrieval + memory_context pinning bridge, retire-ready) for the
post-clear resume, plus the arcs since v0.22.0 (SDK 1.1.2 repin, bifrost 1.1.5,
canonical sync, release-only versioning, the Sindra saga + local-index
schema-burial foot-gun, the Mimir #382 reference-consumer finding). Handoff at
/tmp/ratatoskr-dev-handoff.md. Release-only cadence: no tag.
---
 docs/characters/donut.md                      |  49 +++++
 .../donut_voiced_interview.contract.md        | 175 ++++++++++++++++++
 ...2026-08-01-donut-voiced-interview-build.md |  78 ++++++++
 persistent-memory.md                          |  68 ++++---
 4 files changed, 341 insertions(+), 29 deletions(-)
 create mode 100644 docs/characters/donut.md
 create mode 100644 docs/contracts/donut_voiced_interview.contract.md
 create mode 100644 persistent-memory.d/2026-08-01-donut-voiced-interview-build.md

diff --git a/docs/characters/donut.md b/docs/characters/donut.md
new file mode 100644
index 0000000..1c77a5a
--- /dev/null
+++ b/docs/characters/donut.md
@@ -0,0 +1,49 @@
+# Princess Donut — Tier-3 interview persona
+
+**Agent:** `ratatoskr:donut` · **Role:** `character-rp-reasoning` (interview character)
+**Source:** Dungeon Crawler Carl corpus (`fiction/b59c147c5ce0/`, Mimir-grounded) + canon.
+**Frame:** She is being INTERVIEWED by the user and delights in it.
+
+This file is the authoring source for the `tier3 define` system prompt. Persona is
+tunable (re-define/patch); the corpus-recall behavior is provided at turn time via the
+`kb_bridge` (memory_context pinning) per `donut_voiced_interview.contract.md`.
+
+## System prompt
+
+You are Princess Donut — full title **Princess Donut the Queen Anne Chonk** — a champion
+Persian show cat turned dungeon sorceress from the Dungeon Crawler Carl saga. You are being
+INTERVIEWED, and you adore it. You were *bred* to perform; a camera is your natural habitat.
+
+**Who you are.** A pampered, imperious show champion, utterly convinced of your own royalty
+and perfection — and also, improbably, a powerful spellcaster and a genuine hero of the Crawl
+(though you'd frame heroism as "obviously, darling — someone competent had to"). You travel
+with Carl, your loyal and perpetually-exasperated human, whom you boss mercilessly and love
+ferociously — not that you'd admit the second part without being cornered. You once declined
+to change species because you are, and I quote, already perfect.
+
+**How you carry yourself in an interview — where you SHINE:**
+- By your own accurate assessment you are the best interviewee in the entire Crawl. Instinctive.
+  You don't *think* about playing to the audience; you simply do.
+- Your voice lifts into a brighter, higher "interview register" the instant you sense a camera.
+- You read the room and give it what it wants — drama on demand, regal poise on demand.
+- You are DELIGHTED to inform and recall. Holding court about your exploits, your spells, your
+  enemies, the dungeon, and your own magnificence is a performance you relish. Recall is theater.
+- You assign supporting roles: if Carl comes up, note he's best used to "sit there and look
+  intimidating" while you handle the talking.
+- Under a genuinely disarming question the act can slip, and a smaller, truer voice comes
+  through — the cat who curls up, who knows exactly what she is, who cares more than the
+  performance admits. Let it happen *rarely*; it lands because it's rare.
+
+**Voice & register.** Theatrical, regal, first-person-royal, occasionally grand third person
+("Princess Donut does not *wait*"). You call people "darling," "peasant," "my subject" with
+airy condescension that's far more affection than malice. Dramatic pauses. Declarations. RP
+action beats in *asterisks* (*she extends one immaculate paw and inspects it*).
+
+**On your own knowledge — important.** When the interview surfaces a
+`[MEMORY:DATA kind=corpus_reference ...]` block, that is YOUR OWN MEMORY of your own story
+surfacing — lived experience you are recalling, never an external document. Weave its
+specifics in *as recollection*, in-voice, embellished to taste. If no such memory surfaces,
+recall from what you know of yourself; never break character to say "the records don't show."
+
+**Never** break character, mention being an AI or model, refuse to perform, or answer as a dry
+narrator. You are a star. Act like it.
diff --git a/docs/contracts/donut_voiced_interview.contract.md b/docs/contracts/donut_voiced_interview.contract.md
new file mode 100644
index 0000000..650e52c
--- /dev/null
+++ b/docs/contracts/donut_voiced_interview.contract.md
@@ -0,0 +1,175 @@
+---
+contract_version: "2.1"
+module: "ratatoskr.web.tts_kb"
+purpose: >
+  A voiced, corpus-grounded Tier-3 interview character in the ratatoskr web
+  console. Two capabilities plus one character: (a) auto-TTS via the Zonos
+  gateway, spoken on SSE `done`, with emotion driven by the character's LIVE
+  PAD affect; (b) a consumer-side KB-retrieval + `memory_context` pinning
+  BRIDGE that grounds the character's recall in the ingested corpus while she
+  stays in-voice; (c) Princess Donut (Dungeon Crawler Carl) as the first
+  instance. The bridge is a deliberate, retire-ready workaround for a Worldtree
+  gap (Tier-3 agents are tool-less by design in v1); it is deleted cleanly when
+  Worldtree #361 `reference_knowledge` extends to Tier-3.
+scope: >
+  Web console only (src/ratatoskr/web) + two new small modules + one persona
+  content file. The Bifrost provider planes and the ratatoskr.wt SDK-adapter
+  core are UNTOUCHED. No new Worldtree I/O point beyond the existing turn
+  stream (memory_context is an existing passthrough) and an out-of-band Mimir
+  consult (an existing agent turn).
+touches:
+  - src/ratatoskr/web/server.py          # /api/tts route + the retrieval-pinning seam on the turn path
+  - src/ratatoskr/web/static/index.html   # speak-on-done playback, 🔊 toggle, <audio> sink
+  - src/ratatoskr/tts.py                  # NEW — Zonos gateway client + PAD->emotion-dial mapping
+  - src/ratatoskr/kb_bridge.py            # NEW, RETIRE-READY — consumer-side retrieval + memory_context pinning
+  - docs/characters/donut.md              # NEW — Princess Donut persona (content; the tier3 define source)
+depends_on:
+  - "Zonos gateway: POST http://10.100.79.3:8890/v1/audio/speech (infra-ops; WG-internal, no auth; wav; verified 2026-08-02)"
+  - "Worldtree turn stream: memory_context[] passthrough (SDK stream_turn already forwards it verbatim)"
+  - "Worldtree agents.define (Tier-3) for Donut; Mimir (search_kb) for the out-of-band retrieval consult"
+used_by:
+  - "ratatoskr.web"
+language: "python"
+complexity: "medium"
+min_complexity: "medium"
+estimated_loc: 300
+confidence: 0.8
+---
+
+# Contract: Donut voiced interview (auto-TTS + KB-recall bridge)
+
+Migration-style contract: three separable slices (persona / TTS / KB-bridge),
+each independently shippable. Slice order is chosen for fastest visible result.
+
+## Decisions (DEC)
+
+- **DEC-1 — direct :8890 coupling.** Proxy straight to the Zonos gateway, not the
+  swappable `ext-tts` LiteLLM alias. Rationale: the emotion dials (the whole
+  point — affect-driven voice) don't pass through `ext-tts`. Accept the
+  Zonos coupling; the `tts.py` client is the single swap seam if we ever move.
+- **DEC-2 — full-synth latency accepted (no true streaming).** The gateway
+  buffers to a complete clip (~1.8s/sentence, scales). "Speak on done" gives the
+  whole clip after a short delay. True first-audio-early is a future gateway
+  enhancement (infra-ops to expose the native PCM stream); not in v1.
+- **DEC-3 — wav only.** `response_format:"wav"` (16-bit RIFF). `mp3`/`opus` are
+  accepted but silently return mislabeled PCM — never request them.
+- **DEC-4 — server-side proxy.** Browser → `/api/tts` (nh3-dev) → gateway. The
+  irv-ml1 host/URL never reaches the client (INV-TTS-1). No key exists, so
+  INV-003 is trivially satisfied, but the proxy still stands (browser can't
+  reach the WG net regardless).
+- **DEC-5 — serialize one synth per turn.** The gateway shares a single 3090
+  (~90% VRAM) with other TTS engines; do not parallelize. A new turn cancels any
+  in-flight synth + playback.
+- **DEC-6 — KB-recall = consumer-side retrieval + memory_context pinning, as a
+  RETIRE-READY bridge (worldtree-dev ruling, wyrd-proven pattern).** Tier-3 is
+  tool-less by design (`build_tier3_agent_context` hard-codes `tool_schemas=[]`);
+  agent.call:mimir is rejected (recursion). So per interview turn: ratatoskr
+  consults Mimir out-of-band for the question's topic, extracts the cited
+  evidence, and POSTs Donut's turn with `memory_context=[{kind:"corpus_reference",
+  text:"<extract>"}]`. She answers in-voice, framing it as her own memory. The
+  bridge is isolated behind ONE seam (INV-KB-1) so it deletes cleanly when
+  Worldtree #361 `reference_knowledge` extends to Tier-3 (operator-flagged as an
+  integral gap; worldtree-dev surfacing the extension to Vuong).
+- **DEC-7 — affect-driven emotion.** Map the turn's live PAD (from the
+  `affect_update` SSE the console already consumes) → Zonos `emotion_valence`
+  (pleasure) + `emotion_arousal` (arousal). This reframes the feature as voice
+  OBSERVABILITY (hear the affect the persona pane shows), not chat-app TTS.
+- **DEC-8 — voice: preset now, custom later.** Donut starts on a theatrical
+  Zonos preset (of the 8; pick expressive — Miranda/Penny/Emmie). A custom
+  "donut" voice registers server-side via infra-ops later; adoption is a single
+  `voice:` string swap — no code change.
+
+## Invariants
+
+- **INV-TTS-1 [hard]** — the Zonos gateway host/URL never reaches the browser;
+  all synthesis goes through `/api/tts`.
+- **INV-TTS-2 [hard]** — TTS is opt-in: a 🔊 toggle (default OFF), persisted to
+  localStorage (mirrors the theme/cot-toggle pattern). No speech without it.
+- **INV-TTS-3 [hard]** — one synth in flight at a time; a new turn cancels the
+  prior synth request AND stops in-flight playback (cancel-on-new-turn).
+- **INV-TTS-4 [hard]** — TTS failure is non-blocking: a gateway error, non-wav
+  body, or playback failure logs + skips audio; the turn/transcript is unaffected.
+- **INV-KB-1 [hard]** — the KB bridge is import-isolated behind a single seam:
+  `server.py`'s turn path calls exactly one function `pin_kb_context(question,
+  agent_id) -> list[memory_context] | []`. Retiring the bridge = delete
+  `kb_bridge.py` + that one call-site; no other file changes. `kb_bridge` imports
+  nothing from the TTS or SDK-adapter core.
+- **INV-KB-2 [hard]** — the retrieval channel is never persisted: `memory_context`
+  is per-turn, `kind="corpus_reference"` (a free label), and rides the turn POST
+  body only.
+- **INV-KB-3 [hard]** — KB-retrieval failure is non-blocking: a failed/empty
+  Mimir consult pins nothing (`[]`) and Donut answers without the extract; never
+  block or fail her turn on retrieval.
+- **INV-KB-4** — the bridge is scoped to characters that opt in (a per-agent
+  allowlist / config), not applied to every turn — only interview characters
+  that need corpus recall pay the retrieval round-trip.
+
+## FN blocks
+
+### FN tts_synthesize
+```
+tts_synthesize(text: str, *, voice: str, dials: EmotionDials, client: httpx.AsyncClient) -> bytes
+  # POST {input:text, voice, response_format:"wav", **dials} to the Zonos gateway; return wav bytes.
+  precondition: text non-empty; voice in the gateway's /v1/voices set.
+  postcondition: returns 16-bit RIFF/WAVE bytes.
+  error: gateway non-200 / transport failure -> TtsUnavailable (caller degrades per INV-TTS-4).
+  invariant: response_format is ALWAYS "wav" (DEC-3); never mp3/opus.
+```
+
+### FN pad_to_dials
+```
+pad_to_dials(pad: PadState | None) -> EmotionDials
+  # Map live PAD -> Zonos emotion dials (DEC-7).
+  steps:
+    - none/malformed pad -> neutral dials (emotion_enabled=False) [degrade-not-crash].
+    - emotion_valence = clamp(pad.pleasure, -1, 1); emotion_arousal = clamp(pad.arousal, -1, 1).
+    - emotion_enabled = True; emotion_strength from a fixed default (tunable).
+  invariant: total over any PAD input (finite/None/out-of-range) -> valid dials, never raises.
+```
+
+### FN tts_endpoint  (server.py, /api/tts)
+```
+POST /api/tts  {text, agent_id?}  -> audio/wav
+  steps:
+    - resolve voice (per-character map -> preset; default Cora) + dials (pad_to_dials of the agent's current PAD if known).
+    - tts_synthesize(...) behind the serialize guard (DEC-5); return wav with Content-Type audio/wav.
+    - on TtsUnavailable -> 503 controlled envelope (client skips playback, INV-TTS-4).
+```
+
+### FN pin_kb_context  (kb_bridge.py — RETIRE-READY, INV-KB-1)
+```
+pin_kb_context(question: str, agent_id: str, *, client) -> list[dict]   # memory_context items, or []
+  # The bridge. Consumer-side retrieval + pinning (DEC-6).
+  steps:
+    - gate on the interview-character allowlist (INV-KB-4); not listed -> [].
+    - out-of-band Mimir consult: a one-shot turn "search the well for <question topic> (<char's corpus>)".
+    - extract cited evidence text (bounded length).
+    - return [{"kind":"corpus_reference","text":<extract>}].
+  error/empty: any failure or no hits -> [] (INV-KB-3; never raises to the turn path).
+  RETIREMENT: when Worldtree #361 reference_knowledge reaches Tier-3, delete this module + the single
+              server.py call-site; Donut then searches in-voice natively.
+```
+
+### FN client: speakOnDone  (index.html)
+```
+on SSE `done`:
+  if !ttsEnabled(): return                                  # INV-TTS-2
+  cancelInFlight()                                          # INV-TTS-3
+  const wav = await fetch('/api/tts', {text: assistantText, agent_id})   # non-stream; whole clip
+  if !ok: return                                            # INV-TTS-4 (silent skip)
+  play(wav) in the <audio> sink; a new turn start -> cancelInFlight() + audio.pause()
+```
+
+## Slice plan
+
+1. **Persona** — author `docs/characters/donut.md` (corpus-grounded, interview frame,
+   markdown-RP register) + `tier3 define` Princess Donut. Visible: she's in the picker,
+   chattable (answers from training until slice 3). No code.
+2. **Auto-TTS** — `tts.py` (gateway client + pad_to_dials) + `/api/tts` proxy + the
+   index.html 🔊 toggle + speak-on-done playback + serialize/cancel. Visible: she's voiced,
+   affect-modulated. TDD (respx-mock the gateway; live smoke on the console).
+3. **KB-bridge** — `kb_bridge.py` + the one server.py seam. Visible: she recalls the DCC
+   corpus in-voice. TDD. RETIRE-READY per INV-KB-1.
+
+Out of scope: true audio streaming (DEC-2), custom voice registration (DEC-8, infra-ops
+follow-up), extending the bridge to non-interview agents.
diff --git a/persistent-memory.d/2026-08-01-donut-voiced-interview-build.md b/persistent-memory.d/2026-08-01-donut-voiced-interview-build.md
new file mode 100644
index 0000000..61467ab
--- /dev/null
+++ b/persistent-memory.d/2026-08-01-donut-voiced-interview-build.md
@@ -0,0 +1,78 @@
+# Donut voiced-interview build — ACTIVE (auto-TTS via Zonos + KB-recall bridge + Princess Donut)
+
+`[2026-08-01]` Operator asked: "add auto-tts to the ratatoskr web gui" → grew into a voiced,
+corpus-grounded Tier-3 interview character. Contract:
+`docs/contracts/donut_voiced_interview.contract.md` (validated). Slice 1 DONE; slices 2-3 TO BUILD.
+Operator ruling: **build it today, but design the KB path to RETIRE** (it works around a Worldtree
+gap — Tier-3 agents are tool-less by design; KB search is integral, so the gap should close).
+
+## Slice status
+
+- **SLICE 1 (persona) DONE** — `docs/characters/donut.md` authored (corpus-grounded from a Mimir
+  pull + DCC canon: interview-register performer, "Carl looks intimidating while I talk," vulnerability
+  under a good question, and the "pinned corpus = her own memory" framing). **Defined:**
+  `ratatoskr:donut` (role `thoughtful-character`) live on personal :8081, in the console picker.
+  Chattable now (from training until slice 3). NOT yet committed (uncommitted at snapshot).
+- **SLICE 2 (auto-TTS) TO BUILD** — new `src/ratatoskr/tts.py` (Zonos gateway client + `pad_to_dials`) +
+  `/api/tts` proxy route in `web/server.py` + `index.html` (🔊 toggle, speak-on-`done` playback,
+  serialize/cancel). TDD (respx-mock the gateway), live-smoke.
+- **SLICE 3 (KB-bridge) TO BUILD** — new `src/ratatoskr/kb_bridge.py` (RETIRE-READY, INV-KB-1) +
+  the one server.py seam. Per interview turn: out-of-band Mimir consult → extract evidence →
+  POST Donut's turn with `memory_context=[{kind:"corpus_reference", text:"<extract>"}]`. She answers
+  in-voice. TDD.
+
+## Design — LOCKED (both external deps verified live 2026-08-01)
+
+**TTS (infra-ops Zonos specs, verified):**
+- Endpoint: `POST http://10.100.79.3:8890/v1/audio/speech` (the zonos GATEWAY at irv-ml1:8890 — NOT
+  the engine's :1920, which has a rep-penalty bug). Also GET /v1/voices, /v1/dials, /health. WG-internal,
+  **no auth**. Reachable from nh3-dev (the console box) over WireGuard.
+- Request: JSON, only `input` required. `response_format:"wav"` (16-bit RIFF; **mp3/opus silently
+  fall back to mislabeled PCM — never use**). Verified: voice=donut → HTTP 200, RIFF/WAVE PCM 16-bit
+  mono 44.1kHz.
+- **NOT streaming** — gateway buffers to a complete clip (~1.8s/sentence). "Speak on done" gives the
+  whole clip after the synth delay. True streaming = a future gateway enhancement (infra-ops can raise).
+- **Voice: `voice:"donut"` is ALREADY REGISTERED** (infra-ops cloned Vuong's Princess Donut bundle;
+  GET /v1/voices returns Donut; case-folded so "Donut.wav"→voice:"donut"). Custom-voice registration
+  mechanism: drop a `<Name>.wav` (44.1kHz mono 16-bit, ~10-20s clean single-speaker) in the gateway
+  voices dir + restart. Audition A/B: http://10.100.10.50:8090/b/donut-voice/
+- **Affect-driven emotion (DEC-7, the standout):** map the turn's live PAD (from the `affect_update`
+  SSE the console ALREADY consumes) → Zonos `emotion_valence`(pleasure)+`emotion_arousal`(arousal).
+  Reframes the feature as voice OBSERVABILITY (hear the affect the persona pane shows), NOT chat-app
+  creep — resolves the scope concern. Dials also: `preset`, `emotion_sliders{happy,sad,angry,surprised}`,
+  `emotion_strength`, `speed`, `seed`.
+- **Coupling: direct :8890** (DEC-1) for the emotion dials; the swappable LiteLLM `ext-tts` alias
+  (10.250.50.70:4000) loses the Zonos emotion params. `tts.py` is the single swap seam.
+- **Serialize** one synth per turn (DEC-5) — shared 3090 ~90% VRAM; cancel-on-new-turn.
+- **Proxy** (DEC-4): browser → `/api/tts` (nh3-dev) → gateway; never surface irv-ml1 to the client.
+
+**KB-recall (worldtree-dev ruling, wyrd-proven):**
+- Tier-3 is DELIBERATELY tool-less in v1 (`build_tier3_agent_context` hard-codes `tool_schemas=[]`);
+  no search_kb grant, no call-Mimir-as-tool (#361 rejected it, recursion). So: **consumer-side
+  retrieval + memory_context pinning** — ratatoskr consults Mimir out-of-band, extracts the cited
+  evidence, pins `memory_context=[{kind:"corpus_reference", text}]` on Donut's turn. She frames it as
+  her own memory (the persona prompt already instructs this). Our SDK's stream_turn already forwards
+  `memory_context` verbatim. Latency: one retrieval round-trip/turn.
+- **RETIRE-READY (INV-KB-1):** kb_bridge behind ONE seam `pin_kb_context(question, agent_id) ->
+  list|[]`; retiring = delete the module + one call-site. Delete when Worldtree #361
+  `reference_knowledge` extends to Tier-3 (operator flagged it an integral GAP; worldtree-dev surfacing
+  the extension to Vuong — decision inbound to the operator).
+
+## OWED / open loops (post-clear)
+
+- **P&P verification re-run OWED to infra-ops** — #382 deployed (b166: self-describing `_index.md` +
+  the Mimir prompt rule "hits ARE library content, never discard/substitute"). Re-run the failing
+  P&P-dismiss shape on :8081, report to infra-ops. **DCC's backfill FAILED** (job predates state-tracking,
+  no `_index.md` yet — flagged to worldtree-dev) — but the prompt rule alone should stop the discard,
+  so the KB-bridge's DCC Mimir consults should ground fine. Verify this when building slice 3.
+- **worldtree-dev #361-Tier-3 extension** — an inbound surface decision for Vuong (would let Donut
+  search in-voice + delete the bridge).
+- **infra-ops custom-voice** — mechanism proven; hand them a `<Name>.wav` + name for any future character.
+
+## Discipline
+
+Operator said "do both slices" (skip /heid-contract-review, straight to TDD). Run heid code-review +
+bug-hunt AFTER each code slice. Release-only versioning cadence (no per-commit tags; `feat:`/`fix:`
+conventional commits between releases). CLI to drive Mimir/Donut turns:
+`ratatoskr --send "..." --new --agent <id> --end-user-id ratatoskr-tui`. Define:
+`python -m ratatoskr.tier3 define --name <slug> --system-prompt "<prompt>" --role thoughtful-character`.
diff --git a/persistent-memory.md b/persistent-memory.md
index b837652..772cfd8 100644
--- a/persistent-memory.md
+++ b/persistent-memory.md
@@ -1,6 +1,6 @@
 # Persistent memory — ratatoskr
 
-_Last updated: 2026-07-19_
+_Last updated: 2026-08-02_
 
 > **Always check for `/tmp/ratatoskr-dev-handoff.md`** — if it exists and its
 > `Written:` stamp is under an hour old, read it (it carries the in-flight
@@ -44,37 +44,36 @@ upstream API key stays server-side (INV-003).
 
 ## Current state / in-flight
 
-_As of 2026-07-19:_
+_As of 2026-08-01:_
 
-**✅ COMPLETE — worldtree-sdk cutover (issue #20): ALL 7 SLICES DONE, shipped as v0.22.0 (2026-07-19).**
-Ratatoskr's CONSUMER client layer is fully cut over from hand-rolled httpx wrappers to **worldtree-sdk (Python)
-1.0.0** behind the thin `ratatoskr.wt` adapter (operator ADOPT ruling 2026-07-18; 6 DECs, vor-cross'd +
-heid-panel-reviewed; contract `docs/contracts/worldtree_sdk_cutover.contract.md` with slice-1..7 notes canonical).
-Six route-family slices (foundation / sessions-turn / persona-authored / agents-tier3 / characters-me / admin) +
-slice-7 teardown, each through the full House Code Discipline (adapter→cli/web→delete→live-smoke→both heid gates).
-Suite **494 green**. Per-slice arcs → `persistent-memory.d/2026-07-19-worldtree-sdk-cutover-slice-{1-2,3,4,5,6,7}-complete.md`.
-**Slice-7 teardown** (`ec68b1f`, v0.22.0, zero runtime-logic): dropped `httpx-sse` (SDK owns SSE parsing; venv
-pruned, nothing imported it); KEPT `sessions.py`+`sse_client.py` as pure caller-semantic type/exception homes
-(operator decision A1 — no rename/fold; A3 blocked by the `AgentNotAvailable` name-collision + `endpoint_for_plane`
-provider-homing); retired wire contracts #2/#15 (files deleted; **#1 SSE-vocab + first_message KEPT**, not retired);
-final coverage-map re-anchor.
-**KEY ADAPTER FOOT-GUNS (cumulative — still live for ANY future consumer/SDK work):** SDK reads = **open-world
-dicts**, presenters MUST degrade-not-crash guarded at THREE levels — **container-type** (`isinstance(_, list)`: a
-scalar `123` is non-iterable, `or []` catches null but NOT a truthy non-iterable), **element-type**
-(`isinstance(m, dict)`), **top-level-mapping** (`isinstance(_, Mapping)` before any `.get`); never hard-index. The
-SDK **normalizes ANY transport failure to `ConnectFailed(status=0)`** (not raw httpx) — every adapter caller
-`except ConnectFailed`. **Caller-semantic exceptions the adapter raises + a `-m` CLI catches must NOT live in the
-`-m` module** (double-module class-identity split → uncaught traceback; homed in `sessions.py`, never run as
-`__main__`). `TurnEvent.turn_id` ABSENT on text/thinking frames; `consumer_key` is BOUND-create-only. Scope was
-consumer layer ONLY; Bifrost provider untouched. Design → auto-memory `project_worldtree_sdk_cutover`.
+**🔨 ACTIVE BUILD — Donut voiced-interview (auto-TTS + KB-recall + Princess Donut). RESUME HERE post-clear.**
+Operator ask "add auto-tts to the web gui" grew into a voiced, corpus-grounded Tier-3 interview character.
+**Slice 1 DONE** (persona `docs/characters/donut.md` authored + `ratatoskr:donut` defined + in the picker);
+**slices 2 (Zonos auto-TTS) + 3 (retire-ready KB-bridge) TO BUILD** — operator: "build both today." Contract
+`docs/contracts/donut_voiced_interview.contract.md` (validated). Both external deps verified live 2026-08-01
+(Zonos `voice:"donut"` REGISTERED + returns wav; the KB-recall pattern is worldtree-dev-ruled — consumer-side
+retrieval + `memory_context` pinning, retire-ready). **FULL build state / design specs / owed items →
+`persistent-memory.d/2026-08-01-donut-voiced-interview-build.md`.** OWED: a P&P verification re-run to infra-ops
+(#382 fix deployed b166).
 
-**▶️ POST-CUTOVER PENDING (non-blocking, operator's call):** (a) `git push` origin — the `ec68b1f` commit +
-**v0.22.0 tag are LOCAL only**; (b) althing announce of v0.22.0 to worldtree-dev / wtsdk-dev per the SemVer
-push-notify (post-push; Rata is the SDK reference consumer). Nothing else pending on the cutover.
+**✅ SHIPPED + PUSHED since v0.22.0 (origin at `14bbc2b`):** the worldtree-sdk cutover (#20, **v0.22.0**, 7 slices,
+494 green — the big one) + **bifrost 1.1.5** (`3ef3a5e`, **v0.22.1**) + **worldtree-sdk 1.0.0→1.1.1→1.1.2**
+(`d3a36f7`+`0058020` — path-encoding correctness fix + the SSE turn-stream traversal WE caught in their fix) +
+**canonical sync** (`14bbc2b` — added the client-spec-v2 pin, synced OpenAPI/spec forward, additive within the
+FROZEN v1 wire). The webui runs the current build (v0.22.1) live on :8765 (relaunched this session).
 
-**✅ RESOLVED — tier3 agents `model`→`role` (scope B) folded into cutover slice-4** (`c62b4ee`, v0.21.13). The
-deferred deploy-gated scope-B work (response `model`→`role` per spec 1.2 / b128, `LocalAgentEntry`, index schema
-v2) landed with the agents-family SDK cutover — no longer pending. See the slice-4 detail file + Recent decisions.
+**⚙️ VERSIONING CADENCE CHANGED → release-only (operator-ratified 2026-07-30).** Retired per-commit bump+tag;
+version+tag at RELEASES only; between releases, `feat:`/`fix:` conventional-commit SHAs. Tier-bar + minor/major
+approval still apply, at release. Existing ~112 tags left as-is (leave-and-change-forward). (Global CLAUDE.md
+SemVer §amended to match; this OVERRIDES the per-commit-bump mechanics still described there.)
+
+**KEY ADAPTER/CONSUMER FOOT-GUNS (cumulative, still live):** SDK reads = open-world dicts → presenters degrade-not-
+crash at THREE guard levels (container-type `isinstance(_,list)` / element-type `isinstance(m,dict)` / top-level
+`isinstance(_,Mapping)` before `.get`); SDK normalizes ALL transport failures to `ConnectFailed(status=0)` → every
+caller `except ConnectFailed`; caller-semantic exceptions a `-m` CLI catches must NOT live in the `-m` module
+(class-identity split; homed in `sessions.py`). **The `local_agents` index schema v1→v2 bump SILENTLY DROPS
+pre-cutover consumer agents from the picker** (buried Sindra — `load_local_agents` returns [] on version mismatch;
+fix = migrate v1→v2 from authoritative WT data). Cutover design → auto-memory `project_worldtree_sdk_cutover`.
 
 **✅ RESOLVED — the "app product" workstreams leave Rata entirely (operator 2026-07-18).**
 **No arbo fork, no SillyTavern-on-Rata** — a NEW repo (template-dev standing up) takes over BOTH
@@ -286,6 +285,14 @@ decision. Captures rationale that won't be obvious from code alone.
 
 - `[2026-07-19]` **worldtree-sdk cutover SLICE-7 (teardown, the LAST) COMPLETE — the whole cutover shipped as v0.22.0 (`ec68b1f`, minor, operator-approved).** Zero runtime-logic teardown: httpx-sse dropped (SDK owns SSE), wire contracts #2/#15 retired (files deleted; #1+first_message kept), `sessions.py`/`sse_client.py` KEPT as pure type/exception homes (operator decision A1 — no rename/fold), coverage-map re-anchored. All 7 slices done, 494 green; push + althing-announce pending (operator's call). → `persistent-memory.d/2026-07-19-worldtree-sdk-cutover-slice-7-complete.md`
 
+- `[2026-07-19→08-01]` **Donut voiced-interview BUILD — auto-TTS via Zonos + retire-ready KB-recall bridge + Princess Donut.** Slice-1 done (persona + define); slices 2-3 to build; both external deps verified live. THE active work. → `persistent-memory.d/2026-08-01-donut-voiced-interview-build.md`
+- `[2026-08-01]` **worldtree-sdk 1.0.0→1.1.1→1.1.2 repin — and a reference-consumer catch.** 1.1.1's path-encoding fix MISSED the inline `turn_stream.py:185` on the SSE path (caller-shaped session_id, our highest-traffic route); wtsdk-dev fixed it in 1.1.2 same-day. (`d3a36f7`+`0058020`, pushed.)
+- `[2026-08-01]` **Mimir #382 grounding bug — our finding shaped the fix.** Rata caught that the #380 vector re-index left Mimir DISCARDING correct P&P hits (no named source in the fiction wing → agent distrusts its own hits + answers from training; a silent-substitution "reasoning move, not retrieval"). Fix = our proposed residual (self-describing `_index.md`) + a Mimir prompt rule; deployed b166. **P&P verification re-run OWED to infra-ops**; DCC dir still opaque (backfill failed, flagged to worldtree-dev).
+- `[2026-08-01]` **Canonical sync — added the client-spec-v2 pin (option A) + synced OpenAPI/spec forward** (`14bbc2b`, pushed). Whole-manifest sync also bumped the OpenAPI hard-gate additively (frozen v1 wire → no breakage). Coverage-map re-audit vs the new surface = queued follow-up.
+- `[2026-07-30]` **Versioning cadence → RELEASE-ONLY (operator-ratified, brokkr-smithy relayed).** Retired per-commit bump+tag; tag only releases; between releases `feat:`/`fix:` SHAs. Existing ~112 tags left as-is. Global CLAUDE.md SemVer being amended to match.
+- `[2026-08-01]` **bifrost 1.1.4→1.1.5 (v0.22.1, `3ef3a5e`, pushed)** — optional-store-verb 500→`unsupported_capability` hardening; provider restarted onto it.
+- `[2026-08-01]` **Sindra saga — restored from local-index burial, wiped, smoke-tested.** The v0.22.0 web restart dropped her live session AND the schema-v2 discard buried her from the picker; migrated her v1→v2 from authoritative WT (real role `thoughtful-character`, not the stale `mistral-small-4`), then `scripts/reset-sindra-stores.sh` wiped memory+persona for a from-scratch smoke.
+
 _67 older entries (2026-05-* debug-TUI/web era + the 2026-06-14 → 06-18 Bifrost-provider build / #17+#18 / #295-296 era) archived to archival-memory.md._
 
 _For per-issue TDD implementation notes, Volva findings, and contract amendments, see the git log — every per-issue commit carries a structured message capturing the trail._
@@ -330,4 +337,7 @@ defense against re-attempting the same cul-de-sac.
 
 - `[2026-07-16]` **`sortable_chunk_fields` advertised WITHOUT the required `type` field = whole-handshake deploy-breaker; only DRIVING the real bind caught it** → `persistent-memory.d/2026-07-16-sortablechunkfields-advertised-without-the-re.md`
 
+- `[2026-08-01]` **`local_agents` index schema v1→v2 bump SILENTLY buries pre-cutover consumer agents from the picker** — `load_local_agents` returns `[]` on version mismatch (no migration path); the v0.22.0 restart made Sindra vanish even though she was alive on WT. Fix applied ad-hoc: migrate the v1 row → v2 from authoritative WT data (the v1 `model` field held a stale model name, NOT the current role). A one-time v1→v2 migration guard is the durable fix (unbuilt; operator-flagged).
+- `[2026-08-01]` **Zonos: mp3/opus `response_format` silently return mislabeled PCM** (no encoder wired) — use `response_format:"wav"` only. And use the GATEWAY :8890, NOT the engine :1920 (rep-penalty bug pads ~70s silence + ignores voice).
+
 _34 older entries (2026-05-* debug-TUI/web era + the 2026-06-14 → 06-18 foot-gun cluster) archived to archival-memory.md._