From 75b88553c6d3cbdb83b9b024fba784e377569777 Mon Sep 17 00:00:00 2001
From: m3ta-chiron <m3ta-chiron@agentmail.to>
Date: Thu, 2 Jul 2026 20:00:58 +0200
Subject: [PATCH] docs: add README for talk and crunch packages

Each README covers usage, environment variables, integration patterns,
NixOS installation, and how-it-works diagrams.
---
 pkgs/crunch/README.md | 130 ++++++++++++++++++++++++++++++++++++++++++
 pkgs/talk/README.md   |  87 ++++++++++++++++++++++++++++
 2 files changed, 217 insertions(+)
 create mode 100644 pkgs/crunch/README.md
 create mode 100644 pkgs/talk/README.md

diff --git a/pkgs/crunch/README.md b/pkgs/crunch/README.md
new file mode 100644
index 0000000..faa1500
--- /dev/null
+++ b/pkgs/crunch/README.md
@@ -0,0 +1,130 @@
+# crunch
+
+Voice-notified reminders and AI crunch jobs via systemd transient timers. Schedules tasks that fire through `talk` (ElevenLabs TTS) — no NixOS rebuild needed, survives reboots.
+
+## Usage
+
+### Simple voice reminders
+
+```bash
+crunch at "14:30" "Müll rausbringen"
+crunch at "2026-07-03 10:00" "Zahnarzttermin"
+crunch in "30m" "Build checken"
+crunch daily "09:00" "Daily standup"
+crunch weekly "Mon 09:00" "Weekly review"
+crunch weekly "Montag 09:00" "Weekly review"    # German day names
+```
+
+### AI crunch jobs
+
+Runs a prompt through `pi` or `opencode` in print mode, pipes result to `talk`:
+
+```bash
+crunch ai pi in "1h" "Fasse die neuesten Commits zusammen"
+crunch ai opencode daily "08:00" "Review offene Issues und gib 3 Key-Points"
+crunch ai pi weekly "Mon 09:00" "Generiere Weekly Summary aus git log"
+```
+
+### Custom script jobs
+
+Runs any shell script on schedule. Script stdout → `talk`:
+
+```bash
+crunch script daily "08:00" ~/scripts/basecamp-daily.sh
+crunch script in "2h" ~/scripts/deploy-check.sh -- --verbose
+crunch script weekly "Mon 09:00" ~/scripts/weekly-report.sh
+```
+
+Example script:
+
+```bash
+#!/usr/bin/env bash
+# ~/scripts/basecamp-daily.sh
+TODOS=$(basecamp todos --today 2>/dev/null) || exit 0
+echo "$TODOS" | pi -p "Erstelle Summary als ~/reports/daily.md. Antworte mit Top 3."
+```
+
+### Management
+
+```bash
+crunch list                          # List active jobs
+crunch cancel crunch-mll-rausbringen-12345   # Cancel a job
+crunch purge                         # Remove fired one-shot jobs
+```
+
+## Command Reference
+
+```
+crunch at <time> <message>                    One-shot (14:30 or "2026-07-03 14:30")
+crunch in <duration> <message>                One-shot after delay (30m, 2h, 1h30m)
+crunch daily <time> <message>                 Recurring daily
+crunch weekly <day> <time> <message>          Recurring weekly (Mon/Montag)
+crunch ai <engine> <type> <time> <prompt>     AI crunch (pi|opencode)
+crunch script <type> <time> <script.sh> [args]  Custom script → talk
+crunch list                                    List active jobs
+crunch cancel <name>                           Cancel a job
+crunch purge                                   Remove fired one-shot jobs
+```
+
+## Day Names
+
+Supports English and German:
+
+| English | German | systemd |
+|---|---|---|
+| Mon, Monday | Mo, Montag | Mon |
+| Tue, Tuesday | Di, Dienstag | Tue |
+| Wed, Wednesday | Mi, Mittwoch | Wed |
+| Thu, Thursday | Do, Donnerstag | Thu |
+| Fri, Friday | Fr, Freitag | Fri |
+| Sat, Saturday | Sa, Samstag | Sat |
+| Sun, Sunday | So, Sonntag | Sun |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `ELEVENLABS_API_KEY` | ✅ | — | Required by `talk` |
+| `VOICE_NOTIFY` | ❌ | `1` | `0` silences talk globally |
+| `TALK` | ❌ | `talk` | Override path to talk binary |
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────┐
+│  systemd --user transient timer fires       │
+│                                             │
+│  crunch _say "message"                      │
+│    └─ talk "message"  (TTS via ElevenLabs)  │
+│                                             │
+│  crunch _ai pi "prompt"                     │
+│    └─ pi -p "prompt" | talk  (AI → TTS)    │
+│                                             │
+│  crunch _script ~/script.sh                 │
+│    └─ bash ~/script.sh | talk  (pipe → TTS)│
+└─────────────────────────────────────────────┘
+```
+
+Uses `systemd-run --user` to create transient `.timer` + `.service` units. No NixOS rebuild needed — jobs are created and managed at runtime.
+
+## Prerequisites
+
+- `talk` package installed and in PATH
+- `pi` and/or `opencode` for AI crunch mode
+- `loginctl enable-linger <username>` — **critical** for timers to fire when logged out
+- `ELEVENLABS_API_KEY` in environment (or agenix secrets)
+
+## NixOS Installation
+
+```nix
+# home-manager
+home.packages = [ pkgs.m3ta.crunch pkgs.m3ta.talk ];
+```
+
+Verify lingering is enabled:
+
+```bash
+loginctl show-user $(whoami) | grep Linger=yes
+# If not:
+sudo loginctl enable-linger $(whoami)
+```
diff --git a/pkgs/talk/README.md b/pkgs/talk/README.md
new file mode 100644
index 0000000..c2a3376
--- /dev/null
+++ b/pkgs/talk/README.md
@@ -0,0 +1,87 @@
+# talk
+
+ElevenLabs TTS voice notifications with a dismissable desktop popup. Generates speech from text via the ElevenLabs API, plays it through `mpv`, and shows a notification with a **⛔ Abbrechen** button to stop playback.
+
+## Usage
+
+### Argument
+
+```bash
+talk "Build abgeschlossen. Alle Tests erfolgreich."
+```
+
+### Stdin (pipe)
+
+```bash
+echo "Deployment fertig" | talk
+nixos-rebuild build 2>&1 | tail -3 | talk
+pi -p "Fasse zusammen" | talk
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `ELEVENLABS_API_KEY` | ✅ | — | API key for ElevenLabs |
+| `ELEVENLABS_VOICE_ID` | ❌ | `KXxZd16DiBqt82nbarJx` | Voice ID to use |
+| `VOICE_NOTIFY` | ❌ | `1` | Set to `0` to silence all output |
+
+## How It Works
+
+1. Sends text to ElevenLabs `text-to-speech` API → receives MP3
+2. Plays audio via `mpv` (background)
+3. Shows `notify-send` popup with **⛔ Abbrechen** action (background)
+4. Polls every 0.2s:
+   - If mpv finished → kill notification, exit
+   - If user clicked **Abbrechen** → kill mpv, exit
+5. Cleans up temp files on exit
+
+## Cancel Button
+
+The notification popup has a **⛔ Abbrechen** action button. Clicking it kills `mpv` playback immediately. The popup disappears when audio finishes or is cancelled.
+
+The poll loop uses `[ -s ]` (non-empty file check) on the action output file. This ensures the loop only reacts when `notify-send` actually writes the action key — not when the empty file is created by the shell redirect.
+
+## Integration Patterns
+
+### After long-running tasks
+
+```bash
+nixos-rebuild switch 2>&1 | tail -5 | talk
+```
+
+### With AI agents (print mode)
+
+```bash
+# Pi
+pi -p "Review diesen Code" | talk
+
+# OpenCode
+opencode run "Erkläre diese Funktion" -q | talk
+```
+
+### With crunch (scheduled jobs)
+
+```bash
+crunch ai pi daily "08:00" "Fasse Basecamp Todos zusammen"
+# → talk speaks the summary at 08:00
+```
+
+## NixOS Installation
+
+```nix
+# home-manager
+home.packages = [ pkgs.m3ta.talk ];
+
+# Requires in environment:
+environment.sessionVariables.ELEVENLABS_API_KEY = "your-key";
+# Or via agenix secrets
+```
+
+## Dependencies
+
+- `curl` — API calls
+- `python3` — JSON payload construction
+- `mpv` — audio playback
+- `libnotify` — desktop notification
+- `busybox` — coreutils (rm, cat, grep, sleep, kill, stat)