ha-config/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Root-level YAML files define the Home Assistant configuration.
• Core configuration: configuration.yaml.
• Automations: automations.yaml.
• Scripts: scripts.yaml.
• Scenes: scenes.yaml.
• Groups: groups.yaml.
• Devices: known_devices.yaml.
• Secrets: secrets.yaml (do not commit real secrets; use placeholders).

Build, Test, and Development Commands

• No build step is defined in this repository.
• Use Home Assistant’s built-in config validation before deployment (UI: Settings → System → Check configuration).
• If you use the HA CLI, run ha core check to validate configs.

Coding Style & Naming Conventions

• YAML: 2-space indentation, no tabs.
• Keep keys ordered logically by feature area within each file.
• Use clear, descriptive IDs and aliases for automations/scripts (e.g., alias: "Lights - Evening On").
• Prefer lowercase with underscores for IDs and file references.

Testing Guidelines

• No automated test suite is present.
• Validate changes with Home Assistant configuration check before applying.
• Spot-check automations and scripts after reload.

Commit & Pull Request Guidelines

• Commit messages in history are short and imperative (e.g., update automations).
• Keep commits focused to a single area (automations, scripts, scenes, etc.).
• For PRs, include a concise summary and mention any UI-level checks you performed.

Security & Configuration Tips

• Store credentials in secrets.yaml; reference them with !secret.
• Avoid committing device-specific tokens or external service keys.