v0.8.4

docs/API.md

@@ -136,12 +136,20 @@ curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: appl
 
 # Run Quick Thermostat for 90 minutes, then hand control back to automation.
 curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
-  -d '{"temporary_quick_thermostat":{"finish_kind":"duration","duration_minutes":90,"target_temperature":23.0}}'
+  -d '{"temporary_quick_thermostat":{"start_kind":"now","finish_kind":"duration","duration_minutes":90,"target_temperature":23.0}}'
+
+# Schedule Quick Thermostat to start in 45 minutes and run for two hours.
+curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"temporary_quick_thermostat":{"start_kind":"delay","start_delay_minutes":45,"finish_kind":"duration","duration_minutes":120,"target_temperature":23.0}}'
+
+# Schedule an absolute start. All timestamps are ISO-8601 and are stored as UTC internally.
+curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"temporary_quick_thermostat":{"start_kind":"at","start_at":"2026-08-28T18:30:00+02:00","finish_kind":"until","until":"2026-08-28T22:00:00+02:00","target_temperature":23.0}}'
 
 # Hold 23 C continuously for one hour. Leaving the +/-0.3 C band resets the hold timer.
 # The optional safety limit hands control back after four hours even if the condition never settles.
 curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
-  -d '{"temporary_quick_thermostat":{"finish_kind":"temperature_stable","target_temperature":23.0,"temperature_operator":"within","tolerance_c":0.3,"hold_minutes":60,"max_duration_minutes":240}}'
+  -d '{"temporary_quick_thermostat":{"start_kind":"now","finish_kind":"temperature_stable","target_temperature":23.0,"temperature_operator":"within","tolerance_c":0.3,"hold_minutes":60,"max_duration_minutes":240}}'
 
 # Cancel only the temporary Quick Thermostat session and return to the previous automation state.
 curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
@@ -152,7 +160,7 @@ curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: appl
 
 `power:true/false` on `/api/zones/{id}/control` is a local quick-thermostat power override, not a physical/manual command. `true` lets that zone run through the full thermostat even when its climate group is off and cancels any pending local hand-back timer. Every accepted `false` action turns only that zone off immediately and creates a fresh backend-owned `local_thermostat_resume_at` 15 minutes in the future. When that deadline is reached, the controller clears local quick ownership plus its temporary quick preset/setpoint and recalculates the current group/schedule/house-mode state instead of restoring an old physical ON/OFF snapshot. `clear_local_thermostat_override:true` performs that hand-back immediately. Direct/pilot-style control remains `/api/devices/{id}/command`.
 
-`temporary_quick_thermostat` is a separate persisted session and does **not** reuse `local_thermostat_resume_at`. Supported `finish_kind` values are `duration`, `until`, `temperature_reached`, `temperature_stable`, and `schedule_boundary`. Temperature rules support `within`, `at_or_below`, and `at_or_above`, a tolerance, an optional safety deadline, and for `temperature_stable` a continuous hold duration. If the zone automation was disabled before the session, the session temporarily enables thermostat control and restores the disabled state when it finishes.
+`temporary_quick_thermostat` is a separate persisted session and does **not** reuse `local_thermostat_resume_at`. `start_kind` accepts `now`, `delay`, or `at`; delayed sessions keep normal schedules and automations active until `started_at`, then acquire local thermostat ownership. Supported `finish_kind` values are `duration`, `until`, `temperature_reached`, `temperature_stable`, and `schedule_boundary`. Durations and safety limits begin at the effective start, not when a delayed session is created. `schedule_boundary` resolves the first schedule transition after the effective start. Temperature rules support `within`, `at_or_below`, and `at_or_above`, a tolerance, an optional safety deadline, and for `temperature_stable` a continuous hold duration. While active, the temporary target has priority over schedule transitions and normal device/group automations; those sources resume after hand-back. If the zone automation was disabled before the session, the session temporarily enables thermostat control and restores the disabled state when it finishes.
 
 ### Physical/manual device takeover