overland-controller/AGENTS.md

AGENTS.md

Workflow

• Inspect the repo before changing code.
• Make minimal, targeted changes.
• Preserve existing architecture.
• Update docs when APIs, behavior, wiring, or hardware assumptions change.
• Run available validation/tests before finishing.
• Use meaningful commits.
• Explain what changed, why, and any side effects.

Critical Constraints

• Do not modify JBD/Xiaoxiang BLE behavior without explicit approval.
• Do not change BLE timeout, reconnect, scan, or BMS-selection behavior without approval.
• Cargo ESP32 remains the controller, API server, WebUI host, and source of truth.
• Dashboard ESP32-S3 is a client only.
• Do not move relay/BMS/control authority into the dashboard.
• Do not hardcode install-specific names into firmware.
• Preserve API compatibility when practical.
• Prefer HTTP API integration over custom protocols.

Hardware Rules

• ESP32 relay board outputs trigger external fused automotive relays/contactors.
• 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.
• Dashboard 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.

Documentation

Primary docs:

• docs/ARCHITECTURE.md
• docs/HARDWARE.md
• docs/ROADMAP.md
• docs/API.md when API changes