luuquangvu · luuquangvu · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
-.env
 .venv/
 .vscode/
 __pycache__/
 .ruff_cache/
+node_modules/
 uv.lock
+package-lock.json
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,44 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Run Ruff Check
+        entry: uv run ruff check --fix
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: ruff-format
+        name: Run Ruff Format
+        entry: uv run ruff format
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: ty-check
+        name: Run Ty Check
+        entry: uv run ty check
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: interrogate
+        name: Run Interrogate
+        entry: uv run interrogate
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: prettier
+        name: Run Prettier
+        entry: npx prettier --write .
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: blueprints-check
+        name: Run Blueprints Check
+        entry: uv run tools/validate_blueprints.py
+        language: system
+        pass_filenames: false
+        always_run: true
diff --git a/README.md b/README.md
diff --git a/README_vi.md b/README_vi.md
diff --git a/check_the_device_turns_on_manually.yaml b/check_the_device_turns_on_manually.yaml
@@ -5,7 +5,17 @@ blueprint:
   description: |-
     # Verify whether the device activated manually or via automation/application
 
-    - Prevents false triggers when device comes back from unavailable/unknown state.
+    Identifies whether a device was turned on physically by a human (e.g., pressing a physical wall switch) versus triggered programmatically by an automation, script, or user in the Home Assistant app/dashboard.
+
+    ### Key Features:
+    - **Physical Activation Detection:** Uses Home Assistant event context (`parent_id` and `user_id`) to reliably differentiate physical button presses from software-initiated commands.
+    - **State Synchronization:** Updates an `input_boolean` helper entity (`on` when turned on manually/physically, `off` when turned off or triggered programmatically).
+    - **Fail-Safe Filtering:** Restricts state transitions strictly between `on` and `off`, preventing false activations when devices recover or reboot from `unavailable` or `unknown` states.
+
+    ### Requirements:
+    - A target switch or light entity (`switch` or `light`).
+    - An `input_boolean` helper entity to reflect the manual activation state.
+    - Requires Home Assistant 2024.12.0 or newer.
   domain: automation
   homeassistant:
     min_version: 2024.12.0

diff --git a/create_calendar_event_full_llm.yaml b/create_calendar_event_full_llm.yaml
@@ -3,7 +3,7 @@ blueprint:
   author: luuquangvu
   source_url: https://github.com/luuquangvu/tutorials/blob/dev/create_calendar_event_full_llm.yaml
   description: |-
-    # Tool help to create calendar events used for Voice Assistant
+    # Tool helps create calendar events used for Voice Assistant
 
     ## Blueprint Setup
 

diff --git a/create_lunar_events.yaml b/create_lunar_events.yaml
@@ -3,7 +3,7 @@ blueprint:
   author: luuquangvu
   source_url: https://github.com/luuquangvu/tutorials/blob/dev/create_lunar_events.yaml
   description: |-
-    # Tool help to create Lunar calendar events
+    # Tool helps create Lunar calendar events
 
     ## Blueprint Setup
 

diff --git a/date_lookup_and_conversion_full_llm.yaml b/date_lookup_and_conversion_full_llm.yaml
@@ -3,7 +3,7 @@ blueprint:
   author: luuquangvu
   source_url: https://github.com/luuquangvu/tutorials/blob/dev/date_lookup_and_conversion_full_llm.yaml
   description: |-
-    # Tool converts Solar date to Lunar date and vice versa used for Voice Assistant
+    # Tool converts Solar dates to Lunar dates and vice versa used for Voice Assistant
 
     ## Blueprint Setup
 

diff --git a/devices_schedules.yaml b/devices_schedules.yaml
@@ -16,8 +16,8 @@ blueprint:
     ### Required
 
     - The Pyscript integration needs to be installed through HACS and properly configured.
-    - The `scripts/common_utilities.py` script need to be copied into the `config/pyscript` folder.
-    - This blueprint is a dependency for the `devices_schedules_full_llm.yaml` and the `devices_schedules_restart_handler.yaml` blueprints.
+    - The `scripts/common_utilities.py` script needs to be copied into the `config/pyscript` folder.
+    - This blueprint is a dependency for the `devices_schedules_controller_full_llm.yaml` and the `devices_schedules_restart_handler.yaml` blueprints.
     - The mentioned file(s) is/are included in the repository.
     - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.
 

diff --git a/devices_schedules_controller_full_llm.yaml b/devices_schedules_controller_full_llm.yaml
@@ -32,7 +32,7 @@ blueprint:
 
     ### Required
 
-    - The `devices_schedules.yaml` and `devices_schedules_restart_handler.yaml` blueprints needs to be installed.
+    - The `devices_schedules.yaml` and `devices_schedules_restart_handler.yaml` blueprints need to be installed.
     - The mentioned file(s) is/are included in the repository.
     - A template sensor stores all information about entity aliases needs to be configured in `config/configuration.yaml`; The sensor is required for friendly-name lookup.
 

diff --git a/devices_schedules_restart_handler.yaml b/devices_schedules_restart_handler.yaml
@@ -13,7 +13,7 @@ blueprint:
     ### Required
 
     - The Pyscript integration needs to be installed through HACS and properly configured.
-    - The `scripts/common_utilities.py` script need to be copied into the `config/pyscript` folder.
+    - The `scripts/common_utilities.py` script needs to be copied into the `config/pyscript` folder.
     - The `devices_schedules.yaml` blueprint needs to be installed.
     - The mentioned file(s) is/are included in the repository.
     - You need to enable two Pyscript options through the UI or via YAML to allow importing all Python packages and to make hass available as a global variable.

diff --git a/get_youtube_video_info_full_llm.yaml b/get_youtube_video_info_full_llm.yaml
@@ -9,7 +9,7 @@ blueprint:
 
     ### Required
 
-    - Check out the guide for further details.
+    - Check out the guide `home_assistant_play_favorite_youtube_channel_videos_en.md` for further details.
     - The Feedparser integration needs to be installed from HACS.
     - Expose YouTube Channel entities after created to Assist.
     - Consider adding entity aliases to make them easier to remember if needed.

diff --git a/home_assistant_device_location_lookup_guide_en.md b/home_assistant_device_location_lookup_guide_en.md
@@ -17,8 +17,8 @@
 
 ## Prerequisites
 
-- **Bermuda BLE Trilateration:** (Optional but recommended) Installed via HACS for room-level tracking.
-- **Home Assistant Companion App:** Installed on mobile devices for "Ring to Find" functionality.
+- **Bermuda BLE Trilateration:** (Optional but recommended) Installed via HACS for room-level tracking. Make sure your Bluetooth proxies or scanners (ESPHome, Shelly, etc.) are assigned to their corresponding **Areas** in Home Assistant so Bermuda can report the room location.
+- **Home Assistant Companion App:** Installed on mobile devices for "Ring to Find" functionality (with notification and critical alert permissions enabled).
 
 ## Installation Guide
 
@@ -32,9 +32,9 @@
 If your phone has both a Mobile App tracker and a Bermuda tracker:
 
 1. **Expose only the Bermuda tracker** to Voice Assist (it provides better room-level accuracy).
-2. **Rename the Bermuda device** to match the Mobile App device name.
-   - _Example:_ If your Mobile App device is named `Pixel 9`, rename your Bermuda device to `Pixel 9` (or `Pixel 9 BLE`).
-   - _Why?_ This links the accurate location from Bermuda with the "Ring" capability of the Mobile App.
+2. **Ensure the Bermuda device name / entity ID matches or contains the Mobile App device name**:
+   - _Example:_ If your Mobile App tracker entity is `device_tracker.pixel_9`, naming your Bermuda device `Pixel 9` or `Pixel 9 BLE` results in `device_tracker.pixel_9_ble`. The blueprint automatically identifies that `pixel_9` matches your mobile device.
+   - _Why?_ This dynamically links the accurate room-level location from Bermuda with the `notify.mobile_app_pixel_9` ringing service of the Mobile App.
 
 ### Step 2: Create a Shell Command for Alias Retrieval
 
@@ -72,7 +72,7 @@ template:
 
 **After adding these codes:**
 
-1. **Restart** Home Assistant.
+1. **Restart** Home Assistant (or reload YAML configurations).
 2. **Note:** If you add or change an Alias later, you must reload Template entities (Developer Tools > YAML > Template Entities) or restart HA.
 
 ### Step 4: Install Blueprints
@@ -86,8 +86,9 @@ This blueprint powers the logic to find where your devices are.
 1. Import the blueprint.
 2. Create a **Script** from it.
 3. In the script settings, select the **Template Sensor** (`sensor.assist_entity_ids_and_aliases`) you created in Step 3.
-4. **Keep the default script name** (or ensure it's easy for the LLM to recognize).
-5. **Expose** this new script to Voice Assist.
+4. **Keep the default script name** (`Find Device`).
+5. **Restore LLM Description (Crucial Step):** After saving, click the three dots (`⋮`) in the top-right corner, select **Edit in YAML**, delete the `description: ...` line, and click **Save Script**. This restores the blueprint's native, optimized description so the LLM understands its purpose.
+6. **Expose** this new script to Voice Assist.
 
 #### 2. Device Ringing Blueprint
 
@@ -97,8 +98,9 @@ This blueprint allows Voice Assist to make your device ring.
 
 1. Import the blueprint.
 2. Create a **Script** from it.
-3. **Keep the default script name**.
-4. **Expose** this new script to Voice Assist.
+3. **Keep the default script name** (`Ring Device`).
+4. **Restore LLM Description (Crucial Step):** After saving, click the three dots (`⋮`) in the top-right corner, select **Edit in YAML**, delete the `description: ...` line, and click **Save Script**.
+5. **Expose** this new script to Voice Assist.
 
 ## Usage Examples
 

diff --git a/home_assistant_device_location_lookup_guide_vi.md b/home_assistant_device_location_lookup_guide_vi.md
@@ -17,8 +17,8 @@
 
 ## Yêu cầu trước khi cài đặt
 
-- **Bermuda BLE Trilateration:** (Khuyên dùng) Cài đặt qua HACS để có khả năng định vị chính xác theo từng phòng.
-- **Home Assistant Companion App:** Cài trên điện thoại/máy tính bảng để sử dụng tính năng đổ chuông.
+- **Bermuda BLE Trilateration:** (Khuyên dùng) Cài đặt qua HACS để có khả năng định vị chính xác theo từng phòng. Hãy đảm bảo các Bluetooth proxy hoặc scanner (ESPHome, Shelly...) đã được gán vào đúng các **Khu vực (Areas)** tương ứng trong Home Assistant để Bermuda có thể xác định tên phòng.
+- **Home Assistant Companion App:** Cài trên điện thoại/máy tính bảng để sử dụng tính năng đổ chuông (cần cấp quyền thông báo và thông báo khẩn cấp/critical alerts trên iOS).
 
 ## Hướng dẫn Cài đặt
 
@@ -32,9 +32,9 @@
 Nếu điện thoại của bạn có cả tracker từ Mobile App và Bermuda:
 
 1. **Chỉ expose tracker của Bermuda** cho Voice Assist (để định vị phòng chính xác hơn).
-2. **Đổi tên thiết bị Bermuda** trùng với tên thiết bị Mobile App.
-   - _Ví dụ:_ Nếu Mobile App tên là `Pixel 9`, hãy đổi tên thiết bị Bermuda thành `Pixel 9` (hoặc `Pixel 9 BLE`).
-   - _Tại sao?_ Việc này giúp liên kết vị trí chính xác từ Bermuda với khả năng "Đổ chuông" của Mobile App.
+2. **Đảm bảo tên thiết bị / entity ID của Bermuda trùng hoặc chứa tên thiết bị Mobile App**:
+   - _Ví dụ:_ Nếu thực thể tracker của Mobile App là `device_tracker.pixel_9`, bạn đặt tên thiết bị Bermuda là `Pixel 9` hoặc `Pixel 9 BLE` (tạo ra `device_tracker.pixel_9_ble`). Blueprint sẽ tự động phát hiện `pixel_9` khớp với thiết bị di động của bạn.
+   - _Tại sao?_ Việc này giúp liên kết vị trí phòng chính xác từ Bermuda với action đổ chuông `notify.mobile_app_pixel_9` của Mobile App.
 
 ### Bước 2: Tạo Shell Command lấy Alias
 
@@ -72,7 +72,7 @@ template:
 
 **Sau khi thêm mã:**
 
-1. **Khởi động lại (Restart)** Home Assistant.
+1. **Khởi động lại (Restart)** Home Assistant (hoặc reload YAML cấu hình).
 2. **Lưu ý:** Nếu sau này bạn thêm hoặc sửa Alias, hãy nhớ reload Template entities (Developer Tools > YAML > Template Entities) hoặc khởi động lại HA.
 
 ### Bước 4: Cài đặt Blueprints
@@ -86,8 +86,9 @@ Blueprint này xử lý logic để xác định vị trí thiết bị.
 1. Import blueprint.
 2. Tạo một **Script** từ blueprint này.
 3. Trong cấu hình script, chọn **Template Sensor** (`sensor.assist_entity_ids_and_aliases`) đã tạo ở Bước 3.
-4. **Giữ nguyên tên script mặc định** (hoặc đặt tên dễ hiểu để LLM nhận diện).
-5. **Expose** script này cho Voice Assist.
+4. **Giữ nguyên tên script mặc định** (`Find Device`).
+5. **Khôi phục mô tả chuẩn cho LLM (Bước cực kỳ quan trọng):** Sau khi lưu script, bấm vào dấu ba chấm (`⋮`) ở góc trên bên phải, chọn **Edit in YAML**, xóa bỏ dòng `description: ...` rồi bấm **Save Script**. Thao tác này giúp script lấy lại phần mô tả gốc của blueprint, giúp LLM hiểu chính xác mục đích sử dụng kịch bản.
+6. **Expose** script này cho Voice Assist.
 
 #### 2. Blueprint Đổ chuông (Ringing)
 
@@ -97,8 +98,9 @@ Blueprint này cho phép Voice Assist kích hoạt thiết bị đổ chuông.
 
 1. Import blueprint.
 2. Tạo một **Script** từ blueprint này.
-3. **Giữ nguyên tên script mặc định**.
-4. **Expose** script này cho Voice Assist.
+3. **Giữ nguyên tên script mặc định** (`Ring Device`).
+4. **Khôi phục mô tả chuẩn cho LLM (Bước cực kỳ quan trọng):** Sau khi lưu script, bấm vào dấu ba chấm (`⋮`) ở góc trên bên phải, chọn **Edit in YAML**, xóa bỏ dòng `description: ...` rồi bấm **Save Script**.
+5. **Expose** script này cho Voice Assist.
 
 ## Ví dụ sử dụng
 

diff --git a/home_assistant_ios_themes_en.md b/home_assistant_ios_themes_en.md
@@ -14,11 +14,8 @@ This guide helps you install a beautiful set of iOS themes, automatically switch
 
 ### Install via HACS
 
-1. Go to **HACS** > **Frontend**.
-2. Search for and install **iOS Themes** ([basnijholt/lovelace-ios-themes](https://github.com/basnijholt/lovelace-ios-themes)).
-3. Go to **HACS** > **Integrations**.
-4. Search for and install **Spook** ([frenck/spook](https://github.com/frenck/spook)).
-   - _Note:_ Spook provides the `input_select.random` feature required for this guide.
+1. In Home Assistant, open **HACS**.
+2. Search for and download **iOS Themes** ([basnijholt/lovelace-ios-themes](https://github.com/basnijholt/lovelace-ios-themes)).
 
 ## 2. Configure Local Backgrounds
 
@@ -102,9 +99,11 @@ actions:
       - action: input_boolean.turn_{{ 'on' if trigger.event == 'sunset' else 'off' }}
         target:
           entity_id: input_boolean.ios_themes_dark_mode
-      - action: input_select.random
+      - action: input_select.select_option
         target:
           entity_id: input_select.ios_themes
+        data:
+          option: "{{ state_attr('input_select.ios_themes', 'options') | random }}"
       - stop: Settings updated. Waiting for re-trigger to apply theme.
   - delay: "00:00:01"
   - action: frontend.set_theme
@@ -118,9 +117,11 @@ actions:
 mode: restart
 ```
 
+_Note: If you have Spook installed, you can also use `action: input_select.random` instead of `input_select.select_option`._
+
 ## 4. Activate Theme on Your Device
 
-**Most Important Step:** For the automation to change your interface, you must select **Use default theme** mode in your user settings.
+**Most Important Step:** For the automation to change your interface, you must select **Backend-selected** (or **Use default theme**) mode in your user settings.
 
-1. Click on the **User Profile** icon in the bottom-left corner of the sidebar.
-2. Under **Theme**, select **Use default theme**.
+1. Click on your **User Profile** icon in the bottom-left corner of the sidebar.
+2. Under **Theme**, select **Backend-selected** (or **Use default theme**).
diff --git a/home_assistant_ios_themes_vi.md b/home_assistant_ios_themes_vi.md
@@ -14,11 +14,8 @@ Hướng dẫn này giúp bạn cài đặt bộ giao diện iOS đẹp mắt, t
 
 ### Cài đặt qua HACS
 
-1. Truy cập **HACS** > **Frontend**.
-2. Tìm kiếm và cài đặt **iOS Themes** ([basnijholt/lovelace-ios-themes](https://github.com/basnijholt/lovelace-ios-themes)).
-3. Truy cập **HACS** > **Integrations**.
-4. Tìm kiếm và cài đặt **Spook** ([frenck/spook](https://github.com/frenck/spook)).
-   - _Lưu ý:_ Spook cung cấp tính năng `input_select.random` cần thiết cho hướng dẫn này.
+1. Trong Home Assistant, mở **HACS**.
+2. Tìm kiếm và tải về **iOS Themes** ([basnijholt/lovelace-ios-themes](https://github.com/basnijholt/lovelace-ios-themes)).
 
 ## 2. Cấu hình hình nền cục bộ (Local Backgrounds)
 
@@ -102,9 +99,11 @@ actions:
       - action: input_boolean.turn_{{ 'on' if trigger.event == 'sunset' else 'off' }}
         target:
           entity_id: input_boolean.ios_themes_dark_mode
-      - action: input_select.random
+      - action: input_select.select_option
         target:
           entity_id: input_select.ios_themes
+        data:
+          option: "{{ state_attr('input_select.ios_themes', 'options') | random }}"
       - stop: Settings updated. Waiting for re-trigger to apply theme.
   - delay: "00:00:01"
   - action: frontend.set_theme
@@ -118,9 +117,11 @@ actions:
 mode: restart
 ```
 
+_Lưu ý: Nếu bạn đã cài đặt Spook, bạn cũng có thể sử dụng `action: input_select.random` thay cho `input_select.select_option`._
+
 ## 4. Kích hoạt Theme trên thiết bị
 
-**Bước quan trọng nhất:** Để automation có thể thay đổi giao diện của bạn, bạn phải chọn chế độ **Use default theme** trong cài đặt người dùng.
+**Bước quan trọng nhất:** Để automation có thể thay đổi giao diện của bạn, bạn phải chọn chế độ **Backend-selected** (hoặc **Use default theme**) trong cài đặt hồ sơ người dùng.
 
 1. Nhấn vào biểu tượng **Hồ sơ người dùng (User Profile)** ở góc dưới cùng bên trái thanh menu.
-2. Tại mục **Theme**, chọn **Use default theme**.
+2. Tại mục **Theme**, chọn **Backend-selected** (hoặc **Use default theme**).