Refactor wake phrase handling: introduce REQUIRE_WAKE_WORD configuration, update documentation, and adjust assistant behavior for improved user experience.

README.md

@@ -1,14 +1,15 @@
 # Bolt Assistant
 
-A voice assistant for Bolt. Say **"Hey Bolt"** (or "Bolt", "Thunderbolt", "Hey Assistant" and a few
-others), ask something, and Bolt answers through your speakers. It uses the same server, memory and
-persona as Bolt-Pet, Bolt Console and the phone app.
+A voice assistant for Bolt. While the mic is open, just ask something — there's no wake word — and
+Bolt answers through your speakers. If you'd rather activate it by voice, set
+`REQUIRE_WAKE_WORD=true` and say **"Hey Bolt"** (or "Bolt", "Thunderbolt", "Hey Assistant" and a few
+others) first. It uses the same server, memory and persona as Bolt-Pet, Bolt Console and the phone
+app.
 
 ```
-Listening for "Hey Bolt" (or "Thunderbolt", "Hey Assistant"). Ctrl+C to quit.
+Listening - anything you say is a request. Ctrl+C to quit.
 > what time is it
 < It's quarter past three.
-* Yes?
 > what's in my downloads folder
   file list: C:\Users\aaron\Downloads
 < You've got three installers and a PDF called taxes.
@@ -32,8 +33,11 @@ other than the system default. `run.bat --type` lets you type instead of speak,
    Silence, hum and clicks are never sent anywhere. When it hears something that sounds like
    talking, that stretch of audio is sent to your server's `/desk/stt` relay (Deepgram, as in
    Bolt-Pet) and transcribed as you speak.
-2. **Only transcripts that start with a wake phrase count.** "Hey Bolt, what time is it" asks "what
-   time is it". "I need to tighten the bolt" is ignored, because the phrase has to open what you say,
+2. **Every transcript is a request.** With `REQUIRE_WAKE_WORD` off (the default) the mic being open
+   is the activation: whatever the detector hears is sent to Bolt. A wake phrase said anyway ("Hey
+   Bolt, what time is it") is stripped, and the rest is the request. With `REQUIRE_WAKE_WORD=true`,
+   only transcripts that start with a wake phrase count: "Hey Bolt, what time is it" asks "what time
+   is it", and "I need to tighten the bolt" is ignored because the phrase has to open what you say,
    with at most a filler word such as "um" or "okay" before it. Saying just "Hey Bolt" plays a chime,
    and whatever you say in the next 8 seconds is the request.
 3. **The answer is spoken** through the server's `/desk/tts`, one sentence at a time as Bolt
@@ -44,15 +48,16 @@ other than the system default. `run.bat --type` lets you type instead of speak,
 
 ## Cost and privacy
 
-The server's speech-to-text is what recognises the wake phrase, so **everything said near the mic
-that sounds like speech is sent to your server and transcribed**, not just things said to Bolt. The
-server counts this against your credits like a chat turn. The local detector keeps that to actual
-speech: silence is never sent, and bursts shorter than `MIN_UTTERANCE_SEC` are dropped. In a room
-with a TV or a lot of conversation, it will still transcribe a lot.
+The server's speech-to-text is what turns what you say into a request, so **everything said near the
+mic that sounds like speech is sent to your server and transcribed** — and, with the wake word off,
+answered. The server counts this against your credits like a chat turn. The local detector keeps
+that to actual speech: silence is never sent, and bursts shorter than `MIN_UTTERANCE_SEC` are
+dropped. In a room with a TV or a lot of conversation, it will still transcribe and answer a lot.
 
-If that becomes a problem, the alternative is on-device wake-word detection, which is what Bolt-Pet
-does with openWakeWord and its `thunderbolt.onnx` model. Nothing leaves the machine until the wake
-word is heard, but it only recognises the phrases it was trained on.
+If that becomes a problem, set `REQUIRE_WAKE_WORD=true` so only speech that starts with the wake
+phrase is sent on. The alternative is on-device wake-word detection, which is what Bolt-Pet does with
+openWakeWord and its `thunderbolt.onnx` model. Nothing leaves the machine until the wake word is
+heard, but it only recognises the phrases it was trained on.
 
 ## What Bolt may do on this machine
 
@@ -70,9 +75,12 @@ Anything that isn't allowed is refused, and Bolt is told to say he can't do it h
 
 See `.env.example`. The ones you're most likely to change:
 
+- `REQUIRE_WAKE_WORD`: `false` (default) answers anything said near the open mic; `true` requires a
+  wake phrase before each request.
 - `VAD_RMS_THRESHOLD`: raise it if background noise keeps getting transcribed, lower it if you
   have to raise your voice.
-- `WAKE_WORDS`: the phrases, comma-separated.
+- `WAKE_WORDS`: the phrases, comma-separated (needed to activate Bolt when `REQUIRE_WAKE_WORD=true`;
+  said anyway, they're still stripped from the request).
 - `ANYWHERE_WAKE_WORDS`: words that count anywhere in a sentence, not just at the start
   (default `assistant`: "what's the weather, assistant?"). Blank to turn off.
 - `COMMAND_WAIT_SEC`, `FOLLOW_UP_SEC`: how long it waits after "Hey Bolt", or after asking you