Document audio card initialization

src/building/software-install.md

@@ -111,15 +111,17 @@ Insert the microSD into the pi-Stomp's mainboard (inside the enclosure) and conn
 When the home screen appears, the pi-Stomp is on your Wi-Fi network.
 
 ### Special instructions for pi-Stomp v2 (core) hardware
-If your v2 hardware has an AudioInjector audio card (blue pcb not black or green), then booting will result in a blue screen, likely showing, "Cannot initialize driver".  You'll need to manually change the audio card by running a script.
-```bash
-ssh pistomp@pistomp.local
 
-~/pi-stomp/util/change-audio-card.sh
+If your v2 hardware has an AudioInjector audio card (blue PCB, not black or green), enable the AudioInjector overlay in `config.txt` **before first boot**. While the freshly-written SD card is still connected your computer, open `config.txt` on the boot partition, and change the `dtoverlay=` lines so only AudioInjector is uncommented:
+
+```
+#dtoverlay=iqaudio-codec
+dtoverlay=audioinjector-wm8731-audio
 ```
-Choose #1 (audioinjector)
 
-Once complete, power cycle, and when it comes back up, it should good to go with your audio card.
+Eject and boot.
+
+> **If you didn't set it in `config.txt`**, the first boot lands on the crash screen with "Cannot initialize driver". Click **RECOVERY** → **Audio Card**, pick **AudioInjector**, and reboot. If recovery isn't reachable, SSH in and run `~/pi-stomp/util/change-audio-card.sh`, choose #1 (audioinjector), then power-cycle the unit.
 
 ## Step 7 — Open the Pedalboard editor (MOD-UI)
 

src/maintenance/recovery.md

@@ -64,12 +64,10 @@ The crash screen shows:
 
 - **Navigation encoder** — move between the header, service rows, log textarea, and action buttons
 - **Tweak 1** — when the log textarea is selected, scrolls the log text horizontally (long log lines that don't fit the screen)
-- **Click on the log textarea** — opens the fullscreen log viewer
+- **Click on the log textarea** — opens the fullscreen log viewer (see below)
 - **Click RESUME** — releases the LCD and restarts the main app
 - **Click RECOVERY** — opens the recovery menu
 
-### Fullscreen log viewer
-
 The log viewer shows the complete journalctl output for the crashed service. Use the Navigation encoder to scroll through lines vertically. Use Tweak 1 to scroll long lines horizontally. Long-press or click the back icon to return to the crash screen.
 
 <img src="{{ '/assets/images/recovery-log-view.png' | url }}" alt="Log viewer" class="figure-narrow">
@@ -79,6 +77,12 @@ The log viewer shows the complete journalctl output for the crashed service. Use
 - **Restart Jack** — restarts the JACK audio server. Use this if audio stops working but the LCD is still responsive.
 - **Restart MOD** — restarts mod-host. Use this if plugins stop loading.
 
+## Audio card
+
+The **Audio Card** entry on the main menu switches which audio HAT recovery expects on the next boot. Use it when the LCD is on the crash screen with "Cannot initialize driver" (the wrong `dtoverlay=` is enabled in `config.txt`), or when you've physically swapped cards between IQaudIO CODEC, HiFiBerry, and AudioInjector.
+
+Pick your fitted card and reboot. Recovery enables the matching `dtoverlay=` in `config.txt` and seeds the known-good ALSA mixer state, so JACK starts on the right card at the next boot.
+
 ## Rolling back to a known-good state
 
 pi-Stomp tracks changes in six **domains**:

src/maintenance/troubleshooting.md

@@ -16,7 +16,7 @@ eleventyNavigation:
 | Incorrect routing | Check cabling: instrument → In1, Out1 → amp. In MOD-UI, connect a virtual cable straight from Hardware Capture 1 to Hardware Playback 1 |
 | Volume is down | Turn the Volume knob (Tweak 3) up. Check Input Gain in the Audio & MIDI panel |
 | Processing is bypassed | The power icon in the toolbar should be green. Click it to toggle |
-| Audio card configuration | SSH in and run: `alsactl -f ~/pi-stomp/setup/audio/iqaudiocodec.state restore` |
+| Audio card configuration | **Recovery** → **Factory Reset** → **Audio** allows you to change cards / reset alsa state to factory settings. Or SSH: `sudo /usr/lib/pistomp/alsa/seed.sh <overlay>` followed by `sudo alsactl restore` |
 | Services in bad state | System Menu → **Restart sound engine**, or SSH: `sudo systemctl restart jack` |
 | Hardware | Add a TinyGain plugin to the pedalboard. If the meter shows -inf with signal, the problem is likely the audio card or input wiring |
 
@@ -29,11 +29,19 @@ eleventyNavigation:
 | Low power supply voltage | Run `dmesg \| grep -i voltage`. Use the 27W factory adapter |
 | Unnecessary processes | Shut down any extra software you've installed |
 
+## Wrong audio card or corrupt state
+
+If the system configuration doesn't match the installed hardware on your unit (e.g. for some v2 units) or if the card's mixer state is otherwise unsuitable for MOD/pi-Stomp, JACK may not start up successfully, or the audio inputs/outputs may not function.
+
+Go to the Recovery main menu (either from the crash screen or through **Recovery and Updates** in the System menu), then choose **Audio Card**. Pick the card you have installed (IQaudIO CODEC, HiFiBerry, or AudioInjector), then reboot. Recovery flips the `dtoverlay=` in `config.txt` and seeds the matching mixer state for you.
+
+> Alternatively, SSH in and run `~/pi-stomp/util/change-audio-card.sh`, then pick the fitted card and power-cycle the unit.
+
 ## No audio from headphone jack
 
 Turn up the output volume (Tweak 3). The headphone output follows the same audio as the main outputs. Low-impedance earbuds (< 50 ohms) may sound quiet — use higher-impedance headphones.
 
-## Device is on the network but unreachable from a specific computer
+## Device is on the network but unrreachable from a specific computer
 
 The pi-Stomp shows a healthy Wi-Fi link, but your device (often a Mac) cannot reach it. The Pi's signal is strong and the router reports the Pi as connected. This is an access point bug: the router stops forwarding unicast frames from other clients to the Mac. Ethernet and the device hotspot are unaffected. See [pi-gen-pistomp#39](https://github.com/TreeFallSound/pi-gen-pistomp/issues/39).