docs: define cargo esp api contract

docs/ARCHITECTURE.md

@@ -263,3 +263,17 @@ Current responsibility split:
 - Dashboard ESP32-S3 should not wire directly to cargo-area DS18B20 sensors for v1.
 
 This means future dashboard work should display existing Cargo ESP temperature telemetry rather than reimplementing temperature sensing on the dashboard.
+
+## Cargo ESP API Contract
+
+The Cargo ESP API contract is documented in `docs/cargo-api-contract.md`.
+
+The Cargo ESP32 is the source of truth for:
+
+- Relay/output state
+- DS18B20 temperature readings
+- BMS telemetry
+- Alarm/fault state
+- Local configuration
+
+The ESP32-S3 dashboard should consume Cargo ESP API data over WiFi/HTTP REST instead of directly owning cargo sensors or relay state.

docs/CHATGPT_HANDOFF.md

@@ -173,3 +173,9 @@ Default validation should use the repo-local virtual environment:
 DS18B20 temperature support is already implemented in the Cargo ESP/WebUI/API path.
 
 Do not suggest adding DS18B20 support as if it is missing. Future work should preserve existing Cargo ESP temperature ownership and expose/display that telemetry through the API and ESP32-S3 dashboard.
+
+## Cargo API Contract Guardrail
+
+The Cargo ESP API contract is documented in `docs/cargo-api-contract.md`.
+
+Before making dashboard firmware changes, inspect the current API tests and this contract. Do not move relay, BMS, DS18B20, alarm, or configuration ownership from the Cargo ESP to the dashboard.

docs/README.md

@@ -41,3 +41,5 @@ Archived documents are kept for history, but the primary documents above should
 
 - `repo-cleanup-audit.md` - Active repo audit for stale Pico/UART dashboard references and DS18B20 documentation status.
 - `API.md` - High-level API notes and telemetry ownership.
+
+- `cargo-api-contract.md` - Cargo ESP API ownership and expected API areas for WebUI/dashboard clients.

docs/cargo-api-contract.md

@@ -0,0 +1,124 @@
+# Cargo ESP API Contract
+
+The Cargo ESP32 is the source of truth for power-system state.
+
+The WebUI, ESP32-S3 dashboard, and future clients should consume this API rather than reading sensors or relay state directly.
+
+## Ownership
+
+Cargo ESP32 owns:
+
+- Relay/output state
+- DS18B20 temperature readings
+- BMS telemetry
+- Alarm/fault state
+- Local configuration
+- WebUI/API service
+
+Dashboard ESP32-S3 consumes:
+
+- Status
+- Battery/BMS telemetry
+- Temperature telemetry
+- Relay/output state
+- Alarm/fault state
+
+The dashboard may request relay changes through the API, but the Cargo ESP remains authoritative.
+
+## Expected API Areas
+
+### System Status
+
+Used by clients to determine whether the Cargo ESP is online and healthy.
+
+Expected data:
+
+- Device name
+- Firmware version
+- Uptime
+- WiFi/AP status
+- API version
+- Alarm/fault summary
+
+### Battery / BMS
+
+Used for house battery display.
+
+Expected data:
+
+- Voltage
+- Current
+- State of charge
+- Charging/discharging state
+- Cell data when available
+- BMS online/offline status
+- Protection/fault state
+
+### Temperatures
+
+DS18B20 support is already implemented in the Cargo ESP/WebUI/API path.
+
+Expected data:
+
+- Sensor ID
+- Display name
+- Enabled state
+- Online/offline state
+- Temperature value
+- Temperature unit
+- Role/location, such as fridge, cargo, ambient, or spare
+
+The ESP32-S3 dashboard should display this data from the Cargo ESP API. It should not directly own cargo/fridge DS18B20 sensor wiring for v1.
+
+### Relays / Outputs
+
+Used for fridge, Starlink, lights, spare, and future switched outputs.
+
+Expected data:
+
+- Output ID
+- Display name
+- Enabled state
+- Current state
+- Requested state
+- Fault/lockout state when available
+- Optional output type or role
+
+Relay/output writes should go through the Cargo ESP API.
+
+### Configuration
+
+Configuration should remain owned by the Cargo ESP.
+
+Expected future areas:
+
+- Output names
+- Output enabled/disabled state
+- Temperature sensor names
+- Temperature sensor roles
+- Alarm thresholds
+- Network/AP settings
+- OTA settings
+
+## v1 Client Communication
+
+Current v1 client path:
+
+    ESP32-S3 Dashboard
+            <-> WiFi / HTTP REST
+    Cargo ESP32 AP
+
+Not v1 API transport:
+
+- ESP-NOW
+- MQTT
+- UART dashboard link
+- CAN between controllers
+
+## Compatibility Rule
+
+When possible, future changes should add fields rather than rename or remove existing fields.
+
+Dashboard firmware should tolerate unknown fields.
+
+Cargo ESP firmware should preserve stable field names once dashboard implementation begins.

docs/dashboard-esp32s3.md

@@ -189,3 +189,17 @@ It may display state and request changes through the Cargo ESP HTTP API, but the
 The ESP32-S3 dashboard should display temperature data from the Cargo ESP API.
 
 DS18B20 sensors are already implemented on the Cargo ESP/WebUI/API side. For v1, the dashboard should not directly own cargo/fridge DS18B20 wiring or sensor reads.
+
+## API Dependency
+
+The ESP32-S3 dashboard depends on the Cargo ESP API contract documented in `docs/cargo-api-contract.md`.
+
+For v1, the dashboard should consume:
+
+- System status
+- Battery/BMS telemetry
+- DS18B20 temperature telemetry
+- Relay/output state
+- Alarm/fault state
+
+The dashboard may request output changes through the Cargo ESP API, but the Cargo ESP remains the source of truth.

docs/project-state.md

@@ -240,3 +240,9 @@ Future work should focus on:
 - Keeping the API contract accurate
 - Displaying existing temperature telemetry on the ESP32-S3 dashboard
 - Preserving Cargo ESP ownership of cargo/fridge temperature sensors
+
+## Cargo API Contract
+
+The current Cargo ESP API ownership and expected endpoint areas are documented in `docs/cargo-api-contract.md`.
+
+This contract should guide future ESP32-S3 dashboard work so dashboard firmware targets stable Cargo ESP data instead of duplicating sensor or relay ownership.