Add implementation plan for the assistant overlay

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

1 files changed, 1000 insertions, 0 deletions

diff --git a/docs/superpowers/plans/2026-09-26-overlay.md b/docs/superpowers/plans/2026-09-26-overlay.md
new file mode 100644
index 0000000..fdb05a7
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-26-overlay.md
@@ -0,0 +1,1000 @@
+# Assistant Overlay Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A quickshell overlay that shows the assistant's state, context use, running tool and real audio levels, fed by a JSON-lines Unix socket the assistant owns; ignored presses send a notification instead.
+
+**Architecture:** `assistant.py` gains a socket broadcaster (stdlib `socket` + threads), state/ctx/level events at the points the voice loop already passes through, a playback-clocked level emitter for the reply, and `notify-send` for ignored presses. A new standalone component `assistant/` in the quickshell repo connects to the socket and draws the circle and the wave ring. With no overlay running, the assistant behaves exactly as before.
+
+**Tech Stack:** Python 3.12 stdlib (+ numpy, already present through kokoro-onnx), `notify-send`, Quickshell 0.3.1 QML (`Quickshell.Io.Socket`, `Canvas`), node for the QML library test.
+
+**Spec:** `docs/superpowers/specs/2026-09-26-overlay-design.md`
+
+**Conventions (both repos):**
+- No em dashes. No personal data or home paths in committed files (gitleaks hooks enforce it). GPLv2-only header in every new source file.
+- Commits GPG-signed (default config), `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>` at the end, pushed after each commit. Commit only with the user's go-ahead for this plan's work.
+- desktop-assistant self-check: `python3 assistant.py --test` prints `ok`.
+- quickshell repo: read its `AGENTS.md` first. Process is `qs` (never `pkill -f`, never `pkill -x qs`, which kills every component: stop only this one with `qs kill -p <dir>`). A detached `qs` dies with the agent's tool call: run it as a harness-owned background command and read its log. For anything visual, ask the user. Commit subjects there use the `feat(component): ...` style.
+
+**Deviation from the spec, decided while planning:** `speaking` is emitted by the reply thread when it queues the first sentence of an answer (and again after a tool round), not by the speaker when audio starts. If the speaker emitted it, the tool announcement would overwrite the `tool` state and hide the tool icon while the tool is still running. `idle` still comes from the speaker when the reply's audio has finished.
+
+---
+
+## File structure
+
+| File | Repo | Status | Responsibility |
+|------|------|--------|----------------|
+| `assistant.py` | desktop-assistant | modify | level maths, events socket, notifications, wiring |
+| `examples/config.toml`, `README.md`, `AGENTS.md` | desktop-assistant | modify | `[overlay]` options, docs, findings |
+| `assistant/shell.qml` | quickshell | create | shell root |
+| `assistant/Assistant.qml` | quickshell | create | socket client, state, overlay window |
+| `assistant/Place.js`, `assistant/test_place.js` | quickshell | create | position maths and its node test |
+| `assistant/Theme.qml` | quickshell | symlink | `-> ../shared/Theme.qml` (repo rule: never a copy) |
+| `assistant/README.md` | quickshell | create | what it is, protocol pointer, run/test |
+
+---
+
+### Task 1: level maths
+
+**Files:** Modify `assistant.py` (imports, constants after `TOOL_SCHEMA`, helpers after `latin()`, `test()`)
+
+- [ ] **Step 1: failing test.** Append to `test()` before `print("ok")`:
+
+```python
+    import numpy as np
+    assert scale(0) == 0.0 and scale(1) == 0.0            # -90 dBFS clamps to 0
+    assert scale(32768) == 1.0
+    assert abs(scale(32768 * 10 ** (-30 / 20)) - 0.5) < 1e-9
+    assert pcm_level(b"") == 0.0
+    assert pcm_level(array.array("h", [1000] * 100).tobytes()) == scale(1000)
+    assert pcm_level(b"\x00") == 0.0                      # half a sample is ignored
+    env = envelope(np.zeros(24000, dtype=np.float32), 24000)
+    assert len(env) == 30 and max(env) == 0.0             # 1 s at 30 frames/s
+    env = envelope(np.full(24000, 0.5, dtype=np.float32), 24000)
+    assert all(abs(v - scale(16384)) < 1e-6 for v in env)
+```
+
+- [ ] **Step 2:** Run `python3 assistant.py --test`. Expected: `NameError: name 'scale' is not defined`.
+
+- [ ] **Step 3: implement.** Add `import array` (before `import ctypes`) and `import math` (after `import json`) to the imports.
+
+After `TOOL_SCHEMA = schema(TOOLS) or None` add:
+
+```python
+FRAME = 1 / 30                            # one audio level per frame, seconds
+```
+
+After `latin()` add:
+
+```python
+def scale(rms):
+    # Loudness as the overlay draws it: -60 dBFS and below is 0, full scale
+    # is 1. Logarithmic, so quiet speech still moves the ring.
+    if rms <= 0:
+        return 0.0
+    return max(0.0, min(1.0, (20 * math.log10(rms / 32768) + 60) / 60))
+
+
+def pcm_level(data):
+    # 16-bit little-endian mono, as arecord writes it; a trailing odd byte is
+    # half a sample and ignored.
+    samples = array.array("h", data[: len(data) // 2 * 2])
+    if not samples:
+        return 0.0
+    return scale(math.sqrt(sum(s * s for s in samples) / len(samples)))
+
+
+def envelope(audio, sr):
+    # One level per FRAME of float audio in -1..1 (Kokoro's output).
+    n = int(sr * FRAME)
+    frames = audio[: len(audio) // n * n].reshape(-1, n)
+    return [scale(float(r) * 32768) for r in (frames.astype("float64") ** 2).mean(axis=1) ** 0.5]
+```
+
+- [ ] **Step 4:** Run `python3 assistant.py --test`. Expected: `ok`.
+
+- [ ] **Step 5: commit**
+
+```bash
+git add assistant.py
+git commit -m "Compute audio levels for the overlay
+
+Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
+git push
+```
+
+---
+
+### Task 2: say why a press was ignored
+
+**Files:** Modify `assistant.py` (`presenting()`, new `notify_ignored()`, `main()`, `test()`)
+
+- [ ] **Step 1: failing test.** In `test()`, replace the existing presenting block:
+
+```python
+    with tempfile.TemporaryDirectory() as d:
+        assert not presenting(d)
+        for name, value, want in (("gaming", "1", True), ("gaming", "0", False),
+                                  ("presentation", "1\n", True)):
+            with open(os.path.join(d, f"status.{name}"), "w") as f:
+                f.write(value)
+            assert presenting(d) == want, (name, value)
+```
+
+with:
+
+```python
+    with tempfile.TemporaryDirectory() as d:
+        assert presenting(d) == ""
+        for name, value, want in (("gaming", "1", "gaming"), ("gaming", "0", ""),
+                                  ("presentation", "1\n", "presentation")):
+            with open(os.path.join(d, f"status.{name}"), "w") as f:
+                f.write(value)
+            assert presenting(d) == want, (name, value)
+```
+
+- [ ] **Step 2:** Run `python3 assistant.py --test`. Expected: `AssertionError` (`presenting` returns `False`, not `""`).
+
+- [ ] **Step 3: implement.** In `presenting()`, replace `return flag("presentation") or flag("gaming")` with:
+
+```python
+    # Why the press is ignored, for the notification; "" when it is not.
+    return "gaming" if flag("gaming") else "presentation" if flag("presentation") else ""
+```
+
+After `presenting()` add:
+
+```python
+notify_id = ""
+
+
+def notify_ignored(reason):
+    # Normal urgency: DND (on during presentation mode) holds it back from
+    # popping over a call or a game, and it waits in the notification list.
+    # Each press replaces the last (-r), so one game makes one entry.
+    global notify_id
+    cmd = ["notify-send", "-a", "desktop-assistant", "-u", "normal", "-p"]
+    if notify_id:
+        cmd += ["-r", notify_id]
+    cmd += ["Voice assistant paused", f"The button press was ignored: {reason} mode is on."]
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    notify_id = r.stdout.strip() or notify_id
+```
+
+In `main()`, replace:
+
+```python
+            if on and presenting():
+                log("presentation mode: ignored")
+            elif on:
+```
+
+with:
+
+```python
+            reason = presenting() if on else ""
+            if reason:
+                log(f"{reason} mode: ignored")
+                notify_ignored(reason)
+            elif on:
+```
+
+- [ ] **Step 4:** Run `python3 assistant.py --test`. Expected: `ok`. Then check the notification by hand: `python3 -c "import assistant as a; a.notify_ignored('gaming'); a.notify_ignored('gaming'); print(a.notify_id)"`. Expected: an id printed, and one "Voice assistant paused" notification (the second replaced the first; with DND on it is in the drawer list, not popped). Ask the user to confirm there is one entry, not two.
+
+- [ ] **Step 5: commit**
+
+```bash
+git add assistant.py
+git commit -m "Notify when a press is ignored in presentation or gaming mode
+
+Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
+git push
+```
+
+---
+
+### Task 3: events socket
+
+**Files:** Modify `assistant.py` (`DEFAULTS`, imports, new block after `notify_ignored()`, `ask()`, `test()`)
+
+- [ ] **Step 1: failing test.** Append to `test()` before `print("ok")`:
+
+```python
+    import socket
+    a, b = socket.socketpair()
+    a.setblocking(False)
+    clients.append(a)
+    emit({"type": "ctx", "used": 1, "max": 2})
+    assert json.loads(b.recv(4096)) == {"type": "ctx", "used": 1, "max": 2}
+    emit({"type": "state", "state": "tool", "tool": "search"})
+    assert now_state == {"state": "tool", "tool": "search"}
+    b.recv(4096)
+    b.close()
+    emit({"type": "state", "state": "idle"})             # the dead client is dropped
+    emit({"type": "state", "state": "idle"})
+    assert a not in clients and now_state == {"state": "idle"}
+    with tempfile.TemporaryDirectory() as d:
+        path = os.path.join(d, "s.sock")
+        serve(path)
+        assert os.stat(path).st_mode & 0o777 == 0o600
+        c = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        c.connect(path)
+        f = c.makefile()
+        first = json.loads(f.readline())
+        assert first["type"] == "hello" and first["name"] == CFG["overlay"]["name"]
+        assert first["state"] == "idle" and "ctx_max" in first
+        for _ in range(100):                             # accept() appends just after hello
+            if clients:
+                break
+            time.sleep(0.01)
+        emit({"type": "level", "who": "user", "value": 0.5})
+        assert json.loads(f.readline()) == {"type": "level", "who": "user", "value": 0.5}
+        c.close()
+```
+
+- [ ] **Step 2:** Run `python3 assistant.py --test`. Expected: `NameError: name 'clients' is not defined`.
+
+- [ ] **Step 3: implement.** Add `import socket` (after `import signal`) and `import urllib.parse` (after `import unicodedata`).
+
+In `DEFAULTS`, after `"env": {},` add:
+
+```python
+    "overlay": {"name": "Assistant", "position": "center", "hide_delay": 3.0,
+                "user_color": "accent", "assistant_color": "green"},
+```
+
+After `FRAME = ...` add:
+
+```python
+SOCK = os.path.join(os.environ.get("XDG_RUNTIME_DIR", "/tmp"), "desktop-assistant.sock")
+```
+
+After `notify_ignored()` add:
+
+```python
+# The overlay's feed: JSON lines on a Unix socket, one event per line. With
+# no client connected every event is dropped, so the voice loop never waits
+# on a UI.
+clients, clients_lock = [], threading.Lock()
+now_state = {"state": "idle"}             # repeated in hello for a late client
+ctx = {"model": None, "max": 0}           # context size of the model in use
+
+
+def emit(event):
+    if event["type"] == "state":
+        now_state.clear()
+        now_state.update({k: v for k, v in event.items() if k != "type"})
+    line = (json.dumps(event) + "\n").encode()
+    with clients_lock:
+        for c in clients[:]:
+            try:
+                c.sendall(line)           # non-blocking: a stalled client errors
+            except OSError:
+                clients.remove(c)
+                c.close()
+
+
+def hello():
+    return {"type": "hello", **CFG["overlay"], "ctx_max": ctx["max"], **now_state}
+
+
+def serve(path=SOCK):
+    try:
+        os.unlink(path)                   # left over from a crash
+    except FileNotFoundError:
+        pass
+    srv = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    old = os.umask(0o177)                 # 0600: only this user reads the stream
+    try:
+        srv.bind(path)
+    finally:
+        os.umask(old)
+    srv.listen()
+
+    def accept():
+        while True:
+            c, _ = srv.accept()
+            try:
+                c.sendall((json.dumps(hello()) + "\n").encode())
+            except OSError:
+                c.close()
+                continue
+            c.setblocking(False)
+            with clients_lock:
+                clients.append(c)
+    threading.Thread(target=accept, daemon=True).start()
+
+
+def context_size(model):
+    # The router can swap models, so ask again whenever the id changes.
+    if ctx["model"] != model:
+        url = f"{CFG['llm'].removesuffix('/v1')}/props?model={urllib.parse.quote(model)}"
+        try:
+            with urllib.request.urlopen(url, timeout=5) as r:
+                ctx["max"] = json.load(r)["default_generation_settings"]["n_ctx"]
+        except (OSError, KeyError, ValueError):
+            ctx["max"] = 0
+        ctx["model"] = model
+    return ctx["max"]
+```
+
+In `ask()`, replace:
+
+```python
+    body = {"model": llm_model(), "messages": messages, "stream": True,
+```
+
+with:
+
+```python
+    model = llm_model()
+    context_size(model)
+    body = {"model": model, "messages": messages, "stream": True,
+```
+
+and replace:
+
+```python
+                log(f"context: {chunk['usage']['prompt_tokens']} prompt tokens")
+```
+
+with:
+
+```python
+                used = chunk["usage"]["prompt_tokens"]
+                log(f"context: {used} prompt tokens")
+                emit({"type": "ctx", "used": used, "max": ctx["max"]})
+```
+
+- [ ] **Step 4:** Run `python3 assistant.py --test`. Expected: `ok`. Then: `python3 -c "import assistant as a; print(a.context_size(a.llm_model()))"`. Expected: `32768` with the resident Gemma.
+
+- [ ] **Step 5: commit**
+
+```bash
+git add assistant.py
+git commit -m "Broadcast assistant events on a Unix socket for the overlay
+
+Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
+git push
+```
+
+---
+
+### Task 4: emit state and levels from the voice loop
+
+**Files:** Modify `assistant.py` (`speaker()`, new `user_levels()` and `level_emitter()`, `reply()`, `main()`)
+
+- [ ] **Step 1: user levels and the emitter.** After `speaker()` add:
+
+```python
+def user_levels(rec, mine):
+    # The user's waves: the loudness of what arecord wrote since last time.
+    pos = 0
+    while rec.poll() is None and turn == mine:
+        time.sleep(FRAME)
+        try:
+            with open(RAW, "rb") as f:
+                f.seek(pos)
+                data = f.read()
+        except OSError:
+            continue
+        if len(data) >= 2:
+            pos += len(data) // 2 * 2
+            emit({"type": "level", "who": "user", "value": pcm_level(data)})
+
+
+def level_emitter(lq):
+    # The reply's waves, each frame sent when its audio plays rather than when
+    # it was synthesised (synthesis runs ahead of playback).
+    while True:
+        t, due, value = lq.get()
+        while t == turn and (wait := due - time.monotonic()) > 0:
+            time.sleep(min(wait, 0.05))
+        if t == turn:
+            emit({"type": "level", "who": "assistant", "value": value})
+```
+
+- [ ] **Step 2: speaker clock.** Change `def speaker(q):` to `def speaker(q, lq):`. Replace `    play, playing = None, None            # aplay and the turn it speaks for` with:
+
+```python
+    play, playing = None, None            # aplay and the turn it speaks for
+    start, written = 0.0, 0               # playback clock of the open stream
+```
+
+Replace the end-of-reply block:
+
+```python
+            if item is None:              # end of reply
+                if play:
+                    play.stdin.close()
+                    play.wait()
+                    play = None
+                continue
+```
+
+with:
+
+```python
+            if item is None:              # end of reply
+                if play:
+                    play.stdin.close()
+                    play.wait()
+                    play = None
+                if t == turn:
+                    emit({"type": "state", "state": "idle"})
+                continue
+```
+
+Replace the silence block's write line `                    play.stdin.write(bytes(int(sr * item) * 2))` with:
+
+```python
+                    play.stdin.write(bytes(int(sr * item) * 2))
+                    written += int(sr * item)
+```
+
+Replace:
+
+```python
+                playing, player = t, play
+                # A new stream wakes the suspended sink and the first ~0.2 s is
+                # lost: lead with silence so it eats that, not the first word.
+                play.stdin.write(bytes(int(sr * 0.3) * 2))
+            # The pipe buffer lets synthesis of the next sentence overlap playback.
+            play.stdin.write((audio.clip(-1, 1) * 32767).astype("<i2").tobytes())
+```
+
+with:
+
+```python
+                playing, player = t, play
+                # A new stream wakes the suspended sink and the first ~0.2 s is
+                # lost: lead with silence so it eats that, not the first word.
+                play.stdin.write(bytes(int(sr * 0.3) * 2))
+                start, written = time.monotonic() + 0.3, 0
+            # This sentence plays after everything written so far. If synthesis
+            # fell behind (an underrun), playback restarts from now.
+            # ponytail: no sound-server latency correction; add an offset here
+            # if the waves visibly lead the voice.
+            now = time.monotonic()
+            if start + written / sr < now:
+                start = now - written / sr
+            due = start + written / sr
+            for i, value in enumerate(envelope(audio, sr)):
+                lq.put((t, due + i * FRAME, value))
+            written += len(audio)
+            # The pipe buffer lets synthesis of the next sentence overlap playback.
+            play.stdin.write((audio.clip(-1, 1) * 32767).astype("<i2").tobytes())
+```
+
+- [ ] **Step 3: reply states.** In `reply()`:
+
+Replace:
+
+```python
+    if len(pcm) < 16000 * 2 * 0.3:               # under 0.3 s: a stray press
+        return
+```
+
+with:
+
+```python
+    if len(pcm) < 16000 * 2 * 0.3:               # under 0.3 s: a stray press
+        emit({"type": "state", "state": "idle"})
+        return
+```
+
+Replace `    t = time.perf_counter()\n    lang, text = stt()` (the first two lines of the STT part) with:
+
+```python
+    emit({"type": "state", "state": "transcribing"})
+    t = time.perf_counter()
+    lang, text = stt()
+```
+
+Replace:
+
+```python
+    if not text or text.startswith("[") or turn != mine:   # [BLANK_AUDIO] and friends
+        return
+```
+
+with:
+
+```python
+    if turn != mine:
+        return
+    if not text or text.startswith("["):         # [BLANK_AUDIO] and friends
+        emit({"type": "state", "state": "idle"})
+        return
+```
+
+After the line `    log(f"you ({lang}, {time.perf_counter() - t:.2f}s): {text}")` add:
+
+```python
+    emit({"type": "state", "state": "thinking"})
+```
+
+In `say(s)`, before `said.append(s)` add:
+
+```python
+        if now_state["state"] != "speaking":
+            emit({"type": "state", "state": "speaking"})
+```
+
+Replace:
+
+```python
+        for c in calls.values():
+            result = run_tool(TOOLS, c["name"], c["arguments"])
+```
+
+with:
+
+```python
+        for c in calls.values():
+            emit({"type": "state", "state": "tool", "tool": c["name"]})
+            result = run_tool(TOOLS, c["name"], c["arguments"])
+```
+
+After that `for` loop (after its last line `            msgs.append({"role": "tool", "tool_call_id": c["id"], "content": result})`) add, at the tool loop's indentation level inside the rounds loop:
+
+```python
+        if turn == mine:
+            emit({"type": "state", "state": "thinking"})
+```
+
+- [ ] **Step 4: main.** In `main()`:
+
+After `    start_whisper()` add `    serve()`.
+
+Replace:
+
+```python
+    q = queue.Queue()
+    threading.Thread(target=speaker, args=(q,), daemon=True).start()
+```
+
+with:
+
+```python
+    q, lq = queue.Queue(), queue.Queue()
+    threading.Thread(target=speaker, args=(q, lq), daemon=True).start()
+    threading.Thread(target=level_emitter, args=(lq,), daemon=True).start()
+```
+
+In the `elif on:` branch, after `                    player.kill()` (the barge-in kill) add `                emit({"type": "state", "state": "listening"})`, and after the `rec = subprocess.Popen([...arecord...])` statement add:
+
+```python
+                threading.Thread(target=user_levels, args=(rec, turn), daemon=True).start()
+```
+
+In the `finally:` block, change `        for f in (RAW, WAV):                    # the user's voice: never keep it` to:
+
+```python
+        for f in (RAW, WAV, SOCK):              # the user's voice: never keep it
+```
+
+- [ ] **Step 5:** Run `python3 assistant.py --test` and `python3 -m py_compile assistant.py`. Expected: `ok`.
+
+- [ ] **Step 6: check the stream live.** Restart the running assistant (stop its background task, start `python3 -u assistant.py` again as a harness-owned background command with the log tee'd to the scratchpad). In a second harness-owned background command run `socat -u UNIX-CONNECT:$XDG_RUNTIME_DIR/desktop-assistant.sock - | grep --line-buffered -v '"level"' | tee <scratchpad>/events.log` (levels filtered to keep it readable) and count levels separately with `socat -u UNIX-CONNECT:... - | grep -c level` over one question. Ask the user for a search question. Expected sequence in events.log: `hello`, `listening`, `transcribing`, `thinking`, `ctx`, `tool` with `"tool": "search"`, `thinking`, `ctx`, `speaking`, `idle`. Expected levels: user frames during the press, assistant frames during speech, roughly 30 per second of each. Also check barge-in still works by ear.
+
+- [ ] **Step 7: commit**
+
+```bash
+git add assistant.py
+git commit -m "Emit state, context and audio levels from the voice loop
+
+speaking comes from the reply thread, not the speaker: the tool
+announcement would otherwise replace the tool state while the tool is
+still running.
+
+Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
+git push
+```
+
+---
+
+### Task 5: quickshell position helper
+
+**Files (quickshell repo, `../quickshell`):** Create `assistant/Place.js`, `assistant/test_place.js`
+
+- [ ] **Step 1: failing test.** Create `assistant/test_place.js`:
+
+```js
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// Run: node assistant/test_place.js
+// Place.js is a QML library, so its .pragma line is stripped before node
+// evaluates it.
+
+const fs = require("fs");
+const assert = require("assert");
+
+const src = fs.readFileSync(__dirname + "/Place.js", "utf8")
+    .replace(/^\.pragma library$/m, "");
+const P = new Function(src + "\nreturn { at };")();
+
+assert.deepStrictEqual(P.at("center", 1920, 1080, 360, 24), { x: 780, y: 360 });
+assert.deepStrictEqual(P.at("top", 1920, 1080, 360, 24), { x: 780, y: 24 });
+assert.deepStrictEqual(P.at("bottom", 1920, 1080, 360, 24), { x: 780, y: 696 });
+assert.deepStrictEqual(P.at("top-left", 1920, 1080, 360, 24), { x: 24, y: 24 });
+assert.deepStrictEqual(P.at("top-right", 1920, 1080, 360, 24), { x: 1536, y: 24 });
+assert.deepStrictEqual(P.at("bottom-left", 1920, 1080, 360, 24), { x: 24, y: 696 });
+assert.deepStrictEqual(P.at("bottom-right", 1920, 1080, 360, 24), { x: 1536, y: 696 });
+// An unknown position is the centre, not an error.
+assert.deepStrictEqual(P.at("middle", 1920, 1080, 360, 24), { x: 780, y: 360 });
+console.log("ok");
+```
+
+- [ ] **Step 2:** Run `node assistant/test_place.js` from the quickshell repo. Expected: `ENOENT` for `Place.js`.
+
+- [ ] **Step 3: implement.** Create `assistant/Place.js`:
+
+```js
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+.pragma library
+
+// Top-left corner of a size x size square on a W x H screen, margin away
+// from the edges its position names. Anything unknown is the centre.
+function at(position, W, H, size, margin) {
+    const x = position.endsWith("left") ? margin
+            : position.endsWith("right") ? W - size - margin
+            : (W - size) / 2;
+    const y = position.startsWith("top") ? margin
+            : position.startsWith("bottom") ? H - size - margin
+            : (H - size) / 2;
+    return { x, y };
+}
+```
+
+- [ ] **Step 4:** Run `node assistant/test_place.js`. Expected: `ok`.
+
+- [ ] **Step 5:** No commit yet; the component is committed whole in Task 6.
+
+---
+
+### Task 6: the overlay component
+
+**Files (quickshell repo):** Create `assistant/shell.qml`, `assistant/Assistant.qml`, `assistant/README.md`; symlink `assistant/Theme.qml`.
+
+- [ ] **Step 1: theme link.** From the quickshell repo: `ln -s ../shared/Theme.qml assistant/Theme.qml`.
+
+- [ ] **Step 2: shell.qml**
+
+```qml
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+import Quickshell
+
+ShellRoot {
+    Assistant {}
+}
+```
+
+- [ ] **Step 3: Assistant.qml**
+
+```qml
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+import Quickshell
+import Quickshell.Io
+import Quickshell.Wayland
+import Quickshell.Hyprland
+import QtQuick
+import "Place.js" as Place
+
+// The voice assistant's overlay. desktop-assistant broadcasts its state,
+// context use and audio levels as JSON lines on a Unix socket; this only
+// listens, and keeps reconnecting while the assistant is down.
+Scope {
+    id: root
+
+    // Replaced by the assistant's hello; these render only before it.
+    property string name: "Assistant"
+    property string position: "center"
+    property real hideDelay: 3
+    property string userColor: "accent"
+    property string assistantColor: "green"
+
+    property int ctxUsed: 0
+    property int ctxMax: 0
+    property string state: "idle"
+    property string tool: ""
+    property var levels: []               // newest last, at most 64
+    property bool shown: false
+    property var shownScreen: Quickshell.screens[0]
+
+    // Faded, not switched: the window stays loaded until the fade has run.
+    property real fade: shown ? 1 : 0
+    Behavior on fade { NumberAnimation { duration: 200 } }
+
+    // Colour roles are palette names from udt, so a theme change recolours
+    // the waves live. An unknown name falls back to the accent.
+    function colorOf(role) { return Theme[role] ?? Theme.accent; }
+
+    function handle(line) {
+        let e;
+        try { e = JSON.parse(line); } catch (err) { return; }
+        if (e.type === "hello") {
+            root.name = e.name;
+            root.position = e.position;
+            root.hideDelay = e.hide_delay;
+            root.userColor = e.user_color;
+            root.assistantColor = e.assistant_color;
+            root.ctxMax = e.ctx_max;
+            root.setState(e.state, e.tool ?? "");
+        } else if (e.type === "state") {
+            root.setState(e.state, e.tool ?? "");
+        } else if (e.type === "ctx") {
+            root.ctxUsed = e.used;
+            root.ctxMax = e.max;
+        } else if (e.type === "level") {
+            const l = root.levels.slice(-63);
+            l.push({ who: e.who, value: e.value });
+            root.levels = l;
+        }
+    }
+
+    function setState(s, t) {
+        root.state = s;
+        root.tool = t;
+        if (s === "listening" && !root.shown) {
+            // The monitor in focus when it appears, not wherever it last was.
+            const focused = Hyprland.focusedMonitor?.name;
+            root.shownScreen = Quickshell.screens.find(x => x.name === focused) ?? Quickshell.screens[0];
+            root.levels = [];
+            root.shown = true;
+        }
+        if (s === "idle") hideTimer.restart(); else hideTimer.stop();
+    }
+
+    Timer {
+        id: hideTimer
+        interval: root.hideDelay * 1000
+        onTriggered: root.shown = false
+    }
+
+    Socket {
+        id: sock
+        path: `${Quickshell.env("XDG_RUNTIME_DIR") || "/tmp"}/desktop-assistant.sock`
+        connected: true
+        onConnectionStateChanged: if (!connected) root.shown = false
+        parser: SplitParser { onRead: line => root.handle(line) }
+    }
+
+    // The assistant may start after this shell, or restart: keep trying.
+    Timer {
+        interval: 2000
+        repeat: true
+        running: !sock.connected
+        onTriggered: sock.connected = true
+    }
+
+    // A config with no visible window exits, reporting nothing. This 1x1
+    // click-through window holds the shell open while the overlay is hidden.
+    PanelWindow {
+        anchors { top: true; left: true }
+        implicitWidth: 1
+        implicitHeight: 1
+        color: "transparent"
+        exclusionMode: ExclusionMode.Ignore
+        mask: Region {}
+        WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
+    }
+
+    LazyLoader {
+        active: root.fade > 0
+
+        PanelWindow {
+            screen: root.shownScreen
+            anchors { top: true; bottom: true; left: true; right: true }
+            color: "transparent"
+            exclusionMode: ExclusionMode.Ignore
+            mask: Region {}
+            WlrLayershell.layer: WlrLayer.Overlay
+            WlrLayershell.namespace: "quickshell-assistant"
+            WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
+
+            Item {
+                id: orb
+                readonly property int size: 360
+                readonly property var spot: Place.at(root.position, parent.width, parent.height, size, 24)
+                x: spot.x
+                y: spot.y
+                width: size
+                height: size
+                opacity: root.fade
+
+                // The waves: one radial bar per level, newest at the top and
+                // older ones following clockwise, so the ring moves like a
+                // waveform. Bar colour says who was talking.
+                Canvas {
+                    id: waves
+                    anchors.fill: parent
+                    onPaint: {
+                        const ctx = getContext("2d");
+                        ctx.reset();
+                        const c = width / 2, r0 = 86, reach = 90, n = 64;
+                        const ls = root.levels;
+                        ctx.lineWidth = 4;
+                        ctx.lineCap = "round";
+                        ls.forEach((l, i) => {
+                            const a = -Math.PI / 2 + (ls.length - 1 - i) * 2 * Math.PI / n;
+                            const len = 3 + l.value * reach;
+                            ctx.strokeStyle = `${root.colorOf(l.who === "user" ? root.userColor : root.assistantColor)}`;
+                            ctx.beginPath();
+                            ctx.moveTo(c + r0 * Math.cos(a), c + r0 * Math.sin(a));
+                            ctx.lineTo(c + (r0 + len) * Math.cos(a), c + (r0 + len) * Math.sin(a));
+                            ctx.stroke();
+                        });
+                    }
+                    Connections {
+                        target: root
+                        function onLevelsChanged() { waves.requestPaint(); }
+                    }
+                }
+
+                Rectangle {
+                    anchors.centerIn: parent
+                    width: 160
+                    height: 160
+                    radius: 80
+                    color: Qt.rgba(Theme.base.r, Theme.base.g, Theme.base.b, 0.8)
+                    border.color: root.colorOf(root.assistantColor)
+                    border.width: 2
+
+                    Column {
+                        anchors.centerIn: parent
+                        spacing: 4
+
+                        Text {
+                            anchors.horizontalCenter: parent.horizontalCenter
+                            text: root.name
+                            color: Theme.text
+                            font.family: Theme.fontFamily
+                            font.pixelSize: Theme.fontSize + 2
+                            font.bold: true
+                        }
+                        // nf-fa-wrench, present in Inconsolata Nerd Font.
+                        Text {
+                            anchors.horizontalCenter: parent.horizontalCenter
+                            visible: root.state === "tool"
+                            text: ""
+                            color: Theme.peach
+                            font.family: Theme.iconFamily
+                            font.pixelSize: 22
+                        }
+                        Text {
+                            anchors.horizontalCenter: parent.horizontalCenter
+                            text: root.state === "tool" ? root.tool
+                                : root.ctxMax > 0 ? `${root.ctxUsed} / ${root.ctxMax}`
+                                : `${root.ctxUsed}`
+                            color: Theme.subtext
+                            font.family: Theme.fontFamily
+                            font.pixelSize: Theme.fontSize - 3
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+- [ ] **Step 4: README.md** for the component:
+
+```markdown
+# assistant
+
+Overlay for [desktop-assistant](https://example.org/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`.
+```
+
+Replace `https://example.org/desktop-assistant` with the real public URL if the user gives one; otherwise leave the example.org placeholder (no personal host names in this repo).
+
+- [ ] **Step 5: load check.** Run `node assistant/test_place.js` (expect `ok`). Start the component as a harness-owned background command: `qs -p <quickshell repo>/assistant 2>&1 | tee <scratchpad>/qs-assistant.log`. Expected in the log: `Configuration Loaded` and no QML errors (a `Socket` error while the assistant is down is expected and retried). If `Socket`'s `connected`, `connectionStateChanged` or `parser` do not exist under those names, the log names the property: fix it against Quickshell 0.3.1's Socket and note the real names in the component README.
+
+- [ ] **Step 6: visual check with the user.** With the assistant running (Task 4), ask the user to press, speak, and ask a search question. Ask them to confirm by eye: overlay appears on the focused monitor, waves follow their voice in the accent colour and the reply in green, the tool icon and "search" show during the search, the context line reads `N / 32768`, it fades about 3 s after the reply, a barge-in keeps it up, a press during a game shows nothing (only the notification), and it reconnects after the assistant restarts. Fix what they report before committing.
+
+- [ ] **Step 7: commit in the quickshell repo**
+
+```bash
+git add assistant/
+git commit -m "feat(assistant): overlay for the voice assistant
+
+Reads desktop-assistant's event socket: state, context use, the tool
+running, and audio levels drawn as a wave ring around a circle, the
+user's voice and the reply in two palette colours. Standalone like the
+other components; it reconnects while the assistant is down, and the
+assistant runs the same without it.
+
+Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
+git push
+```
+
+(Check the quickshell repo's recent log for its attribution style first and match it.)
+
+---
+
+### Task 7: autostart and docs
+
+**Files:** the user's `~/.config/hypr/sections/autostart.lua` (live config, not in any repo), desktop-assistant `examples/config.toml`, `README.md`, `AGENTS.md`; quickshell `AGENTS.md` component list.
+
+- [ ] **Step 1: autostart.** Show the user the line to add next to the other quickshell components and add it only after they confirm (outward-facing, their live config):
+
+```lua
+    hl.exec_cmd("qs -p /home/<user>/Programming/GIT/quickshell/assistant")
+```
+
+(written with the real absolute path, matching the neighbouring lines).
+
+- [ ] **Step 2: example config.** In desktop-assistant `examples/config.toml`, before the `[env]` block, add:
+
+```toml
+# The quickshell overlay (quickshell repo, assistant/). udt palette names
+# for the colours.
+# [overlay]
+# name = "Assistant"
+# position = "center"                 # center, top, bottom, top-left, top-right, bottom-left, bottom-right
+# hide_delay = 3.0                    # seconds idle before it fades out
+# user_color = "accent"
+# assistant_color = "green"
+```
+
+- [ ] **Step 3: README.md** (desktop-assistant): add a short "Overlay" section after "Configuration and tools": the socket path, that the assistant runs the same with no overlay, that the overlay lives in the quickshell repo's `assistant/` component, and the `[overlay]` options.
+
+- [ ] **Step 4: quickshell AGENTS.md:** add `assistant/  overlay for the voice assistant, fed by its event socket` to the component list at the top.
+
+- [ ] **Step 5: AGENTS.md findings** (desktop-assistant): a "### Overlay (2026-09-26)" section before "### Barge-in" with what the live checks in Tasks 4 and 6 measured (event sequence, level rate, anything the user reported and how it was fixed). Remove nothing else.
+
+- [ ] **Step 6: commit both repos** (desktop-assistant: examples/config.toml, README.md, AGENTS.md; quickshell: AGENTS.md), each with its own message, and push.