# 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