various tidyups

packages/heat_pump_master_bedroom_schedules.yaml

@@ -1,5 +1,57 @@
 ##########################################################################################
-# heat_pump_master_bedroom_schedules.yaml
+# Master Bedroom Heat Pump Schedules
+##########################################################################################
+#
+# TITLE:
+#   Master Bedroom Heat Pump Schedules
+#
+# FILE:
+#   packages/heat_pump_master_bedroom_schedules.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured documentation for schedules, boost, and helper behavior.
+#
+#   V1.0
+#     - Initial master bedroom heat pump schedules and boost controls.
+#
+# PURPOSE:
+#   Provides optional 21:00 start and midnight stop schedules, a combined Night
+#   Power mode, and a manual one-hour boost for the master bedroom heat pump.
+#
+# DEPENDENCIES:
+#   - climate.master_bedroom provides the Panasonic Comfort Cloud heat pump.
+#   - The climate entity must support the "boost" and "none" preset modes.
+#   - packages/heat_pump_master_bedroom_helpers.yaml provides companion
+#     dashboard, setpoint, HVAC mode, profile, and sleep-timer controls.
+#
+# SCHEDULE MODES:
+#   - Night Power Mode turns the heat pump on at 21:00, applies boost for 30
+#     minutes, returns it to the normal preset, and turns it off at midnight.
+#   - 9pm On turns the heat pump on at 21:00 without changing its preset.
+#   - Midnight Off turns the heat pump off at midnight.
+#   - Enabling Night Power disables the separate 9pm On and Midnight Off modes.
+#   - Enabling either separate mode disables Night Power. The separate 9pm On
+#     and Midnight Off modes may be enabled together.
+#
+# MANUAL BOOST:
+#   - script.master_bedroom_boost_1hr applies boost for one hour.
+#   - If the heat pump was off when boost started, it is turned off afterward.
+#   - If it was already running, boost ends by restoring the normal preset and
+#     leaving the heat pump running.
+#
+# INTERNAL STATE:
+#   - input_boolean.master_bedroom_boost_restore_off records whether manual
+#     boost should restore the heat pump to off.
+#   - timer.master_bedroom_boost_timer controls manual and scheduled boost time.
+#
+# OPERATION NOTES:
+#   - The 21:00 and midnight schedules use exact-time triggers.
+#   - There is no startup catch-up if Home Assistant is offline at either time.
+#
 ##########################################################################################
 
 ##########################################################################################