ha-mcp-dev 8.3.0.dev2444__tar.gz → 8.3.0.dev2447__tar.gz

{ha_mcp_dev-8.3.0.dev2444/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2447}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.3.0.dev2444
+Version: 8.3.0.dev2447
 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.dev2444 → ha_mcp_dev-8.3.0.dev2447}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2444"
+version = "8.3.0.dev2447"
 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.dev2444 → ha_mcp_dev-8.3.0.dev2447}/src/ha_mcp/client/rest_client.py

@@ -8,6 +8,7 @@ import logging
 import os
 import ssl
 import time
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from typing import Any, NoReturn
 
@@ -52,10 +53,23 @@ logger = logging.getLogger(__name__)
 _RETRYABLE_GATEWAY_STATUS = frozenset({502, 503, 504})
 _SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
 _MAX_REQUEST_ATTEMPTS = 3
-# Journald window requested for the Core error log on Supervisor-backed
-# installs. Both such branches of get_error_log() build their request from this
-# constant, so the window they ask for cannot drift apart.
-_ERROR_LOG_LINES = 20000
+# Smallest log window this client requests. Supervisor's Range syntax addresses
+# a newest-anchored window by its first entry, so a one-entry one is
+# inexpressible (``entries=:0:1`` reads from the OLDEST entry instead);
+# Supervisor coerces its own ``?lines=1`` to 2 (supervisor/api/host.py) and this
+# client mirrors that on every route, so all install types serve the same slice.
+# Shared with the tool layer, which sizes its fetch window against it.
+MIN_LOG_WINDOW_LINES = 2
+# Entries the has_more probe reads from just behind a full window. A one-entry
+# probe compared one rendered line, which a boundary duplicate (the same
+# timestamp-less traceback line logged twice) could false-match into "end of
+# history". Comparing a block this deep requires that many CONSECUTIVE
+# identical lines to straddle the boundary — and then the history a false stop
+# skips is more of the same duplicates. Timestamps cannot close the gap
+# instead: the colliding lines are exactly the ones without them, and
+# journald's cursor/timestamp metadata exists only in the journal export
+# format, which the hassio-proxy route cannot request.
+_PROBE_ENTRIES = 8
 
 
 class HomeAssistantError(Exception):
@@ -96,7 +110,7 @@ class HomeAssistantAuthError(HomeAssistantError):
     auth errors as part of the local "this entity is not registered yet"
     polling logic. Sites that specifically need to catch both must list
     them explicitly (see ``_get_supervisor_log`` and
-    ``_get_system_service_log`` in ``tools_utility.py``).
+    ``_get_system_service_log`` in ``log_sources_supervisor.py``).
     """
 
 
@@ -114,6 +128,19 @@ class HomeAssistantAPIError(HomeAssistantError):
         self.response_data = response_data
 
 
+@dataclass(frozen=True)
+class ErrorLogPage:
+    """One bounded window of the error log, plus whether older history exists.
+
+    ``has_more`` cannot be derived by the caller from ``text``: a journald
+    window that comes back full may or may not have anything behind it (see
+    ``_journald_error_log_page``), and only the fetching route knows which.
+    """
+
+    text: str
+    has_more: bool
+
+
 @dataclass(frozen=True)
 class SceneResolution:
     """Outcome of resolving a scene identifier via the entity registry.
@@ -579,8 +606,140 @@ class HomeAssistantClient:
         logger.debug("Checking configuration")
         return await self._request("POST", "/config/core/check_config")
 
-    async def get_error_log(self) -> str:
-        """Get Home Assistant error log.
+    @staticmethod
+    def _journald_range_header(lines: int, offset: int = 0) -> str:
+        """Build Supervisor's journald ``Range`` header for a bounded window.
+
+        Supervisor's log endpoints accept
+        ``Range: entries=<cursor>:<num_skip>:<num_entries>`` and build
+        ``entries=:-{N-1}:{N}`` themselves for a ``?lines=N`` request
+        (supervisor/api/host.py). ``offset`` moves the window that many entries
+        further back, so the returned slice ends ``offset`` entries before the
+        newest one.
+
+        A ``lines=1`` window is only expressible with a non-zero ``offset``: at
+        ``offset=0`` the header degenerates to ``entries=:0:1``, whose
+        non-negative skip reads from the OLDEST entry instead of the newest.
+        Callers anchoring at the newest entry pass ``lines`` already floored at
+        ``MIN_LOG_WINDOW_LINES``; the one-entry probe always carries an offset.
+        """
+        # Negate the computed skip rather than prefixing "-" so the degenerate
+        # skip of 0 renders as ":0:" (non-negative, reads from the oldest
+        # entry) instead of the ill-formed ":-0:".
+        return f"entries=:{-(offset + lines - 1)}:{lines}"
+
+    @staticmethod
+    def _container_error_log_page(text: str, lines: int, offset: int) -> ErrorLogPage:
+        """Window the whole-file ``/api/error_log`` body client-side.
+
+        Same tail semantics as the journald Range the Supervisor-backed
+        branches request, so ``get_error_log`` answers with the same slice of
+        history on every install type. Paging is exact here — the whole file is
+        in hand, so ``has_more`` is simply whether anything precedes the window.
+        An ``offset`` past the start of the file yields an empty final page.
+        """
+        all_lines = text.splitlines()
+        end = len(all_lines) - offset
+        if end <= 0:
+            return ErrorLogPage(text="", has_more=False)
+        start = max(end - lines, 0)
+        return ErrorLogPage(text="\n".join(all_lines[start:end]), has_more=start > 0)
+
+    async def _supervisor_core_logs(self, lines: int, offset: int) -> str:
+        """Fetch a journald window of HA Core's log straight from Supervisor."""
+        return await self._supervisor_logs_get("core", lines=lines, offset=offset)
+
+    async def _proxied_core_logs(self, lines: int, offset: int) -> str:
+        """Fetch the same window through HA Core's hassio proxy with the LLA."""
+        response = await self._raw_request(
+            "GET",
+            "/hassio/core/logs",
+            headers={
+                "Accept": "text/plain",
+                "Range": self._journald_range_header(lines, offset),
+            },
+        )
+        return response.text
+
+    async def _journald_error_log_page(
+        self,
+        lines: int,
+        offset: int,
+        fetch: Callable[[int, int], Awaitable[str]],
+    ) -> ErrorLogPage:
+        """Read one journald window and settle ``has_more`` with a 1-entry probe.
+
+        systemd's journal-gatewayd does not guard the negative-skip branch the
+        way it guards the positive one (``sd_journal_previous_skip(-n_skip + 1)``
+        returns no END_OF_STREAM): an offset past the start of the journal
+        CLAMPS to the oldest entry and still answers with a full window. So a
+        saturated window proves nothing about what lies behind it, and a
+        count-based ``has_more`` would stay true forever — an agent following
+        the pagination hint would loop on identical pages.
+
+        Hence: a short or empty window means the journal really is exhausted
+        (nothing clamps a window smaller), and a saturated one is settled by
+        asking for the ``_PROBE_ENTRIES`` entries that should sit just behind
+        it. If the journal has nothing there, the clamp starts the probe at
+        the same oldest entry the window starts with, so the probe block
+        equals the window's opening lines — identity means end of history. A
+        differing block proves deeper history (an under-full span behind the
+        window also clamps and misaligns, which correctly reads as "more").
+        The identity check also terminates the degraded case where an
+        intermediary strips the ``Range`` header (RFC 7233 permits it): both
+        requests then return Supervisor's default window and compare equal.
+
+        The saturation test counts lines only to decide whether to probe, never
+        to answer: one journald entry can be a multi-line traceback, so the line
+        count over-estimates entries and can only over-trigger the probe, which
+        then gives the real answer. In practice the two rarely diverge here:
+        docker's journald log driver — how HAOS captures Core's output —
+        ingests stdout line by line, one journal entry per rendered line, so
+        multi-line entries reach this endpoint only from native journal-API
+        writers.
+
+        Known imprecision, accepted: the identity check can still stop one
+        page early when the compared block — ``_PROBE_ENTRIES`` lines, or the
+        window's own length when that is smaller — is byte-identical across
+        the boundary (see the constant's comment for why timestamps cannot
+        disambiguate instead). The failure
+        direction is a missed page of exactly those duplicates — bounded,
+        unlike the infinite loop a count-based ``has_more`` produces on the
+        clamp.
+        """
+        text = await fetch(lines, offset)
+        if not text or len(text.splitlines()) < lines:
+            return ErrorLogPage(text=text, has_more=False)
+        probe = await fetch(_PROBE_ENTRIES, offset + lines)
+        probe_lines = probe.splitlines()
+        window_lines = text.splitlines()
+        # Compare the shared-length prefix: with a window smaller than the
+        # probe (lines < _PROBE_ENTRIES), an end-of-history clamp returns a
+        # probe LONGER than the window, and a full-length compare would read
+        # that as "more history" forever — the small-limit loop this method
+        # exists to prevent.
+        shared = min(len(probe_lines), len(window_lines))
+        return ErrorLogPage(
+            text=text,
+            has_more=shared > 0 and probe_lines[:shared] != window_lines[:shared],
+        )
+
+    async def get_error_log(self, lines: int, offset: int = 0) -> ErrorLogPage:
+        """Get a bounded window of the Home Assistant error log.
+
+        ``lines`` is the number of log lines to fetch and ``offset`` how many
+        newer lines to skip, counted back from the most recent one; both are
+        floored/served at ``MIN_LOG_WINDOW_LINES``. Returns the window text and
+        whether older history remains behind it. The window is mandatory: the
+        unconditional 20,000-line fetch this replaces made Supervisor assemble
+        a journald slice for 15+ minutes on real hardware (#2279).
+
+        The whole body runs under one ``asyncio.timeout(self.timeout)``. That
+        is the only bound that holds here: ``httpx.Timeout`` applies per I/O
+        operation, so a server trickling bytes while it assembles the body
+        resets the read timeout indefinitely and no per-attempt timeout ever
+        fires — the mechanism behind #2279's hang. The deadline covers the
+        install-class probe, the log fetch and the ``has_more`` probe together.
 
         Three-way branch depending on how this client reaches HA:
 
@@ -601,6 +760,17 @@ class HomeAssistantClient:
         - **External client → Container/pip HA** (neither of the above):
           keep the historical ``/api/error_log`` proxy path.
 
+        The two Supervisor-backed branches express the window as a journald
+        ``Range`` header (see ``_journald_range_header``) and settle
+        ``has_more`` with a one-entry probe (see ``_journald_error_log_page``).
+        HA Core's hassio proxy forwards that header for its log paths
+        (``PATHS_LOGS`` in ``homeassistant/components/hassio/http.py``); an
+        intermediary that stripped it would degrade to Supervisor's 100-line
+        default, never to an unbounded fetch, and the probe still terminates
+        paging. ``/api/error_log`` is a whole-file plain-text endpoint with no
+        window support, so the container branch reads the file and applies the
+        same window client-side, where paging is exact.
+
         The middle branch was discovered by the HAOS E2E tier (#1326): the
         test harness runs ha-mcp externally against a booted HAOS, hits
         the unregistered endpoint, and the old binary branch surfaced as
@@ -615,30 +785,36 @@ class HomeAssistantClient:
             HomeAssistantConnectionError: Network, timeout, or transport
                 error.
         """
-        if is_running_in_addon():
-            logger.debug("Fetching error log via Supervisor direct (core service)")
-            # An explicit `lines` is required: without it Supervisor applies its
-            # 100-line default, which is far too short a slice to tell what keeps
-            # repeating. `_get_supervisor_log` plumbs the same parameter for the
-            # same reason (#1734).
-            return await self._supervisor_logs_get("core", lines=_ERROR_LOG_LINES)
-
-        if await self._is_supervised_install():
-            logger.debug(
-                "Fetching error log via HA Core /hassio/core/logs proxy (supervised)"
-            )
-            raw_response = await self._raw_request(
-                "GET",
-                f"/hassio/core/logs?lines={_ERROR_LOG_LINES}",
-                headers={"Accept": "text/plain"},
-            )
-            return raw_response.text
+        window = max(lines, MIN_LOG_WINDOW_LINES)
+        try:
+            async with asyncio.timeout(self.timeout):
+                if is_running_in_addon():
+                    logger.debug(
+                        "Fetching error log via Supervisor direct (core service)"
+                    )
+                    return await self._journald_error_log_page(
+                        window, offset, self._supervisor_core_logs
+                    )
 
-        logger.debug("Fetching error log via HA Core proxy (Container/pip)")
-        raw_response = await self._raw_request(
-            "GET", "/error_log", headers={"Accept": "text/plain"}
-        )
-        return raw_response.text
+                if await self._is_supervised_install():
+                    logger.debug(
+                        "Fetching error log via HA Core /hassio/core/logs proxy "
+                        "(supervised)"
+                    )
+                    return await self._journald_error_log_page(
+                        window, offset, self._proxied_core_logs
+                    )
+
+                logger.debug("Fetching error log via HA Core proxy (Container/pip)")
+                raw_response = await self._raw_request(
+                    "GET", "/error_log", headers={"Accept": "text/plain"}
+                )
+                return self._container_error_log_page(raw_response.text, window, offset)
+        except TimeoutError as e:
+            raise HomeAssistantConnectionError(
+                f"Timeout fetching the error log after {self.timeout}s: "
+                f"{str(e) or type(e).__name__}"
+            ) from e
 
     async def _is_supervised_install(self) -> bool:
         """Detect whether the target HA is a Supervised / HAOS install.
@@ -742,12 +918,30 @@ class HomeAssistantClient:
             return await self._get_addon_logs_via_supervisor(slug, lines=lines)
 
         logger.debug(f"Fetching addon logs for slug={slug} via HA Core proxy")
-        response = await self._raw_request(
-            "GET",
-            f"/hassio/addons/{slug}/logs",
-            headers={"Accept": "text/plain"},
-            params={"lines": lines} if lines is not None else None,
-        )
+        return await self._proxied_logs_get(f"addons/{slug}", lines)
+
+    async def _proxied_logs_get(self, path: str, lines: int | None) -> str:
+        """Fetch ``text/plain`` logs through HA Core's hassio proxy.
+
+        Wrapped in an overall wall-clock deadline for the same reason as the
+        error-log routes (#2279): ``httpx.Timeout`` applies per I/O operation,
+        so a server trickling bytes while assembling the body resets the read
+        timeout indefinitely, and the deadline is the only bound that holds.
+        It caps the whole ``_raw_request`` retry envelope.
+        """
+        try:
+            async with asyncio.timeout(self.timeout):
+                response = await self._raw_request(
+                    "GET",
+                    f"/hassio/{path}/logs",
+                    headers={"Accept": "text/plain"},
+                    params={"lines": lines} if lines is not None else None,
+                )
+        except TimeoutError as e:
+            raise HomeAssistantConnectionError(
+                f"Timeout fetching /hassio/{path}/logs from Home Assistant "
+                f"after {self.timeout}s: {str(e) or type(e).__name__}"
+            ) from e
         return response.text
 
     @staticmethod
@@ -772,7 +966,12 @@ class HomeAssistantClient:
             message = text_body.strip() or reason_phrase or "<empty body>"
         return message
 
-    async def _supervisor_logs_get(self, path: str, lines: int | None = None) -> str:
+    async def _supervisor_logs_get(
+        self,
+        path: str,
+        lines: int | None = None,
+        offset: int | None = None,
+    ) -> str:
         """Fetch ``text/plain`` logs from a Supervisor REST endpoint.
 
         ``path`` is everything between ``http://supervisor/`` and ``/logs``:
@@ -782,11 +981,22 @@ class HomeAssistantClient:
           cli, multicast, observer}) for system-service logs
 
         ``lines`` maps to the endpoint's ``?lines=`` journald-window query
-        param; omitted → Supervisor's 100-line default window.
+        param; omitted → Supervisor's 100-line default window. Adding
+        ``offset`` switches the same window to a ``Range: entries=`` header
+        (see ``_journald_range_header``), which is the only form that can
+        address an older window. The two forms are mutually exclusive on the
+        wire — Supervisor tests ``if "lines" in request.query`` first and
+        ignores a ``Range`` header whenever that query param is present — so
+        the offset form sends the window in the header and no query param,
+        rather than a pair that could contradict each other.
 
         Bypasses ``HomeAssistantClient.httpx_client`` because that client targets
         Home Assistant Core through ``http://supervisor/core/api``, while logs
-        belong to Supervisor at ``http://supervisor``. Both clients use the same
+        belong to Supervisor at ``http://supervisor``. Plain HTTP here is the
+        platform contract, not a downgrade: Supervisor serves its API over
+        HTTP only (no TLS endpoint or IPC socket exists), on the internal
+        ``hassio`` docker network whose isolation is the boundary protecting
+        the token — see SECURITY.md § "Local network is the trusted zone". Both clients use the same
         ``SUPERVISOR_TOKEN``; the Core proxy requires ``homeassistant_api``, while
         system-service and arbitrary app-log paths require ``hassio_api`` and
         ``hassio_role: manager``. The recognized-app-token exception is
@@ -815,11 +1025,19 @@ class HomeAssistantClient:
             )
 
         relative_path = f"/{path}/logs"
+        headers = {"Accept": "text/plain"}
+        params = {"lines": lines} if lines is not None else None
+        if offset is not None:
+            # An offset window with no size asked for falls back to the
+            # smallest one the Range syntax can express.
+            size = lines if lines is not None else MIN_LOG_WINDOW_LINES
+            headers["Range"] = self._journald_range_header(size, offset)
+            params = None
         logger.debug(
-            "Fetching %s%s via Supervisor direct (lines=%s)",
+            "Fetching %s%s via Supervisor direct (%s)",
             get_supervisor_base_url(),
             relative_path,
-            lines,
+            f"range={headers['Range']}" if offset is not None else f"lines={lines}",
         )
 
         try:
@@ -830,8 +1048,8 @@ class HomeAssistantClient:
                 ) as client:
                     response = await client.get(
                         relative_path,
-                        headers={"Accept": "text/plain"},
-                        params={"lines": lines} if lines is not None else None,
+                        headers=headers,
+                        params=params,
                     )
         except (TimeoutError, httpx.TimeoutException) as e:
             raise HomeAssistantConnectionError(
@@ -924,13 +1142,7 @@ class HomeAssistantClient:
             return await self._supervisor_logs_get(service, lines=lines)
 
         logger.debug(f"Fetching {service} logs via HA Core proxy")
-        response = await self._raw_request(
-            "GET",
-            f"/hassio/{service}/logs",
-            headers={"Accept": "text/plain"},
-            params={"lines": lines} if lines is not None else None,
-        )
-        return response.text
+        return await self._proxied_logs_get(service, lines)
 
     async def test_connection(self) -> tuple[bool, str | None]:
         """

{ha_mcp_dev-8.3.0.dev2444 → ha_mcp_dev-8.3.0.dev2447}/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.dev2444 → ha_mcp_dev-8.3.0.dev2447}/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.dev2447/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.dev2447/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.dev2444 → ha_mcp_dev-8.3.0.dev2447}/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.dev2444 → ha_mcp_dev-8.3.0.dev2447}/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.dev2444 → ha_mcp_dev-8.3.0.dev2447}/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