docs: clarify controller roles and load switching boundaries

docs/controller-roles.md

@@ -0,0 +1,108 @@
+# Controller Roles
+
+This document separates committed v1 architecture from future wishlist items.
+
+## Cargo ESP32 Controller
+
+The Cargo ESP32 is the power-system controller and source of truth.
+
+Responsibilities:
+
+- WiFi AP
+- Embedded WebUI
+- REST/HTTP API
+- Relay/output control
+- Automotive load-switching control outputs
+- JBD/Xiaoxiang BLE BMS telemetry
+- DS18B20 temperature sensors
+- Optional SSD1306 OLED service/status display
+- Local configuration storage
+- Alarm and fault state
+
+Does not do:
+
+- CAN sniffing
+- OBD-II polling
+- Vehicle data ownership
+- Tilt/roll sensing
+- Dashboard rendering
+- Gauge cluster rendering
+
+## Dashboard ESP32-S3
+
+The Dashboard ESP32-S3 is a touchscreen client and future vehicle-visualization node.
+
+Responsibilities:
+
+- Touchscreen UI
+- LVGL dashboard rendering
+- Vehicle gauges
+- CAN bus access
+- OBD-II polling
+- Future VIN decoding
+- Future fault-code display
+- Future transmission temperature display
+- Future tilt/roll sensor display
+- Future off-road screen
+- Vehicle status visualization
+
+The dashboard must not own relay state, BMS state, alarm authority, or persistent cargo-controller configuration.
+
+## v1 Communications
+
+Current planned v1 path:
+
+    Dashboard ESP32-S3
+            <-> WiFi / HTTP REST
+    Cargo ESP32 AP
+            <-> control outputs
+    Automotive load-switching layer
+            <-> fused loads
+    Fridge / Starlink / lights / spare outputs
+
+Not planned for v1 controller-to-dashboard communication:
+
+- ESP-NOW
+- MQTT
+- CAN between controllers
+- UART between dashboard and Cargo ESP
+
+MQTT may be considered later for optional Home Assistant, Grafana, InfluxDB, or home-server integrations, but it is not the v1 dashboard link.
+
+## Power Distribution
+
+Current v1 assumption:
+
+    Cargo ESP32 control outputs
+            ↓
+    Automotive load-switching layer
+            ↓
+    Properly fused loads:
+    - Fridge
+    - Starlink
+    - Lights
+    - Spare
+
+The ESP32 relay board must not directly carry fridge, Starlink, inverter, compressor, or lighting load current.
+
+The exact load-switching hardware is not finalized yet. Candidate implementation options include:
+
+- Bosch-style automotive relays
+- WUPP-style fused relay/distribution module
+- Smart high-side switching
+- Future custom PCB
+
+## Hardware Wishlist / Future
+
+Keep these separate from committed architecture until explicitly promoted:
+
+- BNO085/BNO086 tilt sensor
+- CAN sniffing
+- Fault-code support
+- Standalone dashboard mode
+- Additional outputs
+- Custom PCB
+- Smart high-side switching
+- GPS
+- microSD logging
+- Home Assistant / MQTT / Grafana / InfluxDB