docs: capture SIGNAL_NEW_CIRCUITS first-fire requirement and circuit-stuck troubleshooting

CLAUDE.md: warn future contributors not to re-introduce the
`if self._known_circuits and new_circuits` guard, and call out the
class of bug it caused (per-circuit gather exceptions producing a
success=True refresh with an empty circuits dict).

CLAUDE.md: replace stale `targetAirVolume` reference in the fan-speed
fallback chain with `targetValue` — the v3 circuit list field.

README.md: short Troubleshooting section pointing pre-0.14.2 users at
the manual reload, plus the two adjacent failure modes (circuits-list
endpoint failure and stuck auth).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: trcyberoptic

CLAUDE.md

@@ -42,9 +42,9 @@ The integration lives in `custom_components/hoval_connect/`. User setup is email
 - Circuit devices identified by `{plantId}_{circuitPath}`
 - Supports HV (ventilation), HK (heating), BL (boiler), and WW (warm water) circuit types (`SUPPORTED_CIRCUIT_TYPES` in `const.py`)
 - Sensor descriptions use `circuit_types: frozenset[str] | None` to filter which sensors appear on which circuit types (`None` = all types)
-- Fan speed resolution uses smart fallback chain: live airVolume → targetAirVolume → program air volume → default 40% (API rejects value=0)
+- Fan speed resolution uses smart fallback chain: live airVolume → `targetValue` (HV percentage from circuit list) → program air volume → default 40% (API rejects value=0)
 - All entity platforms use `translation_key` for entity names (not hardcoded `_attr_name`)
-- Dynamic entity discovery: all platforms listen to `SIGNAL_NEW_CIRCUITS` dispatcher signal to add entities at runtime without restart
+- Dynamic entity discovery: all platforms listen to `SIGNAL_NEW_CIRCUITS` dispatcher signal to add entities at runtime without restart. The coordinator must dispatch this signal whenever `_known_circuits` grows — *including* the first time circuits appear. Earlier the coordinator gated the dispatch on `if self._known_circuits and new_circuits`, which silently stranded all circuit-level entities if the very first refresh after `async_setup_entry` came back without circuits (e.g. transient `_fetch_circuit` failure swallowed by `gather(return_exceptions=True)`); they stayed `restored=true`/`unavailable` until HA was restarted. Each platform's `_add_new()` already deduplicates via its `known` set, so unconditional dispatch on any new circuit is safe.
 
 ## Running Tests
 
@@ -117,6 +117,7 @@ HK (heating), BL (boiler), WW (warm water), FRIWA (fresh water), HV (ventilation
 ## Known Pitfalls
 
 - `aiohttp.resp.json()` on empty body throws `ContentTypeError` (subclass of `ClientError`) — easily misidentified as connection error in generic exception handlers
+- A coordinator refresh can return `success=True` while `plant_data.circuits` is empty — `_fetch_circuit` exceptions are captured per-circuit by `gather(return_exceptions=True)`, plant-level fetches still succeed. Anything keying off "did the coordinator refresh" rather than "did this specific circuit appear" can drift; the `SIGNAL_NEW_CIRCUITS` dispatcher pitfall above is one consequence.
 
 ## Known Gaps
 

README.md

@@ -69,6 +69,12 @@ Plants and circuits are discovered automatically from your account.
 - Dynamic entity discovery — new circuits added without restart
 - All circuit reads/writes use the `/v3` API (Hoval removed `/v1` circuit endpoints in April 2026); legacy v1 enum values still get normalized to v3 keys as a fallback
 
+### Troubleshooting
+
+- **Circuit entities (fan, climate, select, circuit-level sensors) stuck on "unavailable" after upgrade or HA restart** — reload the config entry: *Settings → Devices & Services → Hoval Connect → ⋮ → Reload*. The plant-level entities (weather, events, online status) staying available while every circuit-level entity is unavailable is the giveaway. Fixed in **v0.14.2** (the dispatcher now catches up if the first poll after boot came back without circuits); earlier versions need the manual reload once.
+- **All entities `unavailable`, with `Circuits endpoint failed for plant …` in the log** — the cloud rejected the circuit list call; usually a transient outage. v0.14.0+ surfaces the failure as `unavailable` rather than silently keeping stale values, so wait for the next poll.
+- **Auth keeps failing** — re-trigger the reauth flow from the integration settings; ID-token caching means a stale password is re-tried for ~30 min before the integration prompts.
+
 ### Known Limitations
 
 - **HV, HK, BL, and WW circuits only.** Solar (SOL), fresh water (FRIWA), and other circuit types are not yet implemented.