VoiceWake: capture utterance and add prefix

docs/mac/voicewake.md

@@ -0,0 +1,28 @@
+# Voice Wake Pipeline
+
+Updated: 2025-12-08 · Owners: mac app
+
+## Runtime behavior
+- Always-on listener (Speech framework) waits for any trigger word.
+- On first trigger hit: start capture, raise ears immediately via `AppState.triggerVoiceEars(ttl: nil)`, reset capture buffer.
+- While capturing: keep buffer in sync with partial transcripts; update `lastHeard` whenever audio arrives.
+- End capture when 1.0s of silence is observed (or 8s hard stop), then call `stopVoiceEars()`, prepend the voice-prefix string, send once to Claude, and restart the recognizer for a clean next trigger. A short 350ms debounce prevents double-fires.
+
+## Visual states
+- **Listening for trigger:** idle icon.
+- **Wake word detected / capturing:** ears enlarged with holes; stays up until silence end, not a fixed timer.
+- **After send:** ears drop immediately when silence window elapses; icon returns to idle.
+
+## Forwarding payload
+- Uses `VoiceWakeForwarder.prefixedTranscript(_:)` to prepend the model hint:
+  `User talked via voice recognition on <machine> - repeat prompt first + remember some words might be incorrectly transcribed.`
+- Machine name resolves to Host.localizedName or hostName; caller can override for tests.
+
+## Testing hooks
+- Settings tester mirrors runtime: same capture/silence flow, same prefix, same ear behavior.
+- Unit test: `VoiceWakeForwarderTests.prefixedTranscriptUsesMachineName` covers the prefix format.
+
+## Tuning knobs (swift constants)
+- Silence window: 1.0s (`silenceWindow` in `VoiceWakeRuntime`).
+- Hard stop after trigger: 8s (`captureHardStop`).
+- Post-send debounce: 0.35s (`debounceAfterSend`).