docs: wake button usage and feature record

README.md

@@ -19,6 +19,7 @@ noctalia msg plugins enable loki/headsetcontrol
 - **Bar widget:** shows battery level. Scroll to adjust sidetone, click to open the control panel.
 - **Control center tile:** toggles sidetone on/off.
 - **Control panel:** full device controls. Controls appear only for capabilities the headset reports.
+- **Wake button (panel):** headsets that sleep while idle (e.g. Audeze Maxwell) stop reporting the battery. The panel's Wake button plays a short tone to wake the headset, then refreshes the battery reading. The panel header also shows whether the headset is connected.
 
 ## Settings
 
@@ -29,6 +30,7 @@ noctalia msg plugins enable loki/headsetcontrol
 | Default sidetone | 64 | Level used before any manual adjustment |
 | Device (VID:PID) | *(auto)* | Force a device, e.g. `3329:4b19` |
 | Mock device | off | Simulate a headset for development without hardware |
+| Wake-up audio sink | *(default output)* | PulseAudio/PipeWire sink for the wake tone (find names with `pactl list short sinks`) |
 
 ## Development
 

docs/superpowers/plans/2026-08-31-headsetcontrol-plugin.md

@@ -1298,3 +1298,10 @@ git commit -m "docs: README, license, and store thumbnail"
 - `plugin.toml` panel declares `dismiss_on_outside_click = true` explicitly (matches the design spec; default is already true).
 - Panel shows a `panel.no_caps` hint when no capability control is rendered.
 - Panel sidetone default reads `sidetone_default` config (not a hardcoded 64).
+
+**Wake-Button feature (implemented after the original 8 tasks):**
+- `headsetcontrol/sounds/wake.wav` — 2s very quiet tone (generated via python3 stdlib, committed); playback end ≈ headset awake.
+- `plugin.toml`: `wake_sink` setting (string, default ""); each entry passes it through `hsc.init` (Noctalia gives each entry its own module instance, so without this the setting would be dead in widget/panel/shortcut).
+- `lib/hsc.luau`: `M.wake(cb)` (paplay with optional `--device=`, pw-play `-d` fallback, cb(ok)); `M.fetchConnected(cb)` (parses `headsetcontrol --connected` true/false output; verified live).
+- `panel.luau`: connection-status label in header (connected/disconnected/empty); `caps.battery`-gated Wake button (disabled while waking); `onWake` plays tone, re-reads status, publishes battery/chatmix to the shared channel (widget benefits immediately), refreshes connection status. Forward `local render` declaration (also fixes the same latent nil-global bug on all pre-existing `send` success paths).
+- Live verification: audio through the Maxwell sink transitioned the real device from `BATTERY_UNAVAILABLE`/`--connected false` to `BATTERY_AVAILABLE 94%`/`true` — the feature premise holds.