docs: audio-panel signal-metering spec (implemented)

Records the signal-metering layer for the audio panel: a three-state activity lamp from the pactl state field, and a windowed peak meter feeding the VU needles, keyed per device so per-device metering stays a later GUI-only change. Two review rounds before build (the first caught a parec sample-rate-vs-update-rate bug verified live); marked implemented across four dotfiles commits. Live-eyeball checks filed as a manual-testing checklist.

1 files changed, 42 insertions, 8 deletions

diff --git a/todo.org b/todo.org
index e429837..2f587d7 100644
--- a/todo.org
+++ b/todo.org
@@ -23,7 +23,7 @@ The vocabulary is open — topic tags are coined as needed — so these are conv
 * Archsetup Open Work
 ** TODO [#B] Scrolling/Carousel layout: frame fit + wrap-around :hyprland:
 :PROPERTIES:
-:LAST_REVIEWED: 2026-06-13
+:LAST_REVIEWED: 2026-07-06
 :END:
 Disabled 2026-06-12 (bind and cycle entry points removed; Super+Shift+S reassigned to whole-desktop screenshot). The layout needs real work before it earns its chord back:
 - What fits in each frame: column/frame sizing so windows land at usable widths instead of arbitrary slices.
@@ -203,7 +203,7 @@ Implementation notes: a small GTK layer-shell app (mirror pocketbook's structure
 
 ** TODO [#B] Local offline LLM runtime + per-host model cache :tooling:llm:
 :PROPERTIES:
-:LAST_REVIEWED: 2026-05-29
+:LAST_REVIEWED: 2026-07-06
 :END:
 Add a local-LLM provisioning track so machines can run an offline coding agent when there's no network. Install =llama.cpp= (CPU + Vulkan where practical) and prefetch per-host model files while network is available; expose OpenAI-compat local endpoints (=127.0.0.1:8081= coding, =:8082= general; =:11434= reserved for =ollama= if used). Per the rulesets generic-agent-runtime design pass — rulesets becomes runtime-neutral and owns the runtime manifests + project instructions; archsetup owns machine provisioning + the per-machine model inventory. Source: handoff from rulesets 2026-05-28 ([[file:assets/outbox/2026-05-28-from-rulesets-local-llm-install.org][outbox copy]]).
 
@@ -240,6 +240,9 @@ Boot the configured endpoint and send a short prompt; surface success/failure +
 Acceptance: fresh VM install of the ratio profile reaches an endpoint on =:8081= that answers a smoke prompt; velox profile gets Q4_K_M + 8B and answers a prompt within reasonable laptop latency; network-down install completes successfully with the pending-models warning surfaced.
 
 ** TODO [#C] Voice dictation / speech-to-text input :feature:tooling:
+:PROPERTIES:
+:LAST_REVIEWED: 2026-07-06
+:END:
 Push-to-talk dictation that types transcribed speech into the focused Wayland window — usable at any text field, including the Claude Code terminal prompt and Emacs buffers. Claude Code has no built-in voice input; dictation has to happen at the OS level and inject text. Raised 2026-07-03.
 
 Tool choice is the open decision (needs Craig): =nerd-dictation= (Vosk, lighter, lower accuracy) vs a =whisper.cpp=-based daemon (heavier, higher accuracy, optional GPU). Wayland typing backend is =wtype= or =ydotool=. Scope once chosen: install + model download, a push-to-talk keybind (Hyprland), and an autostart entry; fold into archsetup so it lands on both daily drivers. Consider an Emacs-native path (=whisper.el=) as a complement for in-buffer dictation.
@@ -386,9 +389,9 @@ Need to investigate proper machine-ID regeneration that doesn't break networking
 Would enable parallel test execution in CI/CD
 Priority C because snapshot-based testing meets current needs
 
-** TODO [#B] Fix install errors surfaced by the 2026-05-11 VM test run
+** TODO [#C] Fix install errors surfaced by the 2026-05-11 VM test run
 :PROPERTIES:
-:LAST_REVIEWED: 2026-06-15
+:LAST_REVIEWED: 2026-07-06
 :END:
 *** 2026-06-28 Sun @ 13:29:29 -0400 Audit reconcile: 2026-06-28 btrfs+zfs runs reproduce the same residual set
 Newer full runs landed since the 2026-06-11 reconcile below: the 2026-06-25 zfs run (Testinfra 96/0) and the 2026-06-28 btrfs+zfs runs (97/0, "zero attributed issues"). The residual four were NOT fixed and reproduce unchanged: =enabling firewall= (archsetup:1496-1498, carries a VM-kernel note), =enabling gamemode for user= (archsetup:2221, non-critical), and =tidaler (AUR)=. Zero archsetup-attributed Testinfra issues across both profiles confirms these are environment / non-critical, not archsetup bugs. Bare-metal confirmation of the firewall pair is still the open thread.
@@ -497,9 +500,9 @@ Read recommended resources to make informed security decisions (see metrics for
 :END:
 Practical guidelines for working in public spaces
 
-** TODO [#C] Ensure sleep/suspend works on laptops
+** TODO [#B] Ensure sleep/suspend works on laptops
 :PROPERTIES:
-:LAST_REVIEWED: 2026-06-09
+:LAST_REVIEWED: 2026-07-06
 :END:
 Critical functionality for laptop use - current battery drain unacceptable
 *NOTE:* This applies to Framework Laptop (velox), not Framework Desktop (ratio)
@@ -523,7 +526,7 @@ Ran =makepkg --verifysource= on the current AUR PKGBUILD (3.7.0-1). The package
 
 ** TODO [#C] Review theme config architecture for dunst/fuzzel
 :PROPERTIES:
-:LAST_REVIEWED: 2026-05-21
+:LAST_REVIEWED: 2026-07-06
 :END:
 The active dunst config is stowed from dotfiles/common/ but theme templates
 live in dotfiles/hyprland/.config/themes/. set-theme copies the templates to
@@ -537,7 +540,7 @@ The goal is a single place to edit each config, not two.
 
 ** TODO [#C] Review current tool pain points annually
 :PROPERTIES:
-:LAST_REVIEWED: 2026-05-21
+:LAST_REVIEWED: 2026-07-06
 :END:
 Once-yearly systematic inventory of known deficiencies and friction points in current toolset
 
@@ -571,6 +574,37 @@ Parse yay errors and provide specific, actionable fixes instead of generic error
 Enhance existing indicators to show what's happening in real-time
 
 ** TODO Manual testing and validation
+*** Audio signal metering: apply the package (precondition)
+What we're verifying: the signal-metering build is live. Only a =git pull= is needed — the =audio/= package .py files are stowed and no new launcher files were added, so no restow or reboot. The shared panel CSS gained a =.lamp.dim= class (live-idle); it's in the same stowed =panel.css=.
+#+begin_src sh :results output
+cd ~/.dotfiles && git pull
+#+end_src
+Expected: the pull succeeds (commits 6054d3d..21437b4).
+*** Three-state activity lamp reads live
+What we're verifying: the INPUT/OUTPUT lamps show muted / live-idle / live-active from real device state, not just mute.
+- Open the audio panel (bar sound glyph / Super+A). With nothing playing and the output unmuted, look at the OUTPUT lamp.
+Expected: a dim (not bright) green lamp — live-idle: unmuted but no audio flowing.
+- Start playing audio (music, a video).
+Expected: the OUTPUT lamp brightens to a bright glowing green — live-active.
+- Mute the output (click OUTPUT).
+Expected: the lamp goes red — muted.
+*** OUTPUT needle tracks real signal, not the fader
+What we're verifying: the OUTPUT VU needle moves with actual output level, replacing the old volume-fed needle.
+- With audio playing, watch the OUT · PLAY needle; then pause the audio (leave the volume fader where it is).
+Expected: the needle deflects and rides the music while playing, and falls to rest when paused even though the fader hasn't moved. (The old behavior held the needle up at the fader position.)
+*** INPUT needle registers the mic, including during PTT
+What we're verifying: the IN · MIC needle shows real mic level and confirms PTT is capturing.
+- With the mic live (INPUT unmuted), speak.
+Expected: the IN · MIC needle deflects with your voice.
+- Set the mic to muted, then hold the PUSH·TALK key and speak.
+Expected: while held, the INPUT lamp reads live and the IN · MIC needle registers your voice; on release it rests again.
+*** No parec / CPU cost when the panel is closed
+What we're verifying: the meter runs only while the panel is open and leaves no orphan =parec=.
+- Open the audio panel, then close it (✕, Esc, or the bar click).
+#+begin_src sh :results output
+pgrep -af 'parec .*@DEFAULT_(MONITOR|SOURCE)@' || echo "no parec running — clean"
+#+end_src
+Expected: no matching =parec= process after the panel is closed (the process groups were reaped on teardown).
 *** Timer redesign: apply the package + wtimer, clear stale timers (precondition)
 What we're verifying: the redesigned =timer/= package + =wtimer= are live. Only a =git pull= is needed — the package .py files and =wtimer= are already stowed, and this build added no new launcher files, so no restow or reboot. Clear any pre-existing timers first so a stale-shape state file (an old pomodoro item lacking the new =cfg=) can't crash =wtimer render=.
 #+begin_src sh :results output