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

{ha_mcp_dev-7.10.0.dev776/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.dev776
+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.dev776 → 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.dev776"
+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.dev776 → 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.dev776 → 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.dev776 → 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

ha_mcp_dev-7.10.0.dev777/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/blueprint-guide.md

@@ -0,0 +1,271 @@
+# Blueprints
+
+A **blueprint is a reusable, parameterized automation/script/template** — a skeleton whose device- and entity-specific parts are replaced by user-provided **inputs**. Author a blueprint only when a pattern will be instantiated more than once or shared/distributed. A one-off automation should stay a plain automation; don't blueprint what you'll use once.
+
+## Table of Contents
+1. [When to Author a Blueprint](#when-to-author-a-blueprint)
+2. [Blueprint Metadata](#blueprint-metadata)
+3. [Inputs and Selectors](#inputs-and-selectors)
+4. [`target` Selector vs `entity` Selector](#target-selector-vs-entity-selector)
+5. [Defaults](#defaults)
+6. [Input Sections](#input-sections)
+7. [Referencing Inputs (`!input`) and Templating](#referencing-inputs-input-and-templating)
+8. [Versioning and Updates](#versioning-and-updates)
+9. [Annotated Example](#annotated-example)
+10. [Common Pitfalls](#common-pitfalls)
+
+---
+
+## When to Author a Blueprint
+
+| Signal | Blueprint? |
+|--------|-----------|
+| Same logic wanted for several sensors/rooms/devices | Yes — parameterize the varying parts as inputs |
+| Sharing/distributing to other users | Yes — a blueprint imports cleanly via `source_url` |
+| A single automation for one specific set of entities | No — write a normal automation |
+| Logic differs meaningfully per instance | No — a blueprint that needs many conditional inputs is usually two blueprints |
+
+Blueprints exist for three domains, set by the `domain:` key: `automation`, `script`, and `template`. The input/selector rules below apply to all three; the surrounding body (`triggers`/`actions` vs `sequence` vs `sensor`/`binary_sensor`) is whatever that domain normally uses.
+
+## Blueprint Metadata
+
+Every blueprint opens with a `blueprint:` mapping:
+
+```yaml
+blueprint:
+  name: Motion-Activated Light          # required; short and descriptive
+  description: Turn a light on when motion is detected, off after a delay.
+  domain: automation                    # required: automation | script | template
+  author: Your Name                     # optional
+  source_url: https://github.com/you/ha-blueprints/blob/main/motion_light.yaml
+  homeassistant:
+    min_version: "2024.10.0"           # optional; gate version-specific features (see note below)
+  input:
+    # ... see below
+```
+
+- **`source_url`** — the canonical URL of the blueprint file. Always set it. It enables **"Re-import blueprint"** (in-place updates when you publish a fix), provides attribution, and is what the *Import Blueprint* dialog stores. A blueprint without `source_url` can't be updated from source and is awkward to share.
+- **`min_version`** — set it when the blueprint uses a feature added in a specific release (e.g. input sections need `2024.6.0`; the in-item `action:` key replacing `service:` needs `2024.8.0`; the plural `triggers:`/`conditions:`/`actions:` keys and the in-item `trigger:` key replacing `platform:` need `2024.10.0`). HA refuses to import the blueprint on older versions instead of failing mysteriously at runtime.
+- **`domain`** must match the body: an `automation` blueprint has `triggers:`/`actions:`, a `script` blueprint has a `sequence:`, a `template` blueprint defines template entities.
+
+## Inputs and Selectors
+
+Every entity, device, area, number, or option a user should customize is an **input** with a **selector**. The selector determines the UI control and, critically, *validates and constrains* what the user can pick.
+
+**Prefer a typed selector over free text.** A `text` selector for an entity forces users to type `light.living_room` correctly by hand — a typo passes validation and fails silently at runtime. An `entity` selector gives a filtered picker that can only yield valid, existing entities.
+
+Common selectors:
+
+| Selector | Yields | Use for |
+|----------|--------|---------|
+| `entity` | entity_id(s) | Picking specific entities; filter with `domain`, `device_class`, `integration` |
+| `target` | a target dict (entities/devices/areas/floors/labels) | Anything you pass straight to a service call's `target:` |
+| `device` | device_id(s) | Device triggers, or device-level actions (rare — prefer entities) |
+| `area` / `floor` / `label` | area/floor/label id(s) | Scoping actions to a whole area/floor/label |
+| `number` | number | Timeouts, brightness, thresholds; set `min`/`max`/`step`/`mode`/`unit_of_measurement` |
+| `boolean` | true/false | On/off toggles |
+| `select` | a chosen option | A fixed list of choices (`options:`) |
+| `time` / `duration` | time / duration | Schedules and delays |
+| `action` | a sequence of actions | Letting the user inject their own actions (e.g. "what to do when triggered") |
+| `text` | free string | Genuinely free text only (messages, names) — never entity IDs |
+| `object` | arbitrary YAML | Advanced structured input; last resort |
+
+Constrain entity/device selectors so users can only pick valid targets:
+
+```yaml
+motion_sensor:
+  name: Motion sensor
+  selector:
+    entity:
+      domain: binary_sensor
+      device_class: motion      # only motion binary_sensors are offered
+```
+
+Add `multiple: true` to accept a list. Filter by `integration:` when the blueprint is integration-specific.
+
+## `target` Selector vs `entity` Selector
+
+The issue this guide most often resolves. Both point at "what to control," but they produce different shapes:
+
+- **`entity` selector → `entity_id`(s).** Use it when you need the id itself — for a `state` trigger's `entity_id`, a `states(...)` lookup in a template, or an action that specifically wants an entity.
+- **`target` selector → a target dict** (`{entity_id, device_id, area_id, floor_id, label_id}`). Use it when the value flows straight into a service call's `target:`. It lets the user target entities, whole devices, or entire areas/floors/labels — more flexible for "act on these lights," where the user might prefer to say "all lights in the living room area."
+
+```yaml
+# target selector — pass directly to target:
+target_light:
+  selector:
+    target:
+      entity:
+        domain: light
+# ...
+actions:
+  - action: light.turn_on
+    target: !input target_light        # accepts entity/device/area
+
+# entity selector — you need the id for a trigger / template
+motion_sensor:
+  selector:
+    entity:
+      domain: binary_sensor
+# ...
+triggers:
+  - trigger: state
+    entity_id: !input motion_sensor    # needs a concrete entity_id
+```
+
+Rule of thumb: **controlling things → `target`; observing/templating a specific entity → `entity`.**
+
+## Defaults
+
+Provide `default:` for tuning inputs so the blueprint works out of the box:
+
+```yaml
+no_motion_wait:
+  name: Wait time
+  default: 120                          # sensible default → user can skip it
+  selector:
+    number: { min: 0, max: 3600, unit_of_measurement: seconds, mode: slider }
+```
+
+**Don't** default entity/device/target selectors — there's no universally-correct entity, so the user must choose. An input with no `default:` is required; an input with a `default:` is optional. Use this deliberately: required for the entities the blueprint acts on, optional (defaulted) for behavior tuning.
+
+## Input Sections
+
+Blueprints with many inputs become a wall of fields. Group them with sections (HA `2024.6.0`+). A section is an input entry that itself contains an `input:` map:
+
+```yaml
+input:
+  devices:
+    name: Devices
+    icon: mdi:motion-sensor
+    input:                              # nested inputs belong to this section
+      motion_sensor: { name: Motion sensor, selector: { entity: { domain: binary_sensor, device_class: motion } } }
+      target_light:  { name: Light(s),      selector: { target: { entity: { domain: light } } } }
+  settings:
+    name: Settings
+    icon: mdi:cog
+    collapsed: true                     # collapsed by default — advanced knobs out of the way
+    input:
+      no_motion_wait: { name: Wait time, default: 120, selector: { number: { min: 0, max: 3600 } } }
+```
+
+`!input` still references inputs by their own key (`!input motion_sensor`), regardless of which section they live in — section names are for display only.
+
+## Referencing Inputs (`!input`) and Templating
+
+Inside the blueprint body, reference an input with the `!input` YAML tag: `entity_id: !input motion_sensor`.
+
+**The #1 blueprint bug:** `!input` is a YAML tag, **not** a template value — you cannot write `{{ !input x }}` or drop `!input` inside a Jinja expression. To use an input in a template, first expose it as a **variable**, then reference the variable:
+
+```yaml
+variables:
+  brightness_pct: !input brightness     # bind input → variable at script level
+# ...
+actions:
+  - action: light.turn_on
+    target: !input target_light
+    data:
+      brightness_pct: "{{ brightness_pct }}"   # use the variable, never !input
+```
+
+For **templated triggers**, bind inputs through `trigger_variables:` (a separate top-level key evaluated before triggers fire). It supports **limited templates only** — no `states()`/`state_attr()` — and exists mainly to pass a blueprint `!input` into trigger options (see `automation-patterns.md#trigger-types`). Don't put state-based templates there.
+
+`enabled:` on an individual trigger/condition/action also accepts a blueprint `!input` (evaluated once at load) — handy for optional behavior toggled by a `boolean` input (see `automation-patterns.md#enabled-on-individual-triggers-conditions-and-actions`).
+
+## Versioning and Updates
+
+Users import a blueprint once, then create automations from it. When you publish changes:
+
+- **Renaming or removing an input key breaks every existing instance** — their stored `!input` references no longer resolve. Treat input keys as a public API.
+- **Add** new inputs rather than changing old ones, and give every new input a `default:` so existing automations keep working after a re-import without the user touching them.
+- Bump `min_version` if a change relies on a newer HA feature.
+- Keep `source_url` stable — it's the update anchor. Users re-import from the same URL to pick up fixes.
+
+## Annotated Example
+
+A complete motion-light automation blueprint demonstrating every practice above:
+
+```yaml
+blueprint:
+  name: Motion-Activated Light
+  description: Turn a light (or area) on when motion is detected, off after a delay.
+  domain: automation
+  author: Your Name
+  source_url: https://github.com/you/ha-blueprints/blob/main/motion_light.yaml
+  homeassistant:
+    min_version: "2024.10.0"                # modern triggers/actions syntax (input sections alone need only 2024.6.0)
+  input:
+    devices:
+      name: Devices
+      icon: mdi:motion-sensor
+      input:
+        motion_sensor:
+          name: Motion sensor
+          selector:
+            entity:
+              domain: binary_sensor
+              device_class: motion          # constrained picker — no free text
+        target_light:
+          name: Light(s) to control
+          selector:
+            target:                          # target → user may pick lights OR an area
+              entity:
+                domain: light
+    settings:
+      name: Settings
+      icon: mdi:cog
+      collapsed: true
+      input:
+        no_motion_wait:
+          name: Wait time
+          description: Seconds to keep the light on after the last motion.
+          default: 120                       # sensible default → optional input
+          selector:
+            number: { min: 0, max: 3600, unit_of_measurement: seconds, mode: slider }
+        brightness:
+          name: Brightness
+          default: 100
+          selector:
+            number: { min: 1, max: 100, unit_of_measurement: "%" }
+
+# Body — device-specific values come only from !input, never hardcoded:
+mode: restart                                # re-trigger resets the timer
+max_exceeded: silent
+
+variables:
+  brightness_pct: !input brightness          # expose input for use in a template
+
+triggers:
+  - trigger: state
+    entity_id: !input motion_sensor          # entity selector → concrete entity_id
+    to: "on"
+
+actions:
+  - action: light.turn_on
+    target: !input target_light              # target selector → passed straight to target:
+    data:
+      brightness_pct: "{{ brightness_pct }}" # variable, not !input, inside the template
+  - wait_for_trigger:
+      - trigger: state
+        entity_id: !input motion_sensor
+        to: "off"
+  - delay:
+      seconds: !input no_motion_wait
+  - action: light.turn_off
+    target: !input target_light
+```
+
+## Common Pitfalls
+
+| Pitfall | Do instead | Why |
+|---------|-----------|-----|
+| Free-text field for an entity/device | `entity` / `target` / `device` selector | Typed selectors validate the choice; a typo in text fails silently at runtime |
+| Hardcoded `light.living_room` in the body | `!input` with a selector | Hardcoding defeats the entire purpose of a blueprint — it can't be reused |
+| `!input` used directly in a template (`{{ !input x }}`) | Bind to a `variables:` entry, use the variable | `!input` is a YAML tag, not a template value — the template errors or ignores it |
+| State-based template in `trigger_variables:` | Move logic into a template condition/trigger | `trigger_variables` allows limited templates only (no `states()`) |
+| No `source_url` | Set it to the file's canonical URL | Enables in-place re-import/updates and sharing |
+| No `default:` on tuning inputs | Add a sensible `default:` | Makes the input optional and the blueprint usable out of the box |
+| `default:` on the entity the blueprint controls | Leave it required (no default) | There's no universally-correct entity; the user must choose |
+| `entity` selector where you pass to `target:` | Use a `target` selector | `target` lets users pick areas/devices too and drops straight into `target:` |
+| Renaming/removing input keys in an update | Add new inputs (with defaults); keep old keys | Existing automations reference keys by name and break on rename |
+| Missing `min_version` for a used feature | Set `homeassistant.min_version` | HA blocks import on old versions instead of failing at runtime |