v0.16.3

docs/API.md

@@ -1,8 +1,10 @@
 # GREE Controller API reference
 
-HTTP and WebSocket API for GREE Controller **0.16.1**.
+HTTP and WebSocket API for GREE Controller **0.16.3**.
 
-Version 0.16.1: Zone configuration exposes `heat_anticipation_c` (0..2.5°C, default 0), runtime Zone exposes `heat_coasting`, and optional Flow `zone_thermostat` node configuration supports `heat_anticipation_c` and `standby_offset_c`. These settings alter the GREE temperature target, not physical power.
+Version 0.16.3: the Flow editor adds localized descriptions and contextual examples for the two heating blocks; the API and heating behavior remain compatible with 0.16.2.
+
+Version 0.16.2: Flow adds the `zone_heat_cycle` action with `zone_id`, `day_target`, `night_target`, `day_min`, `boost_after_minutes` and `day_off_after_minutes`. An always-true Flow condition is sufficient. The Zone runtime stores the active `simple_heat` profile and timers; source `automation.flow` means automatic control, not manual. Nighttime modulation keeps the unit ON and uses 19/21/23 °C around a 20.6 °C target. Daytime power is OFF above the minimum until required, then OFF after 30 minutes at target. Existing `zone_thermostat` coasting options remain supported.
 
 
 [← Main documentation](../README.md)
@@ -246,7 +248,7 @@ Response:
 {
   "status": "ok",
   "name": "gree-controller",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "uptime_seconds": 1234,
   "control_ready": true,
   "time": "2026-08-30T06:54:00Z"
@@ -309,7 +311,7 @@ Returns the initial Web UI snapshot:
   "control_plan": {"generated_at": "2026-09-04T08:00:00Z", "zones": [], "rules": []},
   "control_plan_revision": 42,
   "system": {
-    "version": "0.16.1",
+    "version": "0.16.3",
     "uptime_seconds": 1234,
     "auth_required": false,
     "control_ready": true,
@@ -1734,6 +1736,14 @@ Runtime settings expose `compressor_protection_enabled` and `compressor_protecti
 
 Cancellation suppresses the same pending intent until a new explicit thermostat/group/house command re-arms it, a scheduled Temporary Quick Thermostat session takes ownership, or a different mode/target creates a new intent. Safety OFF commands are not delayed by compressor protection. Direct technical device commands remain immediate manual-control operations.
 
+### Simple two-node heating Flow (0.16.2)
+
+Create a `constant` condition with `{"value":true}` and connect it to a `zone_heat_cycle` action. The action configuration takes `zone_id` (zone UUID), `day_target`, `night_target`, `day_min`, `boost_after_minutes` (3–30) and `day_off_after_minutes` (10–120). Day/night boundaries come from global Night Mode. The generated Flow automation owns an independent per-zone temperature policy; this is **automatic** ownership (`control_source=automation.flow`), not a manual `custom` preset. The measured temperature comes from that zone's configured GREE/HA/combined sensor.
+
+GREE modulation at a night room target of 20.6 °C: 21 °C for a moderate dip, 23 °C for a deep dip or no rise after the configured trial, 20 °C at 20.5 °C in the room, 19 °C at/above 20.6 °C. Nighttime physical power remains ON. During day the indoor unit is OFF while above `day_min`; after falling below it the unit heats and powers OFF after the configured continuous time at `day_target`. Compressor-protection settings still apply. Disabling/removing the Flow clears its thermostat policy on the next zone cycle.
+
+Ready-to-import examples are in `flows/simple-heating/`. Disable older Flow v4 before importing to prevent conflicting rules.
+
 ### Flow portability and diagnostics
 
 `GET /api/flows/:id/export` returns a versioned `gree-controller-flow` JSON document containing the source graph plus definitions of every referenced Shared Input. Generated schedules/automations are not exported. The existing envelope may include an optional top-level `shared_inputs` array while leaving the `flow` object unchanged.

docs/FLOW.md

@@ -97,3 +97,29 @@ These need durable state and restart semantics before they should be exposed in
 ### Display name / alias
 
 The Flow name edited in `/flows` is a presentation alias. Renaming it changes labels shown in the UI (including the dashboard) but does not change the stable Flow ID or generated `flow-<unique-id>` schedule/automation names.
+
+## Proste grzanie dzień/noc (od 0.16.2)
+
+Do jednego pokoju potrzebne są **tylko dwa bloki**: `Stała: Tak` → `Proste grzanie dzień/noc`.
+Blok ustawiasz na odpowiednią strefę oraz:
+
+- `day_target` – komfort w dzień (np. 20.0 °C), `night_target` – komfort w nocy (osobny dla każdego pokoju),
+- `day_min` – próg alarmowy w dzień (np. 19.7 °C); powyżej niego jednostka pozostaje **OFF** dopóki wcześniej nie zaczęła ratunkowego dogrzewania,
+- `boost_after_minutes` – czas próby delikatnego grzania (np. 10 min; Jan: 8 min),
+- `day_off_after_minutes` – czas ciągłego utrzymywania dziennego celu przed wyłączeniem (np. 30 min).
+
+Przebieg (dla celu 20.6 °C): noc: **20.6 °C → GREE 19 °C**, od 20.5 °C wyhamowanie **20 °C**, poniżej tego delikatnie **21 °C**; poniżej 19.8 °C lub po 10 minutach bez wzrostu o 0.1 °C grzanie **23 °C**. Przy celu innego pokoju nastawy GREE zmieniają się proporcjonalnie do celu, z zaokrągleniem do całych stopni. Jednostka pozostaje włączona w nocy (niższa nastawa pozwala jej się samoczynnie uspokoić).
+
+Dzień: przy celu 20.0 °C łagodna faza ustawia GREE na 21 °C, a pełna faza na 22 °C. Nad `day_min` jednostka jest fizycznie wyłączona. Przy spadku poniżej `day_min` podejmuje grzanie; po osiągnięciu `day_target` przez nieprzerwane `day_off_after_minutes` wyłącza jednostkę, z zachowaniem zabezpieczeń sprężarki. Jeśli w tym czasie cel zostaje utracony, odliczanie zaczyna się od nowa.
+
+**Ważne:** Ustawienia > **Tryb nocny** muszą mieć włączony harmonogram i prawidłowe godziny, ponieważ ten sam kalendarz ustala dzień/noc dla wszystkich stref. Temperatura pokoju pochodzi ze skonfigurowanego czujnika termostatu strefy (w tym czujnika HA/combined), a nie z osobnego warunku Flow. Pole `control_source=automation.flow` oznacza automatyczną kontrolę (nie ręczną), również gdy GREE jest w uśpieniu. Rzeczywisty pilot/ręczne sterowanie nadal ma pierwszeństwo.
+
+Gotowe importy: `flows/simple-heating/`. Po imporcie **wyłącz lub usuń oryginalne Flow v4**, żeby uniknąć konkurujących poleceń. Wyłączenie nowego Flow usuwa jego profil sterowania w następnym cyklu regulatora.
+
+### Pomoc w samych blokach (0.16.3)
+
+Po kliknięciu bloku **Stała testowa** edytor wyjaśnia, że wartość **Tak** jest bezwarunkowym sygnałem wejściowym w każdym cyklu, a **Nie** blokuje akcję. W bibliotece bloków oba nowe opisy są widoczne pod nazwami; w palecie i na schemacie pojawiają się jako podpowiedzi po najechaniu.
+
+W bloku **Proste grzanie dzień/noc** opis jest widoczny nad ustawieniami, a sekcja **Jak działa?** rozwija kolejne fazy: nocne uśpienie, hamowanie, delikatne i mocne grzanie, dzienny próg uruchomienia oraz warunek wyłączenia po stabilizacji. Temperatury przykładowe są wyliczane na podstawie rzeczywistych wartości ustawionych w edytowanym bloku, więc Jan, Igor i sypialnia mają poprawne progi. Opis obejmuje też dobór źródła pomiaru w strefie, zachowanie przy braku danych HA i pierwszeństwo sterowania ręcznego.
+
+Ta aktualizacja dotyczy **tylko pomocy UI**. Nie zmienia algorytmu, formatu eksportu Flow ani nastaw trzech wcześniejszych importów; nie trzeba ich ponownie importować.

docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "GREE Controller API",
-    "version": "0.16.1",
+    "version": "0.16.3",
     "summary": "Local HTTP/WebSocket API for GREE Controller",
     "description": "Local API used by the GREE Controller Web UI and Home Assistant integration.",
     "license": {
@@ -6079,7 +6079,7 @@
           },
           "version": {
             "type": "string",
-            "example": "0.16.1"
+            "example": "0.16.3"
           },
           "uptime_seconds": {
             "type": "integer",