v0.4.4

docs/API.md

@@ -176,12 +176,30 @@ curl "$BASE/lang/en.json"
 
 ### `GET /api/history`
 
-Returns rich per-zone climate history. Query parameters:
+The history API exposes three independent data families and a combined overview. Common parameters are `hours=6|24|168|720` and `limit` up to 20,000 rows. Downsampling is performed in SQLite: 30-second buckets up to 6 hours, 2-minute buckets up to 24 hours, 10-minute buckets up to 7 days, and 30-minute buckets for longer ranges.
 
-- `zone_id=<zone id>` for one zone, or `zone_id=all` for all zones,
-- `hours=6|24|168|720`,
-- `limit` up to 20,000 rows.
+```text
+GET /api/history?scope=overview&hours=24
+GET /api/history?scope=devices&device_id=DEVICE_ID&hours=24
+GET /api/history?scope=zones&zone_id=ZONE_ID&hours=24
+GET /api/history?scope=sensors&entity_id=sensor.room_temperature&hours=24
+```
 
-Each row contains `gree_temperature`, `external_temperature` (HA room sensor), `control_temperature`, `target_temperature`, `device_setpoint`, `outdoor_temperature`, `power`, `mode`, `fan_speed`, `demand`, `control_source`, and `active_preset`.
+`scope=overview` returns:
 
-The endpoint automatically downsamples in SQLite to keep charts responsive: 30-second buckets up to 6 hours, 2-minute buckets up to 24 hours, 10-minute buckets up to 7 days, and 30-minute buckets for longer ranges.
+```json
+{
+  "scope": "overview",
+  "bucket_seconds": 120,
+  "zones": [],
+  "devices": [],
+  "sensors": [],
+  "counts": {"devices": 0, "zones": 0, "ha": 0}
+}
+```
+
+Device rows come from the existing `readings` table and contain `indoor_temperature`, optional GREE `outdoor_temperature`, `target_temperature`, `power`, and `source`. This makes old device history immediately available after an upgrade.
+
+Zone rows contain `gree_temperature`, `external_temperature` (HA room sensor), `control_temperature`, `target_temperature`, `device_setpoint`, `outdoor_temperature`, `power`, `mode`, `fan_speed`, `demand`, `control_source`, and `active_preset`. If a zone has no rich samples yet, the API falls back to that zone's existing GREE device readings instead of returning an empty timeline.
+
+Sensor rows contain `entity_id`, optional `zone_id`, `kind` (`room` or `outdoor`), `timestamp`, and `temperature`. New HA samples start being collected after the upgrade; where older rich zone samples contain the same HA values, the API can expose them as compatibility history.

docs/PROJECT_SPEC.md

@@ -175,7 +175,7 @@ The zone controller supports `device`, `combined`, and `home_assistant` temperat
 - Every SQLite statement and schema definition is centralized in `src/queries.rs`; database/domain code must not embed SQL strings elsewhere.
 
 
-## Web UI design system (v0.4.3)
+## Web UI design system (v0.4.4)
 
 The embedded UI uses the classic GREE Controller visual language: large rounded surfaces, circular thermostat controls, comfortable spacing, compact desktop navigation and mobile bottom navigation. Light, Dark and System themes use neutral surfaces with a restrained green accent.
 
@@ -184,3 +184,11 @@ The UI ships as a normal static `web/styles.css` file embedded into the Rust bin
 ### Rich zone history
 
 Zone history stores GREE temperature, optional Home Assistant room temperature, calculated control temperature, profile target, actual device setpoint, outdoor temperature assist, power, mode, fan speed, demand, active preset and control source. The UI can compare all zones on common temperature/target charts or inspect one zone in detail.
+
+### History information architecture (v0.4.4)
+
+History is not a single long page. It is split into URL-addressable views: Overview, Zones, GREE devices, HA sensors and Custom chart. Device history exists independently from zones, HA sensors have their own history stream, and zone history adds the thermostat/control context. A compatibility fallback maps existing GREE device readings into a zone timeline when the richer zone table is still empty.
+
+The custom chart composer can mix GREE indoor/outdoor/target values, zone GREE/HA/control/target/device-setpoint/outdoor values, and HA temperature entities. Saved definitions persist in browser storage and a chart definition can be serialized into the `/history/custom?chart=...` URL for direct sharing/bookmarking.
+
+Quick thermostat temperature nudges are optimistic in the browser and stored separately from the selected Comfort/Sleep/Away/Auto preset. Changing `+/-` therefore does not silently leave Auto mode.