ha-mcp-dev 7.10.0.dev776__tar.gz → 7.10.0.dev778__tar.gz

{ha_mcp_dev-7.10.0.dev776/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.10.0.dev778}/PKG-INFO

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

{ha_mcp_dev-7.10.0.dev776 → ha_mcp_dev-7.10.0.dev778}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.10.0.dev776"
+version = "7.10.0.dev778"
 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-7.10.0.dev776 → ha_mcp_dev-7.10.0.dev778}/src/ha_mcp/__main__.py

@@ -34,8 +34,10 @@ from typing import TYPE_CHECKING, Any  # noqa: E402
 
 from fastmcp.exceptions import ToolError  # noqa: E402
 from pydantic import ValidationError as PydanticValidationError  # noqa: E402
-from starlette.requests import Request  # noqa: E402
-from starlette.responses import PlainTextResponse  # noqa: E402
+
+from ha_mcp.browser_landing import (  # noqa: E402
+    register_browser_landing as _register_landing_route,
+)
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -962,21 +964,20 @@ async def _run_http_with_graceful_shutdown(
     )
 
 
-_registered_landing_paths: set[str] = set()
-
-
 def register_browser_landing(
     mcp_instance: "FastMCP | _DeferredMCP",
     path: str,
     *,
     quiet_probe_log: bool = True,
 ) -> None:
-    """Register a GET handler that returns 405 with a helpful message.
+    """Register the friendly browser landing page and tidy the uvicorn access log.
 
-    Browsers and misconfigured clients that send GET instead of POST will see
-    a human-readable explanation instead of a bare "Method Not Allowed" error.
-    The 405 status and Allow header are set explicitly by this handler so
-    automated clients still get the correct HTTP semantics.
+    Delegates the GET landing route to the reusable core in
+    :mod:`ha_mcp.browser_landing` (also used by the in-process ``ha_mcp_tools``
+    server) and, when the route is newly registered, attaches
+    :class:`ProbeAccessLogFilter` to the uvicorn access logger. Browsers and
+    misconfigured clients that send GET instead of POST see a human-readable
+    explanation instead of a bare "Method Not Allowed" error.
 
     Args:
         mcp_instance: The FastMCP server to register the route on.
@@ -986,83 +987,13 @@ def register_browser_landing(
             access log (the handler logs an annotated replacement). Pass False
             for SSE, where a GET answers 200 and a 405 is a genuine fault.
     """
-    if path in _registered_landing_paths:
-        logger.warning(
-            "register_browser_landing: %r already registered, skipping", path
-        )
+    if not _register_landing_route(mcp_instance, path):
+        # Already registered for this path — don't double-attach the log filter.
         return
-    _registered_landing_paths.add(path)
-
-    _landing_message = (
-        "HA-MCP server is up and running!\n"
-        "\n"
-        "To connect, paste the full URL (including the /private_... key) into the\n"
-        "connector or MCP settings of your AI/LLM client. No username or password required.\n"
-        "Setup instructions: https://homeassistant-ai.github.io/ha-mcp/\n"
-        "\n"
-        "--- Seeing this page? Your URL is set up correctly ---\n"
-        "\n"
-        "If this page loads in your browser, the MCP server is reachable and the\n"
-        "URL is correct. If your AI client still cannot connect, the problem is\n"
-        "not on HA-MCP's side. Common causes:\n"
-        "\n"
-        "- Geo / country blocking in your reverse proxy / CDN (Cloudflare, NGINX,\n"
-        "  Traefik, Zoraxy, etc.). Most AI/LLM services connect from US-based\n"
-        "  cloud infrastructure, so if you block US IP addresses (or only allow\n"
-        "  your own country), that is why your client cannot connect. Allow your\n"
-        "  provider's IP ranges (or your client's egress IPs). For example,\n"
-        # Anthropic's documented outbound range; re-verify at
-        # https://platform.claude.com/docs/en/api/ip-addresses if it ever changes.
-        "  Claude.ai connects from Anthropic's network, 160.79.104.0/21.\n"
-        "- WAF, bot-blocking, or rate-limiting rules on the proxy that drop or\n"
-        "  challenge the request.\n"
-        "- The AI client's network can sometimes be spotty -- you may just need\n"
-        "  to try connecting again.\n"
-        "- The AI client itself refusing certain domains or proxy providers on\n"
-        "  its end. This is rare and outside your control; try a different\n"
-        "  hostname or proxy if you suspect it.\n"
-        "\n"
-        "Your proxy's access logs will show the blocked attempt -- look for the\n"
-        "request from your AI provider's IP (e.g. an Anthropic 160.79.x.x address).\n"
-        "\n"
-        "--- Cloudflare Users ---\n"
-        "\n"
-        'If your LLM cannot connect, Cloudflare\'s "Block AI training bots"\n'
-        "setting is the most common cause. To disable it:\n"
-        "\n"
-        "1. Log in to Cloudflare (https://dash.cloudflare.com)\n"
-        "2. In the left sidebar, click Domains, then click Overview\n"
-        "3. Click on the domain you use for connecting to Home Assistant\n"
-        '4. On the right side, find "Control AI Crawlers"\n'
-        '5. Under "Block AI training bots", open the dropdown\n'
-        '6. Select "do not block (allow crawlers)"\n'
-        "\n"
-        "Screenshot of the setting:\n"
-        "https://homeassistant-ai.github.io/ha-mcp/images/cloudflare-ai-crawlers-setting.jpg\n"
-    )
-
-    # Safe because FastMCP registers the MCP route with methods=["POST", "DELETE"]
-    # in stateless mode, so Starlette rejects GET requests before the MCP handler runs.
-    # Custom routes are registered at lowest precedence (after the MCP route).
-    @mcp_instance.custom_route(path, methods=["GET"])
-    async def _browser_landing(_: Request) -> PlainTextResponse:
-        # Any GET here is a non-MCP caller (browser, health check, proxy, or a
-        # connector's SSE-style pre-flight) hitting this POST-only Streamable HTTP
-        # endpoint, which answers 405 by design. Log one annotated line so the 405
-        # reads as expected; ProbeAccessLogFilter drops the raw uvicorn access line
-        # so there's no cryptic duplicate.
-        logger.info("GET %s -> 405 (NORMAL for most non-SSE connections)", path)
-        return PlainTextResponse(
-            _landing_message,
-            status_code=405,
-            # DELETE is included per the MCP Streamable HTTP spec (used for
-            # session termination), even though this deployment uses stateless mode.
-            headers={"Allow": "POST, DELETE"},
-        )
 
     # Tidy uvicorn's access log: always drop browser favicon 404s, and drop the
-    # raw by-design GET/HEAD-405 probe line on the MCP path (the handler above logs
-    # an annotated replacement). The 405 drop is skipped for SSE
+    # raw by-design GET/HEAD-405 probe line on the MCP path (the landing handler
+    # logs an annotated replacement). The 405 drop is skipped for SSE
     # (quiet_probe_log=False), where a GET answers 200 and a 405 is a real fault.
     # Attach to uvicorn.access directly — it has propagate=False, so a root-logger
     # filter would miss it.

ha_mcp_dev-7.10.0.dev778/src/ha_mcp/browser_landing.py

@@ -0,0 +1,138 @@
+"""Friendly browser landing page for the MCP endpoint (issue #777).
+
+A browser (or any GET client) that hits the POST-only Streamable HTTP MCP
+endpoint would otherwise see a bare "Method Not Allowed". This module registers
+a GET handler that answers ``405`` with a human-readable explanation plus the
+correct ``Allow`` header, so automated clients still get the right HTTP
+semantics.
+
+Extracted from :mod:`ha_mcp.__main__` so the in-process server (the
+``ha_mcp_tools`` custom-component worker thread) can register the same landing
+page. Importing ``ha_mcp.__main__`` runs process-global side effects at module
+load (``truststore.inject_into_ssl()``) that must never happen in-process, so
+the reusable core lives here — free of those side effects. ``__main__`` keeps a
+thin wrapper that additionally tidies the uvicorn access log.
+"""
+
+from __future__ import annotations
+
+import logging
+import weakref
+from typing import Any, Protocol
+
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+logger = logging.getLogger(__name__)
+
+
+class CustomRouteServer(Protocol):
+    """Structural type for servers exposing FastMCP's ``custom_route`` decorator.
+
+    Matches the real FastMCP server and ``__main__``'s deferred proxy. Only the
+    ``(path, methods)`` call shape used here is pinned; the decorator's return
+    type is left to the implementation (fastmcp also takes optional ``name`` /
+    ``include_in_schema`` parameters this module never passes).
+    """
+
+    def custom_route(self, path: str, methods: list[str]) -> Any:
+        """Return a decorator that registers a handler for ``methods`` at ``path``."""
+
+
+# The landing body. Plain text so no browser ever interprets it as markup, and
+# so it survives the ha_mcp_tools webhook proxy (which forwards text/plain but
+# coerces text/html to JSON as an XSS guard).
+LANDING_MESSAGE = (
+    "HA-MCP server is up and running!\n"
+    "\n"
+    "To connect, paste the full URL (including the /private_... key) into the\n"
+    "connector or MCP settings of your AI/LLM client. No username or password required.\n"
+    "Setup instructions: https://homeassistant-ai.github.io/ha-mcp/\n"
+    "\n"
+    "--- Seeing this page? Your URL is set up correctly ---\n"
+    "\n"
+    "If this page loads in your browser, the MCP server is reachable and the\n"
+    "URL is correct. If your AI client still cannot connect, the problem is\n"
+    "not on HA-MCP's side. Common causes:\n"
+    "\n"
+    "- Geo / country blocking in your reverse proxy / CDN (Cloudflare, NGINX,\n"
+    "  Traefik, Zoraxy, etc.). Most AI/LLM services connect from US-based\n"
+    "  cloud infrastructure, so if you block US IP addresses (or only allow\n"
+    "  your own country), that is why your client cannot connect. Allow your\n"
+    "  provider's IP ranges (or your client's egress IPs). For example,\n"
+    # Anthropic's documented outbound range; re-verify at
+    # https://platform.claude.com/docs/en/api/ip-addresses if it ever changes.
+    "  Claude.ai connects from Anthropic's network, 160.79.104.0/21.\n"
+    "- WAF, bot-blocking, or rate-limiting rules on the proxy that drop or\n"
+    "  challenge the request.\n"
+    "- The AI client's network can sometimes be spotty -- you may just need\n"
+    "  to try connecting again.\n"
+    "- The AI client itself refusing certain domains or proxy providers on\n"
+    "  its end. This is rare and outside your control; try a different\n"
+    "  hostname or proxy if you suspect it.\n"
+    "\n"
+    "Your proxy's access logs will show the blocked attempt -- look for the\n"
+    "request from your AI provider's IP (e.g. an Anthropic 160.79.x.x address).\n"
+    "\n"
+    "--- Cloudflare Users ---\n"
+    "\n"
+    'If your LLM cannot connect, Cloudflare\'s "Block AI training bots"\n'
+    "setting is the most common cause. To disable it:\n"
+    "\n"
+    "1. Log in to Cloudflare (https://dash.cloudflare.com)\n"
+    "2. In the left sidebar, click Domains, then click Overview\n"
+    "3. Click on the domain you use for connecting to Home Assistant\n"
+    '4. On the right side, find "Control AI Crawlers"\n'
+    '5. Under "Block AI training bots", open the dropdown\n'
+    '6. Select "do not block (allow crawlers)"\n'
+    "\n"
+    "Screenshot of the setting:\n"
+    "https://homeassistant-ai.github.io/ha-mcp/images/cloudflare-ai-crawlers-setting.jpg\n"
+)
+
+# Landing routes already registered, keyed PER MCP INSTANCE (weakly, so a
+# discarded server never leaks). The key must not be the path alone: the
+# in-process server builds a NEW FastMCP on every config-entry reload in the
+# SAME Python process while keeping the same secret path — a process-global
+# path set would skip the re-registration and silently drop the landing page
+# after the first reload. The CLI/add-on never sees this (their process exits).
+_registered_landing_paths: weakref.WeakKeyDictionary[CustomRouteServer, set[str]] = (
+    weakref.WeakKeyDictionary()
+)
+
+
+def register_browser_landing(mcp_instance: CustomRouteServer, path: str) -> bool:
+    """Register a GET handler that returns 405 with the friendly landing message.
+
+    ``mcp_instance`` is a FastMCP-like object exposing ``custom_route`` (the real
+    server or ``__main__``'s deferred proxy). Returns True if the route was newly
+    registered, False if this instance already had one for ``path`` (idempotent
+    per instance + path).
+    """
+    paths = _registered_landing_paths.setdefault(mcp_instance, set())
+    if path in paths:
+        logger.warning(
+            "register_browser_landing: %r already registered, skipping", path
+        )
+        return False
+    paths.add(path)
+
+    # Safe because FastMCP registers the MCP route with methods=["POST", "DELETE"]
+    # in stateless mode, so Starlette rejects GET requests before the MCP handler
+    # runs. Custom routes are registered at lowest precedence (after the MCP route).
+    @mcp_instance.custom_route(path, methods=["GET"])
+    async def _browser_landing(_: Request) -> PlainTextResponse:
+        # Any GET here is a non-MCP caller (browser, health check, proxy, or a
+        # connector's SSE-style pre-flight) hitting this POST-only Streamable HTTP
+        # endpoint, which answers 405 by design. Log one annotated line so the 405
+        # reads as expected.
+        logger.info("GET %s -> 405 (NORMAL for most non-SSE connections)", path)
+        return PlainTextResponse(
+            LANDING_MESSAGE,
+            status_code=405,
+            # DELETE is included per the MCP Streamable HTTP spec (used for
+            # session termination), even though this deployment uses stateless mode.
+            headers={"Allow": "POST, DELETE"},
+        )
+
+    return True

{ha_mcp_dev-7.10.0.dev776 → ha_mcp_dev-7.10.0.dev778}/src/ha_mcp/resources/skills-vendor/README.md

@@ -63,6 +63,7 @@ The `home-assistant-best-practices` skill includes:
 | `references/domain-docs.md` | Integration and domain documentation for service calls, entity attributes |
 | `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 |
 
 ## Contributing
 

{ha_mcp_dev-7.10.0.dev776 → ha_mcp_dev-7.10.0.dev778}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/SKILL.md

@@ -12,6 +12,7 @@ description: >
   - Configuring dashboard cards or selecting helpers
   - Looking up card types or domain docs
   - Writing or reviewing AppDaemon apps
+  - Authoring or editing reusable Blueprints
 
   SYMPTOMS:
   - Agent uses Jinja2 templates where native options exist
@@ -21,8 +22,9 @@ 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
 metadata:
-  version: 12
+  version: 15
 ---
 
 # Home Assistant Best Practices
@@ -39,10 +41,11 @@ If your change affects entity IDs or cross-component references — renaming ent
 
 Steps 1-5 below apply to new config or pattern evaluation.
 
-### 1. Check for native condition/trigger
-Before writing any template, check `references/automation-patterns.md` for native alternatives.
+### 1. Check for a purpose-specific, then generic native, trigger/condition
+Since 2026.7 the default building blocks are purpose-specific triggers/conditions — `<domain>.<name>` keys (motion detected, battery low, door opened) with area/floor/label targets. Check for one that matches the intent first, then a generic native trigger/condition, and only then a template. See `references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267`.
 
 **Common substitutions:**
+- List of individual sensor entities in a trigger → one purpose-specific trigger with an area/floor/label `target:`
 - `{{ states('x') | float > 25 }}` → `numeric_state` condition with `above: 25`
 - `{{ is_state('x', 'on') and is_state('y', 'on') }}` → `condition: and` with state conditions
 - `{{ now().hour >= 9 }}` → `condition: time` with `after: "09:00:00"`
@@ -109,10 +112,16 @@ See `references/device-control.md#zigbee-buttonremote-patterns`.
 | `vacuum.send_command` with vendor room IDs | `vacuum.clean_area` with HA `area_id` (if segments are mapped) | Uses native HA areas, works across integrations — but requires segment-to-area mapping in entity settings first | `references/device-control.md#vacuum-control` |
 | Using `color_temp` (mireds) in light service calls | Use `color_temp_kelvin` | The `color_temp` parameter was removed in 2026.3; only Kelvin is supported | `references/device-control.md#lights` |
 | Person/Device Tracker `entered_home`/`left_home` device triggers or `is_home`/`is_not_home` conditions | `state` trigger `to: home` / `to: not_home`, or `state` condition | These were removed in 2026.5 — state triggers and conditions are the correct replacements | `references/automation-patterns.md#presence-and-person-triggers-and-conditions-removed-in-20265` |
+| Entity list in a trigger where an area/floor/label target fits | Purpose-specific trigger with `target: {area_id: ...}` | Automation follows area membership as devices change — no stale entity lists | `references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267` |
+| 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` | Old keys no longer load; old behavior values raise a repair issue and face removal | `references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267` |
 | Registering callbacks or calling `self.turn_on()`/`self.get_state()` in `__init__()` | Register everything in `initialize()` | Plugin connection not established during `__init__` — calls fail silently | `references/appdaemon.md#app-structure-and-lifecycle` |
 | Calling `run_in` on repeated triggers without cancelling the previous handle | `cancel_timer(self._off_handle)` before each new `run_in` | Every trigger stacks an independent timer — devices toggle unpredictably | `references/appdaemon.md#scheduling-and-timers` |
 | Storing persistent state in instance variables | Use HA `input_number`, `input_boolean`, or `input_text` helpers | Instance variables reset on app reload or daemon restart | `references/appdaemon.md#state-management-and-inter-app-communication` |
 | Hardcoding entity IDs inside the class body | Pass entity IDs via `self.args` in `apps.yaml` | Hardcoded IDs prevent reuse and require code edits per installation | `references/appdaemon.md#appsyaml-configuration` |
+| Hardcoding entity IDs in a Blueprint body | Expose them as `!input` with a selector | Hardcoding defeats a blueprint's purpose — it can't be reused | `references/blueprint-guide.md#inputs-and-selectors` |
+| 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` |
 
 ---
 
@@ -123,7 +132,7 @@ Read these when you need detailed information:
 | File | When to read | Key sections |
 |------|--------------|--------------|
 | `references/safe-refactoring.md` | Renaming entities, replacing helpers, restructuring automations, or any modification to existing config | `#universal-workflow`, `#entity-renames`, `#helper-replacements`, `#trigger-restructuring`, `#config-entry-data--blind-spots-for-entity-registry-renames`, `#storage-mode-dashboards-storagelovelace` |
-| `references/automation-patterns.md` | Writing triggers, conditions, waits, variables, or choosing automation modes; capturing action responses; documenting/annotating steps; disabling automations | `#native-conditions`, `#trigger-types`, `#wait-actions`, `#automation-modes`, `#continue-on-error`, `#stopping-a-sequence`, `#variables`, `#capturing-action-responses`, `#repeat-actions`, `#ifthen-vs-choose`, `#parallel-actions`, `#trigger-ids`, `#documenting-automations--scripts`, `#disabling-automations` |
+| `references/automation-patterns.md` | Writing triggers, conditions, waits, variables, or choosing automation modes; capturing action responses; documenting/annotating steps; disabling automations | `#purpose-specific-triggers--conditions-default-since-20267`, `#native-conditions`, `#trigger-types`, `#wait-actions`, `#automation-modes`, `#continue-on-error`, `#stopping-a-sequence`, `#variables`, `#capturing-action-responses`, `#repeat-actions`, `#ifthen-vs-choose`, `#parallel-actions`, `#trigger-ids`, `#documenting-automations--scripts`, `#disabling-automations` |
 | `references/helper-selection.md` | Deciding whether to use a built-in helper vs template sensor | `#how-helpers-are-created`, `#menu-based-helpers`, `#numeric-aggregation`, `#rate-and-change`, `#time-based-tracking`, `#counting-and-timing`, `#scheduling`, `#entity-grouping`, `#probabilistic-inference`, `#data-smoothing`, `#random-values`, `#climate-control`, `#domain-conversion`, `#template-helpers`, `#decision-matrix` |
 | `references/template-guidelines.md` | Confirming templates ARE appropriate for a use case | `#when-templates-are-appropriate`, `#when-to-avoid-templates`, `#template-sensor-best-practices`, `#common-patterns`, `#error-handling` |
 | `references/yaml-only-integrations.md` | Creating or editing YAML-only integrations that have no config flow (e.g. `command_line`, platform-based `mqtt`, `rest`) | `#yaml-only-integration-types`, `#post-edit-actions` |
@@ -131,6 +140,7 @@ Read these when you need detailed information:
 | `references/scenes.md` | Authoring or activating scenes; snapshot/restore patterns; snapshot-vs-script distinction | `#scene-config-shape`, `#activating-a-scene`, `#snapshot--restore-scenecreate`, `#apply-states-without-storing-sceneapply` |
 | `references/dashboard-guide.md` | Designing or modifying Lovelace dashboards — layout, view types, strategies, sections, cards, badges, CSS styling, HACS | `#dashboard-structure`, `#view-types`, `#dashboard-strategies`, `#built-in-cards`, `#features`, `#badges`, `#custom-cards`, `#css-styling`, `#common-pitfalls` |
 | `references/dashboard-cards.md` | Looking up available card types or fetching card-specific documentation | — |
-| `references/domain-docs.md` | Looking up integration or domain documentation for service calls, entity attributes, or configuration | — |
+| `references/domain-docs.md` | Looking up integration/domain documentation, or the dedicated doc page for a specific trigger, condition, or action | `#fetching-trigger-condition-and-action-docs` |
 | `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` |

{ha_mcp_dev-7.10.0.dev776 → ha_mcp_dev-7.10.0.dev778}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/automation-patterns.md

@@ -229,15 +229,58 @@ id: motion_on        # a single id, or a list (OR semantics):
 
 ## Trigger Types
 
-### Purpose-Specific Triggers (2026.2+)
+### Purpose-Specific Triggers & Conditions (default since 2026.7)
 
-The HA visual automation editor offers **purpose-specific triggers and conditions** organized by real-world concepts (door opened, motion detected, temperature threshold, battery low, etc.) rather than by technical entity domain. These work across entity types — e.g., "when a door opens" fires whether the door is a contact sensor or a motorized cover.
+HA organizes triggers and conditions by real-world intent (motion detected, door opened, battery low, temperature crossed threshold) rather than by technical entity domain. Introduced in 2026.2 and expanded each release, this family **left Labs and became the default automation-building experience in 2026.7**. It is not UI-only sugar: these are first-class config — `trigger: <domain>.<name>` / `condition: <domain>.<name>` with `target:` and `options:` blocks — and round-trip through the config API like any other automation config. (The step-level `note:` field is separate additive syntax — see [Documenting Automations & Scripts](#documenting-automations--scripts).)
 
-**Key points:**
-- **Most** are a UI-editor convenience — under the hood they generate standard `state`, `numeric_state`, etc., so the YAML output uses the same triggers documented below
-- **Exceptions (2026.6, Labs):** the native zone trigger/condition family serializes as new YAML (see [Native Zone Triggers & Conditions](#native-zone-triggers--conditions-20266-labs)), and the step-level `note:` field is new additive syntax (see [Documenting Automations & Scripts](#documenting-automations--scripts)).
-- Available concepts: door/window/gate open/close, motion/occupancy detection, temperature/humidity/illuminance thresholds, power consumption, battery status, air quality, climate, and more
-- When creating automations via the API, use the standard YAML trigger types below (plus the zone family above where you want the native any-zone primitives)
+```yaml
+triggers:
+  - trigger: motion.detected
+    target:
+      area_id: living_room        # entity_id / device_id / area_id / floor_id / label_id
+    options:
+      behavior: each              # multi-target semantics: each (default) / first / all
+      for: "00:00:30"             # optional dwell time
+conditions:
+  - condition: battery.is_low
+    target:
+      label_id: critical_devices
+    options:
+      behavior: any               # conditions combine with any (default) / all
+```
+
+**Prefer these over the generic triggers below when one matches the intent:**
+
+- **Targets, not entity lists.** Target an area/floor/label ("motion in the living room") and the automation follows area membership as sensors are added, swapped, or removed — no entity list to maintain. This also replaces most remaining legitimate uses of device triggers.
+- **No `unavailable`/`unknown` traps.** Each block handles unavailable states and event-entity re-fire quirks internally.
+- **Cross-entity-type.** "Door opened" fires whether the door is a contact sensor or a motorized cover.
+- **Integration-extensible.** Integrations register their own (e.g. `zwave_js.*`), so the catalog grows over time.
+
+**Multi-target `behavior` enums differ between triggers and conditions:**
+
+- Triggers: `each` (default) / `first` / `all`. The pre-2026.7 values `any` and `last` were renamed to `each` and `all` — they still work but raise a repair issue and face removal. Never emit them (some official doc pages still show the old values mid-migration).
+- Conditions: `any` (default) / `all` — unchanged.
+
+**Keys renamed in 2026.7 (trigger keys unless marked *(condition)*) — old keys no longer work:**
+
+| Old | New |
+|-----|-----|
+| `battery.low` | `battery.became_low` |
+| `battery.not_low` | `battery.no_longer_low` |
+| `lawn_mower.docked` | `lawn_mower.returned_to_dock` |
+| `schedule.turned_on` | `schedule.block_started` |
+| `schedule.turned_off` | `schedule.block_ended` |
+| `timer.time_remaining` | `timer.remaining_time_reached` |
+| `update.update_became_available` | `update.became_available` |
+| `vacuum.docked` | `vacuum.returned_to_dock` |
+| `climate.target_temperature` (condition) | `climate.is_target_temperature` |
+| `climate.target_humidity` (condition) | `climate.is_target_humidity` |
+
+**Discovering what exists:** every purpose-specific trigger and condition (and every service action) has a dedicated documentation page covering its config shape, options, and examples — fetch it on demand instead of guessing keys; see `domain-docs.md#fetching-trigger-condition-and-action-docs`. The trees span 50+ domains (~190 trigger and ~145 condition pages, generic types included): battery, motion, occupancy, door/window/gate/garage_door, climate, media_player, sun, timer, schedule, vacuum, lawn_mower, zone, and more. 2026.7 added the sun family (`sun.dawn`, `sun.dusk`, `sun.solar_noon`, `sun.solar_midnight`, elevation triggers).
+
+Since 2026.7, `options.for` durations on **conditions** are primed from recorded history, so a freshly created or reloaded condition does not restart its duration clock from zero. Trigger `for:` clocks still reset as described in [`for:` duration resets](#for-duration-resets-on-restart-and-on-unavailable).
+
+The generic triggers below remain fully supported and are the right choice when no purpose-specific block matches the intent (attribute changes, template-derived conditions, webhooks, MQTT, etc.). As with everything in this file, create and update automations through the config API — the YAML shows the config shape, not a file to hand-edit.
 
 ### State Trigger
 
@@ -342,6 +385,10 @@ only the real start/stop events move it.
 When several entities' `last_changed` all jumped to the same time — one that isn't sunrise/sunset —
 that was a restart re-stamp, not a real state change.
 
+> 2026.7+ primes `options.for` duration tracking for purpose-specific **conditions** from recorded
+> history, so those don't restart from zero on creation/reload. The resets described here still
+> apply to trigger `for:` clauses and to `last_changed`-based template math.
+
 ### Time Trigger
 
 Fires at specific times.
@@ -461,9 +508,9 @@ triggers:
 
 To *check* zone membership in a condition rather than trigger on the transition, see [Zone Condition](#zone-condition).
 
-### Native Zone Triggers & Conditions (2026.6, Labs)
+### Native Zone Triggers & Conditions (2026.6+)
 
-2026.6 adds native, **any-zone** zone primitives (not just home). They are **Labs-gated** in the editor (Settings → System → Labs) but use the standard core config schema, so they round-trip through the config API regardless of the Labs toggle. Unlike most purpose-specific triggers, these serialize as a *new* `<domain>.<subtype>` YAML shape with `options:` and `target:` blocks:
+2026.6 added native, **any-zone** zone primitives (not just home); with the rest of the purpose-specific family they became default (non-Labs) in 2026.7. They serialize as the standard `<domain>.<name>` shape with `options:` and `target:` blocks:
 
 - **Triggers:** `zone.entered`, `zone.left`, `zone.occupancy_detected`, `zone.occupancy_cleared`
 - **Conditions:** `zone.in_zone`, `zone.not_in_zone`, `zone.occupancy_is_detected`, `zone.occupancy_is_not_detected`
@@ -480,7 +527,7 @@ triggers:
       # for: "00:05:00"           # optional dwell time
 ```
 
-Triggers take `behavior: each` (default), `all`, or `first`; the matching **conditions** use a *different* enum — `behavior: any` (default) or `all`. These are Labs keys and may change before they stabilize, so verify against the current schema. The classic flat [Zone Trigger](#zone-trigger) / [Zone Condition](#zone-condition) and plain `state` triggers remain the stable, non-Labs fallback.
+Triggers take `behavior: each` (default), `all`, or `first`; the matching **conditions** use a *different* enum — `behavior: any` (default) or `all` (see [Purpose-Specific Triggers & Conditions](#purpose-specific-triggers--conditions-default-since-20267)). The classic flat [Zone Trigger](#zone-trigger) / [Zone Condition](#zone-condition) and plain `state` triggers remain supported.
 
 > The `entered_home`/`left_home`/`is_home`/`is_not_home` device automations were removed in **2026.5** (see [below](#presence-and-person-triggers-and-conditions-removed-in-20265)) — 2026.6 only *adds* these any-zone primitives as the native successor.
 
@@ -612,40 +659,44 @@ entity_id: person.john
 state: "home"
 ```
 
-For non-home zone presence, see `#zone-condition`.
+2026.7 presence semantics to keep in mind:
+
+- A person located by a home presence scanner (router/Bluetooth) may report **no latitude/longitude** — don't read coordinates to infer home presence; use the state or the `in_zones` attribute.
+- Person and device_tracker entities expose `in_zones` (all zones containing them, smallest first). Zone entity states (person counts) are derived from it, so a person counts in **every** overlapping zone they're inside, not just one.
+- A position-aware device_tracker's state is the **smallest** containing zone (previously: the zone whose center is closest).
+
+For non-home zone presence, prefer the native zone family (see [Native Zone Triggers & Conditions](#native-zone-triggers--conditions-20266)) or `#zone-condition`.
 
 ### Timer Entity Triggers (2026.5+)
 
-Timer entities now expose lifecycle events as purpose-specific triggers in the UI editor. In YAML, use the `event` trigger with the corresponding `timer.*` event type.
+Timer lifecycle events are purpose-specific triggers: `timer.started`, `timer.finished`, `timer.paused`, `timer.restarted`, `timer.cancelled`, plus `timer.remaining_time_reached` (renamed from `timer.time_remaining` in 2026.7), which fires at a set remaining time.
 
 ```yaml
-# Timer finished (also: timer.started, timer.paused, timer.restarted, timer.cancelled)
 triggers:
-  - trigger: event
-    event_type: timer.finished
-    event_data:
+  - trigger: timer.remaining_time_reached
+    target:
       entity_id: timer.cooking
+    options:
+      remaining: "00:05:00"
 ```
 
+The legacy `event`-trigger form (`event_type: timer.finished` with `event_data: {entity_id: ...}`) still works, but the purpose-specific form supports targets and is preferred.
+
 ### Media Player Triggers/Conditions (2026.5+)
 
-Media player entities now have purpose-specific triggers and conditions in the UI editor covering play/pause state, mute status, and volume level. In YAML these map to standard state and numeric_state triggers.
+Media players have purpose-specific triggers (`media_player.started_playing`, `media_player.paused_playing`, `media_player.stopped_playing`, `media_player.turned_on`, `media_player.turned_off`, `media_player.muted`, `media_player.unmuted`, `media_player.volume_changed`, `media_player.volume_crossed_threshold`) and matching conditions (`media_player.is_playing`, `media_player.is_paused`, `media_player.is_not_playing`, `media_player.is_on`, `media_player.is_off`, `media_player.is_muted`, `media_player.is_unmuted`, `media_player.is_volume`).
 
 ```yaml
-# Play/pause state — to: "playing", "paused", "idle", "off"
-triggers:
-  - trigger: state
-    entity_id: media_player.living_room
-    to: "playing"
-
-# Volume threshold
 triggers:
-  - trigger: numeric_state
-    entity_id: media_player.living_room
-    attribute: volume_level
-    above: 0.7
+  - trigger: media_player.started_playing
+    target:
+      entity_id: media_player.living_room
+    options:
+      for: "00:00:30"   # optional: playback must continue this long
 ```
 
+The generic forms still apply where no purpose-specific block fits (e.g. `state` with `to: "idle"`, or `numeric_state` on `attribute: volume_level`).
+
 ---
 
 ## Wait Actions