# 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.