ha-mcp-dev 6.7.2.dev240__tar.gz → 6.7.2.dev241__tar.gz

{ha_mcp_dev-6.7.2.dev240/src/ha_mcp_dev.egg-info → ha_mcp_dev-6.7.2.dev241}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 6.7.2.dev240
+Version: 6.7.2.dev241
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -194,6 +194,17 @@ This server gives your AI agent tools to control Home Assistant. For better conf
 
 An MCP server can create automations, helpers, and dashboards, but it has no opinion on *how* to structure them. Without domain knowledge, agents tend to over-rely on templates, pick the wrong helper type, or produce automations that are hard to maintain. The skills fill that gap: native constructs over Jinja2 workarounds, correct helper selection, safe refactoring workflows, and proper use of automation modes.
 
+### Bundled Skills (built-in)
+
+Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
+| `ENABLE_SKILLS_AS_TOOLS` | `false` | Also expose skills via `list_resources`/`read_resource` tools for clients that don't support MCP resources natively. |
+
+Skills can still be installed manually for clients that prefer local skill files — see the [skills repo](https://github.com/homeassistant-ai/skills) for instructions.
+
 ---
 
 ## 🧪 Dev Channel

{ha_mcp_dev-6.7.2.dev240 → ha_mcp_dev-6.7.2.dev241}/README.md

@@ -164,6 +164,17 @@ This server gives your AI agent tools to control Home Assistant. For better conf
 
 An MCP server can create automations, helpers, and dashboards, but it has no opinion on *how* to structure them. Without domain knowledge, agents tend to over-rely on templates, pick the wrong helper type, or produce automations that are hard to maintain. The skills fill that gap: native constructs over Jinja2 workarounds, correct helper selection, safe refactoring workflows, and proper use of automation modes.
 
+### Bundled Skills (built-in)
+
+Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
+| `ENABLE_SKILLS_AS_TOOLS` | `false` | Also expose skills via `list_resources`/`read_resource` tools for clients that don't support MCP resources natively. |
+
+Skills can still be installed manually for clients that prefer local skill files — see the [skills repo](https://github.com/homeassistant-ai/skills) for instructions.
+
 ---
 
 ## 🧪 Dev Channel

{ha_mcp_dev-6.7.2.dev240 → ha_mcp_dev-6.7.2.dev241}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "6.7.2.dev240"
+version = "6.7.2.dev241"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -53,7 +53,7 @@ package-dir = {"" = "src", "tests" = "tests"}
 packages = { find = { where = ["src", "."], include = ["ha_mcp*", "tests"] } }
 
 [tool.setuptools.package-data]
-ha_mcp = ["py.typed", "_pypi_marker", "resources/*.md", "resources/*.json"]
+ha_mcp = ["py.typed", "_pypi_marker", "resources/*.md", "resources/*.json", "resources/skills-vendor/**/*"]
 
 [tool.mypy]
 python_version = "3.11"

{ha_mcp_dev-6.7.2.dev240 → ha_mcp_dev-6.7.2.dev241}/src/ha_mcp/config.py

@@ -79,6 +79,15 @@ class Settings(BaseSettings):
     # Disable when using clients with programmatic tool use (future).
     enable_dashboard_partial_tools: bool = Field(True, alias="ENABLE_DASHBOARD_PARTIAL_TOOLS")
 
+    # Skills configuration
+    # Serve bundled HA best-practice skills as MCP resources (skill:// URIs).
+    # Resources are not auto-injected — clients must explicitly request them.
+    enable_skills: bool = Field(True, alias="ENABLE_SKILLS")
+
+    # Expose skills as tools (list_resources/read_resource) for clients
+    # that don't support MCP resources natively.
+    enable_skills_as_tools: bool = Field(False, alias="ENABLE_SKILLS_AS_TOOLS")
+
     @property
     def env_file_name(self) -> str:
         """Get the current environment file name."""

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/.claude/settings.json

@@ -0,0 +1,11 @@
+{
+  "enabledPlugins": {},
+  "extraKnownMarketplaces": {
+    "anthropic-agent-skills": {
+      "source": {
+        "source": "github",
+        "repo": "anthropics/anthropic-agent-skills"
+      }
+    }
+  }
+}

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "home-assistant-skills",
+  "owner": {
+    "name": "homeassistant-ai",
+    "email": ""
+  },
+  "metadata": {
+    "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, and device control",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "home-assistant-skills",
+      "description": "Best practices for Home Assistant automations, helpers, scripts, and device controls",
+      "source": "./"
+    }
+  ]
+}

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "home-assistant-skills",
+  "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, and device control.",
+  "version": "0.1.0",
+  "repository": "https://github.com/homeassistant-ai/skills",
+  "license": "MIT"
+}

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/.github/ISSUE_TEMPLATE/skill-rca.md

@@ -0,0 +1,89 @@
+---
+name: Report Bad Skill Advice
+about: A skill misled your agent. Have your agent fill out this report so we can fix the skill.
+title: "[RCA] "
+labels: rca
+---
+
+<!--
+INSTRUCTIONS FOR THE AGENT
+
+A skill in this repository misled you, and your user saw the result.
+
+BEFORE FILING: Search existing issues for the same skill and failure.
+If a matching issue exists, react with thumbs-up or comment with
+additional context. Open a new issue only when the failure is unreported.
+
+Fill out each section below. Quote the skill content that misled you,
+list affected entities and configs, and mark the first failure point.
+
+Write "N/A" for any section that is irrelevant.
+-->
+
+## 1. Context
+
+- **Skill name:**  <!-- e.g. home-assistant-best-practices -->
+- **Skill version:**  <!-- from the metadata.version field in SKILL.md frontmatter -->
+- **What the user originally asked you to do:**
+
+## 2. Timeline
+
+List each action you took. For each, record what you did, what resulted, and its status (e.g., Success, Failure).
+
+Mark the first failing step with **[GAP]** in the `Status` column.
+
+| Step | Action | Result | Status |
+|------|--------|--------|-----|
+| 1 | | | |
+| 2 | | | |
+| 3 | | | |
+
+<!-- Add or remove rows as needed. -->
+
+## 3. Root Cause
+
+### 3a. What skill instruction did you follow?
+
+<!--
+Quote the SKILL.md passage or reference file section that guided
+your actions. Include the file name and section heading.
+If the skill offered no guidance for this scenario, write:
+"No guidance found in the skill for this scenario."
+-->
+
+### 3b. What did that instruction cause you to do (or not do)?
+
+<!--
+Describe the action or omission that caused the failure,
+and tie it to the skill content you quoted in 3a.
+-->
+
+### 3c. What should the skill have told you instead?
+
+<!--
+Describe the guidance the skill should have included
+to prevent this failure.
+-->
+
+## 4. Impact
+
+### 4a. Observable failure
+
+<!--
+What failure did the user observe?
+Error messages, broken UI, unexpected behavior, etc.
+-->
+
+### 4b. Blast radius
+
+<!--
+List every affected component: dashboards, automations,
+configurations, entities, integrations, etc.
+If the failure affected only the immediate task, say so.
+-->
+
+## 5. Environment
+
+- **Home Assistant version:**  <!-- e.g. 2025.1.3 -->
+- **Agent platform and model:**  <!-- e.g. Claude Code with Opus 4.5, ChatGPT with GPT-4o -->
+- **Integration / device type involved:**  <!-- e.g. ZHA, Z2M, IKEA FYRTUR, or N/A -->

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/AGENTS.md

@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a community-contributed collection of **Agent Skills** for Home Assistant, following the open [Agent Skills standard](https://agentskills.io/specification). Skills teach AI agents domain expertise for configuring and controlling Home Assistant. The repository doubles as a Claude Code plugin (see `.claude-plugin/plugin.json`).
+
+## Repository Structure
+
+- `skills/<skill-name>/SKILL.md` — each skill lives in its own folder with a `SKILL.md` file
+- `CONTRIBUTING.md` — skill authoring guidelines and submission workflow
+- `.claude-plugin/plugin.json` — Claude Code plugin metadata
+
+## Skill Format
+
+Every skill is a `SKILL.md` file with YAML frontmatter:
+
+```yaml
+---
+name: skill-name-here
+description: >
+  When to activate this skill and what symptoms it addresses.
+---
+```
+
+Constraints from CONTRIBUTING.md:
+- Max **500 lines** per SKILL.md
+- Reference files must be **one level deep** only (e.g. `references/example.yaml`)
+- Use **forward slashes** in all file paths
+- Optional subdirectories: `references/` (additional docs), `scripts/` (utility scripts), `assets/` (static resources)
+
+## Skill Authoring Principles
+
+- **Context window conservation** — only include domain-specific knowledge that agents lack; omit general programming advice
+- **Conciseness** — provide patterns and quick-reference tables, not tutorials
+- **Consistent terminology** — one term per concept throughout a skill
+- **Symptom-based triggering** — the `description` frontmatter should describe observable agent behaviors that signal the skill is needed
+
+## Validation
+
+CI runs `skills-ref validate` on every PR and push to `main` that touches `skills/**`. To validate locally:
+
+```bash
+pip install skills-ref
+python -m skills_ref.cli validate skills/<skill-name>
+```

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a community-contributed collection of **Agent Skills** for Home Assistant, following the open [Agent Skills standard](https://agentskills.io/specification). Skills teach AI agents domain expertise for configuring and controlling Home Assistant. The repository doubles as a Claude Code plugin (see `.claude-plugin/plugin.json`).
+
+## Repository Structure
+
+- `skills/<skill-name>/SKILL.md` — each skill lives in its own folder with a `SKILL.md` file
+- `CONTRIBUTING.md` — skill authoring guidelines and submission workflow
+- `.claude-plugin/plugin.json` — Claude Code plugin metadata
+
+## Skill Format
+
+Every skill is a `SKILL.md` file with YAML frontmatter:
+
+```yaml
+---
+name: skill-name-here
+description: >
+  When to activate this skill and what symptoms it addresses.
+---
+```
+
+Constraints from CONTRIBUTING.md:
+- Max **500 lines** per SKILL.md
+- Reference files must be **one level deep** only (e.g. `references/example.yaml`)
+- Use **forward slashes** in all file paths
+- Optional subdirectories: `references/` (additional docs), `scripts/` (utility scripts), `assets/` (static resources)
+
+## Skill Authoring Principles
+
+- **Context window conservation** — only include domain-specific knowledge that agents lack; omit general programming advice
+- **Conciseness** — provide patterns and quick-reference tables, not tutorials
+- **Consistent terminology** — one term per concept throughout a skill
+- **Symptom-based triggering** — the `description` frontmatter should describe observable agent behaviors that signal the skill is needed
+
+## Validation
+
+CI runs `skills-ref validate` on every PR and push to `main` that touches `skills/**`. To validate locally:
+
+```bash
+pip install skills-ref
+python -m skills_ref.cli validate skills/<skill-name>
+```

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+Skills for this repository follow the [Agent Skills open standard](https://agentskills.io). See the [specification](https://agentskills.io/specification) for the full format reference.
+
+## Skill Format
+
+Structure each skill as a folder under `skills/` with a `SKILL.md` file:
+
+```
+skills/
+  your-skill-name/
+    SKILL.md              # Required
+    references/           # Optional: additional docs loaded on demand
+    scripts/              # Optional: utility scripts
+    assets/               # Optional: static resources (templates, data files)
+```
+
+### SKILL.md requirements
+
+- **YAML frontmatter** with `name` (letters, numbers, hyphens only; 64 chars max) and `description` (1024 chars max).
+- **`metadata.version`** using [semver](https://semver.org/) (e.g. `"1.0.0"`). Bump the version in every PR that changes skill content. CI enforces this.
+- **`description`** in third person. Describe what the skill does and when to use it. Include keywords that help agents match tasks. Don't summarize the skill's workflow.
+- **Body** under 500 lines. Split into reference files if approaching this limit.
+- **Reference files** one level deep from SKILL.md—no nested references.
+- **Forward slashes** in all file paths.
+
+See Anthropic's [skill authoring best practices](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/best-practices) for additional guidance.
+
+## Guiding Principles
+
+**The context window is a public good.** Only add what the agent doesn't already know. Challenge every paragraph: does its token cost justify its value?
+
+**Concise over verbose.** Claude is smart. Provide domain-specific knowledge and patterns, not general explanations.
+
+**Consistent terminology.** Choose one term for each concept and stick to it throughout the skill.
+
+## Reporting Skill Problems
+
+When a skill misleads your agent — broken dashboards, failed automations, wrong configurations — first search existing issues for the same skill and failure. If a matching issue exists, react with thumbs-up or comment with additional context. Otherwise, open a new issue with the **Report Bad Skill Advice** template. Let the agent fill it out — it holds the full context and can trace the failure to its source in the skill.
+
+The template covers five sections: context, timeline, root cause, impact, and environment. A thorough report gives maintainers everything they need to fix the skill in one pass.
+
+## Submitting a Skill
+
+1. Fork this repository.
+2. Create a folder under `skills/` with your skill name.
+3. Write a `SKILL.md` following the format above.
+4. Test your skill with real scenarios.
+5. Submit a pull request describing what your skill teaches and what problems it solves.

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Unofficial and Awesome Home Assistant MCP Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/README.md

@@ -0,0 +1,65 @@
+# Home Assistant Agent Skills
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Agent Skills](https://img.shields.io/badge/Agent_Skills-agentskills.io-blue)](https://agentskills.io)
+
+An **Agent Skill** is a plugin that teaches AI coding agents best practices for a specific technology, delivered as a portable Markdown knowledge pack.
+
+This repository provides an Agent Skill for Home Assistant, following the open [Agent Skills standard](https://agentskills.io/specification). Install a skill and your agent gains Home Assistant best practices that persist across sessions.
+
+## Included Skill
+
+**[home-assistant-best-practices](skills/home-assistant-best-practices/):** Native HA constructs over templates, helper selection, automation modes, Zigbee button patterns, device control best practices, and safe refactoring.
+
+## Installation
+
+### Agent Skills installer
+
+Requires [Node.js 18+](https://nodejs.org/).
+
+```bash
+npx skills add homeassistant-ai/skills
+```
+
+Works with AI coding agents that support the [Agent Skills standard](https://agentskills.io): Claude Code, Cursor, Copilot, VS Code, Gemini CLI, and others. To update: `npx skills update`
+
+### Claude Code plugin
+
+Run each command separately inside Claude Code:
+
+```
+/plugin marketplace add homeassistant-ai/skills
+```
+```
+/plugin install home-assistant-skills@homeassistant-ai-skills
+```
+
+Restart Claude Code after installation for the skill to take effect.
+
+### Claude Desktop / claude.ai
+
+1. Download or clone this repository
+2. Zip the skill folder: `cd skills && zip -r home-assistant-best-practices.zip home-assistant-best-practices/`
+3. **Settings → Capabilities → Skills → Upload skill** → select the `.zip` file
+
+## Skill Contents
+
+The `home-assistant-best-practices` skill includes:
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Decision workflow and quick-reference routing |
+| `references/safe-refactoring.md` | Safe workflow for renaming entities, replacing helpers, restructuring automations |
+| `references/automation-patterns.md` | Native conditions, triggers, waits, automation modes |
+| `references/helper-selection.md` | Built-in helpers vs template sensors (with decision matrix) |
+| `references/template-guidelines.md` | When templates are the right choice |
+| `references/device-control.md` | Service calls, entity_id vs device_id, Zigbee buttons |
+| `references/examples.yaml` | Compound examples combining multiple best practices |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on writing and submitting skills.
+
+## License
+
+MIT

ha_mcp_dev-6.7.2.dev241/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: home-assistant-best-practices
+description: >
+  Best practices for Home Assistant automations, helpers, scripts, and device controls.
+
+  TRIGGER THIS SKILL WHEN:
+  - Creating or editing HA automations, scripts, or scenes
+  - Choosing between template sensors and built-in helpers
+  - Writing or restructuring triggers, conditions, or automation modes
+  - Setting up Zigbee button/remote automations (ZHA or Zigbee2MQTT)
+  - Renaming entities or migrating device_id references to entity_id
+
+  SYMPTOMS THAT TRIGGER THIS SKILL:
+  - Agent uses Jinja2 templates where native conditions, triggers, or helpers exist
+  - Agent uses device_id instead of entity_id in triggers/actions
+  - Agent modifies entity IDs or config objects without checking all consumers
+  - Agent chooses wrong automation mode (e.g., single for motion lights)
+metadata:
+  version: "1.0.0"
+---
+
+# Home Assistant Best Practices
+
+**Core principle:** Use native Home Assistant constructs wherever possible. Templates bypass validation, fail silently at runtime, and make debugging opaque.
+
+## Decision Workflow
+
+Follow this sequence when creating any automation:
+
+### 0. Gate: modifying existing config?
+
+If your change affects entity IDs or cross-component references — renaming entities, replacing template sensors with helpers, converting device triggers, or restructuring automations — read `references/safe-refactoring.md` first. That reference covers impact analysis, device-sibling discovery, and post-change verification. Complete its workflow before proceeding.
+
+Steps 1-5 below apply to new config or pattern evaluation.
+
+### 1. Check for native condition/trigger
+Before writing any template, check `references/automation-patterns.md` for native alternatives.
+
+**Common substitutions:**
+- `{{ states('x') | float > 25 }}` → `numeric_state` condition with `above: 25`
+- `{{ is_state('x', 'on') and is_state('y', 'on') }}` → `condition: and` with state conditions
+- `{{ now().hour >= 9 }}` → `condition: time` with `after: "09:00:00"`
+- `wait_template: "{{ is_state(...) }}"` → `wait_for_trigger` with state trigger (caveat: different behavior when state is already true — see `references/safe-refactoring.md#trigger-restructuring`)
+
+### 2. Check for built-in helper
+Before creating a template sensor, check `references/helper-selection.md`.
+
+**Common substitutions:**
+- Sum/average multiple sensors → `min_max` integration
+- Binary any-on/all-on logic → `group` helper
+- Rate of change → `derivative` integration
+- Cross threshold detection → `threshold` integration
+- Consumption tracking → `utility_meter` helper
+
+### 3. Select correct automation mode
+Default `single` mode is often wrong. See `references/automation-patterns.md#automation-modes`.
+
+| Scenario | Mode |
+|----------|------|
+| Motion light with timeout | `restart` |
+| Sequential processing (door locks) | `queued` |
+| Independent per-entity actions | `parallel` |
+| One-shot notifications | `single` |
+
+### 4. Use entity_id over device_id
+`device_id` breaks when devices are re-added. See `references/device-control.md`.
+
+**Exception:** Zigbee2MQTT autodiscovered device triggers are acceptable.
+
+### 5. For Zigbee buttons/remotes
+- **ZHA:** Use `event` trigger with `device_ieee` (persistent)
+- **Z2M:** Use `device` trigger (autodiscovered) or `mqtt` trigger
+
+See `references/device-control.md#zigbee-buttonremote-patterns`.
+
+---
+
+## Critical Anti-Patterns
+
+| Anti-pattern | Use instead | Why | Reference |
+|---|---|---|---|
+| `condition: template` with `float > 25` | `condition: numeric_state` | Validated at load, not runtime | `references/automation-patterns.md#native-conditions` |
+| `wait_template: "{{ is_state(...) }}"` | `wait_for_trigger` with state trigger | Event-driven, not polling; waits for *change* (see `references/safe-refactoring.md#trigger-restructuring` for semantic differences) | `references/automation-patterns.md#wait-actions` |
+| `device_id` in triggers | `entity_id` (or `device_ieee` for ZHA) | device_id breaks on re-add | `references/device-control.md#entity-id-vs-device-id` |
+| `mode: single` for motion lights | `mode: restart` | Re-triggers must reset the timer | `references/automation-patterns.md#automation-modes` |
+| Template sensor for sum/mean | `min_max` helper | Declarative, handles unavailable states | `references/helper-selection.md#numeric-aggregation` |
+| Template binary sensor with threshold | `threshold` helper | Built-in hysteresis support | `references/helper-selection.md#threshold` |
+| Renaming entity IDs without impact analysis | Follow `references/safe-refactoring.md` workflow | Renames break dashboards, scripts, and scenes silently | `references/safe-refactoring.md#entity-renames` |
+
+---
+
+## Reference Files
+
+Read these when you need detailed information:
+
+| File | When to read | Key sections |
+|------|--------------|--------------|
+| `references/safe-refactoring.md` | Renaming entities, replacing helpers, restructuring automations, or any modification to existing config | `#universal-workflow`, `#entity-renames`, `#helper-replacements`, `#trigger-restructuring` |
+| `references/automation-patterns.md` | Writing triggers, conditions, waits, or choosing automation modes | `#native-conditions`, `#trigger-types`, `#wait-actions`, `#automation-modes`, `#ifthen-vs-choose`, `#trigger-ids` |
+| `references/helper-selection.md` | Deciding whether to use a built-in helper vs template sensor | `#numeric-aggregation`, `#rate-and-change`, `#time-based-tracking`, `#counting-and-timing`, `#scheduling`, `#entity-grouping`, `#decision-matrix` |
+| `references/template-guidelines.md` | Confirming templates ARE appropriate for a use case | `#when-templates-are-appropriate`, `#when-to-avoid-templates`, `#template-sensor-best-practices`, `#common-patterns`, `#error-handling` |
+| `references/device-control.md` | Writing service calls, Zigbee button automations, or using target: | `#entity-id-vs-device-id`, `#service-calls-best-practices`, `#zigbee-buttonremote-patterns`, `#domain-specific-patterns` |
+| `references/examples.yaml` | Need compound examples combining multiple best practices | — |