Add ChatGPT handoff document

docs/CHATGPT_HANDOFF.md

@@ -0,0 +1,131 @@
+# ChatGPT Handoff
+
+Last updated: 2026-06-07
+
+Use this document to bring a new ChatGPT/Codex session up to speed quickly. Keep it current when project goals, architecture, APIs, hardware assumptions, validation status, or near-term priorities change.
+
+## How to Use This
+
+At the start of a new assistant session, provide this file along with:
+
+- `AGENTS.md`
+- `docs/project-state.md`
+- `docs/ARCHITECTURE.md`
+- `docs/HARDWARE.md`
+- `docs/API.md`
+- `docs/ROADMAP.md`
+
+The assistant should treat the Cargo ESP32 firmware and primary docs as the source of truth, then update this handoff before finishing any meaningful change.
+
+## Non-Negotiable Constraints
+
+- Cargo ESP32 remains the controller, API server, WebUI host, and source of truth.
+- Waveshare ESP32-S3 dashboard is a client only.
+- Do not move relay, BMS, or control authority into the dashboard.
+- Do not modify JBD/Xiaoxiang BLE behavior without explicit approval.
+- Do not change BLE timeout, reconnect, scan, or BMS-selection behavior without approval.
+- Do not hardcode install-specific names into firmware.
+- Preserve API compatibility when practical.
+- Prefer HTTP API integration over custom protocols.
+- ESP32 relay board outputs trigger external fused automotive relays/contactors only.
+- Do not route fridge, Starlink, inverter, or other major load current through the ESP32 relay board.
+- Dashboard target is Waveshare ESP32-S3-Touch-LCD-5.
+- Dashboard connects to Cargo ESP32 AP over WiFi and is powered from ACC switched 12V into VIN.
+- Do not power dashboard from OBD-II pin 16 in the permanent install.
+- CAN termination must stay disabled when connected to vehicle CAN.
+
+## Current Status
+
+Current firmware version:
+
+```text
+0.4.0
+```
+
+Current architecture:
+
+- ESP32 relay board is the cargo controller.
+- Embedded WebUI is served by the Cargo ESP32.
+- HTTP API base path is `/api/v1`.
+- Root HTTP routes remain as compatibility aliases for existing local clients.
+- Dashboard direction is Waveshare ESP32-S3 over WiFi/HTTP, not Pico/UART.
+- UART JSON remains optional for diagnostics or alternate clients.
+
+Current working feature areas:
+
+- Relay control through WebUI, HTTP API, UART JSON, and USB serial.
+- JBD/Xiaoxiang BLE BMS telemetry.
+- DS18B20 temperature scan, assignment, clear, and configured naming workflow.
+- WiFi AP recovery network at `192.168.4.1`.
+- STA mode with saved WiFi networks and priorities.
+- Config-driven generic relay and temperature IDs.
+- Config backup/restore API.
+- BMS setup workflow API.
+
+## API Direction
+
+New clients should use `/api/v1`.
+
+Dashboard MVP should initially consume only:
+
+```text
+GET  /api/v1/status
+POST /api/v1/relay/set
+```
+
+Other current HTTP API areas include:
+
+- Health and capability discovery.
+- Configuration read/update/save/factory-reset.
+- Config export/import.
+- WiFi config/connect/clear.
+- Temperature scan/assign/clear.
+- BMS setup enter/exit, scan, and select.
+
+See `docs/API.md` for the current contract and `tests/test_http_api_contract.py` for contract coverage.
+
+## Near-Term Goals
+
+1. Verify WebUI setup workflow after a fresh flash.
+2. Clean up DS18B20 physical distribution hardware.
+3. Test 2-4 temperature probes after the distribution board is installed.
+4. Start the Waveshare ESP32-S3 dashboard MVP over WiFi/HTTP.
+5. Improve BMS out-of-range handling only with explicit approval for BLE behavior changes.
+6. Define future Pi Zero logging/integration role without moving control authority off the Cargo ESP32.
+
+## Recent Context
+
+- The project recently standardized current HTTP routes under `/api/v1`.
+- Health, capabilities, config backup/restore, configuration update, WiFi, temperature setup, and BMS setup endpoints are documented in `docs/API.md`.
+- The embedded WebUI uses `const API_BASE="/api/v1";`.
+- Pre-versioned HTTP routes remain registered as compatibility aliases.
+- `docs/archive/` contains older or superseded planning material and should not override the primary docs.
+
+## Validation Status
+
+Available validation is driven by:
+
+```text
+python3 run_tests.py
+```
+
+The script performs Python compile checks for the dashboard code, then runs:
+
+```text
+python3 -m pytest tests/test_pico_core.py
+python3 -m pytest tests/test_http_api_contract.py
+```
+
+As of this update, the compile step passes in the local environment, but full test execution is blocked because `pytest` is not installed for the active `python3`.
+
+## Handoff Maintenance Checklist
+
+Update this document when any of these change:
+
+- Active project phase or near-term goals.
+- Cargo ESP32 vs dashboard responsibility boundaries.
+- Current firmware version.
+- HTTP API route list, response shape, or compatibility policy.
+- Hardware assumptions, wiring, power, relay, CAN, or dashboard target.
+- Validation commands, dependencies, or current test status.
+- Important decisions that a future assistant should not rediscover from scratch.

docs/README.md

@@ -12,6 +12,7 @@ This folder contains project documentation for Overland Controller.
 
 ## Project Tracking
 
+- `CHATGPT_HANDOFF.md` - Concise assistant handoff with current status, goals, constraints, and validation notes
 - `project-state.md` - Current project state
 - `roadmap.md` - Roadmap and future plans
 - `decisions.md` - Architecture and implementation decisions