Project Guidelines

Scope

This AGENTS.md is the workspace-wide instruction source. Do not add a second global .github/copilot-instructions.md unless intentionally replacing this file.
Repository focus: BMU firmware for parallelized battery packs (up to 16 channels), with PlatformIO/Arduino code in firmware/ and ESP-IDF code in firmware-idf/.
Safety is mandatory: do not weaken battery protection logic, topology checks, authentication checks, or reconnect behavior.
Prefer focused diffs in firmware/src/ and firmware-idf/. Avoid unrelated edits in hardware folders unless explicitly requested.

Keep naming/comment language consistent with surrounding files (French-first in legacy firmware paths).
Preserve existing API shapes and file-local style; avoid unrelated refactors.
Prefer small, reviewable patches and reuse existing helpers before introducing new abstractions.
For diagnostics, use DebugLogger categories over ad-hoc Serial.print.

Quick validation before substantial firmware edits:
- pio test -e sim-host
Additional checks when scope grows:
- pio run -e kxkm-s3-16MB
- scripts/check_memory_budget.sh --env kxkm-s3-16MB --ram-max 75 --flash-max 85
- cd firmware-idf && idf.py build
PlatformIO gotcha:
- Keep framework=arduino in [arduino_base] only; do not move it to global [env] (breaks sim-host/native tests).
Canonical command references:

Safety core:
- firmware/src/main.cpp (orchestration + fail-safe topology behavior)
- firmware/src/BatteryParallelator.* (protection state machine)
- firmware/src/BatteryManager.* (aggregated state/metrics)
I2C and peripherals:
- firmware/src/I2CMutex.h (global I2C mutex + I2CLockGuard)
- firmware/src/INAHandler.* (INA237 path)
- firmware/src/TCAHandler.* (TCA9535 path)
Web mutation surface:
- firmware/src/WebServerHandler.*
- firmware/src/WebRouteSecurity.*
- firmware/src/WebMutationRateLimit.*
- firmware/src/BatteryRouteValidation.*

Keep French comments/identifiers consistent with surrounding code.
All I2C access must go through I2CLockGuard.
Keep I2C recovery semantics intact (kI2CRecoveryThreshold = 5 consecutive failures).
Validate battery/sensor indexes before any array/driver access.
Preserve NAN/early-return semantics for sensor and bus faults.
Keep periodic FreeRTOS tasks non-blocking.
Maintain topology constraint Nb_TCA * 4 == Nb_INA; mismatch must remain fail-safe (all batteries OFF).
Keep thresholds centralized in firmware/src/config.h (mV/mA conventions).
Prefer DebugLogger categories (KxLogger.h) over ad-hoc Serial.print.

Start by loading the scoped instruction file for the area being edited:
For firmware safety changes, inspect the relevant code path and the closest sim-host tests before proposing edits.
Reuse existing validation/security helpers and keep diffs minimal.
Update nearby tests when behavior changes (especially protection, routes, auth, rate limiting).
For risk-focused review work, prefer narrow agents in .github/agents/ over broad generic reviews.
Link to existing documentation rather than embedding long duplicated guidance in code changes.