ha-mcp-dev 9.1.0.dev3344__tar.gz → 9.1.0.dev3348__tar.gz

{ha_mcp_dev-9.1.0.dev3344 → ha_mcp_dev-9.1.0.dev3348}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3344
+Version: 9.1.0.dev3348
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.1.0.dev3344 → ha_mcp_dev-9.1.0.dev3348}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3344"
+version = "9.1.0.dev3348"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.0.dev3344 → ha_mcp_dev-9.1.0.dev3348}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3344"
+version = "9.1.0.dev3348"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-9.1.0.dev3344 → ha_mcp_dev-9.1.0.dev3348}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/SKILL.md

@@ -23,7 +23,7 @@ description: >
   - Existing state changed with no recovery path
   - Jinja copy-pasted between templates
 metadata:
-  version: "53"
+  version: "56"
 ---
 
 # Home Assistant Best Practices
@@ -95,7 +95,7 @@ Default `single` mode is often wrong. See [automation-actions #automation-modes]
 
 ### 5. For buttons and remotes
 - **Any integration exposing an `event.*` entity:** Use `event.received` targeting that entity (see the anti-pattern row below)
-- **ZHA:** No event entities — use an `event` trigger with `device_ieee` (persistent)
+- **ZHA:** `event.received` if the device has an `event.*` entity (2026.10+; none do in 2026.10), otherwise an `event` trigger with `device_ieee` (persistent)
 - **Z2M:** Event entities are experimental and off by default — use a `device` trigger (autodiscovered) or `mqtt` trigger
 
 Read [device-control #buttonremote-patterns](references/device-control.md#buttonremote-patterns) before writing the trigger.
@@ -117,7 +117,7 @@ Read [device-control #buttonremote-patterns](references/device-control.md#button
 | Template binary sensor with threshold | `threshold` helper | Built-in hysteresis support | [helper-selection #threshold](references/helper-selection.md#threshold) |
 | Renaming entity IDs without impact analysis | Follow [safe-refactoring](references/safe-refactoring.md) workflow | Renames break dashboards, scripts, scenes, Config-Entry data, and storage dashboards silently | [safe-refactoring #entity-renames](references/safe-refactoring.md#entity-renames) |
 | Renaming members of Config-Entry-based groups (UI groups) without updating membership | Update group membership via Options Flow after the registry rename | The entity registry rename does not update `options.entities` in the Config Entry — group silently breaks | [safe-refactoring #config-entry-groups](references/safe-refactoring.md#config-entry-groups) |
-| Renaming entities used by Min/Max helpers or custom Config-Entry integrations (e.g. Better Thermostat) without checking their Config-Entry data | Scan the config entries' `data`+`options`; re-select the renamed entity in the Min/Max Options Flow. An integration that keeps it in `data` (Better Thermostat) has no API fix: tell the user and take a full backup before the rename | They store entity_ids in the Config Entry, and a registry rename does not update them; single-source helpers such as Threshold (since 2025.6) and Generic Thermostat update themselves | [safe-refactoring #config-entry-data--blind-spots-for-entity-registry-renames](references/safe-refactoring.md#config-entry-data--blind-spots-for-entity-registry-renames) |
+| Renaming entities used by Min/Max helpers or custom Config-Entry integrations (e.g. Better Thermostat) without checking their Config-Entry data | Scan the config entries' `data`+`options`; re-select the renamed entity in the Min/Max Options Flow. An integration that keeps it in `data` (Better Thermostat) has no API fix: tell the user, offer a full backup, and before the rename wait for their answer on the backup and their go-ahead for the rename | They store entity_ids in the Config Entry, and a registry rename does not update them; single-source helpers such as Threshold (since 2025.6) and Generic Thermostat update themselves | [safe-refactoring #config-entry-data--blind-spots-for-entity-registry-renames](references/safe-refactoring.md#config-entry-data--blind-spots-for-entity-registry-renames) |
 | `template:` sensor/binary sensor in YAML | Template Helper via the config flow | A flow helper reloads in place and stays UI-editable; a `template:` entry needs a config reload and does not. Exceptions are real — trigger-based templates and `attributes:` have no flow field | [helper-selection #template-helpers](references/helper-selection.md#template-helpers) |
 | Editing `.storage/` files or other HA internal state directly | Use the HA REST/WebSocket API to manage state and config entries | `.storage/` files are HA's internal state database; direct edits bypass validation, risk corruption, and can be silently overwritten by HA | — |
 | Looking for automation config in `.storage/` | Read and write automations through the HA config API. UI-created ones are saved to `automations.yaml` | No `.storage/` file holds automation config, in any config mode. `.storage/` holds only the automations' entity registry entries | — |
@@ -133,8 +133,8 @@ Read [device-control #buttonremote-patterns](references/device-control.md#button
 | Old purpose-specific keys (`battery.low`, `vacuum.docked`, `timer.time_remaining`, ...) or trigger `behavior: any`/`last` | Renamed 2026.7 keys (`battery.became_low`, ...) and `behavior: each`/`all` (renamed 2026.6) | Old keys no longer load; old behavior values raise a repair issue and face removal | [triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267](references/triggers-and-conditions.md#purpose-specific-triggers--conditions-default-since-20267) |
 | AppDaemon: callbacks in `__init__`, uncancelled `run_in` timers, state in instance variables, hardcoded entity IDs | Register in `initialize()`, cancel before rescheduling, persist via `input_*` helpers, pass IDs through `self.args` | Each fails silently, resets on reload, or blocks reuse | [appdaemon #appdaemon-specific-anti-patterns](references/appdaemon.md#appdaemon-specific-anti-patterns) |
 | Blueprints: hardcoded entities, free text where a selector belongs, `!input` inside a template, missing `source_url` | Typed `!input` selectors; bind an input to `variables:` before templating it; always set `source_url` | Hardcoding defeats reuse, text lets typos through, and `!input` is a YAML tag rather than a template value | [blueprint-guide #common-pitfalls](references/blueprint-guide.md#common-pitfalls) |
-| Backups: full restore to undo one object edit, no backup before an irreversible operation (registry deletion, integration removal, Core/OS upgrade), calling an action "reversible" without naming its inverse | Roll the single object back; take the backup *before*; name the exact inverse or treat it as irreversible | A full restore reverts every unrelated change since and restarts HA; a backup taken afterward captures the damage | [backups #when-a-full-backup-earns-its-cost](references/backups.md#when-a-full-backup-earns-its-cost) |
-| Restoring a backup, deleting a backup, or upgrading Core or the OS without explicit user confirmation | Ask, name the concrete effect, and wait for an answer — every time, backup or not | A full restore discards everything since the archive for all restored parts and restarts HA; a Supervisor partial restore overwrites only the selected archive parts; deletion destroys a recovery point; a Core/OS upgrade is high-impact and its recovery path IS the pre-upgrade backup | [backups](references/backups.md) |
+| Backups: full restore to undo one object edit, no backup offered before an irreversible operation (registry deletion, integration removal, Core/OS upgrade), calling an action "reversible" without naming its inverse | Roll the single object back; offer the user a backup *before* and wait for their answer; name the exact inverse or treat it as irreversible | A full restore reverts every unrelated change since and restarts HA; a backup taken afterward captures the damage | [backups #when-a-full-backup-earns-its-cost](references/backups.md#when-a-full-backup-earns-its-cost) |
+| Restoring a backup, deleting a backup, or upgrading Core or the OS without explicit user confirmation | Ask, name the concrete effect, and wait for an answer — every time, backup or not | A full restore discards everything since the archive for all restored parts and restarts HA; a Supervisor partial restore overwrites only the selected archive parts; deletion destroys a recovery point; a Core/OS upgrade is high-impact and a pre-upgrade backup is a recovery path | [backups](references/backups.md) |
 | The same non-trivial Jinja expression repeated across templates | Once a native trigger/condition and a built-in helper are ruled out, define it once as a macro in `config/custom_templates/*.jinja` and import it | One definition to fix when the rule changes, instead of copies that drift apart | [template-guidelines #reusable-macros](references/template-guidelines.md#reusable-macros) |
 | `trigger`, `this`, `value_json`, or a `{% set %}` variable used inside an imported macro | Pass it to the macro as an argument | An import does not carry the caller's context — the variable is undefined inside the macro, so it renders empty and any attribute access on it errors (HA's own functions like `states` are globals and do work) | [template-guidelines #imports-do-not-carry-the-callers-context](references/template-guidelines.md#imports-do-not-carry-the-callers-context) |
 
@@ -154,10 +154,10 @@ Read each file whose row matches the task before you answer:
 | [yaml-only-integrations](references/yaml-only-integrations.md) | Creating or editing YAML-only integrations that have no config flow (e.g. `command_line`, platform-based `mqtt`, `rest`) |
 | [device-control](references/device-control.md) | Writing actions, button/remote automations, or using target: |
 | [scenes](references/scenes.md) | Authoring or activating scenes; snapshot/restore patterns, including putting devices back the way they were after a temporary change; snapshot-vs-script distinction |
-| [dashboard-guide](references/dashboard-guide.md) | Designing or modifying Lovelace dashboards — layout, view types, strategies, sections, cards, badges, CSS styling, HACS |
+| [dashboard-guide](references/dashboard-guide.md) | Designing or modifying Lovelace dashboards — layout, view types, strategies, sections, cards, badges, CSS styling, HACS / Marketplace |
 | [dashboard-cards](references/dashboard-cards.md) | Looking up built-in card types (core, energy, legacy) or where to read a card's fields; [entities-card attribute rows](references/dashboard-cards.md#entities-card-attribute-rows-need-type-attribute) — a row with `attribute:` but no `type: attribute` shows the entity state, not the attribute |
 | [domain-docs](references/domain-docs.md) | Looking up integration/domain documentation, or the dedicated doc page for a specific trigger, condition, or action |
 | [examples.yaml](references/examples.yaml) | Need compound examples combining multiple best practices |
 | [appdaemon](references/appdaemon.md) | AppDaemon apps: when to use vs. native HA, app structure, actions, scheduling, error handling, safe refactoring impact |
 | [blueprint-guide](references/blueprint-guide.md) | Authoring reusable blueprints: metadata & `source_url`, inputs & selectors, `target` vs `entity`, defaults, input sections, `!input` templating, versioning |
-| [backups](references/backups.md) | Deciding whether an operation needs a backup first; choosing between a full restore, a partial restore, and rolling one object back; what an archive actually contains; encryption keys and the emergency kit; restore verification; what HA does and does not protect when deleting a backup; whether a git config repo replaces a full backup |
+| [backups](references/backups.md) | Deciding whether to offer a backup before an operation; choosing between a full restore, a partial restore, and rolling one object back; what an archive actually contains; encryption keys and the emergency kit; restore verification; what HA does and does not protect when deleting a backup; whether a git config repo replaces a full backup |

{ha_mcp_dev-9.1.0.dev3344 → ha_mcp_dev-9.1.0.dev3348}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/backups.md

@@ -10,7 +10,7 @@
 
 - **Restoring a backup** — *irreversible*: it discards every change made since that archive and restarts HA. The only way back is another backup taken before the restore.
 - **Deleting a backup** — *irreversible*: the archive is gone, and with it any recovery point it was the last copy of.
-- **Upgrading Core or the OS** — *high-impact rather than strictly irreversible*: it can break integrations and custom components, and the recovery path is restoring the pre-upgrade backup, which is why one has to exist first.
+- **Upgrading Core or the OS** — *high-impact rather than strictly irreversible*: it can break integrations and custom components, and a recovery path is restoring a pre-upgrade backup, so offer one first; if the user declines, tell them the newest backup they already have, if any, lacks the changes made since it was taken.
 
 A backup lowers recovery risk; it does not authorize the action.
 
@@ -44,9 +44,9 @@ Prefer the narrowest path that can fix the fault. Object rollback is scoped to o
 
 ## When a Full Backup Earns Its Cost
 
-The test is reversibility, not how risky something feels: **back up before an operation you cannot undo by writing the old value back.**
+The test is reversibility, not how risky something feels: **offer a backup before an operation you cannot undo by writing the old value back.** Whether to make one is the user's call.
 
-**Irreversible — take the backup first, and confirm the operation with the user:**
+**Irreversible — offer the user a backup first, wait for their answer, and confirm the operation with them:**
 - Deleting a device, entity, or area from the registry.
 - Removing an integration or config entry.
 - Removing an App, or a major App version jump.
@@ -70,7 +70,7 @@ The test is reversibility, not how risky something feels: **back up before an op
 
 Three things this test depends on:
 
-- **Timing is the whole point.** A backup taken *after* the destructive step captures the damage. It must precede the operation.
+- **Timing is the whole point.** A backup taken *after* the destructive step captures the damage. If the user wants one, it must precede the operation.
 - **An existing schedule does not substitute.** On an instance with nightly automatic backups, the newest one can be almost a day stale — fine for reversible edits, not for an irreversible operation about to run now.
 - **A git config repo does not substitute.** A `/config` directory tracked in git conventionally excludes the recorder database, along with `.storage` and `secrets.yaml`, which carry credentials and long-lived tokens in cleartext. Such a repo holds tracked files only, and the irreversible operations above destroy registry, config-entry, or install state that it does not hold. A repo that does track `.storage` carries those credentials into every clone, so it must not go anywhere the user has not chosen, and writing `.storage` back over a running instance is a direct edit of HA's internal state rather than a restore.
 

{ha_mcp_dev-9.1.0.dev3344 → ha_mcp_dev-9.1.0.dev3348}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/dashboard-guide.md

@@ -16,7 +16,7 @@ Patterns and decisions for designing Home Assistant Lovelace dashboards.
 - [Actions](#actions)
 - [Custom Cards](#custom-cards)
 - [CSS Styling](#css-styling)
-- [HACS Integration](#hacs-integration)
+- [HACS and the Marketplace](#hacs-and-the-marketplace)
 - [Complete Example: Multi-View Dashboard](#complete-example-multi-view-dashboard)
 - [Common Pitfalls](#common-pitfalls)
 - [Modern Best Practices](#modern-best-practices)
@@ -425,7 +425,7 @@ Use the HA dashboard resource API to convert inline code to a hosted URL, then r
 
 **Resource caching:** `/local/` is served with `public, max-age=2678400`, a 31-day cache, in desktop browsers as well as the Companion app. Editing a registered `.js` file in place leaves clients on the old copy until it expires or the client clears its cache.
 
-- HACS versions the plugin resource URLs it manages in storage (`?hacstag=<installed version>`), so a card installed through HACS is re-fetched on update. With YAML-mode resources HACS cannot update the URL, so that version string is yours to bump.
+- HACS and the Marketplace register a card's resource on install and version its URL in storage mode: HACS (2026.10 and older) as `?hacstag=<installed version>`, the Marketplace (2026.11 and later) as `?v=<repository id>-<version>`. A card installed through either is re-fetched on update. Do not add its resource again through the resource API; that creates a duplicate. With YAML-mode resources neither can update the URL, so that version string is yours to bump.
 - A resource registered by hand needs the same: bump a version query string on the resource `url`, `/local/quick-status-card.js?v=2.0.0`. Only a changed URL forces every client to re-fetch, so renaming the element tag does not help; the cached module still registers the old tag name.
 - A client already holding a stale copy needs a client-side fix: hard refresh, clear site data for the HA origin, or **Settings** > **Reset frontend cache** in the Companion app.
 
@@ -435,7 +435,7 @@ Use the HA dashboard resource API to convert inline code to a hosted URL, then r
 
 ### Themes
 
-Global styling is done with HA **themes** (YAML maps of CSS variables), not raw CSS. Themes are defined under `frontend: themes:` in YAML or installed via HACS, and selected per user (profile) or per view/card with the `theme` option. Define both modes so OS dark/light switching applies cleanly to both:
+Global styling is done with HA **themes** (YAML maps of CSS variables), not raw CSS. Themes are defined under `frontend: themes:` in YAML or installed from HACS or the Marketplace, and selected per user (profile) or per view/card with the `theme` option. Define both modes so OS dark/light switching applies cleanly to both:
 
 ```yaml
 frontend:
@@ -452,7 +452,7 @@ frontend:
 
 ### Card-mod (Per-Card Styling)
 
-Requires the `card-mod` HACS component. Use sparingly: it patches frontend internals via shadow-DOM selectors, which makes it a frequent source of breakage after HA upgrades — prefer native options and theme variables where they exist, and re-test card-mod styling after every HA update:
+Requires the `card-mod` card from HACS or the Marketplace. Use sparingly: it patches frontend internals via shadow-DOM selectors, which makes it a frequent source of breakage after HA upgrades — prefer native options and theme variables where they exist, and re-test card-mod styling after every HA update:
 
 ```yaml
 type: entities
@@ -468,20 +468,27 @@ entities:
 
 ---
 
-## HACS Integration
+## HACS and the Marketplace
+
+Since 2026.11 the built-in Marketplace replaces HACS. It is under **Settings** > **Marketplace**, not in the sidebar. HACS installs migrate on the first start after the upgrade. On 2026.10 and older, community cards come from HACS, a custom integration. Check the HA version before naming either.
 
 | Use case | Solution |
 |----------|----------|
-| Popular community card | HACS — search and install via HACS API |
+| Popular community card | HACS / Marketplace — search and install via its API |
 | Small custom styling | Inline CSS — register via HA dashboard resource API |
 | One-off custom card | Inline module — register via HA dashboard resource API |
-| Large/complex card | HACS or filesystem (`/config/www/`) |
+| Large/complex card | HACS / Marketplace or filesystem (`/config/www/`) |
 
 ### Finding and Installing Cards
 
-Search HACS for community cards by name/category, review repository details, then install. HACS install operations are destructive — clients will ask for user confirmation.
+Search for community cards by name/category, review repository details, then install. Install operations are destructive, so clients will ask for user confirmation.
+
+The Marketplace (2026.11 and later) has two gates that are the user's decision. An agent can reach both through the UI or the API; it still must not clear them for the user:
+
+- **First-run notice:** install and update fail with `warning_not_accepted` until the user the agent connects as has accepted the notice in **Settings** > **Marketplace**. Browsing works before that. The notice says community projects are not tested or audited by the Home Assistant project and run inside it. Ask the user to read and accept it themselves.
+- **GitHub account:** adding a custom repository (**Add from link**) fails with `github_not_connected` until a GitHub account is connected in the Marketplace. Connecting links the user's own GitHub account, so ask the user to do it. Without one, the Marketplace does not check installed custom repositories for updates on its own. Catalog projects install and update without it.
 
-### Popular HACS Cards
+### Popular Community Cards
 
 - **mushroom** — Modern, clean card collection (v5+ aligns with the native tile card; its template card covers Jinja-driven icon/color/content)
 - **button-card** — Highly customizable buttons with JS templating
@@ -567,7 +574,7 @@ Custom cards predating sections views (early 2024) that haven't updated since ar
 | Entity not found | Use full entity ID: `light.living_room` not `living_room` |
 | Features not working | Match feature type to entity domain (e.g., `light-brightness` only works on `light.*`) |
 | Custom card not loading | Check resource type is `module` and verify URL is accessible |
-| Card too large for inline | Use HACS or filesystem instead |
+| Card too large for inline | Use HACS / Marketplace or filesystem instead |
 | Section title ignored/flagged | Section `title` is deprecated — use a `heading` card as the section's first card |
 | Cards sized with `layout_options` | Deprecated — use `grid_options` (`columns`/`rows`) |
 | Map card markers show entity-name initials instead of values | `label_mode` is a **per-entity** option, not card-level: `"entities": [{"entity": "sensor.x", "label_mode": "state"}]` |

{ha_mcp_dev-9.1.0.dev3344 → ha_mcp_dev-9.1.0.dev3348}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/device-control.md

@@ -159,7 +159,9 @@ so, and offer to count two presses within a short window instead of inventing a
 
 Two Zigbee stacks are exceptions:
 
-- **ZHA has no event platform**, so ZHA remotes use the `zha_event` pattern below.
+- **ZHA added an event platform in 2026.10, but no ZHA device or quirk in that release
+  creates an `event.*` entity.** Check the device's entities first: use `event.received` if
+  one is there, otherwise the `zha_event` pattern below.
 - **Zigbee2MQTT's event entities are experimental and off by default** — they need
   `homeassistant: {experimental_event_entities: true}`, and Z2M documents both the feature
   and its event-type names as subject to change. Prefer its autodiscovered `device` trigger
@@ -167,10 +169,11 @@ Two Zigbee stacks are exceptions:
 
 ### ZHA (Zigbee Home Automation)
 
-ZHA buttons fire `zha_event` events. Use **event triggers** with `device_ieee` (the device's IEEE address), which is **persistent** across re-adds.
+ZHA buttons fire `zha_event` events. When the device has no `event.*` entity, use **event triggers** with `device_ieee` (the device's IEEE address), which is **persistent** across re-adds.
 
 ```yaml
 # RIGHT — device_ieee is persistent across re-adds
+#    (fallback — use event.received if the device has an event.* entity)
 triggers:
   - trigger: event
     event_type: zha_event
@@ -179,6 +182,13 @@ triggers:
       command: "toggle"
 ```
 
+This trigger does not link the automation to the device, so the device page does not list it:
+HA links an `event` trigger to a device only through a `device_id` in its `event_data`. HA turns a ZHA `device` trigger
+(`domain: zha`, `type: remote_button_short_press`, ...) into this same `zha_event` +
+`device_ieee` match, and that one is listed, but it is keyed on the `device_id` (see
+[Entity ID vs Device ID](#entity-id-vs-device-id)). The missing entry is expected and is not a
+reason to switch.
+
 For a complete multi-button remote with trigger_id + choose, see [examples.yaml](examples.yaml) Example 2.
 
 #### Finding ZHA Event Data
@@ -218,6 +228,7 @@ triggers:
 
 | Aspect | ZHA | Zigbee2MQTT |
 |--------|-----|-------------|
+| `event.*` entities | Platform since 2026.10; none created by any device in 2026.10 | Experimental, off by default |
 | Trigger type | `event` trigger | `device` trigger or `mqtt` trigger |
 | Identifier | `device_ieee` (persistent) | `device_id` (autodiscovered) |
 | Event name | `zha_event` | MQTT device trigger |
@@ -509,7 +520,7 @@ Read left to right and stop at the first column that applies.
 
 | Device type | Purpose-specific (check first) | Generic fallback | Zigbee specifics |
 |-------------|-------------------------------|------------------|------------------|
-| Button/Remote | `event.received` on the `event.*` entity, when one exists | `state` on the `event.*` entity (fires on any event type) | ZHA: `event` trigger on `zha_event` + `device_ieee`. Z2M: `device` or `mqtt` trigger |
+| Button/Remote | `event.received` on the `event.*` entity, when one exists | `state` on the `event.*` entity (fires on any event type) | ZHA without an `event.*` entity: `event` trigger on `zha_event` + `device_ieee`. Z2M: `device` or `mqtt` trigger |
 | Motion sensor | `motion.detected` / `motion.cleared` | `state` | — |
 | Door/Window | `door.opened` / `door.closed`, `window.opened` / `window.closed` | `state` | — |
 | Temperature | `temperature.crossed_threshold` / `temperature.changed` | `numeric_state` or `state` | — |

{ha_mcp_dev-9.1.0.dev3344 → ha_mcp_dev-9.1.0.dev3348}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/safe-refactoring.md

@@ -239,7 +239,7 @@ Iterate the returned entries and check `data` and `options` fields for the old e
 
 For an integration marked ❌ that stores entity_ids in `options` (Min/Max Helper): use the Options Flow. See the Config-Entry-Groups section above for the full Options Flow pattern. Integrations marked ✅ need no patch; after the rename, check that their options show the new ID.
 
-For integrations that store entity_ids in `data` (Better Thermostat): `data` fields written during the initial Config Flow setup have no standard API for post-setup mutation — the Options Flow updates `options` only. No API-based fix path exists. Document this limitation to the user before proceeding with a rename. This is the one operation in this guide that a fetch-before-write rollback cannot undo, so treat the rename as irreversible and take a full backup first — see [backups #when-a-full-backup-earns-its-cost](backups.md#when-a-full-backup-earns-its-cost).
+For integrations that store entity_ids in `data` (Better Thermostat): `data` fields written during the initial Config Flow setup have no standard API for post-setup mutation — the Options Flow updates `options` only. No API-based fix path exists. Document this limitation to the user before proceeding with a rename. This is the one operation in this guide that a fetch-before-write rollback cannot undo, so treat the rename as irreversible: offer the user a full backup, and before renaming wait for their answer on the backup and their go-ahead for the rename itself — see [backups #when-a-full-backup-earns-its-cost](backups.md#when-a-full-backup-earns-its-cost).
 
 ---