DD3-LoRa-Bridge-MultiSender/AGENTS.md

Codex Guidance

• PlatformIO is the canonical build and test tool. Keep Arduino as the framework and keep the pinned pioarduino Espressif platform unless a dependency task explicitly changes it.
• Supported environments are production, debug, and test. Use python -m platformio run -e production, python -m platformio run -e debug, and python -m platformio run -e test.
• The canonical non-hardware verification command is python tools/verify.py. It runs config checks, docs checks, dependency checks, builds, compile-only Unity tests, static analysis, and size checks where supported.
• src/main.cpp stays a thin coordinator. Sender runtime belongs in SenderStateMachine; receiver runtime belongs in ReceiverPipeline.
• Preserve sender and receiver behavior unless explicitly tasked otherwise. Preserve LoRa frame layout, ACK payloads, payload schema v4, MQTT topics and JSON keys, CSV layout, Preferences keys, role detection, timing, sleep, retry, and watchdog behavior.
• Add focused regression tests for bug fixes. Run the smallest relevant test first, then run python tools/verify.py before handoff when practical.
• Report every command executed and its result. Report checks that could not be executed and why; never claim hardware validation without hardware.
• Do not flash hardware, require USB devices, edit generated .pio files, add credentials or private keys, suppress warnings/tests to pass, update dependencies incidentally, or do unrelated cleanup.
• Documentation changes must keep README.md, Requirements.md, docs/TESTS.md, and docs/engineering/ aligned with current protocol, persistence, and verification contracts.
• Definition of done: behavior intentionally unchanged, relevant tests added or updated, all supported environments build, compile-only tests pass, docs are updated, and remaining risks are documented.