ha-mcp-dev 7.10.0.dev775__tar.gz → 7.10.0.dev777__tar.gz

{ha_mcp_dev-7.10.0.dev775/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.10.0.dev777}/PKG-INFO

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

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

@@ -30,6 +30,15 @@ from .rest_client import (
 
 logger = logging.getLogger(__name__)
 
+# Matches the Supervisor's own Core-connection receive limit
+# (MAX_MESSAGE_SIZE_FROM_CORE in home-assistant/supervisor, see supervisor
+# issue #4392). On the add-on path frames above that limit die at the
+# Supervisor proxy anyway, so a larger client-side cap adds nothing there.
+# Registry list responses scale with entity count and arrive as ONE frame
+# (the HA WebSocket API has no pagination); a ~6.4k-entity instance
+# overflowed the previous 20MB cap (#1721).
+MAX_WS_MESSAGE_BYTES = 64 * 1024 * 1024
+
 
 class WebSocketConnectionState:
     """Encapsulates mutable state used by the WebSocket client."""
@@ -109,20 +118,43 @@ class WebSocketConnectionState:
         """Retrieve and remove an authentication message if present."""
         return self._auth_messages.pop(message_type, None)
 
-    def reset_connection(self) -> None:
-        """Reset connection-specific state while preserving handlers."""
+    def reset_connection(self, close_reason: str | None = None) -> None:
+        """Reset connection-specific state while preserving handlers.
+
+        Args:
+            close_reason: Human-readable description of why the connection
+                went away (e.g. a close code/reason pair), included in the
+                error surfaced to any request still awaiting a response.
+        """
         self.connected = False
         self.authenticated = False
         self._message_id = 0
 
+        # ``future.cancel()`` makes awaiters see ``asyncio.CancelledError``,
+        # a BaseException that skips every ``except Exception`` handler in
+        # the tool layer and reaches the MCP SDK, which treats it as a
+        # client-initiated cancellation, suppresses the response entirely,
+        # and leaves the MCP client hanging until its own timeout (#1721).
+        # ``set_exception`` with a normal exception propagates through
+        # ``except Exception`` as expected instead.
+        message = (
+            "WebSocket connection to Home Assistant closed while waiting for a response"
+        )
+        if close_reason:
+            message = f"{message} ({close_reason})"
+
         for future in self._pending_requests.values():
             if not future.done():
-                future.cancel()
+                # A fresh instance per future: sharing one exception object
+                # across multiple ``set_exception`` calls means the second
+                # raise attaches a traceback to an exception already
+                # associated with another future's stack.
+                future.set_exception(HomeAssistantConnectionError(message))
         self._pending_requests.clear()
 
         for future in self._event_responses.values():
             if not future.done():
-                future.cancel()
+                future.set_exception(HomeAssistantConnectionError(message))
         self._event_responses.clear()
 
         # Drop any subscription queues — readers wake on the close signal
@@ -144,9 +176,9 @@ class WebSocketConnectionState:
         """Mark the socket as authenticated and ready for commands."""
         self.authenticated = True
 
-    def mark_disconnected(self) -> None:
+    def mark_disconnected(self, close_reason: str | None = None) -> None:
         """Reset connection state when the socket is closed."""
-        self.reset_connection()
+        self.reset_connection(close_reason)
 
     @property
     def is_ready(self) -> bool:
@@ -293,9 +325,7 @@ class HomeAssistantWebSocketClient:
                 ping_timeout=10,
                 additional_headers={"Authorization": f"Bearer {self.token}"},
                 ssl=ssl_ctx,
-                # Increase max message size to 20MB for large responses
-                # (e.g., HACS repository list can be 2MB+)
-                max_size=20 * 1024 * 1024,
+                max_size=MAX_WS_MESSAGE_BYTES,
             )
             self._state.mark_connected()
 
@@ -390,6 +420,11 @@ class HomeAssistantWebSocketClient:
         """Background task to handle incoming WebSocket messages."""
         if not self.websocket:
             raise Exception("WebSocket not connected")
+        # None means a clean exit (the async-for loop simply ended); the
+        # except blocks below fill this in so pending futures — and the
+        # log — carry *why* the connection went away instead of a bare
+        # "WebSocket connection closed" that gave no lead on #1721.
+        close_reason: str | None = None
         try:
             async for message in self.websocket:
                 try:
@@ -400,12 +435,30 @@ class HomeAssistantWebSocketClient:
                     logger.error(f"Invalid JSON received: {e}")
                 except Exception as e:
                     logger.error(f"Error processing message: {e}")
-        except websockets.exceptions.ConnectionClosed:
-            logger.info("WebSocket connection closed")
+        except websockets.exceptions.ConnectionClosed as e:
+            # Prefer the frame we received (the peer closed on us); fall
+            # back to the frame we sent (we failed the connection
+            # ourselves, e.g. an over-max_size frame produces a sent
+            # Close(1009, ...) with no frame received at all).
+            close = e.rcvd if e.rcvd is not None else e.sent
+            if close is not None:
+                verb = "received" if e.rcvd is not None else "sent"
+                close_reason = f"{verb} close code {close.code}"
+                if close.reason:
+                    close_reason = f"{close_reason} ({close.reason})"
+            else:
+                close_reason = "connection dropped without a close frame"
+
+            log_message = f"WebSocket connection closed ({close_reason})"
+            if close is None or close.code not in (1000, 1001):
+                logger.warning(log_message)
+            else:
+                logger.info(log_message)
         except Exception as e:
+            close_reason = str(e)
             logger.error(f"WebSocket message handler error: {e}")
         finally:
-            self._state.mark_disconnected()
+            self._state.mark_disconnected(close_reason)
 
     async def _process_message(self, data: dict[str, Any]) -> None:
         """Process incoming WebSocket message."""
@@ -649,9 +702,15 @@ class HomeAssistantWebSocketClient:
             result_response = await asyncio.wait_for(
                 result_future, timeout=wait_timeout
             )
-        except TimeoutError:
+        except BaseException:
             self.cancel_pending_response(message_id)
             self.cancel_event_response(message_id)
+            # A connection drop fails BOTH futures via reset_connection;
+            # only result_future gets awaited on this path, so retrieve
+            # event_future's exception too or asyncio logs an ERROR-level
+            # "Future exception was never retrieved" when it is GC'd.
+            if event_future.done() and not event_future.cancelled():
+                event_future.exception()
             raise
 
         if not result_response.get("success"):

{ha_mcp_dev-7.10.0.dev775 → ha_mcp_dev-7.10.0.dev777}/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.dev775 → ha_mcp_dev-7.10.0.dev777}/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.dev775 → ha_mcp_dev-7.10.0.dev777}/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