fix: code review batch 2 — multi-channel, thread safety, DSP reset, MIDI, hotspot, NAM, docs/CI, code quality

README.md

@@ -1,6 +1,6 @@
 # Pi Multi-FX Pedal 🎸
 
-A real-time guitar multi-FX pedal running on **Raspberry Pi 4B** with **32 DSP effects**, **NAM A2 neural amp modeling**, **IR cab simulation**, **4-Cable Method** routing, and a **web UI** on `pedal.local:8080`.
+A real-time guitar multi-FX pedal running on **Raspberry Pi 4B** with **32 DSP effects**, **NAM A2 neural amp modeling**, **IR cab simulation**, **4-Cable Method** routing, and a **web UI** on `pedal.local`.
 
 ## Quick Install (Focusrite 2i2 Test)
 
@@ -85,8 +85,8 @@ python3 main.py
 ### 7. Open the Web UI
 
 From any device on the same network:
-- **Browser:** http://pedal.local:8080
-- Or use the IP: http://192.168.x.x:8080
+- **Browser:** http://pedal.local
+- Or use the IP: http://192.168.x.x
 
 ### WiFi Hotspot (No Network? No Problem)
 
@@ -99,7 +99,7 @@ sudo bash scripts/setup-wifi-ap.sh
 # Or with custom SSID/password:
 sudo bash scripts/setup-wifi-ap.sh --ssid "Pi-Pedal" --psk "yourpassword"
 
-# Phone connects to "Pi-Pedal" → open http://pedal.local:8080
+# Phone connects to "Pi-Pedal" → open http://pedal.local
 
 # To turn it off and go back to client mode:
 sudo bash scripts/setup-wifi-ap.sh --disable
@@ -130,6 +130,58 @@ cp etc/config-focusrite-4cm.yaml ~/.pedal/config.yaml
 
 Toggle 4CM on/off from the Settings page in the web UI.
 
+## Port & Privileges
+
+The web UI runs on **port 80** (standard HTTP), so URLs are clean — just `http://pedal.local` with no port number.
+
+Binding to port 80 requires elevated privileges. Either:
+
+1. **Run as root** (simplest):
+   ```bash
+   sudo python3 main.py
+   ```
+
+2. **Grant the `cap_net_bind_service` capability** (safer — no root shell):
+   ```bash
+   sudo setcap 'cap_net_bind_service=+ep' $(readlink -f $(which python3))
+   python3 main.py   # no sudo needed
+   ```
+
+3. **Override the port** via code change (development only):
+   Change `DEFAULT_PORT` in `src/web/server.py` and `port=80` in `main.py`.
+
+For development, option 2 is recommended.
+
+## WiFi / Bluetooth Permissions
+
+The WiFi hotspot and Bluetooth management features call `sudo` internally for system operations (hostapd, dnsmasq, iwlist, systemctl). If your user does not have passwordless `sudo`, these features will fail silently.
+
+Add a sudoers entry to grant passwordless access for the pedal user (`pi` or your username):
+
+```bash
+sudo visudo -f /etc/sudoers.d/pi-pedal
+```
+
+Add one of the following, replacing `pi` with your actual username:
+
+**Minimal** (only the WiFi setup script):
+```
+pi ALL=(ALL) NOPASSWD: /home/pi/projects/pi-multifx-pedal/scripts/setup-wifi-ap.sh *
+pi ALL=(ALL) NOPASSWD: /usr/sbin/iwlist *
+pi ALL=(ALL) NOPASSWD: /usr/sbin/iwconfig *
+pi ALL=(ALL) NOPASSWD: /usr/bin/wpa_cli *
+pi ALL=(ALL) NOPASSWD: /usr/bin/systemctl * hostapd
+pi ALL=(ALL) NOPASSWD: /usr/bin/systemctl * dnsmasq
+pi ALL=(ALL) NOPASSWD: /usr/bin/systemctl * pi-bt-midi
+```
+
+**Permissive** (full passwordless sudo — convenient on a dedicated device):
+```
+pi ALL=(ALL) NOPASSWD: ALL
+```
+
+The web UI surfaces permission errors with an `"insufficient_permissions"` key when `sudo` calls fail due to missing sudoers configuration.
+
 ## Hardware
 
 | Component | Spec |