348 files

AGENTS.md

@@ -2,6 +2,44 @@
 
 You are working directly within a Home Assistant installation. Your working directory is `/homeassistant`, which is the live Home Assistant configuration directory.
 
+## Repo-Specific Facts
+
+### Version and Structure
+- **HA Version**: 2026.7.3 (see `.HA_VERSION`)
+- **Config entry point**: `configuration.yaml` — flat config, no `!include_dir` for automations (all in `automations.yaml`)
+- **No packages directory** — all automations live in a single `automations.yaml` (~2960 lines)
+- **Prettier** is configured (`.prettierrc.yaml`) and auto-formats YAML on save; it enforces 2-space indent and double quotes but NOT block-style enforcement or boolean normalization
+
+### Blink Camera Dual-Entity Setup (CRITICAL)
+Blink cameras are connected via **two Homebridge plugins** plus the native HA Blink integration. This creates **two sets of camera entities per physical camera**:
+
+| Physical Camera | HomeKit (Homebridge) | BlinkCameras (Homebridge) | Native HA Blink |
+|----------------|---------------------|--------------------------|-----------------|
+| Front | `camera.front` | `camera.blink_front` | — |
+| Backyard | `camera.backyard` | `camera.blink_backyard` | — |
+| Shed | `camera.backyard_shed` | `camera.blink_backyard_shed` | — |
+| Tree | `camera.backyard_tree` | `camera.blink_backyard_tree` | — |
+| Garage Side | — | `camera.blink_garage_side` | — |
+| Thermopump | — | `camera.blink_thermopump` | — |
+
+**Refresh switches** (`switch.*_refresh_snapshot`) come from the BlinkCameras plugin. When writing automations that take snapshots, **match the camera entity to the plugin that owns the refresh switch** — using a HomeKit camera with a BlinkCameras refresh switch produces stale images. Use `camera.blink_*` entities for snapshot automation.
+
+The `camera.front` → `switch.front_refresh_snapshot` pairing is the known working combination.
+
+### Critical Device Rules
+- **`switch.dragon_egg`** (living room smart plug) — **NEVER turn off after 10 PM**. Always check time before any service call targeting this entity.
+
+### Custom Integrations (33 installed)
+Key ones: `hacs`, `alexa_media`, `hilo`, `powercalc`, `versatile_thermostat`, `webrtc`, `nest_protect`, `midea_ac_lan`, `spook`, `watchman`, `alarmo`, `cync_lights`, `wyzeapi`, `asusrouter`, `trueNas`.
+
+### Zigbee2MQTT
+Config at `zigbee2mqtt/configuration.yaml`. Use `zigporter` for device management (cascade renames, mesh visualization). `hab` can list devices but does NOT cascade references.
+
+### Reload vs Restart
+- After editing `automations.yaml`: call `automation.reload` service (no restart needed)
+- After editing `configuration.yaml`: requires HA restart
+- After editing `scripts.yaml`: call `script.reload` service
+
 ## CRITICAL: User Consent and Scope Rules
 
 You MUST follow these rules strictly: