v0.14.13

docs/API.md

@@ -1,6 +1,6 @@
 # GREE Controller API reference
 
-HTTP and WebSocket API for GREE Controller **0.14.12**.
+HTTP and WebSocket API for GREE Controller **0.14.13**.
 
 [← Main documentation](../README.md)
 
@@ -197,7 +197,8 @@ Common statuses:
 | GET/PUT | `/api/settings/debug` | Debug overlay/GREE frame settings. |
 | GET | `/api/configuration/export` | Export full application configuration. |
 | POST | `/api/configuration/import` | Import/replace application configuration. |
-| POST | `/api/integrations/home-assistant/test` | Test HA server/API authentication without requiring an entity. |
+| POST | `/api/integrations/home-assistant/test` | Test the active HA authentication path and return one live sample entity reading when available. |
+| GET | `/api/integrations/home-assistant/entities` | Compact Home Assistant entity catalog used by searchable Shared Flow input suggestions. |
 | POST | `/api/integrations/home-assistant/entity` | Read raw HA entity state/attributes for shared Flow input diagnostics. |
 | POST | `/api/integrations/notifications/test` | Send a test notification. |
 
@@ -233,7 +234,7 @@ Response:
 {
   "status": "ok",
   "name": "gree-controller",
-  "version": "0.14.12",
+  "version": "0.14.13",
   "uptime_seconds": 1234,
   "control_ready": true,
   "time": "2026-08-30T06:54:00Z"
@@ -296,7 +297,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.14.12",
+    "version": "0.14.13",
     "uptime_seconds": 1234,
     "auth_required": false,
     "control_ready": true,
@@ -1198,7 +1199,7 @@ Times must use `HH:MM`; maximum fan speed is clamped to `1..5`.
 }
 ```
 
-`auth_mode` is runtime-only: `manual` for standalone installations and `supervisor` for the Home Assistant add-on. In Supervisor mode the returned URL is `http://supervisor/core/`, authentication uses runtime `SUPERVISOR_TOKEN`, and `PUT` does not replace the stored standalone URL/token fields. In manual mode, `PUT` replaces `token_configured` with optional `token`. Omitted/`null` token preserves the saved token; an explicit empty string clears it. `outdoor_entity_id` is the optional global Home Assistant outdoor-temperature sensor. Each zone can set `ha_outdoor_entity_id` to override that source only for the zone; a blank override uses the global sensor. Home Assistant room-temperature sensors remain configured per zone with `ha_entity_id` when `sensor_source` is `home_assistant` or `combined`. Sensor age is clamped to `30..86400` seconds. URLs, aliases, entity IDs and shared Flow inputs are normalized/validated before persistence. Global/per-zone outdoor sensors and per-zone room sensors are exposed through the normal alias and sensor-history/metric surfaces, and the Web UI offers them as suggestions in Flow Home Assistant entity fields. Shared inputs are value sources only; comparison operators and thresholds belong to Flow nodes. The Home Assistant connection test validates only the server/API token and requires no entity.
+`auth_mode` is `manual` for standalone installations and normally `supervisor` for the Home Assistant add-on. The add-on detects the Supervisor environment and runtime `SUPERVISOR_TOKEN`; while Supervisor auth is active, the effective URL is `http://supervisor/core/` and the Web UI hides manual URL/token/TLS fields. `supervisor_detected`, `supervisor_token_detected`, `manual_url`, `manual_token_configured` and `manual_auth_override` describe that state without exposing secrets. If the automatic HA test fails, the UI unlocks the persisted manual URL/token fallback; saving it sets `manual_auth_override=true`. Standalone URL/token behavior is unchanged. Omitted/`null` token preserves the saved manual token; an explicit empty string clears it. `outdoor_entity_id` is the optional global Home Assistant outdoor-temperature sensor. Each zone can set `ha_outdoor_entity_id` to override that source only for the zone; a blank override uses the global sensor. Home Assistant room-temperature sensors remain configured per zone with `ha_entity_id` when `sensor_source` is `home_assistant` or `combined`. Sensor age is clamped to `30..86400` seconds. URLs, aliases, entity IDs and shared Flow inputs are normalized/validated before persistence. Global/per-zone outdoor sensors and per-zone room sensors are exposed through the normal alias and sensor-history/metric surfaces. Shared Flow input HA sources can query `/api/integrations/home-assistant/entities` for live searchable entity suggestions. Shared inputs are value sources only; comparison operators and thresholds belong to Flow nodes.
 
 ### `/api/settings/debug`
 
@@ -1270,14 +1271,25 @@ Response:
 
 ### `POST /api/integrations/home-assistant/test`
 
-No request body is required. The endpoint validates the configured Home Assistant URL and access token against the Home Assistant API root; it does not read or require any entity. Response:
+No request body is required. The endpoint validates the active Home Assistant authentication path and reads the state registry. In the packaged add-on it uses Supervisor auth unless manual fallback is active. A successful response includes one readable entity sample when available, which the Web UI shows in the success toast:
 
 ```json
 {
-  "ok": true
+  "ok": true,
+  "auth_mode": "supervisor",
+  "sample": {
+    "entity_id": "sensor.living_room_temperature",
+    "name": "Living room temperature",
+    "state": "22.4",
+    "unit": "°C"
+  }
 }
 ```
 
+### `GET /api/integrations/home-assistant/entities`
+
+Returns a compact entity catalog for authenticated Web UI suggestions. Each row contains `entity_id`, friendly `name`, current `state`, `unit` and `device_class`. When HA is not configured it returns `configured: false` with an empty list.
+
 ### `POST /api/integrations/home-assistant/entity`
 
 Reads the current raw Home Assistant entity document used by the shared-Flow-input diagnostics UI.