docs: plan for TTS dash-strip + spoken opening + treasure align; refresh CLAUDE.md (voice/awareness/presence, new gotchas, mirror-first deploy)

CLAUDE.md

@@ -14,10 +14,11 @@ A horror NPC chatbot for the **Build Small Hackathon** (HF / Gradio). Track:
 ## Stack (decided — do not reopen)
 - **UI:** Gradio 6.x `gr.Blocks` + `gr.Chatbot` (messages format default, no `type` param). Pure CSS, **no JS**.
 - **Model:** `Qwen/Qwen3-8B` via `transformers`+`@spaces.GPU(duration=90)` on Space; `qwen3:8b` via Ollama (`localhost:11434`) locally. Switch: `IS_SPACE = bool(os.environ.get("SPACE_ID"))`.
+- **Voice:** Kokoro-82M TTS (`voice.py`), **CPU** — the child whispers (`af_nicole`, speed 0.88, "28% fog" numpy DSP). Import-guarded → **silent if unavailable** (local 3.13 `.venv` has no kokoro; works in 3.12 `.venv-tts` and on the Space at py3.11). Audio inlined as autoplay `<audio>` in a mounted-but-CSS-collapsed `voice_panel`. Plays on every Hollow reply + all finale lines.
 - **State:** plain dict in `gr.State` per session. **Parsing:** Pydantic v2 + fallback.
 - **Art:** grayscale FLUX portraits (Fear & Hunger style) in `assets/`, base64 WebP. Audio synthesized in numpy at import (`sting.py`).
-- **Pkg manager:** `uv` (`uv pip install`).
-- **Rejected (don't reopen):** Gemma 4 12B (no fit in 8 GB local VRAM, re-tuning risk, no prize upside); LangGraph, Qdrant, cloud APIs, fine-tuning.
+- **Pkg manager:** `uv` (`uv pip install`). Space build also needs `packages.txt` (espeak-ng) + `python_version: "3.11"` (Kokoro needs <3.13).
+- **Rejected (don't reopen):** Gemma 4 12B (no 8 GB VRAM fit); **Qwen3.5/3.6 (all multimodal → break the transformers loader; the field uses 1-8B, so 8B stays on-brand)**; LangGraph, Qdrant, cloud APIs, fine-tuning, sponsor-model swap (re-tuning risk for speculative prize).
 
 ## Submission requirements (verified, Field Guide REQ-06)
 - Space in the org ✅. README frontmatter: track + badge tags + write-up ✅ (`track:wood`, `achievement:offgrid/offbrand/fieldnotes`). **No submission form — the Space in the org with a complete README IS the entry.**
@@ -26,19 +27,20 @@ A horror NPC chatbot for the **Build Small Hackathon** (HF / Gradio). Track:
 
 ## File structure
 ```
-app.py        # Gradio layout (3 cols: entity|chat|treasure); chat() generator; _play_finale / _play_finale_bad / _play_finale_good; _PENDING typing bubble; show_progress="hidden" on events
-engine.py     # run_turn(chat_messages, user_msg) -> (reply, raw_json); _EXTRACTION_SYSTEM prompt; IS_SPACE backend switch; repetition_penalty on reply gen
-character.py  # build_system_prompt(...); _PERSONA tiers; tone bands; OWN_FRAGMENTS + FRAGMENT_TONES; OPENING_LINE
-memory.py     # get_tier, apply_update (+ JSON sanitize/Hollow-words filter/fallback), should_recall, decide_ending — all state logic, pure
-finale.py     # finale_steps (loop), finale_steps_bad (wound), finale_steps_good (redemption) — pure data scripts
-render.py     # render_entity(affinity, mode, seq), render_treasure(...) — pure HTML; embeds base64 art + chime audio
-schemas.py    # TurnUpdate(affinity_delta, new_memories, tone_delta, cruel_quote) + clamp/clean validators
-sting.py      # sting_wav_bytes() + chime_wav_bytes(idx) — numpy audio synth (HF rejects committed .wav)
-styles.css    # horror CSS. Sections: 15 entity, 16 treasure, 17 stone frames, 18 endings, 19 hide Gradio progress, 20 typing dots, 21 button press
+app.py        # thread-cap (OMP/OPENBLAS=4) at top; Gradio layout (3 cols: entity|chat|treasure + hidden voice_panel); chat() generator; 3 _play_finale_*; _PENDING bubble; _on_idle (gr.Timer); _toggle_voice (mute); _voice_html/_voice_and_pause; show_progress="hidden"
+voice.py      # speak(text)->base64 wav|None — Kokoro-82M whisper + locked DSP, CPU, import-guarded; thread-cap; _clean_for_tts (planned)
+engine.py     # run_turn(chat_messages, user_msg) -> (reply, raw_json); _EXTRACTION_SYSTEM; IS_SPACE switch; repetition_penalty on reply gen
+character.py  # build_system_prompt(... tone, wounds, ask_for_memory, own_fragment, style, aware_memory); tone bands; OWN_FRAGMENTS; OPENING_LINE
+memory.py     # get_tier, apply_update (+sanitize/Hollow-words filter), should_recall, decide_ending, style_signal (B3), pick_aware_memory (B2) — pure
+finale.py     # finale_steps (loop), finale_steps_bad (wound), finale_steps_good (redemption) — pure data; each has a "frenzy" convulse stage
+render.py     # render_entity(affinity, mode, seq) — modes: idle/flash/flash_strong/build/frenzy/convulse_good/convulse_loop/end/end_settle/rage/peace/peace_settle/peace_dissolve; materialization = fog+brightness (no blur); render_treasure(...)
+sting.py      # _wav + sting/chime/heartbeat/sigh/flatline _wav_bytes — numpy audio synth (HF rejects committed .wav)
+styles.css    # horror CSS §15-22 (22 = finale build pulse + soft convulse + restart + .voice-channel)
 assets/       # hollow_{base,terror,almost,end,rage,peace}.webp  (rage = almost copy placeholder; peace = real art)
-tests/        # 166 tests: test_{memory,render,finale,schemas,engine,character,app}.py
-docs/superpowers/{specs,plans}/   # approved design specs + executed implementation plans
-tools/pacing_sim.py               # plays scripted visitors through real Ollama, reports per-turn state — pacing tuning
+requirements.txt / packages.txt   # +kokoro/misaki[en]/soundfile/spacy/en_core_web_sm; espeak-ng (apt)
+tests/        # 204 tests: test_{memory,render,finale,schemas,engine,character,app,sting,voice}.py
+docs/superpowers/{specs,plans}/   # approved specs + plans (latest pending: 2026-06-13-tts-greeting-treasure-align)
+tools/pacing_sim.py               # scripted visitors through real Ollama — pacing tuning
 ```
 
 ## State shape (gr.State) — all NEW-field reads use `.get(...)` for pre-deploy sessions
@@ -55,6 +57,11 @@ tools/pacing_sim.py               # plays scripted visitors through real Ollama,
   "fragments_told": int,      # how many OWN_FRAGMENTS surfaced (redemption path)
   "ended": bool,              # a finale fired — input dead
   "ending": str | None,       # "good"|"loop"|"bad" once fired
+  "voice_on": bool,           # mute toggle (🔊/🔇)
+  "msg_lengths": list[int],   # B3 — rolling word counts (cap 5) for style_signal
+  "last_aware_memory": str|None,  # B2 — avoid re-surfacing the same memory
+  "last_activity": float,     # idle clock; stamped by _start_turn + chat()
+  "idle_count": int,          # how many idle nudges fired (tier + bond decay)
 }
 ```
 Dev seed: `HOLLOW_FAST_FINALE=good|loop|bad` (`1`/`neutral` alias→ good/loop) — each ending fires on the 2nd message.
@@ -76,6 +83,11 @@ Single gate so no lower threshold can race a warm run:
 - Tone bands in prompt (separate from ending routing): warm ≥15 / wounded −22..−1 / hostile ≤−22 (injects wounds). Mimicry always on.
 - **Measured pacing** (pacing_sim, real model): bad ~msg 6, good (warm) ~msg 10, loop (factual) ~msg 12, seeds msg 2. Warm play tone climbs to ~27; factual play tone stalls ~13 — clean gap at 20.
 
+## Voice + Presence (the child speaks & watches)
+- **Voice:** every Hollow reply + all finale lines are spoken (Kokoro, CPU). Finale `_voice_and_pause` stretches each step's pause to the audio length (+0.15 s) so lines aren't cut. Recall + finale = the wow. Mute toggle (🔊/🔇) mutates `voice_on` in place + clears `voice_panel`.
+- **Awareness (B1/B2/B3):** B3 `style_signal` (Hollow notices short/long messages); B2 `pick_aware_memory` (resurfaces an earlier memory unprompted, every 3rd non-recall turn); B1 `_on_idle` (`gr.Timer` 4 s) — after `_IDLE_AFTER=35 s` of silence Hollow speaks first, escalating plead→hurt→hostile (`_IDLE_TIERS`) and each nudge drops affinity −3 / tone −2 (timer outputs `bond_panel` so the meter falls live).
+- **Materialization:** the child is **sharp, veiled in fog + shadow** (brightness 0.4→1, fog/vig denser at low bond) — NOT blurred (blur read as a broken image).
+
 ## Gotchas / lessons (DON'T re-learn these the hard way)
 - **Verify CSS against the RUNNING app**, never the static harness — it lacks Gradio's cascade and has lied. Workflow: launch `HOLLOW_FAST_FINALE=good .venv/Scripts/python app.py` background → headless Chrome screenshot (`chrome.exe --headless --disable-gpu --screenshot=... --window-size=1900,950 --virtual-time-budget=12000 http://localhost:7860`) → Read the PNG → kill the port owner.
 - **Gradio replaces the HTML DOM each update:** CSS *animations* restart (this IS the flash/screamer mechanism); CSS *transitions* DON'T animate across updates.
@@ -83,7 +95,7 @@ Single gate so no lower threshold can race a warm run:
 - **Qwen emits `+2` (invalid JSON)** if examples lack positive anchors → every positive turn fell back to delta 0 (bond frozen). Fixed by sanitizer in `apply_update` + explicit "no leading +" instruction + dual examples. Keep both.
 - **transformers 5.x:** `apply_chat_template(...,return_tensors="pt")` returns `BatchEncoding` (use `hasattr(t,"input_ids")`); use `dtype=` not deprecated `torch_dtype`. Qwen3 thinking OFF: `enable_thinking=False` (Space) / `"think": False` (Ollama).
 - **One GPU acquisition per turn:** gen + extract inside a single `@spaces.GPU` call. ZeroGPU ≈8 s/turn, PRO ≈1500 s/day.
-- **Portrait fills the arch:** art is square (1:1), arch is 5:6 → materialization is blur/opacity ONLY, never `scale` (left an ugly gap). Opacity floor 0.55 + ground-mist gradient + `!important` img sizing (Gradio base reset wins otherwise).
+- **Portrait fills the arch:** art is square (1:1), arch is 5:6 → materialization is brightness/opacity/fog ONLY, never `scale` (left an ugly gap). **No CSS `blur`** — it read as a broken/loading image; the child is sharp, veiled in shadow+fog. `!important` img sizing (Gradio base reset wins otherwise).
 - **HF rejects committed binaries (.wav):** synthesize audio at runtime (`sting.py`). Same would apply to any new binary asset that isn't an image.
 - **Don't edit `.py` via PowerShell string ops** — it mangled UTF-8 (em-dash → mojibake) once. Use the Edit tool.
 - **Ollama ROCm can corrupt** (`cudaMalloc failed` with free VRAM) → symptom is red Error on ALL components. Fix: restart Ollama (tray + server). The Space (transformers) is immune.
@@ -92,14 +104,22 @@ Single gate so no lower threshold can race a warm run:
 - **NO threading around `run_turn`:** `@spaces.GPU` needs the main request context — a thread pool breaks ZeroGPU. The typing-dots animation is pure CSS for this reason (don't "fix" it with a worker thread).
 - **Hide Gradio progress, animate our own:** `show_progress="hidden"` on the events kills the per-component "processing | Xs" overlay (CSS class-hiding was unreliable); we render our own `_PENDING` typing bubble. The HTML span + class survives Gradio's markdown sanitizer (verified) so §20 CSS animates it.
 - **Live-verify via isolated probe:** to test a UI behavior that only appears mid-generation (typing dots, button states), spin a tiny throwaway Gradio app importing `styles.css`, screenshot it, delete it — don't guess CSS class names.
+- **Cap CPU math threads before torch loads** (`OMP/OPENBLAS/MKL_NUM_THREADS=4` at the top of `app.py`+`voice.py`). On many-core machines under memory pressure OpenBLAS spawns one buffer-hungry thread/core and the CPU allocator fails (`DefaultCPUAllocator: not enough memory` on a tiny alloc, with GBs free) → Kokoro silently disabled. NOT real RAM exhaustion.
+- **`voice_panel` must stay MOUNTED** (`elem_classes="voice-channel"` + CSS collapse to 0 size), NOT `visible=False` — an invisible Gradio component can unmount so the `<audio>` never reaches the DOM and never plays. Voice audio goes here, NEVER in the entity panel (would break the heartbeat's byte-identical HTML).
+- **The idle `gr.Timer` must not race the chat generator:** `_start_turn` outputs `state` (activity stamp persists across the event boundary) and `_on_idle` no-ops if a `_PENDING` "..." bubble is in flight — else it orphans the bubble / clobbers a streaming finale. Non-speaking ticks return `gr.update()` (never `""`) for chatbot/voice.
+- **Browser autoplay blocks audio before the visitor's first gesture** — the opening line can't auto-speak on load; it's voiced on the first message instead. Same reason the chimes are silent until you interact.
+- **Kokoro deps:** import-guarded (silent fallback, never crashes). Needs python <3.13, `misaki[en]`→`spacy`+`en_core_web_sm`, `espeak-ng` (apt). Local: 3.12 `.venv-tts` for voice; the 3.13 `.venv` runs silent (fine for tests, which mock `speak`). TTS verbalizes dashes → strip them (`_clean_for_tts`, planned).
+- **Ollama 500 = the ROCm `cudaMalloc` corruption** (see above), NOT our code — a short prompt may pass while a real 300-token turn 500s. Symptom in-app: every reply is the "fog swallowed your words" fallback. Fix: restart Ollama (kill `ollama.exe` + `ollama app.exe`, reopen). The Space (transformers) is immune.
 
 ## What's next
-- **Placeholder art (Pablo, FLUX):** `hollow_rage.webp` is still a copy of `hollow_almost` — works fine, optional to replace. (`hollow_peace` is real now.) To swap a real PNG: `Image.open(png).convert("RGB").resize((512,512),LANCZOS).save(webp,"WEBP",quality=80,method=6)`. Pure asset swap. Guides in Pablo's Obsidian vault.
-- **Pablo to playtest:** the 3 natural-play scripts (verified by pacing_sim) — warm→redemption ~msg 10, factual→loop ~msg 12, cruel→bad ~msg 6. Note anything to tune; today is the last code day.
-- **Frames (open, blocked on Pablo):** decide A) keep current stone arch, or B) no frame (dissolve to void). Rejected so far: gold/bone, vines, clean+weathered stone, 4 soft-edge directions — vector frames fight the raster art + floating aesthetic. Don't iterate blind again.
-- **Deliverables (Sun):** demo video (horror-trailer), social post (portrait-evolution grid), Field Notes. Add links to README. **Mon:** submit early + community vote.
+- **Current work is on branch `feat/voice-awareness`, NOT deployed.** Both Spaces are frozen at the pre-voice commit (`4deeed5`) — the submission stays safe while we iterate. Voice + awareness + presence-polish are committed on the branch (204 tests green). Deploy is **mirror-first**: merge → push `space` → verify build+voice live → push `hackathon`.
+- **Pending plan:** `docs/superpowers/plans/2026-06-13-tts-greeting-treasure-align.md` — strip dashes from TTS, speak the opening on the first message, align the Treasure panel with the entity frame.
+- **`FIELD_NOTES.md`** lives in the repo (📓 badge content). Field Notes done; the demo video + LinkedIn post are Pablo's, link both from the README when ready.
+- **Optional art:** `hollow_rage.webp` is still a copy of `hollow_almost` (works fine). Swap a PNG: `Image.open(png).convert("RGB").resize((512,512),LANCZOS).save(webp,"WEBP",quality=80,method=6)`.
+- **Deliverables (Pablo):** demo video (horror-trailer), social post. **Mon June 15:** submit early + community vote.
 
 ## Workflows
-**Deploy** (from repo root, `.venv` active): `git add … && git commit -m "…" && git push space main && git push hackathon main`. After push, wait ~2 min for rebuild, then **Ctrl+F5** on the Space (cache serves the old build otherwise). Commit trailer: `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+**Deploy** (from repo root): **mirror-first** — `git push space main` → wait ~3-4 min (Kokoro/spacy build is heavy), **Ctrl+F5**, verify build+voice live → only then `git push hackathon main`. If the mirror build breaks, the submission stays untouched. Commit trailer: `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+**Local voice test:** the 3.13 `.venv` is silent (no kokoro); run from `.venv-tts` (py3.12) for voice, with Ollama running for real replies.
 
 **Working style:** phase by phase; explain *why* before code; everything in **English** (code, prompts, UI, dialogue); no new deps/complexity without asking; push back on scope creep. Subagent-driven dev for plans (implementer + spec review + quality review per task).

docs/superpowers/plans/2026-06-13-tts-greeting-treasure-align.md

@@ -0,0 +1,170 @@
+# TTS Cleanup + Spoken Opening + Treasure Alignment — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan phase-by-phase. Steps use checkbox (`- [ ]`). Stay on git branch `feat/voice-awareness`.
+
+**Goal:** Three fixes. (1) The TTS pronounces dashes (`—`, `-`) as words — strip them from spoken text. (2) Speak the opening line at the start of the chat (greeting that asks for a memory). (3) Align the Treasure panel with the child's frame for visual symmetry.
+
+**Context:** Branch `feat/voice-awareness`. Voice via Kokoro (`voice.py`, `speak()`), works in the 3.12 `.venv-tts`, silent/guarded in the 3.13 `.venv`. Voice plays on every Hollow reply and on finale lines, from a hidden-but-mounted `voice_panel`. Run tests: `.venv/Scripts/python -m pytest -q` (204 green — keep them green). Voice smoke test runs in `.venv-tts`.
+
+---
+
+## PHASE 1 — Strip dashes from TTS input
+
+**Files:** Modify `voice.py`, `tests/test_voice.py`.
+
+The displayed text keeps its stylistic dashes (e.g. "i don't—"); only the text sent to Kokoro is cleaned, so it stops saying "dash".
+
+- [ ] **Step 1: Failing test** (append to `tests/test_voice.py`):
+
+```python
+def test_clean_for_tts_strips_dashes():
+    assert "—" not in voice._clean_for_tts("i don't— i don't remember")
+    assert "-" not in voice._clean_for_tts("a well-kept secret")
+    # collapses to single spaces, trims
+    assert voice._clean_for_tts("a  —  b") == "a , b"
+```
+
+- [ ] **Step 2: Run, verify fail** — `.venv/Scripts/python -m pytest tests/test_voice.py -k clean_for_tts -q`.
+
+- [ ] **Step 3: Implement** in `voice.py`. Add `import re` near the top (after the `os` thread-cap block). Add the helper and use it in `speak()`:
+
+```python
+def _clean_for_tts(text: str) -> str:
+    """Kokoro verbalizes dashes ('—', '-') as words. Replace em/en dashes with a
+    comma pause and hyphens with a space, then collapse whitespace."""
+    text = text.replace("—", ", ").replace("–", ", ").replace("-", " ")
+    return re.sub(r"\s+", " ", text).strip()
+```
+
+In `speak()`, change the synthesis loop to use the cleaned text:
+```python
+        cleaned = _clean_for_tts(text)
+        if not cleaned:
+            return None
+        audio = None
+        for _, _, chunk in _PIPELINE(cleaned, voice=_VOICE, speed=_SPEED):
+            audio = chunk if audio is None else np.concatenate([audio, chunk])
+```
+(Keep the early `if _PIPELINE is None or not text or not text.strip(): return None` guard as-is at the top of `speak()`.)
+
+- [ ] **Step 4: Run** `tests/test_voice.py -k clean_for_tts` then the full suite → green.
+
+- [ ] **Step 5: Commit**
+```bash
+git add voice.py tests/test_voice.py
+git commit -m "fix: strip dashes from TTS input (Kokoro was saying 'dash')
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+## PHASE 2 — Speak the opening line on the first turn
+
+**Files:** Modify `app.py`, `tests/test_app.py`.
+
+Browser autoplay can't fire before a user gesture, so the opening can't be spoken on page load. Instead: on the visitor's FIRST message (the first gesture), Hollow speaks the OPENING_LINE (it matches the opening text shown at the top of the chat), and that first reply is text-only so the greeting isn't cut. From the second turn on, replies are voiced as normal.
+
+- [ ] **Step 1: Failing tests** (append to `tests/test_app.py`, class `TestVoice`):
+
+```python
+    def test_first_turn_speaks_the_opening_line(self, monkeypatch):
+        captured = {}
+        def fake_speak(text):
+            captured["text"] = text
+            return "FAKEB64"
+        monkeypatch.setattr(app, "run_turn",
+                            lambda *a, **k: ("a normal reply.", '{"affinity_delta":1}'))
+        monkeypatch.setattr(app.time, "sleep", lambda s: None)
+        monkeypatch.setattr(app, "should_recall", lambda s: (False, None))
+        monkeypatch.setattr(app, "speak", fake_speak)
+        state = _state(affinity=20, treasure=[], claimed=[], tone=0, turn=0)
+        outs = list(app.chat("hello", state, []))
+        assert "FAKEB64" in outs[-1][7]                 # the greeting is voiced
+        assert captured["text"] == OPENING_LINE         # ...with the opening line
+
+    def test_second_turn_speaks_the_reply(self, monkeypatch):
+        captured = {}
+        monkeypatch.setattr(app, "run_turn",
+                            lambda *a, **k: ("a normal reply.", '{"affinity_delta":1}'))
+        monkeypatch.setattr(app.time, "sleep", lambda s: None)
+        monkeypatch.setattr(app, "should_recall", lambda s: (False, None))
+        monkeypatch.setattr(app, "speak", lambda t: captured.setdefault("text", t) or "FAKEB64")
+        state = _state(affinity=20, treasure=[], claimed=[], tone=0, turn=3)  # not first
+        list(app.chat("hi again", state, []))
+        assert captured["text"] == "a normal reply."     # later turns voice the reply
+```
+
+- [ ] **Step 2: Run, verify fail** — both currently voice the reply.
+
+- [ ] **Step 3: Implement** in `app.py` `chat()`. Near the TOP of the normal-turn path (before `state["turn"] += 1` runs), capture whether this is the first turn:
+```python
+    is_first_turn = state["turn"] == 0
+```
+Then where the voice is computed for the final normal-turn yield, replace:
+```python
+    voice = _voice_html(speak(reply)) if state.get("voice_on", True) else ""
+```
+with:
+```python
+    # on the visitor's first message, Hollow speaks the opening line (its
+    # greeting/memory-ask, matching the text at the top of the chat); that
+    # first reply stays text-only so the greeting isn't cut. Browser autoplay
+    # can't fire before this first gesture, so this is the earliest it can play.
+    if state.get("voice_on", True):
+        voice = _voice_html(speak(OPENING_LINE if is_first_turn else reply))
+    else:
+        voice = ""
+```
+(`OPENING_LINE` is already imported in `app.py`.)
+
+- [ ] **Step 4: Run** the Voice tests then the full suite → green.
+
+- [ ] **Step 5: Commit**
+```bash
+git add app.py tests/test_app.py
+git commit -m "feat: speak the opening line on the visitor's first message
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+## PHASE 3 — Align the Treasure panel with the child's frame (symmetry)
+
+**Files:** Modify `styles.css` (and `app.py` only if a wrapper class is needed). Visual — verify against the running app.
+
+The entity panel (left, the child in the stone arch) and the Treasure panel (right) should share the same top edge and read as a symmetric pair framing the chat. Today the Treasure panel sits slightly off.
+
+- [ ] **Step 1: Observe the current misalignment.** Launch and screenshot:
+  - `HOLLOW_FAST_FINALE=good .venv/Scripts/python app.py` (background), headless Chrome screenshot (per the CLAUDE.md workflow), Read the PNG. Note the vertical offset between the top of the entity arch and the top of the Treasure box, and any height mismatch. Kill the port owner.
+
+- [ ] **Step 2: Read the relevant CSS.** In `styles.css`, find the entity section (the `.entity-portal` / `.entity-frame` rules) and the treasure section (`.treasure-panel`). Note their top margins/padding. In `app.py`, the layout is a `gr.Row` of three `gr.Column`s: entity (scale 1), chat (scale 2), treasure (scale 1). Gradio columns add their own padding/gap.
+
+- [ ] **Step 3: Align.** Adjust CSS so the Treasure panel's top aligns with the entity arch's top (and, if it reads better, match their heights). Likely a top-margin/padding tweak on `.treasure-panel` or its Gradio column, mirroring whatever offset the entity panel has. Keep the horror styling intact. Do NOT use fixed pixel heights that break on resize unless necessary — prefer matching the existing offsets.
+
+- [ ] **Step 4: Verify (REQUIRED — CSS lies in the harness).** Re-launch, screenshot, Read the PNG: the entity arch and the Treasure box should now share a top edge and look symmetric. Iterate until aligned. Kill the port owner.
+
+- [ ] **Step 5: Commit**
+```bash
+git add styles.css app.py
+git commit -m "style: align the Treasure panel with the entity frame (symmetry)
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+## FINAL — verification
+
+- [ ] **Step 1:** `.venv/Scripts/python -m pytest -q` → all green.
+- [ ] **Step 2: Voice smoke** (`.venv-tts`): `python -c "import voice; print(voice._clean_for_tts('a—b—c')); print(bool(voice.speak('hello, i am here.')))"` → cleaned text (no dashes) + `True`.
+- [ ] **Step 3: Live local test** (`.venv-tts`, Ollama running): the opening line is spoken on the first message; no "dash" pronounced anywhere; the Treasure box lines up with the child's frame.
+- [ ] **Step 4: Deploy mirror-first** (orchestrator, with the user's go-ahead): merge `feat/voice-awareness` → `main`, push to `space` (mirror), verify the build + voice live, then push to `hackathon` (submission).
+
+---
+
+## Self-review notes
+- Dash stripping is TTS-only — the displayed dialogue keeps its stylistic dashes.
+- The opening voice is tied to the first SEND (the first gesture autoplay allows); if the visitor never sends, the idle "speak first" still covers presence.
+- The treasure alignment is visual — never trust the static harness; screenshot the running app.