infrapuzzle/esphome/AGENTS.md

AGENTS.md (ESPHome Workspace)

This directory is a self-contained ESPHome project space utilizing dynamic configuration loaders and an interactive flashing CLI.

Rules & Design Standards

Secret Management

• NEVER write plaintext Wi-Fi passwords, tokens, or API keys directly in the YAML configurations.
• DO NOT modify the .gitignore to allow checking in .env files.
• Use ESPHome's !env_var VAR_NAME to inject environment variables at compile-time. Any new secrets must be declared in .env.template and configured locally in .env.

Configuration Standards

• Default board architecture is ESP32 (nodemcu-32s with arduino framework) unless specified.
• Naming conventions for configurations: esdisplay_<name>.yaml or sensor_<name>.yaml.
• All displays should use the time component with SNTP sync for accurate time rendering.
• Prefer importing sensors from Home Assistant over Native API client integrations, as it decouples rendering layouts from automation scripts.

Build and Run Tools

• Use uv run flash.py to compile, validate, clean, or flash ESPHome configurations.
• Avoid triggering direct esphome cli calls unless doing isolated validation tests.