UX-13 P2 review fixes (PR #145, comment 1880)

1. Discard reloads /config/model: after a stale save the page kept the
   new fingerprint with the old values, so Discard + Save overwrote the
   other surface's change without a 409.
2. Removing cards back to one restores the stored inverter shape, so a
   flat site stays flat after add + remove.
3. A choice the page can only keep ("Other time windows") stays offered
   while it is the stored value.
4. A load locks every locked value again.
5. at_zero() needs an accepted 0 W write; before the first one Home says
   "Going to 0 W" (the heartbeat writes every heartbeat_s, so it clears).
6. A field with a unit drops the translation's "(W)" from its label: the
   peak limit read "Peak limit (W)" beside a kW value.
7. A mirrored choice lists the mirrored field's keys, so a search for
   static_profile finds the contract on a fixed-price site.
8. test_settings: a save refused by ui_to_options writes nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitea/infra-pin

@@ -1,2 +1,2 @@
 # The admin/goodwe commit CI tests against. Bump: set to the full SHA of admin/goodwe release/1.0 HEAD (README.md, "CI and the infra pin").
-7081df4276ad3cf788355b97a3b3f40ea28d72bd
+d637d0b1b13f1b863dc47e445e2ca4cf4a82fe10

STYLE.md

@@ -7,7 +7,8 @@ This applies to everything a home owner or installer reads: notifications, phone
 - **Body**: **one sentence** of at most 25 words, saying what happened and what to do. A **red alarm** may use up to **3 sentences** (70 words, each sentence at most 30 words), so that no action a person must take is lost.
 - **Details**: the last line links to the add-on documentation and names the section with the rest: `Details: add-on documentation, section "<title>" under Notifications.` Background, figures, reason codes and history go there or into the log, never into the body.
 - **Status row**: one sentence of at most 15 words. A **red** row may use up to 3 sentences (30 words), like a red alarm. It shows the live numbers the reader acts on and never an HA entity id. **Banner**: at most 12 words. **Refusal**: at most 30 words, naming the setting by its label and then its key, as `messages.setting()` writes it: “Inverter rating” (max_w), or “Inverter rating” for inverter-b (inverters.max_w) for one inverter in the list. **Option name**: at most 6 words, not counting the group prefix. **Option description**: at most 30 words. Where a value comes from belongs in DOCS.md.
-- **Log line** (WARNING/ERROR): one line, at most 25 words, with the numbers that matter. The reasoning goes on a DEBUG line. Log lines stay in English and are not translated. A reason text a line quotes (`%s`) keeps its own codes, because that is the evidence an installer searches for.
+- **Plan line** (UX-13 Home screen: the plan, tooltips, a battery's "now" line): at most 2 sentences, each at most 12 words. Words from `app/homeview.py`, checked by `test_messages.py` part 8.
+- **Log line** (WARNING/ERROR): one line of at most 25 words **as logged**, with any built text filled in. Log lines stay in English and are not translated. A line that reports a safety reason gives one plain sentence and the reason's code (`STALE_READING`, `OUTPUT_CLAMP`), the evidence an installer searches for. The reason itself, with its figures and limits, goes on a DEBUG line right after it and into the action log, never onto the WARNING/ERROR line. It keeps the shape of a red alarm: at most 3 sentences of at most 30 words. The line as logged has no semicolon, banned word, capitals, "1 times" or "(s)". `test_messages.py` part 6 builds every such text with the real code and checks it, and lists the few non-safety families still over 25 words. A line that repeats every cycle is DEBUG. INFO lines carry no section numbers, ISO timestamps or capitals.
 - **Refusal length is counted as shown**: a setting placeholder counts as its label and key, and the long cases are driven through the validator (`test_messages.py` part 3).
 - **Event line** under the buttons: the plain words of `messages.hint()`, like a green row. The add-on's own action log stays technical and is not shown on the page. Installers read it as `events` in the `status` JSON.
 - **Sentences**: one idea each, active voice, present tense, with nothing nested in brackets and no semicolons (a semicolon is a second sentence in disguise). These translate well into Dutch and French.

goodwe_controller/DECISIONS/SAFETY-52-a-battery-that-refuses.md

@@ -0,0 +1,110 @@
+# SAFETY-52 - a battery that refuses is asked for 0 W
+
+**Decided 2026-09-27 by the owner, on the phase A plan (option D3). All four
+questions answered yes.**
+
+## The defect
+
+At the BMS cut-out the battery gives ~0 W whatever it is asked. The saturation
+freeze (`control.py`, `frozen`) then holds the request where it stood, and its
+SAFETY-13 exit cannot fire, because a reading of ~0 against a large ask lies
+inside the interval a limit can produce. The request stood at +5000 W for
+11.87 h on 2026-09-06 and at +1940 W for 3 h 55 m on the bus on 2026-09-19. It
+moved again only when the grid error changed sign. SAFETY-48's lead cap only
+changes where `i_w` parks (one slew step ahead instead of at the rail). When
+the request moved after the reading went flat, the stale-reading gate won
+instead and ran SAFETY-59's ~70 s trip cycle.
+
+## What was decided
+
+1. **A refused direction is held at 0 W**, reason `battery refuses`. It engages
+   in `compute()` when the freeze has held `SETTLE_CYCLES` and the reading is
+   below `REFUSED_BELOW_W` (100 W, the probe's own answer) against an ask beyond
+   `saturation_w`. The drop to 0 skips
+   the slew limit (it only removes an ask nobody meets). The direction is
+   carried like `sat_count` (`refused=`, `Decision.refused`).
+2. **A 200 W probe every 15 minutes, 34 s long** (`PROBE_W`, `PROBE_EVERY_S`,
+   `PROBE_S`; twice `BATT_OBLIGED_S`). A reading of at least 100 W in the held
+   direction ends the refusal, during a probe or not. 200 W is below `freshness.MOVE_W` (250 W), so a probe cannot arm
+   the gate. The clock is main.py's `now_mono`; `compute()` stays clockless.
+3. **A gate trip while the loop is frozen on a ~0 W reading is a refusal** for
+   control (`Controller._refusal_from_stale`). This is what stops the ~70 s
+   cycle. The log keeps SAFETY-56's two-explanation wording.
+4. **No SoC in the loop.** SAFETY-25 Option A stands. Nothing reads SoC.
+
+Other exits: the loop wants the other direction (charge is accepted at the
+floor), control stopped or started, another writer on the wire (the arbiter
+reseed). A gap in the readings keeps the refusal, because the gate's own stop is
+what seeds it.
+
+**One inverter only.** At N>1, OPT-09's `pack` limit already closes an empty
+battery's discharge end and moves its share. There, a one-unit gate trip must
+not refuse the site. `compute()` is passed `refused=None` there, and that path
+is release/1.0's law unchanged (the `i_w=None` equivalence sweep in
+`test_control.py` still holds).
+
+## Evidence
+
+`test_refusal.py` drives the real Controller and gate (the 09-06 and 09-19
+shapes, recovery with no sign change, the probe cadence, every exit).
+`tools/replay_refusal.py` replays the 16-day capture, same model as
+`replay_recorded_loop.py`, and should be read for deltas:
+
+| plant | law | gate trips | request >1 kW above delivery | longest held | import / export kWh | worst 15-min |
+|---|---|---|---|---|---|---|
+| fitted | old | 85 | 113.3 h | 16.57 h | 112.0 / 35.2 | 3434 W |
+| fitted | new | 130 (133 after review) | 11.4 h | 0.21 h | 112.3 / 35.4 | 3456 W |
+| offset 0 W | old | 1010 | 102.2 h | 16.58 h | 112.0 / 35.2 | 3434 W |
+| offset 0 W | new | 85 | 6.1 h | 0.33 h | 111.9 / 35.1 | 3434 W |
+
+**Traced in review (#141).** The +22 W worst quarter is the old law's worst
+quarter too. There the old law stands at +2060 W on a pack giving 0 W, and the
+new law asks 0 W, which the fitted plant answers with its -22 W offset: 22 W
+charged from the grid. The fit above the floor reads `batt = cmd - 28 W`, so a
+real inverter asked 0 W may do the same. Of the 71 new-law trips with no
+old-law trip within 2 min, 59 come 85-97 s after an answered probe. The offset has lifted the modelled pack
+just above its floor, the probe is answered, control ramps, the pack empties
+again mid-ramp, and the gate trips, which re-seeds the hold. The other 12
+follow an other-direction exit the same way. On a site this is one
+`STALE_READING` ERROR line per answered probe at most, and only on a battery
+that answers a probe and then cuts out again. Catching the re-cut before the
+gate needs a faster engage than `SETTLE_CYCLES`, which accuses a healthy slow
+battery, so it is left to SAFETY-58/59. After the review changes below the
+fitted-plant row reads 133 trips (the delivery exit now also catches answers
+that arrive after the probe window); the other figures are unchanged. Rejected alternatives and their figures are in
+the phase A plan: bounding the integrator by demand made the worst quarter
++541 W worse or cycled the gate 3368 times, and an SoC envelope needs the
+configured floor to be right and needs SoC.
+
+## Review changes (#141)
+
+- **"Gives nothing" is below 100 W, not below 500 W.** At `saturation_w` a
+  battery derated to 100-499 W (cold, a tapering battery) was held at 0 W for
+  ~93 % of the time: 300 W derated gave 86 Wh in 4 h against 1 200 Wh on the
+  old law. The capture has 0.11 h in that band, so the replay does not move.
+- **Any delivery ends the hold, not only an answered probe.** With
+  `meter_poll_s: 1` the 12 cycles last 12 s, less than a healthy battery's
+  reading lag (up to `BATT_OBLIGED_S`, 17 s). That engaged on a healthy step and
+  held it for 15 min. Now the late reading ends it within seconds (2 s held in
+  `test_refusal.py` part 5b).
+- **N>1 is stated as a limit in DOCS.** The pack limit there covers an empty
+  battery only when its cut-out level is configured right.
+
+## Not covered
+
+A battery that gives a steady part of the ask (e.g. a 500 W keep-alive) is a
+genuine limit (SAFETY-13 case a) and still holds its request.
+
+## What SAFETY-58 and SAFETY-59 must take into account
+
+- **SAFETY-58** (the first read after a rest trips at once): a probe never arms
+  the gate (200 < 250 W), but the refusal seeding reads the trip. If 58 delays
+  the first verdict, the seed arrives later. The 09-19 shape then needs the
+  compute-side engagement (12 cycles) to win, which it does only while the
+  request stands still. Keep `test_refusal.py` part 4 green.
+- **SAFETY-59** (DOCS says a ~70 s pattern proves a failed register): with this
+  change a refusing battery no longer produces the pattern at one inverter. The
+  DOCS text should say so, and that the `battery refuses` reason is the
+  discriminator the add-on now has. At N>1 the old pattern can still occur.
+- If either changes `MOVE_W`, `PROBE_W` must stay below it.
+  `test_refusal.py` part 2 checks the inequality.

goodwe_controller/DECISIONS/SAFETY-73-refusal-per-inverter.md

@@ -0,0 +1,104 @@
+# SAFETY-73 - a battery that refuses, with two or more inverters
+
+**Decided 2026-09-27 by the owner, on the phase A plan (option R). All four
+new questions answered yes. SAFETY-52's four decisions carry over.**
+
+## The defect
+
+SAFETY-52 held a refusing battery at 0 W at one inverter only. At N>1
+(`main.py` passed `refused=None`) nothing closed a unit that gives ~0 W while
+its state of charge reads above its configured cut-out, so the allocator kept
+handing it its weighted half. Measured on the real `Controller`, two units,
+house 3000 W, A cut out:
+
+| register | law | B gives | grid | A's gate trips / h |
+|---|---|---|---|---|
+| flat -4 W | old | 533 W | +2471 W | 46 (each stops the whole site) |
+| flat -4 W | new | 2000 W (its rating) | +1004 W | 1 |
+| jitter | old | 1910 W | +1094 W | 0 |
+| jitter | new | 2000 W | +1004 W | 0 |
+
+House 1200 W, which B alone carries: old +671 W (flat) and +284 W (jitter)
+standing import, new -16 W. Both cut out: old keeps asking two empty batteries
+(+1910 W each on the jitter shape), new holds the site at 0 W.
+
+## What was decided
+
+1. **A refusing unit is closed in that direction** by its own P_SAFETY unit
+   claim, source `refused`. It engages when the unit gives under
+   `REFUSED_BELOW_W` (100 W) for `SETTLE_CYCLES` (12) cycles, spanning at least
+   `REFUSED_SPAN_S` (22 s), in one direction while asked more than `PROBE_W`
+   (200 W), or when its stale-reading gate
+   trips on a held reading under 100 W. The allocator then hands its share to
+   the others within their own limits (owner decision 1). It is a hard unit
+   limit that always intersects, so OPT-11's P_MODE layer fits inside it.
+2. **It binds every strategy's ask on that unit** (decision 2): peak guard,
+   arbitrage and maintenance are placed around it like the loop.
+3. **A refusal to give power above the configured cut-out** logs INFO plus one WARNING ending
+   in `REFUSES_ABOVE_CUT_OUT` (decision 3). SAFETY-42/43 no longer report such a
+   unit: its share is 0 W, and `account()` treats it as parked.
+4. **All units refusing the same way** pass that sign to `compute()`, so the
+   site holds 0 W with SAFETY-52's law (decision 4). Probes go one unit at a
+   time.
+5. **Probe:** every 15 min for 34 s the claim becomes a pin at +-200 W and the
+   others carry the rest. The pin stands only while the resolved site target
+   asks at least 200 W its way; otherwise it would make a sibling take the
+   opposite direction, so it falls back to the closed limit for that cycle.
+6. **Exits:** a reading of 100 W or more in the held direction (probe or not);
+   100 W or more taken the other way for 12 cycles (charge at the floor; one
+   cycle of the loop overshooting through zero is not enough); stop or start.
+   On every exit the site target and integrator restart from the watts on the
+   wire, or the reopened unit is handed a parked remainder at once.
+
+**Why 200 W and not `saturation_w`.** A unit's share is often small: a 400 W
+night load split two ways asks 200 W of each. With 500 W the empty battery
+kept a phantom share that SAFETY-43's relative arm then reported as not
+delivering, the ERROR decision 3 replaces. Shares of 200 W or less that give
+under 100 W are "too small to call" in `account()`: the sibling covers the
+meter and nothing is asked of the empty battery that matters.
+
+**Why one direction throughout.** On TEST-19's flapping family a command that
+swaps sign each cycle reads ~0 through the plant's lag: 42 engagements in 21
+no-fault runs without the rule, 0 with it.
+
+**N=1 is unchanged.** Every SAFETY-73 path is gated on `len(inverters) > 1`.
+`test_refusal_units.py` part 6 runs SAFETY-52's whole suite with every
+SAFETY-73 method made to raise.
+
+## Evidence
+
+- `test_refusal_units.py`: cases a, b and c on both register shapes against
+  the old behaviour, probes and their spacing, one-at-a-time probing, the
+  recovery reseed, each exit, the small-ask and small-site-target cases, the
+  WARNING, the status row and shadow mode. Mutations U1-U13 in its docstring.
+- **No false engagements.** TEST-19's no-fault campaign (admin/goodwe
+  `sim/delivery_window.py` families, 2640 runs at N=2 and 2640 at N=1, every
+  unit executing its share) graded with the engage clause: 0 engagements, the
+  longest qualifying streak 5 cycles against 12. The grader is
+  `goodwe-session/scratch_s73/s73_nofault.py`.
+- **Recovery.** Case a, A recovering into a house that fell below the parked
+  target: worst grid +0 W with the reseed. Phase A measured -1059 W without the
+  reseed and the site hold.
+
+## Review changes
+
+- **The evidence must span 22 s, not only 12 cycles.** At a 1 s meter the 12
+  cycles were 11 s, shorter than a healthy reading's lag (dead time plus a
+  10-17 s publish). The reviewer's harness (real `Controller`, both units with
+  6 s dead time and a 13-17 s publish, load steps 300/3000 W every 2 min) then
+  refused both healthy units 10-16 times an hour, and each time the site held
+  0 W: +50-85 Wh import an hour and a +4.6 kW grid peak against +3.7 kW without
+  the refusal. At a 2 s tick there were none. `REFUSED_SPAN_S` is
+  `(SETTLE_CYCLES - 1) * LOOP_TICK_S`, so 2 s and slower ticks are unchanged.
+- **The cut-out WARNING is for a refusal to give power only.** A full battery
+  that stops taking charge is always above its cut-out level, and the WARNING
+  told the installer to check a setting that has nothing to do with it.
+
+## Not covered
+
+- A unit that gives a steady part of its ask (100 W or more) is a limit, as at
+  N=1. SAFETY-42/43 still report it.
+- `pack_permissions` stays SoC-based, so the peak guard may size a shave with a
+  refusing battery counted. The shortfall shows as `unmet_w`.
+- A wedged unit (HW-01) reading ~0 W is now shown as a refusal, not reported as
+  not delivering. Its share still moves, which is the gain SAFETY-42 measured.

goodwe_controller/DECISIONS/UX-08-short-notifications.md

@@ -61,3 +61,32 @@ The allowlist is empty and its cap is 0 (43 → 0). Every WARNING and ERROR line
 10. **The panel's key match** no longer files `inverters.max_w` under the flat `max_w`.
 11. **The Supervisor question at start** is one INFO line with a real reason (a timeout's own text is empty, so the error type is named).
 12. **DOCS**: a glossary ("Words used on this page") explains control board, isolator and Developer Tools once. Card ids left the headings and sit on a *For installers* line under each. The links to the renamed headings were updated.
+
+# UX-10: the last plain-language leftovers (after the 2d test)
+
+**Unchanged:** every safety behaviour, every alarm's log level (WARNING and ERROR stay), every notification id, trigger and cadence, the banner cascade, and every row colour except the meter row right after a start (item 6).
+
+1. **Why the 2d scan missed the clamp lines.** Part 3 reads a log call's own literal and counts `%s` as one word. The clamp lines are `"…software fault: %s …"`, and the text in `%s` was built elsewhere, by `loop_clamp_note()` and `ClampResult.describe()`. So the scan passed a line whose logged text had a semicolon, "BUG SIGNAL", "clamped" and "1 times". The same was true of every quoted reason. Part 6 closes the gap. It lists every dynamic part of every WARNING+ line as data (a number, a name, a path, a library's own error text) or as a built text, and a new part in neither list fails. Each built text is produced by the real code (the watchdogs, `decide()`, `loop_clamp_note()`, `MigrationReport.explain()`) or, for a family of builders, by every template of it (`PriceRead.no_data`, `Gate.block`). The text and the line as logged are then checked. A mutation shows the 2d clamp text is caught on both clamp lines.
+2. **A quoted reason gets the red-alarm shape**, 3 sentences of at most 30 words, and not the 25-word line limit. It is the evidence behind an alarm, and it keeps its code and its limits, which the owner asked to keep. The alarm shape is STYLE.md's existing rule for the texts behind a safety stop, so no new limit was made up. Rewritten: `OUTPUT_CLAMP` (both kinds), `METER_FROZEN`, `CIRCULATING_POWER`, `STALE_READING` (SAFETY-56's two explanations and "cannot tell which" kept, in order), the peak guard's reasons, the state-migration report, the price feed and price history reasons, and the maintenance and trading gate reasons. "Software fault" left the clamp reason, because the ERROR line around it already says it.
+3. **Codes are one token.** `PEAK GUARD`, `PEAK GUARD FLOOR-LIMITED` and `PEAK GUARD BLIND` read as capitals, so they are now `PEAK_GUARD`, `PEAK_GUARD_FLOOR_LIMITED` and `PEAK_GUARD_BLIND`, like `OUTPUT_CLAMP`. Nothing in admin/goodwe or in the scripts under `/home/homelab` greps them (checked). `/home/homelab/clampwatch.sh` greps `OUTPUT_CLAMP`, which stays.
+4. **Top table.** *Price history* writes "96 prices over 24 hours for 26 Sep", joined by commas. *Tariff* writes the spacing as "one every 15 minutes or every hour". "Not final yet" was dropped, because a plan is provisional exactly when it holds an estimated price (`n_carried` counts the provisional points), so the estimated count already says it.
+5. **Levels and noise.** The shadow line of every cycle is DEBUG, and "Shadow mode is on/off" is INFO: it follows a setting or a button, and the banner, hint and event are unchanged. aiohttp's access log is on only at log level debug. A settings warning is logged once per start (a filter on `goodwe.config`, WARNING only, so refusals are untouched), because the validator runs twice at start. When Home Assistant restarts, `hass.Outage` says so in one WARNING line for the REST API and the meter websocket together, puts the library's text on DEBUG, and says at INFO when both answer again. INFO lines lost "§8.3", ISO timestamps, "banked" and "keys ARE", and error texts lost "NOT_OBSERVED", "did NOT land" and "AND".
+6. **Display bugs.**
+   - "Why: Other" during a latched per-inverter stop: `main.py` turns a safety winner into its claim's reason, and "sign disagreement" (and "unsplit", main.py's own refusal to split) had no entry in `WHY_WINNER`. The mapping is now `main.why_key()`, and part 7 finds every `Claim.set()` in the code and checks that every key it can produce has words.
+   - Red "Meter: no reading for 0 seconds" after a restart: until the first reading arrives, `P1Ingest.stale` is true, and the age is the time since start. The row now reads amber "waiting for the first reading" while that age is inside the limit. **Colour change, justified:** red at 0 s contradicted the limit the same row prints, and once readings exist the row is red only past that limit. Amber, not green, because control waits for the reading. Past the limit it is red as before. `stale` itself, which gates control, is unchanged.
+   - "A reading is missing for 0 seconds" stuck at 0: with the meter reading gone, the grid value stops changing, so the loop runs a cycle only every `cycle_floor_s`, and the line was computed once per cycle. The age is now counted when the page asks. The hold and its 15 s escalation are unchanged.
+7. **Review: the line as logged gets the shape too.** Part 6 first checked the quoted reason alone, so a title, a 2-sentence reason and two tails still logged as 4 sentences ("Power request too high …: OUTPUT_CLAMP: … +5000 W. The command this cycle was +1000 W. Control is still running. Cut back 1 time so far."). Part 6 now also checks the whole line: at most 3 sentences, none over 30 words. The wrappers became one sentence each, the circulation and peak guard reasons two, and `STALE_READING`'s fixed limits moved from the reason to a DEBUG line beside the ERROR (its release clause stays, pinned by test_freshness). The clamp lines for one inverter are pinned at 30 words at most: `OUTPUT_CLAMP: computed +9000 W, cut to the +5000 W rating, command now +2000 W`. Several clamped inverters read as one sentence of asked/sent pairs; which limit bound each is on its own action-log row and in the notification. Totals above 30 words remain on the direction, delivery, frozen-meter and stale lines (up to 74 words). Shortening them is a follow-up: the direction and delivery reasons are also persisted in state.json, and the direction one is pinned byte-for-byte in test_watchdog.
+8. **Home Assistant 400 while it loads** now reads "Home Assistant refused number.set_value for number.x (error 400, no details). The entity may still be loading, or the value is out of range." A body with more than "400: Bad Request" is still quoted. Still WARNING, still once a minute, still a failed write.
+9. **Witness** (admin/goodwe): the resolved push says "after no answers from … to …", as the resolved card does. The YAML with every title and message stripped is identical.
+
+# UX-11: safety log lines give the code, the figures go to DEBUG
+
+**Unchanged:** every trigger, latch, threshold and alarm log level (the WARNING and ERROR lines stay), every notification id and cadence, every row colour and the banner cascade. No notification is added.
+
+1. **One plain sentence and the code.** A WARNING/ERROR line that reports a safety reason (direction, delivery, stuck meter, stale reading, peak guard, circulation, over-rating) now ends in the reason's code, taken by `messages.reason_code()`. The reason itself, figures and limits included, is on a DEBUG line logged right after it ("Evidence for inverter-a: …"), and the action log entry carries it as before. Part 6 checks that pairing in the code. Circulation and the clamp lines were not among the five named, but they break the same 25-word rule, so they follow the same pattern. The clamp numbers stay in the notification (phase 2a item 3).
+2. **The reasons and `state.json` are unchanged.** `reason` stays the evidence text, so what is saved has the same format as before. An old state file therefore loads and displays like a new one: every saved reason has opened with its code since it was first written (checked in the git history), and that code is all the ERROR line reads. The saved text goes on the DEBUG line. A stop saved without a reason shows `REASON_NOT_SAVED`. `test_messages.py` part 7 restarts from a state file holding the old long texts. `test_watchdog.py` pins the meaning (the code first, then command, reading, time and both limits, in that order) and, since the text did not change, still the bytes.
+3. **The 25-word rule is checked as logged.** Part 6 fails any WARNING+ line over 25 words with its built text filled in. Nine non-safety families still run long (tariff plan words, price feed reasons, the state migration report, write refusals and claim scope errors that only a software fault raises, maintenance, trading gate and price history reasons). They are listed with a reason in `LONG_LINE_OK`, capped at 9, and a listed family that gets shorter fails until it is removed. Shortening them is a follow-up.
+4. **The meter row's "the add-on log shows why" is now true.** When the meter goes quiet past its limit, the add-on logs one WARNING per episode, not one per cycle, and an INFO line when readings return. A meter that flaps (on `ha_signed` a healthy meter under a flat load can go 42–97 s between changes) logs at most one such pair per 10 minutes, and the episodes in between go to DEBUG. This is a new log line, not a new alarm: it has no notification and changes no decision.
+5. **The Why line past the 15 s hold** names the missing reading ("No usable meter reading for over 15 seconds: 0 W", or the battery power or level of an inverter), instead of "A reading is missing: 0 W".
+6. **Action log:** "25 engagement(s)" is "25 engagements", and "SHADOW MODE OFF - …" is "Shadow mode off: …". "SHADOW MODE ON" was not named in the card and is left as it is.
+7. **Review: after a restart the figures go on the action log too.** `log_level` defaults to `info`, so the DEBUG evidence line is not seen by default, and `events` starts empty. Each restored stop (direction per inverter and site, delivery, circulation) now also writes its saved reason to the action log ("FAILSAFE inverter-a, saved before the restart: …"), and the page's event line gets the same plain words the live stop gives. `LONG_LINE_OK` also refuses a key whose text is a safety reason, not only a `reason_code` key.

goodwe_controller/DECISIONS/UX-13-one-layout-table.md

@@ -0,0 +1,75 @@
+# UX-13 — one layout table, and why UI code may now name an option key
+
+**Status: DECIDED 2026-09-27 (owner approved the UX-13 design and mockup).**
+Card 6ab979852f3eca02fb40f69e. Amends [[UX-02]] §3.1. Design note and
+mockup: `goodwe-session/UX-13-design.md`, `UX-13-mockup.html`.
+
+## 1. What UX-02 said, and why it no longer fits
+
+UX-02 built the configuration panel from the Supervisor's schema, so
+`app/configui.py` contains "no option key, no label and no rule", and
+test_selfconfig.py part 5 checks that the page script names no key. That kept
+a second copy of the option surface from drifting, and it is why the panel is
+a flat list of fields in schema order.
+
+UX-13 needs things a schema cannot say: groups and sub-groups, a slider in kW
+for a value stored in W, a picker for an entity, a field shown only for one
+meter source, locked measured values, a Simple view and a setup wizard. It
+also needs page fields that are not options at all: one inverter card that is
+stored as six flat keys, solar rows that become `pv_entity` or `pv_entities`,
+a contract and two prices that become `static_profile` JSON, and a region
+that becomes the levies figure. None of that can be read off the schema, so
+some code has to name option keys.
+
+## 2. The decision
+
+Option keys may appear in UI code in exactly two files:
+
+- **`app/uilayout.py`**, the layout table: screen → group → part → field, with
+  control, unit, display scale, step, entity kind, when it is shown, whether it
+  is on the Simple view or a wizard step, and whether it applies now or after a
+  restart. Every option in `config.yaml` is a field, `DERIVED` or `HIDDEN`,
+  exactly once.
+- **`app/uimodel.py`**, the derivations the table names: `options_to_ui()` and
+  `ui_to_options()`. It may name only the keys it writes.
+
+What UX-02 made authoritative stays authoritative:
+
+- **Ranges** come from the schema (`uilayout.range_of()`); the table writes
+  none. A unit holds no digit.
+- **Labels and help** come from `translations/*.yaml` by key. Page-only fields,
+  group titles and choices are in `app/ui_text/*.json`, held to STYLE by
+  test_messages.py.
+- **Rules** stay in `validate.py`. It gains a warning tier (`validate.Note`,
+  "warn" or "info") for the page. A note never blocks a save, and passing the
+  notes list does not change the refusals returned.
+- **The stored blob** is still the one truth. The page model carries the stored
+  values of every derived key (`keep`). A derivation whose page fields are
+  unchanged writes those values back untouched, so a blob the page cannot
+  express survives a save of another field.
+
+## 3. How it is held
+
+- test_uilayout.py fails when `config.yaml` gains an option, or an inverter
+  field, that the table does not place. It also checks that uimodel.py names
+  only the keys it writes and that web.py and haentities.py name none.
+- test_uimodel.py round-trips options → page model → JSON → options for every
+  validator call the suite made at 652097a (`scenarios/ux13/`), the TEST-23
+  option files and config.yaml's defaults. All must be identical.
+- `tools/ux13_validator_calls.py compare` runs those calls through the old and
+  new validator. At P0: 261 calls, 158 refused, no refusal changed.
+- test_selfconfig.py part 5 still checks the old page script; P1 moves the page
+  into `app/static/` and the same check applies there.
+- P2: the Installer view (`app/static/settings.js`) draws from
+  `app/uipage.py`, which serialises the table and names no key itself
+  (test_uilayout part 5, test_settings part 2). The view posts its page model
+  to the existing `/config/validate` and `/config/save`, which turn it into
+  options with `ui_to_options()` before the shipped validator runs. No route
+  was added.
+
+## 4. What this costs
+
+The table is a second place that knows the option surface, which UX-02 set
+out to avoid. The cost is bounded by the coverage test: an option added to
+config.yaml and not placed here fails CI, rather than silently missing from
+the page. Changing a key's type or range needs no change here.

goodwe_controller/DOCS.md

@@ -295,7 +295,7 @@ When the add-on refuses to start, each reason names the setting by its label and
 - **Stuck meter alarm after** (`meter_freeze_s`): measured, not chosen (SAFETY-18). Over 2399 s of this house at its operating point, the longest run without a new reading is 15.4 s, and 300 s is 19.5 times that. It raises an alarm only and does not set 0 W.
 - **Opposing inverters threshold** (`circulation_w`): measured on 924 closed-loop test runs (SAFETY-31). The worst legitimate opposition drops from 505 s at 100 W to 5 s at 400 W, the lowest value accepted. 700 W is 1.75 times that knee, with margin because the second inverter is still a copy of the first.
 - **Opposing inverters time** (`circulation_hold_s`): derived (SAFETY-31). 75 s is fifteen control cycles, 15 times the worst legitimate episode, and 2.5 times the control board's 30 s link limit.
-- **Not delivering alarm after** (`delivery_hold_s`): two or more inverters only. It reports only (SAFETY-42): nothing is commanded differently. Derived from 2640 closed-loop test runs with nothing faulty. The worst legitimate episode is 35.0 s and 185 s is 5.29 times that. The schema allows 30 s, below that, so expect false reports there. A battery at or below its own cut-out level is never reported. Re-derive with admin/goodwe `sim/delivery_window.py --campaign --blag`.
+- **Not delivering alarm after** (`delivery_hold_s`): two or more inverters only. It reports only (SAFETY-42): nothing is commanded differently. Derived from 2640 closed-loop test runs with nothing faulty. The worst legitimate episode is 35.0 s and 185 s is 5.29 times that. The schema allows 30 s, below that, so expect false reports there. A battery at or below its own cut-out level is never reported, and neither is one that gives under 100 W (SAFETY-73: it is a battery that refuses). Re-derive with admin/goodwe `sim/delivery_window.py --campaign --blag`.
 - **Shadow mode** (`shadow_mode`): the whole decision path runs and nothing reaches the inverter. The status page and action log show what would have been sent. A safety stop that is already up stays up. See [Shadow mode](#shadow-mode-shadow_mode).
 - **Control gain** (`gain`): measured on real hardware and already at the limit.
 - **Largest change per cycle** (`slew_w`): 0 means follow the rating: about a ninth of it, derived (SAFETY-39) from a measured ~18 s step response against a 2 s meter tick. A fixed value faster than the rating allows is refused. At 1000 W against a 5000 W rating control swung the meter from 3.4 kW export to 2.8 kW import on 2026-09-05.
@@ -526,7 +526,7 @@ accumulator is doing:
 | `Loop integrator lead` | W | that value minus **the command it was computed against**, i.e. the command the previous cycle left standing |
 | `Loop reason` | — | the law's own word for this cycle |
 
-`Loop reason` takes one of eight values:
+`Loop reason` takes one of ten values:
 
 | value | what happened |
 |---|---|
@@ -538,6 +538,35 @@ accumulator is doing:
 | `saturated-freeze` | the inverter is not following, so the command's magnitude may fall but not rise |
 | `freeze-released` | the freeze had run out of plant-shaped explanations and the command was let move again |
 | `not-running` | control is stopped **and** shadow mode is off, so the loop did not run |
+| `battery refuses` | the battery gave less than 100 W for 12 cycles (a minute at a 5-second meter) while asked for more than 500 W, so the add-on asks 0 W in that direction (see below) |
+| `battery probe` | the add-on asks 200 W to test whether a refusing battery gives power again |
+
+**When the battery refuses.** At its cut-out level the battery gives nothing,
+whatever it is asked. The add-on then asks 0 W instead of repeating its last
+request, and the `Why` row reads *The battery refuses to give power: 0 W*. Every
+15 minutes it asks 200 W for about half a minute. Control resumes as soon as
+the battery gives 100 W or more, when the grid needs charging instead, and when
+control is stopped or started. 200 W is below the 250 W the stale-reading check
+needs, so a test never trips it. A battery that gives some power, even 100 W,
+is not refusing and keeps its request.
+
+**With two or more inverters** the same rule works per inverter. An inverter
+whose battery gives less than 100 W for 12 cycles, and at least 22 s, while
+asked for more than 200 W is asked 0 W, and the other inverters take over its share, each up to
+its own limits. The status page names it: *inverter-a: the battery refuses to
+give power, the others take over*. It is tested at 200 W every 15 minutes, one
+inverter at a time, and only while the site asks at least 200 W that way.
+It still accepts charge, and 12 cycles of charging end the refusal. When every
+inverter refuses the same way, the whole site asks 0 W as with one inverter.
+If the battery refuses to give power while its level reads above its “Battery
+cut-out level”, the log adds one warning ending in `REFUSES_ABOVE_CUT_OUT`: check that setting.
+A battery that refuses is not reported as *not delivering*.
+
+*For installers:* SAFETY-52 and SAFETY-73. The event log reads
+`BATTERY REFUSES …` and `BATTERY REFUSES ENDED …` (with the inverter's name at
+N>1), and the INFO line ends in `BATTERY_REFUSES`.
+`DECISIONS/SAFETY-52-a-battery-that-refuses.md` has the replay figures and
+`DECISIONS/SAFETY-73-refusal-per-inverter.md` the two-inverter ones.
 
 ⚠️ **`Loop reason` is not the `Why` row on the status page, and the two will
 often disagree.** `Why` is the *arbiter's* answer in words — *Keeping the grid
@@ -1639,7 +1668,7 @@ is the design rather than an accident: it is 1.0 at the top of the quarter and
 grows, so the guard is gentlest when its projection rests on the least evidence
 and becomes aggressive only once the quarter is nearly measured.
 
-**The ceiling** is `peak_cap_w`, raised to the month's banked peak when that
+**The ceiling** is `peak_cap_w`, raised to this month's recorded peak when that
 already stands higher — once a month's bill is set at 5013 W, holding later
 quarters to 3500 W buys nothing and costs real charging. **That relaxation is
 granted only by an OBSERVED reading:** a peak store that cannot be read leaves the
@@ -1716,7 +1745,7 @@ exactly like the SoC drift the monthly maintenance cycle exists to correct.
   **nothing more**. See below for what that costs on a real evening.
 - **When it binds you are told**, once per episode, with notification
   `goodwe_peak_soc_floor` and a red status-page row reading *Battery at its
-  peak reserve* (`PEAK GUARD FLOOR-LIMITED` in the log): the quarter **will**
+  peak reserve* (`PEAK_GUARD_FLOOR_LIMITED` in the log): the quarter **will**
   go over the ceiling, so shedding load is
   the only thing left that changes the bill. Failing to shave is never silent —
   the euro figure is the whole point of the guard.
@@ -1758,7 +1787,7 @@ because the guard it bounds is not the thing doing the discharging.
 
 **And the two can happen in the same cycle.** On the high-load block of the same
 day (15:00–17:00 UTC) with the pack below the floor, the guard reports
-`PEAK GUARD FLOOR-LIMITED` — *"commanding no forced discharge"* — on 49 cycles,
+`PEAK_GUARD_FLOOR_LIMITED` — *"there is no forced discharge"* — on 49 cycles,
 and on **all 49 of them** the loop is simultaneously being granted a discharge of
 up to 2000 W by the arbiter. The status page is telling you the truth about the
 guard while the battery empties.
@@ -1848,14 +1877,14 @@ Both are watched. A guard that watched only the emitted value would be silent on
 every standard configuration.
 
 **The integrator bound is not a bug, and it is reported as what it is.** It
-reads *"the loop's integrator reached its +5000 W anti-windup bound; the loop's
-command this cycle was +2000 W"*, titled *"the control loop is at its integrator
-bound"*, logged as a `WARNING`, with an amber (not red) status row and its own
-notification (`goodwe_integrator_bound`), so it never replaces a BUG SIGNAL
-notice still on screen. Brief
-engagements after a large load or solar step are normal. If it stays engaged,
-check that the battery is following its commands. Only a command over the rating
-carries the BUG SIGNAL text, and it has its own notification budget.
+reads *"the correction the add-on builds up reached its +5000 W limit,
+command now +2000 W"*, titled *"Battery is not keeping up"*, logged
+as a `WARNING`, with an amber (not red) status row and its own notification
+(`goodwe_integrator_bound`), so it never replaces a software-fault notice still
+on screen. Brief engagements after a large load or solar step are normal. If it
+stays engaged, check that the battery is following its commands. Only a command
+over the rating is logged as a software fault, at `ERROR`, and it has its own
+notification budget.
 Why: [`DECISIONS/SAFETY-40-the-integrator-bound-is-not-a-bug.md`](DECISIONS/SAFETY-40-the-integrator-bound-is-not-a-bug.md).
 
 ### The frozen-meter alarm
@@ -2444,7 +2473,7 @@ since TARIFF-11 that row carries the provider plan itself:
 ```
 Tariff: No fixed tariff set. Price plan from 412 s ago, for 48 hours ahead:
         day-ahead prices from the price feed, 60 prices over 33 hours,
-        36 published and 24 estimated, 900+3600 s apart, not final yet
+        36 published and 24 estimated, one every 15 minutes or every hour
 ```
 
 ⚠️ **The two halves of that row are not computed at the same moment, and the
@@ -2461,9 +2490,10 @@ Read the plan half as five separate facts: which *product* the feed publishes
 and whether it came from the feed or from your fixed tariff, how many
 **prices** it carries and how many **whole hours** they cover, how many are
 **published** (firm, for their own interval) against **estimated** (carried
-from yesterday under §8.3), how far **apart** they are in seconds — `900+3600`
-is the normal mixed steady state, quarter-hourly firm points beside hourly
-carried ones — and `not final yet` (provisional) whenever any is estimated.
+from yesterday under §8.3), and how far **apart** they are — "one every 15
+minutes or every hour" is the normal mixed steady state, quarter-hourly firm
+points beside hourly carried ones. The plan is provisional exactly when some
+prices are estimated, so the estimated count says it.
 
 ⚠️ **Points and hours are two different numbers and this row used to print one
 of them under the other's name.** `words` was `f"… {len(points)} h"`, so a
@@ -3094,8 +3124,11 @@ stop control on the add-on page.
 
 This part is for installers. The texts live in `app/messages.py` and follow
 `STYLE.md`. Every notification keeps a fixed `notification_id`, so a repeat
-replaces the card. The full figures and reason codes are on the ERROR or
-WARNING line of the add-on log.
+replaces the card. The ERROR or WARNING line of the add-on log names the
+reason code. The full figures are in `events` in the `status` JSON, also for a
+stop restored after a restart, and on the DEBUG line logged right after it.
+That DEBUG line only shows with “Log level” (log_level) set to `debug`; the
+default `info` hides it.
 
 | Title | Severity | id | Card |
 |---|---|---|---|
@@ -3204,7 +3237,7 @@ ends. That row says how to clear it.
 | Row starts with | What it tells you |
 |---|---|
 | Control | When control last ran. Red when it has stopped running: the control board then sets the inverter to 0 W. |
-| Meter | The grid reading, its age, how many readings were refused, and how long its value has not changed. |
+| Meter | The grid reading, its age, how many readings were refused, and how long its value has not changed. Just after a start it is amber and *waiting for the first reading*. Red means no reading for longer than the limit. |
 | Stuck-meter check | Whether the add-on can warn you about a stuck meter. |
 | Meter reading may be stuck | See *Meter reading may be stuck* under Notifications. |
 | Month peak | This month's highest 15-minute average, when it happened, and how close it is to your peak limit. Amber from 80 %. |
@@ -3222,8 +3255,9 @@ ends. That row says how to clear it.
 
 ### For installers: status page
 
-The texts are in `app/messages.py`. The full figures of any alarm are on its
-ERROR or WARNING line in the add-on log.
+The texts are in `app/messages.py`. An alarm's ERROR or WARNING line names its
+reason code, and its full figures are on the DEBUG line right after it and in
+`events` in the `status` JSON.
 
 - **Stuck-meter check: off** needs `meter_source: homewizard_local` (label
   “Where the meter reading comes from”), a `max_w` (“Inverter rating”) and a
@@ -3244,10 +3278,15 @@ ERROR or WARNING line in the add-on log.
   **Check for inverters working against each other** is SAFETY-31, **Delivery
   check** SAFETY-42.
 - **Month peak** and **15-minute periods measured** are TARIFF-01 and
-  TARIFF-13. The store's state at start is the INFO line `capacity-tariff peak
-  store: …`, and the peak guard's full reason is on its log line.
+  TARIFF-13. The store's state at start is the INFO line `Month peak store:
+  …`, and the peak guard's full reason is on the DEBUG line after its ERROR.
 - ***name*: battery power reading stopped changing** is SAFETY-37/56/57. The
-  ERROR line carries the full `STALE_READING` reason and when it clears.
+  ERROR line says when it clears and names `STALE_READING`. The full reason,
+  with both possible causes, is on the DEBUG line after it.
+- **Meter: no reading for …** (red): the add-on logs one WARNING when the
+  meter goes quiet, "No meter reading for …", and an INFO line when readings
+  return, at most once every 10 minutes. Past `stale_input_s` the **Why**
+  line names the missing reading.
 - The table at the top: **Why** is `messages.why()`, the arbiter's answer in
   words (`Resolution.explain()` stays on the log). **Tariff**, **Price
   history**, **Arbitrage** and **Shadow mode** keep every figure they had

goodwe_controller/app/allocator.py

@@ -246,11 +246,11 @@ class Allocation:
         block the failsafe is worse than the hole it closes.
         """
         if tick is None or self.tick is None or self.tick != tick:
-            return (f"the allocation record on hand was made on tick "
-                    f"{self.tick!r} and this is tick {tick!r} - a record whose "
-                    f"envelopes have moved cannot authorise a write")
+            return (f"the power split on hand is from tick {self.tick!r}, "
+                    f"not this tick {tick!r}, and an old split cannot allow a "
+                    f"write")
         if not self.ok:
-            return f"the allocator refused this tick ({self.explain()})"
+            return f"no power split was possible this tick ({self.explain()})"
         if unit not in self.shares:
             return (f"{unit} has no share in this tick's allocation "
                     f"({self.explain()})")

goodwe_controller/app/arbiter.py

@@ -226,6 +226,12 @@ CLAIM_SCOPE = {
     # reaches the allocator, so a unit-scoped claim is the shape that sentence
     # asks for rather than an evasion of it.
     "pack": SCOPE_UNIT,
+    # main.py: `Claim.limit("refused", P_SAFETY, ...)` and, during a probe,
+    # `Claim.set("refused", P_SAFETY, +-PROBE_W)`. SAFETY-73: THIS battery gives
+    # nothing in one direction, measured on THIS unit's own reading. A hard unit
+    # limit that always intersects, so the share goes to the siblings. Filed at
+    # N>1 only; at N=1 SAFETY-52's law in compute() does the same job.
+    "refused": SCOPE_UNIT,
     # main.py: `Claim.set("maintenance", P_MAINTENANCE, ...)` when the cycle owns
     # the setpoint, and `Claim.limit("maintenance", P_MAINT_SHAPE, hi=...)` when
     # it only shapes. §12's monthly recalibration is a PACK procedure - drain

goodwe_controller/app/circulation.py

@@ -325,12 +325,13 @@ class CirculationWatchdog:
             return False
 
         self.tripped = True
+        # UX-10: plain sentences, every figure kept (test_messages.py part 6).
         self.reason = (
             f"CIRCULATING_POWER: {circ_w:.0f} W measured going round between "
-            f"the inverters (peak {self.peak_w:.0f} W) for {held:.0f} s "
-            f"continuously - the meter cannot see it, because it nets to zero "
-            f"there (limits: over {self.cfg.min_w:.0f} W, held over "
-            f"{self.cfg.hold_s:.0f} s)")
+            f"the inverters for {held:.0f} s, peaking at {self.peak_w:.0f} W, "
+            f"over the limits of {self.cfg.min_w:.0f} W and "
+            f"{self.cfg.hold_s:.0f} s. The meter cannot see it, because it "
+            f"nets to zero there")
         return True
 
     def held_s(self, now: datetime) -> float:

goodwe_controller/app/clamp.py

@@ -142,6 +142,8 @@ import math
 from dataclasses import dataclass
 from datetime import datetime
 
+from . import messages
+
 # The reason code, distinct from any saturation-freeze code by construction:
 # nothing else in this add-on uses it. See "DISTINCT FROM SATURATION".
 REASON_CODE = "OUTPUT_CLAMP"
@@ -234,31 +236,46 @@ CLEAR_CYCLES = 3
 SUSTAINED_CYCLES = 3
 
 
-BUG_SIGNAL = ("This is a BUG SIGNAL, not a limit being used: something "
-              "upstream computed a setpoint the actuator cannot deliver.")
+# UX-10: the reasons below are quoted by a WARNING or ERROR line, so they
+# follow STYLE.md's rule for a quoted reason (test_messages.py part 6): no
+# final full stop, the line adds it. The line around them says "software
+# fault" for an over-rating, so the reason does not. Each is one sentence, so
+# the logged line stays within 3 sentences and about 30 words.
 
 
 def loop_clamp_note(d) -> str:
     """The loop-side alarm text for one `control.Decision`, or "".
 
     SAFETY-40: the integrator bound is anti-windup doing its job and says so;
-    only a command over the rating is a BUG SIGNAL. Every number is the
+    only a command over the rating is a software fault. Every number is the
     decision's own, i.e. from the tick that clamped.
     """
     if d.clamped:
-        return (f"{REASON_CODE}: the loop computed {d.requested_w:+.0f} W, over "
-                f"the {abs(d.clamped_w):.0f} W rating, and it was clamped to "
-                f"{d.clamped_w:+.0f} W; the loop's command this cycle was "
-                f"{d.target_w:+.0f} W. {BUG_SIGNAL}")
+        return (f"{REASON_CODE}: computed {d.requested_w:+.0f} W, cut to the "
+                f"{d.clamped_w:+.0f} W rating, command now {d.target_w:+.0f} W")
     if d.i_clamped:
-        return (f"{REASON_CODE}: the loop's integrator reached its "
-                f"{d.i_bound_w:+.0f} W anti-windup bound; the loop's command "
-                f"this cycle was {d.target_w:+.0f} W. Brief "
-                f"engagements after a large load or solar step are normal. If it "
-                f"persists, check that the battery is following its commands.")
+        return (f"{REASON_CODE}: the correction the add-on builds up reached "
+                f"its {d.i_bound_w:+.0f} W limit, command now "
+                f"{d.target_w:+.0f} W")
     return ""
 
 
+def write_clamp_note(named) -> str:
+    """The write-side alarm text: `named` is `[(inverter name or None,
+    ClampResult)]` for every inverter whose write was cut back this cycle.
+
+    One inverter reads as `describe()`. Several read as one sentence of
+    asked/sent pairs, so the line stays one sentence however many inverters
+    there are. Which limit cut each one back is on its own action-log row
+    (`describe()`) and in the notification."""
+    if len(named) == 1:
+        name, r = named[0]
+        return f"{name}: {r.describe()}" if name else r.describe()
+    return f"{REASON_CODE}: " + ", ".join(
+        f"{name} asked {r.requested_w:+.0f} W and sent {r.applied_w:+.0f} W"
+        for name, r in named)
+
+
 @dataclass(frozen=True)
 class ClampResult:
     """What the guard did, with the RAW value preserved.
@@ -275,10 +292,12 @@ class ClampResult:
     bound: str = ""          # "" | "max_w" | "device" - which stage bit
 
     def describe(self) -> str:
-        return (f"{REASON_CODE}: the computed setpoint {self.requested_w:+.0f} W "
-                f"was clamped to {self.applied_w:+.0f} W by the {self.bound} "
-                f"bound (rating {self.limit_w:.0f} W) - something upstream is "
-                f"winding")
+        # The sent value IS the limit that bound, so the rating is not
+        # repeated: on "max_w" it equals the rating, and on "device" the
+        # rating was not what cut it back.
+        return (f"{REASON_CODE}: asked {self.requested_w:+.0f} W and sent "
+                f"{self.applied_w:+.0f} W, "
+                f"{messages.LIMIT_WORDS.get(self.bound, self.bound)}")
 
 
 def is_commandable(value) -> bool:

goodwe_controller/app/control.py

@@ -265,6 +265,34 @@ _SAT_COUNT_CAP = SETTLE_CYCLES + 1                           # 13
 # `slew_limit_w()` and therefore with the rail.
 SLEW_LEAD_STEPS = 1
 
+# ---------------------------------------------------------------------------
+# SAFETY-52. A BATTERY THAT REFUSES IS ASKED FOR 0 W, NOT HELD AT ITS LAST ASK.
+#
+# At the BMS cut-out the pack delivers ~0 W whatever it is asked, so the
+# saturation freeze below holds the command where it stood (the recorded
+# 09-06 case: +5000 W for 11.87 h) until the grid error changes sign. The
+# freeze's own exit cannot help: a reading of ~0 against a large ask is inside
+# the interval a limit can produce. So a refused DIRECTION is held at 0 W,
+# carried between cycles like `sat_count`, and left again when the loop wants
+# the other direction, when a small probe is answered, or when the caller
+# resets it (stop, start, another writer). The record is DECISIONS/SAFETY-52.
+#
+# PROBE_W is below freshness.MOVE_W (250 W) on purpose: a probe that small can
+# never arm the stale-reading gate, so it cannot start the gate's ~70 s cycle.
+# test_refusal.py pins the inequality. The cadence and length are the owner's
+# 2026-09-27 answer (every 15 minutes) and freshness.BATT_OBLIGED_S twice over
+# (17 s is how long a healthy reading needs to show a command).
+REFUSED = "battery refuses"
+PROBING = "battery probe"
+PROBE_W = 200.0
+PROBE_ANSWER_W = PROBE_W / 2
+# "Gives nothing" is below the probe's own answer, not below `saturation_w`: a
+# pack derated to 100-499 W is a limit, and at 500 W it kept ~7 % of its power
+# (review of #141). The capture's refusals read -4 W.
+REFUSED_BELOW_W = PROBE_ANSWER_W
+PROBE_EVERY_S = 900.0
+PROBE_S = 34.0
+
 
 @dataclass(frozen=True)
 class Tuning:
@@ -346,6 +374,9 @@ class Decision:
     i_bound_w: float = 0.0
     requested_w: float = 0.0
     clamped_w: float = 0.0
+    # SAFETY-52. The refused direction to carry back in (+1 discharge, -1
+    # charge, 0 none), or None when the caller does not carry it.
+    refused: int | None = None
 
 
 def slew_limit_w(tuning: Tuning) -> float:
@@ -442,6 +473,8 @@ def compute(
     tuning: Tuning,
     sat_count: int = 0,
     i_w: float | None = None,
+    refused: int | None = None,
+    probe: bool = False,
 ) -> Decision:
     """One control cycle. A cycle is one meter update (~5 s on a HomeWizard P1).
 
@@ -449,6 +482,9 @@ def compute(
     `grid_w`   net grid power, + = importing
     `actual_w` what the inverter reports it is doing, + = discharging
     `i_w`      the carried integrator, or None to seed it from `prev_w`
+    `refused`  SAFETY-52's carried refused direction, or None to leave it out
+               (the `i_w=None` equivalence path does)
+    `probe`    the caller's clock says a refused direction may try PROBE_W now
     """
     reason = "tracking"
 
@@ -739,6 +775,27 @@ def compute(
             target = min(target, prev_w) if prev_w > 0 else max(target, prev_w)
             reason = "saturated-freeze"
 
+    # --- SAFETY-52: a refused direction is held at 0 W ----------------------
+    # Engages only where the freeze has held for SETTLE_CYCLES and the unit
+    # delivers ~nothing: a reading below REFUSED_BELOW_W against an ask beyond
+    # `saturation_w` is a refusal, not a slow plant. The drop to 0 skips the slew
+    # limit because it only removes an ask the battery is not meeting.
+    if refused is not None:
+        if (refused == 0 and frozen and sat_count >= SETTLE_CYCLES
+                and abs(prev_w) > tuning.saturation_w
+                and abs(actual_w) < REFUSED_BELOW_W):
+            refused = 1 if prev_w > 0 else -1
+        if refused and refused * i_w < 0:
+            refused = 0                          # the loop wants the other way
+        elif refused and refused * actual_w >= PROBE_ANSWER_W:
+            refused = 0                          # it delivers: a probe answered,
+            #                                     or a slow reading arriving
+        elif refused:
+            wants = refused * i_w > 0
+            i_w = 0.0
+            target = refused * PROBE_W if probe and wants else 0.0
+            reason = PROBING if probe and wants else REFUSED
+
     # --- quantise ----------------------------------------------------------
     # 10 W. The register is 1 W and the inverter reports at 1 W, but its
     # response lands on a coarser ladder (~17.6 W measured at ~900 W, consistent
@@ -749,7 +806,7 @@ def compute(
 
     return Decision(float(target), sat_count, frozen, reason, float(i_w),
                     i_clamped, clamped, float(i_bound_w), float(want),
-                    float(clamped_w))
+                    float(clamped_w), refused)
 
 
 def maintenance_charge_floor(

goodwe_controller/app/freeze.py

@@ -424,15 +424,17 @@ class FreezeWatchdog:
         # page was telling, printed into the log and the HA notification where
         # it would outlive the page.
         ceiling = rail_ceiling_w(max_w, dev_min=dev_min, dev_max=dev_max)
+        # UX-10: plain sentences, every figure kept (test_messages.py part 6).
         capped = ("" if ceiling >= abs(float(max_w))
                   else f", capped from max_w {float(max_w):.0f} W by the "
-                       f"setpoint device's own rating")
+                       f"inverter's own rating")
         self.reason = (
-            f"METER_FROZEN: the meter has answered {float(unchanged_s):.0f} s "
-            f"without its measurement changing while the command stands at "
-            f"{float(commanded_w):+.0f} W, at the {ceiling:.0f} W rail{capped} "
-            f"(limits: unchanged over {self.cfg.hold_s:.0f} s, command over "
-            f"{rail_w(max_w, dev_min=dev_min, dev_max=dev_max):.0f} W)")
+            f"METER_FROZEN: the meter has not changed for "
+            f"{float(unchanged_s):.0f} s while the command is "
+            f"{float(commanded_w):+.0f} W, at the {ceiling:.0f} W limit"
+            f"{capped}. Limits: unchanged over {self.cfg.hold_s:.0f} s, "
+            f"command over "
+            f"{rail_w(max_w, dev_min=dev_min, dev_max=dev_max):.0f} W")
         if self.active:
             return False
         self.active = True

goodwe_controller/app/freshness.py

@@ -594,31 +594,26 @@ class Freshness:
         # ("what did the register do" against "can I trust this entity"). One
         # helper serving both would have to drop whichever half the other does
         # not need, and the half it dropped would be the operator's next step.
-        self.reason = (
-            f"STALE_READING: {self.held:+.0f} unchanged for {shown_s:.0f} s "
-            f"while the standing command moved {moved_w:.0f} W to "
-            f"{standing_w:+.0f} W. TWO THINGS LOOK LIKE THIS AND THIS GATE "
-            f"CANNOT TELL THEM APART: the register may have stopped reporting "
-            f"reality, or the source may be unable to comply with the command "
-            f"- a pack the BMS is refusing holds still under any setpoint, and "
-            f"an honest register then reads exactly like a frozen one. Either "
-            f"way the number cannot be read as this command's effect, so it is "
-            f"reported as MISSING rather than as a measurement (limits: "
-            f"unchanged over {self.bound.unchanged_s:.0f} s, command over "
-            f"{self.bound.move_w:.0f} W and moved by over "
-            f"{self.bound.move_w:.0f} W)")
+        # UX-10: two plain sentences (test_messages.py part 6). SAFETY-56's
+        # two explanations stay, in this order, and so does the admission
+        # that this check cannot tell them apart. The reading is treated as
+        # missing either way, which the log line around this says. The
+        # limits (`self.bound`) are on main.py's DEBUG line beside it, so the
+        # logged line stays within 3 sentences.
         # ⚠️ SAFETY-57, AND THE THREE DURATIONS ARE THREE DIFFERENT FACTS, each
-        # in its own slot: the register's unchanged time is in the sentence
-        # above, the WINDOW this verdict actually rests on is here, and so is
-        # how many times this unit has been round the loop. Without the second
-        # one the sentence reads as though 92 s of unchanged register were what
-        # was compared against the 35 s limit, and it was not.
-        if self.releases:
-            self.reason += (
-                f" [re-graded: the {held_s:.0f} s window this verdict rests on "
-                f"opened when the previous one was withdrawn, not when the "
-                f"register last moved - this unit has now been graded "
-                f"{self.releases + 1} times]")
+        # in its own slot: the register's unchanged time, the WINDOW this
+        # verdict actually rests on after a release (`regraded`), and how many
+        # times this unit has been round the loop. Without the second one the
+        # sentence reads as though 92 s of unchanged register were what was
+        # compared against the 35 s limit, and it was not.
+        regraded = (f", checked {self.releases + 1} times over a {held_s:.0f} s "
+                    f"window since the last stop was withdrawn"
+                    if self.releases else "")
+        self.reason = (
+            f"STALE_READING: {self.held:+.0f} W unchanged for {shown_s:.0f} s "
+            f"while the command moved {moved_w:.0f} W to {standing_w:+.0f} W"
+            f"{regraded}. The reading may have stopped, or the battery may be "
+            f"unable to follow the command, and this check cannot tell which")
 
     def unchanged_s(self, now_mono) -> float | None:
         """Seconds since an arrival carried a different number. Status page.

goodwe_controller/app/haentities.py

@@ -0,0 +1,91 @@
+"""UX-13: Home Assistant's entities, for the settings page's entity picker.
+
+A read of `GET /api/states` through the add-on's own session (hass.states()),
+cached for 30 s and trimmed to what a picker shows. Nothing here writes, so
+UX-02 §6 holds. When Home Assistant does not answer, the last good list is
+served with its age, or an empty one that says why: the route never fails.
+"""
+
+import asyncio
+import time
+
+CACHE_S = 30.0
+DOWN_TEXT = "Home Assistant is not answering, so the entity list is empty."
+STALE_TEXT = "Home Assistant is not answering, so this list may be old."
+_POWER_UNITS = ("mW", "W", "kW", "MW", "GW", "TW")
+_ENERGY_UNITS = ("Wh", "kWh", "MWh", "GWh")
+
+
+def row(state: dict) -> dict | None:
+    """One state object -> {entity_id, name, state, unit, device_class}."""
+    if not isinstance(state, dict) or not isinstance(state.get("entity_id"), str):
+        return None
+    attrs = state.get("attributes") if isinstance(state.get("attributes"), dict) else {}
+    return {"entity_id": state["entity_id"],
+            "name": str(attrs.get("friendly_name") or state["entity_id"]),
+            "state": state.get("state"),
+            "unit": attrs.get("unit_of_measurement"),
+            "device_class": attrs.get("device_class")}
+
+
+def matches(r: dict, kind: str) -> bool:
+    """Is `r` what a picker of this kind offers first? `kind` is one of
+    uilayout.ENTITY_KINDS; "" or "any" offers everything."""
+    unit, cls = r.get("unit"), r.get("device_class")
+    if kind in ("power", "power_w"):
+        return cls == "power" or unit in _POWER_UNITS
+    if kind == "energy":
+        return cls == "energy" or unit in _ENERGY_UNITS
+    if kind == "pct":
+        return unit == "%"
+    if kind == "number":
+        return r["entity_id"].startswith(("number.", "input_number."))
+    return True
+
+
+class EntityCache:
+    """The last entity list read from Home Assistant, at most CACHE_S old."""
+
+    def __init__(self, hass, clock=time.monotonic):
+        self.hass = hass
+        self.clock = clock
+        self.rows: dict | None = None
+        self.read_at: float | None = None
+        self.tried_at: float | None = None
+        self._lock = asyncio.Lock()
+
+    async def get(self) -> tuple[dict | None, float | None]:
+        """(rows by entity id, age in s), or (None, None) if never read."""
+        async with self._lock:      # one HA read however many pickers ask
+            now = self.clock()
+            # A failed read also waits CACHE_S, so polls while HA is down do
+            # not queue one 10 s read each behind this lock.
+            if self.tried_at is None or now - self.tried_at >= CACHE_S:
+                self.tried_at = now
+                states = await self.hass.states()
+                if states is not None:
+                    rows = (row(s) for s in states)
+                    self.rows = {r["entity_id"]: r for r in rows if r}
+                    self.read_at = now
+            if self.read_at is None:
+                return None, None
+            return self.rows, now - self.read_at
+
+    def peek(self) -> dict | None:
+        """The cached rows if they are fresh, without asking Home Assistant."""
+        if self.read_at is None or self.clock() - self.read_at >= CACHE_S:
+            return None
+        return self.rows
+
+    async def payload(self, kind: str = "") -> dict:
+        """The route's JSON: matching entities first, then the rest."""
+        rows, age = await self.get()
+        if rows is None:
+            return {"available": False, "text": DOWN_TEXT, "entities": []}
+        ordered = sorted(rows.values(), key=lambda r: r["entity_id"])
+        first = [dict(r, match=True) for r in ordered if matches(r, kind)]
+        rest = [dict(r, match=False) for r in ordered if not matches(r, kind)]
+        out = {"available": True, "age_s": round(age, 1), "entities": first + rest}
+        if age >= CACHE_S:
+            out["text"] = STALE_TEXT
+        return out

goodwe_controller/app/hass.py

@@ -16,6 +16,39 @@ _LOG = logging.getLogger("goodwe.hass")
 CORE_API = "http://supervisor/core/api"
 SUPERVISOR_API = "http://supervisor"
 BAD_STATES = ("unknown", "unavailable", "none", "")
+# What the Supervisor's proxy answers while Home Assistant restarts.
+UNAVAILABLE = (502, 503, 504)
+STATES_TIMEOUT_S = 10       # UX-13's entity list, like every other read here
+
+
+class Outage:
+    """UX-10: Home Assistant not answering, said in one plain line per outage.
+
+    A restart takes the REST API and the meter websocket down together, and
+    each used to log the library's own text for every entity and service
+    ("502, message='Bad Gateway', url=URL(...)", "Received message 8:1000 is
+    not str"). Now the first channel to fail says it once at WARNING, the raw
+    text goes to DEBUG, and the last channel to recover says so at INFO.
+    """
+
+    def __init__(self):
+        self.down_on = set()
+
+    def down(self, channel: str, what: str, detail) -> None:
+        if not self.down_on:
+            _LOG.warning("Home Assistant is not answering (%s), perhaps it is "
+                         "restarting. The add-on keeps trying.", what)
+        self.down_on.add(channel)
+        _LOG.debug("Home Assistant not answering on %s: %s", channel, detail)
+
+    def up(self, channel: str) -> None:
+        if channel in self.down_on:
+            self.down_on.discard(channel)
+            if not self.down_on:
+                _LOG.info("Home Assistant answers again.")
+
+
+OUTAGE = Outage()
 
 
 class HomeAssistant:
@@ -58,10 +91,18 @@ class HomeAssistant:
             async with self.session.get(
                 f"{CORE_API}/states/{entity_id}", headers=self._headers, timeout=10
             ) as resp:
+                if resp.status in UNAVAILABLE:
+                    OUTAGE.down("api", f"error {resp.status}",
+                                f"read {entity_id}: {resp.status}")
+                    return None
+                OUTAGE.up("api")
                 if resp.status == 404:
                     return None
                 resp.raise_for_status()
                 obj = await resp.json()
+        except aiohttp.ClientConnectionError as err:
+            OUTAGE.down("api", "no connection", f"read {entity_id}: {err}")
+            return None
         # SAFETY-61: an undecodable body is an absence like any other failed
         # read, never an exception into the control loop.
         except (aiohttp.ClientError, TimeoutError, ValueError) as err:
@@ -73,6 +114,39 @@ class HomeAssistant:
             return None
         return obj
 
+    async def states(self) -> list | None:
+        """Every entity's state object (`GET /api/states`), or None when Home
+        Assistant does not answer. A read only (UX-13 entity picker)."""
+        try:
+            async with self.session.get(
+                f"{CORE_API}/states", headers=self._headers,
+                timeout=STATES_TIMEOUT_S
+            ) as resp:
+                if resp.status in UNAVAILABLE:
+                    OUTAGE.down("api", f"error {resp.status}",
+                                f"read all states: {resp.status}")
+                    return None
+                OUTAGE.up("api")
+                resp.raise_for_status()
+                obj = await resp.json()
+        except aiohttp.ClientConnectionError as err:
+            OUTAGE.down("api", "no connection", f"read all states: {err}")
+            return None
+        # A timeout's own text is empty, so the line names the wait instead
+        # (UX-13 P1 test, c).
+        except TimeoutError:
+            self._moan("read:*", "Reading the entity list failed: no answer "
+                       "within %s seconds.", STATES_TIMEOUT_S)
+            return None
+        except (aiohttp.ClientError, ValueError) as err:
+            self._moan("read:*", "Reading the entity list failed: %s",
+                       str(err) or type(err).__name__)
+            return None
+        if not isinstance(obj, list):
+            self._moan("shape:*", "The entity list is not a list: %.80r", obj)
+            return None
+        return obj
+
     async def number(self, entity_id: str, invert: bool = False) -> float | None:
         """Numeric state, or None. Never substitutes a default."""
         obj = await self.state(entity_id)
@@ -113,17 +187,37 @@ class HomeAssistant:
                 f"{CORE_API}/services/{domain}/{service}",
                 headers=self._headers, json=data, timeout=10,
             ) as resp:
+                if resp.status in UNAVAILABLE:
+                    OUTAGE.down("api", f"error {resp.status}",
+                                f"service {domain}.{service}: {resp.status}")
+                    return False
+                OUTAGE.up("api")
                 if resp.status >= 400:
                     body = await resp.text()
                     # 400 here usually means out-of-range for the entity - the
                     # value is rejected outright, not clamped. Always log it:
                     # silently dropped commands are how a controller ends up
                     # believing something the hardware never did.
+                    # UX-10: plain words. While Home Assistant loads its
+                    # entities it answers 400 with only "400: Bad Request",
+                    # which says nothing, so only a body with more is quoted.
+                    said = body.strip()[:200]
+                    if said.lower() in (f"{resp.status}: {resp.reason}".lower(),
+                                        ""):
+                        said = "no details"
+                    entity = (data.get("entity_id", "no entity")
+                              if isinstance(data, dict) else "no entity")
                     self._moan(f"svc:{domain}.{service}",
-                               "service %s.%s rejected (%s): %s",
-                               domain, service, resp.status, body[:200])
+                               "Home Assistant refused %s.%s for %s (error %s, "
+                               "%s). The entity may still be loading, or the "
+                               "value is out of range.", domain, service,
+                               entity, resp.status, said)
                     return False
                 return True
+        except aiohttp.ClientConnectionError as err:
+            OUTAGE.down("api", "no connection",
+                        f"service {domain}.{service}: {err}")
+            return False
         # ValueError: an undecodable error body (SAFETY-61) is a failed write.
         except (aiohttp.ClientError, TimeoutError, ValueError) as err:
             self._moan(f"svcerr:{domain}.{service}", "service %s.%s failed: %s",

goodwe_controller/app/inverter.py

@@ -317,6 +317,18 @@ class Inverter:
             tripped=bool(data.get(self.key("delivery_tripped"), False)),
             reason=str(data.get(self.key("delivery_reason"), "") or ""))
 
+        # SAFETY-73. The direction this unit's battery refuses (+1 give, -1
+        # take, 0 none), when that refusal or its last probe started, the
+        # current probe's start, and the cycles of evidence so far and when
+        # they began. Memory only, like SAFETY-52's: stop and start end it.
+        # Used at N>1 only.
+        self.refused = 0
+        self.refused_at = None
+        self.probe_from = None
+        self.ref_count = 0
+        self.ref_since = None
+        self.ref_sign = 0
+
     # -- store ---------------------------------------------------------------
     def key(self, name: str) -> str:
         """This unit's namespaced Store key for `name`. See store.unit_key()."""
@@ -411,6 +423,13 @@ class Inverter:
         return (messages.row_battery_stuck(self.name) if self.batt_fresh.stale
                 else "")
 
+    def refusal_note(self) -> str:
+        """SAFETY-73's status row while this unit's battery refuses."""
+        if not self.refused:
+            return ""
+        return messages.row_battery_refuses(self.name, self.refused,
+                                            self.probe_from is not None)
+
     def link_note(self, now: datetime) -> str:
         """One line for the status page. Empty when there is nothing to say.
 

goodwe_controller/app/maintenance.py

@@ -351,7 +351,7 @@ class Maintenance:
         the action log rather than watching nothing happen.
         """
         if blocked_by:
-            msg = (f"maintenance: forced start REFUSED on {self.name} - "
+            msg = (f"maintenance: {self.name} cannot start now, because "
                    f"{blocked_by}")
             _LOG.warning("%s", msg)
             return [msg]
@@ -378,10 +378,9 @@ class Maintenance:
         """
         if self._deferred != why:
             self._deferred = why
-            msg = (f"maintenance: {self.name} is due and is WAITING its turn - "
-                   f"{why}. It is idle under the control loop and will "
-                   f"recalibrate at the next start hour once the slot is free; "
-                   f"this is not a stalled phase.")
+            msg = (f"maintenance: {self.name} is due and waits its turn, "
+                   f"because {why}. It starts at the next start hour once the "
+                   f"other battery is done. This is not a stalled phase.")
             _LOG.info("%s", msg)
             events.append(msg)
         return events

goodwe_controller/app/messages.py

@@ -311,10 +311,37 @@ def seconds(value) -> str:
     return f"{n} second" if n == "1" else f"{n} seconds"
 
 
+# One token each, like a code, so the line keeps its length and stays greppable.
+NO_REASON_SAVED, NO_REASON_CODE = "REASON_NOT_SAVED", "REASON_WITHOUT_CODE"
+_REASON_CODE = re.compile(r"\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b")
+
+
+def reason_code(reason) -> str:
+    """UX-11: the code in a safety reason (`STALE_READING`), for the one plain
+    WARNING or ERROR line that reports it. The reason with its figures goes on
+    a DEBUG line beside it and into the action log. Saved reasons have always
+    opened with their code, so an old state file reads the same way."""
+    if not reason:
+        return NO_REASON_SAVED
+    m = _REASON_CODE.search(str(reason))
+    return m.group(0) if m else NO_REASON_CODE
+
+
 def times(n) -> str:
     return "1 time" if int(n) == 1 else f"{int(n)} times"
 
 
+def count(n, noun, plural=None) -> str:
+    """`count(1, "price")` -> `1 price`, `count(3, "price")` -> `3 prices`."""
+    return f"{int(n)} {noun if int(n) == 1 else plural or noun + 's'}"
+
+
+def when(at) -> str:
+    """`27 Sep at 09:15`, as the page writes a moment. `at` is already in the
+    time zone the reader wants (the caller passes `price.brussels(t)`)."""
+    return f"{at.day} {at:%b} at {at:%H:%M}"
+
+
 def for_unit(unit) -> str:
     """` for inverter-b` on a site with several inverters, else nothing."""
     return f" for {unit}" if unit else ""
@@ -383,6 +410,11 @@ def row_controller_stalled(age_s, veto_s) -> str:
             f"sets the inverter to 0 W after {seconds(veto_s)}.")
 
 
+def row_meter_waiting(limit_s) -> str:
+    """UX-10: no reading yet since the start, and still inside the limit."""
+    return f"Meter: waiting for the first reading, limit {seconds(limit_s)}"
+
+
 def row_meter_stale(age_s, limit_s) -> str:
     return (f"Meter: no reading for {seconds(age_s)}, limit "
             f"{seconds(limit_s)}. The add-on log shows why.")
@@ -754,6 +786,14 @@ def row_battery_stuck(unit) -> str:
             f"for now")
 
 
+def row_battery_refuses(unit, sign, probing) -> str:
+    """SAFETY-73. One inverter's battery refuses, the others take its share."""
+    way = "give" if sign > 0 else "take"
+    if probing:
+        return f"{unit}: testing if the battery will {way} power again"
+    return f"{unit}: the battery refuses to {way} power, the others take over"
+
+
 # The top of the page: why the battery does what it does (the "Why" line).
 WHY_WINNER = {
     "loop": "Keeping the grid near zero",
@@ -766,6 +806,15 @@ WHY_WINNER = {
     "stopped": "Control is stopped",
     "inputs missing": "A reading is missing",
     "no claim was made": "Nothing asked for power",
+    # UX-10: the claim reasons main.why_key() can return for a safety or
+    # failsafe winner. test_messages.py part 7 finds every one in the code.
+    "sign disagreement": "Safety stop, power went the wrong way",
+    "unsplit": "The power could not be split, all at 0 W",
+    # SAFETY-52: the loop's two words for a battery that gives nothing.
+    "battery refuses": "The battery refuses to give power",
+    "battery probe": "Testing if the battery gives power again",
+    # SAFETY-73: a refusing inverter's own claim, closed or probing.
+    "refused": "A battery refuses power, the others take over",
 }
 WHY_LIMIT = {
     "peak(quarter peak)": "the peak limit",
@@ -776,6 +825,7 @@ WHY_LIMIT = {
     "pack": "the battery level",
     "reserve": "the battery reserve",
     "maintenance": "battery maintenance",
+    "refused": "a battery that refuses power",
 }
 
 
@@ -793,6 +843,11 @@ def why(winner, target_w, bound_by=None, *, contradiction=False) -> str:
     return out
 
 
+def why_missing(what, limit_s) -> str:
+    """UX-11: past the hold, which reading is missing and what it does."""
+    return f"No usable {what} reading for over {seconds(limit_s)}: 0 W"
+
+
 def why_waiting(missing_s) -> str:
     """A reading went missing a moment ago: control holds and waits."""
     return f"A reading is missing for {seconds(missing_s)}, control waits"
@@ -811,6 +866,10 @@ HINTS = {
     "stop_restored": "{unit}: an earlier safety stop is back, it stays at 0 W",
     "battery_stuck": "{unit}: battery power reading stopped changing",
     "battery_back": "{unit}: battery power reading is used again",
+    "battery_refuses": "The battery refuses to give power, the add-on asks 0 W",
+    "battery_gives": "The battery refusal ended, control asks for power again",
+    "unit_refuses": "{unit}: the battery refuses power, the others take over",
+    "unit_gives": "{unit}: the battery refusal ended, it is asked for power again",
     "bad_value": "The add-on made an invalid power value, inverters set to 0 W",
     "write_blocked": "{unit}: a power request was blocked, it is set to 0 W",
     "all_blocked": "A power request was blocked, inverters set to 0 W",
@@ -898,6 +957,7 @@ def status_samples() -> list:
         ("row_controller_ran", GREEN, row_controller_ran(2)),
         ("row_controller_stalled", RED, row_controller_stalled(45, 30)),
         ("row_meter_stale", RED, row_meter_stale(40, 10)),
+        ("row_meter_waiting", AMBER, row_meter_waiting(30)),
         ("row_meter", GREEN, row_meter(-350, 2, 3, 340)),
         ("row_meter_frozen", RED, row_meter_frozen()),
         *(("row_freeze_off", AMBER, row_freeze_off(k)) for k in FREEZE_OFF),
@@ -980,6 +1040,12 @@ def status_samples() -> list:
         ("row_peak_guard_on", AMBER, row_peak_guard_on(1200, 2500,
                                                        shadow=True)),
         ("row_battery_stuck", AMBER, row_battery_stuck("inverter-b")),
+        ("row_battery_refuses", AMBER, row_battery_refuses("inverter-b", 1,
+                                                           False)),
+        ("row_battery_refuses", AMBER, row_battery_refuses("inverter-b", -1,
+                                                           False)),
+        ("row_battery_refuses", AMBER, row_battery_refuses("inverter-b", 1,
+                                                           True)),
         ("row_circulating_check", GREEN, row_circulating_check(0, 0, 60)),
     ]
 
@@ -1052,6 +1118,18 @@ LABELS = {
     "unit_sign_disagree_w": "Per-inverter wrong-direction threshold",
     "slew_w": "Largest change per cycle",
     "shadow_mode": "Shadow mode",
+    # UX-13: named by the settings page's warnings (validate.Note).
+    "integrator_max_w": "Catch-up limit",
+    "maintenance_discharge_w": "Draw-down rate",
+    "peak_cap_w": "Peak limit",
+    "peak_forecast_entity": "15-minute demand forecast entity",
+    "meter_entity": "Grid power entity",
+    "soc_entity": "Battery level entity",
+    "batt_entity": "Battery power entity",
+    "pv_entity": "Solar production entity",
+    "pv_entities": "Solar production entities, per inverter",
+    "p1_phase_import_entities": "Import entities per phase",
+    "p1_phase_export_entities": "Export entities per phase",
 }
 
 

goodwe_controller/app/p1.py

@@ -48,6 +48,7 @@ from datetime import datetime, timezone
 import aiohttp
 
 from . import messages
+from .hass import OUTAGE
 
 _S = messages.setting   # a refusal names the setting by its label (UX-08)
 
@@ -524,6 +525,16 @@ WS_URL = "ws://supervisor/core/websocket"
 BAD_STATES = ("unknown", "unavailable", "none", "")
 
 
+async def _receive_json(ws):
+    """The next JSON message. A socket Home Assistant closed (a restart) is a
+    ConnectionResetError, not aiohttp's "Received message 8:1000 is not str"."""
+    msg = await ws.receive()
+    if msg.type is not aiohttp.WSMsgType.TEXT:
+        raise ConnectionResetError(
+            f"Home Assistant closed the connection ({msg.type.name})")
+    return json.loads(msg.data)
+
+
 class HaDsmrSource:
     """Subscribes to state_changed for the configured DSMR entities.
 
@@ -574,8 +585,12 @@ class HaDsmrSource:
                 backoff = 1.0
             except asyncio.CancelledError:
                 raise
+            except (aiohttp.ClientError, ConnectionError) as err:
+                # UX-10: Home Assistant restarting, said once (hass.Outage).
+                OUTAGE.down("websocket", "the meter connection closed", err)
             except Exception as err:  # noqa: BLE001 - any transport fault retries
-                _LOG.warning("P1 HA websocket: %s - reconnecting in %.0fs", err, backoff)
+                _LOG.warning("The meter connection to Home Assistant failed "
+                             "(%s), trying again in %.0f s.", err, backoff)
             finally:
                 self.connected = False
             await asyncio.sleep(backoff)
@@ -583,16 +598,17 @@ class HaDsmrSource:
 
     async def _session_once(self) -> None:
         async with self.session.ws_connect(WS_URL, heartbeat=30) as ws:
-            hello = await ws.receive_json()
+            hello = await _receive_json(ws)
             if hello.get("type") == "auth_required":
                 await ws.send_json({"type": "auth", "access_token": self.token})
-                reply = await ws.receive_json()
+                reply = await _receive_json(ws)
                 if reply.get("type") != "auth_ok":
                     raise RuntimeError(f"auth rejected: {reply.get('message', reply)}")
             await ws.send_json({"id": 1, "type": "subscribe_events",
                                 "event_type": "state_changed"})
             await ws.send_json({"id": 2, "type": "get_states"})
             self.connected = True
+            OUTAGE.up("websocket")
             _LOG.info("P1 ingest: subscribed to %s", ", ".join(sorted(self.ids)))
 
             async for msg in ws:
@@ -618,7 +634,7 @@ class HaDsmrSource:
                     new = data.get("new_state") or {}
                     self._absorb(data.get("entity_id"), new.get("state"))
                     self._schedule()
-            raise RuntimeError("websocket closed")
+            raise ConnectionResetError("Home Assistant closed the connection")
 
     def _absorb(self, entity_id: str | None, state) -> None:
         if not entity_id or entity_id not in self.ids:

goodwe_controller/app/peakguard.py

@@ -402,27 +402,27 @@ from .tariff import QUARTER_S
 
 # Why the projection may not be graded. Reasons, not booleans: the status page
 # and the action log both have to say WHICH, and "blind" alone is unactionable.
-BLIND_NO_BLOCK = "no open quarter - the meter has produced no sample yet"
+BLIND_NO_BLOCK = "no open 15-minute period, the meter has given no reading yet"
 BLIND_COVERAGE = "meter gap"
-BLIND_FROZEN = "SAFETY-18: the meter is answering without changing"
+BLIND_FROZEN = "the meter is answering without changing"
 
 # Where the ceiling came from. Only the second is a relaxation, and only an
 # OBSERVED reading may produce it.
 CEILING_CAP = "peak_cap_w"
-CEILING_MONTH_PEAK = "the month's banked peak"
+CEILING_MONTH_PEAK = "this month's peak"
 
 # SAFETY-24. Why the forced discharge may not be sized. Reasons, not booleans,
 # for BLIND_*'s reason: the status page, the action log and the operator
 # notification all have to say WHICH, and "floor-limited" alone is unactionable.
-FLOOR_SOC_UNREADABLE = ("the battery state of charge was not measured this "
-                        "cycle, and an unreadable SoC is not a full battery")
-# ⚠️ SAFETY-25. "the peak guard's SoC floor", not "the SoC floor", and the
-# possessive is load-bearing: this string is what the status page, the action log
-# and the operator notification all print, and `peak_soc_floor` bounds THIS GUARD
-# ONLY. Widening it to "the SoC floor" would make the one sentence an operator
-# reads at the moment the battery stops shaving into a claim about the pack that
-# the grid-following loop is at that instant disproving.
-FLOOR_AT_SOC_FLOOR = "state of charge is at or below the peak guard's SoC floor"
+FLOOR_SOC_UNREADABLE = ("the battery level was not read this cycle, and "
+                        "unread is not full")
+# ⚠️ SAFETY-25. "the peak reserve", not "the SoC floor", and the name is
+# load-bearing: this string is what the action log and the add-on log print,
+# and `peak_soc_floor` (“Peak reserve”) bounds THIS GUARD ONLY. Widening it to
+# "the SoC floor" would make the one sentence an operator reads at the moment
+# the battery stops shaving into a claim about the pack that the
+# grid-following loop is at that instant disproving.
+FLOOR_AT_SOC_FLOOR = "the battery level is at or below the peak reserve"
 
 SOURCE = "peak"
 
@@ -566,8 +566,9 @@ def blindness(projection, max_hold_s, frozen: bool) -> str | None:
         return BLIND_NO_BLOCK
     gap = uncovered_s(projection)
     if max_hold_s is not None and gap > float(max_hold_s):
-        return (f"{BLIND_COVERAGE}: {gap:.0f} s of this quarter uncovered, past "
-                f"the {float(max_hold_s):.0f} s the averager will hold a sample")
+        return (f"{BLIND_COVERAGE}, {gap:.0f} s of this 15-minute period not "
+                f"covered, past the {float(max_hold_s):.0f} s a reading is "
+                f"held")
     return None
 
 
@@ -743,9 +744,9 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         return PeakDecision(
             engaged=True, floor_w=0.0, ceiling_w=ceiling, ceiling_from=from_where,
             blind=blind, projected_w=None,
-            reason=(f"PEAK GUARD BLIND ({blind}) - the battery may not import "
-                    f"while the billed quarter cannot be measured; commanding no "
-                    f"charging (floor 0 W)"))
+            reason=(f"PEAK_GUARD_BLIND: {blind}. The battery may not charge "
+                    f"while this 15-minute period cannot be measured, so it "
+                    f"is asked for no charging, floor 0 W"))
 
     projected = float(projection.projected_w)
     if batt_w is None:
@@ -807,17 +808,18 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
             ceiling_from=from_where, projected_w=projected, excess_w=ex,
             wanted_w=wanted, floor_limited=True, soc=soc, soc_floor=soc_floor,
             soc_floor_reason=denied,
+            # UX-10: plain sentences, every figure kept (test_messages.py
+            # part 6). The code is one token, so it is not read as shouting.
             reason=(
-                f"PEAK GUARD FLOOR-LIMITED: the quarter projects "
-                f"{projected:.0f} W against a {ceiling:.0f} W ceiling "
-                f"({from_where}) and {wanted:+.0f} W of discharge would hold "
-                f"it, but {denied}"
-                + ("" if soc is None else f" ({float(soc):.0f} %")
+                f"PEAK_GUARD_FLOOR_LIMITED: this 15-minute period heads for "
+                f"{projected:.0f} W against a {ceiling:.0f} W limit "
+                f"({from_where}), and {wanted:+.0f} W from the battery would "
+                f"hold it. But {denied}"
+                + ("" if soc is None else f", at {float(soc):.0f} %")
                 + ("" if soc is None or soc_floor is None
-                   else f" vs {float(soc_floor):.0f} %")
-                + ("" if soc is None else ")")
-                + " - commanding no forced discharge, so THIS QUARTER WILL GO "
-                  "OVER THE CEILING. Charging stays blocked (floor 0 W)"))
+                   else f" against {float(soc_floor):.0f} %")
+                + ", so no forced discharge and no charging, and this period "
+                  "will go over the limit"))
 
     floor = min(wanted, ceil_top)
     saturated = floor < wanted
@@ -826,13 +828,15 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         blind=None, projected_w=projected, excess_w=ex, wanted_w=wanted,
         saturated=saturated, soc=soc, soc_floor=soc_floor,
         reason=(
-            f"PEAK GUARD: quarter projects {projected:.0f} W against a "
-            f"{ceiling:.0f} W ceiling ({from_where}) with "
+            f"PEAK_GUARD: this 15-minute period heads for {projected:.0f} W "
+            f"against a {ceiling:.0f} W limit ({from_where}), with "
             f"{QUARTER_S - projection.elapsed_s:.0f} s left, so {ex:.0f} W must "
-            f"come off the meter; battery measured {float(batt_w):+.0f} W, "
-            f"floor {floor:+.0f} W"
-            + (f" - SATURATED, {wanted:+.0f} W was needed and the inverter can "
-               f"only give {ceil_top:.0f} W" if saturated else "")))
+            f"come off the meter. The battery measured {float(batt_w):+.0f} W "
+            f"and is asked for {floor:+.0f} W"
+            # Saturated means floor == ceil_top: the ask IS the most the
+            # inverters give, so one clause says both.
+            + (f", the most the inverters give, but {wanted:+.0f} W was needed"
+               if saturated else "")))
 
 
 def charge_headroom_w(decision) -> float | None:

goodwe_controller/app/price.py

@@ -150,6 +150,7 @@ from enum import Enum
 from textwrap import dedent
 from urllib.parse import urlencode
 
+from . import messages
 from .custom_formula import (
     EXPORT_FORMULA_OPTION, FormulaInvalid, PREVIEW_HOURS, parse_export_formula,
     parse_price_formula, preview_lines, price_eur_kwh, to_resolution)
@@ -1738,11 +1739,11 @@ def _points_from_columnar_json(body, expect_unit, scale,
         out.append(RawPoint(start=start, eur_per_kwh=float(v) * scale,
                             provisional=bool(provisional_default)))
     if dropped:
-        _LOG.warning("The price feed gave no price for %d of %d times (index "
-                     "%s). Those times are left out, not counted as free.",
-                     len(dropped), len(times),
+        _LOG.warning("The price feed gave no price for %d of %s, at index "
+                     "%s. Those are left out, not counted as free.",
+                     len(dropped), messages.count(len(times), "time"),
                      ", ".join(str(i) for i in dropped[:5])
-                     + (", ..." if len(dropped) > 5 else ""))
+                     + (" and more" if len(dropped) > 5 else ""))
     if not out:
         raise SourceUnavailable(
             f"the feed carried {len(times)} instants and a price for none of "
@@ -2106,12 +2107,12 @@ async def load_prices(opts: dict, since: datetime, until: datetime,
     pid = provider_id(opts)
     if not provider_configured(opts):
         return PriceRead.no_data(
-            "no price provider configured (price_provider is 'off'); "
-            "§11.4: static profile, plan provisional, no arbitrage")
+            "no price feed is set (price_provider is 'off'), so the fixed "
+            "tariff is used, the plan is estimated and there is no trading")
     cls = PROVIDERS.get(pid)
     if cls is None:
         return PriceRead.no_data(
-            f"unknown price provider {pid!r}; shipped: "
+            f"unknown price provider {pid!r}. The known ones are "
             f"{', '.join(sorted(PROVIDERS))}")
 
     caps = cls.capabilities()

goodwe_controller/app/price_forecast.py

@@ -164,6 +164,7 @@ from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from enum import Enum
 
+from . import messages
 from .maintenance import CHARGE_TIMEOUT_MIN, DRAIN_TIMEOUT_MIN
 from .price import PricePoint, PriceRead, _Outcome, brussels
 
@@ -411,13 +412,14 @@ def fill_from_yesterday(read: PriceRead, *, yesterday: PriceRead,
 
     if not out:
         reason = read.match(
-            series=lambda r: (f"the {len(r.points)} published hours all fall "
-                              f"outside {since.isoformat()}..{until.isoformat()}"),
+            series=lambda r: (f"all {messages.count(len(r.points), 'published price')} "
+                              f"fall outside {messages.when(brussels(since))} to "
+                              f"{messages.when(brussels(until))}"),
             no_data=lambda r: r.reason)
         return PriceRead.no_data(
-            f"§8.3 carry-forward produced no hours: {reason}, and yesterday's "
-            f"profile has nothing to fill them with either. §11.4 applies: "
-            f"static profile, plan provisional, no arbitrage")
+            f"no hours could be filled from yesterday's prices: {reason}. So "
+            f"the fixed tariff is used, the plan is estimated and there is no "
+            f"trading")
 
     _audit(out, published)
     carried = sum(1 for p in out if _utc_hour(p.start) not in published)
@@ -431,10 +433,11 @@ def fill_from_yesterday(read: PriceRead, *, yesterday: PriceRead,
         # hours" about a 48-hour horizon. The fill's unit is the HOUR and the
         # feed's is the POINT; nothing derived from one answers for the other.
         total_h = len({_utc_hour(p.start) for p in out})
-        _LOG.info("§8.3: %d of %d hours carried forward from yesterday's "
-                  "profile and flagged provisional; the feed published %d "
-                  "points over the other %d hours",
-                  carried, total_h, len(out) - carried, total_h - carried)
+        _LOG.info("%d of %s use yesterday's prices, marked as estimated. "
+                  "The feed published %s over the other %s.",
+                  carried, messages.count(total_h, "hour"),
+                  messages.count(len(out) - carried, "price"),
+                  messages.count(total_h - carried, "hour"))
 
     product = read.match(series=lambda r: r.product,
                          no_data=lambda _r: yesterday.product)
@@ -525,8 +528,8 @@ class _Permitted(Gate):
                 "one rule this type has.")
         self.action = action
         self.hours = pts
-        self.words = (f"{action.name} permitted on {len(pts)} firm hours "
-                      f"({pts[0].start.isoformat()} ..)")
+        self.words = (f"allowed on {messages.count(len(pts), 'published price')} "
+                      f"from {messages.when(brussels(pts[0].start))}")
 
 
 class _Blocked(Gate):
@@ -570,8 +573,8 @@ def price_permits(read: PriceRead, now: datetime,
     return read.match(
         series=lambda r: _walk(r, hours, action),
         no_data=lambda r: Gate.block(
-            f"{action.name} is gated on a price and there is no price data: "
-            f"{r.reason}. §11.4 - and a missing price is not a cheap one"))
+            f"{action.name} needs a price and there is none: {r.reason}. A "
+            f"missing price is not a cheap one"))
 
 
 def _walk(series, hours, action) -> Gate:
@@ -579,19 +582,18 @@ def _walk(series, hours, action) -> Gate:
     for u in hours:
         if not series.covers(u):
             return Gate.block(
-                f"{action.name} commits {action.commits_h:g} h from "
-                f"{hours[0].isoformat()} and no price covers "
-                f"{u.isoformat()}. An hour outside the series is an hour with "
-                f"no price (§11.4 for that hour), not a free one")
+                f"{action.name} needs prices for {action.commits_h:g} hours "
+                f"from {messages.when(brussels(hours[0]))}, and no price "
+                f"covers {messages.when(brussels(u))}. An hour with no price "
+                f"is not a free one")
         p = series.at(u)
         if p.provisional:
             return Gate.block(
-                f"{action.name} commits {action.commits_h:g} h from "
-                f"{hours[0].isoformat()} and {u.isoformat()} is PROVISIONAL - "
-                f"carried from yesterday's profile or standing in for a dead "
-                f"feed. §8.3: no irreversible action may be taken on a "
-                f"provisional price. It becomes available when the day-ahead "
-                f"print lands (~14-16 h CET, §5.4)")
+                f"{action.name} needs prices for {action.commits_h:g} hours "
+                f"from {messages.when(brussels(hours[0]))}, and the price for "
+                f"{messages.when(brussels(u))} is only estimated. It can start "
+                f"once the day-ahead prices are published, around 14:00 to "
+                f"16:00")
         pts.append(p)
     return Gate.permit(action, pts)
 
@@ -622,5 +624,6 @@ def _go(maint, now, gate) -> Gate:
 
 
 def _no(gate) -> Gate:
-    _LOG.warning("irreversible action refused - %s", gate.reason)
+    _LOG.warning("An action that cannot be undone does not start: %s.",
+                 gate.reason)
     return gate

goodwe_controller/app/price_history.py

@@ -186,8 +186,9 @@ import json
 import logging
 import os
 import tempfile
-from datetime import datetime, timedelta, timezone
+from datetime import date, datetime, timedelta, timezone
 
+from . import messages
 from .price import PricePoint, PriceProduct, PriceRead, brussels
 from .price_forecast import fill_from_yesterday
 
@@ -345,8 +346,19 @@ def _row_of(day: str, points: int, hours: int) -> str:
     whole day to carry, and that is the HOUR figure; the point count says how
     finely it is priced. Neither answers for the other.
     """
-    return (f"{day} ({points} price{'' if points == 1 else 's'} "
-            f"over {hours} hour{'' if hours == 1 else 's'})")
+    # UX-10: the day as the page writes dates ("26 Sep"), not ISO.
+    return (f"{points} price{'' if points == 1 else 's'} over {hours} "
+            f"hour{'' if hours == 1 else 's'} for {day_words(day)}")
+
+
+def day_words(day) -> str:
+    """`'2026-09-26'` -> `'26 Sep'`, as the page writes a date. A key that is
+    not a date is shown as it is, because this feeds a status row."""
+    try:
+        d = date.fromisoformat(str(day))
+    except ValueError:
+        return str(day)
+    return f"{d.day} {d:%b}"
 
 
 def _bad_rows(rec) -> int:
@@ -393,9 +405,8 @@ class PriceHistory:
             self.last_error = f"no durable volume at {parent}"
             # INFO, not ERROR: on a dev host or in a test container there is no
             # /data and nothing is wrong.
-            _LOG.info("no price history: %s - §8.3 carry-forward has nothing "
-                      "to carry and the horizon stays as short as the feed",
-                      self.last_error)
+            _LOG.info("No price history is kept (%s), so missing hours are "
+                      "not filled from yesterday's prices.", self.last_error)
             return
         self.ok = True
         self._load()
@@ -449,15 +460,15 @@ class PriceHistory:
         # would not notice a writer this build has never met.
         if not isinstance(blob, dict) or isinstance(found, bool) \
                 or not isinstance(found, int) or found != SCHEMA:
-            self.last_error = f"schema {found!r}, not {SCHEMA}"
-            _LOG.warning("price history at %s has %s - discarding it rather "
-                         "than guessing what its points mean",
+            self.last_error = f"version {found!r}, not {SCHEMA}"
+            _LOG.warning("Price history at %s has %s, so it is not used.",
                          self.path, self.last_error)
             return
         days = blob.get("days")
         if not isinstance(days, dict):
-            self.last_error = "no `days` object"
-            _LOG.warning("price history at %s has %s", self.path, self.last_error)
+            self.last_error = "no days in it"
+            _LOG.warning("Price history at %s has %s, so it is not used.",
+                         self.path, self.last_error)
             return
         self._days = self._usable_days(days)
 
@@ -504,20 +515,22 @@ class PriceHistory:
             kept[key] = rec
         notes = []
         if dropped:
-            notes.append(f"{len(dropped)} unusable day record(s) dropped "
-                         f"({', '.join(sorted(dropped))})")
+            notes.append(f"{messages.count(len(dropped), 'unusable day')} "
+                         f"dropped, " + ", ".join(day_words(d)
+                                                  for d in sorted(dropped)))
         if malformed:
             notes.append(
-                f"{sum(malformed.values())} malformed point row(s) in "
-                + ", ".join(f"{d} ({n})" for d, n in sorted(malformed.items())))
+                f"{messages.count(sum(malformed.values()), 'bad price')} in "
+                + ", ".join(f"{day_words(d)} ({n})"
+                            for d, n in sorted(malformed.items())))
         if notes:
             # Recorded, not silent: `yesterday()` and `words` both report
             # `last_error`, and a cache that quietly discards half a file reads
             # to an operator exactly like a normal first day.
-            self.last_error = "; ".join(notes)
-            _LOG.warning("price history at %s: %s - the controller starts "
-                         "anyway and the horizon is as short as the feed makes "
-                         "it", self.path, self.last_error)
+            self.last_error = " and ".join(notes)
+            _LOG.warning("Price history at %s: %s. The add-on starts anyway, "
+                         "and fills in only what the rest holds.",
+                         self.path, self.last_error)
         return kept
 
     def _save(self) -> bool:
@@ -680,10 +693,11 @@ class PriceHistory:
             # undone with the rest of the merge, so those rows are still in the
             # file and the next write that completes drops them again.
             self.last_error = (
-                f"{sum(junked.values())} malformed point row(s) dropped from "
-                + ", ".join(f"{d} ({n})" for d, n in sorted(junked.items())))
-            _LOG.warning("price history at %s: %s - the record is rewritten "
-                         "without them and the refresh continues",
+                f"{messages.count(sum(junked.values()), 'bad price')} dropped "
+                f"from " + ", ".join(f"{day_words(d)} ({n})"
+                                     for d, n in sorted(junked.items())))
+            _LOG.warning("Price history at %s: %s. The file is saved without "
+                         "them and the price update goes on.",
                          self.path, self.last_error)
         self._prune(stamp)
         if not self._save():
@@ -752,21 +766,23 @@ class PriceHistory:
         if self.last_error and not self._days:
             return PriceRead.no_data(
                 f"the price history at {self.path} is {self.last_error}, so "
-                f"§8.3 has no profile to carry forward for {want}; the plan "
-                f"covers only the hours the feed published")
+                f"there are no prices from yesterday to fill in for "
+                f"{day_words(want)}. The plan covers only the hours the feed "
+                f"published")
         rec = self._days.get(want)
         if rec is None:
-            have = ", ".join(sorted(self._days)) or "no days at all"
+            have = (", ".join(day_words(d) for d in sorted(self._days))
+                    or "no days at all")
             return PriceRead.no_data(
-                f"no published prices recorded for {want} (held: {have}), so "
-                f"§8.3 has no profile to carry forward. A record for another "
-                f"day is not a yesterday")
+                f"no published prices are kept for {day_words(want)}, only for "
+                f"{have}, so there are no prices from yesterday to fill in. A "
+                f"record for another day is not a yesterday")
         points, bad = _parse_points(rec.get("points"))
         if not points:
             why = bad or "it is empty"
             return PriceRead.no_data(
-                f"the {want} record holds no usable point ({why}), and an "
-                f"empty series is not a free day")
+                f"the {day_words(want)} record holds no usable price, {why}, "
+                f"and an empty series is not a free day")
         try:
             product = PriceProduct(rec.get("product"))
         except ValueError:
@@ -775,8 +791,9 @@ class PriceHistory:
                 f"which is not a PriceProduct. The optimiser switches on that "
                 f"enum, so a record that cannot name one cannot be a series")
         if bad:
-            _LOG.warning("Price history: %s in the %s record were dropped, "
-                         "and %d points were kept.", bad, want, len(points))
+            _LOG.warning("Price history: %s dropped from the %s record, and "
+                         "%s kept.", bad, day_words(want),
+                         messages.count(len(points), "price"))
         return PriceRead.series(points, product,
                                 str(rec.get("provider") or "price_history"),
                                 stamp)
@@ -805,7 +822,7 @@ class PriceHistory:
         if not self._days:
             why = f" - {self.last_error}" if self.last_error else ""
             return f"empty{why} - nothing to carry forward yet"
-        held = "; ".join(_row_of(d, *_held(self._days[d]))
+        held = ", ".join(_row_of(d, *_held(self._days[d]))
                          for d in sorted(self._days, key=str))
         # A file that PARTLY loaded says so, or the dropped days read as days
         # that were simply never written.
@@ -833,7 +850,7 @@ def _parse_points(raw) -> tuple:
             continue
         out.append(pt)
     out.sort(key=lambda p: p.start.astimezone(timezone.utc))
-    return tuple(out), (f"{dropped} malformed point(s)" if dropped else "")
+    return tuple(out), (messages.count(dropped, "bad price") if dropped else "")
 
 
 class NoHistory:
@@ -861,5 +878,5 @@ class NoHistory:
 
     def yesterday(self, stamp: datetime) -> PriceRead:
         return PriceRead.no_data(
-            "this caller keeps no price history (NoHistory), so §8.3 has no "
-            "profile to carry forward")
+            "this caller keeps no price history, so there are no prices from "
+            "yesterday to fill in")

goodwe_controller/app/selfconfig.py

@@ -82,6 +82,7 @@ import os
 
 import aiohttp
 
+from . import messages
 from .configui import changed_keys
 from .inverter import build_roster
 from .validate import validate_startup_config, validate_unit_ranges
@@ -287,7 +288,7 @@ async def problems_for(opts: dict, hass=None) -> list:
     return problems
 
 
-async def problems_and_ranges(opts: dict, hass=None):
+async def problems_and_ranges(opts: dict, hass=None, notes=None):
     """`problems_for()`, plus WHICH setpoint entities did not report a range.
 
     ⚠️ THE SECOND HALF EXISTS SO THE PAGE CANNOT LOOK GREEN FOR A REASON THE
@@ -302,6 +303,8 @@ async def problems_and_ranges(opts: dict, hass=None):
     has just typed a new `setpoint_entity` must be told about THAT entity, and
     a route that asked the running controller instead would report on the old
     one. That was the first shape of this and it disagreed with itself.
+
+    UX-13: a list passed as `notes` collects the validator's warnings too.
     """
     flat = str(opts.get("setpoint_entity", "") or "").strip()
 
@@ -328,7 +331,7 @@ async def problems_and_ranges(opts: dict, hass=None):
         # disagreement is itself the finding - so it is reported rather than
         # swallowed. Returning `[]` here would turn a crash into a silent
         # acceptance, which is worse than the 500 this replaced.
-        found = list(validate_startup_config(opts))
+        found = list(validate_startup_config(opts, notes=notes))
         if not found:
             found = [f"the configuration could not be composed ({type(exc).__name__}: "
                      f"{exc}), and the validator did not name a reason. This is a "
@@ -346,7 +349,8 @@ async def problems_and_ranges(opts: dict, hass=None):
         if flat and unit.setpoint_entity.strip().lower() == flat.lower():
             dev_min, dev_max = unit.dev_min, unit.dev_max
             break
-    problems = list(validate_startup_config(opts, dev_min, dev_max))
+    problems = list(validate_startup_config(opts, dev_min, dev_max,
+                                            notes=notes))
     problems += validate_unit_ranges(units, skip_entity=flat)
     unread = [unit.setpoint_entity for unit in units
               if unit.setpoint_entity and unit.dev_min is None
@@ -381,8 +385,9 @@ async def save(selfcfg: SelfConfig, proposed: dict, expect: str, *,
     """
     problems = await problems_for(proposed, hass)
     if problems:
-        _LOG.warning("The settings page did not save, because of %d "
-                     "problems. The first: %s", len(problems), problems[0])
+        _LOG.warning("The settings page did not save, because of %s. The "
+                     "first: %s", messages.count(len(problems), "problem"),
+                     problems[0])
         raise SaveRefused("invalid", problems=problems)
 
     info = await selfcfg.info()

goodwe_controller/app/static/app.css

@@ -0,0 +1,218 @@
+/* UX-13 page styles. Colours follow the approved mockup (UX-13-mockup.html,
+   version 2) and prefers-color-scheme. No web fonts, no external files. */
+:root{
+  --bg:#f3f4f6;--card:#ffffff;--ink:#1b1d21;--muted:#5b626c;--faint:#8a919b;--line:#e2e5e9;
+  --accent:#1c64d9;--accent-soft:#e6efff;--on-accent:#ffffff;
+  --ok:#17773a;--ok-bg:#e6f4eb;--warn:#955300;--warn-bg:#fcefd9;--bad:#c02626;--bad-bg:#fce8e8;--info:#5b626c;--info-bg:#eceef1;
+  --solar:#c98a00;--house:#6c47c2;--grid:#56657a;--batt:#17773a;
+  --cheap:#8fcca4;--dear:#f0ad72;--mid:#cfd5dc;--track:#dde1e6;--shadow:0 1px 2px rgba(0,0,0,.05);
+}
+@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){
+  --bg:#111317;--card:#1a1d23;--ink:#e7e9ec;--muted:#a2a9b3;--faint:#7c848f;--line:#2b3038;
+  --accent:#6ea2ff;--accent-soft:#1d2a44;--on-accent:#0b1220;
+  --ok:#7ccf98;--ok-bg:#15291d;--warn:#f3c16b;--warn-bg:#2e2412;--bad:#f28b82;--bad-bg:#3a1a19;--info:#a2a9b3;--info-bg:#22262d;
+  --solar:#f0c04a;--house:#b39cf0;--grid:#9fb0c6;--batt:#7ccf98;
+  --cheap:#3f7d56;--dear:#9a5a26;--mid:#3a414b;--track:#343a44;--shadow:none;
+}}
+:root[data-theme="dark"]{
+  --bg:#111317;--card:#1a1d23;--ink:#e7e9ec;--muted:#a2a9b3;--faint:#7c848f;--line:#2b3038;
+  --accent:#6ea2ff;--accent-soft:#1d2a44;--on-accent:#0b1220;
+  --ok:#7ccf98;--ok-bg:#15291d;--warn:#f3c16b;--warn-bg:#2e2412;--bad:#f28b82;--bad-bg:#3a1a19;--info:#a2a9b3;--info-bg:#22262d;
+  --solar:#f0c04a;--house:#b39cf0;--grid:#9fb0c6;--batt:#7ccf98;
+  --cheap:#3f7d56;--dear:#9a5a26;--mid:#3a414b;--track:#343a44;--shadow:none;
+}
+*{box-sizing:border-box}
+[hidden]{display:none!important}
+html{-webkit-text-size-adjust:100%}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.5 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;overflow-x:hidden}
+button,input,select{font:inherit;color:inherit}
+a{color:var(--accent)}
+:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+.top{display:flex;align-items:center;gap:12px;padding:12px 16px 8px;max-width:820px;margin:0 auto}
+.logo{width:36px;height:36px;border-radius:10px;background:var(--accent-soft);display:grid;place-items:center;color:var(--accent);flex:none}
+.app{font-weight:700;font-size:17px;line-height:1.2}
+.pill{display:flex;flex-wrap:wrap;align-items:center;gap:0 6px;font-size:13px;color:var(--muted)}
+.dot{width:8px;height:8px;border-radius:50%;background:var(--ok);flex:none}
+.dot.warn{background:var(--warn)}.dot.bad{background:var(--bad)}
+.tabs{display:flex;gap:4px;max-width:820px;margin:0 auto;padding:0 16px;border-bottom:1px solid var(--line)}
+.tab{border:0;background:none;padding:10px 12px;border-bottom:2px solid transparent;color:var(--muted);cursor:pointer;display:flex;align-items:center;gap:6px;min-height:44px;position:relative}
+.tab[aria-selected="true"]{color:var(--accent);border-bottom-color:var(--accent);font-weight:600}
+.tab svg{width:20px;height:20px}
+.badge{font-size:11px;font-weight:700;background:var(--warn);color:var(--card);border-radius:9px;padding:0 6px;line-height:18px}
+.badge.bad{background:var(--bad)}
+@media (max-width:640px){
+  .tabs{position:fixed;bottom:0;left:0;right:0;z-index:20;background:var(--card);border-top:1px solid var(--line);border-bottom:0;padding:0 4px env(safe-area-inset-bottom);justify-content:space-around;gap:0}
+  .tab{flex-direction:column;gap:0;font-size:11px;padding:6px 4px;border-bottom:0;border-top:2px solid transparent;flex:1;min-width:0}
+  .tab[aria-selected="true"]{border-top-color:var(--accent)}
+  .tab .badge{position:absolute;top:2px;left:calc(50% + 6px)}
+  .wrap{padding-bottom:96px!important}
+}
+.wrap{max-width:820px;margin:0 auto;padding:16px 16px 40px}
+h2{font-size:15px;margin:0 0 10px;font-weight:650}
+.card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:14px;margin-bottom:12px;box-shadow:var(--shadow)}
+.muted{color:var(--muted)} .small{font-size:13px} .tiny{font-size:12px}
+.row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
+.spread{justify-content:space-between}
+.grow{flex:1 1 auto;min-width:0}
+.banner{border-radius:12px;padding:12px 14px;margin-bottom:12px;display:flex;gap:10px;align-items:flex-start;font-weight:600}
+.banner .ic{flex:none;margin-top:2px}
+.b-ok{background:var(--ok-bg);color:var(--ok)} .b-warn{background:var(--warn-bg);color:var(--warn)} .b-bad{background:var(--bad-bg);color:var(--bad)}
+.banner small{display:block;font-weight:400;color:var(--ink);margin-top:2px}
+.tiles{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:8px}
+@media (max-width:640px){.tiles{grid-template-columns:repeat(2,minmax(0,1fr))}}
+.tile{border:1px solid var(--line);border-radius:10px;padding:10px;min-width:0}
+.tile .lab{font-size:13px;color:var(--muted);display:flex;align-items:center;gap:6px}
+.tile .val{font-size:22px;font-weight:700;font-variant-numeric:tabular-nums;line-height:1.25;margin-top:2px}
+.tile .val small{font-size:13px;font-weight:500;color:var(--muted)}
+.tile .sub{font-size:12px;color:var(--muted)}
+.sw-solar{color:var(--solar)} .sw-house{color:var(--house)} .sw-grid{color:var(--grid)} .sw-batt{color:var(--batt)}
+.brow{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:2px 10px;padding:10px 0;border-top:1px solid var(--line)}
+.brow:first-child{border-top:0}
+.lvl{height:10px;background:var(--track);border-radius:6px;overflow:hidden;grid-column:1/-1;margin:4px 0 2px}
+.lvl>i{display:block;height:100%;background:var(--batt);border-radius:6px}
+.lvl.none>i{background:var(--faint)}
+/* the plan chart */
+.chart{position:relative;margin:18px 0 4px}
+.bars{display:flex;align-items:flex-end;gap:2px;height:72px}
+.bars i{flex:1;border-radius:3px 3px 0 0;background:var(--mid);min-width:0}
+.bars i.cheap{background:var(--cheap)}
+/* not by colour alone: expensive hours are striped, estimates are faded */
+.bars i.dear{background:repeating-linear-gradient(135deg,var(--dear) 0 4px,color-mix(in srgb,var(--dear) 60%,var(--card)) 4px 7px)}
+.bars i.est{opacity:.55}
+.bars i.none{background:none;border-bottom:2px dotted var(--faint);height:2px!important}
+.lane{position:relative;height:18px;margin-top:4px;background:var(--bg);border-radius:4px}
+.lane b{position:absolute;top:2px;bottom:2px;border-radius:3px;min-width:3px}
+.lane .house{background:repeating-linear-gradient(90deg,var(--mid) 0 6px,transparent 6px 9px);top:6px;bottom:6px}
+.lane .grid{background:var(--accent)}
+.lane .give{background:repeating-linear-gradient(135deg,var(--house) 0 4px,color-mix(in srgb,var(--house) 55%,var(--card)) 4px 7px)}
+.lane .cycle{background:repeating-linear-gradient(90deg,var(--warn) 0 3px,var(--warn-bg) 3px 6px)}
+.lane .peak{background:var(--bad)}
+.lanelab{font-size:12px;color:var(--muted);margin-top:6px}
+.nowline{position:absolute;top:-4px;bottom:0;width:2px;background:var(--ink);opacity:.7;pointer-events:none}
+.nowline span{position:absolute;top:-15px;left:-10px;font-size:10px}
+.axis{display:flex;justify-content:space-between;font-size:11px;color:var(--faint);margin-top:4px}
+.legend{display:flex;flex-wrap:wrap;gap:4px 12px;font-size:12px;color:var(--muted);margin-top:8px}
+.legend span{display:inline-flex;align-items:center;gap:5px}
+.legend i{width:14px;height:10px;border-radius:2px;display:inline-block}
+.legend i.house{background:repeating-linear-gradient(90deg,var(--mid) 0 4px,transparent 4px 6px)}
+ul.plain{list-style:none;margin:8px 0 0;padding:0}
+ul.plain li{padding:6px 0;border-top:1px solid var(--line)}
+ul.plain li:first-child{border-top:0}
+.meter{height:12px;background:var(--track);border-radius:6px;overflow:hidden;margin:8px 0 4px}
+.meter i{display:block;height:100%;background:var(--accent)}
+.meter i.warn{background:var(--warn)} .meter i.bad{background:var(--bad)}
+.alert{display:flex;gap:10px;padding:10px 0;border-top:1px solid var(--line)}
+.alert:first-child{border-top:0}
+.sev{flex:none;width:24px;height:24px;border-radius:50%;display:grid;place-items:center;font-size:13px;font-weight:800}
+.sev.warning{background:var(--warn-bg);color:var(--warn)} .sev.alarm{background:var(--bad-bg);color:var(--bad)} .sev.info{background:var(--info-bg);color:var(--info)} .sev.ok{background:var(--ok-bg);color:var(--ok)}
+.alert .t{font-weight:600}
+.btn{border:1px solid var(--line);background:var(--card);padding:9px 14px;border-radius:10px;cursor:pointer;min-height:44px}
+.btn.primary{background:var(--accent);border-color:var(--accent);color:var(--on-accent);font-weight:600}
+.btn.danger{color:var(--bad);border-color:var(--bad)}
+.btn:disabled{opacity:.5;cursor:not-allowed}
+a.btn{display:inline-flex;align-items:center;text-decoration:none;color:var(--ink)}
+details.more{margin-top:12px;border-top:1px solid var(--line)}
+details.more>summary{cursor:pointer;padding:10px 0;color:var(--accent);font-size:14px;min-height:44px;display:flex;align-items:center}
+table.rows{width:100%;border-collapse:collapse;font-size:13px}
+table.rows td{padding:6px 0;border-bottom:1px solid var(--line);vertical-align:top}
+table.rows td:last-child{text-align:right;font-variant-numeric:tabular-nums;font-weight:600;padding-left:12px;overflow-wrap:anywhere}
+table.rows tr:last-child td{border-bottom:0}
+ul.checks{margin:6px 0 0;padding-left:0;list-style:none;font-size:13px}
+ul.checks li{margin:3px 0}
+.c-ok{color:var(--ok)} .c-warn{color:var(--warn)} .c-bad{color:var(--bad)}
+.kv{display:grid;grid-template-columns:auto minmax(0,1fr);gap:4px 12px;font-size:14px;margin-top:10px}
+.kv dt{color:var(--muted)} .kv dd{margin:0}
+#toast{position:fixed;left:50%;transform:translateX(-50%);bottom:24px;z-index:30;background:var(--ink);color:var(--bg);padding:10px 14px;border-radius:10px;font-size:14px;max-width:calc(100% - 32px);opacity:0;pointer-events:none;transition:opacity .2s}
+#toast.show{opacity:1}
+@media (max-width:640px){#toast{bottom:84px}}
+dialog{border:1px solid var(--line);border-radius:14px;background:var(--card);color:var(--ink);max-width:min(420px,calc(100% - 32px));padding:18px}
+dialog::backdrop{background:rgba(0,0,0,.45)}
+@media (prefers-reduced-motion:reduce){*{transition:none!important}}
+.tip{position:fixed;z-index:40;background:var(--ink);color:var(--bg);font-size:12px;line-height:1.35;padding:6px 8px;border-radius:8px;pointer-events:none;max-width:240px;opacity:0;transition:opacity .1s;box-shadow:0 2px 8px rgba(0,0,0,.25);left:0;top:0}
+.tip.show{opacity:1}
+.tip b{display:block;font-weight:700}
+.tip span{display:block}
+.chart [data-tip]{cursor:default}
+.chart [data-tip]:hover,.chart [data-tip]:focus,.chart .hot{outline:2px solid var(--ink);outline-offset:-1px}
+.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
+/* UX-13 P2: Settings, the Installer view (mockup version 2) */
+.btn.link{border:0;background:none;color:var(--accent);padding:6px 0;min-height:0}
+.search{width:100%;border:1px solid var(--line);background:var(--card);border-radius:10px;padding:10px 12px;min-height:44px;margin-bottom:10px}
+.key{font:11px/1.3 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--faint);overflow-wrap:anywhere}
+.chip{display:inline-flex;align-items:center;gap:4px;font-size:12px;border-radius:999px;padding:1px 8px;background:var(--info-bg);color:var(--muted);white-space:nowrap}
+.chip.now{background:var(--ok-bg);color:var(--ok)} .chip.rs{background:var(--warn-bg);color:var(--warn)}
+.chip.bad{background:var(--bad-bg);color:var(--bad)} .chip.changed{background:var(--accent-soft);color:var(--accent)}
+details.grp{background:var(--card);border:1px solid var(--line);border-radius:12px;margin-bottom:10px;box-shadow:var(--shadow)}
+details.grp>summary{list-style:none;cursor:pointer;padding:14px;display:flex;gap:10px;align-items:center;min-height:56px;flex-wrap:wrap}
+details.grp>summary::-webkit-details-marker{display:none}
+details.grp>summary .grow{flex:1 1 200px}
+details.grp>summary .gdesc{display:block}
+details.grp>summary .chev{transition:transform .15s;flex:none;font-size:22px;line-height:1;width:18px;text-align:center;color:var(--muted)}
+details.grp[open]>summary .chev{transform:rotate(90deg)}
+.gchips,.gbadge{display:inline-flex;flex-wrap:wrap;gap:4px}
+details.grp .body{padding:0 14px 8px}
+details.sub{border-top:1px solid var(--line);margin-top:4px}
+details.sub>summary{cursor:pointer;padding:10px 0;color:var(--accent);font-size:14px;min-height:44px;display:flex;align-items:center}
+.subhead{font-size:12px;text-transform:uppercase;letter-spacing:.04em;color:var(--faint);margin:14px 0 0;font-weight:700}
+.f{padding:12px 0;border-top:1px solid var(--line);min-width:0}
+.part>.f:first-child,.subhead+.f{border-top:0}
+.f .lbl{font-weight:600;font-size:14px}
+.f .help{font-size:13px;color:var(--muted);margin-top:4px}
+.f .ctl{margin-top:8px;min-width:0}
+.f.inline{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:4px 12px;align-items:start}
+.f.inline .ctl{margin-top:0;grid-row:1;grid-column:2}
+.f.inline .help,.f.inline .msgs{grid-column:1/-1}
+.f.changed>.head .lbl::after{content:" •";color:var(--accent)}
+.msg{font-size:13px;margin-top:6px;display:flex;gap:6px;align-items:flex-start;border-radius:8px;padding:6px 8px;overflow-wrap:anywhere}
+.msg .mi{font-weight:800;flex:none}
+.msg.bad{background:var(--bad-bg);color:var(--bad)} .msg.warn{background:var(--warn-bg);color:var(--warn)} .msg.info{background:var(--info-bg);color:var(--info)}
+.f.has-bad .ctl select,.f.has-bad .ctl input,.f.has-bad .ent-btn{border-color:var(--bad)}
+.switch{position:relative;width:52px;height:44px;border:0;background:none;cursor:pointer;flex:none;padding:0}
+.switch::before{content:"";position:absolute;left:2px;top:8px;width:48px;height:28px;border-radius:14px;background:var(--track);transition:background .15s}
+.switch::after{content:"";position:absolute;top:11px;left:5px;width:22px;height:22px;border-radius:50%;background:#fff;box-shadow:0 1px 2px rgba(0,0,0,.3);transition:left .15s}
+.switch[aria-checked="true"]::before{background:var(--accent)}
+.switch[aria-checked="true"]::after{left:25px}
+.swrap{display:inline-flex;align-items:center;gap:8px;min-height:44px}
+.swtext{font-size:13px;color:var(--muted)}
+select.sel,input.txt,input.num{border:1px solid var(--line);background:var(--card);border-radius:10px;padding:9px 10px;min-height:44px;max-width:100%}
+select.sel{width:100%}
+.row>select.sel{width:auto;flex:1 1 200px}
+input.num{width:110px;text-align:right;font-variant-numeric:tabular-nums}
+input.txt{width:100%}
+input:disabled{opacity:.6}
+.seg{display:inline-flex;border:1px solid var(--line);border-radius:10px;overflow:hidden;max-width:100%;flex-wrap:wrap}
+.seg button{border:0;background:var(--card);padding:8px 12px;min-height:44px;cursor:pointer;border-left:1px solid var(--line)}
+.seg button:first-child{border-left:0}
+.seg button[aria-checked="true"]{background:var(--accent-soft);color:var(--accent);font-weight:600}
+.choice{display:flex;gap:10px;align-items:flex-start;border:1px solid var(--line);border-radius:10px;padding:10px 12px;margin-top:8px;cursor:pointer;width:100%;text-align:left;background:var(--card);min-height:44px}
+.choice[aria-checked="true"]{border-color:var(--accent);background:var(--accent-soft)}
+.choice .rad{flex:none;width:18px;height:18px;border-radius:50%;border:2px solid var(--faint);margin-top:2px}
+.choice[aria-checked="true"] .rad{border:5px solid var(--accent)}
+.slider{display:flex;align-items:center;gap:10px;width:100%}
+.slider input[type=range]{flex:1;min-width:0;accent-color:var(--accent);height:28px}
+.unit{color:var(--muted);font-size:13px;white-space:nowrap}
+.ent-btn{width:100%;text-align:left;border:1px solid var(--line);background:var(--card);border-radius:10px;padding:8px 10px;min-height:44px;cursor:pointer;display:flex;gap:8px;align-items:center}
+.ent-btn .grow{min-width:0}
+.ent-btn .grow>div{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.ent-pop{border:1px solid var(--line);border-radius:10px;margin-top:6px;background:var(--card);overflow:hidden}
+.ent-pop input[type=search]{border:0;border-bottom:1px solid var(--line);width:100%;padding:10px;background:var(--card);min-height:44px}
+.ent-note{padding:6px 10px}
+.ent-list{max-height:240px;overflow:auto}
+.ent-opt{display:flex;gap:8px;align-items:center;width:100%;border:0;border-bottom:1px solid var(--line);background:none;text-align:left;padding:8px 10px;cursor:pointer;min-height:44px}
+.ent-opt:hover,.ent-opt:focus{background:var(--accent-soft)}
+.ent-opt .grow{min-width:0}
+.ent-opt .grow>div{overflow-wrap:anywhere}
+.ent-opt .v{font-variant-numeric:tabular-nums;font-size:13px;color:var(--muted);white-space:nowrap}
+.ent-all{display:flex;gap:6px;padding:6px 10px;align-items:center;min-height:44px}
+.elist .erow{padding:6px 0;border-bottom:1px dashed var(--line)}
+.elist>.btn{margin-top:8px}
+.inv{border:1px solid var(--line);border-radius:10px;padding:0 12px;margin:10px 0}
+.inv>.hd{display:flex;align-items:center;gap:8px;padding:10px 0;border-bottom:1px solid var(--line);font-weight:600;flex-wrap:wrap}
+.inv>.f:nth-child(2){border-top:0}
+.invs>.btn{margin:4px 0 8px}
+#savebar{position:fixed;left:0;right:0;bottom:0;z-index:15}
+#savebar .in{max-width:820px;margin:0 auto 10px;padding:10px 12px;background:var(--ink);color:var(--bg);border-radius:12px;display:flex;flex-wrap:wrap;gap:8px;align-items:center;box-shadow:0 4px 16px rgba(0,0,0,.25);width:calc(100% - 32px)}
+#savebar .btn{min-height:44px;padding:6px 12px;background:transparent;color:var(--bg);border-color:rgba(127,127,127,.6)}
+#savebar .btn.primary{background:var(--accent);border-color:var(--accent);color:var(--on-accent)}
+@media (max-width:640px){#savebar{bottom:62px}}
+#s-set{padding-bottom:80px}

goodwe_controller/app/static/app.js

@@ -0,0 +1,375 @@
+"use strict";
+/* UX-13 P1: the page shell and the Home screen. Plain JS, no framework, no
+   external files. Every URL is relative, because ingress serves the add-on
+   under a generated path prefix. Every word comes from app/ui_text (fixed
+   labels) or from /status (sentences built by app/homeview.py), so STYLE.md
+   is checked in Python. Data is always set as text, never as HTML. */
+(function () {
+  const T = JSON.parse(document.getElementById("ui-text").textContent).home;
+  const $ = (s) => document.querySelector(s);
+  const t = (path) => path.split(".").reduce((o, k) => (o == null ? o : o[k]), T);
+  function h(tag, attrs, ...kids) {
+    const e = document.createElement(tag);
+    for (const k in attrs || {}) {
+      const v = attrs[k];
+      if (v === false || v == null) continue;
+      if (k === "class") e.className = v;
+      else if (k === "style") e.style.cssText = v;
+      else if (k.startsWith("on")) e.addEventListener(k.slice(2), v);
+      else e.setAttribute(k, v === true ? "" : v);
+    }
+    for (const c of kids.flat()) {
+      if (c == null || c === false) continue;
+      e.append(c.nodeType ? c : document.createTextNode(String(c)));
+    }
+    return e;
+  }
+  const kw = (w) => (Math.abs(Number(w)) / 1000).toFixed(1);
+  const eur = (v) => "€" + Number(v).toFixed(2);
+
+  // Fixed labels from ui_text.
+  document.querySelectorAll("[data-t]").forEach((e) => { e.textContent = t(e.dataset.t) || ""; });
+  document.querySelectorAll("[data-t-label]").forEach((e) => { e.setAttribute("aria-label", t(e.dataset.tLabel) || ""); });
+
+  let S = null;              // the last /status
+  let busy = false;
+
+  /* ---------------- toast and confirm dialog ---------------- */
+  function toast(text) {
+    const e = $("#toast"); e.textContent = text; e.classList.add("show");
+    clearTimeout(toast.timer); toast.timer = setTimeout(() => e.classList.remove("show"), 2600);
+  }
+  let onYes = null;
+  // `key` names Home's words in ui_text, or is {name, description, yes}.
+  function ask(key, fn) {
+    const w = typeof key === "string" ? t("dialog." + key) : key;
+    $("#dlg-t").textContent = w.name;
+    $("#dlg-b").textContent = w.description;
+    $("#dlg-yes").textContent = w.yes;
+    onYes = fn;
+    const d = $("#dlg");
+    if (typeof d.showModal === "function") d.showModal(); else if (window.confirm($("#dlg-t").textContent)) fn();
+  }
+  $("#dlg-no").addEventListener("click", () => $("#dlg").close());
+  $("#dlg-yes").addEventListener("click", () => { $("#dlg").close(); if (onYes) onYes(); });
+
+  /* ---------------- data ---------------- */
+  async function getStatus() {
+    const r = await fetch("status", { cache: "no-store" });
+    if (!r.ok) throw new Error("status " + r.status);
+    return r.json();
+  }
+  async function act(what) {
+    const r = await fetch("action", { method: "POST", headers: { "Content-Type": "application/json" },
+                                      body: JSON.stringify({ action: what }) });
+    if (!r.ok) throw new Error("action " + r.status);
+    return r.json();
+  }
+  async function refresh() {
+    if (busy) return;
+    busy = true;
+    try { S = await getStatus(); render(); }
+    catch (e) { offline(); }
+    finally { busy = false; }
+  }
+
+  /* ---------------- shell ---------------- */
+  function banner(el, level, title, sub, role) {
+    el.replaceChildren(h("div", { class: "banner " + ({ ok: "b-ok", bad: "b-bad" }[level] || "b-warn"), role: role || null },
+      h("span", { class: "ic", "aria-hidden": "true" }, { ok: "✓", bad: "×" }[level] || "!"),
+      h("span", {}, title, sub ? h("small", {}, sub) : null)));
+  }
+  function offline() {
+    banner($("#home-banner"), "bad", t("offline.name"), t("offline.description"), "alert");
+    $("#pill").replaceChildren(h("span", { class: "dot bad" }), h("span", {}, t("offline.name")));
+  }
+  function renderPill() {
+    const st = S.state || null;
+    const dot = st ? ({ running: "", shadow: " warn", stopped: " warn", warning: " warn", alarm: " bad" }[st.kind] ?? " warn")
+                   : (S.level === "ok" ? "" : S.level === "bad" ? " bad" : " warn");
+    const words = st ? [st.pill, st.ran].filter(Boolean).join(". ") : S.banner;
+    $("#pill").replaceChildren(h("span", { class: "dot" + dot, "aria-hidden": "true" }), h("span", {}, words));
+  }
+
+  function render() {
+    renderPill();
+    const structured = S.now && S.plan && !S.home_error;
+    banner($("#home-banner"), S.level, S.banner, structured ? S.state.sub : "", S.level === "bad" ? "alert" : null);
+    ["#c-now", "#c-plan", "#c-peak", "#c-attn"].forEach((id) => { $(id).hidden = !structured; });
+    if (structured) { renderNow(); renderPlan(); renderPeak(); renderAttention(); }
+    renderControl(structured);
+    renderDetails(!structured);
+    renderBatteries();
+  }
+
+  /* ---------------- Home: now ---------------- */
+  function val(id, w, show) {
+    const e = $(id);
+    if (w == null || !show) { e.textContent = "–"; return; }
+    e.replaceChildren(kw(w) + " ", h("small", {}, "kW"));
+  }
+  function levelBar(pct, label) {
+    const known = pct != null;
+    return h("div", { class: "lvl" + (known ? "" : " none"), role: "img",
+                      "aria-label": label + " " + (known ? Math.round(pct) + " %" : "–") },
+      h("i", { style: "width:" + (known ? Math.max(0, Math.min(100, pct)) : 0) + "%" }));
+  }
+  function renderNow() {
+    const n = S.now;
+    val("#v-solar", n.solar_w, n.has_solar); $("#sub-solar").textContent = n.lines.solar;
+    val("#v-house", n.house_w, true); $("#sub-house").textContent = n.lines.house;
+    val("#v-grid", n.grid_w, true); $("#sub-grid").textContent = n.lines.grid;
+    val("#v-batt", n.batt_w, true); $("#sub-batt").textContent = n.lines.batt;
+    $("#home-batts").replaceChildren(...S.batteries.map((b) => h("div", { class: "brow" },
+      h("div", {}, h("strong", {}, b.name), h("span", { class: "muted small" }, " · " + b.mode)),
+      h("div", { class: "small", style: "font-variant-numeric:tabular-nums" }, b.level_pct == null ? "–" : Math.round(b.level_pct) + " %"),
+      levelBar(b.level_pct, b.name),
+      h("div", { class: "small muted", style: "grid-column:1/-1" }, b.now))));
+  }
+
+  /* ---------------- Home: today's plan ---------------- */
+  const LEGEND = [["cheap", "background:var(--cheap)"], ["dear", "background:repeating-linear-gradient(135deg,var(--dear) 0 3px,transparent 3px 5px)"],
+                  ["grid", "background:var(--accent)"], ["give", "background:repeating-linear-gradient(135deg,var(--house) 0 3px,transparent 3px 5px)"],
+                  ["cycle", "background:repeating-linear-gradient(90deg,var(--warn) 0 2px,transparent 2px 4px)"],
+                  ["peak", "background:var(--bad)"], ["house", null]];
+  function tipText(lines) { return lines.filter(Boolean).join(" "); }
+  function chartItem(tag, cls, style, title, lines) {
+    return h(tag, { class: cls, style: style, tabindex: "-1", role: "img", "aria-label": tipText([title + "."].concat(lines)),
+                    "data-tip": JSON.stringify([title].concat(lines.filter(Boolean))) });
+  }
+  function roving(group) {
+    const items = [...group.querySelectorAll("[data-tip]")];
+    items.forEach((el, i) => {
+      el.tabIndex = i === 0 ? 0 : -1;
+      el.addEventListener("keydown", (e) => {
+        const d = { ArrowRight: 1, ArrowLeft: -1, Home: -1e9, End: 1e9 }[e.key];
+        if (d === undefined) return;
+        e.preventDefault();
+        const j = Math.max(0, Math.min(items.length - 1, i + d));
+        items[i].tabIndex = -1; items[j].tabIndex = 0; items[j].focus();
+      });
+    });
+  }
+  function renderPlan() {
+    const p = S.plan;
+    $("#verdict").textContent = p.verdict;
+    $("#plan-head").textContent = p.head;
+    const hours = p.hours || 24;
+    const bars = $("#bars");
+    const known = p.prices.filter((b) => b.eur_kwh != null);
+    const mx = Math.max(0.01, ...known.map((b) => Math.abs(b.eur_kwh)));
+    bars.setAttribute("aria-label", t("plan.name"));
+    bars.replaceChildren(...p.prices.map((b) => {
+      const title = b.label + " " + t("plan.time_to") + " " + b.end_label;
+      if (b.eur_kwh == null) return chartItem("i", "none", "", title, [t("plan.none_tip") + "."]);
+      const kind = b.kind === "cheap" ? ", " + t("plan.cheap_tip") : b.kind === "dear" ? ", " + t("plan.dear_tip") : "";
+      const est = (b.points > 1 ? ", " + t("plan.average_tip") : "") + (b.estimate ? ", " + t("plan.estimate_tip") : "");
+      return chartItem("i", (b.kind || "mid") + (b.estimate ? " est" : ""),
+                       "height:" + Math.max(4, Math.round(Math.abs(b.eur_kwh) / mx * 100)) + "%",
+                       title, [eur(b.eur_kwh) + " " + t("plan.per_kwh") + kind + est + "."]);
+    }));
+    roving(bars);
+    $("#no-prices").hidden = known.length > 0;
+    const lanes = $("#lanes");
+    lanes.replaceChildren();
+    S.batteries.forEach((b, i) => {
+      const lane = h("div", { class: "lane", role: "group", "aria-label": b.name });
+      const runs = p.runs.filter((r) => r.battery === i).sort((a, z) => (a.kind === "house" ? -1 : 0) - (z.kind === "house" ? -1 : 0));
+      for (const r of runs) {
+        if (r.end_h <= r.start_h) continue;
+        lane.append(chartItem("b", r.kind, "left:" + (r.start_h / hours * 100) + "%;width:" + ((r.end_h - r.start_h) / hours * 100) + "%",
+                              b.name + ", " + r.from + " " + t("plan.time_to") + " " + r.to, [r.what, r.why, r.amount]));
+      }
+      lanes.append(h("div", { class: "lanelab", "aria-hidden": "true" }, b.name), lane);
+      roving(lane);
+    });
+    const nl = $("#nowline");
+    nl.style.left = Math.max(0, Math.min(100, p.now_h / hours * 100)) + "%";
+    const used = new Set(p.runs.map((r) => r.kind));
+    known.forEach((b) => used.add(b.kind));
+    $("#legend").replaceChildren(...LEGEND.filter(([k]) => used.has(k)).map(([k, css]) =>
+      h("span", {}, h("i", { class: k === "house" ? "house" : null, style: css, "aria-hidden": "true" }), t("plan." + k))));
+    const list = [];
+    S.batteries.forEach((b, i) => {
+      for (const r of p.runs.filter((x) => x.battery === i && x.kind !== "house")) {
+        list.push(h("li", {}, h("strong", {}, b.name + ", " + r.from + " " + t("plan.time_to") + " " + r.to + ": "), tipText([r.what, r.why, r.amount])));
+      }
+      const house = p.runs.find((x) => x.battery === i && x.kind === "house");
+      if (house) list.push(h("li", {}, h("strong", {}, b.name + ": "), tipText([house.what, house.why])));
+    });
+    for (const line of p.lines) list.push(h("li", {}, line));
+    $("#plan-list").replaceChildren(...list);
+    $("#price-line").textContent = [p.price_line, p.tomorrow_line, p.region_line].filter(Boolean).join(" ");
+  }
+
+  /* ---------------- tooltips: hover, tap and keyboard focus ---------------- */
+  (function () {
+    const tip = $("#tip"); let hot = null;
+    const hide = () => { tip.classList.remove("show"); if (hot) hot.classList.remove("hot"); hot = null; };
+    function show(el, x, y) {
+      if (hot && hot !== el) hot.classList.remove("hot");
+      hot = el; el.classList.add("hot");
+      const lines = JSON.parse(el.dataset.tip);
+      tip.replaceChildren(h("b", {}, lines[0]), ...lines.slice(1).map((l) => h("span", {}, l)));
+      tip.classList.add("show");
+      const r = tip.getBoundingClientRect();
+      let L = x + 12, T2 = y - r.height - 12;
+      if (L + r.width > innerWidth - 8) L = x - r.width - 12;
+      if (L < 8) L = 8;
+      if (T2 < 8) T2 = y + 16;
+      tip.style.left = L + "px"; tip.style.top = T2 + "px";
+    }
+    const target = (e) => e.target.closest && e.target.closest(".chart [data-tip]");
+    document.addEventListener("pointermove", (e) => {
+      if (e.pointerType === "touch") return;
+      const el = target(e);
+      if (el) show(el, e.clientX, e.clientY); else if (hot && document.activeElement !== hot) hide();
+    });
+    document.addEventListener("pointerdown", (e) => {
+      const el = target(e);
+      if (el && e.pointerType === "touch") { if (hot === el) hide(); else show(el, e.clientX, e.clientY); }
+      else if (!el) hide();
+    });
+    document.addEventListener("focusin", (e) => {
+      const el = target(e);
+      if (el) { const r = el.getBoundingClientRect(); show(el, r.left + r.width / 2, r.top); }
+    });
+    document.addEventListener("focusout", (e) => { if (target(e)) hide(); });
+    document.addEventListener("keydown", (e) => { if (e.key === "Escape") hide(); });
+    addEventListener("scroll", hide, { passive: true });
+  })();
+
+  /* ---------------- Home: peak, attention, control, details ---------------- */
+  function renderPeak() {
+    const m = S.month_peak;
+    $("#peak-month").textContent = m.month;
+    const covered = m.state !== "not_covered";
+    $("#peak-figures").hidden = !covered; $("#peak-meter").hidden = !covered;
+    $("#peak-now").textContent = m.peak_w != null ? kw(m.peak_w) + " kW"
+                                 : m.state === "unreadable" ? t("peak.unreadable") : t("peak.none");
+    $("#peak-limit").textContent = kw(m.limit_w) + " kW";
+    const pct = m.pct == null ? 0 : Math.max(0, Math.min(100, m.pct));
+    const bar = $("#peak-meter i");
+    bar.style.width = pct + "%";
+    bar.className = pct >= 100 ? "bad" : pct >= 80 ? "warn" : "";
+    $("#peak-meter").setAttribute("aria-label", t("peak.this_month") + " " + (m.pct == null ? "–" : Math.round(m.pct) + " %"));
+    $("#peak-line").textContent = m.line;
+  }
+  function renderAttention() {
+    const list = S.attention;
+    const icon = { alarm: "×", warning: "!", info: "i" };
+    $("#alerts").replaceChildren(...list.map((a) => h("div", { class: "alert" },
+      h("span", { class: "sev " + a.severity, "aria-hidden": "true" }, icon[a.severity] || "i"),
+      h("div", {}, h("div", { class: "t" }, h("span", { class: "sr" }, t("attention." + a.severity) + ": "), a.title),
+        h("div", { class: "small" }, a.body),
+        a.docs && S.control.docs_url ? h("a", { class: "tiny", href: S.control.docs_url, target: "_top", rel: "noopener" }, t("attention.details")) : null))));
+    const n = list.filter((a) => a.severity !== "info").length;
+    $("#attn-count").textContent = n ? n + " " + t("attention.to_look") : t("attention.nothing");
+    if (!list.length) $("#alerts").replaceChildren(h("div", { class: "small muted" }, t("attention.nothing")));
+    const badge = $("#attn-badge");
+    badge.textContent = n; badge.hidden = !n;
+    badge.classList.toggle("bad", list.some((a) => a.severity === "alarm"));
+  }
+  function renderControl(structured) {
+    const running = structured ? S.control.running : null;
+    const btn = $("#btn-ctl");
+    btn.textContent = running === false ? t("control.start") : t("control.stop");
+    btn.className = "btn" + (running === false ? " primary" : "");
+    $("#ctl-text").textContent = structured ? S.control.text : "";
+    $("#hint").textContent = S.hint || "";
+    const docs = $("#docs-link");
+    if (structured && S.control.docs_url) { docs.href = S.control.docs_url; docs.hidden = false; } else docs.hidden = true;
+  }
+  function renderDetails(open) {
+    $("#rows").replaceChildren(...(S.rows || []).map(([k, v]) => h("tr", {}, h("td", { class: "muted" }, k), h("td", {}, v))));
+    $("#checks").replaceChildren(...(S.checks || []).map((c) => {
+      const cls = c.ok ? (c.warn ? "c-warn" : "c-ok") : (c.warn ? "c-warn" : "c-bad");
+      const mark = c.ok ? (c.warn ? "!" : "✓") : (c.warn ? "!" : "✗");
+      return h("li", { class: cls }, mark + " " + c.text);
+    }));
+    if (open) $("#c-details").open = true;
+  }
+
+  /* ---------------- Batteries (placeholder until P3) ---------------- */
+  function renderBatteries() {
+    if (!S.batteries) { $("#bcards").replaceChildren(); return; }
+    $("#bcards").replaceChildren(...S.batteries.map((b) => h("div", { class: "card" },
+      h("div", { class: "row spread" }, h("strong", {}, b.name), h("span", { class: "small muted" }, b.capacity_kwh ? b.capacity_kwh + " kWh" : "")),
+      levelBar(b.level_pct, b.name),
+      h("dl", { class: "kv" },
+        h("dt", {}, t("batteries.level")), h("dd", {}, b.level_pct == null ? "–" : Math.round(b.level_pct) + " %"),
+        b.stored_kwh != null ? [h("dt", {}, t("batteries.stored")), h("dd", {}, b.stored_kwh.toFixed(1) + " kWh")] : null,
+        h("dt", {}, t("batteries.now")), h("dd", {}, b.now),
+        h("dt", {}, t("batteries.mode")), h("dd", {}, b.mode)))));
+  }
+
+  /* ---------------- control buttons ---------------- */
+  // The action is a toggle, so the page reads the live state first and sends
+  // nothing when control is already where the person asked it to be.
+  // One request at a time: a second confirm while the first is in flight
+  // would read the same state and toggle it back.
+  let toggling = false;
+  async function setControl(want) {
+    if (toggling) return;
+    toggling = true;
+    try {
+      const now = await getStatus();
+      if (!now.control || now.control.running !== want) await act("auto_toggle");
+      toast(want ? t("toast.started") : t("toast.stopped"));
+    } catch (e) { toast(t("toast.failed")); }
+    finally { toggling = false; }
+    refresh();
+  }
+  $("#btn-ctl").addEventListener("click", () => {
+    const running = S && S.control ? S.control.running : true;
+    if (running) ask("stop", () => setControl(false)); else ask("start", () => setControl(true));
+  });
+  async function simple(what) {
+    try { await act(what); toast(t("toast.done")); } catch (e) { toast(t("toast.failed")); }
+    refresh();
+  }
+  $("#btn-maint").addEventListener("click", () => ask("maint_start", () => simple("maint_start")));
+  $("#btn-abort").addEventListener("click", () => ask("maint_abort", () => simple("maint_abort")));
+
+  // Shared with settings.js, which loads after this file.
+  window.UX13 = { h, ask, toast, t, maint: (what) => ask(what, () => simple(what)) };
+
+  /* ---------------- tabs: hash routes, arrow keys ---------------- */
+  const TABS = [...document.querySelectorAll(".tab")];
+  function select(tab, focus) {
+    TABS.forEach((x) => {
+      const on = x === tab;
+      x.setAttribute("aria-selected", String(on)); x.tabIndex = on ? 0 : -1;
+      document.getElementById(x.getAttribute("aria-controls")).hidden = !on;
+    });
+    if (focus) tab.focus();
+    if (location.hash !== "#" + tab.dataset.hash) history.replaceState(null, "", "#" + tab.dataset.hash);
+    schedule();
+    document.dispatchEvent(new CustomEvent("ux13:tab", { detail: tab.dataset.hash }));
+  }
+  TABS.forEach((x, i) => {
+    x.addEventListener("click", () => select(x, false));
+    x.addEventListener("keydown", (e) => {
+      const j = { ArrowRight: i + 1, ArrowLeft: i - 1 + TABS.length, Home: 0, End: TABS.length - 1 }[e.key];
+      if (j === undefined) return;
+      e.preventDefault(); select(TABS[j % TABS.length], true);
+    });
+  });
+  function fromHash() {
+    const want = (location.hash || "#home").slice(1);
+    select(TABS.find((x) => x.dataset.hash === want) || TABS[0], false);
+  }
+  addEventListener("hashchange", fromHash);
+
+  /* ---------------- polling: every 3 s while Home or Batteries shows ---------------- */
+  let timer = null;
+  function schedule() {
+    const live = !document.hidden && ($("#t-home").getAttribute("aria-selected") === "true" ||
+                                      $("#t-batt").getAttribute("aria-selected") === "true");
+    if (live && !timer) { refresh(); timer = setInterval(refresh, 3000); }
+    if (!live && timer) { clearInterval(timer); timer = null; }
+  }
+  document.addEventListener("visibilitychange", schedule);
+  fromHash();
+  refresh();
+})();

goodwe_controller/app/static/index.html

@@ -0,0 +1,148 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Battery add-on</title>
+<style>/*APP_CSS*/</style>
+</head>
+<body>
+<header class="top">
+  <div class="logo" aria-hidden="true"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="7" width="16" height="10" rx="2"/><path d="M21 11v2M8 10l-2 3h4l-2 3"/></svg></div>
+  <div class="grow">
+    <div class="app" data-t="app.name"></div>
+    <div class="pill" id="pill" aria-live="polite"><span class="dot warn"></span><span>…</span></div>
+  </div>
+</header>
+
+<nav class="tabs" role="tablist" id="tabs" data-t-label="tabs.label">
+  <button class="tab" role="tab" id="t-home" aria-controls="s-home" aria-selected="true" data-hash="home"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M3 11l9-7 9 7v9a1 1 0 0 1-1 1h-5v-6H9v6H4a1 1 0 0 1-1-1z"/></svg><span data-t="tabs.home"></span><span class="badge" id="attn-badge" hidden></span></button>
+  <button class="tab" role="tab" id="t-batt" aria-controls="s-batt" aria-selected="false" data-hash="batteries" tabindex="-1"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><rect x="3" y="7" width="16" height="10" rx="2"/><path d="M21 11v2"/><rect x="5.5" y="9.5" width="7" height="5" fill="currentColor" stroke="none"/></svg><span data-t="tabs.batteries"></span></button>
+  <button class="tab" role="tab" id="t-set" aria-controls="s-set" aria-selected="false" data-hash="settings" tabindex="-1"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M4 6h10M18 6h2M4 12h4M12 12h8M4 18h12M20 18h0"/><circle cx="16" cy="6" r="2"/><circle cx="10" cy="12" r="2"/><circle cx="18" cy="18" r="2"/></svg><span data-t="tabs.settings"></span></button>
+  <button class="tab" role="tab" id="t-wiz" aria-controls="s-wiz" aria-selected="false" data-hash="setup" tabindex="-1"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M14 7l3 3M5 19l9.5-9.5 3 3L8 22H5z"/><path d="M19 2v4M17 4h4"/></svg><span data-t="tabs.setup"></span></button>
+</nav>
+
+<main class="wrap">
+
+<section class="screen" id="s-home" role="tabpanel" aria-labelledby="t-home">
+  <div id="home-banner"></div>
+
+  <div class="card" id="c-now">
+    <div class="row spread"><h2 data-t="now.name"></h2><span class="tiny muted" data-t="now.description"></span></div>
+    <div class="tiles">
+      <div class="tile"><div class="lab"><span class="sw-solar" aria-hidden="true">&#9728;</span><span data-t="now.solar"></span></div><div class="val" id="v-solar">–</div><div class="sub" id="sub-solar"></div></div>
+      <div class="tile"><div class="lab"><span class="sw-house" aria-hidden="true">&#8962;</span><span data-t="now.house"></span></div><div class="val" id="v-house">–</div><div class="sub" id="sub-house"></div></div>
+      <div class="tile"><div class="lab"><span class="sw-grid" aria-hidden="true">&#8645;</span><span data-t="now.grid"></span></div><div class="val" id="v-grid">–</div><div class="sub" id="sub-grid"></div></div>
+      <div class="tile"><div class="lab"><span class="sw-batt" aria-hidden="true">&#9646;</span><span data-t="now.batteries"></span></div><div class="val" id="v-batt">–</div><div class="sub" id="sub-batt"></div></div>
+    </div>
+    <div id="home-batts" style="margin-top:6px"></div>
+  </div>
+
+  <div class="card" id="c-plan">
+    <div class="row spread"><h2 data-t="plan.name"></h2><span class="chip tiny muted" id="verdict"></span></div>
+    <div class="small" id="plan-head"></div>
+    <div class="chart" id="chart">
+      <div class="bars" id="bars" role="group"></div>
+      <div id="lanes"></div>
+      <div class="nowline" id="nowline" aria-hidden="true"><span data-t="plan.now"></span></div>
+      <div class="axis" aria-hidden="true"><span>00:00</span><span>06:00</span><span>12:00</span><span>18:00</span><span>24:00</span></div>
+    </div>
+    <p class="tiny muted" id="no-prices" hidden data-t="plan.no_prices.description"></p>
+    <div class="legend" id="legend"></div>
+    <p class="tiny muted" style="margin:6px 0 0" data-t="plan.description"></p>
+    <h3 class="sr" data-t="plan.list"></h3>
+    <ul class="plain small" id="plan-list"></ul>
+    <p class="tiny muted" style="margin:8px 0 0" id="price-line"></p>
+  </div>
+
+  <div class="card" id="c-peak">
+    <div class="row spread"><h2 data-t="peak.name"></h2><span class="tiny muted" id="peak-month"></span></div>
+    <div class="row spread small" id="peak-figures"><span><span data-t="peak.this_month"></span>: <strong id="peak-now"></strong></span><span class="muted"><span data-t="peak.limit"></span> <span id="peak-limit"></span></span></div>
+    <div class="meter" id="peak-meter" role="img"><i style="width:0%"></i></div>
+    <div class="tiny muted" id="peak-line"></div>
+  </div>
+
+  <div class="card" id="c-attn">
+    <div class="row spread"><h2 data-t="attention.name"></h2><span class="tiny muted" id="attn-count"></span></div>
+    <div id="alerts"></div>
+  </div>
+
+  <div class="card" id="c-ctl">
+    <h2 data-t="control.name"></h2>
+    <div class="small" id="ctl-text"></div>
+    <div class="row" style="margin-top:10px">
+      <button class="btn" id="btn-ctl" type="button"></button>
+      <a class="small" id="docs-link" hidden target="_top" rel="noopener" data-t="control.docs"></a>
+    </div>
+    <div class="tiny muted" id="hint" aria-live="polite" style="margin-top:8px"></div>
+    <details class="more">
+      <summary data-t="control.more"></summary>
+      <div class="row" style="padding-bottom:6px">
+        <button class="btn" id="btn-maint" type="button" data-t="control.maint_start"></button>
+        <button class="btn danger" id="btn-abort" type="button" data-t="control.maint_abort"></button>
+      </div>
+    </details>
+  </div>
+
+  <details class="card more" id="c-details">
+    <summary data-t="details.name"></summary>
+    <table class="rows" id="rows"></table>
+    <h2 style="margin-top:12px" data-t="details.checks"></h2>
+    <ul class="checks" id="checks"></ul>
+  </details>
+</section>
+
+<section class="screen" id="s-batt" role="tabpanel" aria-labelledby="t-batt" hidden>
+  <div id="bcards"></div>
+  <div class="card">
+    <p class="small muted" style="margin:0 0 10px" data-t="batteries.description"></p>
+    <a class="btn" href="#settings" data-t="batteries.settings"></a>
+  </div>
+</section>
+
+<section class="screen" id="s-set" role="tabpanel" aria-labelledby="t-set" hidden>
+  <div class="row spread" style="margin-bottom:6px">
+    <h2 style="margin:0" data-s="name"></h2>
+    <a class="small" href="config" id="set-classic" data-s="classic"></a>
+  </div>
+  <p class="small muted" style="margin:0 0 10px" data-s="description"></p>
+  <div id="set-banner" aria-live="polite"></div>
+  <div id="set-body">
+    <input class="search" id="set-search" type="search" autocomplete="off" spellcheck="false" data-s-ph="search.description" data-s-label="search.name">
+    <div class="card" id="set-other" hidden><h2 data-s="other"></h2><ul class="plain small" id="set-other-list"></ul></div>
+    <div id="groups"><p class="small muted" data-s="loading"></p></div>
+    <p class="small muted" id="set-nomatch" hidden data-s="no_match.description"></p>
+    <p class="tiny muted" data-s="footer.description"></p>
+  </div>
+</section>
+
+<section class="screen" id="s-wiz" role="tabpanel" aria-labelledby="t-wiz" hidden>
+  <div class="card">
+    <h2 data-t="setup.name"></h2>
+    <p class="small muted" data-t="setup.description"></p>
+    <a class="btn" href="config" data-t="settings.open"></a>
+  </div>
+</section>
+</main>
+
+<dialog id="dlg" aria-labelledby="dlg-t" aria-describedby="dlg-b">
+  <h2 id="dlg-t"></h2>
+  <p class="small" id="dlg-b"></p>
+  <div class="row" style="justify-content:flex-end">
+    <button class="btn" id="dlg-no" type="button" data-t="dialog.cancel"></button>
+    <button class="btn primary" id="dlg-yes" type="button"></button>
+  </div>
+</dialog>
+<div id="savebar" role="region" hidden><div class="in">
+  <span class="grow" id="sb-text" aria-live="polite"></span>
+  <button class="btn" id="sb-discard" type="button" data-s="savebar.discard"></button>
+  <button class="btn primary" id="sb-save" type="button" data-s="savebar.save"></button>
+</div></div>
+<div id="toast" role="status" aria-live="polite"></div>
+<div id="tip" class="tip" aria-hidden="true"></div>
+
+<script type="application/json" id="ui-text">/*UI_TEXT*/</script>
+<script>/*APP_JS*/</script>
+<script>/*SETTINGS_JS*/</script>
+</body>
+</html>

goodwe_controller/app/static/settings.js

@@ -0,0 +1,561 @@
+"use strict";
+/* UX-13 P2: Settings, the Installer view. It draws from /config/model's
+   `layout` (app/uilayout.py through app/uipage.py) and `ui` (the page model
+   from app/uimodel.py), so this file names no option key: keys, labels,
+   ranges and choices all arrive as data. It posts the page model back; the
+   add-on turns it into options and runs its own start checks, and nothing
+   they refuse is saved. Every word is from app/ui_text or the add-on, and
+   data is set as text, never as HTML. */
+(function () {
+  const ROOT = JSON.parse(document.getElementById("ui-text").textContent);
+  const W = ROOT.settings;
+  const { h, ask, toast, maint } = window.UX13;
+  const $ = (s) => document.querySelector(s);
+  const ws = (path) => path.split(".").reduce((o, k) => (o == null ? o : o[k]), W);
+  const clone = (x) => (x === undefined ? undefined : JSON.parse(JSON.stringify(x)));
+  const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+
+  document.querySelectorAll("[data-s]").forEach((e) => { e.textContent = ws(e.dataset.s) || ""; });
+  document.querySelectorAll("[data-s-ph]").forEach((e) => { e.placeholder = ws(e.dataset.sPh) || ""; });
+  document.querySelectorAll("[data-s-label]").forEach((e) => { e.setAttribute("aria-label", ws(e.dataset.sLabel) || ""); });
+  $("#savebar").setAttribute("aria-label", W.savebar.label);
+
+  let M = null;              // the last /config/model
+  let V = null;              // the page model being edited
+  let ORIG = null;           // the page model as stored
+  let FP = "";               // the stored blob's fingerprint (compare-and-swap)
+  let MSG = [];              // [{field, card, tier, text}] from the add-on
+  let DEVICE = "";
+  let LIST = null;           // the inverter list field
+  let FILLED = {};           // field key -> the preset field that fills it
+  let active = false;
+  let uid = 0;
+  const ROWS = [];
+  const OPEN = new Set();
+  const UNLOCKED = new Set();
+
+  /* ---------------- the page model ---------------- */
+  const sub = (f) => f.key.slice(LIST.key.length + 1);
+  function valueIn(model, f, card) {
+    if (card == null) return model[f.key];
+    const c = (model[LIST.key] || [])[card];
+    return c ? c[sub(f)] : undefined;
+  }
+  const get = (f, card) => valueIn(V, f, card);
+  function visible(f) {
+    return (f.show || []).every(([name, op, want]) => {
+      const have = V[name];
+      if (op === "==") return same(have, want);
+      if (op === "!=") return !same(have, want);
+      if (op === "in") return want.some((x) => same(x, have));
+      if (have == null || have === "" || isNaN(+have)) return false;
+      return op === ">" ? +have > want : +have < want;
+    });
+  }
+  function put(f, card, v, redraw) {
+    if (card == null) V[f.key] = v;
+    else V[LIST.key][card][sub(f)] = v;
+    if (f.mirror) {
+      const m = findField(f.mirror);
+      if (m && (m.choices || []).some((c) => same(c[0], v))) V[f.mirror] = v;
+    }
+    if (f.fills && f.presets && f.presets[v]) V[f.fills] = f.presets[v].value;
+    if (redraw || f.fills) render(); else paint();
+    queueValidate();
+  }
+  function findField(key) {
+    for (const g of M.layout.groups) for (const p of g.parts) for (const f of p.fields) {
+      if (f.key === key) return f;
+      for (const s of f.fields || []) if (s.key === key) return s;
+    }
+    return null;
+  }
+
+  /* ---------------- numbers: stored units <-> shown units ---------------- */
+  const decimals = (x) => { const s = String(x); return s.includes(".") ? s.split(".")[1].length : 0; };
+  function shown(f, v) {
+    if (v == null || v === "") return "";
+    return String(+(Number(v) / (f.scale || 1)).toFixed(6));
+  }
+  function stored(f, x) {
+    const st = f.step || (f.type === "integer" ? 1 : 0);
+    let v = x * (f.scale || 1);
+    if (st) v = Math.round(v / st) * st;
+    if (f.min != null) v = Math.max(f.min, v);
+    if (f.max != null) v = Math.min(f.max, v);
+    return f.type === "integer" ? Math.round(v) : +v.toFixed(Math.min(10, decimals(st) + 2));
+  }
+
+  /* ---------------- controls ---------------- */
+  // A choice the page can only keep stays offered while it is the stored value.
+  function choicesOf(f, card) {
+    const cur = get(f, card), was = valueIn(ORIG, f, card);
+    const out = (f.choices || []).filter((c) => !c[2] || same(c[0], cur) || same(c[0], was));
+    if (cur != null && cur !== "" && !out.some((c) => same(c[0], cur))) out.push([cur, String(cur)]);
+    return out;
+  }
+  function toggle(f, card, lid) {
+    const on = !!get(f, card);
+    const b = h("button", { type: "button", class: "switch", role: "switch", "aria-checked": String(on), "aria-labelledby": lid });
+    const txt = h("span", { class: "swtext", "aria-hidden": "true" }, on ? W.on : W.off);
+    b.addEventListener("click", () => {
+      const n = b.getAttribute("aria-checked") !== "true";
+      b.setAttribute("aria-checked", String(n)); txt.textContent = n ? W.on : W.off;
+      put(f, card, n);
+    });
+    return h("span", { class: "swrap" }, b, txt);
+  }
+  function radios(f, card, lid, cards) {
+    const cur = get(f, card);
+    const g = h("div", { class: cards ? "choices" : "seg", role: "radiogroup", "aria-labelledby": lid });
+    const items = choicesOf(f, card);
+    const buttons = items.map(([v, label], i) => {
+      const on = same(v, cur);
+      const hint = cards && f.hints ? f.hints[v] : "";
+      const b = h("button", { type: "button", role: "radio", class: cards ? "choice" : null, "aria-checked": String(on),
+                              tabindex: on || (!items.some((c) => same(c[0], cur)) && i === 0) ? "0" : "-1" },
+        cards ? [h("span", { class: "rad", "aria-hidden": "true" }), h("span", {}, h("div", {}, label), hint ? h("div", { class: "tiny muted" }, hint) : null)] : label);
+      b.addEventListener("click", () => put(f, card, v, true));
+      b.addEventListener("keydown", (e) => {
+        const d = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }[e.key];
+        if (!d) return;
+        e.preventDefault();
+        const j = (i + d + items.length) % items.length;
+        put(f, card, items[j][0], true);
+        const again = document.querySelector(`[data-rk="${CSS.escape(g.dataset.rk)}"] [role=radio]:nth-child(${j + 1})`);
+        if (again) again.focus();
+      });
+      return b;
+    });
+    g.dataset.rk = f.key + "|" + card;
+    g.append(...buttons);
+    return g;
+  }
+  function select(f, card, lid) {
+    const cur = get(f, card);
+    const s = h("select", { class: "sel", "aria-labelledby": lid });
+    for (const [v, label] of choicesOf(f, card)) s.append(h("option", { value: JSON.stringify(v), selected: same(v, cur) }, label));
+    for (const [v, label] of f.later || []) s.append(h("option", { value: JSON.stringify(v), disabled: true }, label));
+    s.addEventListener("change", () => put(f, card, JSON.parse(s.value), true));
+    const preset = f.presets && f.presets[cur];
+    return preset ? h("div", { class: "row" }, s, h("span", { class: "chip" }, W.region_year.replace("{year}", preset.year))) : s;
+  }
+  function slider(f, card, lid) {
+    if (f.min == null || f.max == null) return number(f, card, lid);
+    const sc = f.scale || 1;
+    const st = f.step || (f.type === "integer" ? 1 : 0.01);
+    const v = get(f, card);
+    const r = h("input", { type: "range", min: f.min, max: f.max, step: st, value: v == null ? f.min : v, "aria-labelledby": lid });
+    const n = h("input", { class: "num", type: "number", inputmode: "decimal", min: f.min / sc, max: f.max / sc, step: st / sc, value: shown(f, v), "aria-labelledby": lid });
+    r.addEventListener("input", () => { const x = stored(f, +r.value / sc); n.value = shown(f, x); put(f, card, x); });
+    n.addEventListener("change", () => {
+      if (n.value === "" || isNaN(+n.value)) { n.value = shown(f, get(f, card)); return; }
+      const x = stored(f, +n.value); r.value = x; n.value = shown(f, x); put(f, card, x);
+    });
+    return h("div", { class: "slider" }, r, n, f.unit ? h("span", { class: "unit" }, f.unit) : null);
+  }
+  function number(f, card, lid) {
+    const sc = f.scale || 1;
+    const by = FILLED[f.key];
+    const preset = by && by.presets[V[by.key]];
+    const n = h("input", { class: "num", type: "number", inputmode: "decimal", step: f.step ? f.step / sc : "any",
+                           min: f.min == null ? null : f.min / sc, max: f.max == null ? null : f.max / sc,
+                           value: shown(f, get(f, card)), disabled: !!preset, "aria-labelledby": lid });
+    n.addEventListener("input", () => {
+      if (n.value === "") { if (f.optional) put(f, card, null); return; }
+      if (!isNaN(+n.value)) put(f, card, stored(f, +n.value));
+    });
+    n.addEventListener("change", () => { n.value = shown(f, get(f, card)); });
+    return h("div", {}, h("div", { class: "row" }, n, f.unit ? h("span", { class: "unit" }, f.unit) : null),
+             preset ? h("div", { class: "tiny muted" }, W.preset.description) : null);
+  }
+  function text(f, card, lid) {
+    const v = get(f, card);
+    const t = h("input", { class: "txt", type: "text", value: v == null ? "" : v, autocapitalize: "none", spellcheck: "false", "aria-labelledby": lid });
+    t.addEventListener("input", () => put(f, card, t.value));
+    return t;
+  }
+  function locked(f, card, lid) {
+    const box = h("div", {});
+    const id = f.key + "#" + card;
+    const open = () => { UNLOCKED.add(id); box.replaceChildren(slider(f, card, lid)); };
+    if (UNLOCKED.has(id)) { open(); return box; }
+    const v = get(f, card);
+    box.append(h("div", { class: "row" },
+      h("strong", {}, v == null ? W.not_set : shown(f, v) + (f.unit ? " " + f.unit : "")),
+      h("span", { class: "chip" }, W.locked),
+      h("button", { type: "button", class: "btn link", "aria-label": W.change + ": " + f.label, onclick: open }, W.change)));
+    return box;
+  }
+
+  /* entity picker: search, the matching kind first, the live reading */
+  const ENT = {};
+  function entities(kind) {
+    const now = Date.now();
+    const e = ENT[kind];
+    if (e && now - e.at < 30000) return e.p;
+    const p = fetch("ha/entities?kind=" + encodeURIComponent(kind || ""), { cache: "no-store" })
+      .then((r) => (r.ok ? r.json() : { available: false, entities: [] }))
+      .catch(() => ({ available: false, entities: [] }));
+    ENT[kind] = { at: now, p };
+    return p;
+  }
+  const reading = (e) => (e && e.state != null && e.state !== "" ? String(e.state) + (e.unit ? " " + e.unit : "") : "–");
+  function picker(f, lid, value, pick) {
+    let data = null, all = false;
+    const btn = h("button", { type: "button", class: "ent-btn", "aria-expanded": "false", "aria-haspopup": "listbox", "aria-labelledby": lid });
+    const pop = h("div", { class: "ent-pop", hidden: true });
+    const q = h("input", { type: "search", placeholder: W.picker.search.description, "aria-label": W.picker.search.description, autocomplete: "off", spellcheck: "false" });
+    const note = h("div", { class: "tiny muted ent-note" });
+    const list = h("div", { class: "ent-list", role: "listbox", "aria-labelledby": lid });
+    const allBox = h("label", { class: "tiny muted ent-all" },
+      h("input", { type: "checkbox", onchange: (e) => { all = e.target.checked; fill(); } }), W.picker.all);
+    function drawBtn() {
+      const id = value();
+      const e = data && data.entities.find((x) => x.entity_id === id);
+      btn.replaceChildren();
+      if (id) btn.append(h("span", { class: "grow" }, h("div", {}, e ? e.name : id), h("div", { class: "key" }, id)),
+                         data && data.available ? h("span", { class: "chip " + (e ? "now" : "rs") }, e ? reading(e) : W.picker.missing) : null);
+      else btn.append(h("span", { class: "grow muted" }, W.picker.choose));
+      btn.append(h("span", { class: "muted", "aria-hidden": "true" }, "▾"));
+    }
+    function opt(id, name, val) {
+      return h("button", { type: "button", class: "ent-opt", role: "option", "aria-selected": String(id === value()),
+                           onclick: () => { pick(id); close(); drawBtn(); btn.focus(); } },
+        h("span", { class: "grow" }, h("div", {}, name), h("div", { class: "key" }, id)), val ? h("span", { class: "v" }, val) : null);
+    }
+    function fill() {
+      const typed = q.value.trim();
+      const t = typed.toLowerCase();
+      const rows = (data ? data.entities : []).filter((e) => (all || e.match) && (e.entity_id + " " + e.name).toLowerCase().includes(t)).slice(0, 200);
+      list.replaceChildren(...rows.map((e) => opt(e.entity_id, e.name, reading(e))));
+      if (typed.includes(".") && !rows.some((e) => e.entity_id === typed)) list.append(opt(typed, W.picker.use, ""));
+      if (!list.children.length) list.append(h("div", { class: "small muted", style: "padding:10px" }, W.picker.none.description));
+      note.textContent = data && data.text ? data.text : "";
+      note.hidden = !note.textContent;
+    }
+    function close() { pop.hidden = true; btn.setAttribute("aria-expanded", "false"); }
+    btn.addEventListener("click", () => {
+      if (!pop.hidden) { close(); return; }
+      pop.hidden = false; btn.setAttribute("aria-expanded", "true"); q.value = ""; fill();
+      setTimeout(() => q.focus(), 0);
+    });
+    q.addEventListener("input", fill);
+    pop.addEventListener("keydown", (e) => {
+      if (e.key === "Escape") { e.preventDefault(); close(); btn.focus(); return; }
+      if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
+      e.preventDefault();
+      const opts = [...list.querySelectorAll(".ent-opt")];
+      const i = opts.indexOf(document.activeElement);
+      const j = e.key === "ArrowDown" ? Math.min(opts.length - 1, i + 1) : i - 1;
+      if (j < 0) q.focus(); else if (opts[j]) opts[j].focus();
+    });
+    pop.append(q, note, list, allBox);
+    drawBtn();
+    entities(f.kind).then((d) => { data = d; drawBtn(); if (!pop.hidden) fill(); });
+    return h("div", { class: "ent" }, btn, pop,
+      f.optional ? h("button", { type: "button", class: "btn link tiny", onclick: () => { pick(""); drawBtn(); } }, W.picker.clear) : null);
+  }
+  function entity(f, card, lid) {
+    return picker(f, lid, () => get(f, card) || "", (v) => put(f, card, v));
+  }
+  function entityList(f, card, lid) {
+    const arr = () => (Array.isArray(get(f, card)) ? get(f, card) : []);
+    const box = h("div", { class: "elist" });
+    arr().forEach((_id, i) => {
+      box.append(h("div", { class: "erow" },
+        h("div", { class: "tiny muted" }, W.phase + " " + (i + 1)),
+        picker(f, lid, () => arr()[i] || "", (v) => { const a = arr().slice(); a[i] = v; put(f, card, a); }),
+        h("button", { type: "button", class: "btn link tiny", onclick: () => { const a = arr().slice(); a.splice(i, 1); put(f, card, a, true); } }, W.remove)));
+    });
+    box.append(h("button", { type: "button", class: "btn", onclick: () => put(f, card, arr().concat([""]), true) }, "+ " + W.add_row));
+    return box;
+  }
+  function solarList(f, card, lid) {
+    const arr = () => (Array.isArray(get(f, card)) ? get(f, card) : []);
+    const box = h("div", { class: "elist" });
+    arr().forEach((row, i) => {
+      const flip = h("button", { type: "button", class: "switch", role: "switch", "aria-checked": String(!!row.reversed), "aria-label": W.reversed });
+      flip.addEventListener("click", () => { const a = clone(arr()); a[i].reversed = !a[i].reversed; put(f, card, a, true); });
+      box.append(h("div", { class: "erow" },
+        picker(f, lid, () => arr()[i].entity || "", (v) => { const a = clone(arr()); a[i].entity = v; put(f, card, a); }),
+        h("div", { class: "row" }, h("span", { class: "swrap" }, flip, h("span", { class: "swtext" }, W.reversed)),
+          h("button", { type: "button", class: "btn link tiny", onclick: () => { const a = clone(arr()); a.splice(i, 1); put(f, card, a, true); } }, W.remove))));
+    });
+    box.append(h("button", { type: "button", class: "btn", onclick: () => put(f, card, arr().concat([{ entity: "", reversed: false }]), true) }, "+ " + W.add_solar));
+    return box;
+  }
+  const CONTROLS = { toggle, segmented: (f, c, l) => radios(f, c, l, false), choice: (f, c, l) => radios(f, c, l, true),
+                     select, slider, number, text, locked, entity, entity_list: entityList, solar_list: solarList };
+
+  /* ---------------- rows, cards and groups ---------------- */
+  function keyText(f, card) {
+    if (card != null) return V[LIST.shape] === "flat" && f.flat ? f.flat : LIST.key + "[" + card + "]." + sub(f);
+    return f.key.startsWith("ui.") ? (f.writes || []).join(", ") : f.key;
+  }
+  function fieldRow(f, card, gid) {
+    if (f.control === "inverter_list") return cardList(f, gid);
+    const lid = "sf" + (++uid);
+    const keys = keyText(f, card);
+    const msg = h("div", { class: "msgs" });
+    const make = CONTROLS[f.control] || text;
+    const row = h("div", { class: "f" + (f.control === "toggle" ? " inline" : ""), "data-key": f.key, "data-card": card },
+      h("div", { class: "head" }, h("div", { class: "lbl", id: lid }, f.label, f.unit && f.control !== "slider" && f.control !== "number" && f.control !== "locked" ? " (" + f.unit + ")" : ""),
+        keys ? h("div", { class: "key" }, keys) : null),
+      h("div", { class: "ctl" }, make(f, card, lid)),
+      f.help ? h("div", { class: "help" }, f.help) : null, msg);
+    ROWS.push({ f, card, el: row, msg, gid, search: (f.label + " " + keys + " " + f.key + " " + (f.help || "")).toLowerCase() });
+    return row;
+  }
+  function blankCard(f, first) {
+    const out = {};
+    for (const s of f.fields) {
+      const k = sub(s);
+      out[k] = s.control === "slider" && first && first[k] != null ? first[k] : s.type === "boolean" ? false : s.control === "number" ? null : "";
+    }
+    return out;
+  }
+  function cardList(f, gid) {
+    const wrap = h("div", { class: "invs", "data-key": f.key });
+    const msg = h("div", { class: "msgs" });
+    const cards = V[f.key];
+    if (!Array.isArray(cards)) {
+      wrap.append(h("div", { class: "msg info" }, W.raw_roster.description), msg);
+    } else {
+      cards.forEach((c, i) => {
+        const box = h("div", { class: "inv" }, h("div", { class: "hd" },
+          h("span", { class: "grow" }, c.name || W.inverter + " " + (i + 1)), h("span", { class: "key" }, f.key + "[" + i + "]"),
+          cards.length > 1 ? h("button", { type: "button", class: "btn link tiny", onclick: () => {
+            V[f.key].splice(i, 1); V[f.count] = V[f.key].length;
+            // Back to one card, the stored shape returns: a flat inverter stays flat.
+            if (V[f.key].length === 1) for (const k in f.grow) V[k] = clone(ORIG[k]);
+            put(f, null, V[f.key], true);
+          } }, W.remove) : null));
+        for (const s of f.fields) box.append(fieldRow(s, i, gid));
+        wrap.append(box);
+      });
+      wrap.append(msg, h("button", { type: "button", class: "btn", onclick: () => {
+        V[f.key].push(blankCard(f, V[f.key][0])); Object.assign(V, f.grow); V[f.count] = V[f.key].length;
+        put(f, null, V[f.key], true);
+      } }, "+ " + W.add_inverter));
+    }
+    ROWS.push({ f, card: null, el: wrap, msg, gid, list: true, search: (f.label + " " + f.key + " " + (f.help || "")).toLowerCase() });
+    return wrap;
+  }
+  const chev = () => h("span", { class: "chev", "aria-hidden": "true" }, "›");
+  function render() {
+    const host = $("#groups");
+    const y = window.scrollY;
+    host.replaceChildren();
+    ROWS.length = 0;
+    for (const g of M.layout.groups) {
+      const d = h("details", { class: "grp", "data-g": g.id },
+        h("summary", {}, h("span", { class: "grow" }, h("strong", {}, g.name), h("span", { class: "small muted gdesc" }, g.description)),
+          h("span", { class: "gchips" }, h("span", { class: "gbadge" }), ...g.applies.map((a) => h("span", { class: "chip applies" }, a))), chev()));
+      d.open = OPEN.has(g.id);
+      d.addEventListener("toggle", () => { if (!$("#set-search").value) (d.open ? OPEN.add(g.id) : OPEN.delete(g.id)); });
+      const body = h("div", { class: "body" });
+      if (g.support_only) body.append(h("div", { class: "msg warn", role: "note" }, W.support.description));
+      for (const p of g.parts) {
+        const pid = g.id + "." + p.id;
+        let box;
+        if (p.collapsed) {
+          box = h("details", { class: "sub part" }, h("summary", {}, p.name));
+          box.open = OPEN.has(pid);
+          box.addEventListener("toggle", () => { if (!$("#set-search").value) (box.open ? OPEN.add(pid) : OPEN.delete(pid)); });
+        } else {
+          box = h("div", { class: "part" }, p.name ? h("div", { class: "subhead" }, p.name) : null);
+        }
+        if (p.description) box.append(h("p", { class: "small muted", style: "margin:4px 0" }, p.description));
+        for (const f of p.fields) box.append(fieldRow(f, null, g.id));
+        body.append(box);
+      }
+      if (g.id === "maintenance") {
+        body.append(h("div", { class: "part" }, h("div", { class: "subhead" }, W.cycle.name),
+          h("p", { class: "small muted", style: "margin:4px 0" }, W.cycle.description),
+          h("div", { class: "row" },
+            h("button", { type: "button", class: "btn", onclick: () => maint("maint_start") }, ROOT.home.control.maint_start),
+            h("button", { type: "button", class: "btn danger", onclick: () => maint("maint_abort") }, ROOT.home.control.maint_abort))));
+      }
+      d.append(body);
+      host.append(d);
+    }
+    paint();
+    window.scrollTo(0, y);
+  }
+
+  /* ---------------- messages, visibility, search, badges ---------------- */
+  const ICON = { bad: "×", warn: "!", info: "i" };
+  const RANK = { bad: 0, warn: 1, info: 2 };
+  function mine(r, m) {
+    if (m.field !== r.f.key) return false;
+    if (r.list || r.card == null) return true;
+    return m.card == null ? r.card === 0 : m.card === r.card;
+  }
+  function paint() {
+    const q = $("#set-search").value.trim().toLowerCase();
+    const placed = new Set();
+    for (const r of ROWS) {
+      r.visible = visible(r.f);
+      const msgs = MSG.filter((m, i) => { const hit = mine(r, m); if (hit && r.visible) placed.add(i); return hit; })
+        .sort((a, z) => RANK[a.tier] - RANK[z.tier]);
+      r.tiers = new Set(msgs.map((m) => m.tier));
+      r.msg.replaceChildren(...msgs.map((m) => h("div", { class: "msg " + m.tier },
+        h("span", { class: "mi", "aria-hidden": "true" }, ICON[m.tier] || "i"),
+        h("span", {}, h("span", { class: "sr" }, W.tier[m.tier] + ": "), m.text))));
+      r.el.classList.toggle("has-bad", r.tiers.has("bad"));
+      // A card list counts as one change when cards were added or removed;
+      // an edit inside a card counts on its own row.
+      r.changed = r.list ? !same((get(r.f) || []).length, (valueIn(ORIG, r.f) || []).length)
+                         : !same(get(r.f, r.card), valueIn(ORIG, r.f, r.card));
+      r.el.classList.toggle("changed", r.changed && !r.list);
+    }
+    // Search: a row shows when it is visible and matches. A card list shows
+    // while any of its rows does.
+    for (const r of ROWS) if (!r.list) r.el.hidden = !(r.visible && (!q || r.search.includes(q)));
+    for (const r of ROWS) if (r.list) r.el.hidden = !!q && !r.search.includes(q) && !ROWS.some((s) => !s.list && s.card != null && !s.el.hidden);
+    let any = false;
+    document.querySelectorAll("#groups details.grp").forEach((d) => {
+      const rows = ROWS.filter((r) => r.gid === d.dataset.g);
+      d.querySelectorAll(".part").forEach((p) => {
+        const inside = rows.filter((r) => p.contains(r.el));
+        if (inside.length) p.hidden = inside.every((r) => r.el.hidden);
+      });
+      const hit = rows.some((r) => !r.el.hidden);
+      any = any || hit;
+      d.hidden = !!q && !hit;
+      if (q && hit) { d.open = true; d.querySelectorAll("details.sub").forEach((s) => { s.open = true; }); }
+      const shownRows = rows.filter((r) => r.visible && !r.list);
+      const bad = shownRows.filter((r) => r.tiers.has("bad")).length + rows.filter((r) => r.list && r.tiers.has("bad")).length;
+      const warn = shownRows.filter((r) => !r.tiers.has("bad") && r.tiers.has("warn")).length;
+      const changed = rows.filter((r) => r.changed).length;
+      d.querySelector(".gbadge").replaceChildren(...[
+        bad ? h("span", { class: "chip bad" }, bad + " " + W.to_fix) : null,
+        warn ? h("span", { class: "chip rs" }, warn + " " + W.to_check) : null,
+        changed ? h("span", { class: "chip changed" }, changed + " " + W.changed) : null].filter(Boolean));
+    });
+    $("#set-nomatch").hidden = !q || any;
+    // A sentence shown beside any field is not repeated here.
+    const shownText = new Set(MSG.filter((m, i) => placed.has(i)).map((m) => m.text));
+    const other = MSG.filter((m, i) => !shownText.has(m.text) && MSG.findIndex((x) => x.text === m.text) === i);
+    if (DEVICE) other.push({ tier: "info", text: DEVICE });
+    $("#set-other").hidden = !other.length;
+    $("#set-other-list").replaceChildren(...other.map((m) => h("li", { class: "c-" + ({ bad: "bad", warn: "warn" }[m.tier] || "info") },
+      h("span", { class: "sr" }, W.tier[m.tier] + ": "), (ICON[m.tier] || "i") + " " + m.text)));
+    savebar();
+  }
+  function dirtyCount() {
+    const seen = new Set();
+    for (const r of ROWS) if (r.changed) seen.add(r.f.key + "#" + r.card);
+    return seen.size;
+  }
+  function savebar() {
+    const n = V ? dirtyCount() : 0;
+    $("#savebar").hidden = !(active && n);
+    $("#sb-text").textContent = n + " " + (n === 1 ? W.savebar.one : W.savebar.many);
+  }
+  $("#set-search").addEventListener("input", () => { if (V) paint(); });
+
+  /* ---------------- talking to the add-on ---------------- */
+  let vtimer = null, vseq = 0;
+  function queueValidate() { clearTimeout(vtimer); vtimer = setTimeout(validate, 400); }
+  async function validate() {
+    const seq = ++vseq;
+    try {
+      const r = await fetch("config/validate", { method: "POST", headers: { "Content-Type": "application/json" },
+                                                 body: JSON.stringify({ model: V }) });
+      const b = await r.json();
+      if (seq !== vseq) return;
+      MSG = b.messages || [];
+      DEVICE = b.device_note || "";
+      paint();
+    } catch (e) { /* the next change tries again */ }
+  }
+  function banner(level, title, sub, button, onClick) {
+    const host = $("#set-banner");
+    if (!title) { host.replaceChildren(); return; }
+    host.replaceChildren(h("div", { class: "banner " + ({ ok: "b-ok", bad: "b-bad" }[level] || "b-warn") },
+      h("span", { class: "ic", "aria-hidden": "true" }, { ok: "✓", bad: "×" }[level] || "!"),
+      h("span", {}, title, h("small", {}, sub, button ? [" ", h("button", { type: "button", class: "btn link", onclick: onClick }, button)] : null))));
+  }
+  function restart() {
+    ask(W.dialog, async () => {
+      try {
+        await fetch("config/restart", { method: "POST", headers: { "Content-Type": "application/json" },
+                                        body: JSON.stringify({ confirm: "restart" }) });
+      } catch (e) { /* the add-on stops answering while it restarts */ }
+      toast(W.toast.restarting.description);
+    });
+  }
+  async function load(after) {
+    let m;
+    try {
+      const r = await fetch("config/model?lang=en", { cache: "no-store" });
+      if (!r.ok) throw new Error("model " + r.status);
+      m = await r.json();
+      if (!m.layout || !m.ui) throw new Error("no layout");
+    } catch (e) {
+      $("#groups").replaceChildren();
+      $("#set-search").hidden = true;
+      banner("bad", W.load_failed.name, W.load_failed.description);
+      return;
+    }
+    M = m; V = clone(m.ui); ORIG = clone(m.ui); FP = m.fingerprint; MSG = []; DEVICE = "";
+    UNLOCKED.clear();
+    $("#set-search").hidden = false;
+    FILLED = {};
+    LIST = null;
+    for (const g of M.layout.groups) for (const p of g.parts) for (const f of p.fields) {
+      if (f.fills) FILLED[f.fills] = f;
+      if (f.control === "inverter_list") LIST = f;
+    }
+    if (!OPEN.size && M.layout.groups.length) OPEN.add(M.layout.groups[0].id);
+    if (after === "saved") banner("ok", W.saved.name, W.saved.description, W.restart, restart);
+    else if ((m.running_differs || []).length) banner("warn", W.differs.name, W.differs.description, W.restart, restart);
+    else banner();
+    render();
+    validate();
+  }
+  function firstBad() {
+    const r = ROWS.find((x) => x.tiers && x.tiers.has("bad") && x.visible);
+    if (!r) { if (!$("#set-other").hidden) $("#set-other").scrollIntoView({ block: "center" }); return; }
+    for (let p = r.el.parentElement; p; p = p.parentElement) if (p.tagName === "DETAILS") p.open = true;
+    r.el.scrollIntoView({ block: "center" });
+    const input = r.el.querySelector("input,select,button");
+    if (input) input.focus({ preventScroll: true });
+  }
+  async function save() {
+    const btn = $("#sb-save");
+    btn.disabled = true; btn.textContent = W.savebar.saving;
+    try {
+      clearTimeout(vtimer);
+      await validate();
+      if (MSG.some((m) => m.tier === "bad")) { toast(W.toast.blocked.description); firstBad(); return; }
+      const r = await fetch("config/save", { method: "POST", headers: { "Content-Type": "application/json" },
+                                             body: JSON.stringify({ model: V, fingerprint: FP }) });
+      const b = await r.json().catch(() => ({}));
+      if (r.ok) { toast(W.toast.saved); await load("saved"); return; }
+      if (r.status === 409 && b.kind === "stale") {
+        FP = b.fingerprint || FP;
+        const names = (b.changed_fields || []).map((k) => { const f = findField(k); return f ? f.label : k; });
+        banner("bad", W.stale.name, W.stale.description + (names.length ? " " + names.join(", ") + "." : ""));
+        return;
+      }
+      if (r.status === 422) { MSG = b.messages || []; paint(); toast(W.toast.blocked.description); firstBad(); return; }
+      toast(W.toast.failed);
+    } catch (e) { toast(W.toast.failed); }
+    finally { btn.disabled = false; btn.textContent = W.savebar.save; }
+  }
+  $("#sb-save").addEventListener("click", save);
+  // Discard reloads what is stored: after a stale save ORIG is no longer it.
+  $("#sb-discard").addEventListener("click", async () => {
+    await load(); toast(W.toast.discarded);
+  });
+  addEventListener("beforeunload", (e) => { if (V && dirtyCount()) { e.preventDefault(); e.returnValue = ""; } });
+  document.addEventListener("ux13:tab", (e) => {
+    active = e.detail === "settings";
+    if (active && !M) load(); else savebar();
+  });
+  // app.js chose the first tab before this file ran.
+  if ($("#t-set").getAttribute("aria-selected") === "true") { active = true; load(); }
+})();

goodwe_controller/app/static_tariff.py

@@ -1130,13 +1130,28 @@ class TariffPlan:
                 PriceProduct.STATIC: "day/night prices",
                 PriceProduct.FIXED: "a fixed price"}.get(self.product,
                                                          str(self.product))
+        # UX-10: the spacing in words, and no "not final yet": a plan is
+        # provisional exactly when it holds an estimated price, which the
+        # count already says.
         gaps = self.spacings_s
         return (f"{what} from {tag}, "
                 f"{self.n_points} prices over {self.hours} hours, "
                 f"{self.n_firm} published and {self.n_carried} estimated"
-                + (f", {'+'.join(str(g) for g in gaps)} s apart"
-                   if gaps else "")
-                + (", not final yet" if self.provisional else ""))
+                + (f", {spacing_words(gaps)}" if gaps else ""))
+
+
+def spacing_words(gaps) -> str:
+    """`(900, 3600)` -> `one every 15 minutes or every hour`."""
+    def one(s):
+        s = int(s)
+        if s == 3600:
+            return "every hour"
+        if s % 3600 == 0:
+            return f"every {s // 3600} hours"
+        if s % 60 == 0:
+            return f"every {s // 60} minutes"
+        return f"every {s} seconds"
+    return "one " + " or ".join(one(g) for g in gaps)
 
 
 def _whole_hours(points) -> int:
@@ -1206,9 +1221,9 @@ def static_plan(opts: dict, since: datetime, until: datetime, *,
     if profile is None:
         return TariffPlan(
             PriceRead.no_data(
-                "no static_profile configured; §11.4: plan provisional, no "
-                "arbitrage. Self-consumption, peak shaving and reserve "
-                "management are unaffected"),
+                "no fixed tariff is set, so the plan is estimated and there "
+                "is no trading. Self-consumption, peak limiting and the "
+                "reserve are not affected"),
             None, "none")
     points = profile.series(since, until, provisional=provisional)
     return TariffPlan(
@@ -1338,16 +1353,18 @@ def _degrade(opts, read, since, until, stamp) -> TariffPlan:
     try:
         profile = parse_static_profile(price_option(opts, "static_profile"))
     except ProfileInvalid as e:
-        _LOG.warning("the price feed is down AND static_profile is unusable "
-                     "(%s), so there is no tariff at all", e)
+        _LOG.warning("The price feed is down and the fixed tariff "
+                     "(static_profile) cannot be used either (%s), so there is "
+                     "no tariff at all.", e)
         profile = None
     if profile is None:
-        _LOG.warning("%s, and no static_profile is set to fall back to, so "
-                     "prices are provisional and trading is off. Peak "
-                     "limiting and home use go on.", read.reason)
+        _LOG.warning("The price feed failed and no fixed tariff is set, so "
+                     "trading is off, while peak limiting and home use go on. "
+                     "%s.", read.reason)
         return TariffPlan(read, None, "none")
-    _LOG.warning("%s, so the static_profile tariff is used instead, marked "
-                 "provisional, and trading is off.", read.reason)
+    _LOG.warning("The price feed failed, so the fixed tariff is used "
+                 "instead, marked as estimated, and trading is off. %s.",
+                 read.reason)
     points = profile.series(since, until, provisional=True)
     return TariffPlan(
         PriceRead.series(points, profile.product, "static_profile", stamp),

goodwe_controller/app/store.py

@@ -222,6 +222,8 @@ class MigrationReport:
         self.misdirected = []
         # Why nothing ran, when nothing ran. Empty means "already at schema".
         self.skipped = ""
+        # The inverter list the moves were graded against, for `explain()`.
+        self.roster = []
 
     @property
     def ok(self) -> bool:
@@ -237,19 +239,27 @@ class MigrationReport:
             # the flat keys ARE its namespace - and an operator reading the
             # startup log needs to be told which, because only one of them
             # changes when a second inverter is declared.
-            return self.skipped or (f"store already at schema "
-                                    f"{self.from_version}; no "
-                                    f"per-inverter migration needed")
-        out = (f"migrated {len(self.moved)} flat key(s) to inverter "
-               f"namespaces: " + ", ".join(sorted(self.moved)))
+            return self.skipped or (f"the saved state is already at version "
+                                    f"{self.from_version}, so nothing moves")
+        # UX-10: plain sentences (test_messages.py part 6). Each problem is
+        # named by its key and what went wrong, and `problems`, `lost` and
+        # `misdirected` keep their full notes for the checks that read them.
+        n = len(self.moved)
+        out = (f"moved {n} saved {'value' if n == 1 else 'values'} to one part "
+               f"per inverter: " + ", ".join(sorted(self.moved)) if n
+               else "moved nothing")
         if self.kept:
-            out += " (left alone, already namespaced: " + ", ".join(sorted(self.kept)) + ")"
-        if self.problems:
-            out += " - PROBLEMS: " + "; ".join(self.problems)
-        if self.lost:
-            out += " - STATE LOST: " + "; ".join(self.lost)
-        if self.misdirected:
-            out += " - WRONG NAMESPACE: " + "; ".join(self.misdirected)
+            out += ". Already in place: " + ", ".join(sorted(self.kept))
+        def keys(notes):
+            return ", ".join(note.split(" ", 1)[0] for note in notes)
+        other = [n for n in self.problems
+                 if n not in self.lost and n not in self.misdirected]
+        parts = ([f"lost {keys(self.lost)}"] if self.lost else []) + (
+            [f"moved under an inverter not in the list {self.roster!r}: "
+             f"{keys(self.misdirected)}"] if self.misdirected else []) + (
+            [f"read back differently {keys(other)}"] if other else [])
+        if parts:
+            out += ". Problems: " + ", and ".join(parts)
         return out
 
 
@@ -436,6 +446,7 @@ def _verify_moves(store, rep: MigrationReport, roster=None) -> None:
     if roster is None:
         return
     names = [str(n) for n in roster]
+    rep.roster = names
     # `unit_key()` builds `unit/<unit>/<key>`, so the unit is field 1. Split
     # through the same spelling the writer used rather than re-deriving it.
     #
@@ -469,8 +480,8 @@ def _verify_moves(store, rep: MigrationReport, roster=None) -> None:
         if unit in names:
             continue
         rep.verified = False
-        note = (f"{target} was migrated into namespace {unit!r}, which is NOT "
-                f"on the roster {names!r} - nothing reads that key")
+        note = (f"{target} was moved under {unit!r}, which is not in the "
+                f"inverter list {names!r}, so nothing reads it")
         rep.problems.append(note)
         rep.misdirected.append(note)
 
@@ -536,14 +547,12 @@ def migrate_maint_keys(store, unit: str, roster) -> MigrationReport:
     names = [str(n) for n in roster]
     rep.from_version = int(data.get(MAINT_SCHEMA_KEY, 0) or 0)
     if len(names) <= 1:
-        rep.skipped = ("one inverter: the flat maintenance keys ARE that pack's "
-                       "history and are read in place, so there is nothing to "
-                       "move and the store layout does not change")
+        rep.skipped = ("one inverter, so it is read where it is and nothing "
+                       "moves")
         return rep
     if rep.from_version >= MAINT_SCHEMA_VERSION:
-        rep.skipped = (f"maintenance history already at schema "
-                       f"{rep.from_version}; written by a multi-inverter "
-                       f"version and not touched")
+        rep.skipped = (f"already at version {rep.from_version}, written for "
+                       f"several inverters, so it is left as it is")
         return rep
 
     rep.ran = True
@@ -567,8 +576,8 @@ def migrate_maint_keys(store, unit: str, roster) -> MigrationReport:
         # the re-run a no-op where the keys did land, so refusing the marker
         # costs one repeated pass and buys the difference between a migration
         # that can still be fixed and one the store says already happened.
-        _LOG.error("per-pack maintenance-history migration did NOT land and "
-                   "has not been marked done: %s", rep.explain())
+        _LOG.error("Moving the maintenance history to one part per inverter "
+                   "did not work, so it is not marked done: %s", rep.explain())
     return rep
 
 

goodwe_controller/app/tariff.py

@@ -114,6 +114,8 @@ import sqlite3
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone, tzinfo
 
+from . import messages
+
 _LOG = logging.getLogger("goodwe.tariff")
 
 QUARTER_S = 900
@@ -339,8 +341,8 @@ class PeakStore:
             # INFO, not ERROR: on a dev host or in a test container there is no
             # /data and nothing is wrong. A store that OPENED and then broke is
             # the error case, and it is logged as one below.
-            _LOG.info("no peak store: %s - the monthly peak will read "
-                      "NOT_OBSERVED", self.last_error)
+            _LOG.info("No peak store (%s), so the month peak cannot be read "
+                      "and only the peak limit is used.", self.last_error)
             return
         try:
             self._db = sqlite3.connect(self.path, timeout=5.0,
@@ -360,8 +362,9 @@ class PeakStore:
             # fault must not stop a controller that is regulating a battery. The
             # cost of continuing is a peak that reads NOT_OBSERVED, and every
             # reader is built to treat that as "do not use me", not as 0 W.
-            _LOG.error("peak store unusable at %s (%s) - the monthly peak will "
-                       "read NOT_OBSERVED, which is not a zero peak", self.path, err)
+            _LOG.error("The peak store at %s cannot be used (%s), so only the "
+                       "peak limit is used. The month peak is unknown, not "
+                       "zero.", self.path, err)
 
     def close(self) -> None:
         if self._db is not None:
@@ -672,12 +675,12 @@ class PeakTracker:
         now = now or datetime.now(timezone.utc)
         snap = self.store.load_partial()
         if not snap:
-            self.restore_state = ("fresh: no checkpoint" if self.store.ok
-                                  else "fresh: store unreadable")
+            self.restore_state = ("fresh start, nothing saved" if self.store.ok
+                                  else "fresh start, the store cannot be read")
             return self.restore_state
         block = snap.get("block")
         if block is None:
-            self.restore_state = "fresh: checkpoint had no open block"
+            self.restore_state = "fresh start, no open 15-minute period saved"
             return self.restore_state
 
         current = int(now.timestamp() // QUARTER_S) * QUARTER_S
@@ -686,11 +689,13 @@ class PeakTracker:
                 # A reshaped accumulator (meter_phases changed) is a different
                 # measurement, not a resumable one. Say so; do not half-resume.
                 self.store.clear_partial()
-                self.restore_state = "fresh: checkpoint does not fit this averager"
+                self.restore_state = ("fresh start, the saved period does not "
+                                      "fit the number of phases")
                 return self.restore_state
             self.restore_state = (
-                f"resumed the open block at {snap.get('elapsed', 0.0):.0f} s "
-                f"of {QUARTER_S} s ({snap.get('acc', 0.0) / QUARTER_S:.0f} W banked)")
+                f"resumed the open 15-minute period at "
+                f"{snap.get('elapsed', 0.0):.0f} s of {QUARTER_S} s, with "
+                f"{snap.get('acc', 0.0) / QUARTER_S:.0f} W counted so far")
             return self.restore_state
 
         # The block ended while the add-on was down. Its measured part really
@@ -704,10 +709,14 @@ class PeakTracker:
                                      if snap.get("pp_acc") and snap.get("last_pp") else None))
         banked = self.store.record_block(closed, self.policy)
         self.store.clear_partial()
+        # UX-10: plain words and the local time, not ISO and "banked".
         self.restore_state = (
-            f"closed a stale block from {closed.start.isoformat()} at "
-            f"{closed.offtake_avg_w:.0f} W (partial coverage), "
-            + ("banked" if banked else "NOT banked - store unwritable"))
+            f"closed the 15-minute period from "
+            f"{messages.when(closed.start.astimezone(BILLING_TZ))} at "
+            f"{closed.offtake_avg_w:.0f} W, partly measured, "
+            + ("and saved it" if banked
+               else "but could not save it, because the store cannot be "
+                    "written"))
         return self.restore_state
 
     # -- steady state -------------------------------------------------------

goodwe_controller/app/ui_text/en.json

@@ -0,0 +1,162 @@
+{
+  "groups": {
+    "meter": {"name": "Meter", "description": "Where the grid reading comes from."},
+    "inverters": {"name": "Inverters and batteries", "description": "The inverters the add-on controls, and your solar."},
+    "tariff": {"name": "Tariff and prices", "description": "What you pay and are paid per kWh."},
+    "safety": {"name": "Safety limits", "description": "The peak limit, starting and stopping, and the safety stops."},
+    "maintenance": {"name": "Maintenance", "description": "The monthly battery cycle and the log."},
+    "tuning": {"name": "Control tuning", "description": "For support only, because these were measured on real hardware."}
+  },
+  "parts": {
+    "meter.timing": {"name": "Timing"},
+    "inverters.solar": {"name": "Solar"},
+    "tariff.selling": {"name": "Charging and selling on price"},
+    "tariff.feed": {"name": "Price feed details"},
+    "safety.peak": {"name": "Peak limit"},
+    "safety.start": {"name": "Starting and stopping"},
+    "safety.stops": {"name": "Safety stops", "description": "Measured on real hardware, so leave them unchanged."},
+    "maintenance.support": {"name": "Support"}
+  },
+  "fields": {
+    "solar": {"name": "Solar inverters", "description": "Each solar inverter's power sensor, which the add-on records but does not use for control."},
+    "contract": {"name": "Your contract", "description": "How your supplier prices each kWh you take from the grid."},
+    "region": {"name": "Region", "description": "Fills in grid costs, levies and VAT for the year shown, but not yet for Wallonia or Brussels, so check your bill."},
+    "fallback": {"name": "Price when the feed is down", "description": "Used when the price source does not answer."},
+    "fixed_price": {"name": "Price per kWh, all in", "description": "Energy, supplier costs, grid costs, levies and VAT together."},
+    "day_price": {"name": "Day price, weekdays 07:00 to 22:00", "description": "All in, as on your bill."},
+    "night_price": {"name": "Night and weekend price", "description": "All in, as on your bill."}
+  },
+  "choices": {
+    "contract": {"none": "No prices", "fixed": "Fixed price", "daynight": "Day and night", "dynamic": "Dynamic, hourly", "custom": "Other time windows"},
+    "fallback": {"none": "None", "fixed": "One price", "daynight": "Day and night", "custom": "Other time windows"},
+    "region": {"flanders": "Flanders, Fluvius Antwerpen", "own": "I enter my own figure"},
+    "meter_source": {"off": "One grid power entity", "ha_dsmr": "Import and export entities", "mqtt_p1": "Meter over MQTT", "ha_signed": "One net power entity", "homewizard_local": "HomeWizard meter on the network"},
+    "meter_phases": {"1": "1 phase", "3": "3 phases"},
+    "shadow_mode": {"auto": "Automatic", "on": "Always on", "off": "Off"},
+    "price_provider": {"generic_dayahead": "Day-ahead market price", "custom_formula": "Your own price formula", "manual_csv": "A price file"},
+    "log_level": {"trace": "Everything, for support", "debug": "Detailed, to find a problem", "info": "Normal", "warning": "Warnings and errors", "error": "Errors only"}
+  },
+  "applies": {
+    "restart": {"name": "Applies after a restart"},
+    "now": {"name": "Applies right away"}
+  },
+  "home": {
+    "app": {"name": "Battery add-on"},
+    "tabs": {"home": "Home", "batteries": "Batteries", "settings": "Settings", "setup": "Setup", "label": "Screens"},
+    "now": {"name": "Now", "description": "Updated every 3 seconds.", "solar": "Solar", "house": "House", "grid": "Grid", "batteries": "Batteries"},
+    "plan": {
+      "name": "Today's plan",
+      "description": "Point at a bar or a block for details, or tap it on a phone.",
+      "cheap": "Low price",
+      "dear": "High price",
+      "estimate": "Estimate",
+      "grid": "Charges from the grid",
+      "give": "Gives power",
+      "cycle": "Monthly battery cycle",
+      "peak": "Peak limit",
+      "house": "Follows the house",
+      "now": "now",
+      "time_to": "to",
+      "per_kwh": "per kWh",
+      "cheap_tip": "low for today",
+      "dear_tip": "high for today",
+      "estimate_tip": "estimate from yesterday",
+      "none_tip": "No price known",
+      "no_prices": {"description": "No prices for today, so the chart shows only the plan."},
+      "list": "The plan in words",
+      "average_tip": "hour average"
+    },
+    "peak": {"name": "Peak limit", "this_month": "This month's peak", "limit": "Limit", "none": "None recorded yet", "unreadable": "Cannot be read now"},
+    "attention": {"name": "Needs attention", "nothing": "Nothing to look at", "to_look": "to look at", "details": "Details", "alarm": "Alarm", "warning": "Warning", "info": "Info"},
+    "control": {"name": "Control", "stop": "Stop control", "start": "Start control", "maint_start": "Start a battery cycle now", "maint_abort": "Stop the battery cycle", "docs": "Add-on documentation", "more": "More actions"},
+    "details": {"name": "Details for installers", "rows": "Status rows", "checks": "Checks", "event": "Last event"},
+    "dialog": {
+      "cancel": "Cancel",
+      "stop": {"name": "Stop control?", "description": "Every inverter is set to 0 W until you start control again.", "yes": "Stop control"},
+      "start": {"name": "Start control?", "description": "The add-on controls the batteries again and clears any safety stop.", "yes": "Start control"},
+      "maint_start": {"name": "Start a battery cycle?", "description": "The battery empties, refills and holds full, which takes a few hours.", "yes": "Start the cycle"},
+      "maint_abort": {"name": "Stop the battery cycle?", "description": "Every inverter is set to 0 W for a moment, then control carries on.", "yes": "Stop the cycle"}
+    },
+    "toast": {"started": "Control started.", "stopped": "Control stopped.", "done": "Done.", "failed": "That did not work. Try again."},
+    "offline": {"name": "Cannot reach the add-on", "description": "The page tries again every 3 seconds."},
+    "batteries": {"name": "Batteries", "description": "Battery modes and on and off switches arrive in a later update.", "level": "Level", "now": "Now", "stored": "Stored", "mode": "Mode", "settings": "Change inverter settings"},
+    "settings": {"name": "Settings", "description": "The settings are grouped by task below.", "open": "Open the settings page"},
+    "setup": {"name": "Setup", "description": "The setup steps arrive in a later update, so use the settings page for now."}
+  },
+  "choices_later": {
+    "region": {"wallonia": "Wallonia, no preset yet", "brussels": "Brussels, no preset yet"}
+  },
+  "choice_help": {
+    "meter_source": {
+      "off": {"description": "A Home Assistant entity that reads grid power in W, positive when you take from the grid."},
+      "ha_dsmr": {"description": "Two Home Assistant entities from the DSMR integration, one for import and one for export."},
+      "mqtt_p1": {"description": "The meter's readings arrive over MQTT on a topic you name."},
+      "ha_signed": {"description": "One Home Assistant entity that reads net grid power, positive for import."},
+      "homewizard_local": {"description": "The add-on reads a HomeWizard meter on your network, and can spot a stuck meter."}
+    }
+  },
+  "settings": {
+    "name": "Settings",
+    "description": "Every setting, grouped by task, and the simple view follows in a later update.",
+    "classic": "Classic settings",
+    "search": {"name": "Find a setting", "description": "Find a setting, for example peak or meter."},
+    "no_match": {"description": "No setting matches your search."},
+    "loading": "Loading the settings",
+    "load_failed": {"name": "Cannot read the settings", "description": "The add-on could not read its stored settings, so use Classic settings or the Configuration tab."},
+    "footer": {"description": "Every change is checked by the add-on's own start checks before it is saved."},
+    "to_fix": "to fix",
+    "to_check": "to check",
+    "changed": "changed",
+    "on": "On",
+    "off": "Off",
+    "not_set": "Not set",
+    "locked": "Locked",
+    "change": "Change",
+    "support": {"description": "These were measured on real hardware, so change them only when support asks."},
+    "picker": {
+      "choose": "Choose an entity",
+      "search": {"description": "Search by name or entity id."},
+      "all": "Show every entity",
+      "use": "Use this entity id",
+      "clear": "Clear",
+      "missing": "Not in Home Assistant",
+      "none": {"description": "Nothing matches, so check the entity in Developer Tools."}
+    },
+    "add_inverter": "Add an inverter",
+    "inverter": "Inverter",
+    "remove": "Remove",
+    "add_row": "Add a row",
+    "add_solar": "Add a solar inverter",
+    "reversed": "Reads negative",
+    "phase": "Phase",
+    "raw_roster": {"description": "This inverter list can only be changed in the Configuration tab."},
+    "region_year": "{year} figures",
+    "hour": "{hour}:00 UTC",
+    "preset": {"description": "Filled in by the region above, so choose your own figure to change it."},
+    "cycle": {"name": "Run a cycle by hand", "description": "The same actions as on Home, each asking first."},
+    "savebar": {"label": "Unsaved changes", "one": "change not saved", "many": "changes not saved", "discard": "Discard", "save": "Save", "saving": "Saving"},
+    "saved": {"name": "Saved, not running yet", "description": "The add-on runs the settings it started with until you restart it."},
+    "differs": {"name": "Stored settings are not running", "description": "Some stored settings differ from what runs now, so restart the add-on to apply them."},
+    "stale": {"name": "Changed somewhere else", "description": "These settings changed elsewhere while you edited, so save again to keep yours or discard to load theirs."},
+    "other": "Other messages",
+    "restart": "Restart now",
+    "dialog": {"name": "Restart the add-on?", "description": "Every inverter is set to 0 W while the add-on restarts, and then the new settings apply.", "yes": "Restart now"},
+    "toast": {
+      "saved": "Saved. Restart to apply.",
+      "discarded": "Changes discarded.",
+      "failed": "That did not work. Try again.",
+      "blocked": {"description": "Fix the settings marked in red, then save again."},
+      "restarting": {"description": "Restart requested, so this page stops answering for a moment."}
+    },
+    "tier": {"bad": "Must fix", "warn": "Check this", "info": "Note"},
+    "derive": {
+      "raw_roster": {"description": "This inverter list can only be changed in the Configuration tab."},
+      "no_inverter": {"description": "Add at least one inverter."},
+      "flat_named": {"description": "Add a second inverter before naming this one."},
+      "no_source": {"description": "Choose where the dynamic prices come from."},
+      "custom_profile": {"description": "Other time windows can only be changed in the Configuration tab."},
+      "no_price": {"description": "Enter a price per kWh."},
+      "unknown": {"description": "The page cannot store this choice, so reload the page."}
+    }
+  }
+}

goodwe_controller/app/uilayout.py

@@ -0,0 +1,303 @@
+"""UX-13: the new page's layout, written once - screen, group, field.
+
+UI code names option keys only here and in uimodel.py, which holds the
+derivations this table lists (DECISIONS/UX-13-one-layout-table.md, amending
+UX-02 §3). Everything else stays where UX-02 put it: ranges in config.yaml's
+schema, rules in validate.py. test_uilayout.py fails CI when an option in
+config.yaml has no place here.
+
+A field's `key` is an option key, `inverters.<field>` for one inverter in the
+list, or `ui.<name>` for a page-only control that uimodel.py turns into options.
+The key is also its text key: label and help are translations/*.yaml's entry
+for an option, and app/ui_text's `fields.<name>` for a `ui.` field.
+"""
+
+from dataclasses import dataclass
+
+RESTART = "restart"         # stored options apply after a restart (UX-02 §5)
+NOW = "now"                 # runtime state (OPT-11's battery switches), none yet
+
+# Controls are names, not string literals, so a key is never followed by a
+# constant (test_defaults_pin.py reads `f("key", <constant>)` as a fallback).
+CHOICE, ENTITY, ENTITY_LIST, TOGGLE, SEGMENTED, SLIDER = (
+    "choice", "entity", "entity_list", "toggle", "segmented", "slider")
+NUMBER, TEXT, SELECT, LOCKED, INVERTER_LIST, SOLAR_LIST = (
+    "number", "text", "select", "locked", "inverter_list", "solar_list")
+CONTROLS = (CHOICE, ENTITY, ENTITY_LIST, TOGGLE, SEGMENTED, SLIDER, NUMBER,
+            TEXT, SELECT, LOCKED, INVERTER_LIST, SOLAR_LIST)
+# What an entity picker offers first. `power_w` is a power sensor the add-on
+# reads as watts with no unit conversion, so validate.py warns on a kW sensor.
+ENTITY_KINDS = ("power_w", "power", "energy", "pct", "number", "any")
+SHOW_OPS = ("==", "!=", "in", ">", "<")
+
+
+@dataclass(frozen=True)
+class Field:
+    key: str
+    control: str
+    unit: str = ""
+    scale: int = 1              # shown = stored / scale (the peak limit in kW)
+    step: float = 0             # slider or number step, stored units; 0 = 1
+    kind: str = ""              # entity picker filter, one of ENTITY_KINDS
+    show: tuple = ()            # ((name, op, value), ...), all must hold
+    applies: str = RESTART
+    simple: bool = False        # also on Settings, Simple
+    wizard: int = 0             # setup wizard step 1-6, 0 = not in the wizard
+    mirror: str = ""            # a choice also copied to this field, if offered
+    fills: str = ""             # a preset choice fills this field (uimodel)
+
+    @property
+    def text(self) -> str:
+        """Where the label and help live: `translations` or `ui_text`."""
+        return "ui_text" if self.key.startswith("ui.") else "translations"
+
+
+@dataclass(frozen=True)
+class Part:
+    id: str                     # "" is the group's main part
+    fields: tuple
+    collapsed: bool = False
+
+
+@dataclass(frozen=True)
+class Group:
+    id: str
+    parts: tuple
+    support_only: bool = False  # collapsed, with a "for support" warning
+
+
+def _src(*values):
+    return (("meter_source", "in", values),)
+
+
+_DYNAMIC = (("ui.contract", "==", "dynamic"),)
+_MAINT = (("maintenance_enabled", "==", True),)
+_ONE = (("inverter_count", "==", 1),)
+_SEVERAL = (("inverter_count", ">", 1),)
+_PHASES = (("meter_phases", ">", 1),)
+# One inverter stored flat has no name or capacity (uimodel._roster_encode).
+_LISTED = (("inverter_shape", "!=", "flat"),)
+
+# The per-inverter card. Its keys are `inverters.<field>` in config.yaml.
+ROSTER_FIELDS = (
+    Field("inverters.name", TEXT, show=_LISTED, wizard=2),
+    Field("inverters.setpoint_entity", ENTITY, kind="number", wizard=2),
+    Field("inverters.max_w", SLIDER, "W", step=100, wizard=2),
+    Field("inverters.bms_soc_floor", SLIDER, "%", wizard=2),
+    Field("inverters.soc_entity", ENTITY, kind="pct", wizard=2),
+    Field("inverters.batt_entity", ENTITY, kind="power_w", wizard=2),
+    Field("inverters.batt_invert", TOGGLE, wizard=2),
+    Field("inverters.capacity_kwh", NUMBER, "kWh", step=0.1, show=_LISTED,
+          wizard=2),
+)
+
+GROUPS = (
+    Group("meter", (
+        Part("", (
+            Field("meter_source", CHOICE, wizard=1),
+            Field("meter_entity", ENTITY, kind="power_w", show=_src("off"),
+                  wizard=1),
+            Field("meter_invert", TOGGLE, show=_src("off"), wizard=1),
+            Field("p1_net_entity", ENTITY, kind="power_w",
+                  show=_src("ha_signed"), wizard=1),
+            Field("p1_import_entity", ENTITY, kind="power_w",
+                  show=_src("ha_dsmr"), wizard=1),
+            Field("p1_export_entity", ENTITY, kind="power_w",
+                  show=_src("ha_dsmr"), wizard=1),
+            Field("p1_host", TEXT, show=_src("homewizard_local"), wizard=1),
+            Field("meter_mqtt_topic", TEXT, show=_src("mqtt_p1"), wizard=1),
+            Field("meter_phases", SEGMENTED, wizard=1),
+            Field("p1_phase_net_entities", ENTITY_LIST, kind="power_w",
+                  show=_src("ha_signed") + _PHASES, wizard=1),
+            Field("p1_phase_import_entities", ENTITY_LIST, kind="power_w",
+                  show=_src("ha_dsmr") + _PHASES, wizard=1),
+            Field("p1_phase_export_entities", ENTITY_LIST, kind="power_w",
+                  show=_src("ha_dsmr") + _PHASES, wizard=1),
+        )),
+        Part("timing", (
+            Field("meter_max_age_s", SLIDER, "s", step=5),
+            Field("meter_poll_s", SLIDER, "s",
+                  show=_src("homewizard_local")),
+        ), collapsed=True),
+    )),
+    Group("inverters", (
+        Part("", (Field("inverters", INVERTER_LIST, wizard=2),)),
+        # pv.py reads each entity's own unit, so a kW sensor is fine here.
+        Part("solar", (Field("ui.solar", SOLAR_LIST, kind="power",
+                             wizard=3),)),
+    )),
+    Group("tariff", (
+        Part("", (
+            # A contract without a feed is also the price used when a feed
+            # is down, so the fallback follows it (uimodel._tariff_encode).
+            Field("ui.contract", SEGMENTED, wizard=4, mirror="ui.fallback"),
+            Field("price_provider", SELECT, show=_DYNAMIC, wizard=4),
+            Field("price_formula", TEXT,
+                  show=_DYNAMIC + (("price_provider", "==", "custom_formula"),),
+                  wizard=4),
+            Field("price_csv_path", TEXT,
+                  show=_DYNAMIC + (("price_provider", "==", "manual_csv"),),
+                  wizard=4),
+            Field("ui.region", SELECT, wizard=4,
+                  fills="price_taxes_eur_kwh"),
+            Field("price_taxes_eur_kwh", NUMBER, "€/kWh", step=0.00001,
+                  wizard=4),
+            Field("price_markup_eur_kwh", NUMBER, "€/kWh", step=0.001,
+                  show=_DYNAMIC, wizard=4),
+            Field("export_price_eur_kwh", NUMBER, "€/kWh", step=0.001,
+                  wizard=4),
+            Field("price_export_formula", TEXT),
+            Field("ui.fallback", SEGMENTED, show=_DYNAMIC, wizard=4),
+            Field("ui.fixed_price", NUMBER, "€/kWh", step=0.01,
+                  show=(("ui.fallback", "==", "fixed"),), wizard=4),
+            Field("ui.day_price", NUMBER, "€/kWh", step=0.01,
+                  show=(("ui.fallback", "==", "daynight"),), wizard=4),
+            Field("ui.night_price", NUMBER, "€/kWh", step=0.01,
+                  show=(("ui.fallback", "==", "daynight"),), wizard=4),
+        )),
+        Part("selling", (
+            # OPT-11: derived from the batteries' selling switches once battery
+            # modes exist (uimodel.arbitrage_from_batteries). A toggle until then.
+            Field("arbitrage_enabled", TOGGLE),
+            Field("cycle_cost_threshold_eur", NUMBER, "€/kWh", step=0.01),
+            Field("arbitrage_soc_floor", SLIDER, "%"),
+            Field("arbitrage_soc_ceiling", SLIDER, "%"),
+        )),
+        Part("feed", (
+            Field("price_feed_url", TEXT, show=_DYNAMIC),
+            Field("price_horizon_h", SLIDER, "h", show=_DYNAMIC),
+            Field("price_timeout_s", SLIDER, "s", show=_DYNAMIC),
+            Field("price_now_entity", ENTITY, kind="any"),
+            Field("price_avg_entity", ENTITY, kind="any"),
+        ), collapsed=True),
+    )),
+    Group("safety", (
+        Part("peak", (
+            Field("peak_cap_w", SLIDER, "kW", scale=1000, step=100,
+                  simple=True, wizard=5),
+            Field("peak_forecast_entity", ENTITY, kind="power_w", wizard=5),
+            Field("peak_soc_floor", LOCKED, "%"),
+        )),
+        Part("start", (
+            Field("shadow_mode", SEGMENTED, simple=True, wizard=6),
+            Field("auto_start", TOGGLE),
+            Field("estop_fitted", TOGGLE),
+            Field("stale_input_s", SLIDER, "s"),
+            Field("meter_freeze_s", SLIDER, "s", step=30,
+                  show=_src("homewizard_local")),
+        )),
+        Part("stops", (
+            Field("sign_disagree_w", LOCKED, "W", step=10, show=_ONE),
+            Field("sign_disagree_s", LOCKED, "s", step=5, show=_ONE),
+            Field("unit_sign_disagree_w", LOCKED, "W", step=10,
+                  show=_SEVERAL),
+            Field("unit_sign_disagree_s", LOCKED, "s", step=5,
+                  show=_SEVERAL),
+            Field("site_sign_disagree_w", LOCKED, "W", step=10,
+                  show=_SEVERAL),
+            Field("site_sign_disagree_s", LOCKED, "s", step=5,
+                  show=_SEVERAL),
+            Field("circulation_w", LOCKED, "W", step=10, show=_SEVERAL),
+            Field("circulation_hold_s", LOCKED, "s", step=5, show=_SEVERAL),
+            Field("delivery_hold_s", LOCKED, "s", step=5, show=_SEVERAL),
+        ), collapsed=True),
+    )),
+    Group("maintenance", (
+        Part("", (
+            Field("maintenance_enabled", TOGGLE),
+            Field("maintenance_interval_days", SLIDER, "days", show=_MAINT),
+            Field("maintenance_start_hour", SELECT, show=_MAINT),
+            Field("maintenance_discharge_w", SLIDER, "W", step=100,
+                  show=_MAINT),
+            Field("maintenance_charge_w", SLIDER, "W", step=100,
+                  show=_MAINT),
+            Field("maintenance_soc_floor", SLIDER, "%", show=_MAINT),
+            Field("maintenance_soc_target", SLIDER, "%", show=_MAINT),
+            Field("maintenance_hold_min", SLIDER, "min", step=5,
+                  show=_MAINT),
+        )),
+        Part("support", (Field("log_level", SELECT),)),
+    )),
+    Group("tuning", (
+        Part("", (
+            Field("gain", LOCKED, step=0.05),
+            Field("slew_w", LOCKED, "W", step=50),
+            Field("deadband_w", LOCKED, "W"),
+            Field("target_grid_w", LOCKED, "W"),
+            Field("step_w", LOCKED, "W"),
+            Field("saturation_w", LOCKED, "W", step=10),
+            Field("saturation_cycles", LOCKED),
+            Field("integrator_max_w", LOCKED, "W", step=100),
+            Field("heartbeat_s", LOCKED, "s"),
+            Field("cycle_floor_s", LOCKED, "s"),
+        )),
+    ), support_only=True),
+)
+
+# Option keys the page never shows. uimodel.py writes each from page fields.
+DERIVED = {
+    "setpoint_entity": "inverters",       # one inverter, stored flat
+    "soc_entity": "inverters",
+    "batt_entity": "inverters",
+    "batt_invert": "inverters",
+    "max_w": "inverters",
+    "bms_soc_floor": "inverters",
+    "pv_entity": "ui.solar",              # one solar row, stored flat
+    "pv_entities": "ui.solar",
+    "pv_invert_entities": "ui.solar",     # the rows' "reads negative" toggles
+    "static_profile": "ui.fallback",      # built from the price fields
+    "price_taxes_profile": "ui.region",   # a preset writes it, "own" keeps it
+}
+# Option keys the page never shows and never writes: passed through as stored.
+HIDDEN: dict = {}
+
+
+def fields():
+    """Every field once, in page order, roster fields after `inverters`."""
+    for group in GROUPS:
+        for part in group.parts:
+            for field in part.fields:
+                yield group, part, field
+                if field.control == INVERTER_LIST:
+                    for sub in ROSTER_FIELDS:
+                        yield group, part, sub
+
+
+def field(key: str) -> Field | None:
+    return next((f for _g, _p, f in fields() if f.key == key), None)
+
+
+def visible(fld: Field, model: dict) -> bool:
+    """Whether `fld` is shown for this page model (uimodel.options_to_ui)."""
+    for name, op, value in fld.show:
+        have = model.get(name)
+        if op == "==" and have != value:
+            return False
+        if op == "!=" and have == value:
+            return False
+        if op == "in" and have not in value:
+            return False
+        try:
+            if op == ">" and not float(have) > value:
+                return False
+            if op == "<" and not float(have) < value:
+                return False
+        except (TypeError, ValueError):
+            return False
+    return True
+
+
+def range_of(key: str, schema_ui: list):
+    """(min, max) from the Supervisor's schema (`info["schema"]`), or None.
+
+    Never typed here: config.yaml is the one place a range is written. A range
+    arrives as lengthMin/lengthMax (tools/supervisor_selfapi_probe.py)."""
+    path = key.split(".")
+    nodes = schema_ui or []
+    for step in path[:-1]:
+        parent = next((n for n in nodes if n.get("name") == step), None)
+        nodes = (parent or {}).get("schema") or []
+    node = next((n for n in nodes if n.get("name") == path[-1]), None)
+    if not node or "lengthMin" not in node or "lengthMax" not in node:
+        return None
+    return node["lengthMin"], node["lengthMax"]

goodwe_controller/app/uimodel.py

@@ -0,0 +1,350 @@
+"""UX-13: stored options <-> the page model, for the keys the page derives.
+
+`options_to_ui()` turns the stored blob into what the page edits: always a list
+of inverter cards, solar rows with a "reads negative" toggle, a contract and
+simple prices instead of `static_profile` JSON, and a region preset instead of
+the levies figure. `ui_to_options()` turns it back, so the validator and the
+Supervisor always see the real blob.
+
+The rule that makes the round trip exact: the model carries the stored values
+of the derived keys (`keep`). A derivation whose page fields still read what
+`keep` decodes to writes `keep` back untouched, and only an edited one is
+re-encoded. So a blob the page cannot express (a `static_profile` with odd
+windows, a malformed roster) survives a save of some other field unchanged.
+See DECISIONS/UX-13-one-layout-table.md.
+"""
+
+import copy
+import json
+
+from .price import FLEMISH_TAXES_COMPONENTS_EUR_KWH
+from .static_tariff import ProfileInvalid, parse_static_profile
+
+__all__ = ["options_to_ui", "ui_to_options", "REGION_PRESETS",
+           "arbitrage_from_batteries", "DeriveError", "COUNT", "GROWN"]
+
+
+class DeriveError(ValueError):
+    """The page model asks for something no options blob can say. `code` names
+    the sentence the page shows (app/ui_text `derive.<code>`), and `field` the
+    page field it is shown beside."""
+
+    def __init__(self, text, code="", field=""):
+        super().__init__(text)
+        self.code, self.field = code, field
+
+
+# The page model's inverter count, which show conditions read, and what adding
+# a card sets: a second inverter turns the one flat inverter into a list.
+COUNT = "inverter_count"
+GROWN = {"inverter_shape": "list"}
+
+
+# --------------------------------------------------------------------------- #
+# Region presets for "Grid costs, levies and VAT". Year-stamped, updated each
+# January (owner, 2026-09-27). Only presets with a sourced figure are listed:
+# Flanders is app/price.py's Fluvius Antwerpen sum (TARIFF-18: Eneco
+# residential card, Flanders, September 2026, VAT included). Wallonia and
+# Brussels have a day and a night band (config.yaml) and join with sourced
+# figures; until then those sites choose "own".
+# --------------------------------------------------------------------------- #
+REGION_PRESETS = {
+    "flanders": {
+        "year": 2026,
+        "taxes_eur_kwh": round(sum(v for _n, v in
+                                   FLEMISH_TAXES_COMPONENTS_EUR_KWH), 5),
+        "taxes_profile": "",
+    },
+}
+OWN = "own"
+
+_ROSTER_FLAT = ("setpoint_entity", "soc_entity", "batt_entity", "batt_invert",
+                "max_w", "bms_soc_floor")
+_TOL = 1e-9
+
+
+def _blank(v) -> bool:
+    return v is None or (isinstance(v, str) and not v.strip())
+
+
+def _num(v):
+    try:
+        return None if _blank(v) or isinstance(v, bool) else float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+# --- 1. one inverter (flat keys) or the `inverters` list -------------------- #
+def _roster_decode(o):
+    entries = o.get("inverters")
+    if entries is None or entries == "" or entries == []:
+        card = {k: o.get(k) for k in _ROSTER_FLAT}
+        card.update(name="", capacity_kwh=None)
+        return {"inverter_shape": "flat", "inverters": [card]}
+    if isinstance(entries, list) and all(isinstance(e, dict) for e in entries):
+        return {"inverter_shape": "list",
+                "inverters": [dict(e) for e in entries]}
+    # Not something a card can show: edited in the Configuration tab only.
+    return {"inverter_shape": "raw", "inverters": None}
+
+
+def _roster_encode(m, keep):
+    out = {}
+    shape, cards = m.get("inverter_shape"), m.get("inverters")
+    if shape == "raw":
+        raise DeriveError("the inverter list is edited in the Configuration tab",
+                          "raw_roster", "inverters")
+    if not cards:
+        raise DeriveError("at least one inverter is needed", "no_inverter",
+                          "inverters")
+    if shape == "flat" and len(cards) == 1:
+        card = cards[0]
+        if not _blank(card.get("name")) or not _blank(card.get("capacity_kwh")):
+            raise DeriveError("one inverter stored flat has no name or "
+                              "capacity", "flat_named", "inverters")
+        for k in _ROSTER_FLAT:
+            if card.get(k) is not None or k in keep:
+                out[k] = card.get(k)
+        out["inverters"] = []
+        return out
+    out["inverters"] = [{k: v for k, v in c.items() if v is not None}
+                        for c in cards]
+    # The flat keys beside a list are not read: they stay as stored.
+    out.update({k: copy.deepcopy(keep[k]) for k in _ROSTER_FLAT if k in keep})
+    if shape == "flat" or _roster_decode(keep)["inverter_shape"] == "flat":
+        # CFG-04 rule 9e: a flat power request entity beside a list is refused,
+        # so a list that replaces the flat inverter clears it.
+        out["setpoint_entity"] = ""
+    return out
+
+
+# --- 2. solar rows: pv_entity / pv_entities / pv_invert_entities ------------ #
+def _strs(v):
+    return [str(x).strip() for x in (v if isinstance(v, list) else [])
+            if not _blank(x)]
+
+
+def _solar_rows(o):
+    listed = _strs(o.get("pv_entities"))
+    if listed:
+        return listed, True
+    one = "" if _blank(o.get("pv_entity")) else str(o.get("pv_entity")).strip()
+    return ([one] if one else []), False
+
+
+def _solar_decode(o):
+    rows, _listed = _solar_rows(o)
+    flipped = set(_strs(o.get("pv_invert_entities")))
+    return {"ui.solar": [{"entity": e, "reversed": e in flipped}
+                         for e in rows]}
+
+
+def _solar_encode(m, keep):
+    out = {}
+    rows = [r for r in (m.get("ui.solar") or [])
+            if not _blank(r.get("entity"))]
+    entities = [str(r["entity"]).strip() for r in rows]
+    old_rows, was_list = _solar_rows(keep)
+    if len(entities) <= 1 and not was_list:
+        out["pv_entity"] = entities[0] if entities else ""
+        if "pv_entities" in keep:
+            out["pv_entities"] = []
+    else:
+        out["pv_entities"] = entities
+        if "pv_entity" in keep:
+            out["pv_entity"] = ""       # TEL-12: the list replaces it
+    # Flips of entities that were never a row stay as stored (pv.stray_inverts
+    # reports them). Flips of removed rows go with the row.
+    extras = [x for x in _strs(keep.get("pv_invert_entities"))
+              if x not in old_rows and x not in entities]
+    flips = [e for e, r in zip(entities, rows) if r.get("reversed")] + extras
+    if flips or "pv_invert_entities" in keep:
+        out["pv_invert_entities"] = flips
+    return out
+
+
+# --- 3. contract and static_profile ----------------------------------------- #
+def _fixed_json(price) -> str:
+    return json.dumps({"periods": [
+        {"name": "all", "from": "00:00", "to": "24:00", "days": "mon-sun",
+         "eur_per_kwh": price}]})
+
+
+def _daynight_json(day, night) -> str:
+    return json.dumps({"periods": [
+        {"name": "day", "from": "07:00", "to": "22:00", "days": "mon-fri",
+         "eur_per_kwh": day},
+        {"name": "night", "from": "22:00", "to": "07:00", "days": "mon-fri",
+         "eur_per_kwh": night},
+        {"name": "night", "from": "00:00", "to": "24:00", "days": "sat,sun",
+         "eur_per_kwh": night}]})
+
+
+def _shape(text):
+    """The periods of a profile without their names, for comparing, or None."""
+    try:
+        prof = parse_static_profile(text)
+    except ProfileInvalid:
+        return None
+    if prof is None:
+        return ()
+    return tuple(sorted((p.start_min, p.end_min, tuple(sorted(p.days)),
+                         p.eur_per_kwh) for p in prof.periods))
+
+
+def _profile_decode(raw):
+    """("none"|"fixed"|"daynight"|"custom", fixed, day, night)."""
+    if isinstance(raw, str) and _blank(raw):
+        return "none", None, None, None
+    if not isinstance(raw, str):
+        return "custom", None, None, None
+    got = _shape(raw)
+    if not got:
+        return ("none" if got == () else "custom"), None, None, None
+    if len(got) == 1 and got == _shape(_fixed_json(got[0][3])):
+        return "fixed", got[0][3], None, None
+    day = next((p[3] for p in got if p[:2] == (420, 1320)), None)
+    night = next((p[3] for p in got if p[:2] == (1320, 420)), None)
+    if (day is not None and night is not None
+            and got == _shape(_daynight_json(day, night))):
+        return "daynight", None, day, night
+    return "custom", None, None, None
+
+
+def _tariff_decode(o):
+    kind, fixed, day, night = _profile_decode(o.get("static_profile", ""))
+    provider = o.get("price_provider")
+    dynamic = not _blank(provider) and provider != "off"
+    return {"ui.contract": "dynamic" if dynamic else kind,
+            "price_provider": provider, "ui.fallback": kind,
+            "ui.fixed_price": fixed, "ui.day_price": day,
+            "ui.night_price": night}
+
+
+def _tariff_encode(m, keep):
+    out = {}
+    contract = m.get("ui.contract")
+    if contract == "dynamic":
+        if _blank(m.get("price_provider")) or m.get("price_provider") == "off":
+            raise DeriveError("a dynamic contract needs a price source",
+                              "no_source", "price_provider")
+        out["price_provider"] = m["price_provider"]
+        kind = m.get("ui.fallback")
+    else:
+        out["price_provider"] = "off"
+        kind = contract
+    if kind == "none":
+        out["static_profile"] = ""
+    elif kind == "fixed":
+        out["static_profile"] = _fixed_json(_price_of(m, "ui.fixed_price"))
+    elif kind == "daynight":
+        out["static_profile"] = _daynight_json(_price_of(m, "ui.day_price"),
+                                               _price_of(m, "ui.night_price"))
+    elif kind == "custom":
+        if "static_profile" not in keep:
+            raise DeriveError("odd tariff windows are edited in the "
+                              "Configuration tab", "custom_profile",
+                              "ui.contract")
+        out["static_profile"] = keep["static_profile"]
+    else:
+        raise DeriveError(f"unknown contract {kind!r}", "unknown",
+                          "ui.contract")
+    return out
+
+
+def _price_of(m, name):
+    value = _num(m.get(name))
+    if value is None:
+        raise DeriveError(f"{name} needs a price", "no_price", name)
+    return value
+
+
+# --- 4. region preset -> price_taxes_eur_kwh / price_taxes_profile ---------- #
+def _region_decode(o):
+    taxes, profile = o.get("price_taxes_eur_kwh"), o.get("price_taxes_profile", "")
+    region = OWN
+    for rid, p in REGION_PRESETS.items():
+        same = _num(taxes) is not None and abs(_num(taxes) - p["taxes_eur_kwh"]) < _TOL
+        if same and str(profile or "").strip() == p["taxes_profile"]:
+            region = rid
+    return {"ui.region": region, "price_taxes_eur_kwh": taxes}
+
+
+def _region_encode(m, keep):
+    region = m.get("ui.region")
+    if region == OWN:
+        out = {"price_taxes_eur_kwh": m.get("price_taxes_eur_kwh")}
+        if "price_taxes_profile" in keep:       # "own" keeps the stored table
+            out["price_taxes_profile"] = keep["price_taxes_profile"]
+        return out
+    if region not in REGION_PRESETS:
+        raise DeriveError(f"unknown region {region!r}", "unknown", "ui.region")
+    p = REGION_PRESETS[region]
+    out = {"price_taxes_eur_kwh": p["taxes_eur_kwh"]}
+    if p["taxes_profile"] or "price_taxes_profile" in keep:
+        out["price_taxes_profile"] = p["taxes_profile"]
+    return out
+
+
+# --- 5. arbitrage_enabled: the OPT-11 hook ---------------------------------- #
+def arbitrage_from_batteries(m):
+    """OPT-11 hook. With battery modes on, `arbitrage_enabled` is true when any
+    battery may sell. Battery modes are not built yet, so this returns None and
+    the toggle is stored as the page has it: no behaviour change."""
+    return None
+
+
+def _arbitrage_decode(o):
+    return {"arbitrage_enabled": o.get("arbitrage_enabled")}
+
+
+def _arbitrage_encode(m, keep):
+    derived = arbitrage_from_batteries(m)
+    value = m.get("arbitrage_enabled") if derived is None else derived
+    return {} if value is None and "arbitrage_enabled" not in keep \
+        else {"arbitrage_enabled": value}
+
+
+# (option keys it writes, decode, encode). Each is independent of the others.
+DERIVATIONS = (
+    (("inverters",) + _ROSTER_FLAT, _roster_decode, _roster_encode),
+    (("pv_entity", "pv_entities", "pv_invert_entities"), _solar_decode,
+     _solar_encode),
+    (("price_provider", "static_profile"), _tariff_decode, _tariff_encode),
+    (("price_taxes_eur_kwh", "price_taxes_profile"), _region_decode,
+     _region_encode),
+    (("arbitrage_enabled",), _arbitrage_decode, _arbitrage_encode),
+)
+_OWNED = {k for keys, _d, _e in DERIVATIONS for k in keys}
+_MODEL_ONLY = ("keep", "inverter_shape", "inverter_count", "region_year")
+
+
+def options_to_ui(options: dict) -> dict:
+    """The page model for a stored blob. Pure: reads nothing else."""
+    model = {k: copy.deepcopy(v) for k, v in options.items()
+             if k not in _OWNED}
+    for _keys, decode, _encode in DERIVATIONS:
+        model.update(decode(options))
+    model["keep"] = {k: copy.deepcopy(options[k]) for k in _OWNED
+                     if k in options}
+    cards = model.get("inverters")
+    model["inverter_count"] = len(cards) if isinstance(cards, list) else None
+    preset = REGION_PRESETS.get(model["ui.region"])
+    model["region_year"] = preset["year"] if preset else None
+    return model
+
+
+def ui_to_options(model: dict) -> dict:
+    """The options blob for a page model. Raises DeriveError on a model no blob
+    can express, so the page says so instead of saving something else."""
+    keep = model.get("keep") or {}
+    out = {k: copy.deepcopy(v) for k, v in model.items()
+           if k not in _MODEL_ONLY and k not in _OWNED
+           and not k.startswith("ui.")}
+    for keys, decode, encode in DERIVATIONS:
+        was = decode(keep)
+        if all(model.get(name) == value for name, value in was.items()):
+            out.update({k: copy.deepcopy(keep[k]) for k in keys if k in keep})
+        else:
+            out.update(encode(model, keep))
+    return out

goodwe_controller/app/uipage.py

@@ -0,0 +1,280 @@
+"""UX-13 P2: the settings view's server half. It names no option key.
+
+It turns app/uilayout.py's table into the JSON the page draws from (labels
+from the Supervisor's translations, ranges and choices from its schema, page
+words from app/ui_text), turns a posted page model into options through
+app/uimodel.py, and says beside which page field each validator sentence
+goes. The rules stay in validate.py and the sentences are passed on as they
+are (DECISIONS/UX-13-one-layout-table.md).
+"""
+
+import copy
+import io
+import json
+import os
+import re
+
+from . import uilayout as L
+from . import uimodel as U
+from .configui import help_of, label_of, problems_by_field, split_group
+
+UI_TEXT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "ui_text",
+                       "en.json")
+# A choice the page cannot make, only keep: odd tariff windows (P5 editor).
+ONLY_IF_HELD = ("custom",)
+_TIERS = ("bad", "warn", "info")
+
+
+def ui_text() -> dict:
+    with io.open(UI_TEXT, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _roster():
+    """The inverter list field's key, read off the table."""
+    return next(f.key for _g, _p, f in L.fields()
+                if f.control == L.INVERTER_LIST)
+
+
+def _node(schema_ui, key):
+    """The Supervisor's schema entry for `key` (`list.sub` too), or {}."""
+    nodes, path = schema_ui or [], key.split(".")
+    for step in path[:-1]:
+        parent = next((n for n in nodes if n.get("name") == step), None)
+        nodes = (parent or {}).get("schema") or []
+    return next((n for n in nodes if n.get("name") == path[-1]), None) or {}
+
+
+def _words(translations, lang, key, T):
+    """(label, help) for a field: ui_text for `ui.` fields, else the
+    translation without its `Group · ` prefix, and the raw key last."""
+    if key.startswith("ui."):
+        entry = T["fields"].get(key[3:], {})
+        return entry.get("name", key), entry.get("description", "")
+    path = tuple(key.split(".")[:-1])
+    name = key.split(".")[-1]
+    label, _lang = label_of(translations, lang, name, path)
+    text, _lang = help_of(translations, lang, name, path)
+    return split_group(label)[1], text
+
+
+def _choices(fld, node, T, value_type):
+    """[[value, label, only_if_held], ...] for a choice control, or None."""
+    if fld.control not in (L.SEGMENTED, L.SELECT, L.CHOICE):
+        return None
+    name = fld.key[3:] if fld.key.startswith("ui.") else fld.key
+    words = T["choices"].get(name) or {}
+    if fld.key.startswith("ui."):
+        values = list(words)
+    elif node.get("options"):
+        values = [v for v in node["options"] if not words or v in words]
+    elif value_type == "integer" and node.get("lengthMax") is not None:
+        values = list(range(int(node["lengthMin"]), int(node["lengthMax"]) + 1))
+        if words:
+            values = [v for v in values if str(v) in words]
+    else:
+        return []
+    out = []
+    for v in values:
+        label = words.get(str(v))
+        if label is None:
+            label = (T["settings"]["hour"].replace("{hour}", f"{v:02d}")
+                     if isinstance(v, int) else str(v))
+        preset = U.REGION_PRESETS.get(v) if fld.fills else None
+        if preset:
+            label = f"{label}, " + T["settings"]["region_year"].replace(
+                "{year}", str(preset["year"]))
+        out.append([v, label, v in ONLY_IF_HELD])
+    return out
+
+
+def _field(fld, schema_ui, translations, lang, T):
+    node = _node(schema_ui, fld.key)
+    label, text = _words(translations, lang, fld.key, T)
+    if fld.unit:
+        # The page shows the unit beside the control, in its own scale (kW),
+        # so the translation's "(W)" goes; "(optional)" stays.
+        label = re.sub(r"\s*\([^()\s]{1,6}\)", "", label)
+    value_type = ("float" if fld.control == L.NUMBER and fld.key.startswith("ui.")
+                  else node.get("type") or "")
+    out = {"key": fld.key, "control": fld.control, "label": label,
+           "help": text, "unit": fld.unit, "scale": fld.scale,
+           "step": fld.step, "kind": fld.kind,
+           "show": [list(c) for c in fld.show], "applies": fld.applies,
+           "type": value_type, "optional": not node.get("required", False),
+           # A choice mirrored into a field also shows (and finds) its keys.
+           "writes": sorted(k for k, how in L.DERIVED.items()
+                            if how in (fld.key, fld.mirror))}
+    if node.get("lengthMin") is not None:
+        out["min"] = node["lengthMin"]
+    if node.get("lengthMax") is not None:
+        out["max"] = node["lengthMax"]
+    choices = _choices(fld, node, T, value_type)
+    if choices is not None:
+        out["choices"] = choices
+        name = fld.key[3:] if fld.key.startswith("ui.") else fld.key
+        later = T.get("choices_later", {}).get(name)
+        if later:
+            out["later"] = [[v, words] for v, words in later.items()]
+        hints = T.get("choice_help", {}).get(name)
+        if hints:
+            out["hints"] = {v: e.get("description", "")
+                            for v, e in hints.items()}
+    if fld.mirror:
+        out["mirror"] = fld.mirror
+    if fld.fills:
+        out["fills"] = fld.fills
+        out["presets"] = {rid: {"year": p["year"], "value": p["taxes_eur_kwh"]}
+                          for rid, p in U.REGION_PRESETS.items()}
+    roster = _roster()
+    if fld.key.startswith(roster + "."):
+        sub = fld.key[len(roster) + 1:]
+        if L.DERIVED.get(sub) == roster:
+            out["flat"] = sub           # how the one flat inverter stores it
+    if fld.control == L.INVERTER_LIST:
+        out["fields"] = [_field(sub, schema_ui, translations, lang, T)
+                         for sub in L.ROSTER_FIELDS]
+        out["count"] = U.COUNT
+        out["grow"] = dict(U.GROWN)
+        out["shape"] = next(iter(U.GROWN))
+    return out
+
+
+def layout(schema_ui, translations, lang="en") -> dict:
+    """Every group, part and field of the Installer view, as the page draws
+    it. Built from the table only: a field the table places is on the page."""
+    T = ui_text()
+    groups = []
+    for g in L.GROUPS:
+        parts = []
+        for p in g.parts:
+            words = T["parts"].get(f"{g.id}.{p.id}", {}) if p.id else {}
+            parts.append({"id": p.id, "name": words.get("name", ""),
+                          "description": words.get("description", ""),
+                          "collapsed": p.collapsed,
+                          "fields": [_field(f, schema_ui, translations, lang, T)
+                                     for f in p.fields]})
+        words = T["groups"].get(g.id, {})
+        applies = sorted({f.applies for p in g.parts for f in p.fields})
+        groups.append({"id": g.id, "name": words.get("name", g.id),
+                       "description": words.get("description", ""),
+                       "support_only": g.support_only,
+                       "applies": [T["applies"][a]["name"] for a in applies],
+                       "parts": parts})
+    return {"groups": groups}
+
+
+# --------------------------------------------------------------------------- #
+# The page model -> options, for the validator and the save
+# --------------------------------------------------------------------------- #
+def _same(a, b) -> bool:
+    """Equal as the Supervisor stores it: 3 and 3.0 alike, True and 1 not."""
+    if isinstance(a, bool) or isinstance(b, bool):
+        return type(a) is type(b) and a == b
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        return a == b
+    if isinstance(a, list) and isinstance(b, list):
+        return len(a) == len(b) and all(_same(x, y) for x, y in zip(a, b))
+    if isinstance(a, dict) and isinstance(b, dict):
+        return a.keys() == b.keys() and all(_same(a[k], b[k]) for k in a)
+    return type(a) is type(b) and a == b
+
+
+def to_options(model: dict, stored: dict | None = None) -> dict:
+    """The options blob for a posted page model. A value equal to the stored
+    one is written as stored, in the stored key order, so a save that changed
+    nothing writes an identical blob (the browser reads 3.0 as 3)."""
+    out = U.ui_to_options(model)
+    stored = stored or {}
+    for k, v in out.items():
+        if k in stored and _same(v, stored[k]):
+            out[k] = copy.deepcopy(stored[k])
+    return ({k: out[k] for k in stored if k in out}
+            | {k: v for k, v in out.items() if k not in stored})
+
+
+def derive_message(err: U.DeriveError) -> dict:
+    words = ui_text()["settings"]["derive"]
+    text = words.get(err.code, words["unknown"])["description"]
+    return {"field": err.field or None, "card": None, "tier": "bad",
+            "text": text}
+
+
+# --------------------------------------------------------------------------- #
+# Where a sentence goes on the page
+# --------------------------------------------------------------------------- #
+# `inverters.max_w`, or `inverters[1].setpoint_entity` for one card.
+_SUB = re.compile(r"(?<![A-Za-z0-9_])([a-z_0-9]+)(?:\[(\d+)\])?\.([a-z_0-9]+)")
+
+
+def _mirror_of(key):
+    return next((f.key for _g, _p, f in L.fields() if f.mirror == key), None)
+
+
+def targets(key: str, text: str, model: dict) -> list:
+    """[(page field, card)] for a sentence that names option `key`. `card` is
+    the inverter card's index, or None."""
+    roster = _roster()
+    cards = model.get(roster) if isinstance(model.get(roster), list) else []
+    names = [c.get("name") for c in cards if isinstance(c, dict)]
+    # messages.setting(): “Inverter rating” for inverter-b (inverters.max_w),
+    # or a roster rule's own `inverters[1] (inverter-b)`.
+    card = next((i for i, n in enumerate(names)
+                 if n and f"for {n} ({roster}." in text), None)
+    index = re.search(re.escape(roster) + r"\[(\d+)\]", text)
+    if card is None and index and int(index.group(1)) < len(cards):
+        card = int(index.group(1))
+    if key == roster:
+        subs = [(f"{roster}.{s}", int(i) if i and int(i) < len(cards) else card)
+                for r, i, s in _SUB.findall(text) if r == roster]
+        subs = [x for x in dict.fromkeys(subs) if L.field(x[0])]
+        return subs or [(roster, card)]
+    if key in L.DERIVED:
+        how = L.DERIVED[key]
+        if how == roster:
+            return [(f"{roster}.{key}", 0 if card is None else card)]
+        fld = L.field(how)
+        if fld is not None and not L.visible(fld, model) and _mirror_of(how):
+            return [(_mirror_of(how), None)]
+        return [(how, None)]
+    if L.field(key) is not None:
+        return [(key, None)]
+    return [(None, None)]
+
+
+def anchors(problems, notes, model, keys) -> list:
+    """[{field, card, tier, text}] for the refusals and notes. `field` is
+    None for a sentence that names no setting on the page."""
+    out, seen = [], set()
+
+    def add(field, card, tier, text):
+        if (field, card, text) not in seen:
+            seen.add((field, card, text))
+            out.append({"field": field, "card": card, "tier": tier,
+                        "text": text})
+
+    by_key, unanchored = problems_by_field(problems, keys)
+    for key, texts in by_key.items():
+        for text in texts:
+            for field, card in targets(key, text, model):
+                add(field, card, "bad", text)
+    for text in unanchored:
+        add(None, None, "bad", text)
+    for note in notes:
+        tier = note.tier if note.tier in _TIERS else "info"
+        for key in note.keys or (None,):
+            for field, card in (targets(key, note.text, model) if key
+                                else [(None, None)]):
+                add(field, card, tier, note.text)
+    # A sentence placed on one inverter's field is not also put on the list.
+    roster = _roster()
+    placed = {m["text"] for m in out
+              if (m["field"] or "").startswith(roster + ".")}
+    return [m for m in out if not (m["field"] == roster
+                                   and m["text"] in placed)]
+
+
+def fields_of(keys, model) -> list:
+    """The page fields that show these option keys (a stale save's list)."""
+    return list(dict.fromkeys(f for k in keys for f, _c in targets(k, "", model)
+                              if f))

goodwe_controller/app/validate.py

@@ -321,8 +321,9 @@ WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
 """
 
 import logging
+from typing import NamedTuple
 
-from . import messages
+from . import messages, pv
 from .arbitrage import enabled as arbitrage_on
 from .control import SLEW_RAIL_FRAC, LOOP_TICK_S, PLANT_SETTLE_S
 from .custom_formula import (
@@ -330,7 +331,8 @@ from .custom_formula import (
     parse_export_formula, parse_price_formula, stale_card)
 from .inverter import roster_entries
 from .maintenance import MAINT_OPTION_DEFAULTS
-from .p1 import is_enabled, validate_meter_options
+from .p1 import (
+    SOURCE_HA, SOURCE_HA_SIGNED, is_enabled, validate_meter_options)
 from .peakguard import PEAK_OPTION_DEFAULTS
 from .price import (
     PRICE_OPTION_DEFAULTS, PROVIDERS, RETIRED_PROVIDERS,
@@ -343,6 +345,46 @@ from .watchdog import SIGN_OPTION_DEFAULTS
 
 _LOG = logging.getLogger("goodwe.config")
 
+
+class _WarnOnce(logging.Filter):
+    """UX-10: a settings warning is said once per start. The validator runs
+    twice at start (before the first cycle and again once the inverter's range
+    is known), and a warning about options that have not changed is the same
+    news both times. Refusals are ERROR and pass untouched."""
+
+    def __init__(self):
+        super().__init__()
+        self.seen = set()
+
+    def filter(self, record):
+        if record.levelno != logging.WARNING:
+            return True
+        text = record.getMessage()
+        if text in self.seen:
+            return False
+        self.seen.add(text)
+        return True
+
+
+WARN_ONCE = _WarnOnce()
+_LOG.addFilter(WARN_ONCE)
+
+
+class Note(NamedTuple):
+    """UX-13: a warning or info for the settings page. Never a refusal: the
+    add-on starts. `keys` are the options it is about, so the page can show it
+    beside them."""
+    tier: str                   # "warn" or "info"
+    keys: tuple
+    text: str
+
+
+def _advise(notes, tier: str, keys, text: str) -> None:
+    """Add a Note when the caller collects them (the settings page)."""
+    if notes is not None:
+        notes.append(Note(tier, tuple(keys), text))
+
+
 # ⚠️ A MIRROR OF A FIRMWARE CONSTANT, AND IT CANNOT BE IMPORTED. The firmware
 # threshold is a compile-time YAML substitution baked into the ESP32 image
 # (`max_age_s: "30"`, master/goodwe-master-stage4-failsafe.yaml), so nothing at
@@ -765,7 +807,8 @@ class ConfigRefused(Exception):
         super().__init__(problems[0] if problems else "configuration refused")
 
 
-def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]:
+def validate_startup_config(opts: dict, dev_min=None, dev_max=None,
+                            notes: list | None = None) -> list[str]:
     """Return the list of reasons this configuration must not be started.
 
     Empty list means go. `dev_min`/`dev_max` are the setpoint device's own
@@ -775,6 +818,9 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
 
     Pure and side-effect free apart from two warnings, so it can be called from
     a test or from sim/inject.py without a Home Assistant anywhere near it.
+
+    UX-13: pass a list as `notes` to also get each logged warning as a `Note`
+    for the settings page. The refusals returned do not depend on it.
     """
     problems: list[str] = []
 
@@ -1103,7 +1149,7 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
                 f"site. Set it to 0 or to at most {bound:.0f} W.")
 
     # --- 7. two price sources on one site ------------------------------------
-    problems.extend(_price_problems(opts))
+    problems.extend(_price_problems(opts, notes))
 
     # --- 8. an EMS energy floor the BMS does not already enforce -------------
     # ⚠️ THE FALLBACKS ARE peakguard.PEAK_OPTION_DEFAULTS, NOT LITERALS, and
@@ -1149,6 +1195,9 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
             "integrator_max_w %.0f W is above max_w %.0f W. This is allowed, "
             "but it only adds overshoot, so 0 is recommended.",
             integ_w, max_w)
+        _advise(notes, "warn", ("integrator_max_w",),
+                f"{S('integrator_max_w')} is above {S('max_w')}, which only "
+                "adds overshoot, so set it to 0.")
 
     # ⚠️ THE SIBLING OF RULE 6, AND NOT THE SAME CASE - see the docstring. The
     # drain phase OWNS the actuator (`Claim.set` at P_MAINTENANCE), and a SET is
@@ -1173,6 +1222,10 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
             "maintenance_discharge_w %.0f W is above max_w%s %.0f W, so "
             "draining runs at %.0f W. Lower it to %.0f W or raise max_w.",
             disch_w, maint_where, maint_cap, maint_cap, maint_cap)
+        _advise(notes, "warn", ("maintenance_discharge_w",),
+                f"{S('maintenance_discharge_w')} is above "
+                f"{S('max_w', maint_where)}, so the battery empties at "
+                f"{messages.watts(maint_cap)} and the cycle takes longer.")
         _LOG.debug(
             "Not refused: the drain phase sets the setpoint, the arbiter "
             "clamps it to %.0f W and names the clamp, and the drain phase has "
@@ -1181,7 +1234,7 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     return problems
 
 
-def _price_problems(opts: dict) -> list[str]:
+def _price_problems(opts: dict, notes: list | None = None) -> list[str]:
     """Rule 7 (TARIFF-02): the price configuration, refused where it is untrue.
 
     ⚠️ NOTE WHAT IS *NOT* HERE. `price_provider: "off"` is not refused and never
@@ -1314,12 +1367,11 @@ def _price_problems(opts: dict) -> list[str]:
         if profile is not None and profile.product is not None \
                 and len(set(profile.prices)) == 1:
             _LOG.info(
-                "static_profile carries one distinct price (%.4f EUR/kWh "
-                "all-in), so this site is priced as FULLY FIXED. Arbitrage is "
-                "off by arithmetic - a flat series has no spread - and the "
-                "add-on runs self-consumption only, which is §9.2's handling "
-                "for this product. Peak shaving, reserve management and the "
-                "maintenance cycle are unaffected.", profile.prices[0])
+                "static_profile has one price (%.4f EUR/kWh all-in), so this "
+                "site has a fully fixed price. A flat price has no spread to "
+                "trade on, so the add-on uses the battery for self-consumption "
+                "only. Peak limiting, the reserve and battery maintenance are "
+                "not affected.", profile.prices[0])
 
     # ⚠️ TARIFF-17: THE TAXES PERIOD TABLE, PARSED AT STARTUP RATHER THAN AT
     # 03:00, FOR `static_profile`'s REASON ONE OPTION OVER. This table is read
@@ -1400,6 +1452,9 @@ def _price_problems(opts: dict) -> list[str]:
                 "%s has negative levies %s EUR/kWh, which are subtracted from "
                 "the price. This is allowed, but it is usually a sign error.",
                 TAXES_PROFILE_OPTION, negative)
+            _advise(notes, "warn", (TAXES_PROFILE_OPTION,),
+                    f"{S(TAXES_PROFILE_OPTION)} has negative figures, which "
+                    "lower the price, and that is usually a sign error.")
 
     # ⚠️ TARIFF-15: THE FORMULA, GRADED AGAINST THE OPERATOR'S OWN CARD, AT
     # STARTUP RATHER THAN AT 03:00.
@@ -1455,6 +1510,10 @@ def _price_problems(opts: dict) -> list[str]:
                 "price_formula is filled in, but price_provider is %r, so the "
                 "formula is not used. Set price_provider to 'custom_formula' "
                 "or clear price_formula.", pid)
+            _advise(notes, "warn", ("price_formula", "price_provider"),
+                    f"{S('price_formula')} is not used, because "
+                    f"{S('price_provider')} is not 'custom_formula', so clear "
+                    "it or choose that source.")
         if spec is not None and pid == "custom_formula":
             taxes = _number(opts, "price_taxes_eur_kwh",
                             PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"])
@@ -1468,6 +1527,8 @@ def _price_problems(opts: dict) -> list[str]:
                 # exactly right and a site refused over one is a site that
                 # cannot start.
                 _LOG.warning("%s", aged)
+                _advise(notes, "warn", ("price_formula",),
+                        _card_note("price_formula", spec))
 
     # ⚠️ TARIFF-16: THE INJECTION LEG, REFUSED AT STARTUP ON THE SAME RULE.
     #
@@ -1505,9 +1566,9 @@ def _price_problems(opts: dict) -> list[str]:
             _LOG.info(
                 "%s is set: injection priced as (%g x index %+g) x "
                 "(1 + %g/100) %s, i.e. %.4g x the wholesale price with a "
-                "%+.5f EUR/kWh offset. ⚠️ NO STRATEGY IN THIS ADD-ON READS "
-                "IT: arbitrage.py prices the sell side as displaced IMPORT "
-                "and compares two all-in CONSUMPTION prices, so this option "
+                "%+.5f EUR/kWh offset. No part of the add-on reads it yet: "
+                "trading prices the sell side as displaced import and "
+                "compares two all-in consumption prices, so this setting "
                 "changes no decision the add-on takes today. It is what you "
                 "are shown, and the shape a future export-aware strategy "
                 "would read.",
@@ -1548,6 +1609,9 @@ def _price_problems(opts: dict) -> list[str]:
                     "%.4g, offset %+.5f EUR/kWh).",
                     EXPORT_FORMULA_OPTION, xspec.passthrough,
                     xspec.offset_eur_kwh)
+                _advise(notes, "info", (EXPORT_FORMULA_OPTION,),
+                        f"{S(EXPORT_FORMULA_OPTION)} has no card block, so "
+                        "only the shape of its numbers is checked.")
                 _LOG.debug(
                     "Accepted because some suppliers (Eneco) print the "
                     "injection formula with no price beside it. If your card "
@@ -1559,6 +1623,8 @@ def _price_problems(opts: dict) -> list[str]:
                 xaged = stale_card(xspec)
                 if xaged:
                     _LOG.warning("%s", xaged)
+                    _advise(notes, "warn", (EXPORT_FORMULA_OPTION,),
+                            _card_note(EXPORT_FORMULA_OPTION, xspec))
 
     # ⚠️ A WARNING, NOT A REFUSAL, AND THE ASYMMETRY IS DELIBERATE. §11.4 says a
     # site with no price data falls back to the static profile; a dynamic site
@@ -1570,6 +1636,9 @@ def _price_problems(opts: dict) -> list[str]:
             "price_provider is %r but static_profile is empty, so a price "
             "feed outage leaves no tariff at all. Fill in static_profile as a "
             "fallback.", pid)
+        _advise(notes, "warn", ("static_profile",),
+                f"{S('static_profile')} is empty, so the site has no tariff "
+                "at all while the price feed is down.")
 
     # ⚠️ OPT-04. THE THREE WAYS `arbitrage_enabled: true` CAN BE A LIE, refused
     # rather than logged, because a strategy that is armed in the UI and cannot
@@ -1621,6 +1690,85 @@ def _price_problems(opts: dict) -> list[str]:
     return problems
 
 
+def _card_note(option: str, spec) -> str:
+    return (f"{S(option)} uses a tariff card dated {spec.card_month}, so copy "
+            "the new figures if your contract changed.")
+
+
+# UX-13: entity options whose number the add-on takes as watts, with no unit
+# conversion. pv.py converts each solar entity's own unit, so those are not here.
+WATT_ENTITY_KEYS = (
+    "meter_entity", "p1_net_entity", "p1_import_entity", "p1_export_entity",
+    "p1_phase_net_entities", "p1_phase_import_entities",
+    "p1_phase_export_entities", "batt_entity", "peak_forecast_entity")
+
+
+def _entities_read(opts: dict) -> list[tuple[str, str, str]]:
+    """(key, inverter name or "", entity id) for each entity the add-on reads
+    with these options. Keys the chosen meter source or roster shape ignores
+    are left out, so a stale default is not reported."""
+    out = []
+
+    def add(key, value, where=""):
+        for e in (value if isinstance(value, list) else [value]):
+            if isinstance(e, str) and e.strip():
+                out.append((key, where, e.strip()))
+
+    source = str(opts.get("meter_source") or "off").strip()
+    by_source = {"off": ("meter_entity",),
+                 SOURCE_HA_SIGNED: ("p1_net_entity", "p1_phase_net_entities"),
+                 SOURCE_HA: ("p1_import_entity", "p1_export_entity",
+                             "p1_phase_import_entities",
+                             "p1_phase_export_entities")}
+    for key in by_source.get(source, ()):
+        add(key, opts.get(key))
+    entries = roster_entries(opts)
+    if not entries:
+        for key in ("setpoint_entity", "soc_entity", "batt_entity"):
+            add(key, opts.get(key))
+    for i, entry in enumerate(entries):
+        if isinstance(entry, dict):
+            where = _unit_label(opts, i).strip().strip("()")
+            for key in ("setpoint_entity", "soc_entity", "batt_entity"):
+                add(key, entry.get(key), where)
+    solar = [e for e in (opts.get("pv_entities") or []) if str(e or "").strip()]
+    add("pv_entities" if solar else "pv_entity", list(pv.entities(opts)))
+    for key in ("peak_forecast_entity", "price_now_entity", "price_avg_entity"):
+        add(key, opts.get(key))
+    return out
+
+
+def config_notes(opts: dict, *, entities: dict | None = None,
+                 month_peak_w=None) -> list[Note]:
+    """UX-13: warnings that need live data, for the settings page. Never a
+    refusal, and nothing here changes what `validate_startup_config()` says.
+
+    `entities` is Home Assistant's entity list by id (app/haentities.py), or
+    None when it could not be read, in which case those checks are skipped.
+    `month_peak_w` is this month's peak so far, or None.
+    """
+    notes: list[Note] = []
+    if entities is not None:
+        for key, where, entity in _entities_read(opts):
+            row = entities.get(entity)
+            if row is None:
+                _advise(notes, "warn", (key,),
+                        f"Home Assistant has no entity {entity}, which "
+                        f"{S(key, where)} names.")
+                continue
+            unit = str(row.get("unit") or "")
+            if key in WATT_ENTITY_KEYS and unit in pv.WATTS_PER and unit != "W":
+                _advise(notes, "warn", (key,),
+                        f"{entity} reads in {unit}, but {S(key, where)} is "
+                        "taken as watts, so pick a sensor in W.")
+    cap = _number(opts, "peak_cap_w", None)
+    if month_peak_w is not None and cap is not None and cap < month_peak_w:
+        _advise(notes, "warn", ("peak_cap_w",),
+                f"This month's peak is already {messages.watts(month_peak_w)}, "
+                f"so a lower {S('peak_cap_w')} saves nothing until next month.")
+    return notes
+
+
 def _number(opts: dict, key, default):
     raw = opts.get(key, default)
     if raw is None or raw == "":

goodwe_controller/app/watchdog.py

@@ -670,11 +670,10 @@ class SignWatchdog:
         # ⚠️ `self.against` IS THE ONLY THING SAFETY-30 CHANGED IN THIS STRING,
         # and it defaults to the wording that shipped - "a meter reading" - so a
         # one-inverter install's `reason` is byte-identical to what an operator
-        # (and test_watchdog.py) has always read. A per-unit instance names what
-        # it actually compared instead, because "commanded +1500 W against a
-        # meter reading -1500 W" would be a false statement about which
-        # instrument produced the evidence, on the one line somebody woken by
-        # this alarm reads first.
+        # has always read (test_watchdog.py pins its meaning). A per-unit
+        # instance names what it actually compared instead, because "commanded
+        # +1500 W against a meter reading -1500 W" would be a false statement
+        # about which instrument produced the evidence.
         self.reason = (
             f"SIGN_DISAGREEMENT: commanded {commanded_w:+.0f} W against "
             f"{self.against} {against_w:+.0f} W for {held:.0f} s continuously "

goodwe_controller/app/web.py

@@ -10,7 +10,9 @@ a cellar, by someone who did not write it. Numbers alone are not enough - it
 says what is wrong in words.
 
 ⚠️ SINCE UX-02 THERE ARE TWO PAGES HERE, AND ONLY ONE OF THEM IS THIS FILE'S.
-`/` is the status and control surface and is unchanged. `/config` is the
+`/` is the status and control surface; since UX-13 P1 its files are in
+app/static/ and its Home screen reads the structured half of `/status`
+(app/homeview.py). `/config` is the
 configuration surface: its markup lives in app/config_page.py, its field model
 in app/configui.py and its Supervisor conversation in app/selfconfig.py. What
 stays HERE is the routing, so that the question a reviewer has to answer - does
@@ -24,97 +26,56 @@ routes below read `GET /addons/self/info`, run the SHIPPED validator, write
 mode or reaches `controller.handle_action()`. The set of things an operator can
 do to the inverter through this panel is exactly what `/action` offered before
 this card - test_selfconfig.py part 7 asserts that by listing the routes and the
-actions and comparing them with the shipped set.
+actions and comparing them with the shipped set. UX-13's `ha/entities` is a GET
+of Home Assistant's entity list (app/haentities.py) and writes nothing.
 """
 
+import io
+import json
 import logging
+import os
 
 from aiohttp import web
 
-from . import messages, selfconfig
+from . import messages, selfconfig, uipage
+from .haentities import EntityCache
+from .homeview import region_of
+from .validate import config_notes
 from .config_page import CONFIG_PAGE
 from .configui import changed_keys, field_model, problems_by_field
+from .uimodel import DeriveError, options_to_ui
 
 _LOG = logging.getLogger("goodwe.web")
 
-PAGE = """<!doctype html>
-<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<title>GoodWe RS485 Controller</title>
-<style>
- :root{--bg:#f5f6f8;--card:#fff;--ink:#1c1e21;--muted:#6b7280;--line:#e5e7eb;
-       --ok:#137333;--warn:#b25e02;--bad:#c5221f}
- @media(prefers-color-scheme:dark){:root{--bg:#111317;--card:#1b1e24;--ink:#e8eaed;
-       --muted:#9aa0a6;--line:#2c3038;--ok:#81c995;--warn:#fdd663;--bad:#f28b82}}
- *{box-sizing:border-box}
- body{margin:0;padding:16px;background:var(--bg);color:var(--ink);
-      font:15px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}
- h1{font-size:18px;margin:0 0 12px}
- .card{background:var(--card);border:1px solid var(--line);border-radius:10px;
-       padding:14px;margin-bottom:12px}
- .banner{font-weight:600;padding:12px 14px;border-radius:10px;margin-bottom:12px}
- .b-ok{background:rgba(19,115,51,.12);color:var(--ok)}
- .b-warn{background:rgba(178,94,2,.12);color:var(--warn)}
- .b-bad{background:rgba(197,34,31,.12);color:var(--bad)}
- table{width:100%;border-collapse:collapse}
- td{padding:6px 0;border-bottom:1px solid var(--line);vertical-align:top}
- td:last-child{text-align:right;font-variant-numeric:tabular-nums;font-weight:600}
- tr:last-child td{border-bottom:0}
- .k{color:var(--muted);font-weight:400}
- ul{margin:6px 0 0;padding-left:18px}
- li{margin:3px 0}
- .ok{color:var(--ok)} .bad{color:var(--bad)} .warn{color:var(--warn)}
- button{font:inherit;padding:9px 14px;border-radius:8px;border:1px solid var(--line);
-        background:var(--card);color:var(--ink);cursor:pointer;margin:0 6px 6px 0}
- button.primary{background:#1a73e8;border-color:#1a73e8;color:#fff}
- button.danger{background:var(--bad);border-color:var(--bad);color:#fff}
- .muted{color:var(--muted);font-size:13px}
-</style></head><body>
-<h1>GoodWe RS485 Controller</h1>
-<p class="muted"><a href="config">Configuration &rarr;</a></p>
-<div id="banner" class="banner b-warn">loading…</div>
+# UX-13 P1: the page lives in app/static/ as three files - index.html,
+# app.css, app.js - plus the page words from app/ui_text/en.json. They are
+# joined into ONE response here, once, so the page needs no second request
+# and no route of its own: the route list below is unchanged, and every URL
+# the page uses stays relative (ingress). No build step, no external file.
+STATIC = os.path.join(os.path.dirname(os.path.abspath(__file__)), "static")
+UI_TEXT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "ui_text",
+                       "en.json")
 
-<div class="card">
-  <table id="live"></table>
-</div>
 
-<div class="card">
-  <div class="k">Commissioning</div>
-  <ul id="checks"></ul>
-</div>
+def _read(path):
+    with io.open(path, encoding="utf-8") as f:
+        return f.read()
 
-<div class="card">
-  <button class="primary" onclick="act('auto_toggle')">Start / stop control</button>
-  <button onclick="act('maint_start')">Force maintenance cycle</button>
-  <button class="danger" onclick="act('maint_abort')">Abort maintenance</button>
-  <div class="muted" id="hint"></div>
-</div>
 
-<script>
-async function refresh(){
-  try{
-    const r = await fetch('status', {cache:'no-store'});
-    const s = await r.json();
-    const b = document.getElementById('banner');
-    b.textContent = s.banner;
-    b.className = 'banner ' + (s.level==='ok'?'b-ok':s.level==='bad'?'b-bad':'b-warn');
-    document.getElementById('live').innerHTML = s.rows
-      .map(([k,v]) => `<tr><td class="k">${k}</td><td>${v}</td></tr>`).join('');
-    document.getElementById('checks').innerHTML = s.checks
-      .map(c => `<li class="${c.ok?'ok':(c.warn?'warn':'bad')}">${c.ok?'✓':(c.warn?'!':'✗')} ${c.text}</li>`)
-      .join('');
-    document.getElementById('hint').textContent = s.hint || '';
-  }catch(e){
-    document.getElementById('banner').textContent = 'cannot reach the add-on';
-  }
-}
-async function act(what){
-  await fetch('action', {method:'POST', headers:{'Content-Type':'application/json'},
-                         body: JSON.stringify({action: what})});
-  refresh();
-}
-refresh(); setInterval(refresh, 3000);
-</script></body></html>
-"""
+def page() -> str:
+    """The assembled index page. `</` is escaped inside the two inline
+    scripts, so no text in them can close the tag early."""
+    ui_text = json.dumps(json.loads(_read(UI_TEXT)), ensure_ascii=False)
+    scripts = {}
+    for name in ("app.js", "settings.js"):
+        scripts[name] = _read(os.path.join(STATIC, name))
+        if "</script" in scripts[name].lower():
+            raise ValueError(f"{name} may not contain a closing script tag")
+    return (_read(os.path.join(STATIC, "index.html"))
+            .replace("/*APP_CSS*/", _read(os.path.join(STATIC, "app.css")))
+            .replace("/*UI_TEXT*/", ui_text.replace("</", "<\\/"))
+            .replace("/*APP_JS*/", scripts["app.js"])
+            .replace("/*SETTINGS_JS*/", scripts["settings.js"]))
 
 
 # ⚠️ WHAT THE PANEL SAYS WHEN IT COULD NOT READ A DEVICE RANGE. Two of
@@ -140,9 +101,11 @@ def build_app(controller, selfcfg=None) -> web.Application:
     if selfcfg is None:
         selfcfg = selfconfig.SelfConfig(controller.hass.session,
                                         controller.hass.token)
+    entities = EntityCache(controller.hass)
+    index_page = page()
 
     async def index(_request):
-        return web.Response(text=PAGE, content_type="text/html")
+        return web.Response(text=index_page, content_type="text/html")
 
     async def status(_request):
         return web.json_response(controller.status_payload())
@@ -162,15 +125,22 @@ def build_app(controller, selfcfg=None) -> web.Application:
     async def config_index(_request):
         return web.Response(text=CONFIG_PAGE, content_type="text/html")
 
-    async def _proposed(request):
+    async def _proposed(request, stored=None):
+        """(body, options, model). UX-13's settings view posts its page
+        `model`, which app/uimodel.py turns into the options blob here, so the
+        validator and the Supervisor only ever see a real blob. The classic
+        page posts `options`. Raises DeriveError for a model no blob can say."""
         try:
             body = await request.json()
         except ValueError:
             raise web.HTTPBadRequest(text="expected JSON")
+        model = body.get("model")
+        if isinstance(model, dict):
+            return body, uipage.to_options(model, stored), model
         options = body.get("options")
         if not isinstance(options, dict):
             raise web.HTTPBadRequest(text="expected an options object")
-        return body, options
+        return body, options, None
 
     async def config_model(request):
         """Everything the page needs to draw itself, from ONE Supervisor call.
@@ -199,6 +169,13 @@ def build_app(controller, selfcfg=None) -> web.Application:
             "running": controller.o,
             "running_differs": changed_keys(controller.o, options),
             "lang": lang,
+            # UX-13 P1: the levies preset and its year, for the P2 Settings
+            # screens, which show the year beside the region choice.
+            "region": region_of(options),
+            # UX-13 P2: the Installer view draws from these two.
+            "layout": uipage.layout(info.get("schema") or [],
+                                    info.get("translations") or {}, lang),
+            "ui": options_to_ui(options),
         })
         return web.json_response(model)
 
@@ -215,14 +192,27 @@ def build_app(controller, selfcfg=None) -> web.Application:
         product this card is delivering; anything this layer did to them would
         be a second opinion about a rule it does not own.
         """
-        _body, options = await _proposed(request)
+        try:
+            _body, options, model = await _proposed(request)
+        except DeriveError as err:
+            return web.json_response({"problems": [], "by_key": {},
+                                      "unanchored": [], "notes": [],
+                                      "messages": [uipage.derive_message(err)]})
+        notes = []
         problems, unread = await selfconfig.problems_and_ranges(
-            options, controller.hass)
+            options, controller.hass, notes=notes)
         by_key, unanchored = problems_by_field(problems, _keys_of(options))
+        # UX-13: warnings and info beside the refusals. Never block a save.
+        # The entity checks use the picker's cached list and never wait on HA.
+        notes += config_notes(options, entities=entities.peek())
         payload = {"problems": problems, "by_key": by_key,
-                   "unanchored": unanchored}
+                   "unanchored": unanchored,
+                   "notes": [n._asdict() for n in notes]}
         if unread:
             payload["device_note"] = DEVICE_NOTE % ", ".join(sorted(set(unread)))
+        if model is not None:
+            payload["messages"] = uipage.anchors(problems, notes, model,
+                                                 _keys_of(options))
         return web.json_response(payload)
 
     def _keys_of(options):
@@ -235,7 +225,27 @@ def build_app(controller, selfcfg=None) -> web.Application:
 
     async def config_save(request):
         """Validate, compare-and-swap, write. Or refuse and write NOTHING."""
-        body, options = await _proposed(request)
+        # The page model carries no stored values of the keys it shows, so the
+        # blob is settled against what is stored: an unchanged value is written
+        # exactly as stored (uipage.to_options).
+        try:
+            posted = await request.json()
+        except ValueError:
+            raise web.HTTPBadRequest(text="expected JSON")
+        stored_now = None
+        if isinstance(posted, dict) and isinstance(posted.get("model"), dict):
+            try:
+                stored_now = (await selfcfg.info()).get("options") or {}
+            except selfconfig.SupervisorUnavailable as err:
+                _LOG.error("saving options failed: %s", err)
+                return web.json_response({"error": str(err)}, status=502)
+        try:
+            body, options, model = await _proposed(request, stored_now)
+        except DeriveError as err:
+            return web.json_response(
+                {"kind": "invalid", "problems": [], "by_key": {},
+                 "unanchored": [], "messages": [uipage.derive_message(err)]},
+                status=422)
         expect = str(body.get("fingerprint") or "")
         try:
             result = await selfconfig.save(selfcfg, options, expect,
@@ -245,6 +255,9 @@ def build_app(controller, selfcfg=None) -> web.Application:
                 stored = refused.stored or {}
                 return web.json_response(
                     {"kind": "stale", "changed": refused.changed,
+                     "changed_fields": (uipage.fields_of(refused.changed,
+                                                         model)
+                                        if model is not None else []),
                      "stored": stored,
                      # The page needs the CURRENT token to be able to save
                      # again after the operator has read the difference. That
@@ -254,9 +267,12 @@ def build_app(controller, selfcfg=None) -> web.Application:
                     status=409)
             by_key, unanchored = problems_by_field(refused.problems,
                                                    _keys_of(options))
-            return web.json_response(
-                {"kind": "invalid", "problems": refused.problems,
-                 "by_key": by_key, "unanchored": unanchored}, status=422)
+            payload = {"kind": "invalid", "problems": refused.problems,
+                       "by_key": by_key, "unanchored": unanchored}
+            if model is not None:
+                payload["messages"] = uipage.anchors(refused.problems, [],
+                                                     model, _keys_of(options))
+            return web.json_response(payload, status=422)
         except selfconfig.SupervisorUnavailable as err:
             _LOG.error("saving options failed: %s", err)
             return web.json_response({"error": str(err)}, status=502)
@@ -290,6 +306,12 @@ def build_app(controller, selfcfg=None) -> web.Application:
                              hint=messages.hint("restart_requested"))
         return web.json_response({"ok": True})
 
+    async def ha_entities(request):
+        """UX-13: Home Assistant's entities for the picker. A read only, and
+        never an error: when Home Assistant is down the list says so."""
+        kind = str(request.query.get("kind", "") or "")[:16]
+        return web.json_response(await entities.payload(kind))
+
     app = web.Application()
     app.add_routes([
         web.get("/", index),
@@ -300,12 +322,21 @@ def build_app(controller, selfcfg=None) -> web.Application:
         web.post("/config/validate", config_validate),
         web.post("/config/save", config_save),
         web.post("/config/restart", config_restart),
+        web.get("/ha/entities", ha_entities),
     ])
     return app
 
 
+def access_log():
+    """UX-10: the page polls /status every few seconds, and aiohttp logs each
+    request at INFO. That access log is kept for a DEBUG log level only."""
+    return (logging.getLogger("aiohttp.access")
+            if _LOG.isEnabledFor(logging.DEBUG) else None)
+
+
 async def start(controller, port: int = 8099, selfcfg=None):
-    runner = web.AppRunner(build_app(controller, selfcfg))
+    runner = web.AppRunner(build_app(controller, selfcfg),
+                           access_log=access_log())
     await runner.setup()
     site = web.TCPSite(runner, "0.0.0.0", port)
     await site.start()

goodwe_controller/scenarios/ux13/test23/options.arb.json

@@ -0,0 +1,73 @@
+{
+ "arbitrage_enabled": true,
+ "arbitrage_soc_ceiling": 95,
+ "arbitrage_soc_floor": 20,
+ "auto_start": false,
+ "batt_entity": "sensor.test23_battery_power",
+ "batt_invert": false,
+ "bms_soc_floor": 10,
+ "circulation_hold_s": 75,
+ "circulation_w": 700,
+ "cycle_cost_threshold_eur": 0.1,
+ "cycle_floor_s": 15,
+ "deadband_w": 15,
+ "delivery_hold_s": 185,
+ "estop_fitted": false,
+ "export_price_eur_kwh": 0.04,
+ "gain": 0.6,
+ "heartbeat_s": 10,
+ "integrator_max_w": 0,
+ "inverters": [],
+ "log_level": "info",
+ "maintenance_charge_w": 2000,
+ "maintenance_discharge_w": 2000,
+ "maintenance_enabled": false,
+ "maintenance_hold_min": 120,
+ "maintenance_interval_days": 28,
+ "maintenance_soc_floor": 11,
+ "maintenance_soc_target": 99,
+ "maintenance_start_hour": 10,
+ "max_w": 2000,
+ "meter_entity": "sensor.p1_meter_active_power",
+ "meter_freeze_s": 300,
+ "meter_invert": false,
+ "meter_max_age_s": 30,
+ "meter_mqtt_topic": "",
+ "meter_phases": 1,
+ "meter_poll_s": 5,
+ "meter_source": "ha_signed",
+ "p1_export_entity": "",
+ "p1_host": "",
+ "p1_import_entity": "",
+ "p1_net_entity": "sensor.test23_p1_meter_active_power",
+ "p1_phase_export_entities": [],
+ "p1_phase_import_entities": [],
+ "p1_phase_net_entities": [],
+ "peak_cap_w": 3500,
+ "peak_forecast_entity": "",
+ "peak_soc_floor": 20,
+ "price_avg_entity": "",
+ "price_csv_path": "/share/goodwe_prices.csv",
+ "price_feed_url": "https://api.energy-charts.info/price?bzn=BE",
+ "price_horizon_h": 48,
+ "price_markup_eur_kwh": 0.03,
+ "price_now_entity": "",
+ "price_provider": "generic_dayahead",
+ "price_taxes_eur_kwh": 0.06,
+ "price_timeout_s": 10,
+ "saturation_cycles": 3,
+ "saturation_w": 500,
+ "setpoint_entity": "number.test23_setpoint_w",
+ "sign_disagree_s": 180,
+ "sign_disagree_w": 300,
+ "site_sign_disagree_s": 325,
+ "site_sign_disagree_w": 300,
+ "slew_w": 0,
+ "soc_entity": "sensor.test23_soc",
+ "stale_input_s": 15,
+ "static_profile": "",
+ "step_w": 10,
+ "target_grid_w": -10,
+ "unit_sign_disagree_s": 85,
+ "unit_sign_disagree_w": 250
+}

goodwe_controller/scenarios/ux13/test23/options.baseline.json

@@ -0,0 +1,73 @@
+{
+ "arbitrage_enabled": false,
+ "arbitrage_soc_ceiling": 95,
+ "arbitrage_soc_floor": 20,
+ "auto_start": false,
+ "batt_entity": "",
+ "batt_invert": false,
+ "bms_soc_floor": 10,
+ "circulation_hold_s": 75,
+ "circulation_w": 700,
+ "cycle_cost_threshold_eur": 0.1,
+ "cycle_floor_s": 15,
+ "deadband_w": 15,
+ "delivery_hold_s": 185,
+ "estop_fitted": false,
+ "export_price_eur_kwh": 0.04,
+ "gain": 0.6,
+ "heartbeat_s": 10,
+ "integrator_max_w": 0,
+ "inverters": [],
+ "log_level": "info",
+ "maintenance_charge_w": 2000,
+ "maintenance_discharge_w": 2000,
+ "maintenance_enabled": false,
+ "maintenance_hold_min": 120,
+ "maintenance_interval_days": 28,
+ "maintenance_soc_floor": 11,
+ "maintenance_soc_target": 99,
+ "maintenance_start_hour": 10,
+ "max_w": 2000,
+ "meter_entity": "sensor.p1_meter_active_power",
+ "meter_freeze_s": 300,
+ "meter_invert": false,
+ "meter_max_age_s": 30,
+ "meter_mqtt_topic": "",
+ "meter_phases": 1,
+ "meter_poll_s": 5,
+ "meter_source": "off",
+ "p1_export_entity": "",
+ "p1_host": "",
+ "p1_import_entity": "",
+ "p1_net_entity": "",
+ "p1_phase_export_entities": [],
+ "p1_phase_import_entities": [],
+ "p1_phase_net_entities": [],
+ "peak_cap_w": 3500,
+ "peak_forecast_entity": "",
+ "peak_soc_floor": 20,
+ "price_avg_entity": "",
+ "price_csv_path": "/share/goodwe_prices.csv",
+ "price_feed_url": "",
+ "price_horizon_h": 48,
+ "price_markup_eur_kwh": 0.03,
+ "price_now_entity": "",
+ "price_provider": "off",
+ "price_taxes_eur_kwh": 0.06,
+ "price_timeout_s": 10,
+ "saturation_cycles": 3,
+ "saturation_w": 500,
+ "setpoint_entity": "",
+ "sign_disagree_s": 180,
+ "sign_disagree_w": 300,
+ "site_sign_disagree_s": 325,
+ "site_sign_disagree_w": 300,
+ "slew_w": 0,
+ "soc_entity": "",
+ "stale_input_s": 15,
+ "static_profile": "",
+ "step_w": 10,
+ "target_grid_w": -10,
+ "unit_sign_disagree_s": 85,
+ "unit_sign_disagree_w": 250
+}

goodwe_controller/scenarios/ux13/test23/options.doc1-roster.json

@@ -0,0 +1,98 @@
+{
+ "arbitrage_enabled": false,
+ "arbitrage_soc_ceiling": 95,
+ "arbitrage_soc_floor": 20,
+ "auto_start": false,
+ "batt_entity": "sensor.test23_battery_power",
+ "batt_invert": false,
+ "bms_soc_floor": 10,
+ "circulation_hold_s": 75,
+ "circulation_w": 700,
+ "cycle_cost_threshold_eur": 0.1,
+ "cycle_floor_s": 15,
+ "deadband_w": 15,
+ "delivery_hold_s": 185,
+ "estop_fitted": false,
+ "export_price_eur_kwh": 0.04,
+ "gain": 0.6,
+ "heartbeat_s": 10,
+ "integrator_max_w": 0,
+ "inverters": [
+  {
+   "batt_entity": "sensor.goodwe_a_battery_power",
+   "bms_soc_floor": 10,
+   "capacity_kwh": 15.36,
+   "max_w": 5000,
+   "name": "inverter-a",
+   "setpoint_entity": "number.goodwe_a_setpoint_w",
+   "soc_entity": "sensor.goodwe_a_soc"
+  },
+  {
+   "batt_entity": "sensor.goodwe_b_battery_power",
+   "bms_soc_floor": 10,
+   "capacity_kwh": 20.48,
+   "max_w": 4600,
+   "name": "inverter-b",
+   "setpoint_entity": "number.goodwe_b_setpoint_w",
+   "soc_entity": "sensor.goodwe_b_soc"
+  }
+ ],
+ "log_level": "info",
+ "maintenance_charge_w": 2000,
+ "maintenance_discharge_w": 2000,
+ "maintenance_enabled": false,
+ "maintenance_hold_min": 120,
+ "maintenance_interval_days": 28,
+ "maintenance_soc_floor": 11,
+ "maintenance_soc_target": 99,
+ "maintenance_start_hour": 10,
+ "max_w": 2000,
+ "meter_entity": "sensor.p1_meter_active_power",
+ "meter_freeze_s": 300,
+ "meter_invert": false,
+ "meter_max_age_s": 30,
+ "meter_mqtt_topic": "",
+ "meter_phases": 1,
+ "meter_poll_s": 5,
+ "meter_source": "ha_signed",
+ "p1_export_entity": "",
+ "p1_host": "",
+ "p1_import_entity": "",
+ "p1_net_entity": "sensor.test23_p1_meter_active_power",
+ "p1_phase_export_entities": [],
+ "p1_phase_import_entities": [],
+ "p1_phase_net_entities": [],
+ "peak_cap_w": 3500,
+ "peak_forecast_entity": "",
+ "peak_soc_floor": 20,
+ "price_avg_entity": "",
+ "price_csv_path": "/share/goodwe_prices.csv",
+ "price_export_formula": "",
+ "price_feed_url": "https://api.energy-charts.info/price?bzn=BE",
+ "price_formula": "",
+ "price_horizon_h": 48,
+ "price_markup_eur_kwh": 0.03,
+ "price_now_entity": "",
+ "price_provider": "generic_dayahead",
+ "price_taxes_eur_kwh": 0.06,
+ "price_taxes_profile": "",
+ "price_timeout_s": 10,
+ "pv_entities": [],
+ "pv_entity": "",
+ "saturation_cycles": 3,
+ "saturation_w": 500,
+ "setpoint_entity": "",
+ "shadow_mode": "auto",
+ "sign_disagree_s": 180,
+ "sign_disagree_w": 300,
+ "site_sign_disagree_s": 325,
+ "site_sign_disagree_w": 300,
+ "slew_w": 0,
+ "soc_entity": "sensor.test23_soc",
+ "stale_input_s": 15,
+ "static_profile": "",
+ "step_w": 10,
+ "target_grid_w": -10,
+ "unit_sign_disagree_s": 85,
+ "unit_sign_disagree_w": 250
+}

goodwe_controller/scenarios/ux13/test23/options.json

@@ -0,0 +1,73 @@
+{
+ "arbitrage_enabled": false,
+ "arbitrage_soc_ceiling": 95,
+ "arbitrage_soc_floor": 20,
+ "auto_start": false,
+ "batt_entity": "sensor.test23_battery_power",
+ "batt_invert": false,
+ "bms_soc_floor": 10,
+ "circulation_hold_s": 75,
+ "circulation_w": 700,
+ "cycle_cost_threshold_eur": 0.1,
+ "cycle_floor_s": 15,
+ "deadband_w": 15,
+ "delivery_hold_s": 185,
+ "estop_fitted": false,
+ "export_price_eur_kwh": 0.04,
+ "gain": 0.6,
+ "heartbeat_s": 10,
+ "integrator_max_w": 0,
+ "inverters": [],
+ "log_level": "info",
+ "maintenance_charge_w": 2000,
+ "maintenance_discharge_w": 2000,
+ "maintenance_enabled": false,
+ "maintenance_hold_min": 120,
+ "maintenance_interval_days": 28,
+ "maintenance_soc_floor": 11,
+ "maintenance_soc_target": 99,
+ "maintenance_start_hour": 10,
+ "max_w": 2000,
+ "meter_entity": "sensor.p1_meter_active_power",
+ "meter_freeze_s": 300,
+ "meter_invert": false,
+ "meter_max_age_s": 30,
+ "meter_mqtt_topic": "",
+ "meter_phases": 1,
+ "meter_poll_s": 5,
+ "meter_source": "ha_signed",
+ "p1_export_entity": "",
+ "p1_host": "",
+ "p1_import_entity": "",
+ "p1_net_entity": "sensor.test23_p1_meter_active_power",
+ "p1_phase_export_entities": [],
+ "p1_phase_import_entities": [],
+ "p1_phase_net_entities": [],
+ "peak_cap_w": 3500,
+ "peak_forecast_entity": "",
+ "peak_soc_floor": 20,
+ "price_avg_entity": "",
+ "price_csv_path": "/share/goodwe_prices.csv",
+ "price_feed_url": "https://api.energy-charts.info/price?bzn=BE",
+ "price_horizon_h": 48,
+ "price_markup_eur_kwh": 0.03,
+ "price_now_entity": "",
+ "price_provider": "generic_dayahead",
+ "price_taxes_eur_kwh": 0.06,
+ "price_timeout_s": 10,
+ "saturation_cycles": 3,
+ "saturation_w": 500,
+ "setpoint_entity": "number.test23_setpoint_w",
+ "sign_disagree_s": 180,
+ "sign_disagree_w": 300,
+ "site_sign_disagree_s": 325,
+ "site_sign_disagree_w": 300,
+ "slew_w": 0,
+ "soc_entity": "sensor.test23_soc",
+ "stale_input_s": 15,
+ "static_profile": "",
+ "step_w": 10,
+ "target_grid_w": -10,
+ "unit_sign_disagree_s": 85,
+ "unit_sign_disagree_w": 250
+}

goodwe_controller/scenarios/ux13/test23/options.s3.json

@@ -0,0 +1,73 @@
+{
+ "arbitrage_enabled": true,
+ "arbitrage_soc_ceiling": 95,
+ "arbitrage_soc_floor": 20,
+ "auto_start": true,
+ "batt_entity": "sensor.test23_battery_power",
+ "batt_invert": false,
+ "bms_soc_floor": 10,
+ "circulation_hold_s": 75,
+ "circulation_w": 700,
+ "cycle_cost_threshold_eur": 0.1,
+ "cycle_floor_s": 15,
+ "deadband_w": 15,
+ "delivery_hold_s": 185,
+ "estop_fitted": false,
+ "export_price_eur_kwh": 0.04,
+ "gain": 0.6,
+ "heartbeat_s": 10,
+ "integrator_max_w": 0,
+ "inverters": [],
+ "log_level": "info",
+ "maintenance_charge_w": 2000,
+ "maintenance_discharge_w": 2000,
+ "maintenance_enabled": false,
+ "maintenance_hold_min": 120,
+ "maintenance_interval_days": 28,
+ "maintenance_soc_floor": 11,
+ "maintenance_soc_target": 99,
+ "maintenance_start_hour": 10,
+ "max_w": 2000,
+ "meter_entity": "sensor.p1_meter_active_power",
+ "meter_freeze_s": 300,
+ "meter_invert": false,
+ "meter_max_age_s": 30,
+ "meter_mqtt_topic": "",
+ "meter_phases": 1,
+ "meter_poll_s": 5,
+ "meter_source": "ha_signed",
+ "p1_export_entity": "",
+ "p1_host": "",
+ "p1_import_entity": "",
+ "p1_net_entity": "sensor.test23_p1_meter_active_power",
+ "p1_phase_export_entities": [],
+ "p1_phase_import_entities": [],
+ "p1_phase_net_entities": [],
+ "peak_cap_w": 15000,
+ "peak_forecast_entity": "",
+ "peak_soc_floor": 20,
+ "price_avg_entity": "",
+ "price_csv_path": "/share/goodwe_prices.csv",
+ "price_feed_url": "",
+ "price_horizon_h": 48,
+ "price_markup_eur_kwh": 0.03,
+ "price_now_entity": "",
+ "price_provider": "manual_csv",
+ "price_taxes_eur_kwh": 0.06,
+ "price_timeout_s": 10,
+ "saturation_cycles": 3,
+ "saturation_w": 500,
+ "setpoint_entity": "number.test23_setpoint_w",
+ "sign_disagree_s": 180,
+ "sign_disagree_w": 300,
+ "site_sign_disagree_s": 325,
+ "site_sign_disagree_w": 300,
+ "slew_w": 0,
+ "soc_entity": "sensor.test23_soc",
+ "stale_input_s": 15,
+ "static_profile": "",
+ "step_w": 10,
+ "target_grid_w": -10,
+ "unit_sign_disagree_s": 85,
+ "unit_sign_disagree_w": 250
+}

goodwe_controller/test_arbiter.py

@@ -149,7 +149,7 @@ check("...and `source` is still the first positional argument, which is what "
       Claim.limit("device", P_SAFETY, -1, 1).source == "device")
 
 print()
-print("ARB-03 2. the split: eleven sources, each classified where it is BUILT")
+print("ARB-03 2. the split: twelve sources, each classified where it is BUILT")
 # The classification is graded against what each claim is ABOUT, restated here
 # so that the table in arbiter.py and the expectation in a test are not the same
 # sentence read twice. test_peakguard.py part 10f pins this set against main.py's
@@ -189,16 +189,20 @@ UNIT_SOURCES = {
                   "is added, `peak_soc_floor` is not consulted, the SITE target "
                   "is untouched, and main.py does not file it at all at a "
                   "roster of one",
+    # SAFETY-73.
+    "refused":    "THIS battery's own reading gave nothing against THIS unit's "
+                  "own standing command, so that direction is closed on THIS "
+                  "unit and its share goes to the others. Filed at N>1 only",
 }
 for _src, _why in sorted(SITE_SOURCES.items()):
     print(f"    site  {_src:<11} {_why}")
 for _src, _why in sorted(UNIT_SOURCES.items()):
     print(f"    unit  {_src:<11} {_why}")
-check("all ELEVEN claim sources are classified, and only those eleven",
+check("all TWELVE claim sources are classified, and only those twelve",
       set(CLAIM_SCOPE) == set(SITE_SOURCES) | set(UNIT_SOURCES))
 check("the six that are about the GRID CONNECTION are site claims",
       {s for s, v in CLAIM_SCOPE.items() if v == SCOPE_SITE} == set(SITE_SOURCES))
-check("the five that are about a PACK, a DEVICE or one write are per-inverter",
+check("the six that are about a PACK, a DEVICE or one write are per-inverter",
       {s for s, v in CLAIM_SCOPE.items() if v == SCOPE_UNIT} == set(UNIT_SOURCES))
 check("a source nobody classified cannot be routed at all - actuator_for() "
       "raises rather than defaulting to the site, because defaulting to the "
@@ -216,7 +220,7 @@ check("with one inverter every source routes to the site, per-inverter ones "
       all(actuator_for(s, "inverter-a", ONE) == ACTUATOR_SITE for s in CLAIM_SCOPE))
 check("...and with none configured at all, likewise",
       all(actuator_for(s, "inverter-a", ()) == ACTUATOR_SITE for s in CLAIM_SCOPE))
-check("with TWO the identity breaks and the split becomes real: the five "
+check("with TWO the identity breaks and the split becomes real: the six "
       "per-inverter sources route to the unit this controller drives, the six "
       "site sources stay on the grid connection",
       {s: actuator_for(s, "inverter-a", TWO) for s in CLAIM_SCOPE}

goodwe_controller/test_clamp.py

@@ -497,8 +497,13 @@ check(f"AC 1: NOT ONE of the {len(emitted)} values that reached the device "
 # largest emitted value is what it is and not 5000 W. The clamp is what makes it
 # bounded; the freeze is what makes it small. A check that read
 # `max(emitted) == max_w` would have been asserting the freeze, not the clamp.
+# SAFETY-52 re-baseline: an inverter reporting 0 W for SETTLE_CYCLES is a
+# battery that refuses, so the command then drops to 0 W. The freeze still
+# engaged first, and the event log says so.
 check(f"...and the saturation freeze is what pins it at {max(emitted):,.0f} W "
-      f"rather than the rail", ctl_r.sat_count >= ctl_r.tuning.saturation_cycles)
+      f"rather than the rail",
+      any("saturation freeze" in e for e in ctl_r.events)
+      and max(emitted) < LIVE_MAX_W)
 
 notes_r = clamp_notes(hass_r)
 print(f"    the loop clamped on {ctl_r.clamp_wd.engagements} of {60} cycles, "
@@ -521,7 +526,8 @@ check(f"the action log records every engagement, coalesced into one row per "
       f"episode ({len(rows_r)} row(s), {ctl_r.clamp_wd.engagements} "
       f"engagement(s))",
       len(rows_r) == ctl_r.clamp_wd.episodes
-      and f"{ctl_r.clamp_wd.engagements} engagement(s)" in rows_r[0])
+      and messages.count(ctl_r.clamp_wd.engagements, "engagement")
+      in rows_r[0])
 
 # ⚠️ REGRESSION, AND IT WAS A REAL BUG BEFORE IT WAS A CHECK. `log_event()` keeps
 # 40 rows. A row per engagement flushes that ring inside 40 cycles of a winding
@@ -538,7 +544,8 @@ check(f"a long winding episode does NOT flood the 40-row event log "
       f"({len(rows_l)} rows for {ctl_l.clamp_wd.engagements} engagements)",
       ctl_l.clamp_wd.engagements > 40 and len(rows_l) <= ctl_l.clamp_wd.episodes)
 check("...and the count in the row is the counter's, so nothing is lost",
-      f"{ctl_l.clamp_wd.engagements} engagement(s)" in nth(rows_l, -1))
+      messages.count(ctl_l.clamp_wd.engagements, "engagement")
+      in nth(rows_l, -1))
 # The RED row exists only while engaged, and the episode above is short, so it
 # is captured mid-run rather than asserted after the hysteresis has cleared it.
 check("the status page flags it WHILE it is engaged - amber, since it is the "
@@ -578,8 +585,12 @@ check("UX-07 item 1: during a bound episode an earlier over-rating count is "
 
 # ⚠️ NOT A TRIP. 11.2's action is "clamp and alarm"; the loop keeps running and
 # keeps writing the clamped value. If a later cut changes that it must come here.
-check(f"it is NOT a trip - the command stands at {ctl_r.target:+.0f} W, not 0 W",
-      ctl_r.target != 0.0 and ctl_r.target == hass_r.writes[-1])
+# SAFETY-52: the loop itself now asks 0 W of an inverter that gives nothing,
+# with its own reason. That is the loop's decision, not a stop.
+check(f"it is NOT a trip - the command stands at {ctl_r.target:+.0f} W because "
+      f"the loop says '{ctl_r.loop_reason}', not because of a stop",
+      ctl_r.loop_reason == "battery refuses"
+      and ctl_r.target == hass_r.writes[-1])
 check("...and the controller still reports itself running, not failsafe",
       ctl_r.auto and not ctl_r.sign_wd.tripped)
 
@@ -1037,7 +1048,8 @@ check("...and the operator is told WHICH bound bit, so a device-rating clamp "
       and messages.LIMIT_WORDS["device"] in notes_w[0]["message"]
       and messages.LIMIT_WORDS["max_w"] not in notes_w[0]["message"])
 check("...and the action log carries the row, written by write_setpoint()",
-      any(REASON_CODE in e and "device bound" in e for e in ctl_w.events))
+      any(REASON_CODE in e and messages.LIMIT_WORDS["device"] in e
+          for e in ctl_w.events))
 
 # The same stimulus, the same clamp, the two calls swapped. This is the ticket
 # in one pair of runs.
@@ -1125,8 +1137,8 @@ check("⚠️ THE ORDERED PAIR IN THE §15 ACTION-LOG ROW (main.py:1366). The "
       "the loop asked for +2000 W and the guard clamped it UP to +9999 W - "
       "past the 2000 W rating printed four words later - which is the alarm "
       "reading backwards on the one line an operator is woken by",
-      any(f"the computed setpoint {_asked_x:+.0f} W was clamped to "
-          f"{_sent_x:+.0f} W" in e for e in _rows_x))
+      any(f"asked {_asked_x:+.0f} W and sent {_sent_x:+.0f} W" in e
+          for e in _rows_x))
 # UX-08: the notification is a SECOND surface off the same numbers, in its own
 # words (messages.output_clamp): asked first, sent second.
 def _asked_then_sent(msg, asked, sent):
@@ -1142,8 +1154,8 @@ check("⚠️ ...AND IN THE ClampWatchdog NOTIFICATION, which is a SECOND surfac
       bool(notes_x) and _asked_then_sent(notes_x[0]["message"], _asked_x, _sent_x))
 check("...and the TRANSPOSED sentence appears on NEITHER surface, so the two "
       "checks above discriminate rather than decorate",
-      not any(f"the computed setpoint {_sent_x:+.0f} W was clamped to "
-              f"{_asked_x:+.0f} W" in e for e in _rows_x)
+      not any(f"asked {_sent_x:+.0f} W and sent {_asked_x:+.0f} W" in e
+              for e in _rows_x)
       and not _asked_then_sent(nth(notes_x, 0)["message"], _sent_x, _asked_x)
       and present(nth(notes_x, 0)))
 # The DEVICE bound, off part 6c's controller: same sentence, other stage. The
@@ -1154,8 +1166,8 @@ check("...and the same ordered pair holds on the DEVICE-bound row, where the "
       "loop asked for +3000 W and the device took +2500 W. PRECONDITION: those "
       "two also render differently",
       f"{_asked_w:+.0f}" != f"{_sent_w:+.0f}"
-      and any(f"the computed setpoint {_asked_w:+.0f} W was clamped to "
-              f"{_sent_w:+.0f} W" in e for e in ctl_w.events)
+      and any(f"asked {_asked_w:+.0f} W and sent {_sent_w:+.0f} W" in e
+              for e in ctl_w.events)
       and _asked_then_sent(nth(notes_w, 0)["message"], _asked_w, _sent_w))
 
 
@@ -2028,16 +2040,17 @@ check("PRECONDITION: the integrator bound engaged, and on a tick where the "
       "carried integrator AND the emitted command both differ from the bound",
       any(d.i_w != _f(d, 'i_bound_w') and d.target_w != _f(d, 'i_bound_w')
           for d, t, r in wind))
-check("defect 1: the integrator bound is NOT reported as a BUG SIGNAL",
-      wind and all("BUG SIGNAL" not in r for d, t, r in wind))
-check("defect 1: ...it names the anti-windup bound, from the same tick",
-      wind and all(f"its {_f(d, 'i_bound_w'):+.0f} W anti-windup bound" in r
+check("defect 1: the integrator bound is NOT reported as an over-rating",
+      wind and all(" rating" not in r and "fault" not in r
+                   for d, t, r in wind))
+check("defect 1: ...it names the integrator's bound, from the same tick",
+      wind and all(f"reached its {_f(d, 'i_bound_w'):+.0f} W limit" in r
                    for d, t, r in wind))
 check("defect 2: the integrator accumulator is not printed as a request",
       wind and all(f"{d.i_w:+.0f} W" not in r and "asked for" not in r
                    for d, t, r in wind))
 check("the command quoted is that tick's Decision, not a later read",
-      wind and all(f"command this cycle was {d.target_w:+.0f} W" in r
+      wind and all(f"command now {d.target_w:+.0f} W" in r
                    for d, t, r in wind))
 check("at the bound nothing is described as 'above' or 'over' the rating",
       wind and all(" above " not in r and " over " not in r
@@ -2049,9 +2062,12 @@ check("it still NOTIFIES (not suppressed), under a title that claims no bug",
 check("...under its OWN notification_id, so it cannot replace a BUG SIGNAL "
       "notice still on screen",
       notes_i and all(n["notification_id"] == BOUND_ID for n in notes_i))
+# UX-11: the WARNING quotes the code. The reason is on the DEBUG line beside
+# it (test_messages.py part 6).
 check("...logged as a WARNING, not an ERROR",
-      any(x.levelno == logging.WARNING and "anti-windup" in x.getMessage()
-          for x in log_i)
+      any(x.levelno == logging.WARNING
+          and x.getMessage().startswith("The battery gives less than asked: "
+                                        "OUTPUT_CLAMP.") for x in log_i)
       and not any(x.levelno >= logging.ERROR and "OUTPUT_CLAMP" in x.getMessage()
                   for x in log_i))
 check("...and the status row is amber, not red",
@@ -2070,17 +2086,18 @@ for d, t, r in over[:2]:
 check("PRECONDITION: the output clamp engaged on a tick where the slew limit "
       "rewrote the command AND the integrator differs from the request",
       any(t != _f(d, 'clamped_w') and d.i_w != _f(d, 'requested_w') for d, t, r in over))
-check("the over-rating KEEPS the BUG SIGNAL",
-      over and all("BUG SIGNAL" in r for d, t, r in over))
+check("the over-rating says it was cut to the rating",
+      over and all(" W rating, command now " in r for d, t, r in over))
 check("defect 2: it quotes the requested COMMAND of that tick, not i_w",
       over and all(f"computed {_f(d, 'requested_w'):+.0f} W" in r for d, t, r in over))
-check("defect 3: 'clamped to' is the clamp's own result, not self.target",
-      over and all(f"clamped to {_f(d, 'clamped_w'):+.0f} W" in r for d, t, r in over))
+check("defect 3: 'cut to' is the clamp's own result, not self.target",
+      over and all(f"cut to the {_f(d, 'clamped_w'):+.0f} W rating" in r
+                   for d, t, r in over))
 check("...and its ERROR says it is a software fault and that control keeps "
       "running (UX-08 2d moved the 14 768 W rationale to a DEBUG line beside "
       "it, which is still in main.py)",
       any(x.levelno == logging.ERROR and "software fault" in x.getMessage()
-          and "Control is still running" in x.getMessage() for x in log_o)
+          and "control runs on" in x.getMessage() for x in log_o)
       and "reached 14 768 W on this project" in
       open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "app",
                         "main.py"), encoding="utf-8").read())

goodwe_controller/test_delivery.py

@@ -33,7 +33,7 @@ from datetime import datetime, timedelta, timezone
 
 from named_absence import given, present
 
-from app import messages
+from app import control, messages
 from app.control import Tuning
 from app.delivery import (
     DELIVERY_OPTION_DEFAULTS, DELIVERY_SHARE_FRACTION, REASON_CODE,
@@ -593,6 +593,15 @@ check("...and the SHARES now differ, which is OPT-09 and not a weakening of the
       "grades the ALARM, and neither can do the other's half",
       _pw != _pf
       and _sf[-1]["shares"][1] == 0.0 and _sw[-1]["shares"][1] == 2000.0)
+# SAFETY-73. A unit that gives < 100 W while asked > 200 W is refused after
+# SETTLE_CYCLES cycles that also span REFUSED_SPAN_S (22 s). This fixture's 14
+# cycles are 0.2 s apart, so the wedged B meets the count and not the span, and
+# SAFETY-42's report stands alone here. test_refusal_units.py grades the
+# refusal. On a site the 185 s hold puts the refusal first.
+check("SAFETY-73: the wedged arm's B is not refused in this fixture: 12 cycles "
+      "of evidence in under 3 s are not the 22 s a refusal needs",
+      _cw.inverters[1].refused == 0
+      and _cw.inverters[1].ref_count >= control.SETTLE_CYCLES)
 check("...and the state of charge is still what tells them apart",
       [r["soc"] for r in _sw] != [r["soc"] for r in _sf])
 print(f"       both arms, last cycle: grid {_sw[-1]['grid']:.0f} W, shares "
@@ -1147,8 +1156,10 @@ async def _one():
             "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
             "meter_source": "off", "max_w": 2000, "gain": 0.6,
             # ⚠️ THE SAME 1 s AS THE TWO-INVERTER FIXTURE, AND THAT IS WHAT
-            # MAKES THIS SECTION NON-VACUOUS. The run below is 2 s of wall clock
-            # against a 1 s window, so a hold is not what stops this firing -
+            # MAKES THIS SECTION NON-VACUOUS. The run below is 1.1 s of wall
+            # clock against a 1 s window (SAFETY-52 shortened it from 2 s, and
+            # "the window was never even opened" below is what still makes it
+            # non-vacuous), so a hold is not what stops this firing -
             # the reduction is. With a shipped-length hold "nothing was
             # reported" would be true of a fixture that simply ran out of time.
             "bms_soc_floor": _FLOOR_PCT, "delivery_hold_s": 1,
@@ -1158,7 +1169,10 @@ async def _one():
     c.inverters[0].dev_min, c.inverters[0].dev_max = -2000.0, 2000.0
     c.auto = True
     hass.ctrl = c
-    await _drive(c, n=20, dt=0.1)
+    # SAFETY-52: from SETTLE_CYCLES of delivering nothing the loop asks 0 W
+    # (the battery refuses), so the run stops just before that. 11 cycles is
+    # still 1.1 s against the 1 s hold.
+    await _drive(c, n=11, dt=0.1)
     return c, hass, store
 
 

goodwe_controller/test_freshness.py

@@ -1644,9 +1644,8 @@ check("...and a re-trip's reason names the TWO durations separately, each "
           [f.submit(A_FROZEN_W, 1300.0, float(t)) for t in range(80, 130)],
           f.stale and f.releases == 1
           and "unchanged for 92 s" in f.reason
-          and "the 35 s window this verdict rests on opened when the previous "
-              "one was withdrawn" in f.reason
-          and "graded 2 times" in f.reason)[-1])(
+          and "checked 2 times over a 35 s window since the last stop was "
+              "withdrawn" in f.reason)[-1])(
               Freshness(BOUNDS["batt"])))
 
 
@@ -1799,8 +1798,8 @@ check("...and the two runs were driven at 50 % and 11 % SoC and the sentence "
 # bytes, and "the register may be unable to comply / the source may have
 # stopped reporting reality" is a different and wrong claim.
 _S56_EXPLANATIONS = [
-    ("DEAD", "the register may have stopped reporting reality"),
-    ("REFUSED", "the source may be unable to comply with the command"),
+    ("DEAD", "reading may have stopped"),
+    ("REFUSED", "battery may be unable to follow the command"),
 ]
 # ⚠️ WHAT THE THREE SENTENCES USED TO ASSERT. Each is a claim about the
 # REGISTER or about the ENTITY, and 11a measured the register to be alive on
@@ -1814,6 +1813,11 @@ _S56_ACCUSATIONS = [
 ]
 _log56 = [r.getMessage() for r in _LOGREC[_S56_LOG0:]
           if "battery power reading stopped changing" in r.getMessage()]
+# UX-11: the ERROR line quotes the code, and the reason itself is on the DEBUG
+# line logged beside it.
+_dbg56 = [r.getMessage() for r in _LOGREC[_S56_LOG0:]
+          if r.levelno == logging.DEBUG
+          and r.getMessage().startswith("Evidence for ")] or [""]
 
 
 def _s56_row(c):
@@ -1856,7 +1860,7 @@ check("PRECONDITION: all four operator-facing surfaces were really produced by "
       "two are the same string, which is 11b again on the log surface",
       len(_log56) == 2 and _log56[0] == _log56[1]
       and all(len(s) > 30 for s in _S56_SURFACES.values())
-      and _r56_ref in _log56[-1])
+      and _log56[-1].endswith(": STALE_READING.") and _r56_ref in _dbg56[-1])
 _idx56 = [_r56_ref.find(t) for _w, t in _S56_EXPLANATIONS]
 check(f"11c. BOTH EXPLANATIONS ARE NAMED, AND IN THAT ORDER: "
       f"{_S56_EXPLANATIONS[0][1]!r} at {_idx56[0]} then "
@@ -1868,7 +1872,7 @@ check(f"11c. BOTH EXPLANATIONS ARE NAMED, AND IN THAT ORDER: "
 check("...and the sentence says in its own words that it CANNOT choose, rather "
       "than leaving two explanations side by side for a reader to rank - an "
       "operator who reads a list picks the first item",
-      "CANNOT TELL THEM APART" in _r56_ref)
+      "this check cannot tell which" in _r56_ref)
 # ⚠️ THE POSITIVE CONTROL FOR THE `not any(...)` BELOW, AND IT IS NOT OPTIONAL:
 # a quantifier over an empty list is True, and so is one over three literals
 # with a typo in each. These are the three sentences as 0.10.1 SHIPPED them,

goodwe_controller/test_haentities.py

@@ -0,0 +1,248 @@
+"""UX-13 P0: the entity list for the picker.  `python3 test_haentities.py`
+
+`GET ha/entities` reads Home Assistant's states through the add-on's own
+session (hass.states()) and must never fail the page: part 1 drives the real
+HomeAssistant client against a local server that answers 502, garbage, the
+wrong shape, nothing at all, or too slowly. Part 2 checks the 30 s cache and
+what is served while Home Assistant is down. Part 3 serves the real route.
+Mutating a module this file grades? Read MUTATION.md first (purge __pycache__).
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import time
+
+from aiohttp import ClientSession, web as aioweb
+
+from app import hass as H, haentities as E, web
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+STATES = [
+    {"entity_id": "sensor.grid", "state": "812",
+     "attributes": {"friendly_name": "Grid power", "unit_of_measurement": "W",
+                    "device_class": "power"}},
+    {"entity_id": "sensor.soc", "state": "54",
+     "attributes": {"friendly_name": "Battery level", "unit_of_measurement": "%",
+                    "device_class": "battery"}},
+    {"entity_id": "number.setpoint", "state": "0", "attributes": {}},
+    {"entity_id": "sensor.pv_kw", "state": "1.2",
+     "attributes": {"unit_of_measurement": "kW"}},
+    {"no_entity_id": True},
+]
+
+
+async def serve(handler):
+    app = aioweb.Application()
+    app.router.add_get("/api/states", handler)
+    runner = aioweb.AppRunner(app)
+    await runner.setup()
+    site = aioweb.TCPSite(runner, "127.0.0.1", 0)
+    await site.start()
+    return runner, site._server.sockets[0].getsockname()[1]
+
+
+async def read_with(handler, timeout_s=10):
+    runner, port = await serve(handler)
+    H.CORE_API, H.STATES_TIMEOUT_S = f"http://127.0.0.1:{port}/api", timeout_s
+    try:
+        async with ClientSession() as session:
+            t0 = time.monotonic()
+            got = await H.HomeAssistant(session, "token").states()
+            read_with.took = time.monotonic() - t0
+            return got
+    finally:
+        await runner.cleanup()
+
+
+async def ok(_r):
+    return aioweb.json_response(STATES)
+
+
+async def bad_gateway(_r):
+    return aioweb.Response(status=502)
+
+
+async def garbage(_r):
+    return aioweb.Response(text="<html>", content_type="application/json")
+
+
+async def not_a_list(_r):
+    return aioweb.json_response({"message": "hi"})
+
+
+async def slow(_r):
+    await asyncio.sleep(2)
+    return aioweb.json_response(STATES)
+
+
+async def closed_port():
+    H.CORE_API = "http://127.0.0.1:9/api"
+    async with ClientSession() as session:
+        return await H.HomeAssistant(session, "token").states()
+
+
+print("1. hass.states() answers None, never an exception")
+check("a normal answer is the state list", asyncio.run(read_with(ok)) == STATES)
+for name, handler in (("502 while HA restarts", bad_gateway),
+                      ("a body that is not JSON", garbage),
+                      ("JSON that is not a list", not_a_list)):
+    check(f"{name} -> None", asyncio.run(read_with(handler)) is None)
+class _Lines(logging.Handler):
+    def __init__(self):
+        super().__init__()
+        self.lines = []
+
+    def emit(self, record):
+        if record.levelno >= logging.WARNING:
+            self.lines.append(record.getMessage())
+
+
+_lines = _Lines()
+logging.getLogger().addHandler(_lines)
+check("an answer slower than the timeout -> None, at the timeout",
+      asyncio.run(read_with(slow, timeout_s=0.3)) is None
+      and read_with.took < 1.0)
+# UX-13 P1 test finding (c): a timeout's own text is empty, which left
+# "Reading the entity list failed: " with no reason.
+check("...and its WARNING line gives the reason, not an empty one "
+      f"({_lines.lines})", any(
+          x == "Reading the entity list failed: no answer within 0.3 seconds."
+          for x in _lines.lines)
+      and not any(x.rstrip().endswith("failed:") for x in _lines.lines))
+logging.getLogger().removeHandler(_lines)
+check("no server at all -> None", asyncio.run(closed_port()) is None)
+check("the timeout for the list is the same 10 s as every other read",
+      "STATES_TIMEOUT_S = 10 " in open(H.__file__, encoding="utf-8").read())
+
+
+class FakeHass:
+    def __init__(self):
+        self.answer, self.reads = STATES, 0
+
+    async def states(self):
+        self.reads += 1
+        await asyncio.sleep(0.01)
+        return self.answer
+
+
+class Clock:
+    def __init__(self):
+        self.t = 1000.0
+
+    def __call__(self):
+        return self.t
+
+
+print("\n2. the cache, and Home Assistant being down")
+_h, _c = FakeHass(), Clock()
+_cache = E.EntityCache(_h, clock=_c)
+
+
+async def burst():
+    return await asyncio.gather(*(_cache.payload("power") for _ in range(5)))
+
+
+_p = asyncio.run(burst())
+check("five pickers opening at once cost one read of Home Assistant",
+      _h.reads == 1 and all(x == _p[0] for x in _p))
+_ids = [r["entity_id"] for r in _p[0]["entities"]]
+check("power entities come first, then the rest, and a broken state is left "
+      f"out ({_ids})", _ids == ["sensor.grid", "sensor.pv_kw",
+                                "number.setpoint", "sensor.soc"]
+      and [r["match"] for r in _p[0]["entities"]] == [True, True, False, False])
+check("each row carries id, name, state, unit and device class",
+      _p[0]["entities"][0] == {"entity_id": "sensor.grid", "name": "Grid power",
+                               "state": "812", "unit": "W",
+                               "device_class": "power", "match": True})
+check("the kinds filter as the pickers need",
+      [r["entity_id"] for r in _p[0]["entities"]
+       if E.matches(r, "pct")] == ["sensor.soc"]
+      and [r["entity_id"] for r in _p[0]["entities"]
+           if E.matches(r, "number")] == ["number.setpoint"])
+_c.t += 10
+asyncio.run(_cache.payload())
+check("within 30 s the cached list is served", _h.reads == 1)
+check("peek() hands the validator the fresh list without a read",
+      set(_cache.peek()) == set(_ids) and _h.reads == 1)
+_h.answer = None
+_c.t += 30
+_down = asyncio.run(_cache.payload())
+check("Home Assistant down after a good read: the old list, marked old",
+      _h.reads == 2 and _down["available"] and _down["text"] == E.STALE_TEXT
+      and len(_down["entities"]) == 4 and _down["age_s"] >= 30)
+check("...and peek() then gives nothing, so no warning rests on an old list",
+      _cache.peek() is None)
+
+
+async def down_windows():
+    """One loop throughout: a contended asyncio.Lock binds to its loop."""
+    hass, clock = FakeHass(), Clock()
+    hass.answer = None
+    cache = E.EntityCache(hass, clock=clock)
+    counts = []
+    for step in (0, 1, 30):
+        clock.t += step
+        await asyncio.gather(*(cache.payload() for _ in range(5)))
+        counts.append(hass.reads)
+    return counts
+
+
+check("five polls while Home Assistant is down cost one read, the polls just "
+      "after wait for the next window, and that window tries once",
+      asyncio.run(down_windows()) == [1, 1, 2])
+_h2 = FakeHass()
+_h2.answer = None
+_empty = asyncio.run(E.EntityCache(_h2).payload("power"))
+check("Home Assistant down from the start: an empty list that says why",
+      _empty == {"available": False, "text": E.DOWN_TEXT, "entities": []})
+
+
+print("\n3. the route")
+
+
+class FakeController:
+    def __init__(self, hass):
+        self.hass, self.o = hass, {}
+
+
+async def route(hass, query=""):
+    app = web.build_app(FakeController(hass), selfcfg=object())
+    runner = aioweb.AppRunner(app)
+    await runner.setup()
+    site = aioweb.TCPSite(runner, "127.0.0.1", 0)
+    await site.start()
+    port = site._server.sockets[0].getsockname()[1]
+    try:
+        async with ClientSession() as s:
+            async with s.get(f"http://127.0.0.1:{port}/ha/entities{query}") as r:
+                return r.status, await r.json()
+    finally:
+        await runner.cleanup()
+
+
+_st, _body = asyncio.run(route(FakeHass(), "?kind=pct"))
+check("GET ha/entities?kind=pct answers 200 with the matching entity first",
+      _st == 200 and _body["entities"][0]["entity_id"] == "sensor.soc")
+_st, _body = asyncio.run(route(_h2))
+check("with Home Assistant down it still answers 200, with the reason",
+      _st == 200 and _body["available"] is False and _body["entities"] == [])
+check("the words shown are short and plain (STYLE: one sentence)",
+      all(len(t.split()) <= 12 and t.count(".") == 1
+          for t in (E.DOWN_TEXT, E.STALE_TEXT)))
+print(json.dumps(_body))
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED")
+    sys.exit(1)
+print("all passed")

goodwe_controller/test_home.py

@@ -0,0 +1,643 @@
+"""UX-13 P1: the Home screen's `/status` and the page shell.  `python3 -B test_home.py`
+
+1. `/status` keeps every old field (`banner`, `level`, `rows`, `checks`,
+   `hint`, `events`) AND carries the structured half the Home screen reads:
+   `state`, `now`, `batteries`, `plan`, `attention`, `month_peak`, `control`.
+   Both are pinned here, by name and shape.
+2. The plan shows only what the add-on does today. Trading on price is the
+   verdict the control cycle would reach (the same `plan.arbitrage()` call),
+   drawn where the cheapest and dearest prices are, with kWh and € per block.
+   The monthly cycle, the peak limit and "follows the house" are the rest.
+3. Shadow mode says "would", a stopped site plans nothing, and a red row is an
+   alarm under "Needs attention".
+4. A fault in the Home view never costs the page its old rows.
+5. The page: served at `/` from app/static, no external file, relative URLs
+   only, every label resolves in app/ui_text, and the region year reaches
+   `config/model` for the P2 Settings screens.
+
+The STYLE scan of every Home sentence is test_messages.py part 8.
+Mutating a module this file grades? Read MUTATION.md first (purge __pycache__).
+"""
+
+import asyncio
+import io
+import json
+import os
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+
+from aiohttp import ClientSession, web as aioweb
+
+from app import homeview, web
+from app.main import Controller
+from app.peakguard import PeakDecision
+from app.price import PricePoint, PriceProduct, PriceRead
+from app.static_tariff import TariffPlan
+from app.uimodel import REGION_PRESETS
+from named_absence import field, nth, present
+
+FLANDERS = REGION_PRESETS["flanders"]["taxes_eur_kwh"]
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+# --------------------------------------------------------------------------- #
+# Fixtures: a real Controller, with its readings set directly.
+# --------------------------------------------------------------------------- #
+class _Store:
+    def __init__(self):
+        self.data = {}
+
+    def set(self, k, v):
+        self.data[k] = v
+
+    def get(self, k, d=None):
+        return self.data.get(k, d)
+
+    def set_time(self, k, v):
+        self.data[k] = v.isoformat()
+
+    def get_time(self, k):
+        v = self.data.get(k)
+        return None if v is None else datetime.fromisoformat(v)
+
+
+class _Pub:
+    enabled = False
+
+    def publish(self, _v):
+        pass
+
+    def close(self):
+        pass
+
+
+class _Hass:
+    session = None
+    token = ""
+
+    async def limits(self, _e):
+        return (-5000.0, 5000.0, 1.0)
+
+    async def number(self, _e, invert=False):
+        return None
+
+    async def state(self, _e):
+        return None
+
+    async def set_number(self, _e, _v):
+        return True
+
+    async def call(self, *_a):
+        return True
+
+    async def states(self):
+        return []
+
+
+ONE = {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+       "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+       "meter_source": "off", "max_w": 5000, "shadow_mode": "off",
+       "maintenance_enabled": False}
+TWO = dict(ONE, inverters=[
+    {"name": "Battery A", "setpoint_entity": "number.a", "soc_entity":
+     "sensor.soc_a", "batt_entity": "sensor.batt_a", "max_w": 2500,
+     "capacity_kwh": 9.6},
+    {"name": "Battery B", "setpoint_entity": "number.b", "soc_entity":
+     "sensor.soc_b", "batt_entity": "sensor.batt_b", "max_w": 2500,
+     "capacity_kwh": 5.4}])
+
+# Sunday 27 September 2026, 11:40 in Brussels (09:40 UTC): the mockup's day.
+NOW = datetime(2026, 9, 27, 9, 40, tzinfo=timezone.utc)
+DAY0 = datetime(2026, 9, 26, 22, 0, tzinfo=timezone.utc)
+MOCK = [.24, .22, .21, .20, .21, .22, .24, .27, .26, .22, .18, .16, .15, .14,
+        .16, .19, .23, .28, .33, .36, .34, .29, .26, .24]
+
+
+def make(opts, *, soc=(62.0, 35.0), batt=(-2500.0, -300.0), grid=10.0,
+         auto=True, wrote=0.0):
+    """`wrote` is each inverter's last accepted power request (None: none yet)."""
+    c = Controller(dict(opts), _Hass(), _Store(), _Pub(), stop=asyncio.Event())
+    c.auto = auto
+    for i, inv in enumerate(c.inverters):
+        inv.soc, inv.batt = soc[i], batt[i]
+        inv.last_write = wrote
+        inv.dev_min, inv.dev_max = -5000.0, 5000.0
+    c.grid = grid
+    return c
+
+
+def provider_plan(prices=MOCK, day0=DAY0, days=2, provisional_from=None):
+    pts = []
+    for d in range(days):
+        for k, p in enumerate(prices):
+            start = day0 + timedelta(days=d, hours=k)
+            pts.append(PricePoint(start, p, provisional_from is not None
+                                  and start >= provisional_from))
+    return TariffPlan(PriceRead.series(tuple(pts), PriceProduct.DAY_AHEAD,
+                                       "generic_dayahead", NOW), None,
+                      "provider")
+
+
+def quiet_guard(projected_w=1240.0):
+    return PeakDecision(engaged=False, floor_w=None, ceiling_w=3500.0,
+                        ceiling_from="cap", projected_w=projected_w)
+
+
+def status(c, now=NOW):
+    s = c.status_payload()
+    # The status route builds at wall-clock time; rebuild the structured half
+    # at the fixture's instant so the day and the hours are the mockup's.
+    s.update(homeview.build(c, level=s["level"], checks=s["checks"], now=now))
+    return s
+
+
+# --------------------------------------------------------------------------- #
+print("1. /status: the old fields stay, the structured half is added")
+# --------------------------------------------------------------------------- #
+c1 = make(ONE, soc=(62.0,), batt=(960.0,), grid=800.0)
+s1 = c1.status_payload()
+OLD = {"banner", "level", "rows", "checks", "hint", "events"}
+NEW = {"state", "now", "batteries", "plan", "attention", "month_peak",
+       "control"}
+check(f"every old field is still there, with its old type ({sorted(OLD)})",
+      OLD <= set(s1) and isinstance(s1["rows"], list)
+      and all(len(r) == 2 for r in s1["rows"])
+      and all({"ok", "warn", "text"} <= set(r) for r in s1["checks"])
+      and isinstance(s1["banner"], str) and s1["level"] in ("ok", "warn", "bad")
+      and isinstance(s1["events"], list))
+check(f"...and the structured half is added beside them ({sorted(NEW)})",
+      NEW <= set(s1) and "home_error" not in s1)
+check("...and it is JSON, as the route serves it", json.loads(json.dumps(s1))
+      == json.loads(json.dumps(s1)))
+check("`state` names the kind, the pill word, the control row and a sub-line",
+      set(s1["state"]) == {"kind", "pill", "ran", "sub"}
+      and s1["state"]["kind"] == "running")
+check("`now` carries the four tiles in W and a plain line for each",
+      {"solar_w", "house_w", "grid_w", "batt_w", "has_solar", "lines"}
+      <= set(s1["now"])
+      and set(s1["now"]["lines"]) == {"solar", "house", "grid", "batt"}
+      and s1["now"]["grid_w"] == 800.0 and s1["now"]["batt_w"] == 960.0)
+_nh = homeview.now_block(grid_w=-3000.0, pv_w=1000.0, batt_w=1500.0,
+                         has_solar=True, shadow=False)
+_nz = homeview.now_block(grid_w=-1030.0, pv_w=1000.0, batt_w=0.0,
+                         has_solar=True, shadow=False)
+_np = homeview.now_block(grid_w=800.0, pv_w=1000.0, batt_w=-300.0,
+                         has_solar=True, shadow=False)
+check("House = grid (+ import) + solar + battery (+ giving): 800 + 1000 - 300 "
+      "= 1500 W",
+      _np["house_w"] == 1500.0 and _np["lines"]["house"] == "Using")
+check("...a sum below zero is not shown as a positive figure: 0 W inside "
+      "the idle band, and no figure beyond it",
+      _nz["house_w"] == 0.0 and _nh["house_w"] is None
+      and _nh["lines"]["house"] == homeview.tile_house(None, True, True))
+check("...and with no solar reading the house figure is NOT invented: it is "
+      "None and the tile says why",
+      s1["now"]["house_w"] is None and s1["now"]["has_solar"] is False
+      and s1["now"]["lines"]["house"] == homeview.tile_house(None, False))
+_b = s1["batteries"][0]
+check("`batteries[]` has level, power, state, mode, the now line and why",
+      {"name", "level_pct", "power_w", "state", "mode", "now", "why",
+       "capacity_kwh", "stored_kwh", "maintenance"} <= set(_b)
+      and _b["level_pct"] == 62.0 and _b["state"] == "giving"
+      and _b["now"] == "Giving 1.0 kW now.")
+_p = s1["plan"]
+check("`plan` carries the verdict, the prices, the runs, the lines and "
+      "the region",
+      {"verdict", "head", "prices", "runs", "lines", "now_h", "hours",
+       "price_line", "tomorrow_line", "region", "region_line"} <= set(_p)
+      and len(_p["prices"]) in (23, 24, 25))
+check("`attention[]` has severity, title, body and docs; `month_peak` and "
+      "`control` are there",
+      all({"severity", "title", "body", "docs"} <= set(a)
+          for a in s1["attention"])
+      and {"month", "limit_w", "peak_w", "pct", "period_w", "state", "line"}
+      <= set(s1["month_peak"])
+      and {"running", "shadow", "text", "maintenance", "docs_url"}
+      <= set(s1["control"]))
+
+# --------------------------------------------------------------------------- #
+print("\n2. the plan is what the add-on actually does")
+# --------------------------------------------------------------------------- #
+s_house = status(make(TWO))
+check("with trading off and no cycle due, each battery follows the house "
+      "from now to the end of the day, and nothing else is drawn",
+      [r["kind"] for r in s_house["plan"]["runs"]] == ["house", "house"]
+      and s_house["plan"]["verdict_key"] == "house"
+      and all(r["end_h"] == 24.0 and abs(r["start_h"] - 11 - 40 / 60) < 0.01
+              for r in s_house["plan"]["runs"])
+      and s_house["plan"]["runs"][0]["to"] == "24:00")
+
+ARB = dict(TWO, arbitrage_enabled=True, cycle_cost_threshold_eur=0.05)
+c_arb = make(ARB)
+c_arb.tariff_plan, c_arb.tariff_at = provider_plan(), NOW
+c_arb.peak_guard = quiet_guard()
+s_arb = status(c_arb)
+_runs = s_arb["plan"]["runs"]
+_grid = [r for r in _runs if r["kind"] == "grid"]
+_give = [r for r in _runs if r["kind"] == "give"]
+check("trading on price: a charge block at the cheapest hour (13:00) and a "
+      "give block at the dearest (19:00), on each battery",
+      [(r["battery"], r["from"], r["to"]) for r in _grid]
+      == [(0, "13:00", "14:00"), (1, "13:00", "14:00")]
+      and [(r["battery"], r["from"], r["to"]) for r in _give]
+      == [(0, "19:00", "20:00"), (1, "19:00", "20:00")]
+      and s_arb["plan"]["verdict_key"] == "trade")
+check("...placed where the control cycle's own verdict puts them: the same "
+      "plan.arbitrage() call on the same plan",
+      c_arb.fresh_tariff_plan(NOW).arbitrage(
+          peak_guard_active=False, min_spread_eur_kwh=0.05,
+          uncertainty=frozenset({__import__("app.price", fromlist=["x"])
+                                 .Uncertainty.NO_WEATHER}))
+      .match(allowed=lambda v: (v.cheapest.start, v.dearest.start),
+             refused=lambda v: None)
+      == (DAY0 + timedelta(hours=13), DAY0 + timedelta(hours=19)))
+# Battery A: 2.5 kW for 1 h = 2.5 kWh; room to the 95 % ceiling is 33 % of
+# 9.6 kWh = 3.17 kWh, so 2.5. Battery B: 60 % of 5.4 = 3.24, so 2.5.
+check("each block carries kWh and €: charging is capped by the battery's own "
+      "rating and the room its level leaves, € = kWh x that hour's price",
+      [r["kwh"] for r in _grid] == [2.5, 2.5]
+      and [r["eur"] for r in _grid] == [0.35, 0.35]
+      and [r["eur_kwh"] for r in _grid] == [0.14, 0.14]
+      and "2.5 kWh" in _grid[0]["what"] and "€0.14" in _grid[0]["why"]
+      and "€0.35" in _grid[0]["amount"])
+# Giving at 19:00 comes after the 13:00 charge, so each battery may give what
+# it will hold then: B is at 35 % + 2.5 kWh of 5.4 = 81 %, and 81 - 20 = 61 %
+# of 5.4 = 3.3 kWh, so 2.5 (an upper bound, like every amount here).
+check("...and giving is capped by what each battery holds above arbitrage's "
+      "floor after the charge before it",
+      [r["kwh"] for r in _give] == [2.5, 2.5]
+      and [r["eur"] for r in _give] == [0.9, 0.9])
+
+
+def trade(soc, prices=MOCK, provisional_from=None, now=NOW, opts=ARB):
+    c = make(opts, soc=soc)
+    c.tariff_plan = provider_plan(prices, provisional_from=provisional_from)
+    c.tariff_at, c.peak_guard = now, quiet_guard()
+    s = status(c, now=now)
+    return ([(r["kind"], r["battery"], r["kwh"]) for r in s["plan"]["runs"]
+             if r["kind"] in ("grid", "give")], s["plan"]["lines"])
+
+
+# Review of #144: only what arbitrage.decide() would still do is drawn.
+_t, _l = trade((96.0, 35.0))
+check("a battery at arbitrage's ceiling gets no charge block, not "
+      "'Charges up to 0.0 kWh'", ("grid", 0, 0.0) not in _t
+      and [k for k in _t if k[0] == "grid"] == [("grid", 1, 2.5)])
+# 20:00 local: the dearest (19:00) is over; tomorrow's charge is a line. Put
+# the dearest later today instead, with the emptiest pack at the floor.
+_late = MOCK[:22] + [.40, .24]
+_t, _l = trade((62.0, 20.0), prices=_late, now=NOW + timedelta(hours=8))
+_t2, _l2 = trade((62.0, 35.0), prices=_late, now=NOW + timedelta(hours=8))
+check("no give block while the emptiest battery is at arbitrage's floor: "
+      "the cycle's sale is graded on the emptiest pack (at 35 % both give)",
+      not [k for k in _t if k[0] == "give"]
+      and [k[:2] for k in _t2] == [("give", 0), ("give", 1)])
+_t, _l = trade((62.0, 35.0), prices=[x - 0.5 for x in MOCK])
+check("no give block at a negative price (the cycle refuses that sale)",
+      not [k for k in _t if k[0] == "give"]
+      and [k for k in _t if k[0] == "grid"])
+# Running, a missing level is a red row and the site is held. In shadow mode
+# the plan is still drawn, so this is where the level gate shows.
+_t, _l = trade((None, 35.0), opts=dict(ARB, shadow_mode="on"))
+check("with a battery level unknown the cycle does not trade, so nothing is "
+      "drawn and a line says why (shadow mode, which still plans)",
+      _t == [] and homeview.line_no_trade("no_level") in _l)
+_t, _l = trade((62.0, 35.0), provisional_from=DAY0)
+check("a plan with no published prices yet says so, not 'the price gap is "
+      "too small'",
+      _t == [] and homeview.line_no_trade("not_firm") in _l
+      and homeview.line_no_trade("not_worth") not in _l)
+check("the price bars are today's 24 hours, from the real series, with the "
+      "cheap and expensive thirds marked",
+      [b["eur_kwh"] for b in s_arb["plan"]["prices"]] == MOCK
+      and s_arb["plan"]["prices"][13]["kind"] == "cheap"
+      and s_arb["plan"]["prices"][19]["kind"] == "dear"
+      and s_arb["plan"]["prices"][0]["kind"] == "mid"
+      and s_arb["plan"]["prices"][13]["label"] == "13:00")
+check("the price line names the price now, today's lowest and highest, and "
+      "that tomorrow's prices are in",
+      s_arb["plan"]["price_line"] == ("Price now €0.16 per kWh, all in. "
+                                      "Today: lowest €0.14 at 13:00, "
+                                      "highest €0.36 at 19:00.")
+      and s_arb["plan"]["tomorrow_line"] == "Tomorrow's prices are in.")
+
+c_late = make(ARB)
+c_late.tariff_plan, c_late.tariff_at = provider_plan(), NOW
+c_late.peak_guard = quiet_guard()
+s_late = status(c_late, now=NOW + timedelta(hours=9))    # 20:40 local
+check("a block whose hour is over is not drawn: at 20:40 no trade is left "
+      "today",
+      not [r for r in s_late["plan"]["runs"] if r["kind"] in ("grid", "give")])
+
+c_peak = make(ARB)
+c_peak.tariff_plan, c_peak.tariff_at = provider_plan(), NOW
+c_peak.peak_guard = PeakDecision(engaged=True, floor_w=800.0,
+                                 ceiling_w=3500.0, ceiling_from="cap",
+                                 projected_w=3900.0)
+s_peak = status(c_peak)
+check("while the peak limit holds, the verdict refuses as the cycle does: no "
+      "trade block, a plain line, and a peak block for this 15-minute period",
+      not [r for r in s_peak["plan"]["runs"] if r["kind"] in ("grid", "give")]
+      and homeview.line_no_trade("peak") in s_peak["plan"]["lines"]
+      and [(r["from"], r["to"]) for r in s_peak["plan"]["runs"]
+           if r["kind"] == "peak"] == [("11:30", "11:45"), ("11:30", "11:45")])
+
+c_pk = make(ARB)
+c_pk.p1_enabled = True        # the peak line is shown where P1 runs
+c_pk.tariff_plan, c_pk.tariff_at = provider_plan(), NOW
+c_pk.peak_guard = PeakDecision(engaged=False, floor_w=None, ceiling_w=4200.0,
+                               ceiling_from="month_peak", projected_w=1240.0)
+s_pk = status(c_pk)
+check("the plan's peak line names the guard's ceiling, which is this month's "
+      "peak once it is above the limit",
+      homeview.line_peak_limit(4200.0, False) in s_pk["plan"]["lines"]
+      and s_pk["month_peak"]["line"].endswith("above 4.2 kW."))
+
+c_blind = make(ARB)
+c_blind.tariff_plan, c_blind.tariff_at = provider_plan(), NOW
+s_blind = status(c_blind)          # meter_source off: the guard never runs
+check("with nothing measuring the 15-minute peak, trading is NOT drawn, as "
+      "the cycle refuses it (guard state None)",
+      not [r for r in s_blind["plan"]["runs"] if r["kind"] in ("grid", "give")]
+      and homeview.line_no_trade("not_covered") in s_blind["plan"]["lines"])
+
+c_flat = make(ARB)
+c_flat.tariff_plan, c_flat.tariff_at = provider_plan(prices=[.2] * 24), NOW
+c_flat.peak_guard = quiet_guard()
+s_flat = status(c_flat)
+check("a flat day: no trade, no cheap or expensive hour marked",
+      not [r for r in s_flat["plan"]["runs"] if r["kind"] in ("grid", "give")]
+      and {b["kind"] for b in s_flat["plan"]["prices"]} == {"mid"}
+      and homeview.line_no_trade("not_worth") in s_flat["plan"]["lines"])
+
+c_old = make(ARB)
+c_old.tariff_plan = provider_plan()
+c_old.tariff_at = NOW - timedelta(hours=3)                # past its max age
+c_old.peak_guard = quiet_guard()
+s_old = status(c_old)
+check("a stale plan is not traded on by the cycle, so it is not drawn",
+      not [r for r in s_old["plan"]["runs"] if r["kind"] in ("grid", "give")])
+
+MAINT = dict(TWO, maintenance_enabled=True, maintenance_start_hour=12)
+c_m = make(MAINT)
+s_m = status(c_m)
+_cyc = [r for r in s_m["plan"]["runs"] if r["kind"] == "cycle"]
+check("a monthly cycle due today is drawn on ONE battery, at the start hour "
+      "the cycle uses (12 UTC is 14:00 here), and the other one waits",
+      len(_cyc) == 1 and field(nth(_cyc), "from") == "14:00"
+      and s_m["plan"]["verdict_key"] == "cycle"
+      and any("waits its turn" in x for x in s_m["plan"]["lines"]))
+check("...with its duration from the battery's capacity and the cycle's rates "
+      "and hold time",
+      present(nth(_cyc)) and _cyc[0]["amount"].startswith("Takes about ")
+      and _cyc[0]["end_h"] > _cyc[0]["start_h"] + 2)
+c_m.maints[0].store.set("phase", "drain")
+s_md = status(c_m)
+check("a cycle under way is drawn from now, and the battery's now line says "
+      "so",
+      [r["from"] for r in s_md["plan"]["runs"] if r["kind"] == "cycle"]
+      == ["11:40"]
+      and s_md["batteries"][0]["now"] == "Monthly cycle: emptying."
+      and any("Battery B waits its turn" in x for x in s_md["plan"]["lines"]))
+
+# --------------------------------------------------------------------------- #
+print("\n3. shadow mode, a stopped site, an alarm")
+# --------------------------------------------------------------------------- #
+c_sh = make(dict(ARB, shadow_mode="on"))
+c_sh.tariff_plan, c_sh.tariff_at = provider_plan(), NOW
+c_sh.peak_guard = quiet_guard()
+s_sh = status(c_sh)
+_texts = [r["what"] for r in s_sh["plan"]["runs"]] + [s_sh["plan"]["head"]]
+check("shadow: the state is shadow, the battery tile is held at 0 W, and "
+      "every block and the head say 'would'",
+      s_sh["state"]["kind"] == "shadow"
+      and s_sh["now"]["lines"]["batt"] == "Held at 0 W"
+      and all("ould" in x for x in _texts)
+      and s_sh["plan"]["head"].startswith("Shadow mode:"))
+check("...and 'Shadow mode is on' is the first item under Needs attention",
+      s_sh["attention"][0]["title"] == homeview.ATTN_SHADOW
+      and s_sh["attention"][0]["severity"] == "info")
+check("...and each battery's now line says it is held at 0 W",
+      all(b["now"].startswith("Held at 0 W.") for b in s_sh["batteries"]))
+
+s_stop = status(make(TWO, auto=False))
+check("stopped: nothing is planned and the head says so",
+      s_stop["plan"]["runs"] == [] and s_stop["state"]["kind"] == "stopped"
+      and s_stop["plan"]["verdict_key"] == "stopped"
+      and s_stop["control"]["running"] is False
+      and all(b["now"] == "Held at 0 W while control is stopped."
+              for b in s_stop["batteries"]))
+
+c_al = make(ONE, soc=(62.0,), batt=(0.0,))
+c_al.inverters[0].sign_wd.tripped = True
+s_al = c_al.status_payload()
+_red = [a for a in s_al["attention"] if a["severity"] == "alarm"]
+check("an alarm: level bad, state alarm, and the red row is the first item "
+      "under Needs attention",
+      s_al["level"] == "bad" and s_al["state"]["kind"] == "alarm"
+      and _red and s_al["attention"][0] is _red[0]
+      and _red[0]["title"] == homeview.ATTN_TITLES["direction"])
+check("...and nothing is planned while every inverter is held at 0 W",
+      s_al["plan"]["runs"] == [] and s_al["plan"]["verdict_key"] == "held")
+_rows = [r for r in s_al["checks"] if not r["ok"] and not r["warn"]]
+check("...and every red, amber and settling row reaches Needs attention with "
+      "its own sentence as the body, and no green row does",
+      [a["body"] for a in homeview.attention(s_al["checks"])]
+      == [r["text"] for r in s_al["checks"] if not r["ok"] and not r["warn"]]
+      + [r["text"] for r in s_al["checks"] if not r["ok"] and r["warn"]]
+      + [r["text"] for r in s_al["checks"] if r["ok"] and r["warn"]])
+
+# UX-13 P1 test finding (a): the page said "Held at 0 W" about 15 s before
+# the inverter's power request reached 0 W. Until the last accepted request
+# is 0 W it says "Going to 0 W".
+c_al.inverters[0].last_write = 20.0
+s_go = homeview.build(c_al, level="bad", checks=s_al["checks"], now=NOW)
+c_al.inverters[0].last_write = 0.0
+s_at = homeview.build(c_al, level="bad", checks=s_al["checks"], now=NOW)
+check("an alarm while the last power request is still 20 W says 'Going to "
+      "0 W', and 'Held at 0 W' once 0 W was accepted",
+      s_go["plan"]["verdict"] == "Going to 0 W"
+      and s_go["batteries"][0]["now"] == "Going to 0 W until the alarm clears."
+      and s_go["plan"]["head"].startswith("Every inverter goes to 0 W")
+      and s_at["plan"]["verdict"] == "Held at 0 W"
+      and s_at["batteries"][0]["now"] == "Held at 0 W until the alarm clears.")
+c_sp = make(TWO, auto=False)
+c_sp.inverters[1].last_write = -1500.0
+s_sp = status(c_sp)
+s_new = status(make(TWO, auto=False, wrote=None))
+check("...and before any power request was accepted (just started, or every "
+      "write refused) it says 'Going to 0 W', not 'Held'",
+      [b["now"] for b in s_new["batteries"]]
+      == ["Going to 0 W while control is stopped."] * 2)
+check("...and a stop does the same, per battery",
+      [b["now"] for b in s_sp["batteries"]]
+      == ["Held at 0 W while control is stopped.",
+          "Going to 0 W while control is stopped."])
+
+# Finding (b): a quarter-hourly feed. The block's price and the price line
+# name the same 15-minute point, and nothing says "the list".
+_q = []
+for _k, _p in enumerate(MOCK):
+    for _m in range(4):
+        _q.append(PricePoint(DAY0 + timedelta(hours=_k, minutes=15 * _m),
+                             round(_p + (0.0 if _m != 3 else -0.01), 4), False))
+_q += [PricePoint(p.start + timedelta(days=1), p.eur_per_kwh, False)
+       for p in list(_q)]
+c_q = make(ARB)
+c_q.tariff_plan = TariffPlan(PriceRead.series(tuple(_q), PriceProduct.DAY_AHEAD,
+                                              "generic_dayahead", NOW), None,
+                             "provider")
+c_q.tariff_at = NOW
+c_q.peak_guard = quiet_guard()
+s_q = status(c_q)
+_grid = [r for r in s_q["plan"]["runs"] if r["kind"] == "grid"]
+_lo = min(_q[:96], key=lambda p: p.eur_per_kwh)
+check("quarter-hour prices: the charge block, its price and the price line's "
+      "lowest are the same 15-minute period",
+      _grid and _grid[0]["from"] == homeview.hhmm(_lo.start)
+      and _grid[0]["why"] == f"Lowest published price, €{_lo.eur_per_kwh:.2f} "
+                             "per kWh."
+      and f"Today: lowest €{_lo.eur_per_kwh:.2f} at "
+          f"{homeview.hhmm(_lo.start)}," in s_q["plan"]["price_line"]
+      and "the list" not in json.dumps(s_q["plan"]))
+check("...and the hour bar says it is an hour average",
+      s_q["plan"]["prices"][13]["points"] == 4
+      and '"plan.average_tip"' in io.open(os.path.join(
+          HERE, "app", "static", "app.js"), encoding="utf-8").read())
+
+# --------------------------------------------------------------------------- #
+print("\n4. a fault in the Home view never costs the page its rows")
+# --------------------------------------------------------------------------- #
+_real = homeview.build
+try:
+    homeview.build = lambda *a, **k: 1 / 0
+    s_err = make(ONE, soc=(50.0,), batt=(0.0,)).status_payload()
+finally:
+    homeview.build = _real
+check("the old fields are served and `home_error` says the rest is missing",
+      OLD <= set(s_err) and s_err.get("home_error") is True
+      and not (NEW & set(s_err)))
+
+# --------------------------------------------------------------------------- #
+print("\n5. the page")
+# --------------------------------------------------------------------------- #
+PAGE = web.page()
+JS = io.open(os.path.join(HERE, "app", "static", "app.js"),
+             encoding="utf-8").read()
+UI = json.load(io.open(os.path.join(HERE, "app", "ui_text", "en.json"),
+                       encoding="utf-8"))["home"]
+
+
+def resolve(path):
+    node = UI
+    for k in path.split("."):
+        if not isinstance(node, dict) or k not in node:
+            return None
+        node = node[k]
+    return node
+
+
+check("the page is assembled: no placeholder is left and the words parse",
+      "/*APP_CSS*/" not in PAGE and "/*APP_JS*/" not in PAGE
+      and "/*UI_TEXT*/" not in PAGE
+      and json.loads(PAGE.split('id="ui-text">', 1)[1]
+                     .split("</script>", 1)[0].replace("<\\/", "</"))["home"]
+      == UI)
+check("four tabs with the four hash routes, in a keyboard tablist",
+      re.findall(r'data-hash="(\w+)"', PAGE) == ["home", "batteries",
+                                                 "settings", "setup"]
+      and 'role="tablist"' in PAGE and PAGE.count('role="tabpanel"') == 4
+      and "ArrowRight" in JS and "ArrowLeft" in JS)
+_ext = re.findall(r"""(?:https?:)?//[A-Za-z0-9.-]+\.[a-z]{2,}""", PAGE)
+check(f"no external file and no web font: no URL leaves the add-on "
+      f"({_ext})", not _ext and "@import" not in PAGE
+      and "<link" not in PAGE and "src=" not in PAGE)
+_abs = re.findall(r"""(?:fetch\(|href=)["'](/[^"']*)["']""", PAGE)
+check(f"every fetch and link is relative, for ingress ({_abs})",
+      not _abs and 'fetch("status"' in JS and 'fetch("action"' in JS)
+_keys = set(re.findall(r'data-t(?:-label)?="([\w.]+)"', PAGE)) | set(
+    re.findall(r'''\bt\("([\w.]+)"\)''', JS))
+_missing = sorted(k for k in _keys if not isinstance(resolve(k), str))
+check(f"every label the page asks for is in app/ui_text ({len(_keys)} "
+      f"keys; missing: {_missing})", len(_keys) > 30 and not _missing)
+check("data is set as text, never as HTML, so no status sentence can inject "
+      "markup", "innerHTML" not in JS and "insertAdjacentHTML" not in JS)
+check("every function of the old page is still on it: start/stop, the "
+      "maintenance start and abort, the status rows, the checks and the "
+      "event line",
+      "auto_toggle" in JS and '"maint_start"' in JS and '"maint_abort"' in JS
+      and 'id="rows"' in PAGE and 'id="checks"' in PAGE
+      and 'id="hint"' in PAGE and 'href="config"' in PAGE)
+check("stopping, starting and both maintenance actions ask first",
+      all(f'ask("{k}"' in JS for k in ("stop", "start", "maint_start",
+                                       "maint_abort")))
+check("tooltips open on hover, on a tap and on keyboard focus",
+      "pointermove" in JS and "pointerdown" in JS and "focusin" in JS)
+check("the chart is not colour alone: expensive hours and blocks are "
+      "patterned, and every item has a text label",
+      "repeating-linear-gradient" in PAGE and '"aria-label": tipText' in JS)
+check("the phone layout puts the tabs at the bottom under 640 px, and dark "
+      "mode follows the system",
+      "@media (max-width:640px)" in PAGE and "position:fixed;bottom:0" in PAGE
+      and "prefers-color-scheme:dark" in PAGE)
+
+
+async def _serve():
+    class _Sup:
+        async def info(self):
+            return {"options": {"price_taxes_eur_kwh": FLANDERS,
+                                "price_taxes_profile": ""},
+                    "schema": [], "translations": {}}
+    c = make(ONE, soc=(50.0,), batt=(0.0,))
+    runner = aioweb.AppRunner(web.build_app(c, _Sup()))
+    await runner.setup()
+    site = aioweb.TCPSite(runner, "127.0.0.1", 0)
+    await site.start()
+    port = site._server.sockets[0].getsockname()[1]
+    out = {}
+    try:
+        async with ClientSession() as s:
+            async with s.get(f"http://127.0.0.1:{port}/") as r:
+                out["page"] = (r.status, r.content_type, await r.text())
+            async with s.get(f"http://127.0.0.1:{port}/status") as r:
+                out["status"] = await r.json()
+            async with s.get(f"http://127.0.0.1:{port}/config/model") as r:
+                out["model"] = await r.json()
+    finally:
+        await runner.cleanup()
+    return out
+
+
+E = asyncio.run(_serve())
+check("GET / serves the assembled page as HTML", E["page"][0] == 200
+      and E["page"][1] == "text/html" and E["page"][2] == PAGE)
+check("GET status over HTTP carries both halves",
+      OLD <= set(E["status"]) and NEW <= set(E["status"]))
+check("the levies preset and its year reach config/model for the P2 "
+      "Settings screens (P0 review follow-up)",
+      E["model"].get("region") == {"id": "flanders", "year": 2026})
+c_reg = make(dict(ARB, price_taxes_eur_kwh=FLANDERS))
+c_reg.tariff_plan, c_reg.tariff_at = provider_plan(), NOW
+s_reg = status(c_reg)
+check("...and Home names the preset with its year wherever prices come from "
+      "a feed, and says 'your own figure' otherwise",
+      s_reg["plan"]["region"] == {"id": "flanders", "year": 2026}
+      and s_reg["plan"]["region_line"]
+      == "Levies and VAT: Flanders, Fluvius Antwerpen, 2026 figures."
+      and s_arb["plan"]["region_line"] == "Levies and VAT: your own figure."
+      and s_house["plan"]["region_line"] == "")
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED")
+    sys.exit(1)
+print("all passed")

goodwe_controller/test_maintenance.py

@@ -497,7 +497,7 @@ check("a FORCED start is refused while another pack holds the slot, and the "
       "phase machine does not move. The calendar is a preference an operator "
       "may overrule; one pack at a time is a property of the grid connection "
       "and a button does not add a second one",
-      _b8.phase == IDLE and len(_ev) == 1 and "REFUSED" in _ev[0]
+      _b8.phase == IDLE and len(_ev) == 1 and "cannot start now" in _ev[0]
       and "inverter-a" in _ev[0])
 check("...and an unblocked forced start still works, so the refusal is a "
       "condition and not a disabled feature",
@@ -534,7 +534,7 @@ check("...and the deferred pack's PHASE does not move either, so "
       _b9.phase == IDLE and _b9.store.get_time("phase_started") is None)
 check("...and the words say WAITING, name the pack it waits for, and say it "
       "will run next - none of which any failure path in this module says",
-      "WAITING" in _r9[1].events[0]
+      "waits its turn" in _r9[1].events[0]
       and "inverter-a" in _r9[1].events[0]
       and "not a stalled phase" in _r9[1].events[0]
       and "ABORT" not in _r9[1].events[0] and "stuck" not in _r9[1].events[0])
@@ -687,7 +687,7 @@ print(f"    a store already written by a multi-inverter version: {_rep3.explain(
 check("a store already at the per-pack schema is NOT TOUCHED - not one key "
       "written - and says so",
       not _rep3.ran and _m3.data == _before3 and _m3.writes == []
-      and "not touched" in _rep3.explain())
+      and "left as it is" in _rep3.explain())
 
 # ⚠️ AND BREAK IT. The read-back postcondition is the whole difference between
 # this and a two-line copy, and it is inherited from `migrate_unit_keys()`
@@ -766,7 +766,7 @@ check("...and the refusal NAMES the namespace it used AND the roster it was "
       "graded against, rather than merely saying something went wrong - the "
       "operator's next question is 'which name, and which one should it have "
       "been', and a bare `not ok` answers neither",
-      "WRONG NAMESPACE" in _rep5.explain()
+      "moved under an inverter not in the list" in _rep5.explain()
       and unit_key(UNIT_A, "last_completed") in _rep5.explain()
       and repr(ROSTER) in _rep5.explain())
 check("⚠️ AND THE MARKER IS NOT STAMPED, WHICH IS THE WHOLE REMEDY. A stamped "
@@ -893,7 +893,7 @@ check("...and the counterfactual: the SAME two calls with the roster's own "
       "`already at schema` early return, not a refusal. So 9c is about the "
       "NAME surviving into the second start, not about second calls",
       _rep7ok_a.ok and _m7ok.data[MAINT_SCHEMA_KEY] == MAINT_SCHEMA_VERSION
-      and _rep7ok_b.ran is False and "already at schema" in _rep7ok_b.explain())
+      and _rep7ok_b.ran is False and "already at version" in _rep7ok_b.explain())
 
 
 # --------------------------------------------------------------------------- #

goodwe_controller/test_peakguard.py

@@ -1240,13 +1240,13 @@ check("an engagement that is not saturated raises NO notification - §10.3's "
       "goodwe_peak_saturated" not in hass.notifications)
 check("...but it does reach the action log, which is where a control action "
       "that moves energy belongs",
-      any("PEAK GUARD" in e for e in c.events))
-n_events = sum(1 for e in c.events if "PEAK GUARD" in e)
+      any("PEAK_GUARD" in e for e in c.events))
+n_events = sum(1 for e in c.events if "PEAK_GUARD" in e)
 asyncio.get_event_loop_policy().new_event_loop().run_until_complete(c.cycle())
 check("...and it is edge-logged, not level-logged: a second engaged cycle adds "
       "no second line, so a quarter of engagement cannot push the cause of the "
       "event off a 40-line log",
-      sum(1 for e in c.events if "PEAK GUARD" in e) == n_events)
+      sum(1 for e in c.events if "PEAK_GUARD" in e) == n_events)
 
 # The saturated case, through the same real cycle.
 # A floor of 1.5x what the inverter can give: it saturates wherever in the
@@ -1661,8 +1661,8 @@ check("...and it still says what it WOULD have taken, so the under-shave is a "
       near(d_lim.wanted_w, WANTED, 1e-6) and d_lim.wanted_w > d_lim.floor_w)
 check("...and its one-line explanation tells the operator the consequence in "
       "the words that matter - the quarter is going over the ceiling",
-      "FLOOR-LIMITED" in d_lim.explain()
-      and "WILL GO OVER THE CEILING" in d_lim.explain()
+      "FLOOR_LIMITED" in d_lim.explain()
+      and "will go over the limit" in d_lim.explain()
       and f"{CEIL:.0f} W" in d_lim.explain())
 check("an unreadable SoC lands in the same branch, with the OTHER reason - so "
       "an operator reading one line can tell a flat battery from a dead sensor",
@@ -1944,7 +1944,7 @@ check("the status page carries exactly one peak-guard row and it is NOT ok - "
       "the money is going to be spent and a human is the only actuator left",
       len(rows24) == 1 and not rows24[0]["ok"] and not rows24[0]["warn"]
       and "peak limit will be passed" in rows24[0]["text"])
-check("...and it reaches the action log too", any("FLOOR-LIMITED" in e
+check("...and it reaches the action log too", any("FLOOR_LIMITED" in e
                                                   for e in c24.events))
 # A missing SoC sensor, through the same real cycle. `inputs_ok` stops the loop
 # at 0 W in that state, so the guard's own answer is what is graded here.
@@ -2655,7 +2655,7 @@ check("...and so does the persistent notification, which outlives the page and "
 # wants from you, not an edit.
 CLAIM_SOURCES = {"device", "supervised", "failsafe", "safety", "peak",
                  "arbitrage", "maintenance", "loop", "circulation",
-                 "sign_site", "pack"}
+                 "sign_site", "pack", "refused"}
 # The two appends that file a claim BUILT ELSEWHERE in the method. Named here so
 # that a THIRD such indirection reads as an unrecognised append rather than as a
 # silent gap in the scan.
@@ -2697,7 +2697,7 @@ check("every `claims.append(...)` in main.py's cycle is one this scan can READ "
       "- a claim filed through a shape it cannot parse has to fail here rather "
       "than be counted as nothing, which is how a scan like this goes quietly "
       "vacuous", len(_appends) >= 10 and None not in _filed)
-check("...and the sources that cycle can file are EXACTLY these ELEVEN. THIS "
+check("...and the sources that cycle can file are EXACTLY these TWELVE. THIS "
       "is what makes part 10 a tripwire: replay_loop() hand-builds the claim "
       "list, so it cannot see a claim main.py adds - and a loop-side SoC "
       "reserve is a new source. Filing one takes this line red on the line it "
@@ -2848,7 +2848,8 @@ check("...and the split is the one ARB-03 argued, with SAFETY-31's and "
       {s for s, v in CLAIM_SCOPE.items() if v == SCOPE_SITE}
       == {"loop", "peak", "arbitrage", "safety", "circulation", "sign_site"}
       and {s for s, v in CLAIM_SCOPE.items() if v == SCOPE_UNIT}
-      == {"device", "supervised", "failsafe", "maintenance", "pack"})
+      == {"device", "supervised", "failsafe", "maintenance", "pack",
+          "refused"})
 
 # The shipped roster is ONE inverter, so §6.2's identity holds and every claim a
 # real cycle files is a site claim. Observed on the claims main.py's own resolve
@@ -2945,7 +2946,7 @@ check("⚠️ AND THIS IS THE BREAKING HALF. Give the same Controller a second "
       "rest of the roster goes on pushing the same way - and this line goes red",
       _routed == {"device": "inverter-a", "supervised": "inverter-a",
                   "failsafe": "inverter-a", "maintenance": "inverter-a",
-                  "pack": "inverter-a",
+                  "pack": "inverter-a", "refused": "inverter-a",
                   "loop": ACTUATOR_SITE, "peak": ACTUATOR_SITE,
                   "arbitrage": ACTUATOR_SITE, "safety": ACTUATOR_SITE,
                   "circulation": ACTUATOR_SITE, "sign_site": ACTUATOR_SITE})
@@ -3027,13 +3028,13 @@ _unit_sources_unrouted = [
     if CLAIM_SCOPE.get(r[0]) == SCOPE_UNIT and "," not in r[1]]
 print(f"    {len(_direct)} direct appends, each read at its own line: "
       + ", ".join(f"main.py:{ln} {s} -> {a}" for s, a, ln in _routing))
-check("all ELEVEN of `Controller.cycle()`'s DIRECT appends route through "
+check("all THIRTEEN of `Controller.cycle()`'s DIRECT appends route through "
       "`self.actuator_of(<string literal>)`, so this scan can read the routing "
       "of EVERY one of them. An append that computed its actuator, or omitted "
       "the argument, or hand-wrote a string, fails HERE rather than being "
       "silently skipped - which is how a scan like this goes quietly vacuous, "
       "and 10f is in this file because that already happened once",
-      len(_direct) == 11
+      len(_direct) == 13
       and all(a is not None and a.startswith("self.actuator_of('")
               for _s, a, _ln in _routing))
 check("⚠️ AND AT EVERY ONE OF THE ELEVEN THE LITERAL IT ROUTES THROUGH IS THE "
@@ -3050,15 +3051,15 @@ check("⚠️ AND EVERY PER-INVERTER APPEND NAMES THE INVERTER IT IS ABOUT. "
       "site-scoped sources and is the whole defect for a per-inverter one: a "
       "`device` limit built inside the roster loop and routed without `inv` "
       "files inverter B's rating on inverter A, where it binds the wrong "
-      "share. Six of the eleven appends are SCOPE_UNIT - `device`, "
-      "`supervised`, `failsafe`, maintenance's two and OPT-09's `pack` - and "
-      "all six pass one. "
+      "share. Eight of the thirteen appends are SCOPE_UNIT - `device`, "
+      "`supervised`, `failsafe`, maintenance's two, OPT-09's `pack` and "
+      "SAFETY-73's two `refused` - and all eight pass one. "
       "SAFETY-30's `sign_site` is deliberately NOT one of them: it is filed on "
       "the site, beside `circulation`, because the number that tripped it is "
       "the site target",
       _unit_sources_unrouted == []
       and len([r for r in _routing
-               if CLAIM_SCOPE.get(r[0]) == SCOPE_UNIT]) == 6)
+               if CLAIM_SCOPE.get(r[0]) == SCOPE_UNIT]) == 8)
 check("...and the only appends this pin does NOT reach are the two that file a "
       "claim BUILT ELSEWHERE - `peak_claim` and `arb_claim` - which have no "
       "`actuator=` at the call site to mis-type. Their routing is pinned where "
@@ -3067,7 +3068,7 @@ check("...and the only appends this pin does NOT reach are the two that file a "
       "arbitrage.claim() by test_arbitrage.py",
       sorted(_indirect) == sorted(CLAIM_BUILDERS)
       and len(_direct) + len(_indirect) == len(_appends))
-check("...and between them the twelve appends account for exactly the eleven "
+check("...and between them the fifteen appends account for exactly the twelve "
       "sources 10f pins, so the routing pin and the source set are one scan "
       "and neither can drift from the other",
       {s for s, _a, _ln in _routing} | set(CLAIM_BUILDERS.values())
@@ -3119,7 +3120,7 @@ check("⚠️ AND THE RATING LIMITS ARE FILED ONCE PER INVERTER, ON ITS OWN "
           ("supervised", "inverter-a"),
           ("supervised", "inverter-b")])
 check("...and naming those three is not an accident of this fixture but the "
-      "reason the static pin exists - SEVEN of the eleven sources need a state "
+      "reason the static pin exists - EIGHT of the twelve sources need a state "
       "no check in this file reaches. SAFETY-31's `circulation` is one of the "
       "seven: it is filed only while the site is MEASURED to be circulating, "
       "which no fixture here is. SAFETY-30's `sign_site` is another, and it "
@@ -3127,7 +3128,8 @@ check("...and naming those three is not an accident of this fixture but the "
       "standing opposed to the meter for its whole window",
       {c.source for c in _cl2}
       == CLAIM_SOURCES - {"failsafe", "safety", "maintenance", "peak",
-                          "arbitrage", "circulation", "sign_site"})
+                          "arbitrage", "circulation", "sign_site",
+                          "refused"})
 # ⚠️ AND NOW THE HALF THAT WAS EVIDENCE-SHAPED AND OBSERVED NOTHING. The three
 # checks above grade WHICH ACTUATOR each claim lands on. They say nothing about
 # WHOSE NUMBERS the bound is built from - and those are two different defects

goodwe_controller/test_price.py

@@ -4107,7 +4107,8 @@ _T11_SLOTS = {
     "carried": r"\d+ published and (\d+) estimated",
     "horizon": r"for (\d+) hours ahead",
     "age_s": r"Price plan from (\d+) s ago",
-    "spacings": r"([\d+]+) s apart",
+    # UX-10: the spacing is in words ("one every 15 minutes or every hour").
+    "spacings": r"one (every [a-z0-9 ]+?)(?:,|\.|$)",
     # ⚠️ THE *Arbitrage* ROW'S OWN AGE SLOT, and it is deliberately the same
     # pattern for "decided N s ago" and "the last one was taken N s ago" -
     # WHICH of the two sentences was rendered is graded by inequality below,
@@ -4125,6 +4126,18 @@ _T11_SLOTS = {
 }
 
 
+def _spacing_s(raw):
+    """`every 15 minutes or every hour` -> `[900, 3600]`; raises otherwise."""
+    unit = {"second": 1, "minute": 60, "hour": 3600}
+    out = []
+    for part in raw.split(" or "):
+        m = re.fullmatch(r"every (?:(\d+) )?(second|minute|hour)s?", part.strip())
+        if m is None:
+            raise ValueError(f"no spacing in {part!r}")
+        out.append(int(m.group(1) or 1) * unit[m.group(2)])
+    return out
+
+
 def _slot(row, name):
     """The number in ONE NAMED SLOT of a rendered row, or `_Raised`.
 
@@ -4140,18 +4153,18 @@ def _slot(row, name):
         if m is None:
             raise ValueError(f"no {name!r} slot in {row[:90]!r}")
         raw = m.group(1)
-        return ([int(x) for x in raw.split("+")] if name == "spacings"
-                else int(raw))
+        return (_spacing_s(raw) if name == "spacings" else int(raw))
     return derived(_get)
 
 
 _T11_GOOD = ("x. Price plan from 7 s ago, for 48 hours ahead: day-ahead "
              "prices from the price feed, 132 prices over 33 hours, "
-             "36 published and 96 estimated, 900+3600 s apart")
+             "36 published and 96 estimated, one every 15 minutes or every "
+             "hour")
 _T11_SHIPPED_DEFECT = ("x. Price plan from 7 s ago, for 48 hours ahead: "
                        "day-ahead prices from the price feed, 132 prices over "
-                       "132 hours, 96 published and 36 estimated, 900+3600 s "
-                       "apart")
+                       "132 hours, 96 published and 36 estimated, one every "
+                       "15 minutes or every hour")
 # The slots divide into the ones a *Tariff*/​*Arbitrage* ROW carries and the
 # ones a REFUSAL sentence carries; each group is calibrated against its own
 # well-formed example, because a slot asked of the wrong kind of sentence is
@@ -4399,12 +4412,16 @@ check(f"AC, AND THE WHOLE OF DEFECT 4: 'trading is off' and 'trading is on "
       f"`off (arbitrage_enabled)` for both - naming an option that is `true` "
       f"in the options blob",
       _T11_OFF[0]["Arbitrage"] != _T11_ON_HELD[0]["Arbitrage"])
+# ⚠️ THE "Why" ROW OF THE SAME RENDER, NOT A SECOND READ OF `why_words`. Since
+# UX-10 the waiting sentence counts its seconds when it is read, so reading the
+# property again here, after the other renders above, could cross a second
+# ("1 second" in the row, "2 seconds" now) - CI run 953 on PR #141 did.
 check(f"...and the armed-but-held row carries the CONTROL LOOP'S OWN REASON "
-      f"({_T11_ON_HELD[1].why_words!r}), so the operator is told which input is "
+      f"({_T11_ON_HELD[0]['Why']!r}), so the operator is told which input is "
       f"missing rather than being sent to look at a switch that is already on. "
       f"The reason comes from main.py, not from this file",
-      _T11_ON_HELD[1].why_words
-      and _T11_ON_HELD[1].why_words in _T11_ON_HELD[0]["Arbitrage"])
+      _T11_ON_HELD[0]["Why"].startswith("A reading is missing")
+      and _T11_ON_HELD[0]["Why"] in _T11_ON_HELD[0]["Arbitrage"])
 check(f"...and a cycle that DID reach the step renders the strategy's own "
       f"sentence - {_T11_ON_OK[1].arb.explain()[:50]!r} - rather than a "
       f"re-derivation of it, which is the guarantee OPT-04 put on this row and "

goodwe_controller/test_price_forecast.py

@@ -66,6 +66,7 @@ import sys
 from named_absence import first, nth
 from datetime import datetime, timedelta, timezone
 
+from app import messages as _msg_fc
 from app import price as _price
 from app import price_forecast as _fc
 from app import static_tariff as _st
@@ -668,8 +669,10 @@ check("with neither a published hour nor a yesterday, the result is no_data - "
 check("...so it has no .points to iterate and no .get() to default out of",
       raises(lambda: _nothing.points, Absence)
       and raises(lambda: _nothing.get("points", []), Absence))
-check("...and its reason names §11.4 for an operator",
-      "§11.4" in _nothing.reason)
+check("...and its reason says the fixed tariff is used and there is no "
+      "trading (§11.4), in words an operator reads",
+      "fixed tariff is used" in _nothing.reason
+      and "no trading" in _nothing.reason)
 check("a naive `since` is refused rather than silently interpreted as UTC",
       raises(lambda: fill_from_yesterday(TODAY_PART, yesterday=YESTERDAY,
                                          since=datetime(2026, 1, 15),
@@ -745,9 +748,10 @@ check("...and the phase machine did not move: it is still idle, so the "
       _m.phase == IDLE)
 check("...and the reason names §8.3, the offending hour, and when the real "
       "price is expected",
-      "§8.3" in _gate_bad.reason
-      and bool(_first_prov) and _first_prov.isoformat() in _gate_bad.reason
-      and "14-16" in _gate_bad.reason)
+      "is only estimated" in _gate_bad.reason
+      and bool(_first_prov)
+      and _msg_fc.when(brussels(_first_prov)) in _gate_bad.reason
+      and "14:00 to 16:00" in _gate_bad.reason)
 
 # The positive arm, so the block above is discriminating rather than universal.
 _firm_long = series_of(hours_between(START,
@@ -772,7 +776,8 @@ _gate_none = begin_phase(_m3, START, PriceRead.no_data("the feed timed out"),
                          MAINTENANCE_DRAIN)
 check("no price data at all BLOCKS an irreversible action too - a missing "
       "price is not a cheap one (§11.4)",
-      _gate_none.kind == "blocked" and "§11.4" in _gate_none.reason
+      _gate_none.kind == "blocked"
+      and "missing price is not a cheap one" in _gate_none.reason
       and _m3.phase == IDLE)
 _short = series_of(DAY[:4], lambda u: t_price(brussels(u).hour),
                    PriceProduct.DAY_AHEAD, "generic_dayahead",

goodwe_controller/test_price_history.py

@@ -1020,7 +1020,7 @@ check("a store holding only the day before LAST answers no_data, not those "
       _y3.kind == "no_data")
 check(f"...and the reason names BOTH the date wanted and the dates held, so an "
       f"operator can see which it is: {why(_y3)!r}",
-      "2026-01-14" in why(_y3) and "2026-01-12" in why(_y3))
+      "14 Jan" in why(_y3) and "12 Jan" in why(_y3))
 
 _h4 = store()
 _ph.PriceHistory._remember(
@@ -1217,7 +1217,7 @@ json.dump({"version": SCHEMA + 99, "days": {}}, open(_p7, "w", encoding="utf-8")
 _h7 = PriceHistory(_p7)
 check("a file from a schema this build does not know is discarded rather than "
       "guessed at - its points might mean something else",
-      "schema" in (_h7.last_error or "")
+      "version" in (_h7.last_error or "")
       and _h7.yesterday(NOW).kind == "no_data")
 
 # A record whose points are malformed. THE DEFECT IS A DEFAULTED PRICE.
@@ -1270,7 +1270,7 @@ json.dump({"version": SCHEMA, "days": {
 _h14 = PriceHistory(_p14)
 check("a day record that is not a dict is DROPPED and REPORTED, and the rest "
       "of the file still loads - one bad record is not a bad file",
-      _h14.ok and "unusable day record" in (_h14.last_error or "")
+      _h14.ok and "unusable day" in (_h14.last_error or "")
       and sorted(_h14._days) == ["2026-01-13"])
 _w14 = derived(lambda: _h14.words)
 _y14 = derived(lambda: _h14.yesterday(NOW).kind)
@@ -1291,7 +1291,7 @@ for _shape in ("oops", [1, 2, 3], 7, None, {"points": "not a list"}):
     check(f"...and the same holds for a day record of {type(_shape).__name__} "
           f"{_shape!r}: dropped, reported, and every accessor answers "
           f"({_wX!r}, {_yX!r})",
-          _hX._days == {} and "unusable day record" in (_hX.last_error or "")
+          _hX._days == {} and "unusable day" in (_hX.last_error or "")
           and isinstance(_wX, str) and _yX == "no_data")
 
 _pF = os.path.join(tmpdir(), "price_history.json")
@@ -1300,7 +1300,7 @@ json.dump({"version": float(SCHEMA), "days": {}},
 check(f"a `version` of {float(SCHEMA)!r} is refused although it EQUALS "
       f"{SCHEMA} - a schema check that cannot tell 1 from 1.0 is one that "
       f"would not notice a writer this build has never met",
-      "schema" in (PriceHistory(_pF).last_error or ""))
+      "version" in (PriceHistory(_pF).last_error or ""))
 
 
 # --------------------------------------------------------------------------- #
@@ -1328,7 +1328,7 @@ check(f"...and a store holding a day names the DATE, the POINT COUNT and the "
       f"HOUR COUNT {words_of(_h_words)!r} - 'a cache exists' and 'the cache "
       f"holds yesterday, all 24 hours of it' are different facts, and only "
       f"the second says the horizon will be full tomorrow morning",
-      words_of(_h_words) == f"{YDAY_D} (24 prices over 24 hours)")
+      words_of(_h_words) == "24 prices over 24 hours for 14 Jan")
 
 # ⚠️ AND THE TWO NUMBERS ARE NOT THE SAME NUMBER - FCST-05's LOW. The row
 # shipped as `f"{d} ({_n_points(rec)} h)"`, which counts POINTS and prints them
@@ -1362,15 +1362,15 @@ check(f"...and the row reports BOTH, each under its own unit: {_qw!r}. "
       f"A day of 96 quarter-hourly prints is 96 points over 24 h, and the "
       f"figure that says whether tomorrow's fill has a whole day to carry is "
       f"the HOUR one",
-      _qw == f"{YDAY_D} (96 prices over 24 hours)")
+      _qw == "96 prices over 24 hours for 14 Jan")
 check(f"...and specifically the row does NOT say '96 h' {_qw!r} - a point "
       f"count wearing the hour's name is H1's defect, and this row is where "
       f"an operator would have read it",
-      isinstance(_qw, str) and "(96 h)" not in _qw and " (96 prices " in _qw)
+      isinstance(_qw, str) and "(96 h)" not in _qw and _qw.startswith("96 prices "))
 check(f"a file that only PARTLY loaded says so in the row {_w14!r}, or the "
       f"days it dropped read as days that were simply never written",
       isinstance(_w14, str) and (_h14.last_error or "") in _w14
-      and "2026-01-13" in _w14)
+      and "13 Jan" in _w14)
 check("NoHistory() has a sentence of its own rather than an empty cell",
       NoHistory().words == "not kept")
 check("...and `words` never raises, whatever the file holds. It is read once "
@@ -1546,8 +1546,8 @@ for _shape, _bad in _BAD_STARTS:
           f"{_wload!r}: ONE point held, and the row that is not a point named "
           f"rather than counted",
           isinstance(_wload, str)
-          and _wload.startswith(f"{TODAY_D} (1 price over 1 hour) [")
-          and "1 malformed point row(s) in" in _wload)
+          and _wload.startswith("1 price over 1 hour for 15 Jan [")
+          and "1 bad price in" in _wload)
     # ⚠️ AND THE TWO NOTES ARE GRADED APART, BECAUSE THEY MASK EACH OTHER
     # OTHERWISE (MUTATION.md TEST-16). `_usable_days()` records what it FOUND
     # at open and `_remember()` records what it DROPPED on the refresh; both
@@ -1562,22 +1562,22 @@ for _shape, _bad in _BAD_STARTS:
           f"'{TODAY_D} (1 h)' - the status row reporting a full cache while "
           f"every tariff refresh was dying on it",
           isinstance(_wafter, str)
-          and "malformed point row(s) dropped from" in _wafter
-          and TODAY_D in _wafter)
+          and "bad price dropped from" in _wafter
+          and "15 Jan" in _wafter)
     check(f"...and the row MOVED from what was found to what was dropped "
           f"{_wload.split('[')[-1]!r} -> {_wafter.split('[')[-1]!r}, so the "
           f"two notes are not one note read twice",
           isinstance(_wload, str) and isinstance(_wafter, str)
-          and "malformed point row(s) in" in _wload
-          and "malformed point row(s) in" not in _wafter
-          and "malformed point row(s) dropped from" not in _wload)
+          and "bad price in" in _wload
+          and "bad price in" not in _wafter
+          and "bad price dropped from" not in _wload)
     # ...and a SECOND refresh over the same store is clean, which is the state
     # a restarted add-on comes up in.
     _hM2 = PriceHistory(_pM)
     check(f"...and the store reopened from that file is CLEAN: the whole day "
           f"held and nothing to report {words_of(_hM2)!r}, so the note clears "
           f"itself rather than becoming permanent furniture",
-          words_of(_hM2) == f"{TODAY_D} ({_want} prices over {_want} hours)"
+          words_of(_hM2) == f"{_want} prices over {_want} hours for 15 Jan"
           and _hM2.last_error is None)
 
 # ...and the shipped path, end to end, through the caller that catches
@@ -1641,7 +1641,7 @@ print("5d. FCST-06 - the OTHER way to be a store that cannot persist")
 # read-only and again on a full tmpfs:
 #
 #     last_error = 'could not write ([Errno 30] Read-only file system)'
-#     words      = '2026-01-14 (24 prices over 24 hours); 2026-01-15 (24 points
+#     words      = '2026-01-14 (24 points over 24 h); 2026-01-15 (24 points
 #                   over 24 h) [could not write (...)]'
 #     yesterday()= series, 24 points
 #     ON DISK    = {}                         <- and gone on the next restart
@@ -1701,7 +1701,7 @@ check(f"...and `words` and `yesterday()` AGREE about that store "
       f"{_h16.words[:44]!r}: neither names a day the file does not hold, and "
       f"both name the write failure. They disagreed - `words` printed two "
       f"full days BESIDE the error while `yesterday()` answered 24 points",
-      YDAY_D not in _h16.words and TODAY_D not in _h16.words
+      "14 Jan" not in _h16.words and "15 Jan" not in _h16.words
       and "could not write" in _h16.words
       and _y16.kind == "no_data" and "could not write" in why(_y16))
 check(f"...and it DEGRADES rather than raising: the carry still returned a "

goodwe_controller/test_pv.py

@@ -697,13 +697,24 @@ print(f"    {len(APP)} modules under app/; TEL-11 material is in: {_touch}")
 check(f"PRECONDITION: the scan found the whole package, not a subset - "
       f"{len(APP)} modules", len(APP) >= 25 and "control.py" in
       [f.name for f in APP])
-check("⭐ EXACTLY THREE MODULES CAN SEE THE MATERIAL: `pv.py` (the reader), "
-      "`main.py` (the read and the two operator surfaces) and `mqtt.py` (the "
-      "publication). `control.py`, `arbiter.py`, `allocator.py`, `peakguard.py`, "
-      "`arbitrage.py`, `maintenance.py`, `clamp.py`, `freeze.py`, "
-      "`watchdog.py`, `delivery.py` and `circulation.py` do not mention it in "
-      "any spelling, comments included",
-      _touch == ["main.py", "mqtt.py", "pv.py"])
+# UX-13 adds the settings surface: labels (messages.py), a settings warning
+# (validate.py) and the page's layout and derivation (uilayout.py, uimodel.py).
+# None of them decides anything, so the decision modules stay excluded.
+# UX-13 P1 adds homeview.py, the Home screen's read-only view: its House tile
+# is grid + solar + battery, and it shows nothing without a solar reading.
+_DECIDERS = ("control.py", "arbiter.py", "allocator.py", "peakguard.py",
+             "arbitrage.py", "maintenance.py", "clamp.py", "freeze.py",
+             "watchdog.py", "delivery.py", "circulation.py")
+check("⭐ ONLY THE READER, THE PUBLISHER AND THE SETTINGS SURFACE SEE THE "
+      "MATERIAL: `pv.py` (the reader), `main.py` (the read and the two operator "
+      "surfaces), `homeview.py` (the Home screen's view), `mqtt.py` (the "
+      "publication), and `messages.py`, `validate.py`, `uilayout.py` and "
+      "`uimodel.py` (settings). "
+      f"{', '.join(_DECIDERS)} do not mention it in any spelling, comments "
+      "included",
+      _touch == ["homeview.py", "main.py", "messages.py", "mqtt.py", "pv.py",
+                 "uilayout.py", "uimodel.py", "validate.py"]
+      and not set(_DECIDERS) & set(_touch))
 # habit 4 in the instrument: a scanner that cannot go red is not a scanner.
 check("...and the scan CAN go red - a module body with the material in it is "
       "caught, so the green above is the tree speaking and not the scanner "

goodwe_controller/test_refusal.py

@@ -0,0 +1,475 @@
+"""Runnable check for SAFETY-52.  `python3 test_refusal.py`
+
+A battery that refuses to give power (the BMS cut-out) used to leave the
+command standing at its last ask for hours: +5000 W for 11.87 h on 2026-09-06,
++1940 W for 3 h 55 m on the bus on 2026-09-19. Now a refused direction is held
+at 0 W, a 200 W probe asks every 15 minutes, and the refusal ends on charge, on
+an answered probe, on stop/start and when another writer takes the wire.
+DECISIONS/SAFETY-52 has the record and the replay figures.
+
+Mutating the modules this file grades? Purge `__pycache__` first, or run
+`tools/mutation_run.sh`, which does - see MUTATION.md.
+
+Parts 1-5 drive the REAL `Controller` (read_inputs + cycle, the real
+SAFETY-37/57 gate) against a scripted battery whose reading stands at exactly
+-4 W for any request >= -4 W at the cut-out, and follows otherwise. Time is the
+`now_mono` handed to `read_inputs()`, so 12 hours run in seconds. `OLD` runs the
+same fixture with `refused=None` forced into `compute()` - release/1.0's law -
+so every "new" figure is shown beside the one it replaces. Part 4 also runs
+`compute()` alone, as the bus saw 09-19 before the gate existed.
+
+Mutations, each on a copy of this tree purged of `__pycache__`, graded with
+`python3 -B` over test_refusal, test_control, test_clamp, test_telemetry and
+test_messages (MUTATION.md). Reds are failing checks, on this tree:
+
+  #   mutation                                                 reds
+  --  -------------------------------------------------------  ---------------
+  R1  control.py: the engage `if` -> `if False and ...`          8 here + 1 clamp
+      (release/1.0's behaviour)
+  R2  control.py: the exit on the other direction removed        1
+  R3  control.py: the exit on an answered probe removed          2
+  R4  control.py: `PROBE_W = 300.0`, above the gate's 250 W       4
+  R5  control.py: the hold keeps the old target, not 0 W          4
+  R6  main.py: `_refusal_from_stale()` returns at once           1
+  R7  main.py: another writer no longer ends the refusal         1
+  R8  main.py: stop/start no longer ends the refusal             1
+  R9  main.py: the probe window never opens                      4
+  R10 main.py: seed from a stale stop below `saturation_w` again,  1
+      not below REFUSED_BELOW_W (review of #141). The same mutation
+      in control.py's engage clause SURVIVES, and that is expected:
+      the delivery exit (R11) ends such a refusal in the same cycle.
+  R11 control.py: only an answered PROBE ends the refusal          2
+      (`and probe` back in the delivery exit; review of #141)
+"""
+
+import asyncio
+import sys
+from datetime import datetime, timedelta, timezone
+
+from app import control, freshness
+from app.control import PROBE_EVERY_S, PROBE_S, PROBE_W, REFUSED, PROBING
+from app.main import Controller, why_key
+from app.arbiter import Claim
+from app import messages
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+LIVE = {"max_w": 5000.0, "gain": 0.6, "slew_w": 400.0, "target_grid_w": -10.0,
+        "deadband_w": 15, "step_w": 10}
+TICK = 5.0            # the meter's measured median tick (replay_recorded_loop)
+CUT_W = -4.0          # what the register reads at the cut-out, 2026-09-06
+H = 3600.0
+BASE = datetime(2026, 9, 6, 19, 30, tzinfo=timezone.utc)
+
+
+class _Store:
+    def __init__(self):
+        self.data = {}
+
+    def set(self, *a):
+        pass
+
+    def get_time(self, *a):
+        return None
+
+
+class _Pub:
+    enabled = False
+
+    def publish(self, values):
+        pass
+
+    def close(self):
+        pass
+
+
+class _Hass:
+    """House load, and a battery that follows unless `cut(t)` says it refuses.
+
+    At the cut-out the reading is exactly CUT_W for any request >= CUT_W (a flat
+    register, which is what arms or does not arm the stale-reading gate). A
+    charge request is followed: the pack accepts charge at the floor.
+    `cap(t)` limits discharge while not cut (the 09-06 pack gave 4570 W at 10 %).
+    """
+
+    def __init__(self, load, cut, cap=lambda t: 1e9):
+        self.load, self.cut, self.cap = load, cut, cap
+        self.t = 0.0
+        self.cmd = 0.0
+        self.writes = []
+
+    def batt(self):
+        if self.cut(self.t) and self.cmd >= CUT_W:
+            return CUT_W
+        return float(round(min(self.cmd, self.cap(self.t))))
+
+    async def limits(self, entity):
+        return (-LIVE["max_w"], LIVE["max_w"], 1.0)
+
+    async def number(self, entity, invert=False):
+        b = self.batt()
+        return {"sensor.grid": self.load(self.t) - b, "sensor.soc": 9.0,
+                "sensor.batt": b}.get(entity)
+
+    async def set_number(self, entity, value):
+        self.writes.append((self.t, float(value)))
+        self.cmd = float(value)
+        return True
+
+    async def call(self, *a):
+        return True
+
+
+def run(load, cut, dur, cap=lambda t: 1e9, old=False, events=None):
+    """Real cycles every TICK seconds of `now_mono`. `events[t] = fn(c)` pokes
+    the controller (stop, start, another writer) at that instant.
+
+    Returns [(t, grid, batt, setpoint, i_w, loop_reason, batt_refused)], the
+    number of gate trips, and the controller."""
+    async def go():
+        hass = _Hass(load, cut, cap)
+        c = Controller(dict(
+            {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+             "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+             "meter_source": "off", "heartbeat_s": 10, "stale_input_s": 15},
+            **LIVE), hass, _Store(), _Pub(), stop=asyncio.Event())
+        c.auto = True
+        c.dev_min, c.dev_max = -LIVE["max_w"], LIVE["max_w"]
+        import app.main as m
+        real, real_dt = m.compute, m.datetime
+        clock = [0.0]
+
+        class _DT(real_dt):
+            """`cycle()`'s wall clock follows `now_mono`, so the 15 s input hold
+            and the gate's release run in simulated seconds too."""
+            @classmethod
+            def now(cls, tz=None):
+                return BASE + timedelta(seconds=clock[0])
+
+        m.datetime = _DT
+        if old:
+            m.compute = lambda *a, **k: real(*a, **dict(k, refused=None))
+        rows, trips, was = [], 0, False
+        try:
+            t = 0.0
+            while t < dur:
+                hass.t = clock[0] = t
+                for et, fn in list((events or {}).items()):
+                    if et <= t:
+                        fn(c)
+                        del events[et]
+                await c.read_inputs(now_mono=t)
+                stale = c.inverters[0].batt_fresh.stale
+                trips += stale and not was
+                was = stale
+                await c.cycle()
+                rows.append((t, hass.load(t) - hass.batt(), hass.batt(),
+                             hass.cmd, c.i_w, c.loop_reason, c.batt_refused))
+                t += TICK
+        finally:
+            m.compute, m.datetime = real, real_dt
+        return rows, trips, c
+    return asyncio.run(go())
+
+
+def at(rows, t):
+    return min(rows, key=lambda r: abs(r[0] - t))
+
+
+def longest_hold_h(rows, floor_w=250.0, until=None):
+    """Longest run of one identical request at or above `floor_w`, in hours."""
+    best = cur = 0.0
+    last = None
+    for r in rows:
+        if until is not None and r[0] >= until:
+            break
+        cur = cur + TICK if (r[3] == last and abs(r[3]) >= floor_w) else 0.0
+        last = r[3]
+        best = max(best, cur)
+    return best / H
+
+
+# ==============================================================================
+print("1. the 09-06 shape: a load step takes the request to 5000 W, the battery "
+      "cuts out, the load ends")
+# ==============================================================================
+def load906(t):
+    return 1020 if t < 60 else 4800 if t < 162 else 940 if t < 11.9 * H else -600
+
+
+def cut906(t):
+    return t >= 132
+
+
+def cap906(t):
+    return 4570.0
+
+
+old906, otrips906, _ = run(load906, cut906, 12.2 * H, cap906, old=True)
+new906, ntrips906, c906 = run(load906, cut906, 12.2 * H, cap906)
+for name, rows, tr in (("old", old906, otrips906), ("new", new906, ntrips906)):
+    print(f"    {name}: request at 2 min {at(rows, 120)[3]:+.0f} W, at 6 h "
+          f"{at(rows, 6 * H)[3]:+.0f} W (i_w {at(rows, 6 * H)[4]:+.0f}), longest "
+          f"hold {longest_hold_h(rows):.2f} h, gate trips {tr}")
+check("PRECONDITION: the old law holds +5000 W for the whole night on this "
+      "fixture, as it did on 2026-09-06 - the fixture reproduces the card",
+      at(old906, 6 * H)[3] == 5000.0 and longest_hold_h(old906) > 11.5)
+check("the request reaches the rail before the cut, so the new law starts from "
+      "the same place", at(new906, 120)[3] == 5000.0)
+t0 = next((r[0] for r in new906 if r[5] == REFUSED), None)
+check(f"after the cut the battery-refuses hold takes the request to 0 W within "
+      f"about a minute (at t={t0})", t0 is not None and 132 < t0 <= 132 + 90
+      and at(new906, t0)[3] == 0.0)
+check("...and it stays refused overnight, with the integrator at 0, and no "
+      "request of 250 W or more stands for longer than one probe interval",
+      at(new906, 6 * H)[6] == 1 and at(new906, 6 * H)[4] == 0.0
+      and longest_hold_h(new906, until=11.9 * H) < PROBE_EVERY_S / H)
+check(f"...and the stale-reading gate does not cycle: {ntrips906} trips in "
+      f"12 hours (the old law's latch also kept it quiet: {otrips906})",
+      ntrips906 == 0)
+morning = [r for r in new906 if r[0] >= 11.9 * H + 60]
+check("when solar makes the grid export, the refusal ends and the battery "
+      "charges - the exit on the other direction",
+      morning and morning[-1][6] == 0 and morning[-1][3] < -400)
+
+# ==============================================================================
+print("2. the probe: 200 W every 15 minutes, below the gate's 250 W")
+# ==============================================================================
+probes = []
+for r in new906:
+    if r[3] == PROBE_W and (not probes or r[0] - probes[-1][1] > TICK):
+        probes.append([r[0], r[0]])
+    elif r[3] == PROBE_W:
+        probes[-1][1] = r[0]
+starts = [p[0] for p in probes]
+gaps = [b - a for a, b in zip(starts, starts[1:])]
+print(f"    {len(probes)} probes, first at {starts[0] / 60 if starts else 0:.1f} "
+      f"min, gaps {sorted(set(round(g) for g in gaps))} s, lengths "
+      f"{sorted(set(round(p[1] - p[0] + TICK) for p in probes))} s")
+check("the probe asks exactly PROBE_W, which is below the stale-reading gate's "
+      "threshold, so a probe can never arm it",
+      PROBE_W < freshness.MOVE_W and all(r[3] in (0.0, PROBE_W)
+                                         for r in new906 if r[6] == 1))
+check("there is a probe every 15 minutes through the night (at least 40 in "
+      "11.8 hours), each about 34 s long",
+      len(probes) >= 40 and all(PROBE_EVERY_S <= g <= PROBE_EVERY_S + PROBE_S
+                                + 2 * TICK for g in gaps)
+      and all(PROBE_S - TICK <= p[1] - p[0] + TICK <= PROBE_S + TICK
+              for p in probes))
+check("...and a probe reads as a probe on the loop's own reason row",
+      any(r[5] == PROBING for r in new906))
+
+# ==============================================================================
+print("3. recovery with no sign change: the battery gives power again at 2 h")
+# ==============================================================================
+def cut_rec(t):
+    return 132 <= t < 2 * H
+
+
+oldr, _, _ = run(load906, cut_rec, 2.6 * H, cap906, old=True)
+newr, _, crec = run(load906, cut_rec, 2.6 * H, cap906)
+after_o = [r for r in oldr if 2 * H <= r[0] < 2 * H + 600]
+after_n = [r for r in newr if 2 * H <= r[0] < 2.6 * H]
+exp_o = sum(max(0.0, -r[1]) * TICK for r in after_o) / 3600
+exp_n = sum(max(0.0, -r[1]) * TICK for r in after_n) / 3600
+print(f"    old: worst grid {min(r[1] for r in after_o):+.0f} W, export "
+      f"{exp_o:.0f} Wh; new: worst grid {min(r[1] for r in after_n):+.0f} W, "
+      f"export {exp_n:.0f} Wh")
+check("PRECONDITION: the old law answers a recovering battery with its "
+      "standing +5000 W and exports kilowatts into a 940 W house",
+      min(r[1] for r in after_o) < -3000)
+check("the new law never exports more than the probe while it waits, and the "
+      "answered probe ends the refusal so control resumes",
+      min(r[1] for r in after_n) > -PROBE_W - 50
+      and after_n[-1][6] == 0 and abs(after_n[-1][1] - (-10)) < 100)
+check("...and the event log says the probe was answered",
+      any("BATTERY REFUSES ENDED: the probe was answered" in e
+          for e in crec.events))
+
+# ==============================================================================
+print("4. the 09-19 shape: a stale-reading stop on a frozen ~0 W reading "
+      "is a refusal")
+# ==============================================================================
+# The request steps +1540 -> +1940 and more as the battery cuts out mid-ramp:
+# the request moves after the reading went flat, so the gate trips before the
+# hold's 12 cycles - the ~70 s cycle SAFETY-59 measured. The trip seeds the hold.
+def load919(t):
+    return 1530 if t < 60 else 2400 if t < 1800 else 900 if t < 4 * H else -600
+
+
+def cut919(t):
+    return t >= 65
+
+
+def run919(old):
+    return run(load919, cut919, 4.2 * H, old=old)
+
+
+old919, otr919, _ = run919(True)
+new919, ntr919, c919 = run919(False)
+print(f"    old: gate trips {otr919}, longest hold {longest_hold_h(old919):.2f} h;"
+      f" new: gate trips {ntr919}, longest hold {longest_hold_h(new919):.2f} h")
+check("PRECONDITION: on the old law the gate trips over and over all night "
+      "(the SAFETY-59 cycle) or the request stands for hours",
+      otr919 > 20 or longest_hold_h(old919) > 1.0)
+check("the new law stops after at most two trips and holds 0 W, and the event "
+      "log says the battery refuses",
+      ntr919 <= 2 and at(new919, 2 * H)[3] in (0.0, PROBE_W)
+      and any("BATTERY REFUSES" in e for e in c919.events))
+
+# The same shape through `compute()` alone, as the bus saw it on 2026-09-19
+# before the gate existed: +1540 -> +1940, then a battery giving nothing.
+T = control.Tuning(**LIVE)
+res = {}
+for name, carry in (("old", None), ("new", 0)):
+    # sat_count 2: the +1540 and +1940 cycles were already short (the plan)
+    prev, i_w, sat, ref, cmds = 1940.0, 2340.0, 2, carry, []
+    for _ in range(2000):              # ~2.8 h at 5 s
+        d = control.compute(prev, 1950.0, CUT_W, T, sat, i_w, refused=ref)
+        prev, i_w, sat, ref = d.target_w, d.i_w, d.sat_count, d.refused
+        cmds.append(prev)
+    res[name] = cmds
+print(f"    compute() alone: old stands at {res['old'][-1]:+.0f} W "
+      f"({sum(v == 1940.0 for v in res['old'])} of 2000 cycles at +1940 W), "
+      f"new at {res['new'][-1]:+.0f} W from cycle "
+      f"{res['new'].index(0.0) if 0.0 in res['new'] else None}")
+check("PRECONDITION: without the gate the old law parks at +1940 W, the 7 065 "
+      "identical writes the bus recorded", set(res["old"]) == {1940.0})
+check("...and the new law holds 0 W within SETTLE_CYCLES cycles",
+      res["new"].index(0.0) < control.SETTLE_CYCLES
+      and set(res["new"][control.SETTLE_CYCLES:]) == {0.0})
+
+# ==============================================================================
+print("5. the other exits: stop, start, another writer")
+# ==============================================================================
+def stop(c):
+    c.auto = False
+
+
+def start(c):
+    c.auto = True
+
+
+rows, _, c = run(load906, cut906, 1200, cap906, events={600.0: stop,
+                                                         700.0: start})
+check("stopping control ends the refusal, and starting again begins from "
+      "nothing refused", at(rows, 590)[6] == 1 and at(rows, 650)[6] == 0
+      and at(rows, 705)[6] == 0)
+
+
+def other_writer(c):
+    c.loop_w = 1234.0      # the arbiter gave the wire something the loop did not ask
+
+
+rows, _, c = run(load906, cut906, 900, cap906, events={600.0: other_writer})
+check("another writer on the wire ends the refusal (the arbiter reseed)",
+      at(rows, 590)[6] == 1 and at(rows, 605)[6] == 0)
+
+# ==============================================================================
+print("5b. review of #141: a pack that gives SOME power, and a reading that is "
+      "only late, are not a refusal")
+# ==============================================================================
+# A pack derated to 100-499 W (cold, BMS taper) gives what it can against a
+# larger ask. Engaging below `saturation_w` (500 W) held it at 0 W for ~93 % of
+# the time; "gives nothing" is below the probe's own answer.
+# `compute()` alone: through the Controller the stale-reading gate trips on the
+# flat 300 W first, and that fixture then passes whatever this threshold is.
+def derated(carry, cap_w=300.0, n=1800):
+    prev, i_w, sat, ref, gave, held = 0.0, 0.0, 0, carry, 0.0, 0
+    b = 0.0
+    for _ in range(n):                                   # 2.5 h at 5 s
+        d = control.compute(prev, 2000.0 - b, b, T, sat, i_w, refused=ref)
+        prev, i_w, sat, ref = d.target_w, d.i_w, d.sat_count, d.refused
+        held += bool(ref)
+        b = max(0.0, min(prev, cap_w))                   # one tick late
+        gave += b
+    return gave / n, held
+
+
+T = control.Tuning(**LIVE)
+gave_old, _ = derated(None)
+gave_new, held_new = derated(0)
+print(f"    pack derated to 300 W: old law {gave_old:.0f} W average, new "
+      f"{gave_new:.0f} W, held as refusing on {held_new} cycles")
+check("a pack that gives a steady 300 W against a 2000 W ask is never held at "
+      "0 W as refusing, and keeps giving what the old law got from it",
+      held_new == 0 and gave_new == gave_old and gave_old > 290.0)
+
+
+def lagging(tick, dead_s=6.0, publish_s=10.0, phase_s=5.0, dur=600.0):
+    """`compute()` on a HEALTHY pack whose reading lags: it follows the command
+    of `dead_s` ago, published every `publish_s`. A 1 s meter (`meter_poll_s`
+    1) makes SETTLE_CYCLES only 12 s, shorter than that lag."""
+    prev, i_w, sat, ref, hist, reg, pub = 0.0, 0.0, 0, 0, [], 0.0, -phase_s
+    held = engaged = 0
+    t = 0.0
+    while t < dur:
+        then = [c for tc, c in hist if tc <= t - dead_s]
+        b = then[-1] if then else 0.0
+        if t - pub >= publish_s:
+            reg, pub = b, t
+        d = control.compute(prev, (3000.0 if t >= 10 else 0.0) - b, reg, T,
+                            sat, i_w, refused=ref)
+        engaged += bool(d.refused) and not ref
+        prev, i_w, sat, ref = d.target_w, d.i_w, d.sat_count, d.refused
+        hist.append((t, prev))
+        held += tick * bool(ref)
+        t += tick
+    return engaged, held
+
+
+lag1 = lagging(1.0)
+print(f"    1 s meter, healthy pack with a late reading: engaged {lag1[0]} "
+      f"time(s), held {lag1[1]:.0f} s")
+check("a healthy pack whose reading is merely late is let go as soon as the "
+      "reading shows it delivering - not held until the next probe",
+      lag1[1] <= 10.0)
+
+
+async def _seed(held_w):
+    """`_refusal_from_stale()` on a unit standing at +2000 W, frozen."""
+    c = Controller(dict(
+        {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+         "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+         "meter_source": "off"}, **LIVE),
+        _Hass(lambda t: 0.0, lambda t: False), _Store(), _Pub(),
+        stop=asyncio.Event())
+    c.auto, c.sat_count = True, c.tuning.saturation_cycles
+    inv = c.inverters[0]
+    inv.last_write, inv.batt_fresh.held = 2000.0, held_w
+    c._refusal_from_stale(inv, 100.0)
+    return c.batt_refused
+
+
+check("a stale-reading stop on a register standing at 300 W is not a refusal "
+      "(it gives something), and one at -4 W is",
+      asyncio.run(_seed(300.0)) == 0 and asyncio.run(_seed(CUT_W)) == 1)
+d = control.compute(0.0, 1500.0, 1400.0, T, 0, 0.0, refused=1, probe=False)
+check("...i.e. a held direction that reads 100 W or more ends the refusal "
+      "without waiting for a probe", d.refused == 0)
+
+# ==============================================================================
+print("6. words")
+# ==============================================================================
+w = messages.why(why_key("loop", [Claim.set("loop", 0, 0.0, REFUSED)]), 0.0)
+wp = messages.why(why_key("loop", [Claim.set("loop", 0, PROBE_W, PROBING)]),
+                  PROBE_W)
+print(f"    {w!r} / {wp!r}")
+check("the page's Why line says the battery refuses, not 'Keeping the grid "
+      "near zero: 0 W'", w == "The battery refuses to give power: 0 W")
+check("...and a probe says what it is", wp.startswith("Testing if the battery"))
+check("...and an ordinary loop cycle still reads as the loop",
+      why_key("loop", [Claim.set("loop", 0, 10.0, "tracking")]) == "loop")
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED: " + ", ".join(fails))
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_refusal_units.py

@@ -0,0 +1,537 @@
+"""Runnable check for SAFETY-73.  `python3 test_refusal_units.py`
+
+SAFETY-52 per inverter. With two or more inverters, a battery that refuses
+(gives < 100 W for 12 cycles and 22 s while asked > 200 W, or trips the stale-reading
+gate on a ~0 W reading) is closed in that direction by its own P_SAFETY limit,
+so the allocator hands its share to the others. It is probed at 200 W every
+15 minutes, one inverter at a time. When every inverter refuses the same way
+the site holds 0 W. When a refusal ends the site target restarts from the watts
+on the wire. DECISIONS/SAFETY-73 has the record.
+
+Drives the REAL `Controller` (read_inputs + cycle, the real freshness gate,
+allocator, OPT-09 pack claim and SAFETY-42 detector) with two inverters in
+simulated time. At the cut-out a battery reads -4 W for any request >= -4 W
+and accepts charge. Two register shapes: FLAT at -4 W (the 09-06 capture) and
+JITTER +-3 W (the gate cannot arm). `OLD` runs the same fixture with the
+per-unit refusal switched off, which is 652097a's behaviour at N>1.
+
+Mutations (MUTATION.md, `python3 -B`, copies purged of `__pycache__`), graded
+over this file / test_delivery / test_refusal. Every one is red here:
+
+  #    mutation                                                   reds
+  ---  ---------------------------------------------------------  -------
+  U1   main.py: the per-unit engage clause never fires              7/2/0
+  U2   main.py: the N>1 stale-reading seed returns at once          14/0/0
+  U3   main.py: no `refused` claim is filed                         13/2/0
+  U4   main.py: a probe never pins (always the closed limit)        7/0/0
+  U5   main.py: a probe pin stands whatever the site target         1/0/0
+  U6   main.py: no reseed of the site target when a refusal ends    1/0/0
+  U7   main.py: no site hold when every inverter refuses            2/0/0
+  U8   main.py: the other-direction exit removed (charge counter)   1/0/0
+  U9   main.py: the delivery exit removed                           3/0/0
+  U10  main.py: probes are no longer one at a time                  1/0/0
+  U11  main.py: the above-cut-out WARNING condition inverted        1/0/0
+  U12  main.py: SAFETY-42's account no longer sees a small ask      1/0/0
+  U13  main.py: a unit engages above `saturation_w`, not PROBE_W    1/0/0
+  U14  main.py: the evidence need not span REFUSED_SPAN_S (review)  1/0/0
+  U15  main.py: the WARNING also for a refusal to take (review)     1/0/0
+
+On 652097a itself this file stops at the first sample (`Inverter` has no
+`refused`); its OLD arms reproduce that tree's N>1 behaviour instead, and
+every PRECONDITION line is graded against them.
+"""
+
+import asyncio
+import logging
+import sys
+from datetime import datetime, timedelta, timezone
+
+from app import control
+from app.control import PROBE_EVERY_S, PROBE_S, PROBE_W
+from app.main import Controller
+from app.arbiter import P_LOOP, P_PEAK, P_SAFETY, Claim, resolve
+import app.main as m
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+TICK = 5.0
+CUT_W = -4.0
+FULL_W = 40.0
+H = 3600.0
+BASE = datetime(2026, 9, 6, 19, 30, tzinfo=timezone.utc)
+UNITS = ("a", "b")
+
+
+class _Store:
+    def __init__(self):
+        from app.store import DEFAULTS
+        self.data = dict(DEFAULTS)
+
+    def set(self, k, v):
+        self.data[k] = v
+
+    def get_time(self, *a):
+        return None
+
+
+class _Pub:
+    enabled = False
+
+    def publish(self, *a, **k):
+        pass
+
+    def close(self):
+        pass
+
+
+class _Hass:
+    """A house, one meter, and two batteries that follow unless cut out.
+
+    `lag` (review): (dead s, publish s). Each battery reading then shows the
+    power of `dead` s before its last publish; the power itself and the meter
+    follow at once. `full[u](t)`: that battery takes at most FULL_W of charge.
+    """
+
+    def __init__(self, load, cut, soc, jitter, lag=None, full=None):
+        self.load, self.cut, self.soc, self.jitter = load, cut, soc, jitter
+        self.lag, self.full = lag, full or {}
+        self.cmd = {u: 0.0 for u in UNITS}
+        self.hist = {u: [(-1e18, 0.0)] for u in UNITS}
+        self.t = 0.0
+
+    def power(self, u, t=None):
+        t = self.t if t is None else t
+        c = next((v for tt, v in reversed(self.hist[u]) if tt <= t), 0.0)
+        if self.cut[u](t) and c >= CUT_W:
+            if self.jitter:
+                return CUT_W + ((int(t / TICK) % 3) - 1) * 3.0
+            return CUT_W
+        if u in self.full and self.full[u](t) and c < -FULL_W:
+            return -FULL_W
+        return float(round(c))
+
+    def batt(self, u):
+        if self.lag is None:
+            return self.power(u)
+        dead, pub = self.lag
+        return self.power(u, (self.t // pub) * pub - dead)
+
+    def grid(self):
+        return self.load(self.t) - sum(self.power(u) for u in UNITS)
+
+    async def limits(self, e):
+        return (-2000.0, 2000.0, 1.0)
+
+    async def call(self, *a):
+        return True
+
+    async def number(self, e, invert=False):
+        if e == "sensor.grid":
+            return self.grid()
+        u = e[-1]
+        if e.startswith("sensor.soc"):
+            v = self.soc[u]
+            return v(self.t) if callable(v) else v
+        if e.startswith("sensor.batt"):
+            return self.batt(u)
+        return None
+
+    async def set_number(self, e, v):
+        self.cmd[e[-1]] = float(v)
+        self.hist[e[-1]].append((self.t, float(v)))
+        return True
+
+
+def _off(c):
+    """652097a's N>1 behaviour: nothing refuses per unit."""
+    c._unit_refusals = lambda: None
+    c._unit_refusal_start = lambda *a, **k: None
+
+
+def run(load, cut, dur, *, soc=None, jitter=False, old=False, events=None,
+        extra=None, tick=None, lag=None, full=None):
+    """Real cycles every TICK of simulated time. Rows are dicts per cycle."""
+    async def go():
+        hass = _Hass(load, cut, soc or {"a": 50.0, "b": 50.0}, jitter, lag,
+                     full)
+        dt = tick or TICK
+        inv = [{"name": f"inverter-{u}", "setpoint_entity": f"number.sp_{u}",
+                "soc_entity": f"sensor.soc_{u}",
+                "batt_entity": f"sensor.batt_{u}",
+                "max_w": 2000, "bms_soc_floor": 10} for u in UNITS]
+        o = {"meter_entity": "sensor.grid", "meter_source": "off",
+             "inverters": inv, "gain": 0.6, "slew_w": 400,
+             "target_grid_w": -10, "deadband_w": 15, "step_w": 10,
+             "heartbeat_s": 10, "stale_input_s": 15, "auto_start": True}
+        o.update(extra or {})
+        c = Controller(o, hass, _Store(), _Pub(), stop=asyncio.Event())
+        for i in c.inverters:
+            i.dev_min, i.dev_max = -2000.0, 2000.0
+        c.auto = True
+        if old:
+            _off(c)
+        real_dt = m.datetime
+        clock = [0.0]
+
+        class _DT(real_dt):
+            @classmethod
+            def now(cls, tz=None):
+                return BASE + timedelta(seconds=clock[0])
+
+        m.datetime = _DT
+        rows = []
+        trips = {u: 0 for u in UNITS}
+        was = {u: False for u in UNITS}
+        pending = dict(events or {})
+        try:
+            t = 0.0
+            while t < dur:
+                hass.t = clock[0] = t
+                for et in sorted(pending):
+                    if et <= t:
+                        pending.pop(et)(c)
+                await c.read_inputs(now_mono=t)
+                for u, i in zip(UNITS, c.inverters):
+                    s = i.batt_fresh.stale
+                    trips[u] += s and not was[u]
+                    was[u] = s
+                await c.cycle()
+                rows.append(dict(
+                    t=t, grid=hass.grid(), site=c.target, reason=c.loop_reason,
+                    a=hass.cmd["a"], b=hass.cmd["b"],
+                    ra=c.inverters[0].refused, rb=c.inverters[1].refused,
+                    da=c.inverters[0].delivery_wd.tripped,
+                    db=c.inverters[1].delivery_wd.tripped))
+                t += dt
+        finally:
+            m.datetime = real_dt
+        return rows, trips, c
+    return asyncio.run(go())
+
+
+def after(rows, t0, t1=None):
+    return [r for r in rows if r["t"] >= t0 and (t1 is None or r["t"] < t1)]
+
+
+def mean(rows, k):
+    return sum(r[k] for r in rows) / len(rows) if rows else float("nan")
+
+
+def never(t):
+    return False
+
+
+def cut_at(t0, t1=None):
+    return lambda t: t >= t0 and (t1 is None or t < t1)
+
+
+def probes(rows, k):
+    """Start times of runs where refused unit `k` is asked exactly PROBE_W."""
+    out, prev = [], False
+    for r in rows:
+        on = abs(r[k]) == PROBE_W and r["r" + k] != 0
+        if on and not prev:
+            out.append(r["t"])
+        prev = on
+    return out
+
+
+SHAPES = (("flat", False), ("jitter", True))
+
+# ==============================================================================
+print("1. case a: house 3000 W, both give power, A cuts out at 120 s")
+# ==============================================================================
+for shape, jit in SHAPES:
+    new, ntr, cn = run(lambda t: 3000.0, {"a": cut_at(120), "b": never}, H,
+                       jitter=jit)
+    old, otr, _ = run(lambda t: 3000.0, {"a": cut_at(120), "b": never}, H,
+                      jitter=jit, old=True)
+    tail_n, tail_o = after(new, 300), after(old, 300)
+    held = [r for r in tail_n if abs(r["a"]) != PROBE_W]
+    print(f"    {shape}: old B {mean(tail_o, 'b'):.0f} W grid "
+          f"{mean(tail_o, 'grid'):+.0f} W trips A {otr['a']}; new B "
+          f"{mean(tail_n, 'b'):.0f} W grid {mean(tail_n, 'grid'):+.0f} W "
+          f"trips A {ntr['a']}")
+    check(f"{shape}: PRECONDITION: on the old law B never takes over (mean "
+          f"under 1950 W) while A gives nothing",
+          mean(tail_o, "b") < 1950 and mean(tail_o, "grid") > 1050)
+    check(f"{shape}: A is refused and asked 0 W outside its probes, B carries "
+          f"its rating, and the grid imports only what B cannot give",
+          cn.inverters[0].refused == 1 and all(r["a"] == 0.0 for r in held)
+          and min(r["b"] for r in tail_n) == 2000.0
+          and abs(mean(tail_n, "grid") - 1004) < 20)
+    check(f"{shape}: A's stale-reading gate trips at most once, the site is "
+          f"never stopped after the first 5 minutes, and SAFETY-42 does not "
+          f"report A as not delivering",
+          ntr["a"] <= 1
+          and all(r["reason"] != "not-running" for r in tail_n)
+          and not any(r["da"] for r in new))
+
+# ==============================================================================
+print("2. case b: house 1200 W, which B alone can carry, A cuts out")
+# ==============================================================================
+for shape, jit in SHAPES:
+    new, ntr, cn = run(lambda t: 1200.0, {"a": cut_at(120), "b": never}, H,
+                       jitter=jit)
+    old, _, _ = run(lambda t: 1200.0, {"a": cut_at(120), "b": never}, H,
+                    jitter=jit, old=True)
+    tail_n, tail_o = after(new, 300), after(old, 300)
+    imp = sum(max(0.0, r["grid"]) for r in tail_n) * TICK / H
+    print(f"    {shape}: old grid {mean(tail_o, 'grid'):+.0f} W, new grid "
+          f"{mean(tail_n, 'grid'):+.0f} W, new import {imp:.0f} Wh")
+    check(f"{shape}: PRECONDITION: the old law leaves a standing import",
+          mean(tail_o, "grid") > 250)
+    check(f"{shape}: B takes over the whole house and the grid sits near its "
+          f"target", abs(mean(tail_n, "grid") + 10) < 25 and imp < 10)
+    pa = probes(new, "a")
+    in_probe = [r for r in new
+                if any(p <= r["t"] < p + PROBE_S for p in pa)]
+    check(f"{shape}: A is probed at 200 W every 15 minutes while B carries "
+          f"the rest, and the two never pull opposite ways",
+          len(pa) >= 3
+          and all(abs(q - p - PROBE_EVERY_S - PROBE_S) <= 2 * TICK
+                  for p, q in zip(pa, pa[1:]))
+          and all(r["b"] > 0 for r in in_probe)
+          and all(r["a"] * r["b"] >= 0 for r in new))
+
+# ==============================================================================
+print("3. case c: both cut out; the site holds 0 W, probes one at a time")
+# ==============================================================================
+for shape, jit in SHAPES:
+    new, ntr, cn = run(lambda t: 3000.0, {"a": cut_at(120), "b": cut_at(150)},
+                       1.5 * H, jitter=jit)
+    old, _, _ = run(lambda t: 3000.0, {"a": cut_at(120), "b": cut_at(150)},
+                    1.5 * H, jitter=jit, old=True)
+    tail_n, tail_o = after(new, 600), after(old, 600)
+    pa, pb = probes(new, "a"), probes(new, "b")
+    print(f"    {shape}: old mean asks A/B {mean(tail_o, 'a'):.0f}/"
+          f"{mean(tail_o, 'b'):.0f} W; new {mean(tail_n, 'a'):.0f}/"
+          f"{mean(tail_n, 'b'):.0f} W, probes A {len(pa)} B {len(pb)}")
+    check(f"{shape}: PRECONDITION: the old law keeps asking two empty "
+          f"batteries", mean(tail_o, "a") > 150 and mean(tail_o, "b") > 150)
+    check(f"{shape}: the site holds 0 W: the loop says `battery refuses` or "
+          f"`battery probe` and each battery is asked 0 W or its probe",
+          all(r["reason"] in (control.REFUSED, control.PROBING)
+              for r in tail_n)
+          and all(r["a"] in (0.0, PROBE_W) and r["b"] in (0.0, PROBE_W)
+                  for r in tail_n))
+    check(f"{shape}: both batteries are probed, never at the same time",
+          len(pa) >= 3 and len(pb) >= 3
+          and not any(r["a"] and r["b"] for r in new if r["t"] > 300))
+
+# ==============================================================================
+print("4. recovery: the reseed stops the parked site target reaching the grid")
+# ==============================================================================
+# Both cut, the house drops to 940 W at 1 h, A recovers at 1.5 h with no sign
+# change. Phase A, with the envelope but no reseed and no site hold: -1059 W.
+ld = (lambda t: 3000.0 if t < H else 940.0)
+for shape, jit in SHAPES:
+    rows, _, c = run(ld, {"a": cut_at(120, 1.5 * H), "b": cut_at(150)},
+                     2 * H, jitter=jit)
+    win = after(rows, 1.5 * H, 1.5 * H + 900)
+    worst = min(r["grid"] for r in win)
+    print(f"    {shape}: worst grid after A recovers {worst:+.0f} W; A "
+          f"refused {c.inverters[0].refused}")
+    check(f"{shape}: A's recovery is found (at its next probe at the latest) "
+          f"and never exports more than 250 W",
+          c.inverters[0].refused == 0 and worst > -250
+          and any("BATTERY REFUSES ENDED inverter-a" in e for e in c.events))
+
+# Case a: B at its rating, the site target parked at 3600 W while the house
+# still imports; the house falls to 2500 W and A recovers. Without the reseed A
+# is handed the parked 1600 W at once, 1100 W more than the house needs.
+ld2 = (lambda t: 3000.0 if t < 0.5 * H else 2500.0)
+rows, _, c = run(ld2, {"a": cut_at(120, 0.75 * H), "b": never}, 1.5 * H)
+win = after(rows, 0.75 * H, 0.75 * H + 900)
+print(f"    a: worst grid when A recovers {min(r['grid'] for r in win):+.0f} W")
+check("case a: a recovery hands A no parked site target (worst export under "
+      "250 W)", min(r["grid"] for r in win) > -250
+      and any("BATTERY REFUSES ENDED inverter-a" in e for e in c.events))
+
+# ==============================================================================
+print("5. exits, words and the circulation guard")
+# ==============================================================================
+# Solar: the house exports from 30 min, so the loop wants to charge.
+rows, _, c = run(lambda t: 3000.0 if t < 0.5 * H else -2500.0,
+                 {"a": cut_at(120), "b": never}, H)
+check("the grid asking the other direction lets A charge at once (its limit "
+      "closes only the refused direction) and a minute of charge ends the "
+      "refusal",
+      c.inverters[0].refused == 0 and min(r["a"] for r in after(rows, 0.6 * H))
+      < -500 and any("the other way" in e for e in c.events))
+
+
+def _stop(c):
+    c.auto = False
+
+
+rows, _, c = run(lambda t: 3000.0, {"a": cut_at(120), "b": never}, 0.5 * H,
+                 events={1200.0: _stop})
+check("stopping control ends the refusal",
+      c.inverters[0].refused == 0
+      and any("control stopped" in e for e in c.events))
+
+# A small house: the site asks under 200 W, so a probe may not pin A (B would
+# have to charge while A gives power). The probe waits instead.
+rows, _, c = run(lambda t: 3000.0 if t < 600 else 120.0,
+                 {"a": cut_at(120), "b": never}, 1.2 * H)
+check("with the site asking under 200 W no probe is sent and no inverter is "
+      "ever asked the opposite way to the other",
+      c.inverters[0].refused == 1
+      and probes(after(rows, 700), "a") == []
+      and all(r["a"] * r["b"] >= 0 for r in rows)
+      and not any("ARBITER" in e for e in c.events))
+
+# The hold binds every strategy's ask: a peak-guard SET at P_PEAK on the site
+# is still placed around a refusing unit's closed limit.
+_res = resolve([Claim.set("peak", P_PEAK, 3000.0, "quarter peak"),
+                Claim.set("loop", P_LOOP, 500.0, "tracking"),
+                Claim.limit("supervised", P_SAFETY, -2000.0, 2000.0,
+                            actuator="inverter-a"),
+                Claim.limit("supervised", P_SAFETY, -2000.0, 2000.0,
+                            actuator="inverter-b"),
+                Claim.limit("refused", P_SAFETY, hi=0.0,
+                            reason=control.REFUSED, actuator="inverter-a")],
+               units=("inverter-a", "inverter-b"),
+               live=("inverter-a", "inverter-b"))
+check("a P_SAFETY refusal limit binds a higher-priority strategy too: the "
+      "peak guard's 3000 W goes to B, A gets 0 W",
+      _res.shares.get("inverter-a") == 0 and _res.shares.get("inverter-b")
+      == 2000)
+
+
+class _Grab(logging.Handler):
+    def __init__(self):
+        super().__init__()
+        self.lines = []
+
+    def emit(self, record):
+        self.lines.append((record.levelno, record.getMessage()))
+
+
+_g = _Grab()
+_lg = logging.getLogger("goodwe")
+_lv = _lg.level
+_lg.setLevel(logging.INFO)
+_lg.addHandler(_g)
+run(lambda t: 3000.0, {"a": cut_at(120), "b": never}, 600)
+run(lambda t: 3000.0, {"a": cut_at(120), "b": never}, 600,
+    soc={"a": 10.0, "b": 50.0})
+_lg.removeHandler(_g)
+_lg.setLevel(_lv)
+warns = [x for lv, x in _g.lines if lv == logging.WARNING
+         and "REFUSES_ABOVE_CUT_OUT" in x]
+infos = [x for lv, x in _g.lines if lv == logging.INFO
+         and "BATTERY_REFUSES" in x]
+print(f"    {warns} / {infos}")
+check("a refusal above the configured cut-out level logs INFO and one WARNING "
+      "naming the inverter, and a battery at its cut-out logs neither "
+      "(OPT-09's limit closes it first)",
+      len(warns) == 1 and warns[0].startswith("inverter-a ")
+      and len(infos) == 1 and infos[0].startswith("inverter-a:")
+      and len(warns[0].split()) <= 25)
+
+# A night load of 400 W: each unit is asked about 400 W once the loop has
+# made up A's missing half, under `saturation_w`. Engaging at PROBE_W is what
+# refuses A here; at 500 W it would keep a phantom share that SAFETY-43 names.
+rows, _, c = run(lambda t: 400.0, {"a": cut_at(0), "b": never}, 1200)
+check("a 400 W night load: A is refused at a share under 500 W, B carries the "
+      "house and nothing reports A as not delivering",
+      c.inverters[0].refused == 1 and not any(r["da"] for r in rows)
+      and abs(mean(after(rows, 300), "grid") + 10) < 25
+      and mean(after(rows, 300), "b") > 380)
+
+# A night load of 150 W: A's share never passes PROBE_W, so it is never
+# refused, and SAFETY-43 must not name it as not delivering either: a battery
+# asked under 200 W that gives under 100 W is a refusal too small to call.
+rows, _, c = run(lambda t: 150.0, {"a": cut_at(0), "b": never}, 1200)
+check("a small share on an empty battery is neither refused nor reported as "
+      "not delivering, and the grid stays near its target",
+      c.inverters[0].refused == 0 and not any(r["da"] for r in rows)
+      and abs(mean(after(rows, 300), "grid") + 10) < 25)
+
+rows, _, c = run(lambda t: 3000.0, {"a": cut_at(120), "b": never}, 600)
+notes = c.liveness_notes()
+check("the status page names the refusing inverter",
+      any(n.startswith("inverter-a: the battery refuses to give power")
+          for n in notes))
+
+# Shadow mode writes nothing, so nothing is asked and nothing can refuse.
+rows, _, c = run(lambda t: 3000.0, {"a": cut_at(120), "b": never}, 1200,
+                 extra={"shadow_mode": True})
+check("shadow mode: no inverter is refused and both stay at 0 W",
+      c.inverters[0].refused == 0 and c.inverters[1].refused == 0
+      and all(r["a"] == 0.0 and r["b"] == 0.0 for r in rows))
+
+# Review. A 1 s meter makes 12 cycles 11 s, shorter than a healthy battery
+# reading's lag (6 s dead time plus a 13 s publish). Ordinary load steps then
+# refused both inverters and dropped the site to 0 W (16 times an hour). The
+# evidence must also span REFUSED_SPAN_S.
+_steps = (lambda t: 300.0 if int(t // 120) % 2 == 0 else 3000.0)
+rows, _, c = run(_steps, {"a": never, "b": never}, H, tick=1.0,
+                 lag=(6.0, 13.0))
+check("a 1 s meter and slow battery readings: load steps for an hour refuse "
+      "neither healthy inverter",
+      not any(r["ra"] or r["rb"] for r in rows))
+rows, _, c = run(lambda t: 3000.0, {"a": cut_at(120), "b": never}, 600,
+                 tick=1.0, lag=(6.0, 13.0))
+_eng = next((r["t"] for r in rows if r["ra"]), None)
+check("...and the same slow readings still refuse a battery that is cut "
+      "out, after the span and well inside the 185 s report",
+      _eng is not None and 120 + m.REFUSED_SPAN_S <= _eng < 185
+      and not any(r["da"] for r in rows))
+
+# Review. A full battery that stops taking charge is refused (charge), and
+# it is always above its cut-out level: that says nothing about the setting,
+# so it gets the INFO line and no REFUSES_ABOVE_CUT_OUT warning.
+_g2 = _Grab()
+_lg.setLevel(logging.INFO)
+_lg.addHandler(_g2)
+rows, _, c = run(lambda t: -3000.0, {"a": never, "b": never}, 600,
+                 soc={"a": 99.0, "b": 60.0}, full={"a": lambda t: t >= 120})
+_lg.removeHandler(_g2)
+_lg.setLevel(_lv)
+check("a full battery that stops taking charge is refused that way only, "
+      "with the INFO line and no warning about its cut-out level",
+      c.inverters[0].refused == -1
+      and any(lv == logging.INFO and "BATTERY_REFUSES" in x
+              for lv, x in _g2.lines)
+      and not any("REFUSES_ABOVE_CUT_OUT" in x for _lv2, x in _g2.lines))
+
+# ==============================================================================
+print("6. one inverter is untouched")
+# ==============================================================================
+
+
+def _boom(*a, **k):
+    raise AssertionError("SAFETY-73 code ran at N=1")
+
+
+_saved = {k: getattr(Controller, k) for k in (
+    "_unit_refusals", "_unit_refusal_start", "_unit_refusal_end",
+    "_unit_probe", "_site_refused")}
+for k in _saved:
+    setattr(Controller, k, _boom)
+try:
+    import test_refusal as _t1
+    _one_ok = not _t1.fails
+except (AssertionError, SystemExit) as e:
+    _one_ok = isinstance(e, SystemExit) and not e.code
+finally:
+    for k, v in _saved.items():
+        setattr(Controller, k, v)
+check("SAFETY-52's whole single-inverter suite passes with every SAFETY-73 "
+      "method made to raise, so none of it runs at N=1", _one_ok)
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED: " + ", ".join(fails))
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_selfconfig.py

@@ -636,12 +636,18 @@ _app = web.build_app(FakeController(), FakeSupervisor())
 _routes = sorted({(r.method, r.get_info().get("path"))
                   for r in _app.router.routes() if r.method != "HEAD"})
 print("    " + "  ".join(f"{m} {p}" for m, p in _routes))
-check("the configuration surface adds five routes and touches none of the "
-      "three that were there",
+check("the configuration surface adds five routes and UX-13 one GET, and "
+      "none touches the three that were there",
       _routes == [("GET", "/"), ("GET", "/config"), ("GET", "/config/model"),
-                  ("GET", "/status"), ("POST", "/action"),
-                  ("POST", "/config/restart"), ("POST", "/config/save"),
-                  ("POST", "/config/validate")])
+                  ("GET", "/ha/entities"), ("GET", "/status"),
+                  ("POST", "/action"), ("POST", "/config/restart"),
+                  ("POST", "/config/save"), ("POST", "/config/validate")])
+_ents_src = io.open(os.path.join(HERE, "app", "haentities.py"),
+                    encoding="utf-8").read()
+check("UX-13's entity list only reads: haentities.py calls hass.states() and "
+      "no service, setter or action",
+      "hass.states()" in _ents_src
+      and not re.search(r"\.(call|set_number|handle_action|post)\(", _ents_src))
 _selfconfig_src = io.open(os.path.join(HERE, "app", "selfconfig.py"),
                           encoding="utf-8").read()
 for forbidden in ("set_number", "write_setpoint", "handle_action",
@@ -692,6 +698,10 @@ async def _e2e():
             async with s.post(f"{root}/config/validate",
                               json={"options": base(setpoint_entity="")}) as r:
                 out["invalid"] = await r.json()
+            async with s.post(f"{root}/config/validate",
+                              json={"options": base(integrator_max_w=3000)}
+                              ) as r:
+                out["warned"] = await r.json()
             # ⚠️ THE COUNTS ARE SNAPSHOTTED AT EACH STAGE. Asserting
             # `sup.writes == []` after the whole sequence would be asserting
             # about the LAST request, not this one - the first draft did, and
@@ -749,6 +759,11 @@ check("...and it honours the browser's language per key, falling back to "
 check("POST config/validate returns the validator's sentences, anchored",
       E["invalid"]["problems"]
       and "setpoint_entity" in E["invalid"]["by_key"])
+check("UX-13: POST config/validate also returns the validator's warnings, "
+      "beside no refusal",
+      E["warned"]["problems"] == [] and [n["keys"] for n in
+                                         E["warned"]["notes"]]
+      == [["integrator_max_w"]] and E["warned"]["notes"][0]["tier"] == "warn")
 check("a save of an invalid blob answers 422 and the Supervisor got nothing",
       E["save_invalid"][0] == 422
       and E["save_invalid"][1]["kind"] == "invalid"

goodwe_controller/test_settings.py

@@ -0,0 +1,464 @@
+"""UX-13 P2: the Installer settings view.  `python3 test_settings.py`
+
+The view is drawn from app/uilayout.py through app/uipage.py and saves the
+page model through app/uimodel.py and the shipped validator. Part 1 checks
+that every group and every mapped field reaches the page with its words,
+range and choices. Part 2 checks the page script names no option key. Parts
+3-5 drive the real routes over HTTP against a fake Supervisor: the save round
+trip, where a refusal lands, and a stale save. Part 6 holds the view's words
+to STYLE. The headless-browser click-through is in the PR, not in CI (the CI
+image has no browser).
+Mutating a module this file grades? Read MUTATION.md first (purge __pycache__).
+"""
+
+import asyncio
+import copy
+import glob
+import io
+import json
+import logging
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "tools"))
+logging.disable(logging.WARNING)            # the validator's own log lines
+
+from aiohttp import ClientSession, web as aioweb                # noqa: E402
+
+import translations_lint as TL                                  # noqa: E402
+import ux13_demo as D                                           # noqa: E402
+from app import selfconfig, uilayout as L, uimodel as U, uipage, web  # noqa: E402
+from app.validate import validate_startup_config                # noqa: E402
+from named_absence import field                        # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+SCHEMA = D.schema_ui(D.CONFIG)
+TRANSLATIONS = {"en": TL.parse_translation_file(
+    os.path.join(HERE, "translations", "en.yaml"))}
+DEFAULTS = D.defaults(D.CONFIG)
+SITE = dict(DEFAULTS, setpoint_entity="number.goodwe_setpoint",
+            soc_entity="sensor.soc", batt_entity="sensor.batt")
+TWO = dict(SITE, setpoint_entity="", inverters=[
+    {"name": "inverter-a", "setpoint_entity": "number.a", "max_w": 2500,
+     "bms_soc_floor": 10},
+    {"name": "inverter-b", "setpoint_entity": "number.b", "max_w": 2500,
+     "bms_soc_floor": 10}])
+UI_TEXT = uipage.ui_text()
+W = UI_TEXT["settings"]
+
+
+def browser(value):
+    """What JSON.parse then JSON.stringify does to a value: 3.0 becomes 3."""
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, list):
+        return [browser(v) for v in value]
+    if isinstance(value, dict):
+        return {k: browser(v) for k, v in value.items()}
+    return value
+
+
+# --------------------------------------------------------------------------- #
+print("1. every group and every mapped field reaches the page")
+# --------------------------------------------------------------------------- #
+LAYOUT = uipage.layout(SCHEMA, TRANSLATIONS)
+_flat = []
+for _g in LAYOUT["groups"]:
+    for _p in _g["parts"]:
+        for _f in _p["fields"]:
+            _flat.append((_g["id"], _f))
+            _flat += [(_g["id"], _s) for _s in _f.get("fields", [])]
+_keys = [f["key"] for _g, f in _flat]
+FIELD = {f["key"]: f for _g, f in _flat}
+check("the six groups, in the design's order",
+      [g["id"] for g in LAYOUT["groups"]]
+      == ["meter", "inverters", "tariff", "safety", "maintenance", "tuning"]
+      and [g["name"] for g in LAYOUT["groups"]]
+      == ["Meter", "Inverters and batteries", "Tariff and prices",
+          "Safety limits", "Maintenance", "Control tuning"])
+check(f"every field of the table is on the page once ({len(_keys)} fields)",
+      sorted(_keys) == sorted(f.key for _g, _p, f in L.fields())
+      and len(_keys) == len(set(_keys)))
+_counts = {g["id"]: sum(1 for gid, _f in _flat if gid == g["id"])
+           for g in LAYOUT["groups"]}
+print(f"    fields per group: {_counts}")
+check("every field has a label, and every option field's label is its "
+      "translation without the group prefix",
+      all(f["label"] and " · " not in f["label"] for _g, f in _flat)
+      and field(FIELD, "meter_source")["label"]
+      == "Where the meter reading comes from")
+_ranged = [(f["key"], f.get("min"), f.get("max")) for _g, f in _flat
+           if f["control"] in (L.SLIDER, L.LOCKED)]
+check(f"every slider and locked value has its range from the schema "
+      f"({len(_ranged)})", all(lo is not None and hi is not None
+                               for _k, lo, hi in _ranged)
+      and ("peak_cap_w", 500.0, 15000.0) in _ranged)
+check("the peak limit is a kW slider over a value stored in W, and its label "
+      "does not say W (the unit is shown beside the control)",
+      field(FIELD, "peak_cap_w")["scale"] == 1000
+      and field(FIELD, "peak_cap_w")["label"] == "Peak limit"
+      and not [f["key"] for _g, f in _flat
+               if f["unit"] and re.search(r"\([^()\s]{1,6}\)", f["label"])])
+_choice = [f for _g, f in _flat
+           if f["control"] in (L.SEGMENTED, L.SELECT, L.CHOICE)]
+check("every choice control has choices with words",
+      all(f["choices"] and all(c[1] for c in f["choices"]) for f in _choice))
+_ms = field(FIELD, "meter_source")
+check("the meter source is radio cards with a line of help on each",
+      _ms["control"] == L.CHOICE and set(_ms["hints"]) == {c[0] for c in
+                                                            _ms["choices"]})
+_reg = field(FIELD, "ui.region")
+check("the region shows its preset year beside the choice (P0 review)",
+      ["flanders", "Flanders, Fluvius Antwerpen, 2026 figures", False]
+      in _reg["choices"] and _reg["presets"]["flanders"]["year"] == 2026)
+check("...and says plainly that Wallonia and Brussels have no preset yet "
+      "(TARIFF-22)", _reg["later"] == [["wallonia", "Wallonia, no preset yet"],
+                                      ["brussels", "Brussels, no preset yet"]]
+      and "Wallonia or Brussels" in _reg["help"])
+_locked = sorted(f["key"] for _g, f in _flat if f["control"] == L.LOCKED)
+check(f"measured and derived values are locked behind 'Change' "
+      f"({len(_locked)}): every control tuning value, every safety stop and "
+      "the peak reserve",
+      {f.key for p in L.GROUPS[-1].parts for f in p.fields} <= set(_locked)
+      and "sign_disagree_w" in _locked and "peak_soc_floor" in _locked
+      and LAYOUT["groups"][-1]["support_only"])
+check("each group says when its settings apply",
+      all(g["applies"] == [UI_TEXT["applies"]["restart"]["name"]]
+          for g in LAYOUT["groups"]))
+_inv = field(FIELD, "inverters")
+check("the inverter cards carry their count, and adding one makes a list",
+      _inv["count"] == U.COUNT and _inv["grow"] == U.GROWN
+      and [s["key"] for s in _inv["fields"]]
+      == [f.key for f in L.ROSTER_FIELDS])
+check("a page-only field names the option keys it writes, for the grey key "
+      "line", _reg["writes"] == ["price_taxes_profile"]
+      and field(FIELD, "ui.solar")["writes"]
+      == ["pv_entities", "pv_entity", "pv_invert_entities"]
+      and "static_profile" in field(FIELD, "ui.contract")["writes"])
+check("without a Supervisor schema the page still draws, with no ranges",
+      len(uipage.layout([], {})["groups"]) == 6)
+
+# --------------------------------------------------------------------------- #
+print("\n2. the page script names no option key")
+# --------------------------------------------------------------------------- #
+JS = io.open(os.path.join(HERE, "app", "static", "settings.js"),
+             encoding="utf-8").read()
+ORDER, _nested = TL.config_surface(D.CONFIG)
+_leak = sorted(k for k in ORDER if re.search(
+    r"[^A-Za-z0-9_]" + re.escape(k) + r"[^A-Za-z0-9_]", JS))
+check(f"settings.js names no option key ({_leak})", not _leak)
+check("data is set as text, never as HTML",
+      "innerHTML" not in JS and "insertAdjacentHTML" not in JS)
+_fetch = sorted(set(re.findall(r'fetch\("([^"?]+)', JS)))
+check(f"every request is relative, to the add-on's own routes ({_fetch})",
+      _fetch == ["config/model", "config/restart", "config/save",
+                 "config/validate", "ha/entities"])
+
+
+def _resolve(path, node=W):
+    for k in path.split("."):
+        if not isinstance(node, dict) or k not in node:
+            return None
+        node = node[k]
+    return node
+
+
+_used = {re.sub(r"\.(replace|join|length)$", "", k) for k in
+         re.findall(r'\bW\.([a-z_]+(?:\.[a-z_]+)*)', JS)}
+_used |= set(re.findall(r'data-s(?:-ph|-label)?="([\w.]+)"', io.open(
+    os.path.join(HERE, "app", "static", "index.html"), encoding="utf-8").read()))
+_miss = sorted(k for k in _used if _resolve(k) is None)
+check(f"every word the view asks for is in app/ui_text ({len(_used)} keys, "
+      f"missing: {_miss})", len(_used) > 25 and not _miss)
+check("search matches a field's label, its key and its help",
+      "(f.label + \" \" + keys + \" \" + f.key + \" \" + (f.help || \"\"))"
+      in JS)
+check("a locked value shows no input until 'Change' is pressed",
+      re.search(r"function locked\(.*?\n  }\n", JS, re.S)
+      and "UNLOCKED.has(id)) { open(); return box; }" in JS)
+check("nothing is saved while the add-on's own checks refuse the model",
+      "if (MSG.some((m) => m.tier === \"bad\")) { toast(" in JS)
+check("Discard reloads the stored settings (after a stale save the page's "
+      "copy is no longer what is stored)",
+      re.search(r'"#sb-discard"\)\.addEventListener\("click", async \(\) => '
+                r'\{\s*await load\(\);', JS) is not None)
+check("a load locks every locked value again, and a choice the page can only "
+      "keep stays offered while it is the stored value",
+      "UNLOCKED.clear();" in JS.split("async function load")[1].split("render();")[0]
+      and "same(c[0], was)" in JS)
+check("removing cards back to one restores the stored shape (a flat inverter "
+      "is not turned into a list of one)",
+      "if (V[f.key].length === 1) for (const k in f.grow) V[k] = clone(ORIG[k]);"
+      in JS)
+check("the old settings page stays reachable (until P5)",
+      'href="config" id="set-classic"' in web.page())
+
+
+# --------------------------------------------------------------------------- #
+# The real routes, over HTTP, against a fake Supervisor
+# --------------------------------------------------------------------------- #
+class Supervisor:
+    def __init__(self, options):
+        self.options = copy.deepcopy(options)
+        self.writes = []
+
+    async def info(self):
+        return {"options": copy.deepcopy(self.options), "schema": SCHEMA,
+                "translations": TRANSLATIONS}
+
+    async def write_options(self, options):
+        self.writes.append(copy.deepcopy(options))
+        self.options = copy.deepcopy(options)
+
+    async def restart(self, confirm):
+        raise AssertionError("no restart here")
+
+
+class Hass:
+    session = None
+    token = ""
+
+    async def limits(self, _e):
+        return (-5000.0, 5000.0, 1.0)
+
+    async def states(self):
+        return []
+
+
+class Controller:
+    def __init__(self, opts):
+        self.o, self.hass, self.inverters = dict(opts), Hass(), []
+
+    def log_event(self, text, hint=None):
+        pass
+
+    def status_payload(self):
+        return {"banner": "", "level": "ok", "rows": [], "checks": []}
+
+    async def handle_action(self, what):
+        raise AssertionError(f"the settings view reached {what!r}")
+
+
+async def session(stored, steps):
+    """Run `steps(s, root)` against the app over a fake Supervisor."""
+    sup = Supervisor(stored)
+    runner = aioweb.AppRunner(web.build_app(Controller(stored), sup))
+    await runner.setup()
+    site = aioweb.TCPSite(runner, "127.0.0.1", 0)
+    await site.start()
+    root = f"http://127.0.0.1:{site._server.sockets[0].getsockname()[1]}/"
+    try:
+        async with ClientSession() as s:
+            out = await steps(s, root, sup)
+    finally:
+        await runner.cleanup()
+    return out, sup
+
+
+async def _get(s, url):
+    async with s.get(url) as r:
+        return await r.json()
+
+
+async def _post(s, url, body):
+    async with s.post(url, json=body) as r:
+        return r.status, await r.json()
+
+
+# --------------------------------------------------------------------------- #
+print("\n3. the save round trip")
+# --------------------------------------------------------------------------- #
+check("the fixture site starts (so a refusal below is the edit's)",
+      not validate_startup_config(TWO) and not validate_startup_config(SITE))
+
+
+async def _round(s, root, sup):
+    out = {}
+    m = await _get(s, root + "config/model?lang=en")
+    out["model"] = m
+    model = browser(m["ui"])
+    out["same"] = await _post(s, root + "config/save",
+                              {"model": model, "fingerprint": m["fingerprint"]})
+    out["after_same"] = copy.deepcopy(sup.options)
+    m = await _get(s, root + "config/model?lang=en")
+    model = browser(m["ui"])
+    model["peak_cap_w"] = 4200
+    model["inverters"][1]["max_w"] = 2200
+    out["edit"] = await _post(s, root + "config/save",
+                              {"model": model, "fingerprint": m["fingerprint"]})
+    return out
+
+
+_stored = dict(TWO, gain=0.5, target_grid_w=-10.0, peak_cap_w=3500)
+_r, _sup = asyncio.run(session(_stored, _round))
+check("config/model carries the layout and the page model",
+      _r["model"]["layout"] == json.loads(json.dumps(uipage.layout(
+          SCHEMA, TRANSLATIONS))) and _r["model"]["ui"]["inverter_count"] == 2)
+check("a save that changed nothing writes an identical blob: same values, "
+      "types and key order, although the browser turned -10.0 into -10",
+      _r["same"][0] == 200 and json.dumps(_r["after_same"])
+      == json.dumps(_stored) and isinstance(_r["after_same"]["target_grid_w"],
+                                            float))
+_written = _sup.writes[-1]
+print(f"    the edit: {_r['edit']}, changed "
+      f"{sorted(k for k in _stored if _written[k] != _stored[k])}")
+check("an edit writes exactly the fields edited, the peak limit in W",
+      _r["edit"][0] == 200
+      and sorted(k for k in _stored if _written[k] != _stored[k])
+      == ["inverters", "peak_cap_w"] and _written["peak_cap_w"] == 4200
+      and _written["inverters"][1]["max_w"] == 2200
+      and _written["inverters"][0] == _stored["inverters"][0])
+_blobs = [("config.yaml", DEFAULTS), ("site", SITE), ("two", TWO)] + [
+    (os.path.basename(f), json.load(open(f))) for f in sorted(glob.glob(
+        os.path.join(HERE, "scenarios", "ux13", "test23", "*.json")))]
+_bad = [n for n, o in _blobs if json.dumps(uipage.to_options(browser(
+    json.loads(json.dumps(U.options_to_ui(o)))), o)) != json.dumps(o)]
+check(f"every known blob comes back byte for byte through the browser "
+      f"({len(_blobs)} blobs, not: {_bad})", not _bad and len(_blobs) >= 8)
+_grown = U.options_to_ui(SITE)
+_grown["inverters"].append(dict(_grown["inverters"][0], name="b",
+                                setpoint_entity="number.b"))
+_grown["inverters"][0]["name"] = "a"
+_grown.update(U.GROWN)
+_g = U.ui_to_options(_grown)
+check("'Add an inverter' on a flat site writes a list and clears the flat "
+      "power request entity, which the validator refuses beside a list",
+      [e["name"] for e in _g["inverters"]] == ["a", "b"]
+      and _g["setpoint_entity"] == "" and not validate_startup_config(_g))
+
+# --------------------------------------------------------------------------- #
+print("\n4. a refusal lands beside the field it is about")
+# --------------------------------------------------------------------------- #
+
+
+async def _refuse(s, root, sup):
+    out = {}
+    m = await _get(s, root + "config/model?lang=en")
+    base = m["ui"]
+
+    async def validate(**edits):
+        model = copy.deepcopy(base)
+        for k, v in edits.items():
+            if k == "card":
+                model["inverters"][v[0]][v[1]] = v[2]
+            else:
+                model[k.replace("__", ".")] = v
+        return (await _post(s, root + "config/validate", {"model": model}))[1]
+
+    out["card"] = await validate(card=(1, "setpoint_entity", ""))
+    out["same"] = await validate(card=(1, "setpoint_entity", "number.a"))
+    out["floor"] = await validate(peak_soc_floor=5)
+    out["derive"] = await validate(ui__contract="dynamic", price_provider="")
+    model = copy.deepcopy(base)
+    model.update({"ui.contract": "dynamic", "price_provider": ""})
+    out["derive_save"] = await _post(s, root + "config/save", {
+        "model": model, "fingerprint": m["fingerprint"]})
+    out["derive_writes"] = len(sup.writes)
+    model = copy.deepcopy(base)
+    model["inverters"][1]["setpoint_entity"] = ""
+    out["save"] = await _post(s, root + "config/save",
+                              {"model": model, "fingerprint": m["fingerprint"]})
+    return out
+
+
+_r, _sup = asyncio.run(session(TWO, _refuse))
+
+
+def _at(payload, tier="bad"):
+    return {(m["field"], m["card"]) for m in payload["messages"]
+            if m["tier"] == tier}
+
+
+print(f"    blank power request entity on card 2: {_r['card']['messages']}")
+check("a blank power request entity on the second card is refused beside "
+      "that card's field, and not beside the list as well",
+      ("inverters.setpoint_entity", 1) in _at(_r["card"])
+      and ("inverters", None) not in _at(_r["card"]))
+print(f"    two cards on one entity: {_r['same']['messages']}")
+check("two cards on one entity are refused beside that field on both cards",
+      {("inverters.setpoint_entity", 0), ("inverters.setpoint_entity", 1)}
+      == _at(_r["same"]))
+check("a peak reserve under the cut-out level lands on the peak reserve and "
+      "on each card's cut-out level",
+      {("peak_soc_floor", None), ("inverters.bms_soc_floor", 0),
+       ("inverters.bms_soc_floor", 1)} <= _at(_r["floor"]))
+check("a model no blob can say is refused beside its field, in plain words",
+      _r["derive"]["messages"] == [{
+          "field": "price_provider", "card": None, "tier": "bad",
+          "text": W["derive"]["no_source"]["description"]}])
+check("a save no blob can say answers 422 with its sentence and writes nothing",
+      _r["derive_save"][0] == 422 and _r["derive_writes"] == 0
+      and _r["derive_save"][1]["messages"] == _r["derive"]["messages"])
+check("a refused save answers 422 with the same placement and writes nothing",
+      _r["save"][0] == 422 and ("inverters.setpoint_entity", 1)
+      in _at(_r["save"][1]) and _sup.writes == [])
+_fixed = U.options_to_ui(dict(TWO, static_profile="not json"))
+check("a sentence about a key the page derives goes to the field that writes "
+      "it, or to the visible choice that sets it",
+      uipage.targets("static_profile", "", _fixed) == [("ui.contract", None)]
+      and uipage.targets("max_w", "", U.options_to_ui(SITE))
+      == [("inverters.max_w", 0)]
+      and uipage.targets("pv_entity", "", _fixed) == [("ui.solar", None)])
+check("a sentence naming no setting on the page is kept, with no field",
+      uipage.anchors(["Something odd."], [], _fixed, ["gain"])
+      == [{"field": None, "card": None, "tier": "bad",
+           "text": "Something odd."}])
+
+# --------------------------------------------------------------------------- #
+print("\n5. a stale save names the fields that changed elsewhere")
+# --------------------------------------------------------------------------- #
+
+
+async def _stale(s, root, sup):
+    m = await _get(s, root + "config/model?lang=en")
+    sup.options["peak_cap_w"] = 5000          # the Configuration tab saves
+    model = copy.deepcopy(m["ui"])
+    model["gain"] = 0.4
+    return await _post(s, root + "config/save",
+                       {"model": model, "fingerprint": m["fingerprint"]})
+
+
+_r, _sup = asyncio.run(session(TWO, _stale))
+check("409 with the page fields to look at, and nothing written",
+      _r[0] == 409 and _r[1]["kind"] == "stale"
+      and "peak_cap_w" in _r[1]["changed_fields"] and _sup.writes == []
+      and _r[1]["fingerprint"] == selfconfig.fingerprint(_sup.options))
+
+# --------------------------------------------------------------------------- #
+print("\n6. the view's words keep to STYLE")
+# --------------------------------------------------------------------------- #
+
+
+def _texts(node, path=""):
+    for k, v in node.items():
+        if isinstance(v, dict):
+            yield from _texts(v, f"{path}{k}.")
+        elif isinstance(v, str):
+            yield f"{path}{k}", v
+
+
+_long = [(p, t) for p, t in _texts(W)
+         if len(t.split()) > (25 if p.endswith("description") else 6)
+         or (p.endswith("description") and len(re.findall(r"[.!?](?:\s|$)", t)) > 1)
+         or ";" in t]
+check(f"every settings string is one sentence of at most 25 words, or a "
+      f"name of at most 6 ({_long})", not _long)
+_labels = [c[1] for _g, f in _flat for c in f.get("choices", [])]
+check("every choice, including the region with its year, is at most 6 words",
+      all(len(x.split()) <= 6 for x in _labels))
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED")
+    sys.exit(1)
+print("all passed")

goodwe_controller/test_tariff.py

@@ -448,7 +448,7 @@ print(f"    restore() across the boundary said: {said}")
 aug7, sep7 = st7.peak(month="2026-08"), st7.peak(month="2026-09")
 check("a restart that straddles the month boundary BANKS the dead August "
       "quarter rather than dropping measured energy",
-      said.startswith("closed a stale block") and aug7.is_observed)
+      said.startswith("closed the 15-minute period") and aug7.is_observed)
 check(f"...at its partial-coverage figure ({aug7.peak_w:.2f} W = "
       f"{RUN_W * 399 / QUARTER_S:.2f} W, the seconds it actually covered)",
       near(aug7.peak_w, RUN_W * 399 / QUARTER_S, 1e-6))
@@ -1325,7 +1325,7 @@ print(f"    quarters banked in {month_key(_sb)}: {_before_stale} -> "
 check("a block closed by restore() rather than by sync() is counted too - the "
       "old counter incremented only in sync() and missed it entirely",
       _before_stale == 0 and _tr13.recorded_in(_sb) == 1
-      and "banked" in _state)
+      and "and saved it" in _state)
 
 # --- the count is scoped to the MONTH it is printed beside --------------------
 # ⚠️ TWO MONTHS AT DIFFERENT COUNTS. Equal counts would be satisfied by a

goodwe_controller/test_uilayout.py

@@ -0,0 +1,205 @@
+"""UX-13 P0: the layout table places every option once.  `python3 test_uilayout.py`
+
+app/uilayout.py is the one place UI code names an option key
+(DECISIONS/UX-13-one-layout-table.md). This file fails CI when config.yaml
+gains an option the table does not place, and checks each row against the
+sources UX-02 keeps authoritative: config.yaml for ranges, translations and
+app/ui_text for words, validate.py for which entities are read as watts.
+Mutating a module this file grades? Read MUTATION.md first (purge __pycache__).
+"""
+
+import io
+import json
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "tools"))
+
+import translations_lint as TL                                  # noqa: E402
+from app import uilayout as L, uimodel, validate                 # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+CONFIG = io.open(os.path.join(HERE, "config.yaml"), encoding="utf-8").read()
+ORDER, NESTED = TL.config_surface(CONFIG)
+TYPES = dict(re.findall(r"^  ([a-z_0-9]+): *(\S.*?) *$",
+                        CONFIG[CONFIG.index("\nschema:"):], re.M))
+EN = TL.parse_translation_file(os.path.join(HERE, "translations", "en.yaml"))
+UI_TEXT = json.load(io.open(os.path.join(HERE, "app", "ui_text", "en.json"),
+                            encoding="utf-8"))
+ROWS = list(L.fields())
+KEYS = [f.key for _g, _p, f in ROWS]
+
+
+def coverage_problems(order, nested):
+    """Every way the table and config.yaml's schema disagree."""
+    out = []
+    placed = [k for k in KEYS if not k.startswith(("ui.", "inverters."))]
+    for k in order:
+        n = placed.count(k) + (k in L.DERIVED) + (k in L.HIDDEN)
+        if n != 1:
+            out.append(f"{k} is placed {n} times")
+    out += [f"{k} is not in config.yaml" for k in
+            set(placed) | set(L.DERIVED) | set(L.HIDDEN) if k not in order]
+    sub = [k.split(".", 1)[1] for k in KEYS if k.startswith("inverters.")]
+    out += [f"inverters.{k} has no card field" for k in nested.get("inverters", [])
+            if sub.count(k) != 1]
+    out += [f"inverters.{k} is not in config.yaml" for k in sub
+            if k not in nested.get("inverters", [])]
+    return out
+
+
+print("1. every option has exactly one place")
+_p = coverage_problems(ORDER, NESTED)
+_fields = sum(1 for k in ORDER if k in KEYS)
+print(f"    {len(ORDER)} options: {_fields} fields, {len(L.DERIVED)} derived, "
+      f"{len(L.HIDDEN)} hidden. Problems: {_p}")
+check(f"config.yaml's {len(ORDER)} options are each a field, derived or hidden, "
+      "once", not _p and len(ORDER) >= 78)
+check("a new option without a place fails this check",
+      coverage_problems(ORDER + ["new_option_w"], NESTED)
+      == ["new_option_w is placed 0 times"])
+check("...and so does a new inverter field",
+      coverage_problems(ORDER, {"inverters": NESTED["inverters"] + ["mode"]})
+      == ["inverters.mode has no card field"])
+check("no key is both a field and derived",
+      not set(KEYS) & (set(L.DERIVED) | set(L.HIDDEN)))
+check("each derived key names the page field that writes it",
+      all(any(f.key == how for _g, _p2, f in ROWS)
+          for how in L.DERIVED.values()))
+
+print("\n2. each row is well formed")
+check("every control, entity kind and show operator is a known one",
+      all(f.control in L.CONTROLS and (not f.kind or f.kind in L.ENTITY_KINDS)
+          and all(op in L.SHOW_OPS for _n, op, _v in f.show)
+          for _g, _p2, f in ROWS))
+_names = set(ORDER) | set(KEYS) | {uimodel.COUNT} | set(uimodel.GROWN)
+check("every show condition reads an option, a page field, or the inverter "
+      "count or shape",
+      all(n in _names for _g, _p2, f in ROWS for n, _o, _v in f.show))
+check("every entity control has a kind, and no other control has one",
+      all((f.control in (L.ENTITY, L.ENTITY_LIST, L.SOLAR_LIST)) == bool(f.kind)
+          for _g, _p2, f in ROWS))
+check("everything applies after a restart: options are read at start, and "
+      "OPT-11's runtime switches are not built yet",
+      all(f.applies == L.RESTART for _g, _p2, f in ROWS))
+check("no unit states a number, so no range is written here",
+      all(not re.search(r"\d", f.unit) for _g, _p2, f in ROWS))
+
+
+_SCHEMA = CONFIG[CONFIG.index("\nschema:"):]
+_ROSTER = re.search(r"^  inverters:\n((?: {4,}.*\n)+)", _SCHEMA, re.M).group(1)
+ROSTER_TYPES = dict(re.findall(r"^ {4,}(?:- )?([a-z_0-9]+): *(\S+)", _ROSTER,
+                               re.M))
+
+
+def _type(key):
+    if key.startswith("inverters."):
+        return ROSTER_TYPES.get(key.split(".", 1)[1], "")
+    return TYPES.get(key, "")
+
+
+_ranged = [f.key for _g, _p2, f in ROWS
+           if f.control in (L.SLIDER, L.NUMBER, L.LOCKED)
+           and not f.key.startswith("ui.")]
+_unranged = [k for k in _ranged if not re.match(r"(int|float)\(", _type(k))]
+check(f"every slider, number and locked value has a range in config.yaml "
+      f"({len(_ranged)} of them, without: {_unranged})", not _unranged)
+_SUFFIX = (("_eur_kwh", "€/kWh"), ("_eur", "€/kWh"), ("_kwh", "kWh"),
+           ("_w", "W"), ("_s", "s"), ("_h", "h"), ("_min", "min"),
+           ("_days", "days"), ("_floor", "%"), ("_ceiling", "%"),
+           ("_target", "%"))
+
+
+def _unit_problem(f):
+    want = next((u for suf, u in _SUFFIX if f.key.endswith(suf)), None)
+    if want is None or f.control not in (L.SLIDER, L.NUMBER, L.LOCKED):
+        return False
+    return f.unit != want and not (want == "W" and f.unit == "kW"
+                                   and f.scale == 1000)
+
+
+_mism = [(f.key, f.unit) for _g, _p2, f in ROWS if _unit_problem(f)]
+check(f"each unit matches its key's suffix (mismatched: {_mism})", not _mism)
+check("the peak limit is shown in kW and stored in W",
+      L.field("peak_cap_w").unit == "kW" and L.field("peak_cap_w").scale == 1000)
+_watt = sorted({f.key.split(".")[-1] for _g, _p2, f in ROWS
+                if f.kind == "power_w"})
+check(f"the pickers that expect watts are exactly the entities validate.py "
+      f"reads as watts ({_watt})",
+      _watt == sorted(validate.WATT_ENTITY_KEYS))
+check("range_of() reads a Supervisor-shaped schema, nested ones too",
+      L.range_of("max_w", [{"name": "max_w", "lengthMin": 100,
+                            "lengthMax": 5000}]) == (100, 5000)
+      and L.range_of("inverters.max_w", [{"name": "inverters", "schema": [
+          {"name": "max_w", "lengthMin": 100, "lengthMax": 5000}]}])
+      == (100, 5000)
+      and L.range_of("p1_host", [{"name": "p1_host"}]) is None)
+
+print("\n3. the words come from translations and app/ui_text")
+_conf = EN["configuration"]
+_no_tr = [k for k in KEYS if not k.startswith("ui.") and not (
+    k in _conf if "." not in k
+    else k.split(".")[1] in _conf["inverters"]["fields"])]
+check(f"every option field has an en.yaml name (missing: {_no_tr})", not _no_tr)
+_no_ui = [k for k in KEYS if k.startswith("ui.")
+          and k[3:] not in UI_TEXT["fields"]]
+check(f"every page-only field has words in ui_text (missing: {_no_ui})",
+      not _no_ui)
+_titles = [g.id for g in L.GROUPS if g.id not in UI_TEXT["groups"]] + [
+    f"{g.id}.{p.id}" for g in L.GROUPS for p in g.parts
+    if p.id and f"{g.id}.{p.id}" not in UI_TEXT["parts"]]
+check(f"every group and part has a title (missing: {_titles})", not _titles)
+_contract = {"none", "fixed", "daynight", "dynamic", "custom"}
+check("every contract, fallback and region the model can hold has words",
+      set(UI_TEXT["choices"]["contract"]) == _contract
+      and set(UI_TEXT["choices"]["fallback"]) == _contract - {"dynamic"}
+      and set(UI_TEXT["choices"]["region"])
+      == set(uimodel.REGION_PRESETS) | {uimodel.OWN})
+check("both 'applies' labels have words",
+      set(UI_TEXT["applies"]) == {L.RESTART, L.NOW})
+
+print("\n4. visibility follows the page model")
+_m = uimodel.options_to_ui({"meter_source": "ha_signed", "meter_phases": 3,
+                            "inverters": [], "maintenance_enabled": False})
+check("a signed meter shows its net entity, and three phases its net list",
+      L.visible(L.field("p1_net_entity"), _m)
+      and L.visible(L.field("p1_phase_net_entities"), _m)
+      and not L.visible(L.field("meter_entity"), _m)
+      and not L.visible(L.field("p1_phase_import_entities"), _m))
+check("one inverter shows the one-inverter stops, not the per-inverter ones",
+      L.visible(L.field("sign_disagree_w"), _m)
+      and not L.visible(L.field("unit_sign_disagree_w"), _m))
+check("maintenance details hide while maintenance is off",
+      not L.visible(L.field("maintenance_charge_w"), _m))
+
+print("\n5. UI code names option keys in two files only")
+_KEY = re.compile(r"""["']([a-z0-9]+(?:_[a-z0-9]+)+)["']""")
+_src = io.open(os.path.join(HERE, "app", "uimodel.py"), encoding="utf-8").read()
+_owned = set(L.DERIVED) | {"inverters", "price_provider",
+                           "price_taxes_eur_kwh", "arbitrage_enabled"}
+_extra = sorted({k for k in _KEY.findall(_src) if k in ORDER} - _owned)
+check(f"uimodel.py names only the keys its derivations write (others: "
+      f"{_extra})", not _extra)
+_leak = sorted({f"{name}:{k}" for name in ("haentities.py", "web.py",
+                                          "uipage.py")
+                for k in _KEY.findall(io.open(os.path.join(HERE, "app", name),
+                                              encoding="utf-8").read())
+                if k in ORDER})
+check(f"haentities.py, web.py and uipage.py name no option key ({_leak})",
+      not _leak)
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED")
+    sys.exit(1)
+print("all passed")

goodwe_controller/test_uimodel.py

@@ -0,0 +1,224 @@
+"""UX-13 P0: stored options <-> page model, exactly.  `python3 test_uimodel.py`
+
+app/uimodel.py derives the keys the page does not show (the flat inverter,
+the solar keys, static_profile, the levies figure, arbitrage_enabled). Part 1
+round-trips every options blob the test suite hands the validator
+(scenarios/ux13/, recorded by tools/ux13_validator_calls.py at 652097a), the
+TEST-23 option files and config.yaml's defaults: options -> model -> JSON ->
+options must be identical. Parts 2-6 edit one page field and check the blob.
+Mutating a module this file grades? Read MUTATION.md first (purge __pycache__).
+"""
+
+import glob
+import gzip
+import io
+import json
+import logging
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+logging.disable(logging.WARNING)            # the validator's own log lines
+
+from app import uimodel as U                                   # noqa: E402
+from app.price import (FLEMISH_TAXES_COMPONENTS_EUR_KWH,        # noqa: E402
+                       PRICE_OPTION_DEFAULTS)
+from app.static_tariff import parse_static_profile              # noqa: E402
+from app.validate import validate_startup_config                # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+def trip(options):
+    return U.ui_to_options(json.loads(json.dumps(U.options_to_ui(options))))
+
+
+def edit(options, **fields):
+    model = json.loads(json.dumps(U.options_to_ui(options)))
+    for k, v in fields.items():
+        model[k.replace("__", ".")] = v
+    return U.ui_to_options(model)
+
+
+def raises(fn):
+    try:
+        fn()
+    except U.DeriveError:
+        return True
+    return False
+
+
+def defaults():
+    """config.yaml's `options:` block, read without PyYAML (not in CI)."""
+    text = io.open(os.path.join(HERE, "config.yaml"), encoding="utf-8").read()
+    block = text[text.index("\noptions:"):text.index("\nschema:")]
+    out = {}
+    for key, raw in re.findall(r"^  ([a-z_0-9]+):(.*)$", block, re.M):
+        raw = raw.split(" #")[0].strip()
+        try:
+            out[key] = json.loads(raw)
+        except ValueError:
+            out[key] = raw
+    return out
+
+
+DEFAULTS = defaults()
+SITE = dict(DEFAULTS, setpoint_entity="number.goodwe_setpoint",
+            soc_entity="sensor.soc", batt_entity="sensor.batt")
+
+print("1. every known blob survives the round trip unchanged")
+_calls = [json.loads(line) for line in gzip.open(os.path.join(
+    HERE, "scenarios", "ux13", "validator-calls-652097a.jsonl.gz"), "rt")]
+_test23 = sorted(glob.glob(os.path.join(HERE, "scenarios", "ux13", "test23",
+                                        "*.json")))
+_blobs = ([("config.yaml", DEFAULTS)]
+          + [(c["source"], c["opts"]) for c in _calls
+             if isinstance(c["opts"], dict)]
+          + [(os.path.basename(f), json.load(open(f))) for f in _test23])
+_bad = []
+for _src, _o in _blobs:
+    try:
+        _back = trip(_o)
+    except Exception as e:                               # noqa: BLE001
+        _bad.append(f"{_src}: {type(e).__name__} {e}")
+        continue
+    if json.dumps(_back, sort_keys=True) != json.dumps(_o, sort_keys=True):
+        _bad.append(f"{_src}: {sorted(set(_back) ^ set(_o)) or 'values'}")
+print(f"    {len(_calls)} validator calls, {len(_test23)} TEST-23 files, "
+      f"config.yaml defaults")
+check(f"all {len(_blobs)} are identical after options -> model -> JSON -> "
+      f"options (not: {_bad[:3]})", not _bad and len(_calls) >= 200
+      and len(_test23) >= 5 and len(DEFAULTS) >= 78)
+check("config.yaml was read whole: the defaults hold every option",
+      "inverters" in DEFAULTS and DEFAULTS["inverters"] == []
+      and DEFAULTS["price_taxes_eur_kwh"] == 0.11736)
+_m = U.options_to_ui(DEFAULTS)
+check("the page model never shows a derived key: it keeps them aside",
+      not {"setpoint_entity", "pv_entity", "pv_entities", "static_profile",
+           "price_taxes_profile"} & set(_m)
+      and set(_m["keep"]) >= {"static_profile", "pv_entity", "max_w"})
+check("a blob that lacks keys gains none", trip({"max_w": 900}) == {"max_w": 900})
+
+print("\n2. one inverter or a list")
+_one = edit(SITE, inverters=[dict(U.options_to_ui(SITE)["inverters"][0],
+                                  max_w=1500)])
+check("editing the one inverter writes the flat keys and keeps the list empty",
+      _one["max_w"] == 1500 and _one["inverters"] == []
+      and _one["setpoint_entity"] == "number.goodwe_setpoint")
+_card = U.options_to_ui(SITE)["inverters"][0]
+_two = edit(SITE, inverters=[
+    dict(_card, name="inverter-a", capacity_kwh=None),
+    dict(_card, name="inverter-b", setpoint_entity="number.goodwe_b",
+         soc_entity="sensor.soc_b", batt_entity="sensor.batt_b")])
+check("a second inverter writes the list and clears the flat power request "
+      "entity, which the validator refuses beside a list",
+      len(_two["inverters"]) == 2 and _two["setpoint_entity"] == ""
+      and "capacity_kwh" not in _two["inverters"][0]
+      and not validate_startup_config(_two))
+_listed = dict(SITE, setpoint_entity="", inverters=[
+    {"name": "garage", "setpoint_entity": "number.g", "max_w": 2000,
+     "bms_soc_floor": 10}])
+_l1 = edit(_listed, inverters=[dict(_listed["inverters"][0], max_w=1800)])
+check("a list of one stays a list, so the inverter keeps its name and stored "
+      "state", _l1["inverters"] == [dict(_listed["inverters"][0], max_w=1800)])
+check("editing a listed inverter keeps the unread flat keys as stored",
+      all(_l1[k] == _listed[k] for k in ("setpoint_entity", "soc_entity",
+                                          "batt_entity", "max_w")))
+check("a name on the flat inverter is refused rather than dropped",
+      raises(lambda: edit(SITE, inverters=[dict(_card, name="garage")])))
+_raw = dict(SITE, inverters="garage")
+check("a roster no card can show is kept when another field is saved, and "
+      "cannot be edited here",
+      edit(_raw, gain=0.5)["inverters"] == "garage"
+      and raises(lambda: edit(_raw, inverters=[_card])))
+
+print("\n3. solar rows")
+check("a stored flip reads as a reversed row",
+      U.options_to_ui(dict(DEFAULTS, pv_entity="sensor.pv",
+                           pv_invert_entities=["sensor.pv"]))["ui.solar"]
+      == [{"entity": "sensor.pv", "reversed": True}])
+check("one row writes pv_entity",
+      edit(DEFAULTS, ui__solar=[{"entity": "sensor.pv", "reversed": False}])
+      ["pv_entity"] == "sensor.pv")
+_pv2 = edit(dict(DEFAULTS, pv_entity="sensor.a"), ui__solar=[
+    {"entity": "sensor.a", "reversed": False},
+    {"entity": "sensor.b", "reversed": True}])
+check("two rows write pv_entities, clear pv_entity and flip the reversed one",
+      _pv2["pv_entities"] == ["sensor.a", "sensor.b"] and _pv2["pv_entity"] == ""
+      and _pv2["pv_invert_entities"] == ["sensor.b"])
+_stray = dict(DEFAULTS, pv_entities=["sensor.a", "sensor.b"],
+              pv_invert_entities=["sensor.b", "sensor.old"])
+_pv1 = edit(_stray, ui__solar=[{"entity": "sensor.a", "reversed": False}])
+check("removing a reversed row drops its flip, and a flip that was never a row "
+      "stays as stored", _pv1["pv_entities"] == ["sensor.a"]
+      and _pv1["pv_invert_entities"] == ["sensor.old"])
+
+print("\n4. contract and prices")
+_fixed = edit(DEFAULTS, ui__contract="fixed", ui__fixed_price=0.31)
+check("a fixed price writes a profile the tariff parser reads as one price",
+      _fixed["price_provider"] == "off"
+      and [p.eur_per_kwh for p in parse_static_profile(
+          _fixed["static_profile"]).periods] == [0.31]
+      and U.options_to_ui(_fixed)["ui.contract"] == "fixed")
+_dn = edit(SITE, ui__contract="daynight", ui__day_price=0.34,
+           ui__night_price=0.26)
+check("day and night write a profile that starts and reads back the same",
+      not validate_startup_config(_dn)
+      and U.options_to_ui(_dn)["ui.day_price"] == 0.34
+      and U.options_to_ui(_dn)["ui.night_price"] == 0.26)
+_dyn = edit(_dn, ui__contract="dynamic", price_provider="generic_dayahead")
+check("a dynamic contract keeps the day and night profile as its fallback",
+      _dyn["price_provider"] == "generic_dayahead"
+      and _dyn["static_profile"] == _dn["static_profile"])
+check("a dynamic contract without a price source is refused here",
+      raises(lambda: edit(DEFAULTS, ui__contract="dynamic")))
+_odd = json.dumps({"periods": [
+    {"from": "00:00", "to": "12:00", "days": "mon-sun", "eur_per_kwh": 0.2},
+    {"from": "12:00", "to": "24:00", "days": "mon-sun", "eur_per_kwh": 0.3}]})
+_om = U.options_to_ui(dict(DEFAULTS, static_profile=_odd))
+check("odd windows show as 'custom' and survive saving another field",
+      _om["ui.contract"] == "custom"
+      and edit(dict(DEFAULTS, static_profile=_odd), gain=0.5)
+      ["static_profile"] == _odd)
+
+print("\n5. region presets")
+_fl = U.REGION_PRESETS["flanders"]
+check("the Flanders preset is the sum of app/price.py's components, and is the "
+      "shipped default", _fl["taxes_eur_kwh"] == round(sum(
+          v for _n, v in FLEMISH_TAXES_COMPONENTS_EUR_KWH), 5)
+      == PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"] == DEFAULTS[
+          "price_taxes_eur_kwh"])
+check("every preset carries its year", all(
+    isinstance(p["year"], int) and p["year"] >= 2026
+    for p in U.REGION_PRESETS.values()))
+_own = dict(DEFAULTS, price_taxes_eur_kwh=0.06)
+check("a figure that is no preset reads as 'own', and choosing Flanders "
+      "writes the preset", U.options_to_ui(_own)["ui.region"] == U.OWN
+      and edit(_own, ui__region="flanders")["price_taxes_eur_kwh"] == 0.11736)
+_prof = dict(DEFAULTS, price_taxes_eur_kwh=0.12,
+             price_taxes_profile='{"day": 0.14, "night": 0.1}')
+check("'own' keeps a stored levies table when the figure is edited",
+      edit(_prof, price_taxes_eur_kwh=0.13)["price_taxes_profile"]
+      == _prof["price_taxes_profile"])
+check("'own' stores the typed figure",
+      edit(DEFAULTS, ui__region=U.OWN, price_taxes_eur_kwh=0.13)
+      ["price_taxes_eur_kwh"] == 0.13)
+
+print("\n6. arbitrage_enabled: the OPT-11 hook changes nothing yet")
+check("the hook answers None while battery modes do not exist",
+      U.arbitrage_from_batteries(U.options_to_ui(DEFAULTS)) is None)
+check("so the toggle is stored as the page has it",
+      edit(DEFAULTS, arbitrage_enabled=True)["arbitrage_enabled"] is True)
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED")
+    sys.exit(1)
+print("all passed")

goodwe_controller/test_validate.py

@@ -1693,11 +1693,11 @@ check("...and a card ON THIS LEG that the coefficients do not reproduce is "
 
 # ⚠️ THE SENTENCE DOCS.md RESTS ON, AND IT IS THE ONE MOST LIKELY TO ROT.
 _T16_INFO = [m for lvl, m in _T16_OK_LOG if lvl == "INFO"
-             and "NO STRATEGY IN THIS ADD-ON READS IT" in m]
+             and "No part of the add-on reads it yet" in m]
 check("the startup line says, in so many words, that NO STRATEGY IN THIS "
       "ADD-ON READS IT - the operator is told what the option does not do in "
       "the same breath as it being accepted",
-      len(_T16_INFO) == 1 and "displaced IMPORT" in _T16_INFO[0])
+      len(_T16_INFO) == 1 and "displaced import" in _T16_INFO[0])
 # ⚠️ THE ASYMMETRY IS ASSERTED AS AN ORDERED PAIR, NOT AS TWO NUMBERS IN ONE
 # SENTENCE (MUTATION.md habit 14). "6 and 0 appear somewhere" is satisfied by
 # the two legs TRANSPOSED - which is the sentence telling an operator that the
@@ -1808,6 +1808,47 @@ check("an UNREADABLE shadow_mode resolves to SHADOW, not to live - the "
       and shadow.engaged({"shadow_mode": ""}, control_started=True) is True
       and shadow.mode({"shadow_mode": "garbage"}) == "on")
 
+# --------------------------------------------------------------------------- #
+print("\nUX-13 - the warning tier: notes for the settings page, never refusals")
+from app.validate import Note, WATT_ENTITY_KEYS, config_notes  # noqa: E402
+
+_warned = base(integrator_max_w=3000, maintenance_discharge_w=2500,
+               price_provider="generic_dayahead", static_profile="")
+_notes = []
+_with = validate_startup_config(_warned, -5000, 5000, notes=_notes)
+check("a config with three logged warnings starts, and gives three notes, "
+      "each filed under the setting it names",
+      _with == [] and validate_startup_config(_warned, -5000, 5000) == []
+      and sorted(n.keys for n in _notes) == [
+          ("integrator_max_w",), ("maintenance_discharge_w",),
+          ("static_profile",)]
+      and all(n.tier == "warn" and f"({n.keys[0]})" in n.text for n in _notes))
+_refused = base(setpoint_entity="", integrator_max_w=3000)
+_n2 = []
+check("collecting notes changes no refusal",
+      validate_startup_config(_refused, notes=_n2)
+      == validate_startup_config(_refused) != [] and len(_n2) == 1)
+_rows = {"number.goodwe_setpoint": {"unit": None},
+         "sensor.soc": {"unit": "%"}, "sensor.batt": {"unit": "kW"}}
+_cn = config_notes(base(), entities=_rows)
+check("a battery power sensor in kW is warned about: the add-on takes it as "
+      "watts", [n.keys for n in _cn] == [("batt_entity",)]
+      and "kW" in _cn[0].text)
+_cn = config_notes(base(meter_entity="sensor.grid"), entities={})
+check("an entity Home Assistant does not have is named, and only the ones "
+      "this meter source and roster shape read",
+      sorted(n.keys[0] for n in _cn) == ["batt_entity", "meter_entity",
+                                         "setpoint_entity", "soc_entity"])
+check("with no entity list (Home Assistant down) those checks are skipped",
+      config_notes(base(), entities=None) == [])
+check("a peak limit below this month's peak is warned about",
+      [n.keys for n in config_notes(base(peak_cap_w=2500),
+                                    month_peak_w=2900)] == [("peak_cap_w",)]
+      and config_notes(base(peak_cap_w=3500), month_peak_w=2900) == [])
+check("pv.py converts solar units itself, so no solar key is read as watts",
+      not [k for k in WATT_ENTITY_KEYS if k.startswith("pv_")]
+      and isinstance(_cn[0], Note))
+
 # --------------------------------------------------------------------------- #
 print()
 if fails:

goodwe_controller/test_watchdog.py

@@ -1422,14 +1422,28 @@ for _t in range(0, 400, 5):
     _wd_unit.evaluate(-1000.0, 1500.0, True, T0 + timedelta(seconds=_t))
 print(f"       site: {_wd_site.reason!r}")
 print(f"       unit: {_wd_unit.reason!r}")
-check("⚠️ THE SITE INSTANCE'S SENTENCE IS BYTE-IDENTICAL TO THE ONE THAT "
-      "SHIPPED. It is what an operator reads on the status page, what goes in "
-      "the action log and what is persisted to /data/state.json, so it is "
-      "asserted against the literal rather than against a format string",
-      _wd_site.reason == (
-          "SIGN_DISAGREEMENT: commanded -1000 W against a meter reading "
-          "+1500 W for 180 s continuously (limits: both over 300 W, held over "
-          "180 s)"))
+# UX-11: this was a byte pin. The reason is now the evidence: the action
+# log, the DEBUG line and /data/state.json carry it, and the ERROR line quotes
+# only its code (`messages.reason_code()`). So what is pinned is what it says:
+# the code in front, where every saved reason has had it and where the ERROR
+# line finds it, then the command and the reading in that order (habit 14),
+# the time held and both limits.
+_sr = _wd_site.reason
+_order = [_sr.find(t) for t in ("commanded -1000 W", "meter reading +1500 W",
+                                "for 180 s", "both over 300 W",
+                                "held over 180 s")]
+check("⚠️ THE SITE INSTANCE'S REASON SAYS WHAT SHIPPED, IN THE SAME ORDER: "
+      "the code first, then what was commanded, what the meter read, how "
+      f"long, and the two limits ({_order})",
+      _sr.startswith("SIGN_DISAGREEMENT: ")
+      and messages.reason_code(_sr) == "SIGN_DISAGREEMENT"
+      and all(i > 0 for i in _order) and _order == sorted(_order))
+# UX-11 review: the text itself did not change, and it is what state.json
+# holds, so the byte pin stays beside the meaning pin.
+check("...and it is still byte-identical to the one that shipped",
+      _sr == ("SIGN_DISAGREEMENT: commanded -1000 W against a meter reading "
+              "+1500 W for 180 s continuously (limits: both over 300 W, held "
+              "over 180 s)"))
 check("...and the per-unit instance names what it ACTUALLY compared instead. "
       "'against a meter reading' there would be a false statement about which "
       "instrument produced the evidence, on the one line somebody woken by "

goodwe_controller/tools/replay_refusal.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""SAFETY-52's evidence: the 16-day capture replayed with and without the
+battery-refuses hold.  `python3 tools/replay_refusal.py`
+
+Same disturbance, fitted plant and pack floor as `replay_recorded_loop.py`,
+plus main.py's reseed, 15 s input hold and 0 W rules and the REAL SAFETY-37/57
+gate on a register published every 10 s. `old` is `compute()` with
+`refused=None`, which is release/1.0's law unchanged; `new` carries the refusal,
+runs the probe on main.py's clock and seeds a refusal from a gate trip.
+Modelled watt-hours: read the deltas, not the absolutes (see that tool).
+"""
+import math
+import pathlib
+import sys
+
+ADDON = pathlib.Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ADDON))
+sys.path.insert(0, str(ADDON / "tools"))
+import replay_recorded_loop as R                            # noqa: E402
+from app import freshness, control as NEW                   # noqa: E402
+
+def go(which, rows, fit, publish_s=10.0, stale_input_s=15.0):
+    law = NEW
+    tun = law.Tuning(**R.LIVE)
+    t0, g0, b0, sp0, soc0 = rows[0]
+    pl = R.Plant(*fit[:4], soc0); pl.seed(t0, b0, sp0)
+    st = dict(target=sp0, i_w=sp0, sat=0, loop_w=sp0, ref=0, anchor=None)
+    fr = freshness.Freshness(freshness.BOUNDS["batt"]); reg, reg_t = None, -1e18
+    bad, trips, was = None, 0, False
+    M = dict(und=0.0, imp=0.0, exp=0.0, q={}, run=0.0, mx=0.0, last=None, refh=0.0, probes=0)
+    for i in range(1, len(rows)):
+        t, gr, ba, sp, soc = rows[i]
+        dt = t - rows[i - 1][0]
+        if dt > R.TICK_CAP_S:
+            pl = R.Plant(*fit[:4], soc); pl.seed(t, ba, sp)
+            st.update(target=sp, i_w=sp, sat=0, loop_w=sp, ref=0, anchor=None)
+            fr = freshness.Freshness(freshness.BOUNDS["batt"]); reg_t = -1e18; bad = None
+            continue
+        b = pl.step(t, dt, st["target"]); grid = gr + ba - b
+        if t - reg_t >= publish_s:
+            reg, reg_t = float(round(b)), t
+        fr.submit(reg, st["target"], t); batt = fr.reading()
+        if fr.stale and not was:
+            trips += 1
+            if (which == "new" and not st["ref"] and st["sat"] >= tun.saturation_cycles
+                    and abs(reg) < NEW.REFUSED_BELOW_W and abs(st["target"]) > tun.saturation_w):
+                st["ref"], st["anchor"] = (1 if st["target"] > 0 else -1), t
+        was = fr.stale
+        if batt is None:
+            bad = t if bad is None else bad
+            if t - bad >= stale_input_s:
+                st.update(target=0.0, i_w=0.0, loop_w=None)
+        else:
+            bad = None
+            if st["loop_w"] is None or st["target"] != st["loop_w"]:
+                st["i_w"] = st["target"]
+            if which == "old":
+                d = law.compute(st["target"], grid, batt, tun, st["sat"], st["i_w"],
+                                refused=None)
+            else:
+                probe = False
+                if st["ref"] and st["anchor"] is not None:
+                    h = t - st["anchor"]
+                    if h >= NEW.PROBE_EVERY_S + NEW.PROBE_S: st["anchor"] = t
+                    else: probe = h >= NEW.PROBE_EVERY_S
+                d = law.compute(st["target"], grid, batt, tun, st["sat"], st["i_w"], refused=st["ref"], probe=probe)
+                if d.refused and not st["ref"]: st["anchor"] = t
+                if not d.refused: st["anchor"] = None
+                if probe and d.target_w == NEW.PROBE_W and M["last"] != NEW.PROBE_W: M["probes"] += 1
+                st["ref"] = d.refused
+            st.update(sat=d.sat_count, i_w=d.i_w, loop_w=d.target_w, target=d.target_w)
+        tg = st["target"]
+        if tg - b > 1000: M["und"] += dt / 3600
+        if st["ref"]: M["refh"] += dt / 3600
+        M["imp"] += max(0, grid) * dt / 3.6e6; M["exp"] += max(0, -grid) * dt / 3.6e6
+        k = math.floor(t / 900); a = M["q"].setdefault(k, [0.0, 0.0]); a[0] += grid * dt; a[1] += dt
+        M["run"] = M["run"] + dt if (M["last"] == tg and abs(tg) >= 250) else 0.0
+        M["mx"] = max(M["mx"], M["run"]); M["last"] = tg
+    worst = max(max(0.0, s / d) for s, d in M["q"].values() if d > 600)
+    return trips, M, worst
+
+def main():
+    rows = R.stream()
+    fit = R.fit_plant(rows, stride=7)
+    print(f"fit {[round(x, 2) for x in fit]}, {len(rows)} meter instants")
+    for label, f in (("fitted plant", fit),
+                     ("plant offset 0 W", (fit[0], fit[1], fit[2], 0.0, fit[4]))):
+        for which in ("old", "new"):
+            tr, M, w = go(which, rows, f)
+            print(f"{label:17s} {which}: gate trips {tr:4d} | request >1 kW above "
+                  f"delivery {M['und']:6.1f} h | longest held >=250 W "
+                  f"{M['mx'] / 3600:5.2f} h | import {M['imp']:6.1f} kWh export "
+                  f"{M['exp']:5.1f} kWh | worst 15-min {w:5.0f} W | refused "
+                  f"{M['refh']:5.1f} h, probes {M['probes']}", flush=True)
+
+if __name__ == "__main__":
+    main()

goodwe_controller/tools/ux13_demo.py

@@ -0,0 +1,259 @@
+"""UX-13: serve the real page and routes over a fixture controller, for a
+headless browser check.  `python3 tools/ux13_demo.py STATE PORT [HOST]`
+
+STATE is running, shadow or alarm. The controller is the shipped `Controller`
+with its readings set by hand (two batteries, solar, today's prices in the
+mockup's shape, trading on). Nothing here talks to Home Assistant or to an
+inverter: `/action` changes only this fixture. Used for the P1 render check
+(no JS errors, tooltips, phone width, dark mode) described in the PR.
+
+P2: the fixture Supervisor serves config.yaml's defaults with this site's
+options, a schema read off config.yaml the way the Supervisor renders it
+(`schema_ui()`) and translations/en.yaml, and keeps what the settings view
+saves in memory, so the Installer view can be clicked through end to end.
+"""
+
+import asyncio
+import io
+import json
+import os
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, HERE)
+sys.path.insert(0, os.path.join(HERE, "tools"))
+
+from aiohttp import web as aioweb                                # noqa: E402
+
+from app import homeview, web                                    # noqa: E402
+from app.main import Controller                                  # noqa: E402
+from app.peakguard import PeakDecision                           # noqa: E402
+from app.price import PricePoint, PriceProduct, PriceRead        # noqa: E402
+from app.static_tariff import TariffPlan                         # noqa: E402
+import translations_lint as TL                                   # noqa: E402
+
+PRICES = [.24, .22, .21, .20, .21, .22, .24, .27, .26, .22, .18, .16, .15,
+          .14, .16, .19, .23, .28, .33, .36, .34, .29, .26, .24]
+
+
+class Store(dict):
+    def set(self, k, v):
+        self[k] = v
+
+    def set_time(self, k, v):
+        self[k] = v.isoformat()
+
+    def get_time(self, k):
+        v = self.get(k)
+        return None if v is None else datetime.fromisoformat(v)
+
+    @property
+    def data(self):
+        return self
+
+
+class Pub:
+    enabled = False
+
+    def publish(self, _v):
+        pass
+
+    def close(self):
+        pass
+
+
+class Hass:
+    session = None
+    token = ""
+
+    async def limits(self, _e):
+        return (-5000.0, 5000.0, 1.0)
+
+    async def number(self, _e, invert=False):
+        return None
+
+    async def state(self, _e):
+        return None
+
+    async def set_number(self, _e, _v):
+        return True
+
+    async def call(self, *_a):
+        return True
+
+    async def states(self):
+        return STATES
+
+
+def _state(eid, name, state, unit=None, cls=None):
+    return {"entity_id": eid, "state": state,
+            "attributes": {"friendly_name": name, "unit_of_measurement": unit,
+                           "device_class": cls}}
+
+
+STATES = [
+    _state("sensor.grid", "Grid power", "-10", "W", "power"),
+    _state("sensor.grid_kw", "Grid power in kW", "-0.01", "kW", "power"),
+    _state("sensor.pv", "Solar power", "3900", "W", "power"),
+    _state("sensor.soc_a", "Battery A level", "62", "%", "battery"),
+    _state("sensor.soc_b", "Battery B level", "35", "%", "battery"),
+    _state("sensor.batt_a", "Battery A power", "-2500", "W", "power"),
+    _state("sensor.batt_b", "Battery B power", "-300", "W", "power"),
+    _state("number.a", "Battery A power request", "0", "W"),
+    _state("number.b", "Battery B power request", "0", "W"),
+    _state("sensor.peak_forecast", "Quarter-hour peak forecast", "1240", "W",
+           "power"),
+]
+
+
+# --- config.yaml as the Supervisor renders it (App.schema_ui) --------------- #
+def _node(name, spec):
+    spec = spec.strip()
+    optional = spec.endswith("?")
+    spec = spec.rstrip("?")
+    out = {"name": name, "required": not optional, "optional": optional}
+    m = re.match(r"(int|float)\(([^,]*),([^)]*)\)$", spec)
+    if m:
+        out.update(type="integer" if m.group(1) == "int" else "float",
+                   lengthMin=float(m.group(2)), lengthMax=float(m.group(3)))
+    elif spec.startswith("list("):
+        out.update(type="select", options=spec[5:-1].split("|"))
+    elif spec in ("bool",):
+        out["type"] = "boolean"
+    elif spec in ("int", "float"):
+        out["type"] = "integer" if spec == "int" else "float"
+    else:
+        out["type"] = "string"
+    return out
+
+
+def schema_ui(text):
+    """config.yaml's `schema:` block in the Supervisor's schema_ui shape: the
+    fixture for tests and this demo, which cannot run the Supervisor."""
+    block = text[text.index("\nschema:"):].splitlines()[1:]
+    out, i = [], 0
+    while i < len(block):
+        line = block[i]
+        m = re.match(r"^  ([a-z_0-9]+):\s*(\S.*?)?\s*$", line)
+        i += 1
+        if not m:
+            continue
+        name, spec = m.group(1), m.group(2)
+        if spec:
+            out.append(_node(name, spec))
+            continue
+        items = []
+        while i < len(block) and (block[i].startswith("    ") or not block[i].strip()):
+            if block[i].strip() and not block[i].strip().startswith("#"):
+                items.append(block[i].strip())
+            i += 1
+        if items and items[0].startswith("- ") and ":" in items[0]:
+            fields = [items[0][2:]] + items[1:]
+            out.append({"name": name, "type": "schema", "optional": True,
+                        "multiple": True,
+                        "schema": [_node(*f.split(":", 1)) for f in fields]})
+        else:
+            node = _node(name, items[0][2:] if items else "str")
+            node.update(multiple=True, required=False, optional=True)
+            out.append(node)
+    return out
+
+
+def defaults(text):
+    """config.yaml's `options:` block (as test_uimodel.py reads it)."""
+    block = text[text.index("\noptions:"):text.index("\nschema:")]
+    out = {}
+    for key, raw in re.findall(r"^  ([a-z_0-9]+):(.*)$", block, re.M):
+        raw = raw.split(" #")[0].strip()
+        try:
+            out[key] = json.loads(raw)
+        except ValueError:
+            out[key] = raw
+    return out
+
+
+CONFIG = io.open(os.path.join(HERE, "config.yaml"), encoding="utf-8").read()
+
+
+class Supervisor:
+    """The stored options, kept in memory: a save here writes nothing else."""
+
+    def __init__(self, options):
+        self.options = options
+        self.writes = 0
+
+    async def info(self):
+        return {"options": json.loads(json.dumps(self.options)),
+                "schema": schema_ui(CONFIG),
+                "translations": {"en": TL.parse_translation_file(
+                    os.path.join(HERE, "translations", "en.yaml"))}}
+
+    async def write_options(self, options):
+        self.options = json.loads(json.dumps(options))
+        self.writes += 1
+        print(f"options saved ({self.writes})", flush=True)
+
+    async def restart(self, confirm):
+        print(f"restart asked ({confirm!r})", flush=True)
+
+
+OPTS = {"meter_entity": "sensor.grid", "meter_source": "off",
+        "pv_entity": "sensor.pv", "maintenance_enabled": True,
+        "maintenance_start_hour": 18, "arbitrage_enabled": True,
+        "cycle_cost_threshold_eur": 0.05,
+        "inverters": [
+            {"name": "Battery A", "setpoint_entity": "number.a",
+             "soc_entity": "sensor.soc_a", "batt_entity": "sensor.batt_a",
+             "max_w": 2500, "capacity_kwh": 9.6},
+            {"name": "Battery B", "setpoint_entity": "number.b",
+             "soc_entity": "sensor.soc_b", "batt_entity": "sensor.batt_b",
+             "max_w": 2500, "capacity_kwh": 5.4}]}
+
+
+def controller(state):
+    opts = dict(OPTS, shadow_mode="on" if state == "shadow" else "off")
+    c = Controller(opts, Hass(), Store(), Pub(), stop=asyncio.Event())
+    c.auto = True
+    now = datetime.now(timezone.utc)
+    day0, _day1 = homeview.local_day(now)
+    pts = tuple(PricePoint(day0 + timedelta(days=d, hours=k), p, False)
+                for d in range(2) for k, p in enumerate(PRICES))
+    c.tariff_plan = TariffPlan(PriceRead.series(
+        pts, PriceProduct.DAY_AHEAD, "generic_dayahead", now), None,
+        "provider")
+    c.tariff_at = now
+    c.peak_guard = PeakDecision(engaged=False, floor_w=None,
+                                ceiling_w=3500.0, ceiling_from="cap",
+                                projected_w=1240.0)
+    for inv, soc, batt in zip(c.inverters, (62.0, 35.0), (-2500.0, -300.0)):
+        inv.soc, inv.batt = soc, (0.0 if state == "shadow" else batt)
+        inv.dev_min, inv.dev_max = -5000.0, 5000.0
+        if state != "running":          # 0 W accepted: Home says "Held"
+            inv.last_write = 0.0
+    c.grid = -10.0 if state != "shadow" else -2810.0
+    c.pv_w = 3900.0
+    if state == "alarm":
+        c.inverters[0].sign_wd.tripped = True
+    return c
+
+
+async def main(state, port, host="127.0.0.1"):
+    c = controller(state)
+    stored = dict(defaults(CONFIG), **OPTS)
+    stored.update(setpoint_entity="", meter_source="ha_signed",
+                  p1_net_entity="sensor.grid", price_provider="generic_dayahead",
+                  peak_forecast_entity="sensor.peak_forecast",
+                  shadow_mode=c.o.get("shadow_mode", "off"),
+                  inverters=[dict(i, bms_soc_floor=10)
+                             for i in OPTS["inverters"]])
+    runner = aioweb.AppRunner(web.build_app(c, Supervisor(stored)))
+    await runner.setup()
+    await aioweb.TCPSite(runner, host, port).start()
+    print(f"serving {state} on http://127.0.0.1:{port}/", flush=True)
+    await asyncio.Event().wait()
+
+
+if __name__ == "__main__":
+    asyncio.run(main(sys.argv[1], int(sys.argv[2]), *sys.argv[3:4]))

goodwe_controller/tools/ux13_validator_calls.py

@@ -0,0 +1,106 @@
+"""UX-13: record every `validate_startup_config()` call the test suite makes,
+and compare two validators over those calls.
+
+    python3 tools/ux13_validator_calls.py record OUT.jsonl.gz
+    python3 tools/ux13_validator_calls.py compare OLD_APP_PARENT OUT.jsonl.gz
+
+`record` runs each test_*.py with the validator wrapped (in this directory, so
+run it where the suite runs: the CI image). `compare` runs the recorded calls
+through the validator under OLD_APP_PARENT (a directory holding an `app/`,
+e.g. from `git archive <base> goodwe_controller/app`) and through this tree's,
+and prints every call whose refusals differ. P0 of UX-13 used it to show that
+adding the warning tier changed no refusal. scenarios/ux13/ holds the record
+test_uimodel.py round-trips.
+"""
+
+import gzip
+import json
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+_WRAP = r"""
+import json, runpy, sys
+sys.path.insert(0, ".")
+from app import validate
+real = validate.validate_startup_config
+out = open(sys.argv[1], "a")
+def rec(opts, dev_min=None, dev_max=None, *a, **kw):
+    try:
+        out.write(json.dumps({"opts": opts, "dev_min": dev_min,
+                              "dev_max": dev_max}) + "\n")
+    except (TypeError, ValueError):
+        pass
+    return real(opts, dev_min, dev_max, *a, **kw)
+validate.validate_startup_config = rec
+sys.argv = sys.argv[2:]
+try:
+    runpy.run_path(sys.argv[0], run_name="__main__")
+except SystemExit:
+    pass
+"""
+
+
+def record(out_path):
+    tmp = out_path + ".part"
+    open(tmp, "w").close()
+    rows, seen = [], set()
+    for name in sorted(f for f in os.listdir(HERE)
+                       if f.startswith("test_") and f.endswith(".py")):
+        before = sum(1 for _ in open(tmp))
+        subprocess.run([sys.executable, "-B", "-c", _WRAP, tmp, name],
+                       cwd=HERE, stdout=subprocess.DEVNULL,
+                       stderr=subprocess.DEVNULL)
+        with open(tmp) as fh:
+            for line in list(fh)[before:]:
+                call = json.loads(line)
+                key = json.dumps(call, sort_keys=True)
+                if key not in seen:
+                    seen.add(key)
+                    rows.append(dict(call, source=name))
+    os.remove(tmp)
+    with gzip.open(out_path, "wt") as fh:
+        for row in rows:
+            fh.write(json.dumps(row, sort_keys=True) + "\n")
+    print(f"{len(rows)} distinct validator calls -> {out_path}")
+
+
+def _run(app_parent, path):
+    code = r"""
+import gzip, json, logging, sys
+logging.disable(logging.CRITICAL)
+sys.path.insert(0, sys.argv[1])
+from app.validate import validate_startup_config as v
+out = []
+for line in gzip.open(sys.argv[2], "rt"):
+    c = json.loads(line)
+    try:
+        out.append(v(c["opts"], c["dev_min"], c["dev_max"]))
+    except Exception as e:
+        out.append("raised " + type(e).__name__)
+print(json.dumps(out))
+"""
+    got = subprocess.run([sys.executable, "-B", "-c", code, app_parent, path],
+                         capture_output=True, text=True, check=True)
+    return json.loads(got.stdout)
+
+
+def compare(old_parent, path):
+    old, new = _run(old_parent, path), _run(HERE, path)
+    differ = [i for i, (a, b) in enumerate(zip(old, new)) if a != b]
+    print(f"{len(old)} calls, {sum(1 for r in old if r)} refused by the old "
+          f"validator, {len(differ)} with different refusals")
+    for i in differ:
+        print(f"  call {i}:\n    old {old[i]}\n    new {new[i]}")
+    return 1 if differ else 0
+
+
+if __name__ == "__main__":
+    if len(sys.argv) == 3 and sys.argv[1] == "record":
+        record(sys.argv[2])
+    elif len(sys.argv) == 4 and sys.argv[1] == "compare":
+        sys.exit(compare(sys.argv[2], sys.argv[3]))
+    else:
+        sys.exit(__doc__)