docs: document ALSA audio error fix for cron and update agent instructions

AGENTS.md

@@ -1,4 +1,7 @@
 # System Context
 
 This project runs on a **Raspberry Pi 4 Model B (2018)**. 
-Please take this into account for all code changes, dependencies (e.g., ARM architecture), and performance optimizations.
+Please take this into account for all code changes, dependencies (e.g., ARM architecture), and performance optimizations.
+
+## Audio Output Note
+When configuring audio or running tasks on this device, **always use the 3.5mm headphone jack (Audio Jack)** as the explicit audio output unless requested otherwise. The system might have HDMI devices as lower-index cards, which can cause headless/cron background scripts to fail with ALSA errors. Ensure tools and scripts explicitly target the correct audio card (usually `hw:2,0` or via a user-wide `~/.asoundrc` config).

README.md

@@ -55,4 +55,25 @@ To have the alarm start automatically at a specific time (e.g., 6:45 AM on weekd
    * *Incorrect:* The alarm waits a few seconds and generates a completely new sequence for you to solve.
 
 ## Author
-Markus Graf (info@marksugraf.ch)
+Markus Graf (info@marksugraf.ch)
+## Troubleshooting
+
+**Audio issues when running via Cron (ALSA: Couldn't open audio device: Unknown error 524):**
+If the script runs perfectly from the terminal but crashes when triggered by cron, it might be trying to use an invalid audio output (like a disconnected HDMI port) because background jobs don't have the same environment variables as interactive sessions.
+
+To force the system to use the 3.5mm headphone jack (Audio Jack), you can create a `~/.asoundrc` file for the `pi` user with the following content:
+
+```
+pcm.!default {
+  type asym
+  playback.pcm {
+    type plug
+    slave.pcm "hw:2,0"
+  }
+}
+ctl.!default {
+  type hw
+  card 2
+}
+```
+*(Note: Change `hw:2,0` and `card 2` to match your actual headphone jack card index, which you can find by running `aplay -l`).*