Refactor code structure for improved readability and maintainability

Author: asucrews

blueprints/automation/witb_plus_actions_lights_fan/v2/CHANGELOG_witb_plus_actions_lights_fan.md

@@ -5,6 +5,87 @@ Format: `[version] — date — summary`, followed by itemized changes.
 
 ---
 
+## [2.3.1] — 2026-03-03 — Fan Run-On Orphan Fix + Tag Cleanup Blueprint
+
+### Fixed
+- **FIX — CRITICAL: Fan run-on timer orphaned by mode:restart mid-sequence.**
+  The `timer.start` for the fan run-on was previously located *after* the
+  lights verify/retry block in the `lights_off` sequence. Any `mode:restart`
+  kill during verify/retry delays (up to `verify_delay + retries × retry_interval`
+  seconds) would kill the run before the timer started. The fan would stay ON
+  permanently with no timer ever firing to turn it off, and `auto_tag_fan` would
+  remain stuck ON.
+
+  Fix: `timer.start` is now called *before* the verify block, immediately after
+  the first `light.turn_off` command. `timer.start` on an already-running timer
+  is idempotent, so early invocation is safe in all paths. The `timer_finished`
+  handler still owns the actual fan-off.
+
+- **FIX: `auto_tag_lights` stuck ON after mode:restart kill during verify loop.**
+  A restart during the verify delay or retry loop would exit before the tag-clear
+  step, leaving `auto_tag_lights` ON even though lights were off. The tag would
+  then block the next vacancy cycle's `tag_lights_ok_to_off` check until the room
+  re-occupied and went vacant again (resetting the `lights_off` trigger). Addressed
+  by the new companion cleanup blueprint (see Added below).
+
+### Added
+- **Companion blueprint: `witb_plus_actions_cleanup.yaml` v1.0.0.**
+  Belt-and-suspenders automation that catches any remaining `auto_tag_lights` or
+  `auto_tag_fan` stuck-ON states that the main automation could not clear due to a
+  `mode:restart` kill. Inputs mirror the Actions instance for the same room.
+  Key behaviors:
+  - Two independent soak timers: `lights_cleanup_delay` (default 5 min) for the
+    lights tag; `fan_cleanup_delay` (default 20 min) for the fan tag.
+  - Lights tag only cleared when all controlled lights are confirmed OFF.
+  - Fan tag never cleared while `fan_runon_timer` is active — `timer_finished`
+    in the main automation always owns that transition.
+  - Both checks re-confirm vacancy at execution time.
+  - `mode: single` — rapid vacancy/occupy cycles reset the timer cleanly.
+  - Deploy one instance per room alongside the Actions automation.
+
+### Changed
+- Verbose inline `# FIX v2.3.x` and `# v2.3.0:` comment blocks removed from
+  blueprint YAML. Replaced with brief `# See CHANGELOG vX.Y.Z` pointers.
+  All rationale lives here in CHANGELOG instead of cluttering the action sequences.
+
+---
+
+## [2.3.0] — 2026-03-xx — External Gating (Lights + Fan)
+
+### Added
+- **`light_gating_entity`** (optional `binary_sensor`): external gate controlling
+  whether lights may turn ON. Must be ON for lights to assert. Leave empty for
+  no gating (always allow). Replaces the inline lux/sun evaluation that previously
+  lived inside the blueprint. Compute lux threshold, sun elevation, curtain state,
+  seasonal offsets, etc. in a separate automation and expose a single binary sensor
+  — the Actions blueprint just consumes it.
+- **`fan_vacancy_gate_entity`** (optional `binary_sensor`): external gate
+  controlling whether the fan may turn OFF on vacancy. OFF = hold fan on; ON = ok
+  to turn fan off. When this gate transitions ON while the room is already vacant
+  and the fan is still running (and no run-on timer is active), the fan turns off
+  automatically via the new `fan_gate_cleared` trigger. Leave empty for no hold.
+  Replaces the inline humidity polling loop.
+- **`fan_gate_cleared` trigger and action block**: fires when
+  `fan_vacancy_gate_entity` transitions to ON. Guards: room still vacant, fan
+  still running, run-on timer not active (run-on takes precedence).
+- **`lights_ok_to_turn_on`** and **`fan_ok_to_turn_off`** variables: derived
+  from the new gate inputs; used consistently across all affected branches.
+
+### Removed
+- Inline lux threshold inputs (`lux_sensor`, `lux_threshold`) and evaluation logic.
+- Inline humidity hold inputs and the polling `while` loop that held the fan on.
+  Humidity logic now belongs in an external `fan_vacancy_gate_entity` automation.
+
+### Migration
+Existing instances using lux or humidity hold inputs must:
+1. Create a separate automation that evaluates your lux/humidity conditions and
+   writes the result to a `input_boolean` or `template` binary sensor.
+2. Wire that sensor into `light_gating_entity` / `fan_vacancy_gate_entity`.
+3. Remove the now-missing lux/humidity inputs from the old automation instance
+   (HA will warn about unknown inputs on load).
+
+---
+
 ## [2.2.1] — 2026-02-26 — Bed Sensor Integration
 
 ### Added

blueprints/automation/witb_plus_actions_lights_fan/v2/README_witb_plus_actions_lights_fan_v2.md

@@ -3,40 +3,79 @@
 This folder contains the **actions blueprint** that pairs with WITB+ occupancy.
 
 Use this when you already have room occupancy sensors from `witb_plus/v4` (for example
-`binary_sensor.<slug>_occupied_effective`) and want reliable light/fan actions with safety tags.
+`binary_sensor.<slug>_occupied_effective`) and want reliable light/fan actions with
+safety tags, external gating, and automatic tag cleanup.
 
 ---
 
-## 1. Blueprint
-
-**File:** `witb_plus_actions_lights_fan.yaml`
-
-This blueprint controls:
-- Lights (brightness profiles, optional sun/lux gating)
-- Fan (`fan.*` or `switch.*`)
-- Vacancy off behavior with optional fan run-on
-- Optional humidity hold (fan stays on while humidity remains high)
-- Optional startup cleanup for auto-tagged entities
-
-It is intended to be used from the Home Assistant UI via **Create Automation from Blueprint**.
+## 1. Blueprints
+
+### `witb_plus_actions_lights_fan.yaml` — main actions blueprint (v2.3.1)
+
+Controls lights and fan for a single room based on occupancy state changes from
+`binary_sensor.<slug>_occupied_effective`. Key behaviors:
+
+- **Lights ON/OFF** with day/night brightness profiles and optional soft-off dim warning.
+- **Manual-off hold** — if you turn lights off while occupied they stay off until
+  vacancy clears `auto_tag_lights`, then re-arm next occupancy.
+- **Bed suppress** — if someone is in bed and lights are off, motion re-assertion
+  (e.g. midnight bathroom return) does not turn lights back on.
+- **Light gating** — wire an external `binary_sensor` computed from lux, sun
+  elevation, curtains, or season. Blueprint does not evaluate these inline.
+- **Fan ON on occupancy** with optional delay and night-disable mode.
+- **Fan run-on timer** after vacancy, with optional gate to hold the fan on while
+  humidity or other conditions require it.
+- **Fan vacancy gate** — wire an external `binary_sensor` (e.g. humidity threshold).
+  OFF = hold fan on; ON = ok to turn off. When the gate clears while the room is
+  already vacant the fan turns off automatically.
+- **Auto-tag helpers** (`input_boolean`) track automation ownership of lights and fan
+  for safe "only turn off what we turned on" behavior.
+- **Startup cleanup** with double-tap validation after HA restart.
+
+### `witb_plus_actions_cleanup.yaml` — tag cleanup blueprint (v1.0.0)
+
+Belt-and-suspenders companion that catches `auto_tag_lights` and `auto_tag_fan`
+helpers stuck ON after a `mode:restart` kill mid-sequence in the main automation.
+Deploy **one instance per room** alongside the main Actions instance.
+
+- Two independent soak timers fire after vacancy: lights check (default 5 min),
+  fan check (default 20 min).
+- Lights tag only cleared when all controlled lights are confirmed OFF.
+- Fan tag never cleared while `fan_runon_timer` is active.
+- Both checks re-confirm vacancy at evaluation time.
+- Inputs mirror the main Actions instance — wire the same entities.
+
+See `CHANGELOG_witb_plus_actions_lights_fan.md` for full fix rationale.
 
 ---
 
-## 2. Package Helpers (helpers only)
+## 2. Package Helpers
 
-**Reference template:** `room_witb_actions_package_template.yaml`  
+**Reference template:** `witb_plus_actions_lights_fan_package_template.yaml`  
 **Generated output location:** `packages/`
 
 Package files provide helper entities such as:
-- `input_boolean.<slug>_auto_lights_on`
-- `input_boolean.<slug>_auto_fan_on`
-- `timer.<slug>_actions_cooldown`
-- `timer.<slug>_fan_runon`
-- `input_datetime.<slug>_actions_night_start`
-- `input_datetime.<slug>_actions_night_end`
-- Optional `input_number` tuning helpers (brightness, fan %, lux threshold, humidity thresholds, fan delay)
 
-Load these packages with:
+| Entity | Purpose |
+|---|---|
+| `input_boolean.<slug>_auto_lights_on` | Auto-tag for lights ownership |
+| `input_boolean.<slug>_auto_fan_on` | Auto-tag for fan ownership |
+| `input_boolean.<slug>_keep_on` | Blocking entity — prevents vacancy off |
+| `timer.<slug>_actions_cooldown` | ON-debounce cooldown timer |
+| `timer.<slug>_actions_fan_runon` | Fan run-on countdown timer |
+| `input_datetime.<slug>_actions_night_start` | Night window start |
+| `input_datetime.<slug>_actions_night_end` | Night window end |
+| `input_number.<slug>_actions_brightness_day_pct` | Day brightness % |
+| `input_number.<slug>_actions_brightness_night_pct` | Night brightness % |
+| `input_number.<slug>_actions_fan_pct_day` | Fan speed % day |
+| `input_number.<slug>_actions_fan_pct_night` | Fan speed % night |
+| `input_number.<slug>_actions_fan_runon_minutes` | Fan run-on duration |
+| `input_number.<slug>_actions_fan_on_delay_seconds` | Fan ON delay |
+| `binary_sensor.<slug>_actions_cooldown_active` | Cooldown active indicator |
+| `binary_sensor.<slug>_actions_fan_runon_active` | Fan run-on active indicator |
+| `binary_sensor.<slug>_actions_in_night_window` | Night window indicator |
+
+Load packages with:
 
 ```yaml
 homeassistant:
@@ -47,26 +86,22 @@ homeassistant:
 
 ## 3. Generator Script
 
-**File:** `generate_witb_plus_actions_packages_templated.py`
-
-The script generates helper package YAML files only.  
-It does **not** generate automations.
+**File:** `generate_witb_packages_templated.py`
 
-Example:
+Generates per-room helper package YAML files from the template. Does **not**
+generate automations — those are created from blueprints in the HA UI.
 
 ```bash
-python3 generate_witb_plus_actions_packages_templated.py \
+# Generate packages for specific rooms
+python3 generate_witb_packages_templated.py \
   --rooms "Office" "Master Bathroom Toilet" \
-  --template room_witb_actions_package_template.yaml \
+  --template witb_plus_actions_lights_fan_package_template.yaml \
   --out ./packages
-```
-
-Dry run:
 
-```bash
-python3 generate_witb_plus_actions_packages_templated.py \
+# Dry run to preview output
+python3 generate_witb_packages_templated.py \
   --rooms "Office" \
-  --template room_witb_actions_package_template.yaml \
+  --template witb_plus_actions_lights_fan_package_template.yaml \
   --out ./packages \
   --dry-run
 ```
@@ -75,17 +110,53 @@ python3 generate_witb_plus_actions_packages_templated.py \
 
 ## 4. Typical Setup Flow
 
-1. Create room occupancy with `witb_plus/v4`.
-2. Generate helpers into `packages/`.
-3. Reload/restart Home Assistant so helpers exist.
-4. Create an automation from `WITB+ Actions - Lights + Fan`.
-5. Bind `occupied_effective` to `binary_sensor.<slug>_occupied_effective`.
-6. Bind lights/fan entities and optional helper inputs.
+1. Run `witb_plus/v4` blueprint for the room to get `binary_sensor.<slug>_occupied_effective`.
+2. Generate helpers via the script and reload/restart HA so all helpers exist.
+3. Create an automation from **WITB+ Actions - Lights + Fan** and wire:
+   - `occupied_effective` → `binary_sensor.<slug>_occupied_effective`
+   - `auto_tag_lights` → `input_boolean.<slug>_auto_lights_on`
+   - `auto_tag_fan` → `input_boolean.<slug>_auto_fan_on`
+   - `cooldown_timer` → `timer.<slug>_actions_cooldown`
+   - `fan_runon_timer` → `timer.<slug>_actions_fan_runon`
+   - `night_start_helper` / `night_end_helper` → corresponding `input_datetime` helpers
+   - Brightness and fan % helpers → corresponding `input_number` helpers
+   - `light_gating_entity` → your external lux/sun gate sensor (optional)
+   - `fan_vacancy_gate_entity` → your external humidity gate sensor (optional)
+4. Create a second automation from **WITB+ Actions Tag Cleanup** for the same room,
+   wiring the same lights, fan, tags, and timers. Use `mode: single`.
+5. Verify in Developer Tools → Template that the `occupied_effective` sensor
+   transitions correctly before testing lights/fan behavior.
+
+---
+
+## 5. Architecture Notes
+
+**Why two blueprints (occupancy + actions)?**  
+WITB+ deliberately separates *occupancy inference* (WITB+ v4) from *action
+orchestration* (Actions). This allows multiple action automations to subscribe
+to the same occupancy sensor independently, and keeps each blueprint focused on
+one concern.
+
+**Why external gating (v2.3.0+)?**  
+Lux evaluation and humidity hold logic were removed from the Actions blueprint
+in v2.3.0. These belong in dedicated automations that write their verdict to a
+binary sensor. This keeps Actions simple and testable — you can force the gate
+ON/OFF manually in the UI to test lighting behavior independently of ambient
+conditions.
+
+**Why a cleanup blueprint (v2.3.1+)?**  
+`mode:restart` is the correct mode for an event-driven automation — it prevents
+stale queued runs from accumulating. The tradeoff is that any run killed mid-
+sequence cannot clean up after itself. The cleanup blueprint handles this with a
+time-delayed soak check that is safe, idempotent, and never turns anything off —
+it only clears boolean tags.
 
 ---
 
 ## Summary
 
-- **WITB+ v4** handles occupancy inference.
-- **WITB+ Actions** handles light/fan behavior.
-- **Package files** provide helper entities for safe automation behavior and dashboard tuning.
+| Blueprint | Role | Instance count |
+|---|---|---|
+| `witb_plus/v4` | Occupancy inference | One per room |
+| `witb_plus_actions_lights_fan` | Light + fan control | One per room |
+| `witb_plus_actions_cleanup` | Tag stuck-ON recovery | One per room |