various tidyups

packages/shower_controls.yaml

@@ -1,3 +1,52 @@
+#:########################################################################################:#
+# Main Bathroom Shower Detection Package                                                #
+#:########################################################################################:#
+#
+# TITLE:
+#   Main Bathroom Shower Detection
+#
+# FILE:
+#   packages/shower_controls.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured documentation and automation descriptions.
+#     - Documented current indicator-only usage.
+#
+#   V1.0
+#     - Initial humidity-rate shower detection.
+#
+# PURPOSE:
+#   Detects shower use from the main-bathroom humidity level and its rate of
+#   change, then maintains input_boolean.main_bathroom_shower as an indicator.
+#
+# DEPENDENCY:
+#   sensor.main_bathroom_environment_zth10_humidity_2 provides humidity in %.
+#
+# DERIVATIVE SENSOR:
+#   - Calculates humidity change in % per minute over a 15-minute time window.
+#   - Rounds the result to 0.1.
+#
+# DETECTION:
+#   - Humidity change must remain above 0.6 %/min for five minutes.
+#   - Current humidity must also be above 63%.
+#
+# CLEARING:
+#   - Humidity change must remain below 0.2 %/min for 15 minutes.
+#   - No absolute-humidity condition is required to clear the indicator.
+#   - The gap between activation and clearing thresholds provides hysteresis
+#     and prevents rapid toggling near one threshold.
+#
+# CURRENT USE:
+#   - The package only maintains input_boolean.main_bathroom_shower.
+#   - No other user-YAML automation, script, or package currently consumes it.
+#   - This package does not directly control a bathroom fan or other device.
+#
+#:########################################################################################:#
+
 input_boolean:
   main_bathroom_shower:
     name: Main Bathroom Shower
@@ -14,6 +63,7 @@ sensor:
 automation:
   - id: main_bathroom_shower_detected
     alias: Main Bathroom - Shower detected (humidity rate + min humidity)
+    description: "Turns on the shower indicator after a sustained humidity rise above the minimum humidity."
     mode: single
     trigger:
       - platform: numeric_state
@@ -31,6 +81,7 @@ automation:
 
   - id: main_bathroom_shower_cleared
     alias: Main Bathroom - Shower cleared (humidity rate)
+    description: "Turns off the shower indicator after the humidity change rate remains low for 15 minutes."
     mode: single
     trigger:
       - platform: numeric_state