feat(assistant): overlay for the voice assistant

Reads desktop-assistant's event socket, JSON lines on a Unix socket the
assistant owns: state, context use, the running tool and audio levels.
A circle shows the name and used/total context, a wrench and the tool
name while one runs, and pulsing dots while it transcribes or thinks.
Around it three sine ripples follow the loudness, the user's voice and
the reply in two palette colours from Theme, so a udt change recolours
them live. It fades out a configurable delay after the reply.

The ripple is driven by FrameAnimation, not a Timer: a 16 ms Timer
drifted against the display refresh and visibly stuttered. Standalone
like the other components; it reconnects every 2 s while the assistant
is down, and the assistant runs the same without it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 17 insertions, 0 deletions

diff --git a/assistant/README.md b/assistant/README.md
new file mode 100644
index 0000000..9c989cf
--- /dev/null
+++ b/assistant/README.md
@@ -0,0 +1,17 @@
+# assistant
+
+Overlay for desktop-assistant, the local voice assistant. It appears when the
+mic button is pressed and shows the assistant's name, its model context use,
+the tool running, and a ring of sound waves that follows the real audio: the
+user's voice in one palette colour, the reply in another. It fades out a few
+seconds after the reply.
+
+The assistant owns a Unix socket, `$XDG_RUNTIME_DIR/desktop-assistant.sock`,
+and writes one JSON event per line (`hello`, `state`, `ctx`, `level`); this
+component only reads it and reconnects every 2 s while the assistant is down.
+Name, position, fade delay and the two colour roles come from the
+assistant's `config.toml` `[overlay]` table, in the `hello` event. The
+protocol is specified in the desktop-assistant repo,
+`docs/superpowers/specs/2026-09-26-overlay-design.md`.
+
+Run: `qs -p <this dir>`. Test the position maths: `node assistant/test_place.js`.