From d7eabfffbbdf5f4d33833da113f8414d7f3d2bd8 Mon Sep 17 00:00:00 2001
From: Willem van den Ende <willem@qwan.eu>
Date: Tue, 28 Apr 2026 13:03:11 +0100
Subject: [PATCH] docs(pi-notifications): update README for audio-based alerts

---
 .pi/llm-metrics.log                 |  1 +
 packages/pi-notifications/README.md | 31 ++++++++++++++++++++++++-----
 2 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/.pi/llm-metrics.log b/.pi/llm-metrics.log
index 475e116..31e99b1 100644
--- a/.pi/llm-metrics.log
+++ b/.pi/llm-metrics.log
@@ -39,3 +39,4 @@
 {"timestamp":"2026-04-28T11:59:02.465Z","provider":"llama.cpp","model":"Qwen3.6-35B-A3B-MXFP4_MOE.gguf","turnCount":1,"inputTokens":16,"outputTokens":43,"totalTokens":59,"prefillTokensPerSec":23.49,"generationTokensPerSec":96.63,"combinedTokensPerSec":52.4,"totalDurationMs":1126,"timeToFirstTokenMs":681,"rawTimestamps":{"ttftMs":681,"allTtftMs":[681],"generationDurationMs":445,"turns":[{"turnId":"turn-0","durationMs":1126,"ttftMs":681}]}}
 {"timestamp":"2026-04-28T12:00:27.499Z","provider":"llama.cpp","model":"Qwen3.6-35B-A3B-MXFP4_MOE.gguf","turnCount":2,"inputTokens":362,"outputTokens":216,"totalTokens":578,"prefillTokensPerSec":231.16,"generationTokensPerSec":71.4,"combinedTokensPerSec":125.9,"totalDurationMs":4591,"timeToFirstTokenMs":1566,"rawTimestamps":{"ttftMs":1566,"allTtftMs":[1566],"generationDurationMs":3025,"turns":[{"turnId":"turn-0","durationMs":2349},{"turnId":"turn-1","durationMs":2242,"ttftMs":1566}]}}
 {"timestamp":"2026-04-28T12:01:00.510Z","provider":"llama.cpp","model":"Qwen3.6-35B-A3B-MXFP4_MOE.gguf","turnCount":1,"inputTokens":25,"outputTokens":361,"totalTokens":386,"prefillTokensPerSec":5.99,"generationTokensPerSec":98.55,"combinedTokensPerSec":49.24,"totalDurationMs":7839,"timeToFirstTokenMs":4176,"rawTimestamps":{"ttftMs":4176,"allTtftMs":[4176],"generationDurationMs":3663,"turns":[{"turnId":"turn-0","durationMs":7839,"ttftMs":4176}]}}
+{"timestamp":"2026-04-28T12:02:20.597Z","provider":"llama.cpp","model":"Qwen3.6-35B-A3B-MXFP4_MOE.gguf","turnCount":7,"inputTokens":539,"outputTokens":2934,"totalTokens":3473,"prefillTokensPerSec":696.38,"generationTokensPerSec":60.84,"combinedTokensPerSec":70.88,"totalDurationMs":48998,"timeToFirstTokenMs":774,"rawTimestamps":{"ttftMs":774,"allTtftMs":[774,688],"generationDurationMs":48224,"turns":[{"turnId":"turn-0","durationMs":14900},{"turnId":"turn-1","durationMs":9439},{"turnId":"turn-2","durationMs":8005},{"turnId":"turn-3","durationMs":6527},{"turnId":"turn-4","durationMs":4604,"ttftMs":774},{"turnId":"turn-5","durationMs":3659},{"turnId":"turn-6","durationMs":1864,"ttftMs":688}]}}
diff --git a/packages/pi-notifications/README.md b/packages/pi-notifications/README.md
index be1a263..9638593 100644
--- a/packages/pi-notifications/README.md
+++ b/packages/pi-notifications/README.md
@@ -1,19 +1,40 @@
 # pi-notifications
 
-Desktop notifications for pi agent events via macOS Notification Center.
+Audio alerts for pi agent events via `afplay`.
 
 ## What it does
 
-Shows a system notification when the agent finishes a turn, so you can step away and get alerted when input is needed.
+Plays a sound when the agent finishes a turn, so you can step away and get alerted when input is needed.
 
 ## Configuration
 
 | Env var | Default | Description |
 |---------|---------|-------------|
 | `PI_NOTIFICATIONS_ENABLED` | `true` | Set to `false` to disable all notifications |
-| `PI_NOTIFICATION_AGENT_END` | `true` | Notification when agent finishes |
-| `PI_NOTIFICATION_TITLE` | `pi` | Notification title |
-| `PI_NOTIFICATION_SOUND` | `default` | macOS sound (Bottle, Ping, Pop, etc.) or `""` for silent |
+| `PI_NOTIFICATION_AGENT_END` | `true` | Play sound when agent finishes |
+| `PI_NOTIFICATION_AUDIO` | `/System/Library/Sounds/Glass.aiff` | Path to audio file (.aiff/.wav/.mp3) |
+| `PI_NOTIFICATION_DEBUG` | `false` | Show visible steer signal instead of playing sound |
+
+## Debugging
+
+- **`PI_NOTIFICATION_DEBUG=true`** — emits a steer message in the TUI instead of playing sound (great for loop testing)
+- **Standalone tester:** `node --input-type=module -e "import {createJiti} from './node_modules/.pnpm/@mariozechner+jiti@2.6.5/node_modules/@mariozechner/jiti/lib/jiti.mjs'; const jiti = createJiti(); await jiti.import('./packages/pi-notifications/src/test-notify.ts');"`
+
+## Available macOS sounds
+
+```
+/System/Library/Sounds/Bottle.aiff
+/System/Library/Sounds/Cork.aiff
+/System/Library/Sounds/Frog.aiff
+/System/Library/Sounds/Glass.aiff       ← default
+/System/Library/Sounds/Hero.aiff
+/System/Library/Sounds/Morse.aiff
+/System/Library/Sounds/Ping.aiff
+/System/Library/Sounds/Pop.aiff
+/System/Library/Sounds/Submarine.aiff
+/System/Library/Sounds/Sosumi.aiff
+/System/Library/Sounds/Tink.aiff
+```
 
 ## Usage