ha-mcp-dev 8.3.0.dev2445__tar.gz → 8.3.0.dev2450__tar.gz

{ha_mcp_dev-8.3.0.dev2445/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2450}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.3.0.dev2445
+Version: 8.3.0.dev2450
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.3.0.dev2445 → ha_mcp_dev-8.3.0.dev2450}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2445"
+version = "8.3.0.dev2450"
 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-8.3.0.dev2445 → ha_mcp_dev-8.3.0.dev2450}/src/ha_mcp/resources/skills-vendor/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, device control, and dashboards",
-    "version": "0.15.0"
+    "version": "0.18.0"
   },
   "plugins": [
     {

{ha_mcp_dev-8.3.0.dev2445 → ha_mcp_dev-8.3.0.dev2450}/src/ha_mcp/resources/skills-vendor/.claude-plugin/plugin.json

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

ha_mcp_dev-8.3.0.dev2450/src/ha_mcp/resources/skills-vendor/AGENTS.md

@@ -0,0 +1,40 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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.
+---
+```
+
+Full authoring constraints: `CONTRIBUTING.md`. The one CI cannot catch:
+- `metadata.version` must be `0` on new skills — do not edit manually; CI assigns the real version on merge
+
+## 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
+- **No tool names** — reference HA REST APIs and concepts, never specific MCP tool names (e.g. `ha_rename_entity`); tool names vary by agent setup
+
+## Validation
+
+To validate locally:
+
+```bash
+uvx skills-ref validate skills/<skill-name>
+```
+
+## Reviewing Skill PRs
+
+- Judge prose as agent-consumed context, not human docs — the Skill Authoring Principles above are the review bar (e.g. an operator→result lookup table beats narrative bullets, because agents land here holding one case to resolve)
+- Skills make version-pinned claims about HA behavior — verify against source at the release tag: `gh api repos/home-assistant/core/contents/<path>?ref=2026.7.4 --jq .content | base64 -d`
+- Community PRs come from forks: base-repo `?ref=<pr-branch>` 404s; get the fork with `gh pr view <pr> --json headRepository` and fetch files from there

ha_mcp_dev-8.3.0.dev2450/src/ha_mcp/resources/skills-vendor/CLAUDE.md

@@ -0,0 +1,40 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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.
+---
+```
+
+Full authoring constraints: `CONTRIBUTING.md`. The one CI cannot catch:
+- `metadata.version` must be `0` on new skills — do not edit manually; CI assigns the real version on merge
+
+## 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
+- **No tool names** — reference HA REST APIs and concepts, never specific MCP tool names (e.g. `ha_rename_entity`); tool names vary by agent setup
+
+## Validation
+
+To validate locally:
+
+```bash
+uvx skills-ref validate skills/<skill-name>
+```
+
+## Reviewing Skill PRs
+
+- Judge prose as agent-consumed context, not human docs — the Skill Authoring Principles above are the review bar (e.g. an operator→result lookup table beats narrative bullets, because agents land here holding one case to resolve)
+- Skills make version-pinned claims about HA behavior — verify against source at the release tag: `gh api repos/home-assistant/core/contents/<path>?ref=2026.7.4 --jq .content | base64 -d`
+- Community PRs come from forks: base-repo `?ref=<pr-branch>` 404s; get the fork with `gh pr view <pr> --json headRepository` and fetch files from there

{ha_mcp_dev-8.3.0.dev2445 → ha_mcp_dev-8.3.0.dev2450}/src/ha_mcp/resources/skills-vendor/README.md

@@ -76,6 +76,7 @@ The `home-assistant-best-practices` skill includes:
 | `references/examples.yaml` | Compound examples combining multiple best practices |
 | `references/appdaemon.md` | AppDaemon apps: when to use vs. native HA, app structure, service calls, scheduling, error handling, safe refactoring impact |
 | `references/blueprint-guide.md` | Blueprint authoring: metadata & `source_url`, inputs & selectors, `target` vs `entity`, defaults, `!input` templating, versioning |
+| `references/backups.md` | Full instance backups vs rolling one object back, when an operation needs a backup first, what an archive contains, encryption keys, restore verification, backup deletion |
 
 ## Contributing
 

{ha_mcp_dev-8.3.0.dev2445 → ha_mcp_dev-8.3.0.dev2450}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/SKILL.md

@@ -5,14 +5,14 @@ description: >
 
   TRIGGER THIS SKILL WHEN:
   - Creating or editing automations, scripts, scenes, or dashboards
-  - Choosing between template sensors and built-in helpers
-  - Restructuring triggers, conditions, or automation modes
-  - Setting up Zigbee button/remote automations
+  - Choosing template sensors vs built-in helpers
+  - Restructuring triggers, conditions, or modes
+  - Zigbee button/remote automations
   - Renaming entities or migrating device_id to entity_id
-  - Configuring dashboard cards or selecting helpers
   - Looking up card types or domain docs
-  - Writing or reviewing AppDaemon apps
-  - Authoring or editing reusable Blueprints
+  - AppDaemon apps
+  - Authoring reusable Blueprints
+  - About to delete a backup, restore a backup, or upgrade Core or the OS
 
   SYMPTOMS:
   - Agent uses Jinja2 templates where native options exist
@@ -22,9 +22,10 @@ description: >
   - Agent hard-codes values or uses raw sensor over helper
   - Agent edits .storage, writes YAML, or generates YAML snippets
   - Agent tells user to edit configuration.yaml for UI integrations
-  - Agent hardcodes entities in a Blueprint or uses free-text input over a selector
+  - Agent hardcodes Blueprint entities or uses free-text over a selector
+  - Agent changes existing state with no recovery path
 metadata:
-  version: 15
+  version: 18
 ---
 
 # Home Assistant Best Practices
@@ -122,6 +123,10 @@ See `references/device-control.md#zigbee-buttonremote-patterns`.
 | Free-text input for an entity/device in a Blueprint | Typed `entity`/`target`/`device` selector | Text lets typos through and fails silently; selectors validate the choice | `references/blueprint-guide.md#inputs-and-selectors` |
 | `!input` used directly inside a template | Bind it to a `variables:` entry, use the variable | `!input` is a YAML tag, not a template value — the template errors or ignores it | `references/blueprint-guide.md#referencing-inputs-input-and-templating` |
 | Publishing a Blueprint without `source_url` | Set `source_url` to the file's canonical URL | Without it users can't re-import updates and sharing is awkward | `references/blueprint-guide.md#blueprint-metadata` |
+| Full instance restore to undo one automation/script/scene/dashboard/helper edit | Roll that object back — write its previous definition back through the config API | A full restore reverts every unrelated change made since the backup and restarts HA | `references/backups.md#which-recovery-path` |
+| Deleting a device/entity/integration, or upgrading Core, without a preceding backup | Take the full backup *before* the operation | Registry deletions can't be undone by writing the old value back, and a backup taken afterward captures the damage | `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 | `references/backups.md` |
+| Calling a service "reversible" without naming its inverse | Treat an operation as reversible only when you can name and target its exact inverse | `vacuum.send_command`, `*.press` and `notify.*` have none; and an exact inverse still doesn't undo the consequence — re-locking a door doesn't un-expose the house | `references/backups.md#when-a-full-backup-earns-its-cost` |
 
 ---
 
@@ -144,3 +149,4 @@ Read these when you need detailed information:
 | `references/examples.yaml` | Need compound examples combining multiple best practices | — |
 | `references/appdaemon.md` | AppDaemon apps: when to use vs. native HA, app structure, service calls, scheduling, error handling, safe refactoring impact | — |
 | `references/blueprint-guide.md` | Authoring reusable blueprints: metadata & `source_url`, inputs & selectors, `target` vs `entity`, defaults, input sections, `!input` templating, versioning | `#when-to-author-a-blueprint`, `#blueprint-metadata`, `#inputs-and-selectors`, `#target-selector-vs-entity-selector`, `#defaults`, `#input-sections`, `#referencing-inputs-input-and-templating`, `#versioning-and-updates`, `#common-pitfalls` |
+| `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 | `#which-recovery-path`, `#when-a-full-backup-earns-its-cost`, `#what-a-full-backup-contains`, `#restoring-consequences-and-verification`, `#deleting-backups`, `#common-pitfalls` |

{ha_mcp_dev-8.3.0.dev2445 → ha_mcp_dev-8.3.0.dev2450}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/automation-patterns.md

@@ -927,6 +927,36 @@ variables:
 
 `trigger_variables:` is a separate top-level key evaluated **before** triggers fire — it supports **limited templates only** (no `states()`/`state_attr()`), mainly for passing a blueprint `!input` into trigger options. Don't put state-based templates there.
 
+### Keys render in order, one at a time
+
+A `variables:` block renders one key at a time, each rendered result feeding the context for the next. A key that reads a name declared **further down the same block** reads it while it is still undefined.
+
+```yaml
+# AVOID — `total` is still undefined when `msg` renders
+variables:
+  msg: "Total: {{ total }}"
+  total: "{{ states('sensor.a') | float(0) + states('sensor.b') | float(0) }}"
+
+# CORRECT — declare before use
+variables:
+  total: "{{ states('sensor.a') | float(0) + states('sensor.b') | float(0) }}"
+  msg: "Total: {{ total }}"
+```
+
+What the forward read costs depends on how the template uses the name (behavior as of 2026.7):
+
+| Use of the undefined name | Result |
+|---|---|
+| `x.attr`, `x['k']`, arithmetic, `<`/`>`/`<=`/`>=`, `\| int`, `\| float` | Raises `UndefinedError`, logs ERROR — **aborts the run** |
+| `{{ x }}`, `{% if x %}`, `{% for i in x %}`, `'p' ~ x` | Empty and falsy, logs WARNING — runs on into the else branch |
+| `x \| length`, `x == y`, `x != y` | `0` / `False` / `True` — **no log and no trace entry** |
+
+For the aborting row, [`continue_on_error:`](#continue-on-error) is no escape — it is an action option, a top-level block is not an action, and on a mid-sequence step it cannot suppress a render error. A default like `| int(0)` does not save it either: the default covers an unconvertible value, not an undefined name. In the silent row, watch `!=`: `{% if later != 'x' %}` on a name that is not defined yet takes the **then** branch, leaving nothing behind to explain why.
+
+Not a problem when the name also exists in an enclosing scope — the reference then resolves outward to that value. The two placements diverge on that collision, though: a top-level `variables:` block **skips** a key already present in the incoming scope, so the incoming value stands and the block's own definition never takes effect for that run, while a mid-sequence `- variables:` step renders and **overwrites** it. Staging a computation across consecutive `variables:` steps is therefore mid-sequence only.
+
+When an automation declares both `trigger_variables:` and `variables:`, the two render as one sequential mapping with `trigger_variables:` first, so a `variables:` key may read a `trigger_variables:` key but not the reverse. That holds for names declared in only one of the two: a name in both merges into a single entry that keeps the `trigger_variables:` position but takes the `variables:` template, so it renders early — before any `trigger_variables:` key declared after it. The separate attach-time render noted above happens before any `variables:` key exists.
+
 ---
 
 ## Capturing Action Responses

ha_mcp_dev-8.3.0.dev2450/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/backups.md

@@ -0,0 +1,128 @@
+# Backups and Recovery
+
+**Three different things get called a "backup" in Home Assistant work.** This file covers the first two, and only the first is a Home Assistant feature:
+
+1. A **full instance backup** — the archive Home Assistant creates at *Settings → System → Backups*, which is also the surface for restoring and deleting one.
+2. **Object rollback** — not an HA feature but a workflow: fetch an object's current definition *before* editing it, then write that definition back through the same config API to undo. One object, no restart.
+3. The **pre-edit file copy** a managed YAML write takes — a different mechanism entirely, covered in `references/yaml-only-integrations.md`.
+
+**Three operations need explicit user confirmation before you act — every time, including when a backup already exists.** They differ in kind, so say which one applies:
+
+- **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.
+
+A backup lowers recovery risk; it does not authorize the action.
+
+## Table of Contents
+1. [Which Recovery Path](#which-recovery-path)
+2. [When a Full Backup Earns Its Cost](#when-a-full-backup-earns-its-cost)
+3. [What a Full Backup Contains](#what-a-full-backup-contains)
+4. [Restoring: Consequences and Verification](#restoring-consequences-and-verification)
+5. [Deleting Backups](#deleting-backups)
+6. [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Which Recovery Path
+
+| Situation | What to do |
+|-----------|------------|
+| One automation / script / scene / dashboard / helper edit went wrong | **Roll the object back** — write its previous definition back through the config API. No restart, nothing else touched. Fetching before writing is what makes this possible; see `references/safe-refactoring.md#universal-workflow`. |
+| Several objects were edited in one session | **Roll each object back**, one at a time. Still no restart. |
+| A device, entity, or area was deleted from the registry | **Restore a full backup.** Registry state — IDs, area/label assignments, and the references other config held to them — cannot be recovered by writing a definition back. |
+| An integration or config entry was removed | **Restore a full backup.** Its entities went with it. |
+| An App update or removal broke something | **Restore a full backup partially** — that App and its data only. Supervisor installs (OS/Supervised) only; elsewhere it is a full restore. |
+| A Core or Operating System upgrade broke the instance | **Restore a full backup.** |
+| The instance no longer boots | **Restore a full backup** through the Supervisor / onboarding restore flow. |
+
+Prefer the narrowest path that can fix the fault. Object rollback is scoped to one object, needs no restart, and cannot lose unrelated work.
+
+**Partial restore is a narrower restore, not a rollback.** HA's partial restore (`hassio.restore_partial`) picks which parts of an existing backup to put back — Home Assistant settings, specific Apps, and folders. Including Home Assistant settings restarts HA. That is a different mechanism from writing one object's definition back through the config API, which restarts nothing.
+
+**Partial restore needs a Supervisor**, so it exists on Home Assistant OS and Supervised only. On Container and Core installs the `hassio` integration is not loaded, there is no partial restore, and the recovery options are object rollback or a full restore through whatever backup mechanism that install uses. Check which install you are on before offering a partial restore as a step.
+
+## 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.**
+
+**Irreversible — take the backup first, and confirm the operation with the user:**
+- Deleting a device, entity, or area from the registry.
+- Removing an integration or config entry.
+- Removing an App, or a major App version jump.
+- Core / Operating System upgrades.
+- Restoring a *different* backup — a restore is itself destructive of current state.
+- Bulk operations across many objects whose before-state was not captured.
+- Editing a Config-Entry integration whose fields have no post-setup API write path — see `references/safe-refactoring.md#config-entry-data--blind-spots-for-entity-registry-renames`.
+
+**Reversible — a backup is usually redundant:**
+- Editing an automation / script / scene / dashboard / helper whose current definition was fetched first. Writing that definition back *is* the undo.
+- Renaming a friendly name, changing an icon, moving an entity between areas.
+- A service call whose inverse you can name and target identically — `light.turn_on` ↔ `light.turn_off` on the same entity.
+
+**Neither list — treat as irreversible until you have checked.** The exact-inverse test is the rule; these are the cases where passing it still is not enough:
+
+- **No inverse exists.** `vacuum.send_command`, any `*.press`, `notify.*` — nothing to call to undo them.
+- **The inverse exists but does not undo the consequence.** `lock.unlock` ↔ `lock.lock` and `cover.open_cover` ↔ `cover.close_cover` are exact inverses, yet the door was unlocked and the cover was open in between. Re-locking restores the state, not the exposure. Confirm these with the user first even though they are mechanically reversible.
+- **The effect has already left Home Assistant.** A sent notification or a fired webhook cannot be recalled, whatever you call next.
+
+"It's just a service call" is not a reversibility argument — the inverse depends on the service and the target, and a reversible state change is not always a reversible event.
+
+Two 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.
+- **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.
+
+## What a Full Backup Contains
+
+Backup contents are **selected per backup**, so what a given archive holds is a property of that archive, not of Home Assistant:
+
+- **Home Assistant settings** — the config directory: `.storage` registries, YAML configuration, and the stored automations, scripts, scenes, dashboards, and helpers.
+- **The recorder database — usually included, but confirm rather than assume.** Home Assistant Core's own backup config defaults `include_database` to true (2026.8.1), so history and long-term statistics normally *are* in the archive and *do* come back. Three things change that answer: the option can be switched off for an individual backup; on Supervised/OS the Supervisor API takes `homeassistant_exclude_database` per backup and the `backups_exclude_database` setting can make exclusion the *default* for every future one; and a recorder pointed at an external database lives outside the archive entirely. Check the archive and the install before telling a user their history will or won't return.
+- **Apps**, individually selectable, with their data directories.
+- **Folders**, individually selectable: `share`, `addons/local`, `ssl`, `media`.
+
+Nothing else on the host is included, and a restore overwrites only the parts a given backup actually contains.
+
+**Encryption and secrets.** Backups are password-protected by default, and restoring one requires its encryption key — the key issued in the backup emergency kit when HA sets up encrypted backups. **An archive without its key is not a recovery point**, so verify the user has the emergency kit before treating a backup as a fallback. A backup downloaded through the UI is decrypted on the way out, and that copy carries `.storage` in cleartext — credentials, long-lived tokens, API keys. Protect the archive and the emergency kit as separate secrets, and never move either anywhere the user has not chosen.
+
+## Restoring: Consequences and Verification
+
+- **Confirm before restoring.** Naming which changes will be lost is part of the ask.
+- A **full restore** reverts every included part to its state at backup time and restarts HA. Unrelated work done in that window is gone.
+- A **partial restore** narrows the blast radius; prefer it whenever the fault is localised. Including Home Assistant settings still restarts HA.
+- An **object rollback** through the config API restarts nothing and touches one object.
+
+After any restore, verify rather than assume:
+- Entities are available, not `unavailable` — a restored config entry whose credentials expired comes back broken.
+- The error log is clean of startup failures.
+- Cloud-backed integrations may need re-authentication; a restore replays a token that may have been rotated since.
+- Objects that were disabled when the backup was taken come back disabled.
+
+## Deleting Backups
+
+Be precise about what Home Assistant protects here, because it is less than it looks:
+
+- The **retention cleanup** that enforces a backup schedule will not delete the last remaining backup for a backup location.
+- A **direct delete of one specific backup** — the operation performed when a user asks for a particular backup to be removed — has **no such guard**, and there is no minimum-age protection anywhere. Delete the only recovery point and Home Assistant will carry it out.
+
+So on this operation the caution has to come from whoever is driving, not from the platform:
+
+- **Confirm the specific backup with the user before deleting it** — name which one and how old it is.
+- **Leave at least one recent, usable recovery point.** Usable includes having its encryption key available.
+- **Delete oldest first** when clearing several.
+
+Storage pressure is not the only legitimate reason to delete. A credential compromise can make the archive itself the liability; a privacy or retention requirement can mandate removal; and a user can simply ask. None of those removes the confirmation step or the keep-one-recovery-point guidance.
+
+## Common Pitfalls
+
+- **Backing up after the destructive step.** The archive now contains the damage.
+- **Using a full restore to undo one config edit.** It reverts every unrelated change since, and restarts HA.
+- **Assuming a direct backup delete is guarded.** It isn't — only the scheduled retention cleanup keeps a last backup.
+- **Treating an archive without its encryption key as a recovery point.** It cannot be restored.
+- **Treating a UI-downloaded backup as an ordinary file.** It is decrypted, and it holds cleartext credentials and tokens.
+- **Claiming history will or won't come back without checking.** The recorder database is included by default, but per-backup selection and external databases both change the answer.
+- **Calling a service "reversible" without naming its inverse** — or treating a mechanical inverse as undoing the consequence, when the door was still unlocked in between.
+- **Treating a backup as a substitute for fetching the current definition before an edit.** Fetching is cheaper, object-scoped, and needs no restart to undo.
+- **Keeping backups only on the instance they back up.** One disk or host failure takes the instance and its recovery points together.
+- **Acting on an irreversible operation because a backup exists.** The backup is the safety net, not the authorization — the user's confirmation is.

{ha_mcp_dev-8.3.0.dev2445 → ha_mcp_dev-8.3.0.dev2450}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/helper-selection.md

@@ -22,7 +22,7 @@ This document covers Home Assistant's built-in helpers and integrations that sho
 Helpers reach Home Assistant through two different creation mechanisms — which one a helper uses determines whether you submit flat fields in a single step or step through a config flow:
 
 - **Storage-collection helpers** — created via a per-domain WebSocket collection command (`<domain>/create`, e.g. `input_boolean/create`, `counter/create`) with flat, structured fields: `input_boolean`, `input_number`, `input_select`, `input_text`, `input_datetime`, `input_button`, `counter`, `timer`, `schedule`, `zone`, `person`, `tag`. (`schedule` additionally offers an optional YAML mode.)
-- **Config-entry-flow helpers** — created through the generic config-entry flow (`config_entries/flow`, handler = the helper domain), often a multi-step flow that begins with a sub-type menu (see [Menu-Based Helpers](#menu-based-helpers)): `template`, `group`, `utility_meter`, `derivative`, `min_max`, `threshold`, `integration`, `statistics`, `trend`, `random`, `filter`, `tod`, `generic_thermostat`, `generic_hygrostat`, `switch_as_x`, `bayesian`, `mold_indicator`.
+- **Config-entry-flow helpers** — created through the generic config-entry flow (`config_entries/flow`, handler = the helper domain), often a multi-step flow that begins with a sub-type menu (see [Menu-Based Helpers](#menu-based-helpers)): `template`, `group`, `utility_meter`, `derivative`, `min_max`, `threshold`, `integration`, `statistics`, `trend`, `random`, `filter`, `tod`, `generic_thermostat`, `generic_hygrostat`, `switch_as_x`, `bayesian`, `mold_indicator`, `history_stats`.
 
 ## Menu-Based Helpers
 
@@ -357,6 +357,9 @@ sensor:
 **Key behaviors:**
 - Limited by recorder's `purge_keep_days`
 - Updates when source changes or once per minute
+- Creatable via the config-entry flow (multi-step: entity and type, then
+  tracked states, then the period — exactly two of `start`/`end`/`duration`);
+  YAML remains supported but is not required
 
 **Common uses:**
 - How long lights were on today

{ha_mcp_dev-8.3.0.dev2445 → ha_mcp_dev-8.3.0.dev2450}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/safe-refactoring.md

@@ -205,7 +205,7 @@ Iterate the returned entries and check `data` and `options` fields for the old e
 
 For integrations that store entity_ids in `options` (Generic Thermostat, Generic Hygrostat, Threshold Helper, Min/Max Helper): use the Options Flow. See the Config-Entry-Groups section above for the full Options Flow pattern.
 
-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.
+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 `references/backups.md#when-a-full-backup-earns-its-cost`.
 
 ---
 

{ha_mcp_dev-8.3.0.dev2445 → ha_mcp_dev-8.3.0.dev2450}/src/ha_mcp/server.py

@@ -828,10 +828,152 @@ class HomeAssistantSmartMCPServer:
             'mean "search failed", not "no results" — see `partial_reason` '
             "(also mirrored into `warnings`). Do not treat a partial response as "
             "complete.\n\n"
-            "For parameters, schema, and examples, see ha_get_skill_guide."
+            "For what to do with what you find — native-first patterns, "
+            "entity_id over device_id, impact analysis before renaming — see "
+            "ha_get_skill_guide."
+        ),
+        # ha_manage_backup: the full description is 4571 dedented chars at
+        # BACKUP_HINT=normal (4672 strong / 4598 weak) and the lite value is
+        # a little over a quarter of that. No exact pair is quoted here on
+        # purpose — three successive edits left a stale figure in this
+        # comment, so the ratio is pinned by
+        # test_backup_lite_description_stays_substantially_smaller instead,
+        # which measures both sides at test time.
+        #
+        # It was the largest full description in the GATEWAY catalog this was
+        # measured against, not in the repo: ha_eval_template (5834) and
+        # ha_get_system_health (5811) are both larger and both unmapped.
+        # The reduction is smaller than pure compression would give because
+        # the safety content below is kept inline. The routing matrix STAYS —
+        # the `action` parameter's own Field description says "Valid (scope,
+        # action) combinations are listed in the tool description", so
+        # trimming it away would leave that pointer aimed at nothing.
+        #
+        # The deferral target now exists: homeassistant-ai/skills#76 landed
+        # references/backups.md, and the submodule pin in this commit
+        # includes it, so test_every_lite_destination_resolves enforces it
+        # rather than the entry sitting on "self-contained". What defers is
+        # the recovery-layer judgment — which of HA's two paths fits which
+        # failure, what an archive actually contains, encryption keys, and
+        # what HA does and does not protect on delete. The eleven worked
+        # examples stay dropped: they were call syntax, which the input
+        # schema already carries.
+        #
+        # destructiveHint is set on this tool, so the lite text keeps every
+        # irreversibility marker inline rather than deferring it: the
+        # restart, the confirm, the human-only enable_snapshot_delete, and
+        # each individual delete guard. It also keeps the two diagnostics
+        # that have no fallback anywhere else — the enable_auto_backup
+        # empty-list ambiguity, and the {backup_hint_text} timing sentence
+        # (resolved per-instance; see _lite_docstring_tokens).
+        "ha_manage_backup": (
+            "Manage Home Assistant backups: full HA snapshots "
+            "(`scope='snapshot'`) and per-entity auto-backups of agent edits "
+            "(`scope='edits'`). Pick the scope first — the wrong one routes "
+            "through the wrong code path.\n\n"
+            "`scope='snapshot'` actions: `create` (slow on a large "
+            "instance — progress heartbeats are sent while waiting, so a "
+            "long wait is not a hang; retrying starts a SECOND backup), "
+            "`list`, `restore` (**restarts HA**), `delete` (needs "
+            "`confirm=True`; disabled until a human sets "
+            "`enable_snapshot_delete` — an agent cannot enable it. Even then "
+            "a delete is refused for scheduled/automatic backups, for "
+            "anything younger than `snapshot_delete_min_age_days` (default "
+            "7; 0 disables the floor), and for the single newest snapshot "
+            "remaining).\n\n"
+            "`scope='edits'` actions: `create` (needs `domain` + "
+            "`entity_id`), `list`, `view`, `diff`, `restore` (takes a fresh "
+            "safety snapshot first; no HA restart), `delete`. Automatic "
+            "capture on write is gated by `enable_auto_backup`, so an empty "
+            '`list` means "nothing saved" OR "the toggle is off" — check it '
+            "before concluding there is nothing to restore. Either way "
+            "`(edits, create)` still works: it bypasses the toggle because "
+            "the request is explicit.\n\n"
+            "Use `edits` to undo a recent agent edit to an "
+            "automation/script/scene/dashboard/helper; use `snapshot` for "
+            "system-wide recovery and before irreversible operations. "
+            "{backup_hint_text}\n\n"
+            "For which recovery path fits which failure, what an archive "
+            "actually contains, and the encryption key a restore needs, see "
+            "ha_get_skill_guide (`references/backups.md`)."
+        ),
+        # ha_report_issue: the dedented docstring is what gets advertised,
+        # not the raw indented one (2351 chars), and the lite value is about
+        # a third of it. Same reason as above for not quoting a pair.
+        #
+        # Unlike every other entry here, the deferral target is the tool's
+        # OWN RESPONSE, not the skill guide: `instructions` (see
+        # tools_bug_report.py) independently re-derives the duplicate check,
+        # the template choice, the missing-tool pre-check, and the mandatory
+        # anonymisation step. Issue reporting is ha-mcp product meta — it
+        # cannot go in the skill pack, whose CONTRIBUTING forbids coupling
+        # skill content to specific MCP tool names. The lite text says so
+        # outright so a compliant agent doesn't spend a call finding out.
+        "ha_report_issue": (
+            "Get diagnostic information plus a ready-to-file report "
+            "template. Covers two kinds of report: a runtime bug (ha-mcp "
+            "errored or behaved unexpectedly) and agent-behaviour feedback "
+            "(the AI used the wrong tool or worked inefficiently). Pick "
+            "based on whether the fault was in ha-mcp or in the agent's own "
+            "choices.\n\n"
+            "The response carries the full workflow in its `instructions` "
+            "field — duplicate check, template selection, the mandatory "
+            "anonymisation step, and the submit URLs — plus "
+            '`missing_tool_hint` for the "a tool I expected is missing" '
+            "case, which is usually a stale client tool list rather than a "
+            "bug. Read `instructions` before presenting anything to the "
+            "user; ha_get_skill_guide does not cover issue reporting."
         ),
     }
 
+    # Where each _LITE_DOCSTRINGS entry's "see ..." pointer actually lands.
+    #
+    # The pointer is the whole bargain of lite mode: the trimmed text is only
+    # acceptable because the detail is reachable. Enforcing that every entry
+    # merely CONTAINS the string "ha_get_skill_guide" (the original
+    # invariant) checks the pointer and never the destination — which is how
+    # an entry deferring to guide content that does not exist could pass
+    # tests (#2153 review). This map names the destination so
+    # tests/src/unit/test_lite_docstrings.py can resolve it against the
+    # vendored skill pack.
+    #
+    # Three legal value forms, each with a matching check in the tests:
+    #
+    #   "references/<file>.md" / "SKILL.md"
+    #       A path inside the home-assistant-best-practices skill. Must
+    #       resolve against the VENDORED pack, and the lite text must carry
+    #       a ha_get_skill_guide pointer to reach it.
+    #   "tool-response:<field>"
+    #       The guidance ships in the tool's own response instead. The field
+    #       must actually be returned, and the lite text must name it.
+    #   "self-contained"
+    #       The entry defers nothing. The lite text must carry NO
+    #       ha_get_skill_guide pointer and name no reference file, so an
+    #       entry cannot quietly re-acquire a pointer to content that isn't
+    #       vendored — which is what "self-contained" exists to prevent.
+    _LITE_DOCSTRING_DESTINATIONS: ClassVar[dict[str, str]] = {
+        "ha_config_get_automation": "references/automation-patterns.md",
+        "ha_config_set_automation": "references/automation-patterns.md",
+        "ha_config_get_script": "references/automation-patterns.md",
+        "ha_config_set_script": "references/automation-patterns.md",
+        "ha_config_get_scene": "references/scenes.md",
+        "ha_config_set_scene": "references/scenes.md",
+        "ha_config_list_helpers": "references/helper-selection.md",
+        "ha_config_set_helper": "references/helper-selection.md",
+        "ha_config_get_dashboard": "references/dashboard-cards.md",
+        "ha_config_set_dashboard": "references/dashboard-guide.md",
+        "ha_call_service": "references/domain-docs.md",
+        "ha_config_set_yaml": "references/yaml-only-integrations.md",
+        # The skill pack has no search reference, so this lands on the
+        # decision workflow. The lite text was reworded to promise what
+        # SKILL.md actually holds (what to do with the results) instead of
+        # "parameters, schema, and examples", which it never had — the
+        # parameters ship in the input schema regardless.
+        "ha_search": "SKILL.md",
+        "ha_manage_backup": "references/backups.md",
+        "ha_report_issue": "tool-response:instructions",
+    }
+
     # Description overrides that REPLACE the original description for BM25.
     # Used to narrow overly broad tools so they stop matching generic queries
     # against ha-mcp's internal BM25 search tool. Only applied when
@@ -840,6 +982,50 @@ class HomeAssistantSmartMCPServer:
     # unnecessarily trim context for other clients.
     _SEARCH_DESCRIPTION_OVERRIDES: ClassVar[dict[str, str]] = {}
 
+    @staticmethod
+    def _lite_docstring_tokens() -> dict[str, str]:
+        """Operator-tuned values interpolated into the lite descriptions.
+
+        ``_LITE_DOCSTRINGS`` is a static ``ClassVar``, but not every full
+        description it replaces is static: ``ha_manage_backup``'s is an
+        f-string built in ``register_backup_tools()`` that interpolates
+        ``_get_backup_hint_text()`` from ``BACKUP_HINT``
+        (strong/normal/weak). Hard-coding one wording into the lite text
+        would make that setting a silent no-op whenever lite mode is on —
+        the add-on UI would confirm a Backup-hint change that changed
+        nothing. So the lite values carry ``{token}`` placeholders and are
+        resolved here, reading the same env var at the same point in
+        startup the full description does.
+        """
+        # Local import: same lazy-seam pattern as backup_manager's
+        # _normalize_config_for_roundtrip import. It does NOT keep the tools
+        # package off the module-load path — server.py already imports
+        # .tools.helpers at module scope — what it avoids is pulling in
+        # tools.backup, which is the actual reason to keep it local.
+        from .tools.backup import _get_backup_hint_text
+
+        return {"backup_hint_text": _get_backup_hint_text()}
+
+    @classmethod
+    def _resolve_lite_docstrings(cls) -> dict[str, str]:
+        """Return ``_LITE_DOCSTRINGS`` with its placeholders filled in.
+
+        Uses ``str.replace`` rather than ``str.format`` so the descriptions
+        stay free to contain literal braces (Jinja examples, JSON) without
+        a stray ``{`` turning into a ``KeyError`` at startup. An unknown
+        placeholder is left verbatim rather than raising —
+        ``test_every_placeholder_in_the_map_is_resolvable`` is what catches a
+        typo'd token, at test time instead of in a user's tool catalog.
+        """
+        tokens = cls._lite_docstring_tokens()
+        resolved: dict[str, str] = {}
+        for name, lite in cls._LITE_DOCSTRINGS.items():
+            filled = lite
+            for token, value in tokens.items():
+                filled = filled.replace("{" + token + "}", value)
+            resolved[name] = filled
+        return resolved
+
     def _apply_lite_docstrings(self) -> None:
         """Swap heavy tool descriptions for shorter variants if enabled.
 
@@ -850,6 +1036,10 @@ class HomeAssistantSmartMCPServer:
         ``ha_get_skill_guide``. Tools not in the
         mapping pass through unchanged.
 
+        Descriptions are resolved through ``_resolve_lite_docstrings`` so
+        operator-tuned text (``BACKUP_HINT``) survives the swap instead of
+        being pinned to whatever wording the static map happened to carry.
+
         Emits a startup WARNING when enabled so non-addon users (Docker,
         uvx, pip) see the trade-off in their logs — the addon UI surfaces
         the same warning via the toggle description. A second WARNING is
@@ -884,7 +1074,7 @@ class HomeAssistantSmartMCPServer:
 
         try:
             self.mcp.add_transform(
-                LiteDocstringsTransform(replacements=self._LITE_DOCSTRINGS)
+                LiteDocstringsTransform(replacements=self._resolve_lite_docstrings())
             )
         except Exception:
             logger.exception("Failed to apply LiteDocstringsTransform")