Add resilient dual-radio network failover

README.md

@@ -16,6 +16,7 @@ The current MVP slice includes:
 - a responsive 1920×720-oriented setup, login, and dashboard UI;
 - an idempotent Raspberry Pi installer with systemd start-on-boot support;
 - atomic, dashboard-triggered Git updates with automatic verification and rollback safety;
+- optional dual-radio Wi-Fi failover with an always-recoverable offline car hotspot;
 - automated API security tests and reproducible quality commands.
 
 The ADB transport, job UI, artifacts, Android companion, and remaining operations work are tracked in [PLAN.md](./PLAN.md).
@@ -153,6 +154,37 @@ Important values:
 - `ADB_ENABLED`: enables the read-only head-unit collector; defaults to `false`
 - `ADB_SERIAL`: optional exact serial; when empty, discovery requires exactly one attached device
 - `ADB_PATH` and `ADB_TIMEOUT_MS`: executable path and per-command timeout
+- `NETWORK_MANAGER_ENABLED`: enables the separately supervised NetworkManager controller after explicit setup
+- `NETWORK_STATUS_PATH` and `NETWORK_COMMAND_PATH`: validated state and fixed-action request files
+- `NETWORK_HOTSPOT_INTERFACE` / `NETWORK_UPSTREAM_INTERFACE`: default to built-in `wlan0` and USB `wlan1`
+- `NETWORK_PROBE_TIMEOUT_SECONDS`: maximum built-in upstream attempt before restoring the offline hotspot
+
+### Dual-radio car network
+
+The optional network controller prefers a USB Wi-Fi adapter for upstream internet and keeps the built-in adapter on a stable car hotspot. If the USB adapter disappears, the built-in adapter tries its saved upstream profiles for 60 seconds. When none connect, the controller restores the offline hotspot at `http://10.42.0.1:8787`.
+
+Automatic switching is disabled by default so installation cannot interrupt an existing SSH connection. First connect the USB adapter to a saved upstream profile:
+
+```bash
+sudo nmcli --ask device wifi connect "HOME_SSID" ifname wlan1 name upstream-home
+```
+
+Then create the recovery hotspot and enable its controller:
+
+```bash
+sudo pi-car-companion-network-setup
+```
+
+The helper requires `wlan1` to be connected before it enables switching, asks interactively for a unique hotspot password, and never places that password in the application configuration. Settings then shows the current mode and offers **Try upstream again** and **Restore hotspot** controls.
+
+Behavior by mode:
+
+- `wlan1` connected: `wlan0` hosts `MG4-Companion` and shares upstream access.
+- `wlan1` unavailable: `wlan0` becomes upstream when a saved network connects.
+- no upstream after 60 seconds: `wlan0` returns to the offline hotspot automatically.
+- `wlan1` returns: it must connect and remain stable before `wlan0` returns to hotspot mode.
+
+Add phone hotspots as additional saved `wlan1` profiles. Dashboard actions only select existing NetworkManager profiles; Wi-Fi credentials are not accepted through the API.
 
 ### Read-only ADB setup