wifi: add WPA2 AP setup API and pairing roadmap

docs/API.md

@@ -850,3 +850,44 @@ POST /api/v1/system/restart
 ```
 
 If added later, update this document and add contract tests.
+
+
+### AP configuration
+
+The Cargo ESP32 access point uses WPA2 authentication.
+
+On first boot, if no AP password exists, the controller generates and saves a unique password. Until the OLED setup display is added, that generated password is printed to Serial during boot.
+
+#### GET /api/v1/config/ap
+
+Returns AP metadata. The password is never returned.
+
+Example response:
+
+    {
+      "ok": true,
+      "ssid": "OverlandController",
+      "password_set": true,
+      "password_min_length": 8,
+      "password_max_length": 63,
+      "auth": "wpa2"
+    }
+
+#### POST /api/v1/config/ap
+
+Updates the AP SSID/password and restarts the access point.
+
+Example request:
+
+    {
+      "ssid": "Xterra-Camp",
+      "password": "new-secure-password"
+    }
+
+Rules:
+
+- SSID must be 1-32 characters.
+- Password must be 8-63 characters.
+- Password is stored in controller preferences.
+- Password is not returned by status or config APIs.
+- Future dashboard pairing will use Cargo-led credential migration so the dashboard follows AP credential changes automatically.

docs/ARCHITECTURE.md

@@ -170,3 +170,26 @@ Future optional architecture:
       -> Cargo ESP32 outbound connection
 
 Remote features must not break local operation.
+
+
+## Cargo-led AP Pairing and Credential Migration
+
+The Cargo ESP32 owns the local overland network. It is the AP owner, source of truth, and configuration authority.
+
+Target behavior:
+
+1. Cargo ESP32 starts a WPA2-protected AP.
+2. Cargo OLED shows setup credentials and critical recovery/status information.
+3. Phone connects to the Cargo AP and uses the WebUI for setup/admin.
+4. Dashboard ESP32-S3 joins the Cargo AP as a client.
+5. If the user changes the Cargo AP SSID/password, the Cargo ESP stages the new credentials and coordinates dashboard migration.
+6. Dashboard stores the new credentials before the Cargo AP restarts.
+7. Cargo AP applies the new credentials.
+8. Dashboard reconnects automatically.
+
+The dashboard should not own network authority. A temporary dashboard setup AP may exist only as a recovery/fallback mechanism, not the normal pairing path.
+
+Recovery target:
+
+- A setup/status button on the Cargo ESP enclosure can show AP credentials on the OLED.
+- A long hold can restore factory AP credentials or enter recovery mode.

docs/roadmap.md

@@ -60,3 +60,46 @@ UI direction:
 - Dashboard alert sounds
 - More vehicle PIDs
 - Historical charts
+
+
+## AP Security, OLED Setup, and Dashboard Pairing
+
+### Phase 1 — Cargo AP security
+
+- Require WPA2 on the Cargo ESP32 AP.
+- Generate a unique AP password on first boot.
+- Store AP SSID/password in Preferences.
+- Add /api/v1/config/ap for AP configuration.
+- Add AP auth/SSID metadata to status responses.
+- Do not expose AP password in API responses.
+
+### Phase 2 — Cargo OLED setup display
+
+- Add 128x64 SSD1306 OLED support on the Cargo ESP32.
+- Show AP SSID/password/IP during first boot and setup mode.
+- Show critical operational state during normal operation:
+  - SOC
+  - voltage/current
+  - relay state
+  - WiFi/IP
+  - alarms
+- Add setup/status button:
+  - short press cycles pages
+  - long press shows AP credentials
+  - extended hold enters recovery/reset mode
+
+### Phase 3 — Dashboard credential migration
+
+- Dashboard ESP32-S3 connects as a client to the Cargo ESP AP.
+- Cargo ESP remains the network/configuration authority.
+- When AP credentials are changed from the phone WebUI, Cargo stages the new credentials.
+- Dashboard fetches and saves pending credentials before Cargo restarts AP.
+- Cargo applies the new AP settings.
+- Dashboard reconnects automatically.
+- Temporary dashboard setup AP is fallback/recovery only.
+
+### Phase 4 — User-friendly setup polish
+
+- Add QR code display for joining Cargo AP.
+- Add dashboard settings UI.
+- Add LVGL on-screen keyboard only after core dashboard functionality is stable.