Restructure repository: organize blueprints into folders

Each blueprint now has its own folder containing:
- blueprint.yaml: The automation code with a short header
- README.md: Detailed documentation extracted from headers

Updated CLAUDE.md with repository structure guidelines.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -22,4 +22,41 @@ After any change to repository content (blueprints, documentation, or other file
 
 ## Repository Structure
 
+Each blueprint is organized in its own folder:
+
+```text
+Common/
+  Blueprint Name/
+    blueprint.yaml    # The automation blueprint
+    README.md         # Detailed documentation
+Zigbee/
+  Blueprint Name/
+    blueprint.yaml
+    README.md
+```
+
+### Working with Blueprints
+
+**When modifying a blueprint:**
+
+1. Edit `blueprint.yaml` for code changes
+2. Update `README.md` if the change affects features, configuration, or behavior
+3. Keep the blueprint header short (4-5 lines) - detailed docs go in README.md
+
+**When creating a new blueprint:**
+
+1. Create a new folder named after the blueprint (e.g., `Common/My New Blueprint/`)
+2. Add `blueprint.yaml` with a short header referencing README.md
+3. Add `README.md` with full documentation (features, how it works, configuration)
+
+**Blueprint header format:**
+
+```yaml
+# Blueprint Name
+# One-line description of what it does.
+# See README.md for detailed documentation.
+#
+# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
+```
+
 When any blueprint file is moved ask if I need to update the link somewhere else.

Common/Alarm Notification/README.md

@@ -0,0 +1,14 @@
+# Multi-Sensor Alarm & Notification Blueprint
+
+This blueprint monitors multiple binary sensors and triggers push notifications and alarm device control when sensors activate.
+
+## Features
+
+- Per-sensor custom notification messages
+- Debounce timer to prevent false alarms from brief sensor triggers
+- Optional melody and volume selection for alarm devices
+- Automatic alarm turn-off when all sensors clear
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Alarm Notification/blueprint.yaml

@@ -1,18 +1,6 @@
-# =============================================================================
 # Multi-Sensor Alarm & Notification Blueprint
-# =============================================================================
+# Monitors sensors and triggers notifications and alarms when activated.
-# This blueprint monitors multiple binary sensors and triggers:
+# See README.md for detailed documentation.
-# - Push notifications when sensors activate
-# - Alarm device control (with configurable melody and volume)
-#
-# Features:
-# - Per-sensor custom notification messages
-# - Debounce timer to prevent false alarms from brief sensor triggers
-# - Optional melody and volume selection for alarm devices
-# - Automatic alarm turn-off when all sensors clear
-#
-# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Multi-Sensor Alarm & Notification"

Common/Climate Device Controller/README.md

@@ -0,0 +1,66 @@
+# Climate Device Controller Blueprint
+
+This blueprint controls climate devices (heaters, AC, humidifiers, etc.) based on environmental sensors, window/door states, and schedules.
+
+## Supported Device Types
+
+Supports any controllable device type through custom actions:
+
+- Switches (traditional on/off control)
+- Climate entities (HVAC, air conditioners)
+- Smart remotes (IR/RF commands for AC units)
+- Scripts and scenes
+- Any other controllable entity
+
+## Features
+
+- Automatic on/off based on target value (temperature, humidity, etc.)
+- Hysteresis window to prevent rapid on/off cycling
+- Force ON override (manual override to keep device always on)
+- Window/door sensor integration (turns off when open for efficiency)
+- Decay duration (waits before reacting to door/window changes)
+- Emergency threshold (forces device ON below critical value)
+- Schedule support (only runs during scheduled times)
+- Power monitoring (detects device malfunction)
+- House-wide and room-specific window/door sensors
+
+## Control Logic (Priority Order)
+
+1. If Force ON switch is ON → FORCE ON (manual override)
+2. If value is below emergency threshold → FORCE ON (safety override)
+3. If control switch is OFF → FORCE OFF
+4. If environment not sealed OR schedule not active → OFF
+5. If value at or above target → OFF (target reached)
+6. If value below turn-on threshold (target - hysteresis) → ON
+7. Otherwise → maintain current state (in hysteresis zone)
+
+## Hysteresis Example
+
+Prevents rapid cycling:
+
+- Target humidity: 30%, Hysteresis window: 5%
+- Device turns OFF when humidity reaches 30%
+- Device turns ON when humidity drops to 25% (30% - 5%)
+- Between 25-30%: device maintains its current state
+
+## Window/Door Logic
+
+- "House closed" = ALL house windows are closed (for decay duration)
+- "Room closed" = ALL room windows AND doors are closed (for decay duration)
+- Device can run if EITHER house OR room is fully closed
+
+## Power Monitoring
+
+If device is ON but power consumption is below threshold for decay duration, it's flagged as problematic (possible malfunction).
+
+## Requirements
+
+- Device entity to monitor state (switch, climate, etc.)
+- Custom actions for turning device on/off
+- Control switch (master enable/disable)
+- Environment sensor(s) for current value
+- Target value entity (input_number)
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Climate Device Controller/blueprint.yaml

@@ -1,65 +1,8 @@
-# =============================================================================
+# Climate Device Controller Blueprint
-# Climate Device Controller Blueprint for Home Assistant
+# Controls climate devices based on environmental sensors, window/door states,
-# =============================================================================
+# and schedules with hysteresis support. See README.md for detailed documentation.
-# This blueprint controls climate devices (heaters, AC, humidifiers, etc.)
-# based on environmental sensors, window/door states, and schedules.
-#
-# Supports any controllable device type through custom actions:
-#   - Switches (traditional on/off control)
-#   - Climate entities (HVAC, air conditioners)
-#   - Smart remotes (IR/RF commands for AC units)
-#   - Scripts and scenes
-#   - Any other controllable entity
-#
-# Features:
-#   - Automatic on/off based on target value (temperature, humidity, etc.)
-#   - Hysteresis window to prevent rapid on/off cycling
-#   - Force ON override (manual override to keep device always on)
-#   - Window/door sensor integration (turns off when open for efficiency)
-#   - Decay duration (waits before reacting to door/window changes)
-#   - Emergency threshold (forces device ON below critical value)
-#   - Schedule support (only runs during scheduled times)
-#   - Power monitoring (detects device malfunction)
-#   - House-wide and room-specific window/door sensors
-#
-# Control Logic (in priority order):
-#   1. If Force ON switch is ON → FORCE ON (manual override)
-#   2. If value is below emergency threshold → FORCE ON (safety override)
-#   3. If control switch is OFF → FORCE OFF
-#   4. If environment not sealed OR schedule not active → OFF
-#   5. If value at or above target → OFF (target reached)
-#   6. If value below turn-on threshold (target - hysteresis) → ON
-#   7. Otherwise → maintain current state (in hysteresis zone)
-#
-# Hysteresis Example (prevents rapid cycling):
-#   - Target humidity: 30%, Hysteresis window: 5%
-#   - Device turns OFF when humidity reaches 30%
-#   - Device turns ON when humidity drops to 25% (30% - 5%)
-#   - Between 25-30%: device maintains its current state
-#
-# Window/Door Logic:
-#   - "House closed" = ALL house windows are closed (for decay duration)
-#   - "Room closed" = ALL room windows AND doors are closed (for decay duration)
-#   - Device can run if EITHER house OR room is fully closed
-#
-# Power Monitoring:
-#   - If device is ON but power consumption is below threshold for
-#     decay duration, it's flagged as problematic (possible malfunction)
-#
-# Requirements:
-#   - Device entity to monitor state (switch, climate, etc.)
-#   - Custom actions for turning device on/off
-#   - Control switch (master enable/disable)
-#   - Environment sensor(s) for current value
-#   - Target value entity (input_number)
-#
-# Device Control Flexibility:
-#   - Supports any controllable device type via custom actions
-#   - Examples: switches, climate entities, smart remotes, scripts, scenes
-#   - Define your own turn_on and turn_off actions for maximum flexibility
 #
 # Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Climate Device Control"

Common/Day Scene Controller/README.md

@@ -0,0 +1,31 @@
+# Day Scene Controller Blueprint
+
+This blueprint automatically activates scenes based on time-of-day state and a control switch. It bridges the Time of Day State Machine with scene activation.
+
+## How It Works
+
+- Monitors a time-of-day input_select (from Time of Day State Machine)
+- When control switch is ON: activates the scene matching current time slot
+- When control switch is OFF: activates the default scene
+- Optionally applies default scene as transition before switching scenes
+
+## Index Mapping
+
+Scenes are mapped to time-of-day states by index:
+
+| Time State Index | Scene |
+|-----------------|-------|
+| option[0] | scenes[0] |
+| option[1] | scenes[1] |
+| option[2] | scenes[2] |
+| etc. | etc. |
+
+## Example Configuration
+
+- **Time of Day options**: `["Night", "Morning", "Afternoon", "Evening"]`
+- **Scenes**: `[scene.night, scene.morning, scene.afternoon, scene.evening]`
+- When time is "Morning" and control is ON → `scene.morning` activates
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Day Scene Controller/blueprint.yaml

@@ -1,29 +1,6 @@
-# =============================================================================
 # Day Scene Controller Blueprint
-# =============================================================================
+# Automatically activates scenes based on time-of-day state and control switch.
-# This blueprint automatically activates scenes based on time-of-day state
+# See README.md for detailed documentation.
-# and a control switch. It bridges the Time of Day State Machine with scene
-# activation.
-#
-# How It Works:
-# - Monitors a time-of-day input_select (from Time of Day State Machine)
-# - When control switch is ON: activates the scene matching current time slot
-# - When control switch is OFF: activates the default scene
-# - Optionally applies default scene as transition before switching scenes
-#
-# Index Mapping:
-# Scenes are mapped to time-of-day states by index:
-# - Time state option[0] -> scenes[0]
-# - Time state option[1] -> scenes[1]
-# - etc.
-#
-# Example:
-# - Time of Day options: ["Night", "Morning", "Afternoon", "Evening"]
-# - Scenes: [scene.night, scene.morning, scene.afternoon, scene.evening]
-# - When time is "Morning" and control is ON -> scene.morning activates
-#
-# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Day Scene Controller"

Common/Home Presence/README.md

@@ -0,0 +1,30 @@
+# Home Presence Controller Blueprint
+
+This blueprint determines home presence/occupancy based on multiple signals:
+
+- Activity sensors (presence assumed if any sensor changed state recently)
+- Person/presence entities (tracking if someone is home)
+- Wi-Fi connection (devices connected to home network)
+- Bluetooth/BLE devices (device trackers reporting home/away)
+
+The result is stored in an input_boolean helper that other automations can use to determine if someone is likely home.
+
+## Features
+
+- Multiple signal sources for robust presence detection
+- Activity sensors with configurable threshold (door, motion, etc.)
+- Guest mode override for manual presence control
+- Bluetooth device tracker support
+- Debug notifications for troubleshooting
+- Graceful handling of unavailable sensors
+- Automatic evaluation on Home Assistant startup
+
+## Signal Priority
+
+1. Guest mode (forces presence ON when enabled)
+2. Stable signals (person entities, Wi-Fi, Bluetooth)
+3. Activity sensors (temporary presence based on recent state changes)
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Home Presence/blueprint.yaml

@@ -1,31 +1,8 @@
-# =============================================================================
 # Home Presence Controller Blueprint
-# =============================================================================
+# Determines home presence/occupancy based on activity sensors, person entities,
-# This blueprint determines home presence/occupancy based on multiple signals:
+# Wi-Fi connections, and Bluetooth devices. See README.md for detailed documentation.
-# - Activity sensors (presence assumed if any sensor changed state recently)
-# - Person/presence entities (tracking if someone is home)
-# - Wi-Fi connection (devices connected to home network)
-# - Bluetooth/BLE devices (device trackers reporting home/away)
-#
-# The result is stored in an input_boolean helper that other automations
-# can use to determine if someone is likely home.
-#
-# Features:
-#   - Multiple signal sources for robust presence detection
-#   - Activity sensors with configurable threshold (door, motion, etc.)
-#   - Guest mode override for manual presence control
-#   - Bluetooth device tracker support
-#   - Debug notifications for troubleshooting
-#   - Graceful handling of unavailable sensors
-#   - Automatic evaluation on Home Assistant startup
-#
-# Signal Priority:
-#   1. Guest mode (forces presence ON when enabled)
-#   2. Stable signals (person entities, Wi-Fi, Bluetooth)
-#   3. Activity sensors (temporary presence based on recent state changes)
 #
 # Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Home Presence Controller"

Common/Immich Album Watcher/README.md

@@ -0,0 +1,213 @@
+# Immich Album Watcher Blueprint
+
+This blueprint monitors Immich album changes and sends notifications when assets (photos/videos) are added to specified albums. Designed to be used in pair with the `Immich Album Watcher` integration.
+
+## Features
+
+- Filter by hub/instance name (for multi-hub setups)
+- Monitor specific albums by name (whitelist)
+- Filter by asset type (track images only, videos only, or both)
+- Send notifications to multiple targets simultaneously
+- Customizable notification messages with template variables
+- Separate templates for image and video assets
+- Optional: include people detected in photos
+- Optional: include detailed asset list with per-item formatting
+- Support for multiple change types (assets added, removed, changed)
+- Optional: send photos/videos as Telegram media attachments
+- Optional: periodic summary notifications with album list and share URLs
+
+## Event Data from Immich
+
+### Assets Added/Removed/Changed Events
+
+| Field | Description |
+|-------|-------------|
+| `hub_name` | Name of the Immich hub/instance that sent the event |
+| `album_id` | Album ID |
+| `album_name` | Album name |
+| `album_url` | Public URL to view the album (only if album has shared link) |
+| `change_type` | Type of change (assets_added, assets_removed, changed) |
+| `added_count` | Number of assets added |
+| `removed_count` | Number of assets removed |
+| `added_assets` | List of added assets (see Added Assets Fields below) |
+| `removed_assets` | List of removed asset IDs |
+| `people` | List of all people detected in the album |
+
+### Album Renamed Event
+
+| Field | Description |
+|-------|-------------|
+| `hub_name` | Name of the Immich hub/instance that sent the event |
+| `album_id` | Album ID |
+| `old_name` | Previous album name |
+| `new_name` | New album name |
+| `album_url` | Public URL to view the album (only if album has shared link) |
+
+### Album Deleted Event
+
+| Field | Description |
+|-------|-------------|
+| `hub_name` | Name of the Immich hub/instance that sent the event |
+| `album_id` | Album ID |
+| `album_name` | Album name that was deleted |
+
+## Added Assets Fields
+
+Each item in `added_assets` contains:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique asset ID |
+| `type` | Type of asset (IMAGE or VIDEO) |
+| `filename` | Original filename of the asset |
+| `created_at` | Date/time when the asset was originally created |
+| `owner` | Display name of the user who owns the asset |
+| `owner_id` | Unique ID of the user who owns the asset |
+| `description` | Description/caption (user-added in Immich, or EXIF fallback) |
+| `is_favorite` | Whether the asset is marked as favorite (true or false) |
+| `rating` | User rating of the asset (1-5 stars, or null if not rated) |
+| `url` | Public URL to view the asset (only if album has shared link) |
+| `download_url` | Direct download URL for the original file (if shared link exists) |
+| `playback_url` | Video playback URL (for VIDEO assets only, if shared link exists) |
+| `photo_url` | Photo preview URL (for IMAGE assets only, if shared link exists) |
+| `people` | List of people detected in this specific asset |
+
+## Message Template Variables
+
+All message templates support these placeholder variables (use single braces):
+
+| Variable | Description |
+|----------|-------------|
+| `{album_name}` | Name of the album |
+| `{album_url}` | Public URL to view the album (empty if no shared link) |
+| `{added_count}` | Number of assets added |
+| `{removed_count}` | Number of assets removed |
+| `{people}` | Comma-separated list of people detected |
+| `{assets}` | Formatted list of added assets (using asset item template) |
+| `{video_warning}` | Warning about video size limits (Telegram only, empty otherwise) |
+| `{common_date}` | Common date formatted with template if all assets share same date, empty otherwise |
+
+## Asset Item Template Variables
+
+These variables can be used in the image and video asset templates. Also used for Telegram media captions.
+
+| Variable | Description |
+|----------|-------------|
+| `{filename}` | Original filename of the asset |
+| `{description}` | Description/caption (user-added in Immich, or EXIF fallback) |
+| `{type}` | Asset type (IMAGE or VIDEO) |
+| `{created}` | Creation date/time (always shown) |
+| `{created_if_unique}` | Creation date/time formatted with template if dates differ, empty if all same |
+| `{owner}` | Owner display name |
+| `{url}` | Public URL to view the asset (empty if no shared link) |
+| `{download_url}` | Direct download URL for the original file |
+| `{photo_url}` | Photo preview URL (for IMAGE assets only) |
+| `{playback_url}` | Video playback URL (for VIDEO assets only) |
+| `{people}` | People detected in this asset |
+| `{album_name}` | Name of the album |
+| `{is_favorite}` | Favorite indicator (using template) if asset is favorite, empty otherwise |
+| `{rating}` | User rating (1-5) or empty if not rated |
+
+## Telegram Media Attachments
+
+When enabled, photos/videos are sent as media attachments to Telegram using the `immich_album_watcher.send_telegram_notification` service.
+
+### Supported Recipients
+
+1. **Notify Entities**: Select Telegram notify entities. Chat ID is extracted from the friendly name. Format: `"Name (123456789)"`
+2. **Input Text Entities**: Select input_text entities containing chat IDs for groups/channels.
+
+### Requirements
+
+- Immich Album Watcher integration must be configured with Telegram bot token
+- Immich album must have a shared link (to generate public asset URLs)
+
+### Behavior
+
+- First sends a text notification message to each Telegram chat
+- Then sends photos/videos as media groups (albums) as replies to that message
+- Media is downloaded from Immich and uploaded to Telegram (bypasses CORS)
+- Large media lists are automatically split into multiple groups (2-10 items per group)
+
+### Limitations
+
+- Only assets with valid public URLs will be sent
+- Telegram has a 50 MB file size limit for media
+- Optional video warning can be shown when videos are present
+- Media captions use the Image/Video Asset Templates
+
+## Periodic Summary
+
+Sends a summary notification of tracked albums at regular intervals. Album names and share URLs are automatically read from the Album ID Entity's `album_name` and `share_url` attributes (if available).
+
+### Summary Message Template Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{albums}` | Formatted list of albums (using album item template) |
+| `{album_count}` | Number of tracked albums |
+
+### Album Item Template Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{album_name}` | Name of the album |
+| `{album_url}` | Share URL for the album |
+
+### Testing Periodic Summary
+
+To test the periodic summary without waiting for the scheduled time, fire this event from Developer Tools > Events:
+
+- **Event type**: `immich_album_watcher_test_periodic_summary`
+
+To target a specific automation, set its Automation ID in config and include it in the event data:
+
+- **Event data**: `{"automation_id": "your-automation-id"}`
+
+## Scheduled Assets
+
+Sends scheduled notifications with existing assets from tracked albums. Uses the `immich_album_watcher.get_assets` service to fetch assets.
+
+### Album Modes
+
+| Mode | Description |
+|------|-------------|
+| `per_album` | Send separate notifications for each tracked album |
+| `combined` | Fetch assets from all albums into one notification |
+| `random` | Pick one random album each time |
+
+### Asset Filter Options
+
+| Option | Description |
+|--------|-------------|
+| `limit` | Maximum number of assets to fetch (1-100) |
+| `favorite_only` | Only fetch favorite assets |
+| `asset_type` | Filter by type (all, photo, video) |
+| `order_by` | Sort by (random, date, rating, name) |
+| `order` | Sort direction (ascending, descending) |
+| `filter_min_rating` | Minimum rating filter (1-5, 0 = no filter) |
+| `min_date` | Assets created on or after this date (YYYY-MM-DD) |
+| `max_date` | Assets created on or before this date (YYYY-MM-DD) |
+
+### Scheduled Assets Message Template Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{album_name}` | Name of the album |
+| `{album_url}` | Share URL for the album |
+| `{asset_count}` | Number of assets fetched |
+| `{assets}` | Formatted list of assets (using asset item template) |
+
+### Testing Scheduled Assets
+
+To test without waiting for the scheduled time, fire this event:
+
+- **Event type**: `immich_album_watcher_test_scheduled_assets`
+
+To target a specific automation, set its Automation ID in config and include it in the event data:
+
+- **Event data**: `{"automation_id": "your-automation-id"}`
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Immich Album Watcher/blueprint.yaml

@@ -1,175 +1,7 @@
-# =============================================================================
+# Immich Album Watcher Blueprint
-# Immich Album Watcher Blueprint for Home Assistant
+# Monitors Immich album changes and sends notifications when assets are added.
-# =============================================================================
+# Designed to be used with the `Immich Album Watcher` integration.
-# This blueprint monitors Immich album changes and sends notifications when
+# See README.md for detailed documentation.
-# assets (photos/videos) are added to specified albums.
-# Designed to be used in pair with `Immich Album Watcher` integration.
-#
-# Features:
-#   - Filter by hub/instance name (for multi-hub setups)
-#   - Monitor specific albums by name (whitelist)
-#   - Filter by asset type (track images only, videos only, or both)
-#   - Send notifications to multiple targets simultaneously
-#   - Customizable notification messages with template variables
-#   - Separate templates for image and video assets
-#   - Optional: include people detected in photos
-#   - Optional: include detailed asset list with per-item formatting
-#   - Support for multiple change types (assets added, removed, changed)
-#   - Optional: send photos/videos as Telegram media attachments
-#   - Optional: periodic summary notifications with album list and share URLs
-#
-# Event Data from Immich:
-#   Assets Added/Removed/Changed Events:
-#   - `hub_name`:       Name of the Immich hub/instance that sent the event
-#   - `album_id`:       Album ID
-#   - `album_name`:     Album name
-#   - `album_url`:      Public URL to view the album (only if album has shared link)
-#   - `change_type`:    Type of change (assets_added, assets_removed, changed)
-#   - `added_count`:    Number of assets added
-#   - `removed_count`:  Number of assets removed
-#   - `added_assets`:   List of added assets (see Added Assets Fields below)
-#   - `removed_assets`: List of removed asset IDs
-#   - `people`:         List of all people detected in the album
-#
-#   Album Renamed Event:
-#   - `hub_name`:       Name of the Immich hub/instance that sent the event
-#   - `album_id`:       Album ID
-#   - `old_name`:       Previous album name
-#   - `new_name`:       New album name
-#   - `album_url`:      Public URL to view the album (only if album has shared link)
-#
-#   Album Deleted Event:
-#   - `hub_name`:       Name of the Immich hub/instance that sent the event
-#   - `album_id`:       Album ID
-#   - `album_name`:     Album name that was deleted
-#
-# Added Assets Fields (each item in `added_assets`):
-#   - `id`:           Unique asset ID
-#   - `type`:         Type of asset (IMAGE or VIDEO)
-#   - `filename`:     Original filename of the asset
-#   - `created_at`:   Date/time when the asset was originally created
-#   - `owner`:        Display name of the user who owns the asset
-#   - `owner_id`:     Unique ID of the user who owns the asset
-#   - `description`:  Description/caption (user-added in Immich, or EXIF fallback)
-#   - `is_favorite`:  Whether the asset is marked as favorite (true or false)
-#   - `rating`:       User rating of the asset (1-5 stars, or null if not rated)
-#   - `url`:          Public URL to view the asset (only if album has shared link)
-#   - `download_url`: Direct download URL for the original file (if shared link exists)
-#   - `playback_url`: Video playback URL (for VIDEO assets only, if shared link exists)
-#   - `photo_url`:    Photo preview URL (for IMAGE assets only, if shared link exists)
-#   - `people`:       List of people detected in this specific asset
-#
-# Message Template Variables:
-#   All message templates support these placeholder variables (use single braces):
-#   - `{album_name}`     - Name of the album
-#   - `{album_url}`      - Public URL to view the album (empty if no shared link)
-#   - `{added_count}`    - Number of assets added
-#   - `{removed_count}`  - Number of assets removed
-#   - `{people}`         - Comma-separated list of people detected
-#   - `{assets}`         - Formatted list of added assets (using asset item template)
-#   - `{video_warning}`  - Warning about video size limits (Telegram only, empty otherwise)
-#   - `{common_date}`    - Common date formatted with template if all assets share same date, empty otherwise
-#
-# Asset Item Template Variables (for image/video templates):
-#   These variables can be used in the image and video asset templates.
-#   Also used for Telegram media captions.
-#   - `{filename}`          - Original filename of the asset
-#   - `{description}`       - Description/caption (user-added in Immich, or EXIF fallback)
-#   - `{type}`              - Asset type (IMAGE or VIDEO)
-#   - `{created}`           - Creation date/time (always shown)
-#   - `{created_if_unique}` - Creation date/time formatted with template if dates differ, empty if all same
-#   - `{owner}`             - Owner display name
-#   - `{url}`               - Public URL to view the asset (empty if no shared link)
-#   - `{download_url}`      - Direct download URL for the original file
-#   - `{photo_url}`         - Photo preview URL (for IMAGE assets only)
-#   - `{playback_url}`      - Video playback URL (for VIDEO assets only)
-#   - `{people}`            - People detected in this asset
-#   - `{album_name}`        - Name of the album
-#   - `{is_favorite}`       - Favorite indicator (using template) if asset is favorite, empty otherwise
-#   - `{rating}`            - User rating (1-5) or empty if not rated
-#
-# Telegram Media Attachments:
-#   When enabled, photos/videos are sent as media attachments to Telegram
-#   using the immich_album_watcher.send_telegram_notification service.
-#
-#   Supports multiple recipients via two methods:
-#   1. Notify Entities: Select Telegram notify entities. Chat ID is extracted
-#      from the friendly name. Format: "Name (123456789)"
-#   2. Input Text Entities: Select input_text entities containing chat IDs for groups/channels.
-#
-#   Requirements:
-#   - Immich Album Watcher integration must be configured with Telegram bot token
-#   - Immich album must have a shared link (to generate public asset URLs)
-#
-#   Behavior:
-#   - First sends a text notification message to each Telegram chat
-#   - Then sends photos/videos as media groups (albums) as replies to that message
-#   - Media is downloaded from Immich and uploaded to Telegram (bypasses CORS)
-#   - Large media lists are automatically split into multiple groups (2-10 items per group)
-#
-#   Limitations:
-#   - Only assets with valid public URLs will be sent
-#   - Telegram has a 50 MB file size limit for media
-#   - Optional video warning can be shown when videos are present
-#   - Media captions use the Image/Video Asset Templates
-#
-# Periodic Summary:
-#   Sends a summary notification of tracked albums at regular intervals.
-#   Album names and share URLs are automatically read from the Album ID Entity's
-#   `album_name` and `share_url` attributes (if available).
-#
-#   Summary Message Template Variables:
-#   - `{albums}`        - Formatted list of albums (using album item template)
-#   - `{album_count}`   - Number of tracked albums
-#
-#   Album Item Template Variables:
-#   - `{album_name}`    - Name of the album
-#   - `{album_url}`     - Share URL for the album
-#
-#   Testing Periodic Summary:
-#   To test the periodic summary without waiting for the scheduled time,
-#   fire this event from Developer Tools > Events:
-#   Event type: immich_album_watcher_test_periodic_summary
-#
-#   To target a specific automation, set its Automation ID in config and
-#   include it in the event data:
-#   Event data: {"automation_id": "your-automation-id"}
-#
-# Scheduled Assets:
-#   Sends scheduled notifications with existing assets from tracked albums.
-#   Uses the immich_album_watcher.get_assets service to fetch assets.
-#
-#   Album Modes:
-#   - `per_album`: Send separate notifications for each tracked album
-#   - `combined`:  Fetch assets from all albums into one notification
-#   - `random`:    Pick one random album each time
-#
-#   Asset Filter Options:
-#   - `limit`:            Maximum number of assets to fetch (1-100)
-#   - `favorite_only`:    Only fetch favorite assets
-#   - `asset_type`:       Filter by type (all, photo, video)
-#   - `order_by`:         Sort by (random, date, rating, name)
-#   - `order`:            Sort direction (ascending, descending)
-#   - `filter_min_rating`: Minimum rating filter (1-5, 0 = no filter)
-#   - `min_date`:         Assets created on or after this date (YYYY-MM-DD)
-#   - `max_date`:         Assets created on or before this date (YYYY-MM-DD)
-#
-#   Scheduled Assets Message Template Variables:
-#   - `{album_name}`   - Name of the album
-#   - `{album_url}`    - Share URL for the album
-#   - `{asset_count}`  - Number of assets fetched
-#   - `{assets}`       - Formatted list of assets (using asset item template)
-#
-#   Testing Scheduled Assets:
-#   To test without waiting for the scheduled time, fire this event:
-#   Event type: immich_album_watcher_test_scheduled_assets
-#
-#   To target a specific automation, set its Automation ID in config and
-#   include it in the event data:
-#   Event data: {"automation_id": "your-automation-id"}
-#
-# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Immich Album Watcher"

Common/Motion Light/README.md

@@ -0,0 +1,54 @@
+# Motion Light Automation Blueprint
+
+This blueprint creates a smart motion-activated light control system. It handles motion detection, luminance-based triggering, and manual override detection to provide intelligent lighting automation.
+
+## Features
+
+- Multiple motion sensor support (triggers on ANY sensor)
+- Condition switches (ALL must be ON for automation to work)
+- Multiple lights and/or switches control
+- Light groups and area-based targeting
+- Configurable timeout delay before turning off
+- Minimum on duration (prevents rapid on/off cycling)
+- Motion sensor debounce (filter false triggers)
+- Smooth light transitions with configurable duration
+- Luminance sensor support (only trigger in dark conditions)
+- Time-based conditions (only active during specified hours)
+- Day/Night mode (different light settings based on time)
+- Scene support (activate scenes instead of light parameters)
+- Dim before off (visual warning before turning off)
+- Manual override detection (stops automation if user changes light)
+- Brightness threshold (only trigger if light is dim)
+- Custom light parameters (brightness, color, etc.)
+- Callback actions for enable/disable/manual events
+- Debug notifications for troubleshooting
+
+## State Machine
+
+The automation tracks these states via persistent storage:
+
+| State | Value | Description |
+|-------|-------|-------------|
+| NONE | 0 | Idle, waiting for motion |
+| ENABLING | 2 | Light turn-on command sent, waiting for state change |
+| ENABLED | 1 | Light is ON and controlled by automation |
+| MANUAL | 3 | User took control, automation paused until light turns off |
+
+## Behavior Notes
+
+- Will NOT turn on light if it's already ON (prevents hijacking user control)
+- If user changes light while automation is active, enters MANUAL mode
+- MANUAL mode exits when light is turned OFF (by any means)
+- Timeout delay only applies when turning OFF (motion cleared)
+- Time conditions support overnight windows (e.g., 22:00 to 06:00)
+- Day/Night mode uses separate time window from time conditions
+
+## Requirements
+
+- At least one motion sensor
+- `input_text` entity for persistent state storage
+- Target light(s), switch(es), group, or area to control
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Motion Light/blueprint.yaml

@@ -1,52 +1,6 @@
-# =============================================================================
+# Motion Light Automation Blueprint
-# Motion Light Automation Blueprint for Home Assistant
+# Smart motion-activated light control with manual override detection.
-# =============================================================================
+# See README.md for detailed documentation.
-# This blueprint creates a smart motion-activated light control system.
-# It handles motion detection, luminance-based triggering, and manual override
-# detection to provide intelligent lighting automation.
-#
-# Features:
-#   - Multiple motion sensor support (triggers on ANY sensor)
-#   - Condition switches (ALL must be ON for automation to work)
-#   - Multiple lights and/or switches control
-#   - Light groups and area-based targeting
-#   - Configurable timeout delay before turning off
-#   - Minimum on duration (prevents rapid on/off cycling)
-#   - Motion sensor debounce (filter false triggers)
-#   - Smooth light transitions with configurable duration
-#   - Luminance sensor support (only trigger in dark conditions)
-#   - Time-based conditions (only active during specified hours)
-#   - Day/Night mode (different light settings based on time)
-#   - Scene support (activate scenes instead of light parameters)
-#   - Dim before off (visual warning before turning off)
-#   - Manual override detection (stops automation if user changes light)
-#   - Brightness threshold (only trigger if light is dim)
-#   - Custom light parameters (brightness, color, etc.)
-#   - Callback actions for enable/disable/manual events
-#   - Debug notifications for troubleshooting
-#
-# State Machine:
-#   The automation tracks these states via persistent storage:
-#   - NONE (0):     Idle, waiting for motion
-#   - ENABLING (2): Light turn-on command sent, waiting for state change
-#   - ENABLED (1):  Light is ON and controlled by automation
-#   - MANUAL (3):   User took control, automation paused until light turns off
-#
-# Behavior Notes:
-#   - Will NOT turn on light if it's already ON (prevents hijacking user control)
-#   - If user changes light while automation is active, enters MANUAL mode
-#   - MANUAL mode exits when light is turned OFF (by any means)
-#   - Timeout delay only applies when turning OFF (motion cleared)
-#   - Time conditions support overnight windows (e.g., 22:00 to 06:00)
-#   - Day/Night mode uses separate time window from time conditions
-#
-# Requirements:
-#   - At least one motion sensor
-#   - input_text entity for persistent state storage
-#   - Target light(s), switch(es), group, or area to control
-#
-# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Motion Light"

Common/Refrigerator/README.md

@@ -0,0 +1,21 @@
+# Refrigerator Express Mode Control Blueprint
+
+This blueprint monitors refrigerator temperature and automatically enables express/turbo cooling mode when the temperature drifts too far from target.
+
+## How It Works
+
+- Monitors the temperature sensor and compares to target temperature
+- If difference exceeds threshold (and door is closed), enables express mode
+- Sends notification when express mode is activated
+- Automatically disables express mode when temperature normalizes
+
+## Requirements
+
+- Door sensor (binary_sensor) to detect if door is open
+- Temperature sensor reporting current fridge temperature
+- Climate entity with target temperature attribute
+- Switch entity to control express/turbo mode
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Refrigerator/blueprint.yaml

@@ -1,23 +1,6 @@
-# =============================================================================
 # Refrigerator Express Mode Control Blueprint
-# =============================================================================
+# Enables express cooling when temperature drifts too far from target.
-# This blueprint monitors refrigerator temperature and automatically enables
+# See README.md for detailed documentation.
-# express/turbo cooling mode when the temperature drifts too far from target.
-#
-# How It Works:
-# - Monitors the temperature sensor and compares to target temperature
-# - If difference exceeds threshold (and door is closed), enables express mode
-# - Sends notification when express mode is activated
-# - Automatically disables express mode when temperature normalizes
-#
-# Requirements:
-# - Door sensor (binary_sensor) to detect if door is open
-# - Temperature sensor reporting current fridge temperature
-# - Climate entity with target temperature attribute
-# - Switch entity to control express/turbo mode
-#
-# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Refrigerator Express Mode Control"

Common/Telegram Commands/README.md

@@ -0,0 +1,30 @@
+# Telegram Commands Blueprint
+
+This blueprint responds to Telegram bot commands (e.g., /start, /help, /status). Each command can trigger a different callback action and send an optional reply.
+
+## How It Works
+
+1. User sends a command to the Telegram bot (e.g., `/lights_on`)
+2. Home Assistant receives `telegram_command` event
+3. Blueprint matches command to the configured list
+4. Executes the corresponding callback action
+5. Optionally sends a reply message
+
+## Command Format
+
+Commands should start with "/" (e.g., `/status`, `/lights_on`, `/arm_alarm`). The bot must be configured to receive these commands.
+
+## Example Configuration
+
+| Commands | Answers |
+|----------|---------|
+| `/status` | "Status checked" |
+| `/lights_on` | "Lights turned on" |
+| `/lights_off` | "Lights turned off" |
+| `/arm` | "Alarm armed" |
+
+Each command has its own callback action that executes when received.
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Telegram Commands/blueprint.yaml

@@ -1,27 +1,6 @@
-# =============================================================================
 # Telegram Commands Blueprint
-# =============================================================================
+# Responds to Telegram bot commands by executing callback actions.
-# This blueprint responds to Telegram bot commands (e.g., /start, /help, /status).
+# See README.md for detailed documentation.
-# Each command can trigger a different callback action and send an optional reply.
-#
-# How It Works:
-# 1. User sends a command to the Telegram bot (e.g., /lights_on)
-# 2. Home Assistant receives telegram_command event
-# 3. Blueprint matches command to the configured list
-# 4. Executes the corresponding callback action
-# 5. Optionally sends a reply message
-#
-# Command Format:
-# Commands should start with "/" (e.g., /status, /lights_on, /arm_alarm)
-# The bot must be configured to receive these commands.
-#
-# Example Configuration:
-# - Commands: ["/status", "/lights_on", "/lights_off", "/arm"]
-# - Answers: ["Status checked", "Lights turned on", "Lights turned off", "Alarm armed"]
-# - Each command has its own callback action
-#
-# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Telegram Commands"

Common/Telegram Question/README.md

@@ -0,0 +1,34 @@
+# Telegram Keyboard Action Blueprint
+
+This blueprint creates interactive Telegram messages with inline keyboard buttons. When a button is pressed, the corresponding callback action runs.
+
+## How It Works
+
+1. Manual trigger (service call) → Sends message with keyboard to chat(s)
+2. Button press → Triggers `telegram_callback` event
+3. Blueprint matches callback data to `keyboard_id`
+4. Executes the corresponding button's callback action
+5. Optionally sends answer and/or hides keyboard/message
+
+## Chat ID Resolution
+
+Chat IDs can be provided in two ways:
+
+- Directly as text list (`chat_ids` input)
+- From notify entities with friendly names like `"Alex (123456789)"` - the number in parentheses is extracted as the chat ID
+
+## Multiple Telegram Bots
+
+If you have multiple Telegram bots configured in Home Assistant, you must specify the `config_entry_id` to identify which bot to use.
+
+Find it in: Settings → Devices & Services → Telegram Bot → your bot → URL
+
+## Callback Data Format
+
+Each button sends callback data: `/<keyboard_id>_<button_index>`
+
+Example: `/my_keyboard_0` for first button of keyboard `"my_keyboard"`
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Telegram Question/blueprint.yaml

@@ -1,33 +1,8 @@
-# =============================================================================
 # Telegram Keyboard Action Blueprint
-# =============================================================================
+# Creates interactive Telegram messages with inline keyboard buttons and
-# This blueprint creates interactive Telegram messages with inline keyboard
+# handles button callbacks. See README.md for detailed documentation.
-# buttons. When a button is pressed, the corresponding callback action runs.
-#
-# How It Works:
-# 1. Manual trigger (service call) -> Sends message with keyboard to chat(s)
-# 2. Button press -> Triggers telegram_callback event
-# 3. Blueprint matches callback data to keyboard_id
-# 4. Executes the corresponding button's callback action
-# 5. Optionally sends answer and/or hides keyboard/message
-#
-# Chat ID Resolution:
-# Chat IDs can be provided in two ways:
-# - Directly as text list (chat_ids input)
-# - From notify entities with friendly names like "Alex (123456789)"
-#   The number in parentheses is extracted as the chat ID
-#
-# Multiple Telegram Bots:
-# If you have multiple Telegram bots configured in Home Assistant, you must
-# specify the config_entry_id to identify which bot to use.
-# Find it in: Settings → Devices & Services → Telegram Bot → your bot → URL
-#
-# Callback Data Format:
-# Each button sends callback data: /<keyboard_id>_<button_index>
-# Example: /my_keyboard_0 for first button of keyboard "my_keyboard"
 #
 # Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Telegram Keyboard Action"

Common/Thermostat Controller/README.md

@@ -0,0 +1,26 @@
+# Thermostat Controller Blueprint
+
+This blueprint controls a thermostat/climate entity based on schedules, presence, and various conditions.
+
+## Features
+
+- Schedule-based heating control (using HA schedule helper)
+- Working and standby temperature modes
+- Optional input_number overrides for temperatures
+- External temperature sensor support
+- Window/door sensor integration (disable when open)
+- Force heating override
+- Minimum on-time to prevent rapid cycling
+- Configurable behavior when disabled (off vs standby)
+- Debug notifications for troubleshooting
+
+## Temperature Priority
+
+1. Windows open → Turn off (or standby based on setting)
+2. Force heating ON → Working temperature
+3. Schedule active → Working temperature
+4. Schedule inactive → Standby temperature (or off)
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Thermostat Controller/blueprint.yaml

@@ -1,28 +1,6 @@
-# =============================================================================
 # Thermostat Controller Blueprint
-# =============================================================================
+# Controls thermostat based on schedules, window sensors, and force heating.
-# This blueprint controls a thermostat/climate entity based on schedules,
+# See README.md for detailed documentation.
-# presence, and various conditions.
-#
-# Features:
-#   - Schedule-based heating control (using HA schedule helper)
-#   - Working and standby temperature modes
-#   - Optional input_number overrides for temperatures
-#   - External temperature sensor support
-#   - Window/door sensor integration (disable when open)
-#   - Force heating override
-#   - Minimum on-time to prevent rapid cycling
-#   - Configurable behavior when disabled (off vs standby)
-#   - Debug notifications for troubleshooting
-#
-# Temperature Priority:
-#   1. Windows open → Turn off (or standby based on setting)
-#   2. Force heating ON → Working temperature
-#   3. Schedule active → Working temperature
-#   4. Schedule inactive → Standby temperature (or off)
-#
-# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Thermostat Controller"

Common/Time Of Day Controller/README.md

@@ -0,0 +1,35 @@
+# Time of Day State Machine Blueprint
+
+This blueprint automatically updates an input_select based on time-of-day thresholds. Useful for managing different modes throughout the day (morning, afternoon, evening, night, etc.).
+
+## How It Works
+
+- Define states (e.g., "Morning", "Afternoon", "Evening", "Night")
+- Define corresponding time thresholds for each state
+- The blueprint sets the input_select to the appropriate state based on current time
+
+## Index Mapping
+
+States and times are mapped by index position:
+
+| Index | State | Time |
+|-------|-------|------|
+| 0 | states[0] | times[0] |
+| 1 | states[1] | times[1] |
+| 2 | states[2] | times[2] |
+| etc. | etc. | etc. |
+
+## Supported Time Formats
+
+- `input_datetime` entities (time-only: HH:MM:SS)
+- Sensor entities reporting time strings (e.g., `sun.sun` next_rising attribute)
+
+## Example Configuration
+
+- **States**: `["Night", "Morning", "Afternoon", "Evening"]`
+- **Times**: `[00:00, 06:00, 12:00, 18:00]`
+- At 14:30, the state would be "Afternoon" (last threshold passed)
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Time Of Day Controller/blueprint.yaml

@@ -1,33 +1,6 @@
-# =============================================================================
 # Time of Day State Machine Blueprint
-# =============================================================================
+# Updates an input_select based on time-of-day thresholds.
-# This blueprint automatically updates an input_select based on time-of-day
+# See README.md for detailed documentation.
-# thresholds. Useful for managing different modes throughout the day
-# (morning, afternoon, evening, night, etc.).
-#
-# How It Works:
-# - Define states (e.g., "Morning", "Afternoon", "Evening", "Night")
-# - Define corresponding time thresholds for each state
-# - The blueprint sets the input_select to the appropriate state based on
-#   current time
-#
-# Index Mapping:
-# States and times are mapped by index position:
-# - states[0] activates at times[0]
-# - states[1] activates at times[1]
-# - etc.
-#
-# Supported Time Formats:
-# - input_datetime entities (time-only: HH:MM:SS)
-# - Sensor entities reporting time strings (e.g., sun.sun next_rising attribute)
-#
-# Example Configuration:
-# - States: ["Night", "Morning", "Afternoon", "Evening"]
-# - Times: [00:00, 06:00, 12:00, 18:00]
-# - At 14:30, the state would be "Afternoon" (last threshold passed)
-#
-# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Time of Day State Machine"

Common/Track Abnormal Plug Activity/README.md

@@ -0,0 +1,27 @@
+# Power Overconsumption Monitor Blueprint
+
+This blueprint monitors power sensors for sustained overconsumption that might indicate device malfunction, overload, or safety concerns.
+
+## How It Works
+
+- Triggers when power EXCEEDS a maximum threshold
+- Requires power to stay high for a configurable duration (filters startup spikes)
+- Optionally ignores readings below an idle threshold (device "off")
+- Can automatically turn off the switch for safety
+
+## Use Cases
+
+- Space heater drawing more than rated wattage (fire risk)
+- Motor consuming excessive power (mechanical binding/failure)
+- Appliance exceeding safe operating limits
+- Extension cord/circuit overload protection
+
+## Naming Convention
+
+The blueprint assumes sensors follow the pattern: `sensor.<name>_power` and the corresponding switch is: `switch.<name>`
+
+**Example**: `sensor.coffee_maker_power` → `switch.coffee_maker`
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Track Abnormal Plug Activity/blueprint.yaml

@@ -1,28 +1,6 @@
-# =============================================================================
 # Power Overconsumption Monitor Blueprint
-# =============================================================================
+# Monitors power sensors for sustained overconsumption above a threshold.
-# This blueprint monitors power sensors for sustained overconsumption that
+# See README.md for detailed documentation.
-# might indicate device malfunction, overload, or safety concerns.
-#
-# How It Works:
-# - Triggers when power EXCEEDS a maximum threshold
-# - Requires power to stay high for a configurable duration (filters startup spikes)
-# - Optionally ignores readings below an idle threshold (device "off")
-# - Can automatically turn off the switch for safety
-#
-# Use Cases:
-# - Space heater drawing more than rated wattage (fire risk)
-# - Motor consuming excessive power (mechanical binding/failure)
-# - Appliance exceeding safe operating limits
-# - Extension cord/circuit overload protection
-#
-# Naming Convention:
-# The blueprint assumes sensors follow the pattern: sensor.<name>_power
-# and the corresponding switch is: switch.<name>
-# Example: sensor.coffee_maker_power -> switch.coffee_maker
-#
-# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Power Overconsumption Monitor"

Common/Washing Machine/README.md

@@ -0,0 +1,73 @@
+# Washing Machine / Dryer Notifications Blueprint
+
+This blueprint monitors washing machine or dryer appliances and sends notifications for various events throughout the wash/dry cycle.
+
+## Features
+
+- Start notification with cycle duration, estimated end time, and mode details
+- Completion notification (reminder to unload clothes) with energy report
+- "Almost done" notification (configurable minutes before end)
+- Pause/Resume notifications (detect when cycle is paused or resumed)
+- Error message notifications
+- Preparation mode notification (e.g., for dryer prep)
+- Tub/drum cleaning reminder based on wash counter
+- Power consumption monitoring with energy tracking per cycle
+- Fully customizable notification messages (i18n support)
+- Debug notifications for troubleshooting
+
+## State Machine
+
+The automation tracks the appliance through these states:
+
+| State | Description |
+|-------|-------------|
+| IDLE | Waiting for cycle to start |
+| RUNNING | Cycle in progress (start notification sent) |
+| PAUSED | Cycle temporarily paused (pause notification sent) |
+| FINISHING | Near completion (time-to-end notification sent) |
+| COMPLETED | Cycle done (completion notification sent, state reset) |
+
+## Persistent State Keys
+
+| Key | Description |
+|-----|-------------|
+| `nass` | Notification About Start Sent |
+| `nart` | Notification About Remaining Time Sent |
+| `naps` | Notification About Preparation Sent |
+| `napas` | Notification About Pause Sent |
+| `wasp` | Was Paused flag |
+| `cst` | Cycle Start Time (ISO timestamp) |
+| `esmp` | Energy Samples accumulator (Wh) |
+| `lst` | Last Sample Time (ISO timestamp) |
+
+## Message Template Variables
+
+All message templates support these placeholder variables (use single braces):
+
+| Variable | Description |
+|----------|-------------|
+| `{appliance_name}` | Device name (e.g., "Washing Machine") |
+| `{remaining}` | Remaining time as string (e.g., "01:30:00") |
+| `{estimated_end}` | Estimated completion time (e.g., "14:30") |
+| `{minutes}` | Remaining minutes as number (e.g., 90) |
+| `{error}` | Error message text (only in error notification) |
+| `{tub_count}` | Tub clean counter value (only in tub clean notification) |
+| `{tub_threshold}` | Tub clean threshold (only in tub clean notification) |
+| `{details}` | Startup details from sensors (only in start notification) |
+| `{energy_kwh}` | Energy consumed in kWh (only in completion notification) |
+| `{energy_cost}` | Estimated cost (only in completion notification) |
+
+## Requirements
+
+- Sensors for: remaining time, run state, error messages
+- `input_text` entity for persistent state storage
+- Notification service entity
+- (Optional) Power sensor for energy tracking
+
+## Note
+
+Default messages are in Russian for LG ThinQ integration. Customize messages in the "Messages" section for your language.
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Common/Washing Machine/blueprint.yaml

@@ -1,63 +1,8 @@
-# =============================================================================
+# Washing Machine / Dryer Notifications Blueprint
-# Washing Machine / Dryer Notifications Blueprint for Home Assistant
+# Monitors appliance cycles and sends notifications for start, completion,
-# =============================================================================
+# errors, and more. See README.md for detailed documentation.
-# This blueprint monitors washing machine or dryer appliances and sends
-# notifications for various events throughout the wash/dry cycle.
-#
-# Features:
-#   - Start notification with cycle duration, estimated end time, and mode details
-#   - Completion notification (reminder to unload clothes) with energy report
-#   - "Almost done" notification (configurable minutes before end)
-#   - Pause/Resume notifications (detect when cycle is paused or resumed)
-#   - Error message notifications
-#   - Preparation mode notification (e.g., for dryer prep)
-#   - Tub/drum cleaning reminder based on wash counter
-#   - Power consumption monitoring with energy tracking per cycle
-#   - Fully customizable notification messages (i18n support)
-#   - Debug notifications for troubleshooting
-#
-# State Machine:
-#   The automation tracks the appliance through these states:
-#   1. IDLE: Waiting for cycle to start
-#   2. RUNNING: Cycle in progress (start notification sent)
-#   3. PAUSED: Cycle temporarily paused (pause notification sent)
-#   4. FINISHING: Near completion (time-to-end notification sent)
-#   5. COMPLETED: Cycle done (completion notification sent, state reset)
-#
-# Persistent State Keys:
-#   - nass:  Notification About Start Sent
-#   - nart:  Notification About Remaining Time Sent
-#   - naps:  Notification About Preparation Sent
-#   - napas: Notification About Pause Sent
-#   - wasp:  Was Paused flag
-#   - cst:   Cycle Start Time (ISO timestamp)
-#   - esmp:  Energy Samples accumulator (Wh)
-#   - lst:   Last Sample Time (ISO timestamp)
-#
-# Message Template Variables:
-#   All message templates support these placeholder variables (use single braces):
-#   - `{appliance_name}` - Device name (e.g., "Washing Machine")
-#   - `{remaining}`      - Remaining time as string (e.g., "01:30:00")
-#   - `{estimated_end}`  - Estimated completion time (e.g., "14:30")
-#   - `{minutes}`        - Remaining minutes as number (e.g., 90)
-#   - `{error}`          - Error message text (only in error notification)
-#   - `{tub_count}`      - Tub clean counter value (only in tub clean notification)
-#   - `{tub_threshold}`  - Tub clean threshold (only in tub clean notification)
-#   - `{details}`        - Startup details from sensors (only in start notification)
-#   - `{energy_kwh}`     - Energy consumed in kWh (only in completion notification)
-#   - `{energy_cost}`    - Estimated cost (only in completion notification)
-#
-# Requirements:
-#   - Sensors for: remaining time, run state, error messages
-#   - input_text entity for persistent state storage
-#   - Notification service entity
-#   - (Optional) Power sensor for energy tracking
-#
-# Note: Default messages are in Russian for LG ThinQ integration.
-#       Customize messages in the "Messages" section for your language.
 #
 # Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: Washing Machine Notifications"

Zigbee/MQTT Button Control/README.md

@@ -0,0 +1,22 @@
+# MQTT Button Control Blueprint
+
+Controls lights and switches using Zigbee2MQTT button devices with multiple action mappings.
+
+## Features
+
+- Map multiple action IDs to different lights/switches
+- Supports light, switch, and input_boolean entities
+- Visual feedback via blink indication when pressing already-active light
+- Tracks last interacted entity in an input_text helper
+- Supports multiple MQTT topics (multiple buttons)
+
+## How It Works
+
+1. Receives MQTT messages with action IDs from Zigbee buttons
+2. Maps action ID to corresponding entity by index position
+3. Toggles the matched entity (light/switch/input_boolean)
+4. Optionally blinks light if it's already on (idle timeout feature)
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Zigbee/MQTT Button Control/blueprint.yaml

@@ -1,24 +1,8 @@
-# =============================================================================
 # MQTT Button Control Blueprint
-# =============================================================================
+# Controls lights and switches using Zigbee2MQTT button devices.
-# Controls lights and switches using Zigbee2MQTT button devices with multiple
+# See README.md for detailed documentation.
-# action mappings.
-#
-# Features:
-# - Map multiple action IDs to different lights/switches
-# - Supports light, switch, and input_boolean entities
-# - Visual feedback via blink indication when pressing already-active light
-# - Tracks last interacted entity in an input_text helper
-# - Supports multiple MQTT topics (multiple buttons)
-#
-# How It Works:
-# - Receives MQTT messages with action IDs from Zigbee buttons
-# - Maps action ID to corresponding entity by index position
-# - Toggles the matched entity (light/switch/input_boolean)
-# - Optionally blinks light if it's already on (idle timeout feature)
 #
 # Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: MQTT Button Control"

Zigbee/MQTT Generic Control/README.md

@@ -0,0 +1,21 @@
+# MQTT Generic Control Blueprint
+
+A flexible blueprint that triggers custom actions based on MQTT messages. Supports up to 8 different action IDs, each with its own callback.
+
+## Features
+
+- Listen to up to 4 MQTT topics simultaneously
+- Map up to 8 action IDs to custom callback actions
+- Works with any Zigbee2MQTT device that sends action payloads
+- Fully customizable actions for each trigger
+
+## How It Works
+
+1. Listens for MQTT messages on configured topics
+2. Extracts the `action` field from the JSON payload
+3. Matches action against configured action IDs
+4. Executes the corresponding callback action sequence
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Zigbee/MQTT Generic Control/blueprint.yaml

@@ -1,23 +1,8 @@
-# =============================================================================
 # MQTT Generic Control Blueprint
-# =============================================================================
+# Triggers custom actions based on MQTT messages with up to 8 action callbacks.
-# A flexible blueprint that triggers custom actions based on MQTT messages.
+# See README.md for detailed documentation.
-# Supports up to 8 different action IDs, each with its own callback.
-#
-# Features:
-# - Listen to up to 4 MQTT topics simultaneously
-# - Map up to 8 action IDs to custom callback actions
-# - Works with any Zigbee2MQTT device that sends action payloads
-# - Fully customizable actions for each trigger
-#
-# How It Works:
-# - Listens for MQTT messages on configured topics
-# - Extracts the `action` field from the JSON payload
-# - Matches action against configured action IDs
-# - Executes the corresponding callback action sequence
 #
 # Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: MQTT Generic Control"

Zigbee/MQTT Light Control/README.md

@@ -0,0 +1,22 @@
+# MQTT Light Control Blueprint
+
+Provides extended light control functionality via MQTT devices (typically Zigbee controllers through zigbee2mqtt).
+
+## Features
+
+- Control multiple lights via MQTT topics
+- Sequential and "all at once" turn on/off actions
+- Brightness control (increment, hold, list-based, min/max)
+- Color temperature control (increment, hold, list-based)
+- RGB/Hue control (increment, hold, list-based)
+- Preset list support (JSON format) for quick scene switching
+- Scene activation support (up to 4 scenes)
+- Light group and area targeting
+- Configurable transition duration for smooth changes
+- Alternative light support (control secondary lights when primary are off)
+- Persistent state storage via input_text entity
+- Custom action callbacks for extending functionality
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Zigbee/MQTT Light Control/blueprint.yaml

@@ -1,25 +1,8 @@
-# =============================================================================
+# MQTT Light Control Blueprint
-# MQTT Light Control Blueprint for Home Assistant
+# Extended light control via MQTT devices with brightness, color temp, and RGB support.
-# =============================================================================
+# See README.md for detailed documentation.
-# This blueprint provides extended light control functionality via MQTT devices
-# (typically Zigbee controllers through zigbee2mqtt).
-#
-# Features:
-#   - Control multiple lights via MQTT topics
-#   - Sequential and "all at once" turn on/off actions
-#   - Brightness control (increment, hold, list-based, min/max)
-#   - Color temperature control (increment, hold, list-based)
-#   - RGB/Hue control (increment, hold, list-based)
-#   - Preset list support (JSON format) for quick scene switching
-#   - Scene activation support (up to 4 scenes)
-#   - Light group and area targeting
-#   - Configurable transition duration for smooth changes
-#   - Alternative light support (control secondary lights when primary are off)
-#   - Persistent state storage via input_text entity
-#   - Custom action callbacks for extending functionality
 #
 # Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "Custom: MQTT Light Control"

Zigbee/MQTT Light Selector/README.md

@@ -0,0 +1,22 @@
+# MQTT Light Selector Blueprint
+
+Cycles through a list of lights using MQTT button events (up/down/remind). The selected light flashes to provide visual feedback, then returns to its original state. Selection is persisted in an input_text helper.
+
+## Features
+
+- Navigate lights with up/down actions
+- Remind action flashes the currently selected light
+- Visual feedback via configurable flash pattern
+- Persists selection in an input_text helper
+- Optional state persistence across restarts (JSON storage)
+- Optional "remind on idle" - up/down acts as remind if idle too long
+
+## How It Works
+
+1. Press up/down to cycle through the light list
+2. Selected light flashes N times to confirm selection
+3. Light returns to its original on/off state after flashing
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Zigbee/MQTT Light Selector/blueprint.yaml

@@ -1,12 +1,8 @@
-# =============================================================================
 # MQTT Light Selector Blueprint
-# =============================================================================
+# Cycles through lights using MQTT button events with visual feedback.
-# Cycles through a list of lights using MQTT button events (up/down/remind).
+# See README.md for detailed documentation.
-# The selected light flashes to provide visual feedback, then returns to its
-# original state. Selection is persisted in an input_text helper.
 #
 # Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "MQTT Light Selector"

Zigbee/Media Knob Control/README.md

@@ -0,0 +1,23 @@
+# MQTT Knob Media Controller Blueprint
+
+Controls a media player using an MQTT-connected rotary encoder/knob.
+
+## Features
+
+- Play/Pause toggle (button press)
+- Volume up/down (rotation)
+- Mute toggle (optional)
+- Next/Previous track (optional)
+
+## Volume Step Behavior
+
+- If your device sends `action_step_size` in the MQTT payload, it will be used
+- Otherwise, the configured default step size is applied
+
+## Configuration
+
+Action IDs can be customized to match your specific MQTT device.
+
+## Author
+
+Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

Zigbee/Media Knob Control/blueprint.yaml

@@ -1,11 +1,8 @@
-# =============================================================================
 # MQTT Knob Media Controller Blueprint
-# =============================================================================
 # Controls a media player using an MQTT-connected rotary encoder/knob.
-# Supports customizable action IDs to work with various MQTT devices.
+# See README.md for detailed documentation.
 #
 # Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
-# =============================================================================
 
 blueprint:
   name: "MQTT Knob Media Controller"

manifest.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.19.3"
+  "version": "1.20.0"
 }