Merge pull request 'Release 0.15.0' (#173) from release-0.15.0 into release/1.0

Release 0.15.0 (#173)

.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").
-2d026dfa7c425f462c6969b2f7cdfddc17b17a81
+3b4ff84757f9c2c5b63a4b4a53e593ccaeafb847

STYLE.md

@@ -0,0 +1,64 @@
+# STYLE.md - how user-facing text is written (UX-08)
+
+This applies to everything a home owner or installer reads: notifications, phone pushes, the add-on page, refusals, add-on log lines at WARNING and above, and the names and descriptions of options. It is enforced by `goodwe_controller/test_messages.py`. Its allowlist is empty since phase 2d and its cap is 0: a new string that breaks the rule fails the test.
+
+## 1. Shape
+- **Title**: at most 5 everyday words. It says what is wrong ("Meter reading may be stuck"). No "GoodWe:" prefix, no full stop.
+- **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.
+- **Plan line** (UX-13 Home screen: the plan, tooltips, a battery's "now" line): at most 2 sentences, each at most 12 words. Words in `app/ui_text/<lang>.json` under `home_words`, built by `app/homeview.py`, checked by `test_messages.py` part 8. The page's own words, English and Dutch, are checked by `test_ui_text.py`.
+- **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.
+
+## 2. Numbers
+Use a number only if it helps the reader act, for example the peak limit, or what was asked and what was sent in a fault report. Write it the way `app/messages.py` does: `5 000 W`, `20 %`, `10 minutes`, `14:05`.
+
+## 3. Severity
+Severity is shown by the title and the colour, never by CAPITALS or by words like "BUG SIGNAL".
+
+| Level | Colour | When |
+|---|---|---|
+| alarm | red | Control stopped, money or energy lost now, a fault, or a person must act now. Up to 3 sentences. |
+| warning | orange | Control is still running, but something needs a look. 1 sentence. |
+| info | grey | No action needed. 1 sentence. |
+| resolved | green | An earlier alarm or warning has cleared. 1 sentence. |
+
+A rewrite never changes an alarm's severity, `notification_id` or cadence.
+
+## 4. Words - the same word for the same thing everywhere
+A setting is named by its label in `translations/en.yaml`, in quotes when it sits mid-sentence (“Inverter rating”). The words below match those labels. If a label changes, change it here and in `app/messages.py` in the same change.
+
+| Say | Not |
+|---|---|
+| the add-on (who decides), control (what it does: "start control", "Control: last ran …") | controller, loop, planner |
+| battery | pack, BMS pack |
+| inverter, or its name | unit, device, actuator |
+| meter | P1 feed, telegram |
+| peak limit / this month's peak | ceiling, capaciteitstarief, billed quarter |
+| 15-minute period | quarter |
+| battery level (setting: “Battery level entity”) | SoC, state of charge, charge level |
+| battery cut-out level, or cut-out level next to "battery" (setting: “Battery cut-out level”) | BMS floor, `bms_soc_floor` |
+| peak reserve (setting: “Peak reserve”) | `peak_soc_floor`, EMS floor, "peak guard will not discharge below" |
+| “Inverter rating” (the setting) | `max_w`, rail, inverter rating as a fact about the hardware |
+| solar production, solar entity (settings: “Solar production entity”, “Solar production entities, per inverter”, “Reversed-sign solar entities”) | PV, reversed-sign list, single sensor setting |
+| “Where the meter reading comes from” | meter source |
+| “Grid power entity”; entity for any Home Assistant sensor a setting points at | grid power sensor, sensor setting |
+| draw the battery down, give power | discharge, discharging |
+| control is stopped / every inverter is set to 0 W | failsafe, trip, latch, parked |
+| safety stop (a stop that only starting control clears) | failsafe latch |
+| software fault | BUG SIGNAL |
+| control board | master, ESP32 |
+| power request, what the add-on asks | command, setpoint (on the page) |
+| the power went the wrong way | sign disagreement, command and meter point opposite ways |
+| check for inverters working against each other | circulating power check |
+| month peak, 15-minute periods measured | billed quarter, banked, soft limit, open block |
+| shadow mode | a mode that makes every decision but commands 0 W. The name is kept. In shadow mode a text says what the add-on **would** send, never that it sent it. |
+
+**Banned in titles and bodies** (the test fails on them): SAFETY-/TARIFF-/TEL-/CFG-/FW-/HW-nn and other card ids, integrator, anti-windup, windup, clamp, clamped, saturated, BUG SIGNAL, latch, latched, arbiter, allocator, register, `0x…`, layer 1/2/3, heartbeat, watchdog, telegram, ACK, CRC, OTA, Modbus, planner, `§n`, file names, IP addresses, option keys in snake_case, **HA entity ids**, and runs of 2 or more CAPITALISED words.
+
+HA entity ids are allowed only in refusals and validator messages, where the installer has to find that entity. They are never allowed in alarms or status rows.
+
+**Glossary.** DOCS.md "Words used on this page" explains, once, the words a home owner meets without context: control board, isolator, Developer Tools, shadow mode, safety stop, peak limit, peak guard, peak reserve and cut-out level. A home-owner text may use them without explaining them again. Card ids stay out of DOCS.md headings: they go on a *For installers* line under the heading.

docs/img/ux13/README.md

@@ -0,0 +1,9 @@
+# UX-13 screenshots
+
+Made from the real page by `goodwe_controller/tools/ux13_screenshots.sh`. Do not
+edit them by hand: run the script again.
+
+- `home-*.png`: Home, running, in Dutch, in shadow mode, at phone width, and in setup.
+- `settings-*.png`: Settings, Simple and Installer, and the time-window editor with an overlap.
+- `batteries*.png`: the Batteries screen with modes on, in Dutch, an Off battery helping the peak limit, a refusal at phone width, and modes off.
+- `setup-step-1*.png`: Setup, step 1.

goodwe_controller/CHANGELOG.md

@@ -1,5 +1,168 @@
 # Changelog
 
+## 0.15.0
+
+**A minor bump: changed behaviour, and no option changes.** No option was
+added, removed or renamed, and no default changed (83 options). Options that
+start 0.14.0 also start 0.15.0. The changes below apply with one inverter and
+with two.
+
+The add-on now learns and saves, per battery, what its power reading shows
+at rest (`unit/<name>/idle_w`). It learns it after about two quiet minutes and
+uses 0 W until then, as before. There is nothing to set.
+
+Contents of this release, in merge order since 0.14.0 (`02ed120`):
+
+| | |
+|---|---|
+| `cf705a9` | No more false "battery power reading stopped changing" errors at a new command after a rest, or at a change of phase. Each one paused control for a few seconds (several a day on a live site). A healthy battery that lags or turns around is no longer held as refusing for up to 15 min. With two inverters, a refusing battery whose reading at rest is about −100 W is now caught too. The rest value used is limited to ±75 W ([[SAFETY-94]], [[SAFETY-97]], also fixes [[SAFETY-58]]) |
+| `3129dae` | CI tests against a newer `admin/goodwe` (CI only) ([[CI-14]]) |
+
+### Known issues
+
+- A false "Battery is not keeping up" can still show when the peak guard pauses a maintenance charge ([[SAFETY-92]]).
+- After a gap in the P1 meter, the peak guard is blind for the rest of that quarter hour ([[SAFETY-90]]).
+- A battery capped at a low limit with a perfectly flat reading can still trip the stale check ([[SAFETY-74]]).
+- A battery whose reading at rest is beyond about ±170 W is still not caught when it refuses, as in 0.14.0 ([[SAFETY-97]]).
+- Two inverters: if one battery's drain stops early (e.g. switched Off), the other battery can jump to about 1.6 kW at once, and the surplus goes to the grid ([[SAFETY-95]]).
+- Two inverters: after one battery's link drops, control can stall until a safety stop ([[SAFETY-96]]).
+- Two inverters: the maintenance charge can switch on and off while the house is above the peak aim ([[SAFETY-88]]).
+- Two inverters: the "circulating" figure counts a battery's reading at rest ([[SAFETY-98]]).
+
+### If you are crossing from a version older than 0.10.0
+
+`## 0.10.0` below can refuse an old config: `slew_w` above its limit, and the
+withdrawn `price_provider` ids `engie_dynamic`, `totalenergies_dynamic` and
+`eneco_eddy`. Read it before you update. Run `tools/predeploy_check.py` with the
+bare options (`jq '.data.options'`) first.
+
+## 0.14.0
+
+**A minor bump: new behaviour with two inverters, and no option changes.**
+No option was added, removed or renamed, and no default changed (83
+options). Options that start 0.13.0 also start 0.14.0. With one inverter,
+control is the same as in 0.13.0.
+
+⭐ **Two inverters are now supported** for the monthly maintenance (drain,
+charge, hold) and the peak guard. To add a second inverter, follow
+`docs/commissioning-b.md` in the `admin/goodwe` repo. Its Stage 5, where the
+add-on takes control of it, needs 0.14.0. Read the known issues below first:
+three of them are about two inverters.
+
+Contents of this release, in merge order since 0.13.0 (`8c438ab`):
+
+| | |
+|---|---|
+| `f3e409c` | Two inverters: a battery at or under its peak reserve gives last, after the others give their full power. It is freed again above reserve + 1 point (e.g. above 21 % for a 20 % reserve). At a quarter's edge the peak guard no longer drops out for a second ([[SAFETY-91]]) |
+| `858f77c` | Two inverters: when a maintenance charge ends, for any reason, the other battery no longer starts charging from the grid; control hands over in small steps ([[SAFETY-93]]) |
+| `e51e3e0` | CI tests against a newer `admin/goodwe` (CI only) ([[CI-13]]) |
+
+### Known issues
+
+- A false "Battery is not keeping up" can still show when the peak guard pauses a maintenance charge ([[SAFETY-92]]).
+- A healthy battery that turns from charging to giving can be held at 0 W for up to 15 min ([[SAFETY-94]]).
+- After a gap in the P1 meter, the peak guard is blind for the rest of that quarter hour ([[SAFETY-90]]).
+- Two inverters: if one battery's drain stops early (e.g. switched Off), the other battery can jump to about 1.6 kW at once, and the surplus goes to the grid ([[SAFETY-95]]).
+- Two inverters: after one battery's link drops, control can stall until a safety stop ([[SAFETY-96]]).
+- Two inverters: the maintenance charge can switch on and off while the house is above the peak aim ([[SAFETY-88]]).
+
+### If you are crossing from a version older than 0.10.0
+
+`## 0.10.0` below can refuse an old config: `slew_w` above its limit, and the
+withdrawn `price_provider` ids `engie_dynamic`, `totalenergies_dynamic` and
+`eneco_eddy`. Read it before you update. Run `tools/predeploy_check.py` with the
+bare options (`jq '.data.options'`) first.
+
+## 0.13.0
+
+**A minor bump: new behaviour, a new add-on page (Home, Settings, Batteries,
+Setup), and six new options.** No option was removed or renamed, and no
+default of an existing option changed (77 options -> 83). The only new
+start-up checks are on the new options, so options that start 0.12.0 also
+start 0.13.0.
+
+New options, and what they do if you leave them alone:
+
+| option | default | left alone |
+|---|---|---|
+| `peak_margin_w` | `50` | the peak guard aims 50 W below your peak limit, or below a higher peak already reached this month; `0` is the old aim ([[SAFETY-79]]) |
+| `battery_modes_enabled` | `false` | no battery modes, control as before ([[OPT-11]]) |
+| `pv_forecast_entity`, `pv_forecast_tomorrow_entity` | empty | no solar forecast is used ([[OPT-11]]) |
+| `solar_trust_pct` | `70` | only used with a solar forecast ([[OPT-11]]) |
+| `pv_invert_entities` | `[]` | PV readings as before ([[TEL-14]]) |
+
+⚠️ **Turn on Watchdog** on the add-on's Info tab. It is off by default. If
+the control loop crashes, the add-on now sets the batteries to 0 W and stops.
+Home Assistant only starts it again when Watchdog is on ([[SAFETY-61]],
+[[DOC-5]]).
+
+⚠️ **The peak guard now starts a little earlier.** It aims 50 W below your
+peak limit, so the batteries give a bit more at peak times. Set
+`peak_margin_w: 0` for the old aim ([[SAFETY-79]]).
+
+Contents of this release, in merge order since 0.12.0 (`a45ed06`):
+
+| | |
+|---|---|
+| `fa3d237` | Docs name the right P1 age entity and a battery list that starts ([[DOC-1]]) |
+| `6e65272` | If the control loop crashes, the batteries go to 0 W and the add-on stops ([[SAFETY-61]]) |
+| `3e38baf` | The check tools refuse a file they cannot read, instead of saying all clear (tools only) ([[SAFETY-60]], [[SAFETY-62]]) |
+| `43b2740` | A missing value in a check is a named failure (tests only) ([[TEST-26]]) |
+| `20260e8` | Docs: turn on Watchdog ([[DOC-5]]) |
+| `16c796f` | New option `pv_invert_entities`: flip the sign of a PV sensor that reads backwards ([[TEL-14]]) |
+| `6a8a5ff` | CI tests against the real inverter simulator (CI only) ([[CI-12]]) |
+| `82f032e` | CI pin checks report failures properly (CI only) ([[TOOL-9]]) |
+| `fe13251` | CI pin update (CI only) |
+| `397dd15` | Alarm notifications that are still active come back after a Home Assistant restart ([[SAFETY-34]]) |
+| `59415ea` | CI pin update (CI only) |
+| `2503de1` | "Battery is not keeping up" is a warning with its own notification, not a "bug" alarm; its figures are correct ([[SAFETY-40]]) |
+| `48ef06a` | Shorter, plainer notifications ([[UX-08]]) |
+| `5c151a3` | CI pin update (CI only) |
+| `d57767f` | Shorter, plainer status rows and banners ([[UX-08]]) |
+| `e1d0970` | Details link works on current Home Assistant; plainer words ([[UX-09]]) |
+| `a02cd4b` | Shorter refusals, errors and option texts ([[UX-08]]) |
+| `32b9e56` | Plainer log lines and docs ([[UX-08]]) |
+| `125b070` | CI pin update (CI only) |
+| `2b14b88` | Last plain-language fixes in logs and the status page ([[UX-10]]) |
+| `c4032eb` | CI pin update (CI only) |
+| `d1f7e33` | Safety log lines: one plain sentence and a code ([[UX-11]]) |
+| `652097a` | A battery that refuses power (e.g. empty) is asked for 0 W, and tried at 200 W for 34 s every 15 min ([[SAFETY-52]]) |
+| `afd6af0` | Groundwork for the new settings pages ([[UX-13]]) |
+| `a36dca6` | New page with a Home screen ([[UX-13]]) |
+| `28a49cc` | With two or more inverters, a battery that refuses power is held on its own; the others take over ([[SAFETY-73]]) |
+| `515c11b` | New Installer settings view ([[UX-13]]) |
+| `4de9675` | New setup wizard for installers ([[UX-13]]) |
+| `8c34647` | A new install with no inverter opens the setup wizard instead of stopping ([[UX-15]]) |
+| `a5dddad` | Dutch text and a time-period editor ([[UX-13]]) |
+| `ed739d4` | Battery modes (off by default): per-battery limits, on/off, solar order ([[OPT-11]]) |
+| `7995e4d` | Simple settings view and a Batteries screen ([[UX-13]]) |
+| `7337b79` | Battery modes in Home Assistant, when modes are on ([[OPT-11]]) |
+| `7a00f12` | New option `peak_margin_w`: the peak guard keeps a margin below the limit ([[SAFETY-79]]) |
+| `5a4cdc2` | Battery modes: charge in cheap hours, hold for expensive hours; selling is off for now ([[OPT-11]]) |
+| `4f25b24` | No false "Load too high" alarms at quarter edges or with a noisy load (10 s hold) ([[SAFETY-81]]) |
+| `35cdffe` | Maintenance drain with two batteries no longer stalls ([[SAFETY-78]]) |
+| `1145a93` | Battery modes: a solar forecast decides how much to buy from the grid ([[OPT-11]]) |
+| `9d5b7d1` | With one battery, the peak guard wins over the maintenance drain ([[SAFETY-83]]) |
+| `4ad8298` | Maintenance charge with two batteries no longer stalls; it gives way to the peak guard ([[SAFETY-84]]) |
+| `b8ddfd7` | The peak guard wins over the maintenance hold; the hold ends on time, with no top-up ([[SAFETY-86]]) |
+| `9358781` | With two or more batteries, the peak guard uses every battery that can still give; peak alarms no longer say control stopped ([[SAFETY-87]]) |
+| `61072ca` | No false "Battery is not keeping up" during maintenance; real shortfalls still warn; the status row counts each episode once ([[SAFETY-85]]) |
+
+### Known issues
+
+- A false "Battery is not keeping up" can still show when the peak guard pauses a maintenance charge ([[SAFETY-92]]).
+- Two inverters: at the end of a maintenance charge one battery can charge from the grid while the house uses a lot. Do not add a second inverter before the next release ([[SAFETY-93]]).
+- A healthy battery that turns from charging to giving can be held at 0 W for up to 15 min ([[SAFETY-94]]).
+- After a gap in the P1 meter, the peak guard is blind for the rest of that quarter hour ([[SAFETY-90]]).
+- Two batteries: one at its peak reserve can be used before a draining battery has used its room ([[SAFETY-91]]).
+
+### If you are crossing from a version older than 0.10.0
+
+`## 0.10.0` below can refuse an old config: `slew_w` above its limit, and the
+withdrawn `price_provider` ids `engie_dynamic`, `totalenergies_dynamic` and
+`eneco_eddy`. Read it before you update. Run `tools/predeploy_check.py` with the
+bare options (`jq '.data.options'`) first.
+
 ## 0.12.0
 
 **A MINOR BUMP FOR ONE NEW OPTION: `pv_entities` ([[TEL-12]]), for sites with

goodwe_controller/DECISIONS/MAINT-05-per-pack-maintenance.md

@@ -285,32 +285,11 @@ cross-inverter `lo > hi` contradiction at `arbiter.py:114`. The only line this
 card changed there is **which** roster entry the claim is filed on: the one whose
 state machine produced the result, rather than `inverters[0]`.
 
-## 6. FOUND AND NOT FIXED: the site loop still contradicts a drain at N>=2
+## 6. FIXED BY SAFETY-78: the site loop contradicted a drain at N>=2
 
-Measured while wiring this card, and **pre-existing on `release/1.0` at
-`2d025ee`** — the same drain filed on `inverters[0]` produces the identical
-refusal with the two unit names swapped.
-
-The maintenance SET **pins** its pack. The loop's target is a **site** claim.
-When the site target is *below* the pin — a 2000 W drain while the house imports
-less than that, which is most of a night — the only split that sums to the site
-target asks the sibling to **charge** while the maintained pack **discharges**,
-and `allocator.plan()` refuses it by name as circulating power. The refusal is
-correct and fails safe: the whole site goes to 0 W with an `ARBITER: REFUSED`
-line in the action log.
-
-**The consequence an operator would see is a misdiagnosis.** The pack is held at
-0 W while its state machine believes it is draining, so after 12 h the DRAIN
-timeout fires and reports *"drain stuck"* — §12's words for a battery that is not
-following commands. The battery is fine; the site refused to allocate.
-
-**Why it is not fixed here.** The fix is to change what the site loop's target
-*means* while a unit is pinned — regulate the meter using only the unpinned
-packs — which is loop and allocator territory and changes the integrator's
-subject. MAINT-05 moves which pack is pinned and nothing else about it. It is
-pinned as a running check (`test_maintenance.py` part 12) rather than left as a
-comment, so it cannot be forgotten or quietly tuned away, and it wants a card of
-its own.
+Found here and pre-existing: below the pin the other pack had to charge, the
+allocator refused it and the site sat at 0 W. Fixed by a site `drain` floor;
+see [[SAFETY-78]] (`DECISIONS/SAFETY-78-drain-at-two.md`).
 
 ## 7. FOUND AND NOT FIXED: `migrate_unit_keys()` has the same hole, and it is a LATCH
 

goodwe_controller/DECISIONS/OPT-11-battery-modes.md

@@ -0,0 +1,129 @@
+# OPT-11 - battery modes, per battery
+
+A battery's mode (on/off, Solar first, Leftover solar) is a soft unit limit at
+`P_MODE` = 35 that always holds 0 W. A SET above 35 (a safety stop) overrides
+it; a limit above 35 (the peak guard) makes it give way only as far as that
+limit needs, and a battery its mode holds back then carries only what the
+others cannot (`arbiter._unit_modes()`, `_site_mode()`). Design and owner answers: `goodwe-session/OPT-11-design.md` (2026-09-27);
+P1 is its section 6 P1, and the pull request lists what was measured.
+
+- Off by default (`battery_modes_enabled`); off, commands are byte-identical to
+  a5dddad (`test_modes.py` part 1).
+- Off is a mode range, so the peak guard can still use an Off battery when the
+  others cannot cover the floor (design sections 2-3). Whether Off should be
+  absolute is an open owner question.
+- Review (PR #149): releasing only when the peak floor bound S let a trade won
+  above the floor keep the modes and place less than the floor, and let a
+  capped grid charge release an Off battery. Both are graded in
+  `test_arbiter.py` part 11. The loop bound leaves a side that reaches the
+  rail to the rail, so SAFETY-03 still flags a loop winding into it.
+- P2 (HA entities): a select and a switch per battery, only while modes are
+  on; commands go through `handle_action()`, the page's path. A retained
+  command is dropped, not applied: the store already holds the last choice,
+  and a replay after a restart could otherwise undo a newer one. The config
+  topics announced are kept in the store (`mqtt_mode_configs`), so turning
+  modes off removes exactly those, and an install that never turned them on
+  publishes what ed739d4 did (`test_mqtt.py` part 10). A removed topic stays
+  in that list and its empty config is re-sent on each start, so a start with
+  no broker cannot lose it; re-sending is harmless. The HA options are the
+  page's English names, pinned by a test, and are not renamed with the page:
+  automations send them.
+- In P1 only Off closes a direction; Leftover solar differs by charging last.
+- P3 (price runs, `priceruns.py`, `modetrade.py`): each battery's range is
+  narrowed by its role this tick (hold, give, charge, rest, sell); main.py
+  files the intersection with the switch, so it still holds 0 W. With modes on
+  the site trade is filed by the modes, sized from the loop bound (so no
+  battery a mode or a refusal holds is asked for watts, P1's unmet share) and
+  the guard's headroom; `arbitrage.decide()` runs only with modes off, which
+  stays byte-identical to 7a00f12 (`test_modes_p3.py` part 1).
+- SAFETY-46 item 2 is decided as the owner answered (2026-09-25): a trade is
+  a run of consecutive firm slots. It applies with battery modes on; the
+  modes-off trade keeps its one-period shape, because that path must not move.
+- Choices that were measured, not assumed (tools/opt11p3_replay.py):
+  - a sale needs the guard to have measured the quarter, not to be clear: a
+    5 kW discharge alone reads "engaged" on export and flipped the sale every
+    5 s;
+  - a grid charge makes the others rest, so it starts only at 500 W and, once
+    the guard or the headroom stops it, stays off for that 15-minute period
+    (without: 13 flips in 4 minutes under a 3.5 kW house);
+  - stored energy is valued at the last cheap run for 12 h, and a charge
+    needs its own run to clear the spread (without: a night charge was spent
+    on flat morning prices, then charging went on at them);
+  - a run edge reseeds the loop at the house's level (a 3 kW import spike
+    removed; about 0.1 x rating still overshoots as export).
+- Replay (tools/opt11p3_replay.py, 16 recorded days, EPEX hourly prices a
+  year earlier, modelled batteries), net EUR, lower is better: P2 19.33, P3
+  Solar first + Leftover solar 19.57, with a sale 19.60, the old one-period
+  trade 18.14. Review of #153 (same model, with a per-action split):
+  - the cheapest hours were at midday on 15 of 16 days, so Leftover solar (acting
+    as Cheap hours until P4) bought 12.2 kWh there that the sun would have
+    given: 7 kWh more exported, 12 kWh less solar stored. Holding for the
+    expensive hours saved 4 kWh of import, not enough. With no grid charge on
+    Leftover solar: 19.44;
+  - the old trade charged one hour, so the afternoon sun still fit;
+  - a sale earned the wholesale price (2.27 EUR for 11.4 kWh) and the house
+    then bought the same energy back (2.29 EUR): a wash before wear. It pays
+    only when the sale hour's wholesale price beats the later import price,
+    levies included (about 0.13 EUR/kWh above that hour's wholesale here);
+  - valuing the charge left at the end, wear and real Flemish levies make
+    selling worse and do not change the order.
+- Owner decision 2026-09-29 (option A): selling is off until it can be judged
+  on the price the grid pays (`packmode.SELLING_ENABLED`, code kept), and
+  Leftover solar takes solar only until P4's forecast
+  (`packmode.GRID_CHARGE_MODES`); Cheap hours only still charges from the grid. Replayed
+  (16 days, as above): Solar first + Leftover solar 19.44 EUR net against
+  P2's 19.33; Solar first + Cheap hours only 19.57.
+- Not done in P3: the forecast (P4), and a headroom too short for the run
+  moving the rest to the next cheap periods.
+
+## P4: the solar forecast and the day plan (2026-09-29)
+- Input: a Home Assistant forecast sensor (`pv_forecast_entity`, kWh left
+  today; `pv_forecast_tomorrow_entity` optional), read by `app/solarfc.py`.
+  Supported shapes: Forecast.Solar (state only), Solcast (`detailedForecast`)
+  and Open-Meteo Solar Forecast (`wh_period`). The unit is read, not guessed;
+  older than 3 h is stale (one missed hourly poll must not flag it).
+- Trust: `solar_trust_pct`, default 70 (owner answer 5).
+- House use: nothing the add-on recorded fitted. `tariff.db` holds grid
+  import per quarter, which the batteries shape. So `dayplan.HouseProfile`
+  keeps grid + battery per local hour for 7 days in the store
+  (`house_profile`), median per hour. It is net of the solar the house used,
+  so the solar sum never takes it below the night median. Solar readings are
+  not used (TEL-11). The first plan needs one day of it.
+- Verdict (`dayplan.plan()`): trust x sum max(0, forecast - house) x 0.95
+  until the expensive run the cheap run is for. Solar first takes it first.
+  - Leftover solar may then charge from the grid up to min(ceiling, floor +
+    the house's use in the expensive runs / 0.95), less its sun share: only
+    the shortfall.
+  - Cheap hours only ignores the plan and fills to the ceiling (design
+    section 1; review of #156, see the replay below).
+  - Solar first never charges from the grid (owner, 2026-09-29).
+- The level is kept unless it moves by min(1 kWh, 10 %). With no plan
+  (no, stale or failed forecast, no house profile, no capacity) every mode
+  is P3 option A exactly: `test_modes_p4.py` part 1 pins 12 digests from
+  5a4cdc2 (modes on, with and without an unavailable forecast).
+- The plan is made with the runs (every 15 min, or at once when the forecast
+  comes or goes). A lost forecast drops the levels at the next cycle.
+- Not done: the design's scaling by measured solar from 10:00 (it needs the
+  solar readings TEL-11 keeps out), the HA `goodwe_<inv>_plan` sensor, and
+  FCST-01.
+- Replay (`tools/opt11p4_replay.py`, 16 recorded days, Solar first + Leftover
+  solar, net EUR, lower is better; site solar rebuilt from the recording,
+  forecast errors from Elia's day-ahead Belgian solar forecast):
+  - year-earlier hourly prices: P2 19.33, P3 option A 19.44, old one-period
+    trade 18.14, P4 19.15 (perfect forecast 19.14, 1.5 x too high 19.16,
+    missing 19.44);
+  - the days' real 2026 quarter-hourly prices (held out): P2 32.26, option A
+    32.01, old trade 31.40, P4 29.19 (perfect 29.21, too high 29.28, missing
+    32.01).
+  - Solar first + Cheap hours only, skipping its sun share (the first
+    build): 19.57 (same as P3) and 29.72 against P3's 29.41. The shorter,
+    moved runs left B lower, so later midday top-ups rested A while the sun
+    shone. Cheap hours now ignores the plan, which is P3 exactly.
+  - A forecast of no sun at all gives 19.14 and 29.33. So nearly all of the
+    gain is Leftover solar buying the evening's shortfall in the cheap run;
+    the forecast itself was worth 0.14 EUR in 16 September days.
+  - Bias: the site's solar is rebuilt from the same net use the replay
+    plays, and "recorded" keeps its hourly shape and adds only the national
+    daily error. Both favour P4; "national" (no house leakage) gives 29.25.
+  No threshold was tuned to these days. The 2026-09-24 PV recording could not
+  be replayed: it is only in the live Home Assistant.

goodwe_controller/DECISIONS/SAFETY-32-per-pack-bms-floor.md

@@ -69,6 +69,8 @@ which does not run the startup gate) the absence costs a shave and never a pack.
 
 ## 3. DECISION 2 — the site verdict is the MAXIMUM of the packs' own floors
 
+*At N>=2 one pack at its floor no longer stops the others: [[SAFETY-87]].*
+
 `Controller.pack_floor_soc` — the **minimum** measured SoC, the emptiest pack —
 **is unchanged**, exactly as the card instructed. What changed is the floor it is
 graded against. `peakguard.binding_soc_floor()` reduces the roster's per-pack

goodwe_controller/DECISIONS/SAFETY-40-the-integrator-bound-is-not-a-bug.md

@@ -0,0 +1,28 @@
+# SAFETY-40: the integrator bound is not a bug
+
+**Decision.** `i_clamped` (the integrator reaching `integrator_max_w`, i.e.
+anti-windup) keeps alarming through the same `ClampWatchdog`: it is counted,
+notified on the same cadence, and escalates on a sustained run
+(SAFETY-41). It gets its own text, a `WARNING` and an amber status row. Only
+`clamped` (a command over `max_w`) and write-path clamps keep the BUG SIGNAL,
+the `ERROR` and the red row.
+
+**Why it still notifies.** On a default install `clamped` is unreachable
+(`control.py`, at the integrator bound), so the integrator bound is the only
+loop-side signal of a runaway such as the 14 768 W one. Silencing it would
+remove that. The card says the same: "the fix is to say the true thing, not to
+say less."
+
+**Why a bug has its own budget.** A genuine over-rating must not wait up to
+`REASSERT_S` behind anti-windup notices. `ClampWatchdog` tracks a separate
+`last_bug_alarm`, and a bug's text is never overwritten by later anti-windup
+text within an episode. Across episodes the WARNING uses its own
+notification id (`goodwe_integrator_bound`), so it cannot replace a BUG SIGNAL
+notice still on screen (review of #130). With only bug engagements, the cadence is the same as
+before (`test_clamp.py` part 9).
+
+**Numbers.** They come from the `Decision` of the clamping tick (`i_bound_w`,
+`requested_w`, `clamped_w`, `target_w`), not from `i_w` or `self.target`.
+
+**Open for the owner.** Whether scattered one-cycle anti-windup episodes should
+notify at all, or only log and count. They notify now, as before.

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/SAFETY-78-drain-at-two.md

@@ -0,0 +1,43 @@
+# SAFETY-78 - a maintenance drain at two inverters
+
+**Status: DECIDED 2026-09-29.** Fixes MAINT-05 §6 (OPT-11 P1 F1, UX-13 P3
+check 5, OPT-11 P3 F4). Tests: `test_safety78.py`.
+
+**The defect.** At N>=2 the drain pins its pack (a unit SET at
+`P_MAINTENANCE`) and the site target is split around the pin. Whenever the
+site target was below the pin, the other pack had to charge. The allocator
+refuses opposite directions (SAFETY-25 §0a, SAFETY-31), so the site went to
+0 W and logged `ARBITER: REFUSED` every cycle. That covers a house below the
+drain rate, a grid-charge trade, and a house above it too: after a refusal the
+loop restarts from 0 W and its 400 W slew step is below the pin again.
+
+**The fix.** While a pack drains at N>=2, main.py files a site limit
+`drain`, `lo` = what the pin really places (`allocator.pin_w()`: the drain
+rate inside that pack's own hard limits), at `P_MAINTENANCE`. So the site
+target is never below the pin and the other pack only adds power in the same
+direction. Opposite splits stay forbidden.
+
+- The order is the arbiter's own: a safety SET (100) outranks the limit and
+  the pin, so everything parks; the peak floor (50) and the drain floor are
+  both applied, so the higher wins; a trade or the loop below the drain is
+  lifted to it.
+- Below the drain rate the drained pack exports the rest, as the drain does at
+  N=1 (`maintenance.py`: "forced discharge, exports the surplus"). Holding it
+  to the house load would make N=2 drain differently from N=1; that is an
+  owner question, not this fix.
+- A draining pack that can place nothing (a refusal, a stale link) adds no
+  floor, and the wait is logged once per episode.
+- With battery modes on, no pack is a grid charger while another drains
+  (`modetrade.decide(draining=)`, why `cycle`), and the other battery's card
+  says why (`other_cycle`). Not while the drain waits: no floor is filed
+  then, so the other battery may charge from solar.
+- Not filed at N=1, where the drain is the site SET itself: byte-identical
+  (`tools/safety78_identity.py`, which hashes the claims too).
+
+**Not changed (measured in the PR #154 review, follow-ups).**
+- At N=1 a drain (60) outranked the peak floor (50): a 5000 W house imported
+  3000 W against a 2500 W limit. Fixed by [[SAFETY-83]].
+- At N=2 a maintenance CHARGE in a cheap window has the same stall: the
+  charging pack's `hi = -floor` against the loop asking the other to give is
+  refused on 141 of 261 cycles. The mirror fix is a site `hi`, which can meet
+  the peak floor's `lo` (0 W), so it is not this card. Fixed by [[SAFETY-84]].

goodwe_controller/DECISIONS/SAFETY-79-peak-margin.md

@@ -0,0 +1,41 @@
+# SAFETY-79 — the peak guard keeps a margin below the peak limit
+
+**Status: DECIDED 2026-09-28 (owner decision).**
+
+## Decision
+
+The peak guard aims `peak_margin_w` under the limit it holds: under
+`peak_cap_w`, or under a month peak already banked above it
+(`quarter_target_w()`). `peak_margin_w` is a setting: default 50 W, range
+0-500 W, whole watts. An install without the key gets 50.
+
+**Why (owner):** the guard aimed exactly at the cap, and in the OPT-11 P1 test
+a quarter banked 3501.9 W against a 3500 W limit (OPT-11-P1-test-report.md,
+check 4). A peak even 1 W over still sets the billed peak. It is a setting and
+not a constant because the add-on is sold to several sites.
+
+**Banked peak (review, 2026-09-29):** the PR first aimed at a banked month
+peak as it stood. That can bank a few W over it, which raises the bill the
+same way; and a peak banked between cap - margin and the cap (common in the
+month an install upgrades, since the old guard held quarters at the cap) was
+aimed at exactly, so one overshoot went over the cap. The margin now applies
+under it too. Cost: up to `peak_margin_w` of a peak already paid for goes
+unused (more discharge, less charge headroom); no bill cost. Undo is one line
+in `quarter_target_w()`.
+
+## What uses which number
+
+- **the aim:** `peakguard.decide()` (the claim's floor, and so arbitrage's
+  `charge_headroom_w()` and OPT-11's give-way, which read it), and, as cap -
+  margin, `shaping_suspended()` and `maintenance_charge_floor()` (the forecast
+  checks, via `Controller.peak_aim_w()`).
+- **the real cap (reporting and billing):** `PeakTracker` (month peak,
+  headroom, 80 % warning), the decision's `ceiling_w` and every notice and
+  status row built from it, Home's limit, and `validate.config_notes()`.
+
+## Checks
+
+`peak_margin_w: 0` is byte-identical to ed739d4 (test_peak_margin.py part 1,
+digests from tools/safety79_identity.py, which also runs a maintenance charge
+with a forecast). validate.py rule 12 refuses a value outside 0-500, not
+whole, or not below `peak_cap_w`.

goodwe_controller/DECISIONS/SAFETY-81-load-too-high.md

@@ -0,0 +1,63 @@
+# SAFETY-81 — no false "Load too high for battery" alarms
+
+**Status: 2026-09-29, owner go for the card. Review kept the 10 W tolerance
+as a constant and added the 10 s hold.**
+
+## Defect
+
+The SAFETY-79 test (SAFETY-79-test-report.md, F1/F2) saw 6 false alarms in 7.
+The alarm fired whenever `decide()` clamped its floor to the rating
+(`saturated`). Three things set that while the quarter landed on target:
+
+- **Double count.** `decide()` sizes from the held meter reading plus the
+  battery reading. When the meter sample predates the battery's last increase,
+  the increase is counted twice. It happens under noise, and at each quarter
+  start, where the battery is back while the held sample is still the spike.
+- **The aim, not the cap.** `saturated` is graded against cap − margin, so at
+  margin 50 noise needs 50 W less to trip it (F2).
+- **Last seconds.** The gain 900 / remaining turns a few W over the aim into
+  thousands of W wanted, with the battery far from its rating.
+
+## Decision
+
+The alarm needs `saturated` and `peakguard.load_too_high()`: with the battery
+at full power from now on, the quarter still ends more than `ALARM_MISS_W`
+(10 W) over the real limit (`ceiling_w`). That is the miss itself, without the
+gain. The battery reading it uses is the lower of this cycle's and the last
+one's. It must hold for `ALARM_HOLD_S` (10 s). At most one notification per
+quarter, because near the threshold the test flickers with the meter; the
+ERROR log line is written for every episode.
+
+**Why 10 W:** at margin 0 the guard itself lands up to +5.7 W over (SAFETY-79
+test, check 5), and those misses are real but tiny; the alarm would fire in
+the last second of most guarded quarters. The margin (default 50) is the fix
+for them. Cost: a real miss of 10 W or less is not alarmed; at a capacity
+tariff of the order of EUR 50 per kW a year, 10 W in one month is cents.
+Review measured +13 W on a 10 kW two-unit site at margin 0, not saturated, so
+no alarm: the tolerance only matters when the battery is at its rating. A
+constant, not an option: `peak_margin_w` is the owner's knob.
+
+**Why the hold (review):** the test assumes the load now lasts the rest of
+the quarter. A load over cap + battery for ~5 s every 30 s (`sine4500_fast`,
+a cycling hob or heater) alarmed at each quarter start while the quarter
+landed under the aim. The hold stops that.
+
+**Cost:** a real alarm comes 10-12 s later than on 5a4cdc2 (`step6500` at
+1211 s, not 1201 s); a slow ramp 20 s later (`ramp6500`), as it waits for the
+real cap. While the battery refuses or its reading is lost, the alarm waits
+until the quarter is lost even at full battery (27-60 s later in review runs);
+those faults have their own alarms. A load over cap + battery for more than
+10 s still alarms even if the quarter later lands under. `ALARM_HOLD_S = 0`
+removes the hold.
+
+## Not changed: the 1 s spike itself
+
+The cycle after a quarter boundary and before the new quarter's first meter
+sample still sees 0 s left, files no claim, and an Off battery drops to 0 W for
+one cycle. That is the same edge tick as OPT-15 F1, so it is left to OPT-15.
+Control is unchanged here: every command in `tools/safety81_sim.py` is
+byte-identical to 5a4cdc2 (test_safety81.py part 1).
+
+The double count also moves control, not only the alarm: on a late sample the
+guard asks for the full rating for one cycle (edge4600 at 902 s: 2000 W where
+1150 W holds the aim). Left to a follow-up card.

goodwe_controller/DECISIONS/SAFETY-83-peak-over-drain.md

@@ -0,0 +1,34 @@
+# SAFETY-83 - the peak guard outranks the maintenance drain at N=1
+
+**Status: DECIDED 2026-09-29 (owner go, P1).** Follows SAFETY-78's "Not
+changed" list. Tests: `test_safety83.py`.
+
+**The defect.** At N=1 the drain is the site SET at `P_MAINTENANCE` (60). The
+peak floor is a limit at `P_PEAK` (50), and clause 2 applies only limits at or
+above the winner, so the floor was ignored and the house imported what the
+drain left. A 5000 W house under a 2500 W limit and a 2000 W drain banked
+3000 W quarters; on the owner's settings (limit 3500, drain 2500, margin 50) a
+breach starts at about 5950 W.
+
+**The fix.** While a drain owns the setpoint at N=1 and the peak floor asks
+for more than the drain rate, `main.py` (`_peak_over_drain()`) refiles that
+peak claim at `P_MAINTENANCE`. The arbiter then applies it: the target is the
+floor, still inside the safety limits, and a safety SET (100) still parks
+everything. Where the floor is at or below the drain rate nothing changes.
+
+- The order in effect is now the same at N=1 and N=2: safety limits and the
+  SAFETY-73 refusal > peak guard (with the SAFETY-79 margin) > maintenance >
+  modes > trade > loop (`arbiter.py`, beside the priorities).
+- The drain keeps counting: the battery discharges at least the drain rate on
+  every cycle, so the cycle is not reset or stalled; it only ends sooner.
+- Below the drain rate the rest is still exported (owner, 2026-09-29).
+- Identity: `tools/safety78_identity.py --diff` against 35cdffe changes only
+  cycles where the guard asked for more than the drain; after such an episode
+  the commands are identical again and only the log and the idle loop's
+  integrator differ. N=2 is unchanged.
+
+**Not changed.**
+- Between the drain rate and the peak aim, the house still imports what the
+  drain leaves (N=1 behaviour kept by the identity). At N=2 the loop covers it.
+- A maintenance HOLD (0 W, 120 min, battery full) still outranked the peak
+  guard at N=1. Fixed by [[SAFETY-86]].

goodwe_controller/DECISIONS/SAFETY-84-charge-at-two.md

@@ -0,0 +1,46 @@
+# SAFETY-84 - a maintenance charge at two inverters
+
+**Status: DECIDED 2026-09-30.** Follows SAFETY-78's "Not changed" list.
+Tests: `test_safety84.py`; identity: `tools/safety84_identity.py`.
+
+**The defect.** In a cheap window the charging pack files its own
+`hi = -charge` (P_MAINT_SHAPE). At N>=2 the loop's site target sat above it
+(a house to cover, or its 400 W slew step from 0 W), so the other pack had to
+give while this one charged. The allocator refuses opposite directions
+(SAFETY-31), so the site sat at 0 W whatever the house
+(`tools/safety84_identity.py` on 9d5b7d1: 436 of 480 cycles refused). N=1
+was fine.
+
+**The fix.**
+- While a pack's own limits make it charge at N>=2, `main.py` files a site
+  limit `charge`, `hi` = what that pack's own `hi` places
+  (`allocator.hi_w()`, whole W as the allocator rounds). The site target is
+  never above it, so the other pack only adds power in the same direction.
+  Opposite splits stay forbidden. Mirror of SAFETY-78's `drain` floor.
+- Peak guard first (owner order, SAFETY-83). The charge is sized to the
+  quarter's headroom under the aim (`charge_headroom_w()`, cap or banked peak
+  minus `peak_margin_w`), so it charges less instead of stopping: the meter
+  sits on the aim and the guard does not need to step in. Where the house
+  alone is over the aim the guard engages, the shaping is suspended as before
+  (`shaping_suspended()`) and no `charge` is filed, so the guard's `lo` and
+  this `hi` never meet in one cycle (no `lo > hi`, no park at 0 W).
+  Without the headroom sizing the aim still held (the suspension did it), but
+  a battery gave power back on 285 of 540 cycles at a 3000 W house
+  (test_safety84.py part 2).
+- A site stop (a safety SET above P_MAINT_SHAPE) sizes the charge to 0 W:
+  the unit `hi` is a hard limit, so a charge under a 0 W stop needs the other
+  pack to give. It was refused, with an ARBITER line, on most cycles of the
+  stop (test_safety84.py part 4). The stop still parked the site at 0 W.
+- A pack that cannot take the charge (a refusal, a full pack, a stale link)
+  files no ceiling; the other pack follows the loop.
+- Not filed at N=1: byte-identical (`tools/safety84_identity.py`, which hashes
+  every claim, in and out of a cheap window and under a banked peak).
+
+**Not changed.**
+- At N=1 the charge is not sized to the headroom: the guard still suspends it
+  and the battery gives until the quarter is safe. The same sizing would fit
+  there; that is an owner question, not this fix.
+- Outside a cheap window (`hi = 0`, solar only) nothing is filed, at any N.
+- A HOLD (later fixed by [[SAFETY-86]]) and the "Battery is not keeping up"
+  alarm (SAFETY-85) are untouched. In the identity runs that alarm's log line
+  comes as often at N=2 as at N=1 (2 in 480 cycles).

goodwe_controller/DECISIONS/SAFETY-85-no-false-not-keeping-up.md

@@ -0,0 +1,91 @@
+# SAFETY-85 - no false "not keeping up" while another owner sets the battery
+
+**Status: implemented 2026-10-01, for review.** Tests: `test_safety85.py`.
+
+**The defect.** "Battery is not keeping up" (SAFETY-40, `goodwe_integrator_bound`)
+fired about every 2.5 min during maintenance (drain, charge, HOLD) and under the
+peak guard, while the battery gave exactly what it was told. Each warning
+re-created the HA notification. Rig counts: 24 in an hour (SAFETY-83 F1), 43 in
+7 episodes (SAFETY-86), 35 in 16 (SAFETY-87), 12 in 6 (SAFETY-84). The page
+counter counted cycles (861), not episodes.
+
+**Cause, measured on the real Controller.**
+- N=1: when a higher claim decides, `cycle()` re-seeds the integrator from the
+  target each cycle, then `compute()` adds `gain * error` for a grid error the
+  loop does not own. Target + kick crosses the rail and sets `i_clamped`. The
+  carried integrator is not wound (SAFETY-48 caps the lead at one slew step),
+  so control comes back one slew step at a time.
+- N>=2: a maintenance pin is a unit claim. The loop stays the site winner and
+  winds to its rail for watts the pinned battery may not give. When the pin
+  lifts, the site jumps: 2500 W in one cycle when a HOLD ends under a 4500 W
+  house, 1390 W when a charge pin lifts (`s84 n2_charge_dear`, t=1800 s).
+
+**Decision.** Three rules; the alarm, its text and its id are unchanged.
+1. **The loop's clamp counts only on a cycle the loop decided.** The winner is
+   the loop. Its number is on the wire, or only a rating (`device`,
+   `supervised`) cut it. No bound held it, and nothing was unmet.
+   (`Controller._loop_alarm_input`.)
+2. **A battery another owner set to discharge alarms when it gives less than
+   it was told.** This covers every battery on a cycle the loop did not
+   decide, and a battery with its own pin otherwise. The test is more than
+   `saturation_w` short of the least it stood at over `SHORT_CYCLES` cycles
+   and `SHORT_SPAN_S` (the plant's measured settle, SAFETY-13/73), for
+   `saturation_cycles` cycles in a row (`clamp.delivery_short`). It covers a
+   real shortfall during maintenance or under the peak guard. Before, that
+   shortfall was silent unless the kick happened to reach the rail (house
+   1000 W, drain 2000 W, battery gives nothing: 0 warnings before, 4 in 10 min
+   now).
+3. **At N>=2, while maintenance holds a battery, the loop is bounded** by
+   OPT-11's `loop_bound()` (what the batteries may place). It does not wind,
+   and control comes back one slew step a cycle. Why maintenance only: that is
+   where the jump was measured and where the owner order puts maintenance
+   above the loop. Other N>=2 limits (pack cut-out, SAFETY-73 refusal) keep
+   the old law. Rule 1 still silences them (the target is unmet), so they no
+   longer warn either.
+
+Fixing the windup was chosen over only ignoring the wound part, because at
+N>=2 the wound integrator moves real watts at hand-back. At N=1 there was
+nothing to fix: re-seeding already prevents windup.
+
+**What SAFETY-03/40 protect is kept.** With the loop in charge, the integrator
+bound still warns (a runaway, a house above the rating), and a saturated
+inverter under the loop's own command still does not alarm (SAFETY-03 AC 2):
+rule 2 grades only batteries another owner set.
+
+**The counter.** `ClampWatchdog.bound_episodes` counts episodes that had a
+bound engagement. The status row shows it ("N times since start").
+`bound` (cycles) stays for the log and the tests.
+
+**Re-pinned digests.** Every change is intended; nothing at N=1 moves a watt.
+
+| digest | what changed |
+|---|---|
+| s78 `n1_drain_owner` | the false clamp rows are gone from the log; commands identical |
+| s78 `n2_drain`, s84 `n2_charge`, `n2_charge_banked`, s79 `n2_maint` (test_peak_margin) | loop reason (`mode-bound`), integrator and loop claim while bounded; commands identical |
+| opt11 `n2_maint` (test_modes) | A drops out at t=1655 s: B follows the house at once, 8 cycles differ (max 920 W) |
+| s84 `n2_charge_dear` | A's pin lifts at t=1800 s: 400 W a cycle, not a 1390 W jump; the surplus step after it; 98 cycles |
+
+test_safety86's "without the ceiling the log floods" now needs the ceiling
+and the bound both removed: either one alone keeps the loop inside what the
+batteries can give. The `alarmed()` helpers in test_safety84/86 also read
+SAFETY-81's quarter stamp, because ALLOCATOR rows can push its row out of
+the 40-row log.
+
+**Review (PR #163).** The first draft graded each battery against last
+cycle's command and graded charges too. On plantsim's battery (10 s lag) at
+the live 2 s meter, every drain or charge start warned once, and an N=2 drain
+or HOLD under the peak guard with a stepping house warned 15 times an hour. A
+maintenance charge tapering near full warned 11 times in 50 min, which
+SAFETY-42 section 7 had ruled out. With the settle window and discharge only:
+0 in all of those cases. A battery that gives nothing still warns, lagging
+or not. At a hypothetical 20 s lag, it warns at most twice an hour. The cost:
+a battery that does not take a charge another owner set is not named by this
+alarm (the same gap SAFETY-42 states; the charge has its 36 h timeout).
+`test_safety85.py` part 7.
+
+**Not changed, open for the owner.**
+- With the loop in charge and the house above the batteries' total rating,
+  it still warns (SAFETY-40). On the rig's 2 x 2000 W N=2, most of SAFETY-84's
+  count came from houses of 4500 and 6500 W.
+- TEL-10's `Loop reason` reads `mode-bound` while the maintenance bound holds
+  the loop, with modes off. DOCS lists the value with both meanings.

goodwe_controller/DECISIONS/SAFETY-86-peak-over-hold.md

@@ -0,0 +1,47 @@
+# SAFETY-86 - the peak guard outranks the maintenance HOLD
+
+**Status: DECIDED 2026-09-30 (owner).** Follows SAFETY-83's "Not changed"
+list. Tests: `test_safety86.py`.
+
+**The defect.** The HOLD (battery resting full after the maintenance charge)
+is a SET of 0 W at `P_MAINTENANCE` (60), above the peak floor (`P_PEAK`, 50),
+so the floor did not bind. At N=1 a 6500 W house banked 6500 W quarters and
+'Load too high' fired (SAFETY-83 rig test, check 4). At N=2 only the other
+battery gave: 4500 W against a 3950 W aim (SAFETY-84 rig test, check 6).
+
+**The fix** (`main.py`, `_peak_over_hold()`).
+- N=1: during a HOLD a peak floor above 0 W is refiled at `P_MAINTENANCE`, as
+  for a drain (SAFETY-83). The battery gives the floor; the Why reads "raised
+  for the peak limit".
+- N>=2: the holding battery's pin is raised to the floor minus what the other
+  live batteries may place (their hard `hi`, or their pin). The others give
+  first, the holding one only the shortfall. Why this split and not the
+  allocator's shares: the hold is maintenance and outranks the others' use
+  (owner order), and the owner rule for an Off battery is the same, "give way
+  only for the shortfall". A battery Off by its mode (P_MODE, below
+  maintenance) therefore still gives before the holding one.
+- N>=2, while the holding battery gives: a site `hold` ceiling at the floor
+  (P_MAINTENANCE), so the loop does not ask for watts the hold keeps back.
+  Without it the moving pin re-logged the ALLOCATOR "could not be placed"
+  row each cycle and filled the action log (review, PR #161).
+- Below the aim nothing changes: the floor is 0 W, the hold is 0 W, the rows
+  are identical to before (test_safety86.py part 2).
+- A site stop (a SET above `P_PEAK`) decides alone: nothing is raised at N>=2,
+  and the refiled floor at N=1 stays under `P_SAFETY`. If another battery is
+  pinned to charge (a SAFETY-73 probe) the pin is not raised, so the site is
+  never split both ways.
+- The hold resumes by itself: the rule is evaluated each cycle, so when the
+  guard lets go the command is 0 W again.
+
+**The level dips below the target: the hold finishes anyway.** Owner
+decision 2026-10-01: the HOLD ends on its clock (`maintenance_hold_min`) even
+when the peak guard pulls the level down; no top-up. A top-up would re-enter
+CHARGE (up to 36 h, `CHARGE_TIMEOUT_MIN`) and keep the site's one maintenance
+slot meanwhile.
+
+**Not changed.**
+- The peak guard still grades the emptiest battery (SAFETY-32): at N=2 with
+  B under `peak_soc_floor` the floor is limited and A holds even when it is
+  full (SAFETY-87).
+- "Battery is not keeping up" during maintenance (SAFETY-85), the N=2 charge
+  flapping (SAFETY-88) and the N=1 charge headroom sizing are untouched.

goodwe_controller/DECISIONS/SAFETY-87-guard-uses-able-batteries.md

@@ -0,0 +1,83 @@
+# SAFETY-87 - the peak guard uses every battery that can still give
+
+**Status: DECIDED 2026-10-01 (owner card).** Follows SAFETY-86's "Not
+changed" list. Tests: `test_safety87.py`; identity:
+`tools/safety87_identity.py`.
+
+**The defect.** At N>=2 the guard graded the emptiest battery against the
+highest floor ([[SAFETY-32]] §3). One battery under `peak_soc_floor` made the
+whole site floor-limited: the claim asked for 0 W and the reserve alarm fired,
+even with the other battery full. Measured: a maintenance charge (A at 11 %)
+raised the alarm 10 times while both batteries gave 2000 W and the quarter
+landed on the aim (SAFETY-84 rig test, check 3); a HOLD (A at 99 %, B at
+15 %) left A at 0 W and banked 4051 W, raising the month peak (SAFETY-86
+review; rig case 7a: 4563.8 W).
+
+**The fix.**
+- `decide()` and its call are unchanged. At N>=2 `Controller._peak_on_able()`
+  then grades each battery on its own floor (`peakguard.reserve_split()`).
+  One at or under it is *held*. The others that are live and not refusing
+  (SAFETY-73) are *able*.
+- A floor-limited decision is re-taken on the able batteries
+  (`peakguard.place_on_able()`): their own permission (min SoC against max
+  floor, among them), and a floor of `min(need, able_w)`. `able_w` is their
+  rating plus the drain a held battery gives anyway (its maintenance pin).
+- The held batteries weigh 0 in the split while the site gives
+  (`arbiter.resolve(reserve=)`), so the floor lands on the able ones. During a
+  HOLD, a held battery is not counted among the "others" (`_peak_over_hold()`),
+  so the holding battery covers the need.
+- Floor-limited now means: some battery is held and the able ones cannot hold
+  the aim. The claim still asks them for `able_w`. The alarm fires only if
+  they miss the real limit at full power for `ALARM_HOLD_S`, the same test as
+  'Load too high' (`_reserve_short()`), so a one-cycle miss at a quarter's end
+  is not an alarm. With nothing able (all held, or the rest refusing or
+  dropped) it is the old state: 0 W, immediate alarm.
+- The alarm and the row name `held`, each battery graded on its own floor. The
+  old code named batteries against the site's highest floor.
+- Page: the two peak rows carry `runs`. A red `runs` row gives the banner its
+  title without "Not ready", and the Home page is not shown as held at 0 W.
+  Rows that do stop control still outrank it.
+
+**How SAFETY-32's concern is still covered.** SAFETY-32 took min(SoC) against
+max(floor) so the guard never sizes a forced discharge a battery's own BMS
+stops. Now no battery at or under its own floor is asked for the peak: it is
+graded on its own floor, and an unread SoC or unknown cut-out counts as held.
+The min/max pairing still decides permission, over the able batteries. The
+roster verdict `decide()` echoes (`soc`, `soc_floor`) is kept, so SAFETY-32's
+call-site and reduction checks still bite. What changed is only that one held
+battery no longer stops the others. One exception, with battery modes on: see
+Open.
+
+**Maintenance pins beside a held battery** (review). A draining battery that
+may still give is raised from its drain rate towards its rating for the peak
+floor, after the others (`_drain_over_reserve()`; peak > drain), else the
+floor's rest landed on the held battery. In a HOLD, a held battery counts its
+own pin (a drain) among the others, and a held battery pinned to charge stops
+the raise (never split both ways).
+
+**Before -> after** (test_safety87.py, rig of 2 x 2500 W, aim 3450 W):
+
+| case | before | after |
+|---|---|---|
+| charge, A 11 %, house 4500 | 3 reserve alarms, quarter 3450 | 0 alarms, 3450 |
+| HOLD, A 99 % / B 15 %, house 5500 | A 0 W, B 2488 W, 3 alarms | A 2054 W, B 0 W, 0 alarms, 3450 |
+| HOLD, house 6500 | A 0 W, B 2488 W, 4051 W | A 2500 W, B 0 W, 4014 W, 1 alarm (A alone is short) |
+| HOLD, month peak 4000, house 6000 | A 0 W, B 2488 W, 3551 W, alarms | A 2054 W, B 0 W, 3950 (peak - margin), 0 alarms |
+| both under the reserve | alarm | alarm (unchanged) |
+| N=1, every scenario | | byte-identical |
+
+**Open, for the owner.**
+- The loop still draws a held battery (SAFETY-25 option A: the reserve binds
+  the peak guard only). It gives last, after the able ones. So with house 6500
+  in the charge case, B alone cannot hold the aim, the alarm fires as
+  specified, and the loop then lands the quarter on the aim from A. The text
+  says "cannot keep … alone", not "will go over", so it stays true.
+- Battery modes on, A Off and B held: when B alone can place the floor, OPT-11
+  keeps A resting and B gives it. When B cannot, A gives first. Making Off give
+  before a held battery in the first case needs a third allocator tier. The
+  same at N=3: A Off, B held, C able, floor 4000 W gives C 2500, B 1500, A 0.
+  Until then, with modes on, a held battery can give for the peak.
+- The notification and row text live in `messages.py`, which has no NL layer
+  yet (UX-19). The Home page text, which has NL, is unchanged.
+
+**Not changed.** N=1. 'Load too high' (SAFETY-81). SAFETY-85, -88, -89, -90.

goodwe_controller/DECISIONS/SAFETY-91-held-battery-last.md

@@ -0,0 +1,74 @@
+# SAFETY-91 - a held battery is drawn only after the others are full
+
+**Status: DECIDED 2026-10-01 (owner: held battery last, SAFETY-25 option A
+kept).** Follows SAFETY-87. Tests: `test_safety91.py`.
+
+**The defect** (SAFETY-87 rig test, F1 and F2). At N>=2 a battery at or under
+its own peak reserve was held back (weight 0) only on cycles where the peak
+guard asked for power.
+- F1: B draining at 1000 W, A held at 15 %, house 5500. Once the grid was
+  near zero the loop set the target, A had its normal weight and B's drain
+  pin bound, so the loop drew A at 2500 W for the whole quarter (15.0 ->
+  10.7 %) while B stayed at 1000 W. In the next quarter A reached its
+  cut-out, and B stayed pinned at the peak floor (~2422 W), not its 2500 W.
+- F2: in a HOLD (A holding, B held), at a quarter's edge the guard saw a block
+  with no seconds left and asked for nothing for one cycle. The HOLD's
+  ceiling lapsed, A went back to 0 W and the loop's target went to B: 2500 W
+  for 1 s.
+
+**The fix** (`main.py`, N>=2 only).
+- `_held_back()`: the batteries at or under their own reserve while another
+  can still give (live, not refusing), graded as in `_peak_on_able()`. They
+  weigh 0 in every split where the site gives, not only for the peak. With
+  nobody able (all held, or the rest refusing or dropped) nobody is held back
+  and the split is as before.
+  Review: once held back, a battery stays so until its SoC reads more than 1
+  point above its reserve. A reading flipping 20/21 % otherwise swapped
+  ~1000 W between the batteries on each flip (grid +-500 W with A 10 s and
+  B 3 s lag). The guard's own permission (SAFETY-87) is unchanged.
+- `_drain_rise()`: while a battery is held back, a draining battery's pin
+  becomes a floor at its drain rate (`lo`), so it rises towards its rating
+  before the held one gives. Not for a held battery's own drain, not under a
+  site stop, not for a battery that is not live.
+- `tariff.next_quarter()`: past a block's end, before the next block's first
+  telegram, the guard grades the next quarter, projected from the held
+  reading (the averager credits it there). Not when that reading is too old
+  to be credited (`max_hold_s`).
+
+**What stays.** SAFETY-25 option A: once every able or draining battery is
+at full power, the loop still draws a held battery (`allocator._fill()`'s
+last-resort pass). With house 5500 and 2 x 2500 W, A still gives 2500 W
+after B is full. Nothing is placed on a battery at its cut-out: OPT-09's
+pack limit closes it (`hi = 0`), and the drain rise lets B take the rest.
+
+**Before -> after** (`test_safety91.py`, 2 x 2500 W, lagging battery 10 s):
+
+| case | before | after |
+|---|---|---|
+| B drain 1000, A held, house 4000 | A 2500, B 1000 | A 1500, B 2500 |
+| same, house 5500 | A 2500, B 1000 | A 2500, B 2500 (option A) |
+| cycles A asked while B not full | 612 of 900 | 0 |
+| A at its cut-out, house 5500: B | 1572 W mean | 2500 W, A 0 W |
+| HOLD, late telegram at the edge | A 0, B 2470 for 1 cycle | A 2050, B 0 |
+| idle, A held, house 2000 | A 1005, B 1005 | A 0, B 2020 |
+| N=1, every scenario | | byte-identical |
+
+**Why N>=2 only.** At N=1 there is no other battery to give first. The edge
+roll would also fix the N=1 one-cycle dip at a quarter's edge (SAFETY-86
+rig, "A dropped to 0 W for 1 s"), but this ticket keeps N=1 byte-identical;
+extending it is a one-line change for a later ticket.
+
+**Re-pinned.** `test_modes.py` `n2` and `n2_off`: from t=1600 battery A is
+at its 20 % reserve, so B carries the house and A gives last (100 of 540
+cycles differ). With SAFETY-87's held rule both are a5dddad's again, and the
+test grades that.
+Two fixtures changed with it: `test_safety87.py` part 10's "without the
+raise" run also turns off `_drain_rise()` (else B rises anyway), and
+`test_peakguard.py` 10g and `test_watchdog.py`'s two-inverter rig give
+their second battery a cut-out, as rule 8 requires (an unknown cut-out is held, so A alone would carry the cycle).
+
+**Not changed.** The peak guard's own rules (SAFETY-87). A drain with
+nobody held stays a pin (SAFETY-78). An Off battery beside a held one
+(SAFETY-87 Open). The first cycle after start, before any quarter is
+measured, can still put the loop's first step on a held battery in a HOLD.
+SAFETY-88, -89, -90, -92, -93, -94.

goodwe_controller/DECISIONS/SAFETY-93-charge-end.md

@@ -0,0 +1,60 @@
+# SAFETY-93 - the maintenance charge end hands back smoothly
+
+**Status: implemented 2026-10-02, for review.** Tests: `test_safety93.py`.
+
+**The defect** (SAFETY-85 rig test, check 4; also on 9358781). At N=2, when
+A's maintenance charge ended, B went 0 -> -1600 W in one cycle and charged
+from the grid with the house at 6000 W. The HOLD end was already smooth
+(SAFETY-85).
+
+**Cause.** During the charge the site target holds A's charge (SAFETY-84's
+`charge` ceiling, -2000 W). At the end A gets its HOLD pin (0 W), but the
+loop starts its next step from last cycle's site target. The slew limit
+moves the site total by 400 W (-2000 -> -1600), and the only battery left
+to place it on is B. The same happens when the charge times out or the
+battery is switched Off (A free, its -2000 W shared out). With the charge
+suspended by the guard and A giving under the loop, B took A's share in
+one step (675 W).
+
+**The fix** (`main.py`, `_reseed_charge_end()`, N>=2 only). On the cycle a
+battery leaves CHARGE, the loop's start point (`self.target`, and the
+integrator with it) is what the other batteries stood at plus that
+battery's new command: its pin (HOLD or abort, 0 W), or, if it is free, its
+last discharge (a charge stops). The loop then moves from there one slew
+step a cycle. The ending battery's own step (-2000 -> 0 W) is maintenance's
+pin, as before; it lowers the grid import. The end is kept until the loop
+next runs, so a missed poll on that cycle (the input hold) does not lose it.
+
+Review: a charge also ends, for the site, when the battery is still in
+CHARGE but can no longer be placed: a stale link or a refusal (SAFETY-73)
+drops it, and its -2000 W landed on B the same way (B 0 -> -1600 W at a
+1200 W house). So the end is noted after the unit claims are filed: a
+battery leaves the charge when it leaves CHARGE, is not live, or its own
+claims contradict. The guard suspending the charge (SAFETY-84) is no end.
+
+Why a start-point reseed, and not a per-battery slew in the allocator: the
+jump comes from one stale number at one edge, the kind of edge SAFETY-73
+(`_unit_refusal_end`) and OPT-11 P3 (`_reseed_run_edge`) already reseed.
+The change stays at that edge; nothing else at N>=2 moves.
+
+**Before -> after** (`test_safety93.py`, 2 x 2500 W, 10 s lag, 2 s meter):
+
+| case | before | after |
+|---|---|---|
+| rig case: house 6000, A charges 2000 to the end | B 0 -> -1600, charges 4 cycles | B 0 -> 400 -> 800 ..., never charges |
+| house 1200 | B 0 -> -1600 (2800 W from the grid) | B steps of 400, never charges |
+| charge times out / A switched Off | B 0 -> -1600 | B 0 -> 400 |
+| guard suspended the charge, A gives 1825 | B step 675 W | B step 395 W |
+| missed poll on the end cycle | B 0 -> -1600 a cycle later | B 0 -> 400 |
+| A dropped mid-charge (stale link, refusal), house 1200 | B 0 -> -1600 | B 0 -> 400 |
+| N=1, both charge ends above | | byte-identical |
+
+No pinned digest moved: the 46 digests of `tools/*identity*.py` (N=1 and
+N=2) are byte-identical to f3e409c; none of their scenarios reaches a
+charge end.
+
+**Not changed.** The peak guard's floor still moves the site in one step
+when it engages (a house step, a quarter edge): the guard outranks the slew
+(owner order). A HOLD pin still drops the holding battery to 0 W at once
+and SAFETY-86 gives way to the others first. SAFETY-88 (charge flapping
+above the aim) is untouched.

goodwe_controller/DECISIONS/SAFETY-94-lagging-battery.md

@@ -0,0 +1,102 @@
+# SAFETY-94 - a battery that lags or reverses is not frozen or refusing
+
+**Status: implemented 2026-10-03, for review.** Tests: `test_safety94.py`
+(rig: `tools/safety94_rig.py`). Also closes SAFETY-58. SAFETY-74 stays open.
+
+## The defects
+
+1. **Stale-reading gate (SAFETY-37).** Its 35 s ran from the register's last
+   change. After a rest that clock was already past 35 s, so the first read
+   after a new command tripped it, before the register could answer. Live
+   2026-10-03 (0.14.0, N=2): 17:39:16 B and 17:39:25 A (load ramp after a
+   rest), 19:00:04 A (drain start), 21:21:22 B (drain -> charge). Each was
+   1 s after its command; each register answered within 11 s. This is
+   SAFETY-58's shape.
+2. **Refusal at N=1 (SAFETY-52).** `compute()` engaged after `SETTLE_CYCLES`
+   frozen cycles if the reading was under 100 W at that moment. The frozen
+   cycles include a reversal through the battery's lag. At a 1 s meter the
+   12th cycle comes as a battery reversing out of a charge passes 0 W
+   (SAFETY-85 rig, O1: "gave -20 W for 13 cycles"). The refusal then held
+   0 W, the battery settled at 0 W, never gave 100 W, and waited for the
+   15-minute probe. N>1 already required 22 s in the band, so it was safe
+   at a 10 s lag but not at 20 s.
+
+## What changed
+
+- **The gate counts only time the register was asked to move**
+  (`freshness.Freshness._oblige`). A read counts the time since the last
+  read when, at that read, the command is 250 W or more and has moved 250 W
+  from where it stood at the register's last change. A register change
+  (or a SAFETY-57 release) restarts the count. A command flapping in and
+  out of the ask still adds up (frozen register, 0/1500 W every 5 s: trip
+  at 69 s). The conjunction, `MOVE_W` and `RELEASE_S` are unchanged.
+- **The bound is unchanged at 35 s and now means what its derivation
+  says.** The floor was always "how long a healthy register takes to answer
+  a command": 6 s plant + 10 s publish + 1 s read = 17 s. The band
+  `[2 x 17, 0.5 x 75] = [34, 37.5]` holds. Live answers measured: 1.4, 3,
+  6 and 11 s after the command.
+- **Refusal evidence is the same at every roster size**
+  (`main.Controller._gave_nothing`, SAFETY-73's count moved into a method).
+  The reading must stay under 100 W, one way, while asked over 200 W, for 12
+  cycles spanning 22 s. At N=1 `compute()` gets this as `gave_nothing` and
+  needs it on top of its own freeze test. `None` (compute alone) keeps the
+  old law.
+- **The evidence restarts when the reading moves 50 W towards the ask**
+  (`REFUSED_PROGRESS_W`). A refusing battery reads flat (-3/-4 W live). Live
+  readings wander by under 25 W at rest. A first-order lag crossing the band
+  gains 50 W in at most 0.4 tau, so it cannot fill 22 s unless tau > 54 s.
+  This also covers B, whose reading is 100 W below its power.
+
+## Bounds and worst-case catch
+
+| fault | before | after | budget |
+|---|---|---|---|
+| register frozen, then asked to move | 0-35 s after the ask (often 1 s) | 35 s after the ask (+1 read) | SAFETY-37: 35 s, under the 75/85 s consumer holds |
+| register frozen at rest reading ~0 W | stale 1 s after the ask | refused or stale, 0 W within 23-35 s | the same |
+| refusing battery, 1 s meter, N=1 | 11-16 s | 22-28 s | SAFETY-73's 22 s span (+ one 10 s publish) |
+| refusing battery, 2 s meter | 22-28 s | 22-28 s | unchanged |
+| refusing battery, 5 s meter | N=1 35-41 s, N=2 41-55 s | N=1 40-45 s, N=2 50-55 s | 12 cycles = 55-60 s |
+
+Rig: `test_safety94.py` part 3. A release after SAFETY-57 still exposes
+the held number for one 35 s window of asking, so 35 < 75 < 85 still holds.
+
+## Before -> after
+
+- Live replay (part 1): 4 trips -> 0.
+- Refusing B (its -100 W idle reading): see SAFETY-97.
+- Rig, 10 s lag, N=1 and N=2, 1/2/5 s meters, two register shapes, 48 runs
+  (part 2): before 27 stale trips and 1 refusal, after 0 and 0.
+- Reversals, lag 10 and 20 s, 1 s meter (part 2): before N=1 6 stale / 3
+  refused, N=2 6 / 1; after 0 / 0.
+- 16-day loop capture (`test_freshness.py` part 8): 93 trips -> 59. Trips
+  answered within 20 s: 21 -> 1. Two of the removed trips were not quick:
+  a register held 351 s under a command hovering at the 250 W travel edge
+  (under 35 s of asking before it moved; survivor 2's shape), and a
+  refusing battery the gate had caught only on a passing ramp (SAFETY-52's
+  refusal covers it).
+
+## SAFETY-58 and SAFETY-74
+
+- **SAFETY-58 is fixed** by this change: its card asks for the clock to
+  start with the obligation and for the bound to be re-derived. Both are
+  done above. `test_freshness.py` survivor 5 is now graded as closed.
+- **SAFETY-74 is not fixed.** A battery capped at 300 W with a perfectly
+  flat reading, 5 s meter, house stepping: 50 trips/h at N=1 and 80 at N=2
+  before, 37 and 60 after. With +-1 W dither: 0. A flat reading under a
+  command that moved is exactly what the gate is for; telling "limited"
+  from "frozen" needs a second signal (the meter, or SoC).
+
+## Known gaps
+
+- ~~B's standby offset (-95 to -118 W at idle) puts a refusing B outside the
+  100 W band, so a refusing B never latched (review F1: at N=1 new, at N=2
+  as before).~~ **Fixed by SAFETY-97 in the same PR:** the band is centred
+  on each unit's learned idle reading. `SAFETY-97-idle-offset.md`.
+- A command that asks only part of the time (a fraction d) is caught after
+  35 s of asking, which is 35/d s of wall time (0/1500 W every 5 s: 69 s).
+  SAFETY-30's per-unit check restarts when its command stops opposing the
+  held reading, which a lapsing ask normally does, so 35 < 85 holds there.
+  SAFETY-31's circulation check (75 s) ignores the command, so its margin
+  holds only while d >= 0.47.
+- A register frozen under a command that stays near the 250 W travel edge
+  is caught late or not at all (survivor 2).

goodwe_controller/DECISIONS/SAFETY-97-idle-offset.md

@@ -0,0 +1,118 @@
+# SAFETY-97 - "gives nothing" is graded against each battery's idle reading
+
+**Status: implemented 2026-10-04, folded into PR #171 (SAFETY-94), for
+review.** Owner decision 2026-10-04: the band's centre is clamped to
++-75 W (see Bounds). Tests: `test_safety97.py` (rig: `tools/safety94_rig.py`).
+Closes SAFETY-94 review finding F1.
+
+## The defect
+
+B's power reading (board B's `inverter_ac_power`, 0x0518) shows -95 to -118 W
+at idle: its standby draw (the GoodWe app shows 0 W). A's shows -2 to -4 W.
+Every "the battery gives nothing" test was `|reading| < 100 W`, so a refusing
+B sat on the band's edge and never latched:
+
+- N=2: never caught, before or after SAFETY-94.
+- N=1: the old one-instant check caught it in 17-105 s; SAFETY-94's shared
+  rule (12 cycles in the band in a row) never did (review probe, 1200 s).
+
+## Design
+
+- **Offset source: learned per unit** (`app/idle.py`, `Inverter.idle`). No
+  new option: a required one is a setup step every client gets wrong, and an
+  optional one is a second source to reconcile. An override can be added
+  later if a site needs one.
+- **When it learns:** control runs; the unit is not refused (unit or site),
+  stale or sign-tripped; its command has been within 50 W (`IDLE_ASK_W`) for
+  120 s (`IDLE_QUIET_S`, 6 lags of 20 s). A refusing battery is asked more
+  than 50 W, and while refused it does not learn, so its refusal cannot be
+  learned as idle. A capped battery under a big ask is not sampled either.
+- **How:** the first value is the mean of 120 s of samples; then it follows
+  drift with a 30 min time constant. A sample beyond 250 W (`IDLE_SAMPLE_W`)
+  is dropped (a register held at a giving value). The band is centred on
+  the value clamped to 75 W (`IDLE_MAX_W`; owner decision below).
+- **Restart:** saved per unit (`unit/<name>/idle_w`, on first learn and each
+  5 W move) and restored, clamped to 250 W. Without it a battery refusing from the
+  start is never quiet, so never learned, so never caught.
+- **Until learned the idle reading is 0 W**: the rule as it was.
+
+## Not chosen: the GoodWe LAN integration's DC battery power
+
+Both inverters also appear through HA's GoodWe integration (B:
+`sensor.kelder_dyness_battery_power`, 0 W at idle; found read-only on the
+live HA 2026-10-04). Pointing `batt_entity` at it removes B's offset by
+configuration, but:
+
+- the band must be safe without it: other installs may not have it;
+- it is polled over UDP on the inverter's Wi-Fi, a second channel that can
+  drop while the board keeps reading (HW-01 lost both once); a missing
+  reading stops the site;
+- SAFETY-37's 35 s bound is derived from the board's 10 s publish; the
+  integration's poll interval (believed 10 s, not checked here) and latency
+  are not measured;
+- DC power is not 0x0518, which SAFETY-30/31/42 were measured against.
+
+It stays an install choice to test on the rig, not a code change here. With
+it, the learned idle reading is simply ~0 W.
+
+## Where it applies
+
+Every test of "gives nothing / gives / takes" now uses `reading - idle`:
+
+| check | change |
+|---|---|
+| shared refusal evidence `_gave_nothing` (N=1 and N>=2) | centred |
+| N=1 engage and end in `compute()` (`idle_w`, the site sum) | centred |
+| N=1 end in `_refusal_update` | centred |
+| N>1 unit end (probe answered, takes the other way) | centred; uncentred, B's idle -100 W read as "takes 100 W" and ended a charge refusal at once |
+| stale-path refusal (`_refusal_from_stale`, N=1 and N>1) | centred |
+| SAFETY-42 "parked" (small ask, gives nothing) | centred |
+| SAFETY-37 stale gate | unchanged: it grades register changes against command travel, not a level |
+| SAFETY-57 release | unchanged: it reads the command only |
+| SAFETY-30 per-unit sign | unchanged: opposition needs both over 250 W; B's 100 W idle cannot make or hide one alone |
+| SAFETY-42 shortfall | unchanged: B reads ~100 W short at every power, which errs towards reporting (report only) |
+
+## Bounds: owner decision 2026-10-04 (review R1)
+
+Band: `|reading - centre| < 100 W`, centre = idle clamped to +-75 W.
+
+- **Why a clamp under the band.** A wrong idle reading (taught during a
+  rest while the reading shows something else, e.g. a grid top-up of a unit
+  held at 0 W, or restored onto a swapped inverter) more than about 100 W off
+  hid every refusal on that battery, at N=1 and N=2; with the first +-250 W
+  clamp the rig missed a refusing A whenever the error was 110-250 W. At
+  +-75 W the band always keeps 0 W +-25 W, so a battery reading about 0 W
+  while refusing is caught whatever was learned or restored, and a wrong idle
+  cannot refuse a healthy 0 W battery (its ask is over 200 W).
+- **The trade-off.** Options: keep +-250 W (covers idle readings to about
+  +-350 W, any 100 W mis-learn hides refusals); clamp to +-75 W (chosen);
+  "old band or centred band" (rejected: a correct B would need to give 200 W
+  to answer its 200 W probe).
+- **Cost.** A battery whose idle reading is beyond about +-170 W is centred
+  at most 75 W out, so its refusal falls outside the band: it behaves as in
+  0.14.0 (not caught by this rule). B (-95 to -118 W) reads 20-43 W from its
+  clamped centre. B is caught across -150..+90 W of error in its idle
+  reading; learned 110 W or more too high it is missed, as in 0.14.0 at N=2.
+- A frozen register is still caught by the stale gate at 35 s of asking.
+- Recovery from a wrong value needs quiet time: tau 30 min.
+
+## Catch times (rig, refusing from 200 s after a 400 s rest, +-4 W)
+
+| refusing | meter 1 s | 2 s | 5 s |
+|---|---|---|---|
+| A, N=1 | 28 s (before 28) | 28 (28) | 65 (65) |
+| A, N=2 | 28 (28) | 28 (28) | 110 (110) |
+| B, N=1 | 28 (never) | 28 (never) | 65 (never) |
+| B, N=2 | 24 (never) | 24 (never) | 60 (never) |
+
+A at N=2 on a 5 s meter is 110 s here because the rig's grid goes flat once
+A is cut, so the loop cycles on the 15 s floor; the same run on the PR before
+SAFETY-97 gives 110 s. B restored after a restart, refusing from the start:
+24 s; with nothing saved: never.
+
+## Before -> after
+
+- Healthy B with its offset, SAFETY-94's four scenarios, N=1 and N=2, 1/2/5 s
+  meters, both register shapes, idle learned or restored (96 runs): 0 stale,
+  0 refused. Reversals, lag 10/20 s, idle restored: 0.
+- Live replay (SAFETY-94 part 1): 0 trips (the gate is untouched).

goodwe_controller/DECISIONS/TEL-12-several-pv-inverters.md

@@ -357,3 +357,5 @@ the bump is PKG's call. The material an entry needs is this file.
 
 The option surface moves **76 keys → 77**, one new optional key, `pv_entities`,
 empty on every install that does not set it.
+
+**Superseded in part (UX-08, 2026-09-27):** the PV status rows no longer read 0.11.0's sentences at one entity. The owner ruled out entity ids on status rows, so 2/5 now holds for the control document only. See `UX-08-short-notifications.md`, phase 2b item 3.

goodwe_controller/DECISIONS/UX-02-two-config-surfaces.md

@@ -148,6 +148,11 @@ exits 78 and the panel goes with it. Recovery is the Configuration tab. That is
 the reason it stays, and the reason the panel refuses to write a blob the
 validator rejected: this surface must never be the thing that removes itself.
 
+*Amended by [[UX-15-setup-only-mode]] (2026-09-28):* one refused configuration
+keeps the panel: options that name no inverter at all and have no other
+refusal, which is what a new install ships. The add-on then serves the page in
+setup-only mode and commands nothing. Every other refusal still exits 78.
+
 **The panel shows fewer refusals than the startup gate can, never more.** Two
 of `validate.py`'s rules compare a configured ceiling against the setpoint
 device's *own* reported range, which is only knowable by asking Home Assistant.

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

@@ -0,0 +1,92 @@
+# UX-08 phase 2a: short notifications, and what moved out of them
+
+The owner decided on 2026-09-27: a title of at most about 5 everyday words and a one-sentence body. A red safety alarm may use up to 3 sentences, so no action-relevant information is lost. Titles are neutral, with no "GoodWe:" prefix. HA entity ids appear only in refusals. The rule is `STYLE.md` at the repository root, the texts are in `app/messages.py`, and `test_messages.py` enforces both. The detail each notification used to carry is in DOCS.md under "Notifications", and the body links to it.
+
+**Unchanged:** every `notification_id`, every trigger and cadence (edges, SAFETY-34 re-announce, per-unit ids), every log line and every status row. The status banner and rows are phase 2b, refusals and option texts 2c, logs 2d; `ux08_allowlist.txt` lists them until then.
+
+## Where a choice was made
+1. **Severity of "not delivering" (SAFETY-42).** The notification is an *alarm*, so it may use 3 sentences. Its log line is ERROR and the alarm is latched. The page banner stays amber, as SAFETY-42 decided, because control keeps running; the two answer different questions (is control running / must a person act) and HA shows no colour on a notification. The three checks stay in their original order. Clearing it takes stop then start, and the body says so.
+2. **Figures left the bodies** of the frozen-meter card (the rail and the command), the circulating-power card (the watts and the time window) and the peak cards (the projection). None of them is needed to act, and all of them are still in the reason text that the log line and the status row carry. `test_freeze.py` and `test_watchdog.py` now pin that. The frozen-meter card can therefore no longer quote a wrong rail (SAFETY-20), because it quotes none.
+3. **The over-rating alarm keeps its numbers** (asked, sent, and which limit cut it), because they are what a fault report needs. `ClampWatchdog.facts` carries them under the same keep-the-bug rule as `reason`, so the words and the numbers always describe the same tick, with asked before sent (SAFETY-40, `test_clamp.py` part 6).
+4. **SAFETY-25 stays in the peak-reserve alarm** as its last sentence ("the reserve only limits peak shaving … down to its cut-out level"). The alarm now gives each branch its own action: at the reserve, lower it; battery level unread, check the sensor; floor unknown, set the cut-out level. That last branch is `soc_floor is None`, which happens when an inverter's cut-out level is missing, not the peak reserve (that option always has a value). Before, every branch said "lower peak_soc_floor". The title, "Battery stopped limiting the peak", is true on all three branches.
+5. **SAFETY-32 at a roster of one.** The body no longer ends in a separate "WHICH PACK" paragraph. The pack's name is part of the first sentence ("The battery of inverter-b …"), and at a roster of one that is the only difference.
+6. **Dropped as background, now in DOCS:** "charging stays blocked" (peak reserve), "why no other guard fired" (circulating power, not delivering), and the saturation-freeze distinction (over-rating). "The meter cannot see this" stays in the circulating-power card, as the owner asked.
+7. **The Details link** opens the add-on's documentation page (`/hassio/addon/<slug>/documentation`, with the slug taken from the container hostname) and names the section. A `#heading` anchor was not used because nobody has checked that Home Assistant's documentation tab renders heading ids; if it does, adding one is a one-line change. Outside an add-on container it names the section without a link.
+
+# Phase 2b: status rows and page banners
+
+Every row of the Commissioning list and every banner is now in `app/messages.py` (`row_*`, `banner_*`), and `test_messages.py` checks a rendering of each. The row and banner kinds are gone from `ux08_allowlist.txt` (200 → 168 entries). DOCS.md "Status page" explains the rows. **Unchanged:** every row's colour (ok / warn / bad), which rows show when, and the banner cascade order.
+
+## Where a choice was made
+1. **A red row may use 3 sentences (30 words).** STYLE.md gave rows 15 words; the owner allows red safety states 3 sentences. A red row needs room for what happened, the state (0 W) and how it clears. STYLE.md now says so, and the test applies it by colour.
+2. **Figures left the rows, not the product.** The reason texts (freeze, sign, circulating, delivery, peak guard) carry reason codes and limits; they stay on the ERROR/WARNING log line and the event list, as before. Rows keep the numbers a reader acts on: the stall age and the 0 W deadline, the meter age and limit, asked and sent for an over-rating, the peak limit, and "opposite for 12 of 60 seconds" while a check counts. So 2a item 2 ("also on the status row") no longer holds, and DOCS.md says "in the add-on log".
+3. **No entity id on any row**, even the green ones that used to print `sensor.x = 54`. The sensor rows name the setting (*Battery power for inverter-b*). Solar sources are numbered in the order of the settings list (*source 2 of 3*, *entry 1 of the reversed-sign list*). This retires TEL-12's rule that a one-entity site reads 0.11.0's sentence byte for byte. A `tools/tel11_pv_trace.py --compare` against a pre-UX-08 tree therefore shows the PV rows as changed telemetry, and the control documents stay equal. The per-source watts and units left the multi-source row. The total, the count and which source is missing remain.
+4. **UX-07 item 1.** `ClampWatchdog` now also counts `over_rating` and `bound` separately. After an episode, each count shows under its own alarm's title ("Power request too high: 2 times since start, not now", "Battery is not keeping up: …"). A site with both gets two amber rows where it had one.
+5. **The "Not ready" banner** is the first red row's own `banner`, or else its first sentence. The peak-reserve and over-rating rows set `banner` to their notification title. The three trips keep their own banner branches, reworded (e.g. "Inverters worked against each other. Every inverter is set to 0 W.").
+6. **How a latch clears stays on the row**, shortened: "Only starting control clears this", "A restart does not clear this", "only stopping and starting control clears this" (not delivering). SAFETY-25's sentence stays on the peak-reserve row.
+7. **Rows got an `id`** (`meter_frozen`, `direction`, `pv`, …), so tests find a row by what it is, not by its words. The page ignores it.
+8. **Left for later:** texts that rows embed from other modules and that were not flagged as rows (the month-peak line, `peakguard.explain()`, the liveness and stale notes, `shadow.banner()`). The month-peak row only lost its semicolons.
+
+# UX-09: fixes after the phase 2a test
+
+1. **The Details link follows the Home Assistant version.** HA 2026.2 added the built-in `app` panel (core #157554, frontend #28245), whose add-on pages are `/config/app/<slug>/documentation`. 2026.5 stopped registering the `hassio` panel, so `/hassio/addon/<slug>/documentation` is a 404 there (TEST-23, HA 2026.9.1). 2026.1 and older have only the old path. The one path valid on both, `/_my_redirect/supervisor_addon?addon=<slug>`, opens the Info tab, not Documentation. So the add-on reads its slug (`GET /addons/self/info`) and the HA version (`GET /info`) at start, and picks the path. An unknown version gets the current path. The hostname stays as a fallback for the slug. Phase 2a item 7 is replaced by this.
+2. **Shadow mode says "would".** The over-rating alarm and row said "sent X W" while 0 W was on the wire, and the peak alarm said "the battery is giving all it can". Both now take `shadow=`, and in shadow mode say what would have been sent and that the inverters stay at 0 W. Severity, id and cadence do not change with the mode.
+3. **"Controller" is gone from texts.** "The add-on" names who decides, and "control" names what it does, as in the existing "start control". The add-on is what the reader sees in Home Assistant, and "controller" was easy to confuse with the control board.
+4. **One term per setting, matching its label.** Four labels changed instead of the texts, because the texts' words were plainer: “Peak reserve (%)” (was "Peak guard will not discharge below"), “Battery level entity (%)” (was "Battery charge level"), and “Solar production entity / entities, per inverter / Reversed-sign solar entities” (was "PV …"). The Dutch labels already said "Zonneproductie". Option descriptions are phase 2c and were not changed, so some still say "PV".
+5. **The shadow banner and the inverter notes** are now `messages.banner_shadow()` and `row_no_setpoint` / `row_not_controllable` / `row_commands_refused`, so `test_messages.py` checks them. The red shadow banner no longer lists the latches, because 12 words cannot carry them. It says a safety stop stays on, and each latch keeps its own red row, which names it and says how it clears. The colour of a liveness row now comes from `is_live()`, not from matching "NOT COMMANDABLE" in the text.
+6. **DOCS "Notifications" and "Status page"** are written for a home owner, and the card ids, keys and log detail moved to a "For installers" part of each.
+
+# UX-08 phase 2c: refusals, error texts and option texts
+
+Validator refusals, the parse errors they carry, and every option name and description are now short. No rule, key, schema, default or exit code changed. Over 36 spoiled configurations the old and new validators refuse the same number of times. The allowlist went from 167 entries to 43, and only log lines (phase 2d) remain on it.
+
+1. **A refusal names the setting by its label and then its key**, as `messages.setting()` writes it: “Inverter rating” (max_w). The key has to stay, because `configui.problems_by_field()` shows a reason beside every key its text names. A test checks each label against en.yaml. A few reasons no longer mention keys they only named in passing, such as `price_markup_eur_kwh` in the withdrawn-provider reason, so the panel shows those reasons beside fewer settings. Each reason still names the setting that fixes it. A setting of one inverter in the list is written “Inverter rating” for inverter-b (inverters.max_w), so the panel shows it beside `inverters`, where that value is changed, and not only beside the flat `max_w` that a list does not read.
+2. **Citations moved to DOCS.** Option descriptions say "Measured value, leave it unchanged" or similar, and the record behind the value is under "For installers: where the numbers come from". The UX-01 citation check in `test_translations.py` now checks the tab for that instruction and DOCS for the record.
+3. **What left the refusals:** the shipped default in the peak-reserve reason, the superseded-default note in the levy-table reason (DOCS already covers it), the endpoints of the withdrawn providers (DOCS "Energy price providers"), the plant measurement behind `slew_w` (DOCS, beside the setting), and the leg-specific paragraphs of the tariff-formula errors. Each reason keeps the rejected value, the limit and what to change.
+4. **Not rewritten:** errors that only a code defect can raise, such as plugin-contract and argument-type checks in `price.py`, `price_forecast.py`, `static_tariff.py`, `arbitrage.py` and `main.py`, which a home owner never reads. INFO lines such as the tariff-formula preview were also left.
+
+# UX-08 phase 2d: log lines, the rest of the status page, and DOCS
+
+The allowlist is empty and its cap is 0 (43 → 0). Every WARNING and ERROR line is one plain line of at most 25 words, with no card ids, capitals or semicolons (the semicolon rule now covers log lines too). **Unchanged:** every log level, every trigger and cadence, every notification id, every row's colour and when it shows, the banner cascade, and every refusal count.
+
+1. **No code prefixes on log lines.** Nothing outside the repositories greps them, except `/home/homelab/clampwatch.sh`, a one-off site watch from 2026-09-05 that greps `OUTPUT_CLAMP` and `Engagements so far`. `OUTPUT_CLAMP` is still in the reason the line quotes; "Engagements so far" is now "Cut back N times so far". The tests that found a line by its card id (`SAFETY-37`, `SAFETY-44`, `CONTROL LOOP DIED`, `UNGRADED`) now find it by its words.
+2. **Reason texts keep their codes.** A line quotes a watchdog's reason (`%s`), such as `STALE_READING: …` or `OUTPUT_CLAMP: …`. Those are the evidence an installer searches for and many tests pin them, so they were not rewritten. The line around them is plain.
+3. **Reasoning moved to DEBUG, not deleted,** for the 10 lines marked DROP-to-DEBUG (for example the 14 768 W history behind the over-rating alarm, why SAFETY-42 reports and does not act, and the Eneco card advice). The 25-word line keeps the action and the numbers. SAFETY-57's promise stays on the ERROR line, as an ordered pair: "until it changes, or 17 s after the command drops below 250 W".
+4. **The line under the buttons** showed the newest raw action-log entry (`OUTPUT_CLAMP …`, `FAILSAFE …: SIGN_DISAGREEMENT`, `ALLOCATOR …`). Each `log_event()` call now also names a plain hint from `messages.HINTS`, and the page shows that. The action log itself is unchanged, because tests and later analysis read it, and the page no longer shows it. It stays reachable as `events` in the `status` JSON (review of #136), because some entries are written nowhere else: a dropped inverter's reason, the unplaced watts, the peak guard's projection and the shadow decision.
+5. **The top table.** *Why* is `messages.why()`: the arbiter's winner and limit in words ("Keeping the grid near zero: 440 W, held back by the peak limit"). `self.reason` keeps `Resolution.explain()` for the log and the checks. *Tariff*, *Price history*, *Arbitrage* and *Shadow mode* keep every figure TARIFF-11 and SAFETY-47 put there, each in its own slot, in words. Labels: *Battery level*, *Solar production*, *Power request*.
+6. **The month-peak row became two rows**, because one sentence of 15 words cannot hold the peak, its time, its share of the limit and TARIFF-13's coverage figure. The store's state at start (`restore_state`) left the row: it is the INFO line at start.
+7. **The peak guard rows** name the projection first and the limit second, as before (SAFETY-38). The blind row says what it means for the owner: the battery does not charge until the period can be measured again.
+8. **Wording that changed meaning-carrying words**: "command and meter point opposite ways" is now "the power went the wrong way" (banner) and "…went against what the add-on asked" (row). The N=1 banner still names the meter, the N≥2 texts still say "own power". The inverter range reads "up to 5 000 W each way" instead of "-5 000 W to 5 000 W".
+9. **Refusals are counted as shown.** Setting placeholders are expanded to label and key, and the long cases the 2c test found are driven through the validator. Seven refusals were shortened. The card refusals no longer show `c_eur_per_kwh`, `vat_pct` or "its own card", and a text that does not parse says "not valid near character N" instead of the parser's words. A missing value shows as *empty*, not `None`.
+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,104 @@
+# 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.
+- P4: the setup wizard draws the same model by each field's `wizard` step.
+  Its tables (`KETTLE`, `SHADOW`) are in `uilayout.py`, and its live checks
+  are rules, so they are in `validate.py` (`setup_checks`). settings.js still
+  names no key. See [[UX-13-setup-wizard]].
+- P5: the page words are in `app/ui_text/en.json` and `nl.json`, one key set,
+  loaded by `app/uitext.py` with an English fallback per key. The page picks
+  Dutch when the browser's language is `nl`, as the classic page does. Home's
+  sentences moved from `homeview.py` into `home_words`, so `/status?lang=nl`
+  builds them in Dutch. Status rows, banners, hints and validator sentences
+  (`messages.py`, `validate.py`) stay English: they are shared with
+  notifications, the log and the start refusal. `test_ui_text.py` checks both
+  files against STYLE.md and each other, using the rules in
+  `tools/style_rules.py`, which it shares with test_messages.py.
+- P5: "Other time windows" is a list editor (`ui.periods`, control
+  `period_list`). `uimodel._periods_json()` builds `static_profile` and names
+  the first bad time, empty price, overlap or gap. Its tiling rule matches
+  `static_tariff._check_tiling`. A stored profile whose days the editor has no
+  choice for (for example "mon,wed") is still kept as stored and edited in the
+  Configuration tab. Supervisor 2026.08.0's `AppOptions` accepted all 133
+  wizard blobs, 17 of them with time windows
+  (`tools/ux13_wizard_blobs.py --supervisor`, run offline on 2026-09-28).
+- P3: Settings, Simple draws the fields the table marks `simple`, with an
+  optional `note` under each (words in `settings.simple.note`), plus the
+  batteries' switches and modes. Those are store state set through the
+  existing `/action` values, not options, so the table places no key for
+  them. The Batteries screen's Now, Today and Why lines are built in
+  `homeview.py` from what the add-on knows this cycle; the plan per mode is
+  OPT-11 P3/P4, so until then Today says "Not planned yet" when no block
+  is planned for the battery (`test_batteries_screen.py`).
+
+## 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/DECISIONS/UX-13-setup-wizard.md

@@ -0,0 +1,101 @@
+# UX-13 P4 — the setup wizard, and when it opens by itself
+
+**Status: DECIDED 2026-09-28 (P4 dev; the design and mockup were approved
+2026-09-27).** Card 6ab979852f3eca02fb40f69e. Builds on
+[[UX-13-one-layout-table]]. Design note: `goodwe-session/UX-13-design.md` §1, §3.6.
+
+## 1. What the wizard is
+
+The Setup tab draws the Installer view's page model one step at a time: a
+field is on step *n* when its `uilayout.Field` says `wizard=n`. It uses P2's
+controls, `/config/validate` and `/config/save`. No route was added.
+`uilayout.py` holds what a field cannot say: the kettle table (`KETTLE`), the
+optional step and the shadow switch (`SHADOW`). Step 5 has no battery modes
+yet (OPT-11); it says they come later.
+
+A step moves on when no refusal is anchored to one of its shown fields
+(`uipage.step_problems`). A refusal on a hidden field, a field on no step or
+no field at all blocks the last step, which lists every refusal.
+
+## 2. When it opens by itself (`uipage.setup_needed`)
+
+The page opens `#setup` only when it is opened with no route, and only when
+`/config/model` gives a reason:
+
+- **`no_power_request`**: the stored options name no inverter to control.
+- **`first_start`**: this boot found no `/data/state.json` (`Store.fresh`), the
+  Store has no `setup_done` and no `auto` key, and control is not started.
+  `auto` is the key Start/Stop writes. Neither the startup gate's exit 78 nor
+  setup-only mode (UX-15) writes the Store, so a new install's first good boot
+  is fresh.
+
+"Never started" alone is not enough: both TEST-23 add-ons have `auto_start`
+off and no `auto` key, and one has run in shadow for weeks (review of PR #146,
+R1). So a Store read from a file is an old site, and it is never sent to the
+wizard. A new install that restarts before the page is opened is not sent
+either, and its Setup tab still works. A site that runs control, or ever
+started or stopped it, is never sent. Without a Store the answer is no. The wizard's save writes
+`setup_done` (an ISO time) to the Store. A save from the Installer view does
+not.
+
+**Decided since, in [[UX-15-setup-only-mode]] (owner, 2026-09-28):** a
+brand-new install ships `setpoint_entity: ""`, and it no longer exits 78. When
+naming no inverter is the gate's only refusal, the add-on serves the page in
+setup-only mode, which commands nothing, and the wizard opens with
+`no_power_request`. Setup-only mode writes no Store file, so the first-run
+rule above still holds for an install set up on the Configuration tab.
+
+## 3. The kettle test and the sign checks
+
+Step 1 reads the meter's entities now (`GET ha/entities?entity=`, one
+`hass.state()` read, in W) before and after a kettle is switched on. The
+change, not the sign, decides: a rise of at least 500 W keeps `meter_invert`
+off, a fall turns it on. For a net entity or import and export, a fall cannot
+be fixed by an option, so the step is not passed and the page says what to
+check. A meter the add-on reads itself (HomeWizard, MQTT) cannot be read by
+the page, so the test is skipped and Home shows the direction after the
+restart. The installer may skip the test, because a cloud can fake a fall;
+the last step then warns, and after a fall it says the reading went down.
+
+The battery and solar signs cannot be forced from the page, which never
+commands an inverter. The last step reports each battery's reading with its
+direction ("reads 800 W charging now, so check the inverter shows the same")
+and warns when a solar entity reads below zero without its "reads negative"
+switch. It also warns when meter + solar + battery, all known, add up to a
+house using less than -300 W: a battery sensor reversed while giving power.
+An idle or charging battery cannot be judged that way.
+
+## 4. The last step
+
+`validate.setup_checks()` sits beside the rules because it names option keys.
+It reads nothing itself: `web.py` passes a Home Assistant entity list at most
+5 s old, the running options, the running meter reading and today's price
+count. Tiers are ok, info, warn and bad. A power request entity missing from
+Home Assistant is **bad**, because a write to it is answered 200 (SAFETY-77)
+and only the entity list can tell. So is Home Assistant not answering, since
+the list is then unknown. The wizard does not save while anything is
+bad. It then saves through P2's path (`setup: "done"`) and asks for the
+restart as the second, confirmed request, with a dialog that names the 0 W.
+The shadow switch is on by default and writes `shadow_mode: on`, which holds
+every inverter at 0 W after a restart even if control is started. Off keeps the
+stored value, or `auto` if that was `on`. The switch goes only on the model the
+wizard posts, never into the page model the Installer view also saves.
+
+## 5. The stale save lists only what moved (P2 test, finding a)
+
+`/config/model` remembers the last 16 blobs it handed out, by fingerprint. On a
+stale save the add-on compares that blob with what is stored now, so the banner
+lists only the other surface's changes. `changed` (stored against the posted
+blob) is unchanged for the classic page's "theirs → mine" list. When the
+fingerprint was not handed out by this process, it falls back to `changed`.
+
+## 6. How it is held
+
+- test_setup.py: the steps and tables, the kettle logic (and the page's copy of
+  it), step blocking, the first-run rule on new and TEST-23 sites, the live
+  checks, the save through the P2 path, the stale fix, and the words.
+- tools/ux13_wizard_blobs.py produces every blob the wizard can save from a new
+  install and three TEST-23 sites (88 accepted by the shipped validator).
+  UX-15 added the shipped defaults as a start (setup-only mode). At P4
+  all 88 were accepted by Supervisor 2026.08.0's `AppOptions`, offline, 78
+  keys each.

goodwe_controller/DECISIONS/UX-15-setup-only-mode.md

@@ -0,0 +1,114 @@
+# UX-15 — setup-only mode: a new install serves the wizard
+
+**Status: DECIDED 2026-09-28 (owner decision; UX-15 dev).** Card
+6aba0053d27a32cb3f210dcc. Changes the CFG-01 startup gate and closes the open
+question in [[UX-13-setup-wizard]] §2. Amends [[UX-02-two-config-surfaces]] §4.
+
+## 1. The rule
+
+`config.yaml` ships `setpoint_entity: ""`, so a new install's options are
+refused by rule 1 of `validate_startup_config()`: no inverter to control.
+Until now that was exit 78 before any page was served, and the installer had
+to fill in the entity on the Configuration tab before the wizard could open.
+
+The add-on now starts in **setup-only mode** when, and only when
+(`setuponly.applies()`):
+
+- the options name no inverter at all: no flat `setpoint_entity` and no
+  `inverters` entry, and
+- rule 1's refusal (`no_power_request_problem()`) is the gate's **only**
+  refusal.
+
+In setup-only mode it serves the page, says it is in setup (banner, `/status`
+`setup_only: true`, a WARNING log line) and opens the wizard when the page is
+opened with no route (`setup_needed` is `no_power_request`). After the
+wizard's save and restart the normal gate applies to the saved options.
+
+## 2. What still exits 78, and why
+
+Everything else the gate refuses, including:
+
+- a complete configuration that is refused, e.g. `maintenance_charge_w` above
+  `max_w`;
+- no power request entity **and** any other refusal;
+- an `inverters` list whose entry has a blank power request entity.
+
+These are configurations somebody edited. The Configuration tab stored them,
+the log's refusal banner names each problem, and the tab is where they are
+fixed (UX-02 §4). Serving the wizard there would put a six-step setup in
+front of someone who needs to change one field. A narrow rule also keeps the
+setup-only decision to one comparison against one known sentence, so a new
+validator rule cannot widen it by accident: any other refusal fails the
+equality and exits 78.
+
+The cost: an installer who first sets, say, a DSMR meter with no entities on
+the Configuration tab and leaves the power request entity empty gets exit 78,
+not the wizard. The log then names both fields.
+
+## 3. Why it cannot command
+
+Setup-only mode builds nothing that commands. `amain()` branches to
+`setuponly.serve()` before the MQTT broker, the controller, the meter task and
+the tariff task are built, and it returns from there when the Supervisor
+stops it. What serves the page is `SetupOnly`, which holds no inverter.
+
+Three checks make it structural rather than a convention:
+
+1. **The HomeAssistant is read-only** (`HomeAssistant(read_only=True)`).
+   `call()` refuses before it sends anything, and every service call goes
+   through it: `number.set_value` (`set_number()`), notifications, all of
+   them. The flag is fixed at construction, and there is no setter.
+2. **`SetupOnly` refuses a HomeAssistant that can write, and `Controller`
+   refuses one that cannot.** So neither can be built on the wrong one.
+3. **`/action` answers 409** in setup-only mode, before
+   `handle_action()`. Start, Stop and the battery cycle do nothing.
+
+No MQTT client is created, so nothing is published. The page's other routes
+already read only, or write the add-on's own options (UX-02 §6).
+
+Setup-only mode writes no Store file. The wizard's save writes `setup_done`,
+as in any mode. So a new install that is set up on the Configuration tab
+instead still has a fresh Store on its first normal boot, and the first-run
+rule (UX-13 §2) sends it to the wizard as before.
+
+## 4. How it is held
+
+- `test_setup_only.py` part 1: when it applies, including the three exit-78
+  cases above. Part 2: the read-only write path refuses with nothing sent,
+  and the two constructors refuse. Part 3 boots the real `main()` on the
+  shipped defaults against a fake Supervisor and Home Assistant over HTTP and
+  logs every request: the page is served, `/status` says setup-only, Start
+  and the cycle get 409, and there are 0 service calls and no MQTT request,
+  also with `auto_start` on and a Store that says control was started. The
+  wizard's save is then booted: it passes the normal gate, does not open the
+  wizard again, and every write is 0 W (shadow). Part 4: the refused
+  configurations exit 78 and serve nothing.
+- Mutations, each red: `applies()` always false or always true, the
+  read-only refusal removed, the Controller's check removed, `amain()` giving
+  setup-only mode a writable HomeAssistant, `/action`'s 409 removed, and the
+  `return` after `serve()` removed.
+- TEST-23 (PR #147 review, 2026-09-28): the add-on image on the shipped
+  defaults and an empty `/data` made 0 service calls and no MQTT request in
+  3.5 minutes of setup-only mode, counted in both the stand-in and the rig
+  shim logs. The wizard save then passed Supervisor 2026.08.0's `AppOptions`,
+  and after the restart it ran in shadow: 11 of 11 writes were
+  `set_value 0.0`.
+
+## 5. The wizard fixes in the same card
+
+- **F1.** `/config/validate` converts what it can of a page model
+  (`uimodel.ui_to_options_partial()`), so a conversion error blocks its own
+  step beside its field and the live checks still run on the rest. A refusal
+  about a key the failed conversion writes is left out, because it would
+  judge the stored value. The save still refuses such a model (422, with
+  `steps`).
+- **F2.** A save from the page model sends `base`, the model it opened. The
+  add-on writes only the keys whose value differs from `base`, onto the blob
+  stored now (`uipage.only_edits()`). So "save again to keep yours" after a
+  409 keeps the other surface's changes. A key both surfaces changed takes
+  this page's value, which is what the second press after the banner means.
+- **Meter entity.** On the last step a meter entity Home Assistant does not
+  have is red, like a missing power request entity, so a skipped kettle test
+  cannot let it through. In the Installer view it stays a warning.
+- **Step 1 after a skip.** When the kettle test saw the reading fall and was
+  then skipped, step 1 says the reading went down. The skip stays (UX-13 §3).

goodwe_controller/app/allocator.py

@@ -98,6 +98,12 @@ DROP_STALE = "stale link"
 DROP_CONTRADICTION = "contradicts itself"
 DROP_NO_INTEGER = "no integer setpoint in its interval"
 
+# OPT-11: why a unit's MODE layer was not applied this tick. Only the first is
+# a fault; the other two are the rule working.
+MODE_FAULT = "mode range leaves out 0 W"
+MODE_RELEASED = "mode released by a higher claim"
+MODE_OUTRANKED = "hard limit leaves no room for the mode"
+
 REFUSE_SCOPE = "mis-routed claim"
 REFUSE_EMPTY = "no unit available"
 REFUSE_SIGN = "opposite directions"
@@ -213,6 +219,10 @@ class Allocation:
     # that calls `plan()` for its arithmetic gets None and does not care;
     # main.py stamps every record it puts on the write path.
     tick: int | None = None
+    # OPT-11: ((unit, why), ...) for each unit whose mode range left out 0 W
+    # this tick. That mode was dropped (see `unit_interval()`); main.py logs it
+    # as a software fault. Empty on every tick without a mode.
+    mode_faults: tuple = ()
 
     @property
     def ok(self) -> bool:
@@ -246,11 +256,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()})")
@@ -290,6 +300,99 @@ class Allocation:
         return out
 
 
+def unit_interval(b, deciding_priority=None):
+    """OPT-11. `(lo, hi, note)`: the interval a unit is allocated into.
+
+    The hard limits (`b.lo`, `b.hi`) always apply. The unit's MODE range
+    (`b.mode_lo`, `b.mode_hi`) narrows them unless `deciding_priority` is
+    above the mode's own priority (arbiter._unit_modes() passes None when the
+    modes hold, and the yielding limit's priority when they give way). `note` says why the
+    mode did not apply, or is None when it did or there is none:
+
+    * MODE_FAULT: the mode range leaves out 0 W. A mode may forbid a direction
+      and never force one, so this is a software fault and the mode is dropped.
+      It is what keeps REFUSE_SIGN unreachable from a mode: the fill below
+      moves every free unit away from 0 in ONE direction, and it starts from 0
+      only while every interval holds 0.
+    * MODE_RELEASED: a higher claim (the peak floor) decided the target.
+    * MODE_OUTRANKED: the hard limits and the mode do not overlap. The hard
+      limits win, as they always do.
+
+    A unit without mode fields (`mode_priority` absent or None) gets its hard
+    limits, unchanged: that is every unit when battery modes are off.
+    """
+    lo, hi = b.lo, b.hi
+    prio = getattr(b, "mode_priority", None)
+    if prio is None:
+        return lo, hi, None
+    mlo, mhi = b.mode_lo, b.mode_hi
+    if not (mlo <= 0.0 <= mhi):
+        return lo, hi, MODE_FAULT
+    if deciding_priority is not None and deciding_priority > prio:
+        return lo, hi, MODE_RELEASED
+    nlo, nhi = max(lo, mlo), min(hi, mhi)
+    if nlo > nhi:
+        return lo, hi, MODE_OUTRANKED
+    return nlo, nhi, None
+
+
+class _Narrowed:
+    """A unit's bounds with its interval replaced by `unit_interval()`'s."""
+    __slots__ = ("lo", "hi")
+
+    def __init__(self, lo, hi):
+        self.lo, self.hi = lo, hi
+
+
+def pin_w(b):
+    """The watts a unit's own SET places once held inside its hard limits,
+    as `plan()` places a standing pin, or None when the unit has no SET."""
+    pv = getattr(b, "pinned_w", None)
+    if getattr(b, "gate", None) is None or pv is None:
+        return None
+    lo, hi = _int_envelope(b)
+    return float(pv) if lo > hi else float(_clamp_int(round(float(pv)), lo, hi))
+
+
+def hi_w(b):
+    """A unit's upper hard limit as `plan()` narrows it to whole W (SAFETY-84)."""
+    return float(_int_envelope(b)[1])
+
+
+def loop_bound(bounds, live=None):
+    """OPT-11. `(lo, hi)`: what the units can place when the LOOP decides.
+
+    The sum, over live units that do not contradict themselves, of each unit's
+    interval with its mode applied (`unit_interval()` with no higher claim). A
+    pinned unit adds the span from 0 to its pin, so a probe or a maintenance
+    pin stays reachable. Every term holds 0, so the sum does too.
+
+    `compute()` keeps the site target inside this, so the loop never asks for
+    watts no battery may give: the allocator would report them as unmet and the
+    saturation freeze would park the target on them (SAFETY-73 section 1).
+    Pure, like `plan()`: it reads numbers and intervals and nothing else.
+    """
+    lo_sum, hi_sum = 0.0, 0.0
+    for u in sorted(bounds):
+        b = bounds[u]
+        if live is not None and u not in live:
+            continue
+        if getattr(b, "contradiction", False):
+            continue
+        p = pin_w(b)
+        if p is not None:
+            lo_sum += min(0.0, p)
+            hi_sum += max(0.0, p)
+            continue
+        lo, hi, _ = unit_interval(b)
+        lo, hi = _int_envelope(_Narrowed(lo, hi))
+        if lo > hi:
+            continue
+        lo_sum += min(0.0, lo)
+        hi_sum += max(0.0, hi)
+    return lo_sum, hi_sum
+
+
 def _int_envelope(b):
     """A unit's interval, narrowed to the integers a 1 W register can hold.
 
@@ -385,7 +488,8 @@ def _fill(order, weights, cap, amount):
 
 
 def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
-         site_priority=None, site_key="site", tick=None) -> Allocation:
+         site_priority=None, site_key="site", tick=None,
+         deciding_priority=None) -> Allocation:
     """Divide the site grid target `target_w` across the units in `bounds`.
 
     `bounds`   unit name -> that unit's interval for THIS TICK (arbiter stage 1,
@@ -411,6 +515,9 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
     `site_priority` the priority of the SITE claim that chose `target_w`. It is
                what a unit's own winning SET is weighed against - see PINS.
     `site_key` the name to use when there are no units at all.
+    `deciding_priority` OPT-11: the priority that decided `target_w`
+               (`Resolution.deciding_priority`). Each unit's mode range applies
+               only at or below it - see `unit_interval()`. None applies them.
     `tick`     an opaque token identifying the tick this record is FOR, handed
                straight back on the record. SAFETY-28's write gate compares it
                against the tick it is writing on, so that a record cannot be
@@ -497,6 +604,7 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
     dropped = []
     ilo, ihi = {}, {}
     considered = []
+    mode_faults = []
     for u in units:
         b = bounds[u]
         if live is not None and u not in live:
@@ -512,7 +620,12 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
             # has no interval to allocate into.
             dropped.append((u, DROP_CONTRADICTION))
             continue
-        lo, hi = _int_envelope(b)
+        # OPT-11: the mode layer, when it applies, narrows the hard limits.
+        # A unit with no mode gets exactly its hard limits, as before.
+        nlo, nhi, note = unit_interval(b, deciding_priority)
+        if note == MODE_FAULT:
+            mode_faults.append((u, MODE_FAULT))
+        lo, hi = _int_envelope(_Narrowed(nlo, nhi))
         if lo > hi:
             # An interval that contains no integer. The register is 1 W, so
             # there is no number this unit could be commanded that both bounds
@@ -526,7 +639,7 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
         return Allocation(
             target_w=float(target_w), sum_w=sum_w, shares={}, plans=(),
             dropped=tuple(dropped), unmet_w=sum_w, quantisation_w=quant,
-            refused=why, tick=tick)
+            refused=why, tick=tick, mode_faults=tuple(mode_faults))
 
     # --- REFUSAL 2: nobody is available ------------------------------------
     if not considered:
@@ -659,4 +772,5 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
 
     return Allocation(target_w=float(target_w), sum_w=sum_w, shares=shares,
                       plans=tuple(plans), dropped=tuple(dropped),
-                      unmet_w=int(unmet), quantisation_w=quant, tick=tick)
+                      unmet_w=int(unmet), quantisation_w=quant, tick=tick,
+                      mode_faults=tuple(mode_faults))

goodwe_controller/app/arbiter.py

@@ -76,6 +76,12 @@ from . import allocator
 P_SAFETY = 100        # stopped, inputs missing, shutting down, device limits
 P_MAINTENANCE = 60    # maintenance owns the actuator outright (drain, hold)
 P_PEAK = 50           # capacity-tariff peak shaving - costs real money
+# The order in effect: safety limits and the SAFETY-73 refusal > the peak
+# guard > maintenance > modes > trade > loop. A peak floor above a drain still
+# binds: the `drain` site floor at N>=2 (SAFETY-78), refiled at P_MAINTENANCE
+# at N=1 (SAFETY-83); over a HOLD, `_peak_over_hold()` (SAFETY-86).
+# A cheap-window charge is suspended while the peak guard holds and, at N>=2,
+# sized to the quarter's headroom (SAFETY-84).
 P_MAINT_SHAPE = 40    # maintenance shaping the loop (charge-only)
 # OPT-04. §10.1 priority 3 - price arbitrage. ⚠️ ITS POSITION IS THE SPEC, NOT A
 # preference: P_PEAK (50) is ABOVE it so clause 2 lets the capacity-tariff floor
@@ -86,8 +92,17 @@ P_MAINT_SHAPE = 40    # maintenance shaping the loop (charge-only)
 # because trading against the meter is the entire point - the grid-following
 # loop would otherwise cancel every charge the moment it created import.
 P_ARBITRAGE = 30      # price arbitrage - trades against the meter on purpose
+# OPT-11. A battery's mode (Solar first, Leftover solar, Off): a SOFT unit
+# limit, kept apart from the hard ones. Above arbitrage, so a trade stays inside
+# each battery's mode; below the peak guard, to which a mode gives way only as
+# far as the floor needs (`_unit_modes()`, `_site_mode()`).
+# DECISIONS/OPT-11-battery-modes.md.
+P_MODE = 35
 P_LOOP = 10           # ordinary grid-following
 
+# The one source filed at P_MODE. pre_resolve() keeps it out of the hard limits.
+MODE_SOURCE = "mode"
+
 SET = "set"
 LIMIT = "limit"
 
@@ -175,6 +190,22 @@ CLAIM_SCOPE = {
     # the banner and the claim an install has had since SAFETY-02 shipped.
     # `Controller.cycle()` does not even arm the site detector there.
     "sign_site": SCOPE_SITE,
+    # main.py: `Claim.limit("drain", P_MAINTENANCE, lo=...)`, SAFETY-78. At
+    # N>=2, while a pack's maintenance drain is pinned, the site target may
+    # not go below what that pin places: below it a sibling would have to
+    # charge against the drain (circulation, refused, 0 W). A site `lo`,
+    # never filed at N=1. DECISIONS/SAFETY-78-drain-at-two.md.
+    "drain": SCOPE_SITE,
+    # main.py: `Claim.limit("charge", P_MAINT_SHAPE, hi=...)`, SAFETY-84. The
+    # mirror of `drain` for a cheap-window maintenance charge at N>=2: the site
+    # target may not go above what the charging pack's own `hi` asks, or a
+    # sibling would have to give against it. Never filed at N=1.
+    # DECISIONS/SAFETY-84-charge-at-two.md.
+    "charge": SCOPE_SITE,
+    # main.py: `Claim.limit("hold", P_MAINTENANCE, hi=...)`, SAFETY-86. While a
+    # holding pack gives the peak shortfall at N>=2, the site target stays at
+    # the peak floor, what the pin and the others place. Never filed at N=1.
+    "hold": SCOPE_SITE,
 
     # --- UNIT: about one pack, one inverter, one device -------------------
     # main.py: `Claim.limit("device", P_SAFETY, self.dev_min, self.dev_max,
@@ -226,12 +257,25 @@ 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
     # this pack to its floor, charge this pack to full, recalibrate this pack's
     # coulomb counter. Two packs recalibrate on their own schedules.
     "maintenance": SCOPE_UNIT,
+    # main.py: `Claim.limit("mode", P_MODE, lo, hi, ...)`, OPT-11. THIS
+    # battery's mode, chosen per battery by its owner. A unit claim that never
+    # enters a `lo > hi` test with a site limit: stage 1 keeps it apart from the
+    # hard limits, and it gives way to a site limit above P_MODE only as far as
+    # that limit needs (`_unit_modes()`). At N=1 it routes to the site, and
+    # `resolve()` takes it out of stage 2 for the same reason.
+    "mode": SCOPE_UNIT,
 }
 
 
@@ -359,6 +403,13 @@ class UnitBounds:
     pinned_w: float | None = None
     pinned_by: str | None = None
     contradiction: bool = False
+    # OPT-11: the mode layer, APART from `lo`/`hi` above, which stay the hard
+    # limits. `mode_priority` is None when no mode claim applies. Whether the
+    # mode binds is decided at stage 3 (`allocator.unit_interval()`), because it
+    # depends on the priority that decided the SITE target.
+    mode_lo: float = -inf
+    mode_hi: float = inf
+    mode_priority: int | None = None
 
     def explain(self) -> str:
         if self.contradiction:
@@ -404,6 +455,15 @@ class Resolution:
     # rules drifting apart: this is set by the same line that picks the winner
     # `explain()` names.
     winner_priority: int | None = None
+    # OPT-11. The higher of the winning set's priority and the priority of the
+    # limit that bound `target_w`. Whether the modes hold is decided from the
+    # limits themselves (`_site_mode()`, `_unit_modes()`): a mode gives way
+    # only as far as a limit above it (the peak floor) needs, so a mode `hi`
+    # never meets a site `lo`.
+    deciding_priority: int | None = None
+    # OPT-11 at N=1: why the site's mode layer was dropped this tick, or None.
+    # At N>1 the same fact is on `allocation.mode_faults`, per unit.
+    mode_fault: str | None = None
 
     def explain(self) -> str:
         """One line an operator can act on - this is the point of the module."""
@@ -427,7 +487,8 @@ def pre_resolve(unit_claims: list) -> UnitBounds:
     of the fault this card removes, and the reason `resolve()` partitions rather
     than filters twice.
     """
-    sets = sorted((c for c in unit_claims if c.kind == SET),
+    sets = sorted((c for c in unit_claims
+                   if c.kind == SET and c.source != MODE_SOURCE),
                   key=lambda c: c.priority, reverse=True)
     gate = pinned_w = pinned_by = None
     if sets:
@@ -435,19 +496,30 @@ def pre_resolve(unit_claims: list) -> UnitBounds:
 
     lo, hi = -inf, inf
     lo_src = hi_src = None
+    # OPT-11: a mode claim never joins the hard limits, so a mode cannot make a
+    # unit contradict itself or narrow a pin. A mode SET is not a thing: only
+    # limits are read. The lowest mode priority is kept (the first to release).
+    mode_lo, mode_hi, mode_priority = -inf, inf, None
     for c in unit_claims:
         if c.kind != LIMIT or (gate is not None and c.priority < gate):
             continue
+        if c.source == MODE_SOURCE:
+            mode_lo, mode_hi = max(mode_lo, c.lo), min(mode_hi, c.hi)
+            mode_priority = (c.priority if mode_priority is None
+                             else min(mode_priority, c.priority))
+            continue
         if c.lo > lo:
             lo, lo_src = c.lo, c.source
         if c.hi < hi:
             hi, hi_src = c.hi, c.source
     return UnitBounds(lo, hi, lo_src, hi_src, gate, pinned_w, pinned_by,
-                      contradiction=lo > hi)
+                      contradiction=lo > hi, mode_lo=mode_lo, mode_hi=mode_hi,
+                      mode_priority=mode_priority)
 
 
 def allocate(target_w: float, bounds: dict, *, weights=None, live=None,
-             scope_errors=(), site_priority=None) -> tuple:
+             scope_errors=(), site_priority=None,
+             deciding_priority=None) -> tuple:
     """STAGE 3. THE SEAM, AND SINCE ALLOC-01 IT IS OCCUPIED. `(shares, allocated)`.
 
     ⚠️ THE ALLOCATOR ITSELF IS `app/allocator.py` AND THE REASONING LIVES THERE.
@@ -485,11 +557,13 @@ def allocate(target_w: float, bounds: dict, *, weights=None, live=None,
     """
     return allocate_record(target_w, bounds, weights=weights, live=live,
                            scope_errors=scope_errors,
-                           site_priority=site_priority)[:2]
+                           site_priority=site_priority,
+                           deciding_priority=deciding_priority)[:2]
 
 
 def allocate_record(target_w: float, bounds: dict, *, weights=None, live=None,
-                    scope_errors=(), site_priority=None, tick=None) -> tuple:
+                    scope_errors=(), site_priority=None, tick=None,
+                    deciding_priority=None) -> tuple:
     """`allocate()` plus the record - `(shares, allocated, allocation)`.
 
     `tick` is SAFETY-28's freshness token: it identifies the tick the record is
@@ -501,7 +575,7 @@ def allocate_record(target_w: float, bounds: dict, *, weights=None, live=None,
     rec = allocator.plan(target_w, bounds, weights=weights, live=live,
                          scope_errors=scope_errors,
                          site_priority=site_priority, site_key=ACTUATOR_SITE,
-                         tick=tick)
+                         tick=tick, deciding_priority=deciding_priority)
     return rec.shares, rec.ok, rec
 
 
@@ -538,23 +612,30 @@ def site_resolve(claims: list) -> Resolution:
     considered = [f"{c.source}:{c.kind}" for c in claims]
 
     if lo > hi:
+        # OPT-11: 0 W here, and every limit that took part counts as deciding.
         return Resolution(0.0, winner.source, bound_by=None,
                           contradiction=True, considered=considered,
-                          winner_priority=winner.priority)
+                          winner_priority=winner.priority,
+                          deciding_priority=max(winner.priority,
+                                                lo_src.priority,
+                                                hi_src.priority))
 
     target = max(lo, min(hi, winner.value))
     bound_by = None
+    deciding = winner.priority
     if target != winner.value:
         binder = lo_src if target == lo else hi_src
         if binder is not None:
             bound_by = f"{binder.source}({binder.reason})" if binder.reason else binder.source
+            deciding = max(deciding, binder.priority)
 
     return Resolution(float(target), winner.source, bound_by, False, considered,
-                      winner_priority=winner.priority)
+                      winner_priority=winner.priority,
+                      deciding_priority=deciding)
 
 
 def resolve(claims: list, *, units=None, weights=None, live=None,
-            tick=None) -> Resolution:
+            tick=None, reserve=()) -> Resolution:
     """The three stages, in order, over one cycle's claims.
 
     `units` is the site's roster of inverters. Left None it is derived from the
@@ -600,6 +681,12 @@ def resolve(claims: list, *, units=None, weights=None, live=None,
     written down.
     """
     site_claims = [c for c in claims if c.actuator == ACTUATOR_SITE]
+    # OPT-11: a mode claim on the site (N=1, where every source routes there)
+    # never enters stage 2's `lo > hi` test. It is applied after it, below, by
+    # the same release rule stage 3 uses.
+    site_modes = [c for c in site_claims if c.source == MODE_SOURCE]
+    if site_modes:
+        site_claims = [c for c in site_claims if c.source != MODE_SOURCE]
     if units is None:
         units = {c.actuator for c in claims if c.actuator != ACTUATOR_SITE}
     units = tuple(sorted(units))
@@ -611,6 +698,8 @@ def resolve(claims: list, *, units=None, weights=None, live=None,
     # STAGE 2 - the site claims become the grid target. At N=1 `site_claims` IS
     # `claims`, so this is the shipped arbiter on the shipped list.
     out = site_resolve(site_claims)
+    if site_modes:
+        _site_mode(out, site_modes, site_claims)
 
     # STAGE 3 - the seam, and since ALLOC-01 the allocator behind it.
     #
@@ -643,10 +732,132 @@ def resolve(claims: list, *, units=None, weights=None, live=None,
     # nothing. See `packshare.weights()` on the residual this leaves (the fill's
     # own direction can differ from the target's sign under a pin, in which case
     # the weighting is a worse preference and still cannot be unsafe).
+    # OPT-11: whether each unit's mode holds this tick (`_unit_modes()`).
+    # Before the weights, because a limit above the modes may move the target.
+    gate, held = _unit_modes(out, site_claims, bounds, live)
     if callable(weights):
         weights = weights(out.target_w)
+    # SAFETY-87/91: units under their peak reserve weigh 0 while the site
+    # gives, so the others carry the target first. An Off battery gives the
+    # peak's shortfall, so it goes before them when no other unit is left.
+    reserve = set(reserve) if out.target_w > 0.0 else set()
+    if held and reserve and not set(bounds) - held - reserve:
+        held = set()
+    held = held | reserve
+    if held:
+        weights = {u: (0.0 if u in held else
+                       (1.0 if weights is None else weights.get(u, 1.0)))
+                   for u in bounds}
     out.shares, out.allocated, out.allocation = allocate_record(
         out.target_w, bounds, weights=weights, live=live,
         scope_errors=out.scope_errors, site_priority=out.winner_priority,
-        tick=tick)
+        tick=tick, deciding_priority=gate)
     return out
+
+
+def _limits_above(site_claims: list, prio: int) -> tuple:
+    """OPT-11: `(lo, lo_src, hi, hi_src)` over the site LIMITs above `prio`.
+
+    These are what a mode may never take the site target outside of: the peak
+    guard (P_PEAK), maintenance shaping (P_MAINT_SHAPE) and the hard limits.
+    """
+    lo, hi = -inf, inf
+    lo_src = hi_src = None
+    for c in site_claims:
+        if c.kind != LIMIT or c.priority <= prio:
+            continue
+        if c.lo > lo:
+            lo, lo_src = c.lo, c
+        if c.hi < hi:
+            hi, hi_src = c.hi, c
+    return lo, lo_src, hi, hi_src
+
+
+def _yield_to(out: Resolution, t1: float, above: tuple):
+    """OPT-11: the target `t1` the modes allow, moved only as far as the limits
+    above the mode need (`_limits_above()`). Returns the claim that moved it,
+    or None when `t1` already satisfies them, and sets `out.target_w`."""
+    lo, lo_src, hi, hi_src = above
+    t2 = max(lo, min(hi, t1))
+    out.target_w = float(t2)
+    if t2 == t1:
+        return None
+    binder = lo_src if t2 == lo else hi_src
+    out.bound_by = (f"{binder.source}({binder.reason})" if binder.reason
+                    else binder.source)
+    out.deciding_priority = max(out.deciding_priority or binder.priority,
+                                binder.priority)
+    return binder
+
+
+def _site_mode(out: Resolution, modes: list, site_claims: list) -> None:
+    """OPT-11 at N=1: the one battery's mode bounds the SITE target, after stage 2.
+
+    A SET above the mode (a safety stop) decides alone. Otherwise the target is
+    clamped into the mode range and then back into the site limits above the
+    mode, so the mode gives way only as far as those limits need: a peak floor
+    of 2000 W over an Off battery asks it for 2000 W, whether a trade or the
+    loop won stage 2, and a charge the peak guard merely caps stays at 0 W. A
+    range without 0 W is a software fault that drops the mode
+    (`out.mode_fault`). Clamping one number cannot contradict anything.
+    """
+    out.considered = out.considered + [f"{c.source}:{c.kind}" for c in modes]
+    lims = [c for c in modes if c.kind == LIMIT]
+    if not lims or out.contradiction:
+        return
+    lo = max(c.lo for c in lims)
+    hi = min(c.hi for c in lims)
+    prio = min(c.priority for c in lims)
+    if not (lo <= 0.0 <= hi):
+        out.mode_fault = f"mode range [{lo:.0f}, {hi:.0f}] leaves out 0 W"
+        return
+    if out.winner_priority is not None and out.winner_priority > prio:
+        return
+    before = out.target_w
+    t1 = max(lo, min(hi, before))
+    if _yield_to(out, t1, _limits_above(site_claims, prio)) is None \
+            and t1 != before:
+        c = lims[0]
+        out.bound_by = f"{c.source}({c.reason})" if c.reason else c.source
+
+
+def _unit_modes(out: Resolution, site_claims: list, bounds: dict, live):
+    """OPT-11 at N>1: `(gate, held)` for stage 3.
+
+    `gate` is the `deciding_priority` handed to the allocator: None applies
+    every unit's mode, a number above P_MODE releases them. `held` is the set
+    of units whose mode holds them back in the target's direction; while the
+    modes are released they weigh 0, so they carry only what the other units
+    cannot (the allocator's last-resort pass).
+
+    The rule matches N=1: a SET above the mode decides alone. Otherwise the
+    target is clamped into what the units can place with their modes
+    (`allocator.loop_bound()`) and back into the site limits above the mode.
+    If that point is still placeable with the modes, they hold and the target
+    is unchanged (what they cannot place is reported unmet, as before). If a
+    limit above the mode needs more, the target moves only that far, and the
+    modes are released for it.
+    """
+    mode_units = [u for u, b in bounds.items()
+                  if getattr(b, "mode_priority", None) is not None]
+    if not mode_units or out.contradiction:
+        return out.deciding_priority, set()
+    prio = min(bounds[u].mode_priority for u in mode_units)
+    if out.winner_priority is not None and out.winner_priority > prio:
+        return out.deciding_priority, set()
+    clo, chi = allocator.loop_bound(bounds, live)
+    t1 = max(clo, min(chi, out.target_w))
+    before = out.target_w
+    binder = _yield_to(out, t1, _limits_above(site_claims, prio))
+    if binder is None:
+        out.target_w = float(before)
+        return None, set()
+    held = set()
+    for u in mode_units:
+        b = bounds[u]
+        nlo, nhi, note = allocator.unit_interval(b)
+        if note is not None:
+            continue
+        if (nhi < b.hi) if out.target_w > 0 else (nlo > b.lo):
+            held.add(u)
+    return binder.priority, held

goodwe_controller/app/arbitrage.py

@@ -262,10 +262,8 @@ def threshold_eur_kwh(opts: dict) -> float:
     v = float(price_option(opts, "cycle_cost_threshold_eur"))
     if not math.isfinite(v) or v < 0:
         raise ValueError(
-            f"cycle_cost_threshold_eur is {v!r}. It is what a round trip COSTS, "
-            f"in EUR/kWh, so it is non-negative and finite - a negative "
-            f"threshold is one every spread clears, which is arbitrage with the "
-            f"brake removed.")
+            f"“Battery cycle cost” (cycle_cost_threshold_eur) is {v!r}. Set "
+            f"it to 0 or more, in EUR/kWh.")
     return v
 
 

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

@@ -73,6 +73,7 @@ An alarm wired only to this module's `ClampResult.engaged` would therefore be
 silent on the exact configuration the whole ticket is about. The winding is
 visible one layer up, at the integrator bound, and that is why `Decision` now
 carries `i_clamped` / `clamped` BOOLEANS and the caller ORs them in here.
+They alarm in different words: see `loop_clamp_note()` (SAFETY-40).
 
 AND WHY BOOLEANS RATHER THAN `Decision.reason`. `reason` is a single string that
 later stages overwrite: a cycle that clamps the integrator and is then slew
@@ -141,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"
@@ -200,9 +203,8 @@ REASON_CODE = "OUTPUT_CLAMP"
 # ceiling rests on one number a test author chose; if that number is ever
 # revisited, this constant moves with it.
 #
-# ⚠️ THIS IS A STOP-GAP AND DOES NOT MAKE THE ALARM CORRECT. The message still
-# calls the integrator bound a BUG SIGNAL and still pairs a request from one
-# moment with a `self.target` read at another - SAFETY-40. Nothing here is
+# ⚠️ THIS WAS A STOP-GAP; the wording and the numbers were SAFETY-40's, fixed
+# in `loop_clamp_note()` below. Nothing here is
 # suppressed: every engagement is still counted, the action-log row is written on
 # every engaged cycle regardless, and the rising edge of every episode alarms
 # unconditionally, so no alarm is DROPPED - only delayed.
@@ -234,6 +236,62 @@ CLEAR_CYCLES = 3
 SUSTAINED_CYCLES = 3
 
 
+# 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 software fault. Every number is the
+    decision's own, i.e. from the tick that clamped.
+    """
+    if d.clamped:
+        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 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 shortfall_note(named) -> str:
+    """SAFETY-85: the alarm text while another owner sets the batteries.
+    `named` is `[(inverter name or None, asked W, given W)]`, one per battery
+    that gave less than asked."""
+    return f"{REASON_CODE}: " + ", ".join(
+        f"{name or 'the battery'} gives {given:+.0f} W of the {asked:+.0f} W "
+        f"asked" for name, asked, given in named)
+
+
+def delivery_short(asked_w, given_w, margin_w) -> bool:
+    """SAFETY-85: did a battery asked to discharge give more than `margin_w`
+    less? A charge is never short: a full pack tapers (SAFETY-42 section 7)."""
+    asked, given = float(asked_w), float(given_w)
+    return asked > 0.0 and asked - given > abs(float(margin_w))
+
+
+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.
@@ -250,10 +308,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:
@@ -333,32 +393,80 @@ class ClampWatchdog:
     def __init__(self):
         self.active = False
         self.engagements = 0      # every engagement, never deduplicated
+        # UX-08: the same count split by alarm type, so the status page names
+        # each with its own alarm's title after the episode clears.
+        self.over_rating = 0      # bug=True: "Power request too high"
+        self.bound = 0            # bug=False: "Battery is not keeping up"
         self.episodes = 0         # rising edges
+        # SAFETY-85: episodes with a bug=False engagement. The status row
+        # counts these; counting cycles read 861 on one rig run.
+        self.bound_episodes = 0
+        self._bound_counted = False
         self.since: datetime | None = None
         self.last_alarm: datetime | None = None
         self.reason = ""
+        # UX-08: the numbers behind `reason`, for the notification - set under
+        # the same rule as `reason`, so both always describe the same tick.
+        self.facts = ()
         self.clean_cycles = 0
         # SAFETY-41. Consecutive engaged cycles, and whether THIS episode has
         # spoken yet - the two the escalation clause needs.
         self.run_len = 0
         self.spoken = False
+        # SAFETY-40. Did this episode include a genuine over-rating (`bug`), and
+        # has THAT spoken? A bug has its own budget, so anti-windup notices can
+        # never delay it; with bug=True throughout, cadence is as before.
+        self.bug = False
+        self.bug_spoken = False
+        self.last_bug_alarm: datetime | None = None
 
-    def note(self, engaged: bool, reason: str, now: datetime) -> bool:
+    def _due(self, last, now) -> bool:
+        return last is None or (now - last).total_seconds() >= REASSERT_S
+
+    def _speak(self, now, bug) -> bool:
+        self.last_alarm = now
+        self.spoken = True
+        if bug:
+            self.last_bug_alarm = now
+            self.bug_spoken = True
+        return True
+
+    def note(self, engaged: bool, reason: str, now: datetime,
+             bug: bool = True, facts=()) -> bool:
         """Advance one cycle. True when the caller should raise the alarm.
 
         `now` is the caller's clock, the same discipline as
-        `SignWatchdog.evaluate()` and `FreezeWatchdog.evaluate()`.
+        `SignWatchdog.evaluate()` and `FreezeWatchdog.evaluate()`. `bug` False
+        is the integrator bound (SAFETY-40): counted and notified like the
+        rest, but it never replaces a bug's text within an episode.
         """
         if engaged:
             self.engagements += 1
+            if bug:
+                self.over_rating += 1
+            else:
+                self.bound += 1
             self.clean_cycles = 0
-            self.reason = reason
             self.run_len += 1
-            if not self.active:
+            rising = not self.active
+            if rising:
                 self.active = True
                 self.since = now
                 self.episodes += 1
                 self.spoken = False
+                self.bug = False
+                self.bug_spoken = False
+                self._bound_counted = False
+            if not bug and not self._bound_counted:
+                self._bound_counted = True
+                self.bound_episodes += 1
+            if bug or not self.bug:
+                self.reason = reason
+                self.facts = tuple(facts)
+            self.bug = self.bug or bug
+            if bug and not self.bug_spoken and self._due(self.last_bug_alarm, now):
+                return self._speak(now, True)
+            if rising:
                 # ⚠️ SAFETY-41. THE RISING EDGE IS RATE-LIMITED TOO, and it did
                 # not used to be. It fired unconditionally, so a condition that
                 # engages and clears repeatedly raised one notification PER
@@ -384,11 +492,8 @@ class ClampWatchdog:
                 # still written on every engaged cycle, and a genuine runaway -
                 # which by definition keeps engaging - is picked up by the
                 # re-assert path within REASSERT_S. Delay, not loss.
-                if (self.last_alarm is None
-                        or (now - self.last_alarm).total_seconds() >= REASSERT_S):
-                    self.last_alarm = now
-                    self.spoken = True
-                    return True
+                if self._due(self.last_alarm, now):
+                    return self._speak(now, self.bug)
                 return False
             # ⚠️ THE ESCALATION. An episode that has not yet spoken because the
             # budget was spent by an EARLIER, unrelated episode speaks anyway
@@ -396,15 +501,10 @@ class ClampWatchdog:
             # engages every cycle and reaches it; the scattered one-cycle
             # railing that produced the live flood never does.
             if not self.spoken and self.run_len >= SUSTAINED_CYCLES:
-                self.last_alarm = now
-                self.spoken = True
-                return True
+                return self._speak(now, self.bug)
             # Still engaged: re-assert on the slow cadence, not every cycle.
-            if (self.last_alarm is None
-                    or (now - self.last_alarm).total_seconds() >= REASSERT_S):
-                self.last_alarm = now
-                self.spoken = True
-                return True
+            if self._due(self.last_alarm, now):
+                return self._speak(now, self.bug)
             return False
 
         self.run_len = 0
@@ -420,5 +520,7 @@ class ClampWatchdog:
             # above. The episode ends; the notification budget does not reset
             # with it.
             self.reason = ""
+            self.facts = ()
+            self.bug = False
             self.clean_cycles = 0
         return False

goodwe_controller/app/config_page.py

@@ -413,10 +413,9 @@ function showProblems(payload){
   save.disabled = total > 0;
   if(total){
     note(banner, 'bad', 'This configuration would not start.',
-      'The add-on refuses to run on it and would stop with exit 78. '
-      + 'Saving is blocked until these are fixed; nothing has been written. '
-      + 'Each message below is the add-on\\u2019s own words, from the same '
-      + 'check that runs at startup.');
+      'The add-on would refuse to start on it. Saving is blocked until these '
+      + 'are fixed, and nothing has been written. Each message below comes '
+      + 'from the same check that runs at start.');
     banner.insertBefore(banner.lastChild, banner.firstChild);
     msg(total + (total === 1 ? ' problem' : ' problems')
         + ' - saving is blocked', 'bad');

goodwe_controller/app/configui.py

@@ -289,7 +289,10 @@ def problems_by_field(problems, keys):
     cross-field rule is about all of its fields, and hiding it from one of them
     would be this card's own defect in miniature.
     """
-    patterns = [(key, re.compile(r"(?<![A-Za-z0-9_])" + re.escape(key)
+    # ⚠️ `.` BEFORE THE KEY DOES NOT COUNT (UX-08 2d): `inverters.max_w`
+    # names a setting of one inverter in the list, which is changed under
+    # `inverters`, and it must not also land beside the flat `max_w`.
+    patterns = [(key, re.compile(r"(?<![A-Za-z0-9_.])" + re.escape(key)
                                  + r"(?![A-Za-z0-9_])")) for key in keys]
     by_key, unanchored = {}, []
     for problem in problems:

goodwe_controller/app/control.py

@@ -17,6 +17,7 @@ exists because its absence produced a specific, observed failure.
 """
 
 import math
+from math import inf
 from dataclasses import dataclass
 
 # ---------------------------------------------------------------------------
@@ -265,6 +266,38 @@ _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
+
+# OPT-11. The loop's reason when the battery modes, not the meter, set the
+# command: every battery that may move this way is at its mode's limit.
+MODE_BOUND = "mode-bound"
+
 
 @dataclass(frozen=True)
 class Tuning:
@@ -340,6 +373,18 @@ class Decision:
     # the comment at the bound below, and clamp.py.
     i_clamped: bool = False
     clamped: bool = False
+    # SAFETY-40. The alarm's numbers, taken at the clamp so they are one tick's:
+    # the bound the integrator reached, and the command before/after the
+    # rating clamp. `target_w` is this tick's emitted command.
+    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
+    # SAFETY-85. The `bound` held the integrator or the command this cycle,
+    # so the batteries' limits, not the loop, decided it.
+    held: bool = False
 
 
 def slew_limit_w(tuning: Tuning) -> float:
@@ -436,6 +481,11 @@ def compute(
     tuning: Tuning,
     sat_count: int = 0,
     i_w: float | None = None,
+    refused: int | None = None,
+    probe: bool = False,
+    bound: tuple | None = None,
+    gave_nothing: bool | None = None,
+    idle_w: float = 0.0,
 ) -> Decision:
     """One control cycle. A cycle is one meter update (~5 s on a HomeWizard P1).
 
@@ -443,8 +493,34 @@ 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
+    `bound`    OPT-11: `(lo, hi)`, what the batteries may place this tick with
+               their modes applied (`allocator.loop_bound()`), or None. See
+               MODE_BOUND below. None is the law as it was.
+    `gave_nothing` SAFETY-94: the caller's span check - the reading stayed
+               under REFUSED_BELOW_W, one way, for SETTLE_CYCLES spanning
+               REFUSED_SPAN_S. A refusal engages only with it. None leaves it
+               out (compute() alone, as before).
+    `idle_w`   SAFETY-97: what `actual_w` reads while the batteries give
+               nothing (app/idle.py). The refusal's band and its end are
+               centred on it. 0 is the law as it was.
     """
     reason = "tracking"
+    # OPT-11: a bound that leaves out 0 W would FORCE a direction, which no
+    # mode may do. It is dropped rather than obeyed (a software fault, and
+    # main.py never builds one: every term of `loop_bound()` holds 0).
+    if bound is not None and not (bound[0] <= 0.0 <= bound[1]):
+        bound = None
+    # ...and a side of it that reaches the rail is left to the rail, so that
+    # SAFETY-03's `i_clamped` still fires when the loop winds into it. With
+    # every battery on, the bound IS the rail, and the law is exactly as it was.
+    if bound is not None:
+        _rail = min(tuning.max_w, tuning.max_w if tuning.integrator_max_w is None
+                    else tuning.integrator_max_w)
+        bound = (float(bound[0]) if bound[0] > -_rail else -inf,
+                 float(bound[1]) if bound[1] < _rail else inf)
 
     # --- saturation, WITH the duration term -------------------------------
     # Command and actual diverging means the inverter cannot follow - it is at
@@ -547,6 +623,17 @@ def compute(
         else:
             i_w = max(moved, i_w)
 
+    # OPT-11: the integrator does not wind past what the modes let the
+    # batteries place. Only a side tighter than the rail is left in `bound`
+    # (above), so this never takes SAFETY-03's `i_clamped` away from the rail.
+    held_by_bound = False
+    if bound is not None:
+        held = max(float(bound[0]), min(float(bound[1]), i_w))
+        if held != i_w:
+            i_w = held
+            reason = MODE_BOUND
+            held_by_bound = True
+
     # ⚠️ Applied EVERY cycle, frozen or not: the freeze is conditional, this
     # bound is not. It is what makes the worst-case unwind time finite and
     # knowable instead of a function of how long the error happened to stand.
@@ -563,6 +650,7 @@ def compute(
         # winding, "clamped" is a command that came out over the rating anyway.
         reason = "i-clamped"
     i_w = bounded
+    i_bound_w = bounded if i_clamped else 0.0
     want = i_w
 
     # ⚠️ Maintenance shaping (charge-only, cheap-window floor) used to live
@@ -574,6 +662,7 @@ def compute(
     # An early draft applied a floor after the clamp and let demand escape it.
     target = max(-tuning.max_w, min(tuning.max_w, want))
     clamped = target != want
+    clamped_w = target
     if clamped:
         reason = "clamped"
 
@@ -731,6 +820,49 @@ 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:
+        # SAFETY-94: and only when the reading has given nothing for the
+        # whole span, not just now. `sat_count` also counts the cycles a
+        # healthy battery spends reversing through its lag (-2000 W towards
+        # +800 W): at a 1 s meter its 12 cycles end as the reading passes 0.
+        if (refused == 0 and frozen and sat_count >= SETTLE_CYCLES
+                and abs(prev_w) > tuning.saturation_w
+                and abs(actual_w - idle_w) < REFUSED_BELOW_W
+                and gave_nothing is not False):
+            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 - idle_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
+
+    # --- OPT-11: the command stays inside what the modes allow -------------
+    # Applied after the slew limit and the freeze, so a mode that closes drops
+    # the ask at once rather than one slew step per cycle. That moves no
+    # battery further than the allocator would: it places at most this bound
+    # when the loop decides. What it removes is the unmet part, which would
+    # otherwise hold `prev_w` away from `actual_w` and trip the saturation
+    # freeze on watts no battery was allowed to give.
+    if bound is not None:
+        inside = max(float(bound[0]), min(float(bound[1]), target))
+        if inside != target:
+            target = inside
+            reason = MODE_BOUND
+            held_by_bound = True
+        # SAFETY-48's lead cap above may pull the integrator back toward the
+        # slewed command; what is CARRIED stays inside the bound too.
+        i_w = max(float(bound[0]), min(float(bound[1]), i_w))
+
     # --- 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
@@ -738,9 +870,17 @@ def compute(
     # 10 W simply avoids a visible staircase on dashboards.
     step = max(1, int(tuning.step_w))
     target = round(target / step) * step
+    if bound is not None:
+        # OPT-11: rounding must not step outside the bound. The bound holds
+        # 0 W, so one step toward 0 is always inside it.
+        if target > bound[1]:
+            target -= step
+        elif target < bound[0]:
+            target += step
 
     return Decision(float(target), sat_count, frozen, reason, float(i_w),
-                    i_clamped, clamped)
+                    i_clamped, clamped, float(i_bound_w), float(want),
+                    float(clamped_w), refused, held_by_bound)
 
 
 def maintenance_charge_floor(

goodwe_controller/app/custom_formula.py

@@ -175,6 +175,8 @@ import math
 from dataclasses import dataclass
 from datetime import date, datetime, timezone
 
+from . import messages
+
 
 class FormulaInvalid(Exception):
     """`price_formula` cannot be used. Raised by the parser, refused by
@@ -199,7 +201,7 @@ RESOLUTIONS: tuple = ("hourly", "quarter_hourly")
 # index id -> the human name of the series it refers to. One entry today; a
 # second index is a new row here plus a fetch path, not a new grammar.
 INDEXES: dict = {
-    "epex_be": "EPEX BE day-ahead, EUR/MWh",
+    "epex_be": "Belgian day-ahead price, EUR/MWh",
 }
 
 # ⚠️ 0.01 IN THE CARD'S OWN UNITS, WHICH IS THE LAST DIGIT BOTH REAL CARDS
@@ -285,87 +287,28 @@ _LEGS = {
                  '"offset":1.00,"units":"c_eur_per_kwh","vat_pct":6,'
                  '"card":{"month":"2026-09","index_eur_per_mwh":133.9905,'
                  '"expect_incl_vat":15.55}}'),
-        when="Leave it empty unless price_provider is 'custom_formula'.",
-        zero_factor=("every spread is exactly 0, and arbitrage can never "
-                     "clear any threshold - a strategy that silently never "
-                     "fires rather than one that is off"),
-        flat=("that is `static_profile` with a single period covering "
-              "00:00-24:00 on all days and price_provider 'off'; the add-on "
-              "then says so at startup instead of leaving you to find out "
-              "from a year of unchanged bills"),
-        neg_factor=("No consumption tariff is indexed negatively; if your "
-                    "card shows a minus sign it is on the OFFSET (`A`), "
-                    "which is allowed here and common on injection"),
+        when="Leave it empty unless “Dynamic price source” is 'custom_formula'.",
+        zero_factor=" and trading never finds a price difference",
+        flat="use “Fixed or day/night tariff” (static_profile) instead",
+        neg_factor="Put the minus sign on the offset, not on the factor",
         card_required=True,
-        card_note=("It is the only thing that can tell a correct pair of "
-                   "coefficients from a plausible-looking wrong one"),
-        card_causes=(
-            "or - the expensive one - network charges, levies or excise "
-            "folded into `offset`. ⚠️ THEY DO NOT BELONG THERE: a Belgian "
-            "card's Tariefformule line is the ENERGY component alone (Eneco "
-            "tabulates network tariffs and levies separately; ENGIE says in "
-            "so many words that the formula excludes network, distribution, "
-            "transport, levies and excise), the add-on adds "
-            "price_taxes_eur_kwh on top of it, and folding ~12 c EUR/kWh of "
-            "network charge into `offset` bills you for it twice. That is "
-            "the error this check exists to catch, and it is why it cannot "
-            "be switched off."),
+        card_note="The add-on needs it to check your two numbers",
+        card_causes=("the units, the VAT, and that network charges are not "
+                     "in the offset"),
     ),
     EXPORT_FORMULA_OPTION: _Leg(
         option=EXPORT_FORMULA_OPTION,
         what="injection",
-        # ⚠️ NO `card` BLOCK IN THE EXAMPLE, because Eneco's injection line has
-        # none to copy - the formula is printed with no price beside it. An
-        # example carrying one would invite an operator to compute the figure
-        # themselves, which is the one thing this leg must not encourage.
         example=('{"index":"epex_be","resolution":"hourly","factor":0.1,'
                  '"offset":-1.188,"units":"c_eur_per_kwh","vat_pct":0}'),
-        when=("Leave it empty unless your supplier pays you an injection "
-              "price that moves with the market; a flat one is "
-              "export_price_eur_kwh. ⚠️ This option is read whatever "
-              "price_provider is set to - it is the leg you are PAID on, not "
-              "the one you buy on."),
-        zero_factor=("every hour pays the same, which is a FLAT injection "
-                     "price written as a formula. ⚠️ Note this is NOT the "
-                     "arbitrage argument the consumption leg gives: no "
-                     "strategy in this add-on reads an injection price at "
-                     "all, so a flat one here fires nothing and declines "
-                     "nothing - it is simply the wrong option"),
-        flat=("that is `export_price_eur_kwh`, the flat injection scalar, "
-              "which is what every site used before this option existed and "
-              "which still answers when this one is empty"),
-        neg_factor=("No Belgian injection tariff is indexed negatively - you "
-                    "are paid MORE when the market is dearer, not less. The "
-                    "minus sign on an injection card is on the OFFSET (`A`): "
-                    "Eneco prints `0,1 x BELPEX-H - 1,188` and Aspiravi "
-                    "`0,07 x Belpex - 2`, and a negative offset is accepted "
-                    "here"),
+        when="Fill it in only if your injection price follows the market.",
+        zero_factor="",
+        flat="use “Injection price” (export_price_eur_kwh) instead",
+        neg_factor="Put the minus sign on the offset, not on the factor",
         card_required=False,
-        card_note=(
-            "⚠️ IT IS OPTIONAL ON THIS LEG, AND THAT IS A STATED GAP RATHER "
-            "THAN A RELAXED RULE. A Belgian card prints the CONSUMPTION "
-            "formula with the reference index and the resulting price beside "
-            "it, which is what makes `price_formula`'s self-check possible. "
-            "Eneco's injection line has NO printed price beside it, so on "
-            "that card there is nothing to grade against and requiring a "
-            "`card` block would make the market's own published formula "
-            "inexpressible - or, worse, invite an operator to compute the "
-            "estimate themselves, at which point the check grades the "
-            "coefficients against arithmetic done with the same coefficients. "
-            "Supply it if YOUR card prints one; when it is absent the add-on "
-            "says at startup that this leg is UNGRADED and the two "
-            "coefficient bounds below are all there is"),
-        card_causes=(
-            "or VAT added where there is none. ⚠️ INJECTION IS VAT-EXEMPT IN "
-            "BELGIUM - \"Injectietarieven zijn vrijgesteld van btw\" - while "
-            "consumption is at 6%, so `vat_pct` on THIS option is 0 on every "
-            "Belgian card the research found, and a 6 typed here because it "
-            "is 6 on the consumption leg is a ratio of exactly 1.06. Nothing "
-            "is added to this leg by the framework: price_taxes_eur_kwh is a "
-            "CONSUMPTION component and is not applied to what you are paid "
-            "for export, so an offset carrying network charges is a "
-            "different error here than it is on price_formula and this "
-            "check cannot tell you which one you made."),
+        card_note=("It is optional here. Without it the add-on only checks "
+                   "the size of your two numbers"),
+        card_causes="the units, and that the VAT is 0 for injection",
     ),
 }
 
@@ -488,16 +431,12 @@ def _finite(value, field: str, option: str = "price_formula") -> float:
     """
     if isinstance(value, bool) or not isinstance(value, (int, float)):
         raise FormulaInvalid(
-            f"{option}.{field} is {value!r}, which is not a number. "
-            f"Write the coefficient as a bare JSON number - 0.102, not "
-            f"\"0.102\" and not an expression: this provider takes FIXED "
-            f"coefficients and evaluates nothing.")
+            f"{option}.{field} is {value!r}, which is not a number. Write a "
+            f"plain number, for example 0.102.")
     if not math.isfinite(float(value)):
         raise FormulaInvalid(
-            f"{option}.{field} is {value!r}, which is not finite. A NaN "
-            f"or an infinity here makes every price NaN, every price "
-            f"comparison False, and an arbitrage strategy that never fires "
-            f"while reporting that it is armed.")
+            f"{option}.{field} is {value!r}, which is not finite. Write a "
+            f"plain number, for example 0.102.")
     return float(value)
 
 
@@ -517,11 +456,8 @@ def _card(raw, leg: _Leg = None) -> tuple:
         if not leg.card_required:
             return ("", None, None)
         raise FormulaInvalid(
-            f"{leg.option} has no \"card\" block, and it is REQUIRED. "
-            f"{leg.card_note}: the add-on recomputes your "
-            "supplier's own printed example from the numbers you typed and "
-            "refuses to start if it does not come out. Copy the three figures "
-            "off the same tariff card as the coefficients: "
+            f"{leg.option} has no \"card\" block. {leg.card_note}. Copy "
+            "the three figures from your tariff card, for example "
             "{\"month\": \"2026-09\", \"index_eur_per_mwh\": 133.9905, "
             "\"expect_incl_vat\": 15.55}.")
     if not isinstance(raw, dict):
@@ -531,16 +467,13 @@ def _card(raw, leg: _Leg = None) -> tuple:
     unknown = sorted(set(raw) - set(_CARD_KEYS))
     if unknown:
         raise FormulaInvalid(
-            f"{leg.option}.card has no field(s) {unknown}. The fields it "
-            f"takes are {list(_CARD_KEYS)}; a key that is merely ignored is a "
-            f"number the operator believes took effect.")
+            f"{leg.option}.card has unknown field(s) {unknown}. It takes "
+            f"only {list(_CARD_KEYS)}.")
     month = str(raw.get("month", "") or "").strip()
     if not _month_date(month):
         raise FormulaInvalid(
-            f"{leg.option}.card.month is {raw.get('month')!r}; write the "
-            f"month the card is dated as \"YYYY-MM\", e.g. \"2026-09\". It is "
-            f"not used in any price - it is what lets the add-on tell you "
-            f"your card has gone stale.")
+            f"{leg.option}.card.month is {raw.get('month')!r}. Write the "
+            f"month of the card as \"YYYY-MM\", for example \"2026-09\".")
     return (month,
             _finite(raw.get("index_eur_per_mwh"), "card.index_eur_per_mwh",
                     leg.option),
@@ -594,10 +527,8 @@ def parse_price_formula(value, *, option: str = "price_formula"):
             value = json.loads(text)
         except ValueError as e:
             raise FormulaInvalid(
-                f"{option} is not valid JSON ({e}). It is a JSON object "
-                f"on one line, e.g.\n"
-                f"  {leg.example}\n"
-                f"{leg.when}")
+                f"{messages.not_valid(option, e)}. Copy the example from the "
+                f"documentation. {leg.when}")
     if not isinstance(value, dict):
         raise FormulaInvalid(
             f"{option} is {type(value).__name__}, not a JSON object with "
@@ -612,34 +543,21 @@ def parse_price_formula(value, *, option: str = "price_formula"):
     unknown = sorted(set(value) - set(_TOP_KEYS))
     if unknown:
         raise FormulaInvalid(
-            f"{option} has no field(s) {unknown}. The fields it takes "
-            f"are {list(_TOP_KEYS)}. ⚠️ There is deliberately NO field that "
-            f"takes an expression: this provider multiplies and adds two "
-            f"FIXED coefficients and evaluates nothing, because two "
-            f"coefficients can be graded against your card's printed price "
-            f"and an arbitrary expression cannot be graded against anything. "
-            f"If your contract needs a shape this cannot express, it needs a "
-            f"new named field here - say which shape.")
+            f"{option} has unknown field(s) {unknown}. It takes only "
+            f"{list(_TOP_KEYS)}.")
 
     index = str(value.get("index", "") or "").strip()
     if index not in INDEXES:
         raise FormulaInvalid(
-            f"{option}.index is {value.get('index')!r}. The reference "
-            f"series this add-on can fetch are "
-            f"{', '.join(f'{k!r} ({v})' for k, v in sorted(INDEXES.items()))}. "
-            f"If your card names a different index, the add-on cannot get it "
-            f"and guessing which series your supplier meant would price your "
-            f"battery against the wrong curve.")
+            f"{option}.index is {value.get('index')!r}. The add-on can only "
+            f"fetch "
+            f"{', '.join(f'{k!r} ({v})' for k, v in sorted(INDEXES.items()))}.")
 
     resolution = str(value.get("resolution", "") or "").strip()
     if resolution not in RESOLUTIONS:
         raise FormulaInvalid(
-            f"{option}.resolution is {value.get('resolution')!r}; it "
-            f"must be one of {list(RESOLUTIONS)}. Belgium has been on a "
-            f"15-minute MTU since 2025-10-01 and the feed publishes 96 points "
-            f"a day; a contract written against the HOURLY series is priced "
-            f"on the mean of each hour's quarters. Which one your contract "
-            f"uses is on your card and cannot be inferred from the feed.")
+            f"{option}.resolution is {value.get('resolution')!r}. Choose one "
+            f"of {list(RESOLUTIONS)}, as your tariff card says.")
 
     # ⚠️ `units` IS REQUIRED AND HAS NO DEFAULT. A default here would be the
     # factor-1000 class with a friendly face: the add-on would silently assume
@@ -648,12 +566,8 @@ def parse_price_formula(value, *, option: str = "price_formula"):
     units = str(value.get("units", "") or "").strip()
     if units not in UNITS:
         raise FormulaInvalid(
-            f"{option}.units is {value.get('units')!r} and is REQUIRED - "
-            f"there is no default, on purpose. It must be one of "
-            f"{sorted(UNITS)}. Your card prints the formula in ONE of these "
-            f"and two suppliers use two different conventions for the same "
-            f"shape, so assuming one would be a factor of 100 or 1000 on "
-            f"every hour with nothing able to notice.")
+            f"{option}.units is {value.get('units')!r}. Choose one of "
+            f"{sorted(UNITS)}, as printed beside the formula on your card.")
 
     factor = _finite(value.get("factor"), "factor", option)
     offset = _finite(value.get("offset"), "offset", option)
@@ -667,10 +581,8 @@ def parse_price_formula(value, *, option: str = "price_formula"):
     # the operator at it rather than let them build it by accident.
     if factor == 0.0:
         raise FormulaInvalid(
-            f"{option}.factor is 0, so the index would not enter the "
-            "price at all: every hour of every day comes out at "
-            f"{offset:g} x (1 + {vat_pct:g}/100), {leg.zero_factor}. If "
-            f"your {leg.what} tariff really is one flat price, {leg.flat}.")
+            f"{option}.factor is 0, so every hour gets the same {leg.what} "
+            f"price{leg.zero_factor}. For one flat price, {leg.flat}.")
 
     # ⚠️ A NEGATIVE FACTOR INVERTS THE MARKET, and the direction is the danger:
     # the dearest hour becomes the cheapest one, so the battery is told to
@@ -678,22 +590,16 @@ def parse_price_formula(value, *, option: str = "price_formula"):
     # mispriced site, it is a site actively trading against itself.
     if factor < 0.0:
         raise FormulaInvalid(
-            f"{option}.factor is {factor:g}, which is NEGATIVE. That "
-            f"inverts the market: the dearest hour of the day comes out as "
-            f"the cheapest one, so the battery would charge at the evening "
-            f"peak and discharge at 03:00 - trading against itself on every "
-            f"cycle. {leg.neg_factor}.")
+            f"{option}.factor is {factor:g}, which turns the market upside "
+            f"down. {leg.neg_factor}.")
 
     # ⚠️ 0 IS LEGITIMATE AND MUST STAY SO: injection is VAT-exempt in Belgium,
     # and some cards are already quoted VAT-inclusive. The bound exists for the
     # 106 / 1.06 / 6 confusion, not to make VAT compulsory.
     if not 0.0 <= vat_pct <= 30.0:
         raise FormulaInvalid(
-            f"{option}.vat_pct is {vat_pct:g} and must be between 0 and "
-            f"30. It is a PERCENTAGE, so Belgian residential electricity is "
-            f"6, not 0.06 and not 106. Zero is legitimate and is not refused: "
-            f"injection is VAT-exempt, and a card that already quotes "
-            f"VAT-inclusive coefficients needs no second multiplication.")
+            f"{option}.vat_pct is {vat_pct:g}. Write a percentage between 0 "
+            f"and 30, for example 6.")
 
     month, card_index, card_expect = _card(value.get("card"), leg)
     spec = FormulaSpec(index=index, resolution=resolution, factor=factor,
@@ -771,33 +677,15 @@ def parse_export_formula(value):
 def card_refusal(spec: FormulaSpec, delta: float) -> str:
     """The sentence an operator reads when their formula misses its own card.
 
-    ⚠️ IT NAMES THE DISCREPANCY AND THE SIX WAYS IT HAPPENS. "Invalid
-    configuration" would be true and useless: every one of these errors looks
-    exactly like a working tariff from the status page, which is why the check
-    exists at all.
+    It names both numbers and what to check. The usual causes are in DOCS.md,
+    because each of these errors looks like a working tariff on the status page.
     """
     got = in_card_units(spec, spec.card_index_eur_per_mwh)
-    ratio = (got / spec.card_expect_incl_vat
-             if spec.card_expect_incl_vat else float("inf"))
     leg = _LEGS[spec.option]
     return (
-        f"{spec.option} does not reproduce its own card, so the add-on will "
-        f"NOT start on it. Your contract's arithmetic is "
-        f"price = (factor x index_eur_per_mwh + offset) x (1 + vat_pct/100); "
-        f"on the card's own index that is "
-        f"({spec.factor:g} x {spec.card_index_eur_per_mwh:g} + "
-        f"{spec.offset:g}) x (1 + {spec.vat_pct:g}/100) = {got:.4f} "
-        f"{spec.units}, but card.expect_incl_vat says "
-        f"{spec.card_expect_incl_vat:g} - OUT BY {delta:+.4f} {spec.units} "
-        f"(ratio {ratio:.4g}; the tolerance is {CARD_TOLERANCE}, which is the "
-        f"last digit a card prints). One of the two sides is wrong and the "
-        f"add-on cannot tell which, so it refuses rather than price a battery "
-        f"on it. The usual causes, in the order they happen: the coefficients "
-        f"and the expected price are in DIFFERENT units (ratio 10, 100 or "
-        f"1000 - `units` must be the one the formula line is printed in); VAT "
-        f"left out or applied twice (ratio 1.06 or 1/1.06); a transposed "
-        f"digit; the two sides copied off DIFFERENT cards or different "
-        f"months; {leg.card_causes}")
+        f"{spec.option} gives {got:.4f} "
+        f"{messages.UNIT_WORDS.get(spec.units, spec.units)}, the card says "
+        f"{spec.card_expect_incl_vat:g}. Check {leg.card_causes}.")
 
 
 # --------------------------------------------------------------------------- #
@@ -852,20 +740,10 @@ def implausible_all_in(spec: FormulaSpec, taxes_eur_kwh: float):
     if energy >= PLAUSIBLE_LO_EUR_KWH and all_in <= PLAUSIBLE_HI_EUR_KWH:
         return None
     return (
-        f"{spec.option}'s own card works out at {energy:.5f} EUR/kWh of "
-        f"energy ({spec.card_expect_incl_vat:g} {spec.units} as the card "
-        f"prints it) and {all_in:.5f} EUR/kWh all-in once "
-        f"price_taxes_eur_kwh is added, which is outside the plausible band "
-        f"{PLAUSIBLE_LO_EUR_KWH}-{PLAUSIBLE_HI_EUR_KWH} EUR/kWh for a Belgian "
-        f"retail tariff. The card self-check passed, so the coefficients and "
-        f"the printed price AGREE - they simply agree on a number no Belgian "
-        f"bill carries, which is what a whole card read in the wrong units "
-        f"looks like (a factor of 10, 100 or 1000 applied to BOTH sides at "
-        f"once cancels out of that check and cannot cancel out of this one). "
-        f"Check `units` against the unit printed beside your formula. "
-        f"⚠️ This bounds the CARD'S OWN POINT, not every hour: a live hour may "
-        f"legitimately fall outside the band, and a negative day-ahead hour - "
-        f"the best charging opportunity of the year - is never refused.")
+        f"{spec.option} gives {energy:.5f} EUR/kWh for energy and "
+        f"{all_in:.5f} EUR/kWh with “Distribution, levies and VAT” "
+        f"(price_taxes_eur_kwh), outside the plausible band of "
+        f"{PLAUSIBLE_LO_EUR_KWH}-{PLAUSIBLE_HI_EUR_KWH} EUR/kWh. Check \"units\" against the unit beside your formula.")
 
 
 def implausible_injection(spec: FormulaSpec):
@@ -914,36 +792,16 @@ def implausible_injection(spec: FormulaSpec):
     """
     if not PASSTHROUGH_LO <= spec.passthrough <= PASSTHROUGH_HI:
         return (
-            f"{spec.option}.factor is {spec.factor:g} {spec.units} per "
-            f"EUR/MWh, which passes through {spec.passthrough:.4g}x the "
-            f"wholesale price - outside the plausible "
-            f"{PASSTHROUGH_LO}-{PASSTHROUGH_HI}x for an injection tariff. A "
-            f"Belgian injection formula pays a share of the market price a "
-            f"little under or about equal to it: Eneco's "
-            f"`0,1 x BELPEX-H - 1,188` c EUR/kWh is 1.00x and Aspiravi's "
-            f"`0,07 x Belpex - 2` is 0.70x. {spec.passthrough:.4g}x is what a "
-            f"factor typed in the wrong units looks like - check `units` "
-            f"({spec.units!r}) against the unit printed beside your formula, "
-            f"because the card self-check cannot see a factor of 10, 100 or "
-            f"1000 applied to BOTH sides at once. ⚠️ This bounds the "
-            f"COEFFICIENT and not the price: an injection price below zero is "
-            f"accepted and is the real market - Eneco's goes negative under "
-            f"11.88 EUR/MWh of BELPEX-H, which is the middle of a sunny day.")
+            f"{spec.option}.factor passes through {spec.passthrough:.4g}x the "
+            f"market price, outside {PASSTHROUGH_LO}-{PASSTHROUGH_HI}x. Check "
+            f"\"units\" ({spec.units!r}) against the unit beside your "
+            f"formula.")
     if abs(spec.offset_eur_kwh) > INJECTION_OFFSET_MAX_EUR_KWH:
         return (
-            f"{spec.option}.offset is {spec.offset:g} {spec.units} = "
-            f"{spec.offset_eur_kwh:+.5f} EUR/kWh, and |offset| above "
-            f"{INJECTION_OFFSET_MAX_EUR_KWH} EUR/kWh is not a Belgian "
-            f"injection tariff in either direction. The published ones are "
-            f"small and NEGATIVE - Eneco -1,188 c EUR/kWh (-0.01188), "
-            f"Aspiravi -2 c (-0.02) - so a minus sign here is expected and is "
-            f"not what this refuses; a MAGNITUDE two orders out is. The usual "
-            f"cause is the offset typed in a different unit from `units` "
-            f"({spec.units!r}), or a consumption offset copied onto the "
-            f"injection leg: they are different numbers on the same card. "
-            f"⚠️ Network charges and levies do not belong here either - "
-            f"nothing is added to what you are PAID for export, so an offset "
-            f"carrying them is simply wrong rather than double-counted.")
+            f"{spec.option}.offset is {spec.offset:g} {spec.units}, which is "
+            f"{spec.offset_eur_kwh:+.5f} EUR/kWh and larger than "
+            f"{INJECTION_OFFSET_MAX_EUR_KWH} EUR/kWh either way. Check its "
+            f"unit.")
     return None
 
 
@@ -957,15 +815,9 @@ def stale_card(spec: FormulaSpec, today=None):
     if dated is None or (now - dated).days <= CARD_STALE_DAYS:
         return None
     return (
-        f"{spec.option}'s card is dated {spec.card_month}, which is "
-        f"{(now - dated).days} days ago. Suppliers reprice: if your contract "
-        f"has been renewed or rolled over since then, the coefficients here "
-        f"are last year's and every price this add-on computes is wrong by "
-        f"however far they moved - and the card self-check cannot see it, "
-        f"because it grades your coefficients against the card you typed, not "
-        f"the card against your current contract. Not refused: ENGIE freezes "
-        f"coefficients for the contract's duration, so an old card is often "
-        f"exactly right. Worth re-reading your klantenzone once.")
+        f"{spec.option}'s card is dated {spec.card_month}, "
+        f"{(now - dated).days} days ago. The add-on still starts, but if your "
+        f"contract changed since, copy the new figures from your supplier.")
 
 
 # --------------------------------------------------------------------------- #

goodwe_controller/app/dayplan.py

@@ -0,0 +1,262 @@
+"""OPT-11 P4: the day plan. Will the sun fill each battery before the
+expensive hours? If not, how much should it take from the grid?
+
+Pure: the forecast (`solarfc`), the house profile, the price runs and the
+batteries in; a level per battery (`Plan.targets`) out. `modetrade.charge_to()`
+turns the level into permission to charge from the grid; main.py rebuilds the
+plan with the price runs (at most every 15 minutes) and keeps a level unless
+it moves by `HYST_KWH` or `HYST_FRAC` (`hold()`).
+
+The sums (OPT-11-design section 1, "Excess solar", with the owner's answers):
+* `sun`: trust x the solar the house will not use, between now and the
+  expensive run the cheap run is for, x the charge efficiency:
+  `trust x sum_h max(0, forecast_h - house_h) x EFF`.
+* Solar first batteries take it first, up to the ceiling. What is left is
+  shared by the Leftover solar batteries by their room.
+* Cheap hours only ignores the plan and fills to the ceiling, as in P3 and
+  the design (section 1). Skipping the sun's share cost money in the replay
+  (PR #156 review: 29.72 against 29.41 EUR on real 2026 prices).
+* A Leftover solar battery charges only up to what the house will draw from
+  it in the expensive runs before the next cheap run, less its share:
+  `min(ceiling, floor + house use / EFF) - share`. So it buys only the
+  shortfall, not up to the ceiling.
+* Solar first never charges from the grid (owner, 2026-09-29).
+
+The house profile is the add-on's own measurement, grid + battery power, per
+local hour, over the last `PROFILE_DAYS` days; the estimate for an hour is the
+median of that hour. It is net of the solar the house used itself, so for
+the solar sum it is never taken below the night-time median (`base()`).
+The site's own solar readings are not used: TEL-11 keeps them out of every
+control decision.
+"""
+
+import statistics
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from .packmode import LEFTOVER_SOLAR, SOLAR_FIRST
+from .tariff import BILLING_TZ
+
+EFF = 0.95                  # charge (and discharge) efficiency
+HYST_KWH = 1.0              # a kept level moves only by this much...
+HYST_FRAC = 0.10            # ...or this share of the battery's shortfall
+PROFILE_DAYS = 7
+MIN_HOURS = 20              # hours of a day recorded before it counts
+NIGHT_HOURS = (0, 1, 2, 3, 4, 5, 22, 23)
+DEFAULT_TRUST_PCT = 70
+
+# Site verdicts (the page's forecast line).
+SUNNY, PARTLY, DARK = "sunny", "partly", "dark"
+
+
+# --------------------------------------------------------------------------- #
+# The house profile
+# --------------------------------------------------------------------------- #
+def _local(t: datetime):
+    return t.astimezone(BILLING_TZ)
+
+
+class HouseProfile:
+    """Hourly means of the house's net use (grid + battery power), kept per
+    local day and hour: `{"YYYY-MM-DD": {hour: [mean_w, samples]}}`. The
+    store holds `dump()`; `load()` takes it back and drops what is bad."""
+
+    def __init__(self, data=None):
+        self.days = {}
+        self._cur = None            # (day, hour, sum, n)
+        if isinstance(data, dict):
+            self.load(data)
+
+    def load(self, data):
+        for day, hours in data.items():
+            try:
+                datetime.strptime(str(day), "%Y-%m-%d")
+            except ValueError:
+                continue
+            if not isinstance(hours, dict):
+                continue
+            row = {}
+            for h, v in hours.items():
+                try:
+                    hi, w = int(h), float(v)
+                except (TypeError, ValueError):
+                    continue
+                if 0 <= hi < 24 and abs(w) < 1e6:
+                    row[hi] = w
+            if row:
+                self.days[str(day)] = row
+
+    def dump(self) -> dict:
+        return {d: {str(h): round(w, 1) for h, w in sorted(r.items())}
+                for d, r in sorted(self.days.items())}
+
+    def add(self, now: datetime, house_w) -> bool:
+        """One reading. Returns True when an hour closed (then store it)."""
+        lt = _local(now)
+        key = (lt.strftime("%Y-%m-%d"), lt.hour)
+        closed = False
+        if self._cur is not None and self._cur[:2] != key:
+            day, hour, s, n = self._cur
+            if n >= 60:                 # about 5 minutes of readings
+                self.days.setdefault(day, {})[hour] = s / n
+                closed = True
+            self._cur = None
+            self._prune(lt)
+        if house_w is None:
+            return closed
+        if self._cur is None:
+            self._cur = (key[0], key[1], 0.0, 0)
+        d, h, s, n = self._cur
+        self._cur = (d, h, s + float(house_w), n + 1)
+        return closed
+
+    def _prune(self, lt):
+        """Keep the last `PROFILE_DAYS` days; a day after today (the clock
+        was wrong once) would never age out, so it goes too."""
+        keep = (lt.date() - timedelta(days=PROFILE_DAYS)).isoformat()
+        today = lt.date().isoformat()
+        for d in [d for d in self.days if d < keep or d > today]:
+            del self.days[d]
+
+    def ready(self) -> bool:
+        """At least one day with `MIN_HOURS` hours recorded."""
+        return any(len(r) >= MIN_HOURS for r in self.days.values())
+
+    def hour_w(self, hour: int):
+        vals = [r[hour] for r in self.days.values() if hour in r]
+        return statistics.median(vals) if vals else None
+
+    def base(self):
+        vals = [w for h in NIGHT_HOURS if (w := self.hour_w(h)) is not None]
+        return statistics.median(vals) if vals else None
+
+    def estimator(self):
+        """`f(hour) -> W`, or None when not ready. Fixed at call time."""
+        if not self.ready():
+            return None
+        base = self.base() or 0.0
+        table = {}
+        for h in range(24):
+            w = self.hour_w(h)
+            table[h] = base if w is None else w
+        return lambda h: table[h], max(0.0, base)
+
+
+# --------------------------------------------------------------------------- #
+# The plan
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class Plan:
+    verdict: str                # SUNNY / PARTLY / DARK
+    sun_kwh: float              # solar the batteries can count on
+    fc_kwh: float               # the forecast over the same span
+    until: datetime             # the expensive run the plan is for
+    targets: dict               # name -> level % (Leftover solar only)
+    need_kwh: dict              # name -> kWh from the grid (0: none)
+    share_kwh: dict             # name -> kWh of solar counted for it
+
+
+def _hour_slices(t0, t1):
+    """Local-hour slices of [t0, t1): (start, end, local hour)."""
+    out, t = [], t0
+    while t < t1:
+        lt = _local(t)
+        nxt = (lt.replace(minute=0, second=0, microsecond=0)
+               + timedelta(hours=1)).astimezone(timezone.utc)
+        e = min(nxt, t1)
+        out.append((t, e, lt.hour))
+        t = e
+    return out
+
+
+def _room(p, to_pct):
+    if p.capacity_kwh is None or p.soc is None:
+        return 0.0
+    return max(0.0, float(to_pct) - float(p.soc)) / 100.0 * float(
+        p.capacity_kwh)
+
+
+def plan(forecast, house, runs, now, packs, *, trust_pct, floor_pct,
+         ceiling_pct):
+    """The day plan, or None when there is none to make: no forecast, no
+    house profile yet, no price plan, or no expensive run after the cheap
+    run. `house` is `HouseProfile.estimator()`'s answer. `packs` are
+    `modetrade.Pack`s."""
+    if forecast is None or house is None or runs is None or not runs.on \
+            or runs.cheap is None:
+        return None
+    house_w, base_w = house
+    until = next((g for g in runs.give if g.start >= runs.cheap.end), None)
+    if until is None:
+        return None
+    trust = max(0.0, min(1.0, float(trust_pct) / 100.0))
+    sun = fc_sum = 0.0
+    for s, e, h in _hour_slices(now, until.start):
+        pv = forecast.between(s, e)
+        if pv is None:
+            return None             # the span reaches a day with no forecast
+        hrs = (e - s).total_seconds() / 3600.0
+        use = max(house_w(h), base_w) * hrs / 1000.0
+        sun += max(0.0, pv - use)
+        fc_sum += pv
+    sun *= trust * EFF
+
+    usable = [p for p in packs if p.use and p.live and p.idle
+              and p.soc is not None and p.capacity_kwh]
+    sf = [p for p in usable if p.mode == SOLAR_FIRST]
+    price = [p for p in usable if p.mode == LEFTOVER_SOLAR]
+    sf_room = sum(_room(p, ceiling_pct) for p in sf)
+    excess = max(0.0, sun - sf_room)
+    rooms = {p.name: _room(p, ceiling_pct) for p in price}
+    total_room = sum(rooms.values())
+
+    # What the house draws in the expensive runs from the one this plan is
+    # for until the next cheap run (or a day), from the profile.
+    horizon = until.start + timedelta(hours=24)
+    use_kwh = 0.0
+    for g in runs.give:
+        if g.start < until.start or g.start >= horizon:
+            continue
+        for s, e, h in _hour_slices(g.start, g.end):
+            use_kwh += max(0.0, house_w(h)) * (
+                e - s).total_seconds() / 3600.0 / 1000.0
+    caps = {p.name: float(p.capacity_kwh) for p in price}
+    cap_sum = sum(caps.values()) or 1.0
+
+    targets, need, share = {}, {}, {}
+    for p in price:
+        sh = excess * rooms[p.name] / total_room if total_room > 0 else 0.0
+        sh_pct = sh / caps[p.name] * 100.0
+        want = use_kwh * caps[p.name] / cap_sum / EFF
+        top = min(float(ceiling_pct),
+                  float(floor_pct) + want / caps[p.name] * 100.0)
+        level = max(0.0, top - sh_pct)
+        targets[p.name] = round(level, 2)
+        need[p.name] = round(_room(p, level), 3)
+        share[p.name] = round(sh, 3)
+    if sun < sf_room:
+        verdict = DARK
+    elif any(v > 0.05 for v in need.values()):
+        verdict = PARTLY
+    else:
+        verdict = SUNNY
+    return Plan(verdict, round(sun, 3), round(fc_sum, 3), until.start,
+                targets, need, share)
+
+
+def hold(old: dict | None, new: dict, capacity: dict) -> dict:
+    """Hysteresis: a battery keeps its old level unless the new one differs
+    by at least `HYST_KWH`, or by `HYST_FRAC` of the larger level's energy
+    (whichever is less). A battery new to the plan takes its level at once;
+    one that left the plan is dropped at once."""
+    out = {}
+    for name, level in new.items():
+        was = (old or {}).get(name)
+        cap = float(capacity.get(name) or 0.0)
+        if was is None or cap <= 0:
+            out[name] = level
+            continue
+        moved = abs(level - was) / 100.0 * cap
+        step = min(HYST_KWH, HYST_FRAC * max(was, level) / 100.0 * cap)
+        out[name] = level if moved >= step else was
+    return out

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

@@ -87,6 +87,10 @@ when it has not moved THROUGH A CHANGE IT WAS OBLIGED TO FOLLOW:
                 AND |standing command now - standing command when the reading
                      last changed| >= MOVE_W
 
+SAFETY-94: "unchanged for" counts only the reads at which both command terms
+held, so a register that rested is not judged before it could answer.
+DECISIONS/SAFETY-94-lagging-battery.md.
+
 0x0518 is the inverter reporting ITSELF and it tracks its own command: r = 0.998
 with battery power against r = 0.09 with the real meter (goodwe/NOTES.md §3.3),
 command and actual agreeing within 4 W once settled (§5.10, 2026-08-22), and the
@@ -216,6 +220,8 @@ change - which was the ONLY exit - has a median of 143 s, 17 episodes at or
 over the live one's 710 s, and a worst case of 21440 s. That distribution is a
 property of this battery's firmware. It is not a property of this code, and the
 add-on must not depend on it.
+SAFETY-94: many were the gate judging a rested register on its first read
+(SAFETY-58). Counted from the ask, the same days give 59 trips.
 
 THE RULE, and it is SAFETY-13's shape one module over - "which latches get an
 exit, not how long the block lasts":
@@ -372,7 +378,9 @@ BOUNDS = {
                    "SAFETY-57: the verdict is withdrawn after 17.0 s of the "
                    "standing command below 250 W, because at 0 W the register "
                    "is obliged to nothing and the verdict cannot be tested "
-                   "again from inside the state it creates"),
+                   "again from inside the state it creates. SAFETY-94: the "
+                   "35 s counts only reads at which the command asks the "
+                   "register to move"),
     "soc": Bound(
         signal="soc (0x050E, pack SoC, U16, 1 %, 10 s publish)",
         unchanged_s=float("inf"),
@@ -416,11 +424,9 @@ class Freshness:
     new grading window at that instant. The 1 Hz oscillation the latch exists to
     prevent is still prevented: the new window is `bound.unchanged_s` wide, so
     no re-trip can land sooner than 35 s after a release, rather than on the
-    next read. ⚠️ MEASURED FROM THE RELEASE, NOT FROM THE COMMAND RESUMING - if
-    the site rests for longer than the window before it asks for anything, the
-    window is already old and the re-trip lands on the first read at which the
-    command travels 250 W again. That is survivor 5's shape, it predates this
-    card, and its cost is one `stale_input_s` hold.
+    next read. SAFETY-94: the 35 s counts only while the command asks the
+    register to move, so a site that rests after a release is not re-tripped
+    on its first ask.
 
     ⚠️ TWO CLOCKS, AND THE DISTINCTION IS THE WHOLE OF SAFETY-57'S HONESTY.
     `changed_mono` / `held` are facts about the REGISTER: when it last carried a
@@ -451,6 +457,11 @@ class Freshness:
         # the change-stamps; `_release()` is where they diverge.
         self.graded_from = None
         self.standing_at_grade = None
+        # SAFETY-94. Seconds of this window during which the register was
+        # obliged to move (the command at least `move_w` and `move_w` away
+        # from `standing_at_grade`), and the instant of the last read.
+        self.obliged_acc = 0.0
+        self.last_read = None
         # The instant the standing command last FELL below `move_w`, or None
         # while an obligation is standing. The release timer runs off this.
         self.rested_since = None
@@ -499,6 +510,7 @@ class Freshness:
         # it reads in the order the state machine moves - withdraw, then
         # re-grade - not because the code depends on it.
         self._release(standing_w, now_mono)
+        self._oblige(standing_w, now_mono)
         self._grade(standing_w, now_mono)
 
     def _open_window(self, standing_w, now_mono) -> None:
@@ -510,6 +522,35 @@ class Freshness:
         self.graded_from = float(now_mono)
         self.standing_at_grade = (None if standing_w is None
                                   else float(standing_w))
+        # The read that opens a window is never an ask (no travel yet).
+        self.obliged_acc = 0.0
+
+    def _obliged(self, standing_w) -> bool:
+        """Is the register asked to move: the command is at least `move_w` and
+        has travelled `move_w` since the window opened?"""
+        if standing_w is None or self.standing_at_grade is None:
+            return False
+        standing_w = float(standing_w)
+        return (abs(standing_w) >= self.bound.move_w
+                and abs(standing_w - self.standing_at_grade)
+                >= self.bound.move_w)
+
+    def _oblige(self, standing_w, now_mono) -> None:
+        """SAFETY-94. Count only the time the register was asked to move.
+
+        A register that held still while nothing asked it to move has not
+        failed, so time before the command moved is not evidence. The time
+        since the previous read counts when the obligation stands at this
+        read; a command flapping in and out of the obligation still adds up.
+        """
+        now_mono = float(now_mono)
+        if self.last_read is not None and self._obliged(standing_w):
+            self.obliged_acc += max(0.0, now_mono - self.last_read)
+        self.last_read = now_mono
+
+    def obliged_s(self) -> float:
+        """Seconds of the current window the register was obliged to move."""
+        return self.obliged_acc
 
     def _release(self, standing_w, now_mono) -> None:
         """SAFETY-57. Withdraw a verdict whose obligation is no longer standing.
@@ -543,7 +584,12 @@ class Freshness:
         if self.stale or self.graded_from is None:
             return
         held_s = self.graded_s(now_mono)
-        if held_s < self.bound.unchanged_s:
+        # SAFETY-94 (closes SAFETY-58): the bound counts only the time the
+        # command asked the register to move, not the time since it last
+        # changed. A register that rested for minutes was otherwise judged on
+        # the first read after a new command, before it could answer (live,
+        # 2026-10-03: 1 s after the command).
+        if self.obliged_s() < self.bound.unchanged_s:
             return
         # ⚠️ BOTH None GUARDS ARE FOR A CALLER THAT DOES NOT KNOW ITS OWN
         # OBLIGATION YET, WHICH IS NOT `_read_unit`. `Inverter.standing_w()`
@@ -594,31 +640,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,115 @@
+"""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")
+_TO_W = {"mW": 0.001, "W": 1.0, "kW": 1000.0, "MW": 1e6}
+_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 watts(r: dict | None):
+    """A power entity's reading in W, or None when it is not a number in a
+    power unit (the setup wizard's kettle test)."""
+    if not r or r.get("unit") not in _TO_W:
+        return None
+    try:
+        value = float(r.get("state"))
+    except (TypeError, ValueError):
+        return None
+    return value * _TO_W[r["unit"]] if value == value else None
+
+
+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, max_age: float = CACHE_S
+                  ) -> tuple[dict | None, float | None]:
+        """(rows by entity id, age in s), or (None, None) if never read.
+        `max_age` is how old a try may be before HA is asked again: the setup
+        wizard's last step asks for a list at most a few seconds old."""
+        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 >= max_age:
+                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
+
+    async def reading(self, entity_id: str) -> dict:
+        """One entity read now, not from the list: the kettle test compares
+        two readings seconds apart, which a 30 s list cannot. A read only."""
+        r = row(await self.hass.state(entity_id)) if entity_id else None
+        return {"entity_id": entity_id, "found": r is not None,
+                "state": r and r["state"], "unit": r and r["unit"],
+                "watts": watts(r)}
+
+    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,12 +16,53 @@ _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 ReadOnly(RuntimeError):
+    """A service call on a read-only HomeAssistant (UX-15 setup-only mode)."""
 
 
 class HomeAssistant:
-    def __init__(self, session: aiohttp.ClientSession, token: str | None = None):
+    def __init__(self, session: aiohttp.ClientSession, token: str | None = None,
+                 *, read_only: bool = False):
         self.session = session
         self.token = token or os.environ.get("SUPERVISOR_TOKEN", "")
+        # UX-15: setup-only mode reads Home Assistant and calls no service.
+        # Fixed at construction; `call()` refuses before it sends anything.
+        self._read_only = bool(read_only)
         self._last_moan: dict[str, float] = {}
         if not self.token:
             _LOG.error("SUPERVISOR_TOKEN missing - is this running as an add-on?")
@@ -58,10 +99,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 +122,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)
@@ -107,23 +189,53 @@ class HomeAssistant:
                 return None
         return (_f("min"), _f("max"), _f("step"))
 
+    @property
+    def read_only(self) -> bool:
+        return self._read_only
+
     async def call(self, domain: str, service: str, data: dict) -> bool:
+        if self._read_only:
+            # Every service call, `number.set_value` included, goes through
+            # here, so setup-only mode has no way to command (DECISIONS UX-15).
+            _LOG.error("Setup-only mode called no service, because it may not "
+                       "command anything.")
+            raise ReadOnly(f"{domain}.{service} refused: setup-only mode")
         try:
             async with self.session.post(
                 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/idle.py

@@ -0,0 +1,87 @@
+"""SAFETY-97: what a battery's power reading shows while it gives nothing.
+
+B's reading (0x0518) shows -95 to -118 W at idle (standby draw, live
+2026-10-03); A's shows -2 to -4 W. "The battery gives nothing" is graded
+against this idle reading, not against 0 W, or a refusing B never latches.
+DECISIONS/SAFETY-97-idle-offset.md.
+
+Learned per unit, never configured:
+- only while control runs, the unit is not refused, stale or tripped, and
+  its command has been within IDLE_ASK_W for IDLE_QUIET_S (a refusing battery
+  is asked more than that, so it cannot teach its refusal as idle);
+- a reading beyond IDLE_SAMPLE_W is not a sample;
+- first value: the mean of IDLE_FIRST_S of samples; then a slow follow
+  (IDLE_TAU_S);
+- persisted per unit and restored, clamped to IDLE_SAMPLE_W, at start.
+The band is centred on it clamped to IDLE_MAX_W (owner, 2026-10-04). Until
+learned the idle reading is 0 W, the rule as it was.
+"""
+
+import math
+
+IDLE_MAX_W = 75.0       # |idle| used: under the 100 W band, so it keeps 0 W +-25 W
+IDLE_SAMPLE_W = 250.0   # a reading beyond this is not a sample
+IDLE_ASK_W = 50.0       # a command this small counts as "asked ~0"
+IDLE_QUIET_S = 120.0    # 6 lags of 20 s: a 2500 W step has decayed to 6 W
+IDLE_FIRST_S = 120.0    # seconds of samples averaged for the first value
+IDLE_TAU_S = 1800.0     # then follow drift this slowly
+IDLE_SAVE_W = 5.0       # persist when the value moved this far
+IDLE_GAP_S = 10.0       # a longer gap between reads counts as this
+
+
+def _num(v):
+    try:
+        v = float(v)
+    except (TypeError, ValueError):
+        return None
+    return v if math.isfinite(v) else None
+
+
+class IdleReading:
+    """One unit's idle reading. `w` is what "gives nothing" is centred on."""
+
+    def __init__(self, saved=None):
+        v = _num(saved)
+        self.value = (None if v is None
+                      else max(-IDLE_SAMPLE_W, min(IDLE_SAMPLE_W, v)))
+        self.saved = self.value
+        self.quiet_since = None
+        self.last = None
+        self.acc_w = 0.0
+        self.acc_s = 0.0
+
+    @property
+    def w(self) -> float:
+        """The centre used: the learned value clamped to IDLE_MAX_W."""
+        if self.value is None:
+            return 0.0
+        return max(-IDLE_MAX_W, min(IDLE_MAX_W, self.value))
+
+    def observe(self, reading, standing_w, now_mono, may_learn) -> bool:
+        """One read. Returns True when the value should be persisted."""
+        now = float(now_mono)
+        dt = (0.0 if self.last is None
+              else max(0.0, min(IDLE_GAP_S, now - self.last)))
+        self.last = now
+        standing = _num(standing_w)
+        if not may_learn or standing is None or abs(standing) > IDLE_ASK_W:
+            self.quiet_since = None
+            return False
+        if self.quiet_since is None:
+            self.quiet_since = now
+        b = _num(reading)
+        if (now - self.quiet_since < IDLE_QUIET_S or b is None
+                or abs(b) > IDLE_SAMPLE_W or dt <= 0.0):
+            return False
+        if self.value is None:
+            self.acc_w += b * dt
+            self.acc_s += dt
+            if self.acc_s < IDLE_FIRST_S:
+                return False
+            self.value = self.acc_w / self.acc_s
+        else:
+            self.value += (b - self.value) * min(1.0, dt / IDLE_TAU_S)
+        if self.saved is None or abs(self.value - self.saved) >= IDLE_SAVE_W:
+            self.saved = self.value
+            return True
+        return False

goodwe_controller/app/inverter.py

@@ -123,9 +123,11 @@ from datetime import datetime
 
 from .clamp import ClampResult
 from .delivery import DeliveryConfig, DeliveryWatchdog
+from . import messages
 # SAFETY-37. The freshness policy, and the ONE place its bounds are written.
 # freshness.py imports nothing from this package, so the direction is one-way.
 from .freshness import BOUNDS, Freshness
+from .idle import IdleReading
 # CFG-03's ONE in-code mirror of config.yaml's SAFETY-24 defaults. Imported
 # rather than retyped: the flat-keys path below needs `bms_soc_floor`'s
 # shipped default and a literal here would be the fourth defaults site that
@@ -316,6 +318,26 @@ 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.
+        # The evidence count is also used at N=1 (SAFETY-94); the rest at N>1.
+        self.refused = 0
+        self.refused_at = None
+        self.probe_from = None
+        self.ref_count = 0
+        self.ref_since = None
+        self.ref_sign = 0
+        self.ref_from = None
+        # SAFETY-97: what this unit's reading shows at idle; "gives nothing"
+        # is centred on it. Learned, persisted, restored (app/idle.py).
+        self.idle = IdleReading(data.get(self.key("idle_w")))
+
+    @property
+    def idle_w(self) -> float:
+        return self.idle.w
+
     # -- store ---------------------------------------------------------------
     def key(self, name: str) -> str:
         """This unit's namespaced Store key for `name`. See store.unit_key()."""
@@ -407,21 +429,31 @@ class Inverter:
         stop the site (`inputs_ok`). Folding one into the other is how a
         measurement fault ends up handing a sibling extra power.
         """
-        return self.batt_fresh.note(self.name)
+        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."""
+        """One line for the status page. Empty when there is nothing to say.
+
+        The words are `app/messages.py`'s (UX-09). main.py colours the row red
+        exactly when `is_live()` is False.
+        """
         if not self.has_writer():
-            return (f"{self.name}: NO SETPOINT ENTITY - this controller cannot "
-                    f"command it, and the site refuses rather than running at "
-                    f"part strength")
-        live, why = self.is_live(now)
+            return messages.row_no_setpoint(self.name)
+        live, _why = self.is_live(now)
+        held = (0.0 if self.rejected_since is None
+                else (now - self.rejected_since).total_seconds())
         if not live:
-            return f"{self.name}: NOT COMMANDABLE - {why}"
+            return messages.row_not_controllable(self.name, held, LINK_STALE_S)
         if self.rejected_since is not None:
-            held = (now - self.rejected_since).total_seconds()
-            return (f"{self.name}: writes rejected for {held:.0f} s - still "
-                    f"commandable until {LINK_STALE_S:.0f} s")
+            return messages.row_commands_refused(self.name, held, LINK_STALE_S)
         return ""
 
     def __repr__(self) -> str:

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/modetrade.py

@@ -0,0 +1,269 @@
+"""OPT-11 P3: each battery's role this tick, from its mode and the price runs.
+
+Pure: no I/O, no clock. main.py hands in the run plan (`priceruns`), each
+battery's state and the peak guard's answers, files each battery's range as
+its `mode` claim (P_MODE), and files the site trade as the `arbitrage` claim
+(P_ARBITRAGE), sized inside the modes (`size()`), only with battery modes on.
+With them off, `arbitrage.decide()` runs exactly as before.
+
+Roles (the page's Why line names them):
+  off      Off: [0, 0].
+  house    follows the house: charges from spare solar, gives power at any
+           hour (Solar first always; the other modes when there is no plan).
+  hold     Leftover solar / Cheap hours outside a give run: may charge from
+           spare solar, gives nothing, so its energy is kept for the run.
+  give     the same inside a give run: covers the house.
+  sell     inside the sell run, with selling on: gives its rating, to the
+           house first and the rest to the grid.
+  charge   inside the cheap run: charges from the grid.
+  rest     another battery charges from the grid, so this one may not charge
+           (the owner's 2026-09-27 answer 3: while one battery charges from the
+           grid the others cannot give power either; the allocator never
+           splits a target both ways).
+
+Rules that keep this safe (tests: test_modes_p3.py):
+  * every range holds 0 W (a mode may forbid a direction, never force one);
+  * a Solar first battery never charges from the grid;
+  * P4: with a day plan (`targets`), a Leftover solar battery charges from
+    the grid only up to its planned level, never above the ceiling; with
+    none it takes solar only (P3 option A). Cheap hours only fills to the
+    ceiling either way (`charge_to()`);
+  * grid charging needs a measured peak guard that is clear and a measured
+    headroom (SAFETY-45); the trade is sized to that headroom, whose aim is
+    `peak_cap_w - peak_margin_w` (SAFETY-79). It starts only at START_W or
+    more, and once the guard or the headroom stops it, it stays stopped for
+    the rest of that 15-minute period (`blocked`): a charge makes the other
+    batteries stop giving power, so a few watts of charge flipping on and
+    off would swing the house between them and the grid (measured on the
+    2026-09-09 replay: 13 flips in 4 minutes at a 3.5 kW house);
+  * selling needs selling on for that battery, the sell run, a price >= 0
+    now, and the battery above `arbitrage_soc_floor`; it stops there. The
+    peak guard never stops a sell (section 9.1: discharge is never capped);
+    it must only have measured the quarter;
+  * a battery out of a run (full, or at the floor) stays out until the run
+    ends, so the ceiling and the floor do not re-arm within one run;
+  * a battery that refuses a direction (SAFETY-52/73) takes no part in a
+    run in that direction: the refusal wins over the run;
+  * no grid charge while another battery drains for its monthly cycle
+    (`draining`, SAFETY-78): it would charge against the drain.
+"""
+
+from dataclasses import dataclass
+
+from .packmode import (CHEAP_HOURS, GRID_CHARGE_MODES, LEFTOVER_SOLAR,
+                       PLAN_CHARGE_MODES, SOLAR_FIRST)
+
+OFF, HOUSE, HOLD, GIVE, SELL, CHARGE, REST = (
+    "off", "house", "hold", "give", "sell", "charge", "rest")
+PRICE_MODES = (LEFTOVER_SOLAR, CHEAP_HOURS)
+
+# The smallest grid charge worth starting, in W. Under it the other batteries
+# would stop covering the house for less than they give.
+START_W = 500.0
+
+
+@dataclass(frozen=True)
+class Pack:
+    """One battery as this module needs it."""
+    name: str
+    use: bool
+    mode: str
+    sell: bool
+    rating_w: float
+    soc: float | None
+    capacity_kwh: float | None
+    live: bool = True
+    idle: bool = True           # not in a maintenance phase
+    refused: int = 0            # SAFETY-52/73: +1 refuses to give, -1 to charge
+
+
+@dataclass(frozen=True)
+class Tick:
+    ranges: dict                # name -> (lo, hi), only for idle batteries
+    roles: dict                 # name -> role
+    action: str | None          # "charge" | "sell" | None
+    ask_w: float                # signed site ask before sizing (0 if none)
+    why: str | None             # why no trade when a run is on, else None
+
+
+def _room_kwh(p: Pack, pct: float) -> float:
+    """kWh to `pct` (charging) or above it (selling); a battery with no
+    capacity set counts one hour at its rating, so a run is still sized."""
+    if p.capacity_kwh is None or p.soc is None:
+        return abs(p.rating_w) / 1000.0
+    return max(0.0, abs(pct - p.soc)) / 100.0 * float(p.capacity_kwh)
+
+
+def charge_to(p: Pack, ceiling_pct, targets=None):
+    """The level this battery may charge to from the grid, or None.
+
+    `targets` is the day plan (`dayplan.plan()`: name -> level), or None
+    when there is none (no forecast, stale, or not configured). With no plan
+    this is P3 option A exactly: Cheap hours to the ceiling, the others never.
+    With a plan, a Leftover solar battery charges only to its planned level
+    (the sun fills the rest); a battery the plan leaves out, Cheap hours only
+    included, gets the no-plan answer. Solar first never charges."""
+    if p.mode in GRID_CHARGE_MODES:
+        return float(ceiling_pct)
+    if targets is None or p.name not in targets \
+            or p.mode not in PLAN_CHARGE_MODES:
+        return None
+    t = targets[p.name]
+    return None if t is None else min(float(ceiling_pct), float(t))
+
+
+def chargers(packs, ceiling_pct, done=(), targets=None) -> list:
+    """Batteries that may charge from the grid in a cheap run: below the
+    level `charge_to()` allows them (P4: the day plan's)."""
+    out = []
+    for p in packs:
+        to = charge_to(p, ceiling_pct, targets)
+        if (to is not None and p.use and p.idle and p.live
+                and p.soc is not None and p.soc < to
+                and p.refused >= 0 and p.name not in done):
+            out.append(p)
+    return out
+
+
+def sellers(packs, floor_pct, done=()) -> list:
+    """Batteries that may sell in the sell run. Solar first never sells."""
+    return [p for p in packs
+            if p.use and p.idle and p.live and p.sell
+            and p.mode in PRICE_MODES
+            and p.soc is not None and p.soc > floor_pct
+            and p.refused <= 0 and p.name not in done]
+
+
+def energy(packs, floor_pct, ceiling_pct, done_charge=(), done_sell=(),
+           targets=None):
+    """`(charge_kwh, charge_kw, sell_kwh, sell_kw)` for `priceruns.plan()`.
+    With a day plan the charge is each battery's shortfall, so the cheap run
+    is only as long as the shortfall needs."""
+    ch = chargers(packs, ceiling_pct, done_charge, targets)
+    se = sellers(packs, floor_pct, done_sell)
+    return (sum(_room_kwh(p, charge_to(p, ceiling_pct, targets))
+                for p in ch),
+            sum(abs(p.rating_w) for p in ch) / 1000.0,
+            sum(_room_kwh(p, floor_pct) for p in se),
+            sum(abs(p.rating_w) for p in se) / 1000.0)
+
+
+def decide(runs, now, packs, *, charge_ok, sell_ok, trade_why, price_now,
+           headroom_w, floor_pct, ceiling_pct, house_w, charging_now=False,
+           blocked=False, done_charge=(), done_sell=(),
+           targets=None, draining=False) -> Tick:
+    """This tick's ranges, roles and site ask.
+
+    `runs` is the kept `priceruns.RunPlan` or None (no fresh prices).
+    `charge_ok` is True only when `TariffPlan.arbitrage()` allowed a trade
+    this tick with the MEASURED peak guard clear; `sell_ok` when it allowed
+    one with the guard measured (either state); else `trade_why` says why.
+    `headroom_w` is `peakguard.charge_headroom_w()` (None: unmeasured).
+    `house_w` is the measured house (grid + batteries), or None.
+    `charging_now` says last tick charged (then any headroom above 0 keeps
+    it going); `blocked` that the guard or the headroom stopped a charge in
+    this 15-minute period. `targets` is the day plan (`charge_to()`).
+    `draining` says a battery drains for its monthly cycle, so none may
+    charge from the grid (why "cycle").
+    """
+    plan_on = runs is not None and runs.on
+    in_cheap = plan_on and runs.cheap.holds(now) and runs.charge_useful()
+    in_give = plan_on and runs.give_at(now) is not None
+    in_sell = plan_on and runs.sell is not None and runs.sell.holds(now)
+
+    why = None
+    ch = chargers(packs, ceiling_pct, done_charge, targets) if in_cheap \
+        else []
+    if ch and draining:
+        ch, why = [], "cycle"
+    charging = False
+    if ch:
+        need = 0.0 if charging_now else START_W
+        if blocked:
+            why = "headroom"
+        elif not charge_ok:
+            why = trade_why
+        elif headroom_w is None or not headroom_w > need:
+            why = "headroom"
+        else:
+            charging = True
+    se = sellers(packs, floor_pct, done_sell) if in_sell and not charging \
+        else []
+    selling = False
+    if se:
+        if not sell_ok:
+            why = why or trade_why
+        elif price_now is None or price_now < 0.0 or house_w is None:
+            why = why or "negative"
+        else:
+            selling = True
+
+    ranges, roles = {}, {}
+    ch_names = {p.name for p in ch} if charging else set()
+    se_names = {p.name for p in se} if selling else set()
+    for p in packs:
+        r = abs(float(p.rating_w))
+        if not p.use:
+            role, lo, hi = OFF, 0.0, 0.0
+        elif p.name in ch_names:
+            role, lo, hi = CHARGE, -r, 0.0
+        elif charging:
+            # Another battery charges from the grid: this one may not charge
+            # (it would be grid charging too), and cannot give (one sign).
+            role, lo, hi = REST, 0.0, (r if p.mode == SOLAR_FIRST
+                                       or not plan_on or in_give else 0.0)
+        elif p.name in se_names:
+            role, lo, hi = SELL, -r, r
+        elif p.mode == SOLAR_FIRST or not plan_on:
+            role, lo, hi = HOUSE, -r, r
+        elif in_give:
+            role, lo, hi = GIVE, -r, r
+        else:
+            role, lo, hi = HOLD, -r, 0.0
+        roles[p.name] = role
+        if p.idle:
+            ranges[p.name] = (lo, hi)
+
+    if charging:
+        ask = -sum(abs(p.rating_w) for p in ch)
+        return Tick(ranges, roles, CHARGE, ask, None)
+    if selling:
+        ask = sum(abs(p.rating_w) for p in se) + max(0.0, float(house_w))
+        return Tick(ranges, roles, SELL, ask, None)
+    return Tick(ranges, roles, None, 0.0,
+                why if (in_cheap or in_sell) else None)
+
+
+def size(tick: Tick, bound, headroom_w) -> float:
+    """The site trade in W, inside what the batteries may place with their
+    modes (`bound` = main's loop bound) and, for a charge, the billed
+    quarter's headroom. 0.0 means no trade (a 0 W trade is a park order and
+    is never filed)."""
+    if tick.action is None or bound is None:
+        return 0.0
+    lo, hi = bound
+    if tick.action == CHARGE:
+        cap = min(-float(tick.ask_w), -float(lo),
+                  float(headroom_w) if headroom_w is not None else 0.0)
+        return -max(0.0, cap)
+    return max(0.0, min(float(tick.ask_w), float(hi)))
+
+
+def weights(roles: dict, base, target_w: float):
+    """Who carries the site target first (design 3.5). Selling: the sellers.
+    Giving power: batteries in a give run before Solar first. Charging from
+    the grid: only the chargers. Otherwise `base` unchanged. Comfort only;
+    the ranges above are the permission."""
+    names = sorted(roles)
+    first = None
+    if target_w > 0 and any(r == SELL for r in roles.values()):
+        first = {n for n in names if roles[n] == SELL}
+    elif target_w > 0 and any(r == GIVE for r in roles.values()):
+        first = {n for n in names if roles[n] in (GIVE, SELL)}
+    elif target_w < 0 and any(r == CHARGE for r in roles.values()):
+        first = {n for n in names if roles[n] == CHARGE}
+    if not first:
+        return base
+    w = {n: (1.0 if base is None else float(base.get(n, 1.0))) for n in names}
+    out = {n: (w[n] if n in first else 0.0) for n in names}
+    return out if any(v > 0.0 for v in out.values()) else base

goodwe_controller/app/mqtt.py

@@ -7,8 +7,10 @@ That separation is deliberate; observability must never be able to take down
 control.
 """
 
+import asyncio
 import json
 import logging
+import re
 
 try:
     import paho.mqtt.client as mqtt
@@ -375,7 +377,26 @@ def _payload(name, object_id, unique_id, state_topic, device,
     return cfg
 
 
-def discovery_payloads(units=(), omit=(), include=()) -> list:
+def unit_unique_id(slug: str, key: str) -> str:
+    """One unit's entity `unique_id` (also its config topic's middle part)."""
+    return f"{BASE}_unit_{slug}_{key}"
+
+
+def _unit_places(names):
+    """`(slug, device, prefix)` for each roster name, in order."""
+    slugs = unit_slugs(names)
+    for i, (name, slug) in enumerate(zip(names, slugs)):
+        # ⚠️ `i == 0` IS THE ASYMMETRY, IN ONE LINE. The first roster entry
+        # keeps the device it already has and carries its name in the ENTITY
+        # name instead; every later one gets its own device and does not.
+        # Either way HA composes device-name + entity-name into the same
+        # string, which is why `object_id` can be written once for both.
+        device = DEVICE if i == 0 else unit_device(name, slug)
+        prefix = f"{_title(name)} " if i == 0 else ""
+        yield slug, device, prefix
+
+
+def discovery_payloads(units=(), omit=(), include=(), modes=()) -> list:
     """Every `(topic, payload)` this add-on announces, in announcement order.
 
     Split out of `_announce()` so that the acceptance criterion can be graded as
@@ -389,6 +410,8 @@ def discovery_payloads(units=(), omit=(), include=()) -> list:
     the output here (`_payload()`'s note, and test_mqtt.py part 1 asserts an
     ordered LIST precisely because a re-order is a zero-byte edit that
     re-announces every entity on a live install).
+
+    `modes` (OPT-11 P2) is the battery modes offered, empty when they are off.
     """
     omit = set(omit)
     include = [k for k in include if k not in omit]
@@ -400,19 +423,10 @@ def discovery_payloads(units=(), omit=(), include=()) -> list:
             f"homeassistant/sensor/{BASE}_{key}/config",
             _payload(name, object_id, f"{BASE}_{key}", f"{BASE}/{key}",
                      DEVICE, unit, dev_class, state_class, icon)))
-    names = announced_units(units)
-    slugs = unit_slugs(names)
     site_slug = _slug(DEVICE["name"])
-    for i, (name, slug) in enumerate(zip(names, slugs)):
-        # ⚠️ `i == 0` IS THE ASYMMETRY, IN ONE LINE. The first roster entry
-        # keeps the device it already has and carries its name in the ENTITY
-        # name instead; every later one gets its own device and does not.
-        # Either way HA composes device-name + entity-name into the same
-        # string, which is why `object_id` below can be written once for both.
-        device = DEVICE if i == 0 else unit_device(name, slug)
-        prefix = f"{_title(name)} " if i == 0 else ""
+    for slug, device, prefix in _unit_places(announced_units(units)):
         for key, oid, label, unit, dev_class, state_class, icon in UNIT_SENSORS:
-            unique_id = f"{BASE}_unit_{slug}_{key}"
+            unique_id = unit_unique_id(slug, key)
             out.append((
                 f"homeassistant/sensor/{unique_id}/config",
                 _payload(prefix + label,
@@ -427,12 +441,135 @@ def discovery_payloads(units=(), omit=(), include=()) -> list:
             f"homeassistant/sensor/{BASE}_{key}/config",
             _payload(name, object_id, f"{BASE}_{key}", f"{BASE}/{key}",
                      DEVICE, unit, dev_class, state_class, icon)))
+    # OPT-11 P2: last, and only when battery modes are on.
+    out.extend(mode_payloads(units, modes))
     return out
 
 
+# --- OPT-11 P2: each battery's switch and mode, as HA entities ---------------
+# Announced only when battery modes are on, after every other row, so no
+# existing row moves. A command goes through Controller.handle_action(), the
+# page's /action path. DECISIONS/OPT-11-battery-modes.md has the record.
+#
+# The select's options are these labels, in `packmode.MODES` order. A new mode
+# (P3) is a new entry here and a new option at the end; no id changes.
+MODE_LABELS = {"solar_first": "Solar first", "leftover_solar": "Leftover solar",
+               "cheap_hours": "Cheap hours only"}         # OPT-11 P3
+USE_ON, USE_OFF = "ON", "OFF"
+# A longer command payload is refused before it is decoded.
+MAX_COMMAND_BYTES = 64
+# The store key holding the mode config topics last announced, so that turning
+# modes off can remove exactly those (an empty retained config) and an install
+# that never turned them on publishes nothing new.
+MODE_CONFIGS_KEY = "mqtt_mode_configs"
+_MODE_CONFIG_RE = re.compile(
+    rf"homeassistant/(select|switch)/{BASE}_unit_[a-z0-9_]+_(mode|use)/config")
+_COMMAND_RE = re.compile(rf"{BASE}/unit/([a-z0-9_]+)/(mode|use)/set")
+# (entity key, HA component, entity name, icon)
+MODE_ENTITIES = [
+    ("mode", "select", "Mode", "mdi:battery-sync"),
+    ("use", "switch", "Use", "mdi:power"),
+]
+
+
+def mode_payloads(units, modes) -> list:
+    """The `(topic, payload)` for each battery's select and switch.
+
+    Every roster entry gets them, also at a roster of one. The device rule is
+    TEL-07's: the first battery's rows go on the site device with its name in
+    front, each later battery's on its own device. Empty when `modes` is empty.
+    """
+    if not modes:
+        return []
+    site_slug = _slug(DEVICE["name"])
+    options = [MODE_LABELS[m] for m in modes]
+    out = []
+    for slug, device, prefix in _unit_places([str(u) for u in units]):
+        for key, component, label, icon in MODE_ENTITIES:
+            unique_id = unit_unique_id(slug, key)
+            state = f"{BASE}/{unit_state_key(slug, key)}"
+            cfg = {
+                "name": prefix + label,
+                "object_id": f"{site_slug}_{slug}_{key}",
+                "unique_id": unique_id,
+                "state_topic": state,
+                "command_topic": f"{state}/set",
+            }
+            if component == "select":
+                cfg["options"] = options
+            else:
+                cfg["payload_on"] = USE_ON
+                cfg["payload_off"] = USE_OFF
+            # HA sends commands unretained; a retained one is ignored anyway.
+            cfg["retain"] = False
+            cfg["availability_topic"] = AVAILABILITY
+            cfg["device"] = device
+            cfg["icon"] = icon
+            out.append((f"homeassistant/{component}/{unique_id}/config", cfg))
+    return out
+
+
+def mode_retractions(stored, current) -> list:
+    """Config topics announced before and not now: each gets an empty
+    retained config, which removes the entity from HA. Anything in the store
+    that is not one of our mode config topics is ignored."""
+    if not isinstance(stored, list):
+        return []
+    keep = set(current)
+    return list(dict.fromkeys(t for t in stored if isinstance(t, str)
+                              and _MODE_CONFIG_RE.fullmatch(t)
+                              and t not in keep))
+
+
+def mode_configs(units, modes, stored) -> tuple:
+    """`(keep, retract)` at start-up: the mode config topics to store, and the
+    ones to remove now. A removal stays in `keep`, so a start with no broker
+    does not forget it; resending an empty config is harmless."""
+    current = [t for t, _ in mode_payloads(units, modes)]
+    retract = mode_retractions(stored, current)
+    return current + retract, retract
+
+
+def parse_command(topic, payload, retained, modes):
+    """`(slug, action, value, reject)` for one message on a command topic.
+
+    `action` is `pack_use` or `pack_mode`. `value` is what /action would be
+    sent: a bool for the switch, a mode key for the select, or None for a
+    payload that is neither (the store path then refuses it). `reject` is a
+    reason when the message is dropped here: replayed by the broker (retained),
+    too long, not UTF-8, or not a command topic.
+    """
+    m = _COMMAND_RE.fullmatch(topic) if isinstance(topic, str) else None
+    if m is None:
+        return None, None, None, "topic"
+    slug, key = m.group(1), m.group(2)
+    action = "pack_use" if key == "use" else "pack_mode"
+    if retained:
+        return slug, action, None, "retained"
+    if not isinstance(payload, (bytes, bytearray)) \
+            or len(payload) > MAX_COMMAND_BYTES:
+        return slug, action, None, "size"
+    try:
+        text = bytes(payload).decode("utf-8")
+    except UnicodeDecodeError:
+        return slug, action, None, "encoding"
+    if key == "use":
+        value = {USE_ON: True, USE_OFF: False}.get(text)
+    else:
+        value = next((k for k in modes if MODE_LABELS.get(k) == text), None)
+    return slug, action, value, None
+
+
 class MqttPublisher:
+    # OPT-11 P2. Class defaults, so a publisher built without them (and every
+    # test fixture that builds one with __new__) behaves as before.
+    modes = ()
+    retract = ()
+    _loop = None
+    _handler = None
+
     def __init__(self, host, port, username=None, password=None, omit=(),
-                 units=(), include=()):
+                 units=(), include=(), modes=(), retract=()):
         # `omit` drops sensor keys from discovery entirely. ⚠️ Announcing a
         # sensor that nothing will ever publish to is not harmless here:
         # p1_sample_age_s is a watchdog input, and an entity that exists but is
@@ -448,6 +585,10 @@ class MqttPublisher:
         # second reading of the option. Defaults to empty, so a caller that has
         # not been taught about it announces exactly what it announced before.
         self.include = [str(k) for k in include]
+        # OPT-11 P2: the modes offered (empty when battery modes are off), and
+        # the mode config topics to remove (`mode_retractions()`).
+        self.modes = tuple(modes)
+        self.retract = [str(t) for t in retract]
         self.enabled = mqtt is not None and bool(host)
         self.client = None
         if not self.enabled:
@@ -470,7 +611,8 @@ class MqttPublisher:
         # paho DROPS QoS-0 publishes when disconnected, silently. The result is
         # an add-on that logs "MQTT connected" and creates no entities at all.
         # As a bonus, this also re-announces after every reconnect.
-        self.client.on_connect = lambda *_args, **_kw: self._announce()
+        self.client.on_connect = lambda *_args, **_kw: self._on_connect()
+        self.client.on_message = self._on_message
         try:
             self.client.connect(host, int(port), keepalive=60)
             self.client.loop_start()
@@ -485,10 +627,35 @@ class MqttPublisher:
         # diffing what actually goes on the wire - and a payload built here
         # instead would be one this add-on publishes and no check has ever seen.
         for topic, cfg in discovery_payloads(self.units, self.omit,
-                                             self.include):
+                                             self.include, self.modes):
             self.client.publish(topic, json.dumps(cfg), retain=True)
+        for topic in self.retract:
+            self.client.publish(topic, "", retain=True)
         self.client.publish(AVAILABILITY, "online", retain=True)
 
+    def _on_connect(self) -> None:
+        self._announce()
+        if self.modes:
+            for key in ("mode", "use"):
+                self.client.subscribe(f"{BASE}/unit/+/{key}/set")
+
+    def bind(self, loop, handler) -> None:
+        """OPT-11 P2: hand each command to `handler(topic, payload, retained)`,
+        a coroutine function run on `loop` (the controller's)."""
+        self._loop, self._handler = loop, handler
+
+    def _on_message(self, _client, _userdata, msg) -> None:
+        # paho's network thread: nothing is done here but the handoff.
+        loop, handler = self._loop, self._handler
+        if loop is None or handler is None:
+            _LOG.debug("MQTT command before start-up ignored: %s", msg.topic)
+            return
+        try:
+            asyncio.run_coroutine_threadsafe(
+                handler(msg.topic, bytes(msg.payload), bool(msg.retain)), loop)
+        except RuntimeError as err:  # the loop has closed
+            _LOG.debug("MQTT command dropped: %s", err)
+
     def publish(self, values: dict) -> None:
         if not self.enabled or self.client is None:
             return

goodwe_controller/app/p1.py

@@ -47,6 +47,11 @@ 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)
+
 try:
     import paho.mqtt.client as mqtt
 except ImportError:  # pragma: no cover - container always has it
@@ -180,7 +185,8 @@ def make_sample(source: str, import_w, export_w, *, phases: int,
     # already applied a sign we are about to apply again - reject it rather
     # than silently double-signing the control loop.
     if imp < 0 or exp < 0:
-        raise P1Error(f"unsigned registers cannot be negative (import={imp:g} export={exp:g})")
+        raise P1Error(f"import and export readings cannot be negative "
+                      f"(import={imp:g} export={exp:g})")
 
     per_phase = per_phase_import = None
     if phase_import_w is not None or phase_export_w is not None:
@@ -188,8 +194,8 @@ def make_sample(source: str, import_w, export_w, *, phases: int,
         pe = list(phase_export_w or [0.0] * len(pi))
         if len(pi) != phases or len(pe) != phases:
             raise P1Error(
-                f"phase count mismatch: telegram has {len(pi)} import / {len(pe)} export "
-                f"phases, meter_phases is {phases}")
+                f"the meter sent {len(pi)} import and {len(pe)} export phases, "
+                f"but {_S('meter_phases')} is {phases}")
         vals = [_watts(a, f"L{i + 1} import") - _watts(b, f"L{i + 1} export")
                 for i, (a, b) in enumerate(zip(pi, pe))]
         per_phase = tuple(vals)
@@ -467,7 +473,7 @@ class P1Ingest:
         """
         self.parse_errors += 1
         self.last_error = str(err)
-        _LOG.warning("P1 telegram rejected: %s", err)
+        _LOG.warning("A meter message could not be read: %s", err)
 
     # -- what consumers read -------------------------------------------------
     def age_s(self) -> float | None:
@@ -519,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.
 
@@ -569,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)
@@ -578,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:
@@ -613,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:
@@ -1160,37 +1181,37 @@ def validate_meter_options(opts: dict, phases: int, max_age_s: float) -> list[st
         exp = str(opts.get("p1_export_entity", "") or "").strip()
         if not imp or not exp:
             problems.append(
-                f"meter_source {SOURCE_HA} needs both p1_import_entity and "
-                f"p1_export_entity (got {imp or '<blank>'!r} / {exp or '<blank>'!r})")
+                f"{_S('meter_source')} is {SOURCE_HA!r}, so it needs "
+                f"{_S('p1_import_entity')} and {_S('p1_export_entity')}. They "
+                f"are {messages.shown(imp)} and {messages.shown(exp)}.")
     elif source == SOURCE_HA_SIGNED:
         net = str(opts.get("p1_net_entity", "") or "").strip()
         phase_net = [str(e).strip() for e in
                      (opts.get("p1_phase_net_entities") or []) if str(e).strip()]
         if not net:
             problems.append(
-                f"meter_source {SOURCE_HA_SIGNED} needs p1_net_entity "
-                "(sensor.p1_sample_age_s would otherwise be announced with "
-                "nothing feeding it)")
+                f"{_S('meter_source')} is {SOURCE_HA_SIGNED!r}, so it needs "
+                f"{_S('p1_net_entity')}.")
         if phase_net and len(phase_net) != phases:
             problems.append(
-                f"p1_phase_net_entities has {len(phase_net)} entities but "
-                f"meter_phases is {phases} - every telegram would be rejected "
-                "on the phase-count check")
+                f"{_S('p1_phase_net_entities')} has {len(phase_net)} entities, "
+                f"but {_S('meter_phases')} is {phases}. Make them match.")
     elif source == SOURCE_MQTT:
         if not str(opts.get("meter_mqtt_topic", "") or "").strip():
-            problems.append(f"meter_source {SOURCE_MQTT} needs meter_mqtt_topic")
+            problems.append(f"{_S('meter_source')} is {SOURCE_MQTT!r}, so it "
+                            f"needs {_S('meter_mqtt_topic')}.")
     elif source == SOURCE_HOMEWIZARD:
         host, port_s = homewizard_host_port(opts)
         if not host:
             problems.append(
-                f"meter_source {SOURCE_HOMEWIZARD} needs p1_host (the meter's "
-                "own address, e.g. 192.168.2.250)")
+                f"{_S('meter_source')} is {SOURCE_HOMEWIZARD!r}, so it needs "
+                f"{_S('p1_host')}, the meter's address on your network.")
         if port_s:
             try:
                 int(port_s)
             except ValueError:
-                problems.append(f"p1_host {opts.get('p1_host')!r} has an "
-                                "unparseable port")
+                problems.append(f"{_S('p1_host')} is {messages.shown(opts.get('p1_host'))}, and "
+                                "its port is not a number.")
         try:
             # ⚠️ Not `or 5`: that turns an explicit 0 into the default, and a
             # cadence of 0 is a misconfiguration that must be reported, not
@@ -1198,23 +1219,26 @@ def validate_meter_options(opts: dict, phases: int, max_age_s: float) -> list[st
             raw = opts.get("meter_poll_s", 5)
             poll_s = float(5 if raw is None or raw == "" else raw)
         except (TypeError, ValueError):
-            problems.append(f"meter_poll_s {opts.get('meter_poll_s')!r} is not a number")
+            problems.append(f"{_S('meter_poll_s')} is "
+                            f"{messages.shown(opts.get('meter_poll_s'))}, which is not a "
+                            "number.")
         else:
             if poll_s <= 0:
-                problems.append("meter_poll_s must be positive")
+                problems.append(f"{_S('meter_poll_s')} must be above 0.")
             # ⚠️ The age can never be fresher than the poll interval. At or past
             # max_age_s every reading is stale before its successor arrives, so
             # the controller would sit permanently on missing inputs while the
             # meter is perfectly healthy - refuse it rather than ship that.
             elif poll_s >= max_age_s:
                 problems.append(
-                    f"meter_poll_s {poll_s:.1f} is not under meter_max_age_s "
-                    f"{max_age_s:.1f} - every reading would go stale before the "
-                    "next poll")
+                    f"{_S('meter_poll_s')} is {poll_s:.1f}, not below "
+                    f"{_S('meter_max_age_s')} at {max_age_s:.1f}. Poll more "
+                    "often, or every reading goes stale.")
     else:
         problems.append(
-            f"meter_source {source!r} is not one of "
-            + ", ".join((SOURCE_HA, SOURCE_MQTT, SOURCE_HA_SIGNED, SOURCE_HOMEWIZARD)))
+            f"{_S('meter_source')} is {source!r}. Choose one of: off, "
+            + ", ".join((SOURCE_HA, SOURCE_MQTT, SOURCE_HA_SIGNED, SOURCE_HOMEWIZARD))
+            + ".")
     return problems
 
 
@@ -1261,9 +1285,8 @@ def build_source(opts: dict, ingest: P1Ingest, session, broker: dict | None):
         # 0 W cycle, which is fail-safe. The refusal above is for cadences that
         # can NEVER be fresh.
         if poll_s > ingest.max_age_s / 2:
-            _LOG.warning("meter_poll_s %.1f leaves no room under meter_max_age_s "
-                         "%.1f: one missed poll makes the reading stale. The meter "
-                         "updates every ~5 s; 5 s against 30 s is the tested pair.",
+            _LOG.warning("“Time between meter reads” (%.1f s) is too close to "
+                         "“Reading too old after” (%.1f s). Use 5 s and 30 s.",
                          poll_s, ingest.max_age_s)
         return HomeWizardLocalSource(session, ingest, host, port=port, poll_s=poll_s)
     if source == SOURCE_MQTT:

goodwe_controller/app/packmode.py

@@ -0,0 +1,129 @@
+"""OPT-11: each battery's mode and on/off switch, as limits and weights.
+
+Pure: no I/O, no clock. main.py reads the store, calls these, and files the
+result as a `mode` claim (arbiter.P_MODE) and as the charge weights.
+DECISIONS/OPT-11-battery-modes.md has the record; OPT-11-design section 1 has
+the modes.
+
+Two rules hold for every mode, and they are what keeps modes safe:
+
+1. A mode range always holds 0 W. A mode may forbid a direction, never force
+   one, so batteries never move power in opposite directions because of a mode
+   (allocator.unit_interval() drops a range without 0 as a software fault).
+2. A mode is a limit, not a weight. A weight of 0 does not keep a battery out:
+   allocator._fill()'s last-resort pass still uses it. So "may not" is a range,
+   and weights only set the order among batteries that may.
+
+`mode_range()` is the switch alone (Off is [0, 0]). P3 adds the price runs:
+`modetrade.decide()` narrows each battery's range by its role this tick
+(hold for the expensive hours, charge from the grid, sell), and main.py files
+the intersection. Selling is a per-battery choice (`pack_sell`, the owner's
+2026-09-27 answer), for Leftover solar and Cheap hours only.
+"""
+
+from dataclasses import dataclass
+
+from .store import unit_key
+
+SOLAR_FIRST = "solar_first"
+LEFTOVER_SOLAR = "leftover_solar"
+CHEAP_HOURS = "cheap_hours"         # OPT-11 P3
+
+# The modes a battery may be set to, in the order the page and the HA select
+# list them. The first is the default when the store has no value. A new mode
+# is appended, never inserted: automations send the HA labels (P2).
+MODES = (SOLAR_FIRST, LEFTOVER_SOLAR, CHEAP_HOURS)
+DEFAULT_MODE = SOLAR_FIRST
+
+# Store keys, per battery: `unit/<name>/<key>` (store.unit_key()).
+USE_KEY = "pack_use"
+MODE_KEY = "pack_mode"
+SELL_KEY = "pack_sell"              # OPT-11 P3: sell in the sell run
+
+# Owner decision 2026-09-29 (option A): selling is off until it can be judged
+# on the price the grid pays. While False, `read()` answers `sell=False`
+# whatever the store holds, the page shows no switch and `pack_sell` is
+# refused; the sell code in modetrade/priceruns stays, unreachable.
+SELLING_ENABLED = False
+
+# The modes that may charge from the grid in a cheap run with no day plan.
+# Leftover solar takes solar only then (owner decision 2026-09-29, option A).
+GRID_CHARGE_MODES = (CHEAP_HOURS,)
+# OPT-11 P4: with a fresh solar forecast, the day plan (dayplan.py) lets
+# Leftover solar charge from the grid, by the shortfall only. Cheap hours only
+# ignores the plan (fills to the ceiling); Solar first never grid-charges.
+PLAN_CHARGE_MODES = (LEFTOVER_SOLAR,)
+
+
+def enabled(opts) -> bool:
+    """Battery modes are on only when the option is exactly true. One answer,
+    read by the controller and by the MQTT announcement."""
+    return opts.get("battery_modes_enabled") is True
+
+
+@dataclass(frozen=True)
+class PackMode:
+    """One battery's choice: on or off, its mode, and selling."""
+    use: bool = True
+    mode: str = DEFAULT_MODE
+    sell: bool = False
+
+    @property
+    def can_sell(self) -> bool:
+        """Selling applies to the price modes only; Solar first never sells.
+        False for every battery while SELLING_ENABLED is False."""
+        return SELLING_ENABLED and self.mode in (LEFTOVER_SOLAR, CHEAP_HOURS)
+
+    @property
+    def key(self) -> str:
+        """The page's word for this state: a mode, or `off`."""
+        return self.mode if self.use else "off"
+
+
+def read(data: dict, name: str) -> PackMode:
+    """Battery `name`'s choice from the store's data. A missing or unknown
+    value falls back to the default (on, Solar first), never to Off: a store
+    written by a later version must not switch a battery off here."""
+    use = data.get(unit_key(name, USE_KEY), True)
+    mode = data.get(unit_key(name, MODE_KEY), DEFAULT_MODE)
+    return PackMode(use=use is not False,
+                    mode=mode if mode in MODES else DEFAULT_MODE,
+                    sell=SELLING_ENABLED
+                    and data.get(unit_key(name, SELL_KEY)) is True)
+
+
+def mode_range(pm: PackMode, rating_w: float) -> tuple:
+    """`(lo, hi)` in W for this battery's switch. Always holds 0 W.
+
+    Off asks for 0 W both ways; On allows the rating both ways. main.py files
+    this intersected with the role range from `modetrade.decide()`.
+    """
+    if not pm.use:
+        return 0.0, 0.0
+    r = abs(float(rating_w))
+    return -r, r
+
+
+def charge_weights(base, modes: dict, target_w: float):
+    """The allocator's weights with the solar order applied (design 3.5).
+
+    `base` is packshare.weights()' answer (None for "all 1.0"). While the site
+    charges (`target_w < 0`), a Leftover solar battery weighs 0 and a Solar
+    first battery keeps its weight, so the fill gives the Solar first batteries
+    everything they can take before the last-resort pass reaches the others.
+    Giving power keeps `base`; `modetrade.weights()` adds the run order.
+
+    When no battery that is on would keep a positive weight (all Leftover
+    solar, or every Solar first one at 0), `base` is returned unchanged, so the
+    order among equals stays OPT-09's rather than an equal split.
+    """
+    if float(target_w) >= 0.0 or not modes:
+        return base
+    names = sorted(modes)
+    w = {n: (1.0 if base is None else float(base.get(n, 1.0))) for n in names}
+    out = {n: (0.0 if modes[n].mode in (LEFTOVER_SOLAR, CHEAP_HOURS)
+               else w[n])
+           for n in names}
+    if not any(out[n] > 0.0 for n in names if modes[n].use):
+        return base
+    return out

goodwe_controller/app/peakguard.py

@@ -143,6 +143,10 @@ because the money is spent on `max(month's peak so far, this quarter)`:
 
     ceiling_w = max(peak_cap_w, the month's banked peak)
 
+SAFETY-79: the guard AIMS `peak_margin_w` under that ceiling
+(`quarter_target_w()`), so a quarter that lands a little high still stays under
+it. `ceiling_w` stays the real limit for reports and the bill.
+
 Once a month's peak already stands at 5013 W, holding every later quarter to
 3500 W buys nothing - the bill for that month is already 5013 W - while the
 holding itself costs real charging the site wanted. Raising the ceiling to a peak
@@ -393,35 +397,36 @@ function, so whichever way the owner answers, this file does not change and does
 not need re-testing. Nothing here indexes a phase.
 """
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 
+from . import messages
 from .arbiter import ACTUATOR_SITE, P_PEAK, Claim
 from .control import peak_at_risk
 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"
 
@@ -452,7 +457,13 @@ PEAK_OPTION_DEFAULTS = {
     # and it is consistent with DoD 90 on a full pack. It exists so validate.py
     # rule 8 can refuse a `peak_soc_floor` at or below it - see that rule.
     "bms_soc_floor": 10,
+    # SAFETY-79. Watts the guard aims under `peak_cap_w`, so a quarter that
+    # lands a little high still stays under the cap. Owner decision 2026-09-28.
+    "peak_margin_w": 50,
 }
+# SAFETY-79. config.yaml's schema range for `peak_margin_w`, mirrored so
+# validate.py can refuse it in words; test_peakguard.py pins it to the file.
+PEAK_MARGIN_RANGE_W = (0, 500)
 
 
 @dataclass(frozen=True)
@@ -473,29 +484,49 @@ class PeakDecision:
     projected_w: float | None = None
     excess_w: float = 0.0
     wanted_w: float | None = None    # the floor before `achievable_w` clamped it
+    target_w: float | None = None    # SAFETY-79: what the guard aims at
     saturated: bool = False
     # SAFETY-24. True when a forced discharge WAS wanted and the EMS-side SoC
     # floor refused to size it. Mutually exclusive with `saturated` by
     # construction: this branch asks for nothing, so it cannot have run out of
     # inverter. `soc_floor_reason` says WHICH of the two ways it bound.
+    # SAFETY-87: at N>=2 it may ask the batteries above their reserve for
+    # `able_w`, all they have, when that is not enough (`place_on_able()`).
     floor_limited: bool = False
     soc: float | None = None
     soc_floor: float | None = None
     soc_floor_reason: str | None = None
     reason: str = ""
+    # SAFETY-87, N>=2 only: the batteries at or under their own reserve,
+    # which give nothing for the peak, and what the others can give (None
+    # when they are not asked). See `place_on_able()`.
+    held: tuple = ()
+    able_w: float | None = None
 
     def explain(self) -> str:
+        """Idle: the status row's plain words (UX-08). Engaged: `reason`, the
+        technical record with every figure, for the log and the action log."""
         if self.floor_limited:
             return self.reason
         if not self.engaged:
             if self.projected_w is None:
-                return f"peak guard idle - {self.reason}"
-            return (f"peak guard idle - quarter projects "
-                    f"{self.projected_w:.0f} W under a {self.ceiling_w:.0f} W "
-                    f"ceiling ({self.ceiling_from})")
+                return messages.row_peak_guard_quiet()
+            return messages.row_peak_guard_idle(
+                self.projected_w, self.ceiling_w,
+                month_peak=self.ceiling_from == CEILING_MONTH_PEAK)
         return self.reason
 
 
+def blind_kind(blind: str) -> str:
+    """Which of the three kinds of blindness, as a key of
+    `messages.BLIND_WORDS`, for the status row."""
+    if blind == BLIND_FROZEN:
+        return "frozen"
+    if blind == BLIND_NO_BLOCK:
+        return "no_block"
+    return "gap"
+
+
 def quarter_ceiling_w(cap_w, reading) -> tuple[float, str]:
     """The average this quarter may not exceed, and where the number came from.
 
@@ -511,6 +542,15 @@ def quarter_ceiling_w(cap_w, reading) -> tuple[float, str]:
     return cap, CEILING_CAP
 
 
+def quarter_target_w(cap_w, margin_w, reading) -> float:
+    """SAFETY-79. The average the guard AIMS at: `margin_w` under
+    `quarter_ceiling_w()`, so under a month peak already banked as well as
+    under the cap. Aiming AT a banked peak can bank a few W over it, which
+    raises the bill as surely as going over the cap. Reports and the bill keep
+    the real limit (`ceiling_w`)."""
+    return quarter_ceiling_w(cap_w, reading)[0] - float(margin_w)
+
+
 def excess_w(projection, ceiling_w) -> float:
     """Watts that must come off the meter NOW to land the quarter on the ceiling.
 
@@ -553,8 +593,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
 
 
@@ -699,8 +740,45 @@ def binding_soc_floor(packs, soc_floor):
     return max(floors)
 
 
-def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
-           max_hold_s=None, frozen: bool = False) -> PeakDecision:
+def reserve_split(packs, soc_floor) -> tuple[list, tuple]:
+    """SAFETY-87: `(packs the guard may spend, names of those it may not)`,
+    each pack graded on its own floor by `pack_permissions()`."""
+    perms = pack_permissions(packs, soc_floor)
+    return ([p for p, (_n, why) in zip(packs, perms) if why is None],
+            tuple(n for n, why in perms if why is not None))
+
+
+def place_on_able(decision, held, *, able_w, soc, soc_floor) -> PeakDecision:
+    """SAFETY-87: `decision` with the batteries in `held` (at or under their
+    own reserve) giving nothing for the peak. `able_w`, `soc` and `soc_floor`
+    describe the others, as `decide()`'s arguments do for the roster. A
+    floor-limited decision is re-taken on them: they are asked for the need
+    up to `able_w`, and it stays floor-limited only if that is not enough.
+    `soc` and `soc_floor` keep the roster's verdict, as `decide()` echoed it.
+    DECISIONS/SAFETY-87-guard-uses-able-batteries.md."""
+    held = tuple(held)
+    if not decision.floor_limited or decision.wanted_w is None \
+            or discharge_permitted(soc, soc_floor) is not None:
+        return replace(decision, held=held)
+    wanted = float(decision.wanted_w)
+    floor = min(wanted, float(able_w))
+    head = (f"this 15-minute period heads for {decision.projected_w:.0f} W "
+            f"against a {decision.ceiling_w:.0f} W limit "
+            f"({decision.ceiling_from}), aiming at {decision.target_w:.0f} W. "
+            f"At the peak reserve, so giving nothing for the peak: "
+            f"{messages.names(held)}. The others are asked for {floor:+.0f} W")
+    if floor >= wanted:
+        return replace(decision, floor_limited=False, floor_w=floor,
+                       soc_floor_reason=None, held=held, able_w=float(able_w),
+                       reason=f"PEAK_GUARD: {head}")
+    return replace(decision, floor_w=floor, held=held, able_w=float(able_w),
+                   reason=(f"PEAK_GUARD_FLOOR_LIMITED: {head}, all they can "
+                           f"give, but {wanted:+.0f} W was needed, so this "
+                           f"period may go over the limit"))
+
+
+def decide(projection, *, batt_w, cap_w, margin_w, reading, achievable_w, soc,
+           soc_floor, max_hold_s=None, frozen: bool = False) -> PeakDecision:
     """The whole guard. Pure: no clock, no I/O, no state carried between calls.
 
     `batt_w`       MEASURED battery power, positive = discharge. None when the
@@ -718,8 +796,13 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
                    the pack for money. REQUIRED, and deliberately without a
                    default: a default here would be CFG-03's fourth defaults
                    site and TEST-14's quiet fallback in one line.
+    `margin_w`     SAFETY-79. Watts to aim under `cap_w` (`peak_margin_w`).
+                   REQUIRED for the same reason. `ceiling_w` stays the real
+                   limit for every report; only `excess_w` uses the target.
     """
     ceiling, from_where = quarter_ceiling_w(cap_w, reading)
+    target = quarter_target_w(cap_w, margin_w, reading)
+    aim = "" if target == ceiling else f", aiming at {target:.0f} W"
     ceil_top = abs(float(achievable_w))
 
     blind = blindness(projection, max_hold_s, frozen)
@@ -729,10 +812,10 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # see", which is one-directional and cannot cost pack energy.
         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)"))
+            target_w=target, blind=blind, projected_w=None,
+            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:
@@ -741,7 +824,7 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # measurement that is not there is a made-up number.
         return PeakDecision(
             engaged=False, floor_w=None, ceiling_w=ceiling,
-            ceiling_from=from_where, projected_w=projected,
+            ceiling_from=from_where, target_w=target, projected_w=projected,
             reason="no battery measurement to size a floor from")
     if QUARTER_S - float(projection.elapsed_s) <= 0.0:
         # A block with no seconds left cannot be influenced. This is degenerate
@@ -749,10 +832,10 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # the battery's own current output would be a claim that says nothing.
         return PeakDecision(
             engaged=False, floor_w=None, ceiling_w=ceiling,
-            ceiling_from=from_where, projected_w=projected,
+            ceiling_from=from_where, target_w=target, projected_w=projected,
             reason="the quarter has no seconds left to influence")
 
-    ex = excess_w(projection, ceiling)
+    ex = excess_w(projection, target)
     wanted = float(batt_w) + ex
     if wanted <= 0.0:
         # ⚠️ THE TEST IS ON THE FLOOR, NOT ON `excess > 0`, AND THE REPLAY IS WHY.
@@ -773,7 +856,8 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # the quantity being thresholded is simply the right one.
         return PeakDecision(
             engaged=False, floor_w=None, ceiling_w=ceiling,
-            ceiling_from=from_where, projected_w=projected, excess_w=ex,
+            ceiling_from=from_where, target_w=target, projected_w=projected,
+            excess_w=ex,
             wanted_w=wanted,
             reason="the load is under the level this quarter can afford")
 
@@ -791,35 +875,73 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # not the grid-following loop, which still has no SoC guard.
         return PeakDecision(
             engaged=True, floor_w=0.0, ceiling_w=ceiling,
-            ceiling_from=from_where, projected_w=projected, excess_w=ex,
+            ceiling_from=from_where, target_w=target, 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}){aim}, and {wanted:+.0f} W from the battery "
+                f"would 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
     return PeakDecision(
         engaged=True, floor_w=floor, ceiling_w=ceiling, ceiling_from=from_where,
-        blind=None, projected_w=projected, excess_w=ex, wanted_w=wanted,
-        saturated=saturated, soc=soc, soc_floor=soc_floor,
+        target_w=target, 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}){aim}, 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 "")))
+
+
+# SAFETY-81. A quarter must end this many W over the real limit before
+# "Load too high for battery" fires. Above the guard's own landing error at
+# margin 0 (up to +5.7 W, SAFETY-79 test check 5), which margin 0 accepts.
+ALARM_MISS_W = 10.0
+# ...and for this long without a break, so a load that peaks for a few seconds
+# (a hob or heater cycling) is not read as the rest of the quarter.
+ALARM_HOLD_S = 10.0
+
+
+def load_too_high(projection, *, batt_w, ceiling_w, achievable_w) -> bool:
+    """SAFETY-81. May "Load too high for battery" fire? Only if, with the
+    battery at full power from now on, the quarter still ends more than
+    `ALARM_MISS_W` over the real limit (`ceiling_w`, not the aim).
+
+    This is the miss itself, in W of the quarter average, so it does not have
+    `decide()`'s gain (900 / remaining): near a quarter's end that gain turns
+    a watt over the aim into thousands of W wanted.
+
+    The load is the held meter reading plus `batt_w`. The caller passes the
+    lower of this cycle's and the last cycle's battery reading, so a meter
+    sample taken before the battery's last increase is not counted twice
+    (DECISIONS/SAFETY-81-load-too-high.md). A real overload shows on the meter
+    before the battery moves, so that filter costs it no cycle.
+    """
+    remaining = QUARTER_S - float(projection.elapsed_s)
+    if batt_w is None or remaining <= 0.0:
+        return False
+    rest = float(projection.held_w) + float(batt_w) - float(achievable_w)
+    done_ws = (QUARTER_S * float(projection.projected_w)
+               - max(float(projection.held_w), 0.0) * remaining)
+    ends_w = (done_ws + max(rest, 0.0) * remaining) / QUARTER_S
+    return ends_w - float(ceiling_w) > ALARM_MISS_W
 
 
 def charge_headroom_w(decision) -> float | None:
@@ -1019,5 +1141,6 @@ def claim(decision: PeakDecision) -> Claim | None:
     return Claim.limit(SOURCE, P_PEAK, lo=float(decision.floor_w),
                        reason=("blind" if decision.blind
                                else "SoC floor" if decision.floor_limited
+                               and not decision.floor_w
                                else "quarter peak"),
                        actuator=ACTUATOR_SITE)

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)
@@ -1314,8 +1315,8 @@ def code_leaks(cls) -> list:
         src = dedent(inspect.getsource(cls))
         tree = ast.parse(src)
     except (OSError, TypeError, IndentationError, SyntaxError) as e:
-        _LOG.warning("could not read %s's source for the framework-key scan "
-                     "(%s); the double-counting guard is NOT enforced for it",
+        _LOG.warning("Could not read the code of price source %s (%s), so its "
+                     "double-counting check is skipped.",
                      getattr(cls, "id", cls), e)
         return []
     for node in ast.walk(tree):
@@ -1453,9 +1454,8 @@ def _validate_raw(points, caps):
         if abs(p.eur_per_kwh) > MAX_PLAUSIBLE_EUR_KWH:
             raise SourceUnavailable(
                 f"point at {p.start.isoformat()} is {p.eur_per_kwh} EUR/kWh, "
-                f"beyond +-{MAX_PLAUSIBLE_EUR_KWH} - the usual cause is a feed "
-                f"in EUR/MWh being read as EUR/kWh, which is a factor of 1000 "
-                f"and would make every hour look like an emergency")
+                f"beyond +-{MAX_PLAUSIBLE_EUR_KWH}, so the feed is probably in "
+                f"EUR/MWh")
         u = p.start.astimezone(timezone.utc)
         if seen is not None and u <= seen:
             raise SourceUnavailable(
@@ -1708,25 +1708,19 @@ def _points_from_columnar_json(body, expect_unit, scale,
     if len(times) != len(prices):
         raise SourceUnavailable(
             f"{COLUMNAR_TIME_KEY} has {len(times)} entries and "
-            f"{COLUMNAR_PRICE_KEY} has {len(prices)}; refusing to zip them. "
-            f"The short array would truncate the series silently, and a price "
-            f"series missing its last hours is one missing the evening peak - "
-            f"traded on as if complete, where no data at all would have "
-            f"switched arbitrage off (§11.4)")
+            f"{COLUMNAR_PRICE_KEY} has {len(prices)}, so the feed is cut short "
+            f"and none of it is used")
     unit = _columnar_unit(doc.get(COLUMNAR_UNIT_KEY, ""))
     if unit != _columnar_unit(expect_unit):
         raise SourceUnavailable(
             f"the feed reports {doc.get(COLUMNAR_UNIT_KEY)!r}, not "
-            f"{expect_unit!r}. This provider converts with a fixed factor of "
-            f"{scale}, so a changed unit is a factor of 1000 on every price "
-            f"with nothing downstream able to notice it")
+            f"{expect_unit!r}, so its prices cannot be converted")
     if doc.get("deprecated"):
         # Not a refusal: today's prices are still prices. But §11.4 makes a
         # dead feed look exactly like a quiet one, so the warning that the
         # source is going away has to be emitted while it still works.
-        _LOG.warning("the price feed reports deprecated=%r; it still answers, "
-                     "but this endpoint is scheduled to stop",
-                     doc.get("deprecated"))
+        _LOG.warning("The price feed says it will stop (deprecated=%r), "
+                     "though it still answers for now.", doc.get("deprecated"))
     out = []
     dropped = []
     for i, (t, v) in enumerate(zip(times, prices)):
@@ -1745,12 +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 feed published no price for %d of %d instants "
-                     "(index %s); those instants are left OUT of the series, "
-                     "never zero-filled - a missing hour is not a free hour",
-                     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 "
@@ -1796,16 +1789,16 @@ def dayahead_feed_url(plugin_id, opts, since, until, base, bzn) -> str:
     override = str(opts.get("price_feed_url") or "").strip()
     if override:
         _LOG.warning(
-            "price_feed_url is set, so %s is requesting %s exactly as "
-            "given and is adding NO date range to it. The public feed "
-            "answers a single Brussels day to a request that names no "
-            "range, and every hour past that day is then carried forward "
-            "from yesterday's profile and flagged provisional - §8.3 "
-            "drops provisional hours from the trade set, so arbitrage "
-            "would never see tomorrow as firm. Clear price_feed_url to "
-            "let this plugin ask for the %s..%s it was given.",
+            "price_feed_url is set, so %s asks for %s as given, and "
+            "tomorrow's prices may stay provisional. Clear it to ask for %s "
+            "to %s.",
             plugin_id, override, *(d.isoformat()
                                    for d in brussels_date_range(since, until)))
+        _LOG.debug(
+            "The public feed answers one Brussels day to a request that names "
+            "no range. Every later hour is then copied from yesterday and "
+            "marked provisional, and §8.3 leaves provisional hours out of "
+            "trading.")
         return override
     first, last = brussels_date_range(since, until)
     return dated_feed_url(base, bzn=bzn, start=first.isoformat(),
@@ -2011,11 +2004,9 @@ class CustomFormula(PriceProvider):
             raise SourceUnavailable(f"price_formula: {e}")
         if spec is None:
             raise SourceUnavailable(
-                "price_provider is 'custom_formula' but price_formula is "
-                "empty, so there are no coefficients to price anything with. "
-                "validate.py refuses this configuration at startup; reaching "
-                "it here means the options blob changed under a running "
-                "add-on")
+                "“Dynamic price source” (price_provider) is 'custom_formula', "
+                "but “Your own tariff formula” (price_formula) is empty. "
+                "Restart the add-on to check the settings again")
         url = dayahead_feed_url(self.id, opts, since, until,
                                 self.FEED_BASE, self.BZN)
         check_egress(url, self.capabilities())
@@ -2091,8 +2082,8 @@ def _emit_startup_preview(plugin, pid: str, points) -> None:
     try:
         lines = list(plugin.startup_preview(points))
     except Exception as e:                                    # noqa: BLE001
-        _LOG.warning("%s's startup preview raised (%s: %s); prices are "
-                     "unaffected - this is a log line, not a decision",
+        _LOG.warning("%s could not show its start-up preview (%s: %s). Prices "
+                     "are not affected.",
                      pid, type(e).__name__, e)
         return
     for line in lines:
@@ -2116,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()
@@ -2139,12 +2130,12 @@ async def load_prices(opts: dict, since: datetime, until: datetime,
         # Not silent, and not a traceback into the 30 s tick. validate.py
         # should have refused this at startup; if the add-on is running with it
         # anyway, the operator is told which key and what is wrong with it.
-        _LOG.error("price_taxes_profile cannot be used (%s: %s), so this fetch "
-                   "has NO tax component to add - it is not falling back to "
-                   "price_taxes_eur_kwh, because a silently different tax "
-                   "basis is the defect this option exists to remove. Fix the "
-                   "table or clear it; validate.py refuses it at startup",
+        _LOG.error("price_taxes_profile cannot be used (%s: %s), so no taxes "
+                   "are added to this price update. Fix the table or clear it.",
                    type(e).__name__, e)
+        _LOG.debug("price_taxes_eur_kwh is not used instead, because a "
+                   "silently different tax basis is the fault this setting "
+                   "exists to remove.")
         return PriceRead.no_data(
             f"price_taxes_profile cannot be used: {e}")
     if table is not None:

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} point{'' if points == 1 else 's'} "
-            f"over {hours} h)")
+    # 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()
@@ -437,9 +448,9 @@ class PriceHistory:
             # exactly what this handler says, and a third `ValueError` subclass
             # nobody has thought of is how this defect arrived the first time.
             self.last_error = f"unreadable ({err})"
-            _LOG.warning("price history at %s is %s - starting from empty. "
-                         "§8.3 carry-forward has nothing to carry until the "
-                         "next refresh has written a full day",
+            _LOG.warning("Price history at %s is %s, so it starts empty. "
+                         "Missing hours cannot be filled in until a full day "
+                         "is saved.",
                          self.path, self.last_error)
             return
         found = blob.get("version") if isinstance(blob, dict) else None
@@ -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; "
-                         "%d point(s) carried forward", 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/priceruns.py

@@ -0,0 +1,203 @@
+"""OPT-11 P3: price runs. Which consecutive firm price slots are cheap, which
+are expensive, and which one a battery may sell in.
+
+Pure: prices, the time and a few energy figures in, a `RunPlan` out. No I/O,
+no clock. `modetrade.py` turns the plan into each battery's range and the
+site's trade; main.py rebuilds the plan at most once per 15 minutes and keeps
+a run that has started until its end (`keep_started()`).
+
+The owner's SAFETY-46 answer (2026-09-25): a trade is a run of consecutive
+slots, not one 15-minute interval. OPT-11-design section 2 ("Prices") and
+DECISIONS/OPT-11-battery-modes.md have the record.
+
+* The CHEAP run is the cheapest consecutive firm window long enough to put
+  the planned energy in at the chargers' combined rating.
+* A slot is EXPENSIVE when its price is above the cheap run's mean by at
+  least the required spread (`cycle_cost_threshold_eur`, widened as
+  `TariffPlan.arbitrage()` widens it). Give runs are the maximal consecutive
+  expensive slots. Holding batteries cover the house in them. The mean is
+  the lower of the next cheap run's and `ref_eur_kwh`, the cheap run the
+  batteries last filled in (main.py keeps it for 12 h): energy bought at
+  03:00 is still worth that price at 08:00, when the next cheap run in sight
+  is today's dearer midday (measured: without it a Cheap hours battery spent
+  its night charge on flat morning prices, then had nothing at 19:00).
+* The SELL run is the dearest consecutive window inside one give run long
+  enough to sell the sellers' energy at their rating, with no slot below 0
+  (section 17 of the spec: never export at a negative price).
+* A provisional (carried) price is never part of any run (section 8.3).
+"""
+
+import math
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+from .price import _cover_table
+
+# How far ahead runs are looked for. A day: tonight's cheap hours and the next
+# evening's expensive ones, without holding a battery for a peak two days out.
+HORIZON = timedelta(hours=24)
+
+# No plan, and why (the page words are in homeview / ui_text).
+NO_PRICES = "no_prices"           # fewer than two firm slots ahead
+NOT_WORTH = "not_worth"           # no slot clears the required spread
+
+
+@dataclass(frozen=True)
+class Run:
+    start: datetime
+    end: datetime
+    mean_eur_kwh: float
+
+    def holds(self, when: datetime) -> bool:
+        return self.start <= when < self.end
+
+
+@dataclass(frozen=True)
+class RunPlan:
+    """What the prices say for the next day. `reason` is None when there is
+    a plan (a cheap run and at least one give run), else why there is none."""
+    cheap: Run | None
+    give: tuple
+    sell: Run | None
+    level_eur_kwh: float | None
+    reason: str | None
+    # A slot after the cheap run clears the spread over the CHEAP RUN'S OWN
+    # price (not the reference): only then is buying in it worth a cycle.
+    charge_worth: bool = False
+
+    @property
+    def on(self) -> bool:
+        return self.reason is None
+
+    def give_at(self, when):
+        return next((g for g in self.give if g.holds(when)), None)
+
+    def next_give(self, when):
+        """The give run under way at `when`, else the next one, else None."""
+        return next((g for g in self.give if g.end > when), None)
+
+    def charge_useful(self) -> bool:
+        """Charging in the cheap run pays only if, after it, a slot clears
+        the spread over the cheap run's own price."""
+        return self.cheap is not None and self.charge_worth
+
+
+def firm_slots(points, now: datetime, horizon: timedelta = HORIZON) -> list:
+    """`[(start, end, eur_kwh)]`, ascending: the firm slots that have not
+    ended and start within the horizon. A slot's span is TARIFF-14's rule
+    (`price._cover_table()`), so 15-minute and hourly series both work."""
+    out = []
+    for start, end, p in _cover_table(points):
+        if p.provisional or end <= now or start >= now + horizon:
+            continue
+        if end > start:
+            out.append((start, end, float(p.eur_per_kwh)))
+    return out
+
+
+def _segments(slots) -> list:
+    """Split slots into runs of consecutive ones (each starts where the last
+    ended). A gap or a provisional slot breaks a run."""
+    segs, cur = [], []
+    for s in slots:
+        if cur and s[0] != cur[-1][1]:
+            segs.append(cur)
+            cur = []
+        cur.append(s)
+    if cur:
+        segs.append(cur)
+    return segs
+
+
+def _hours(s) -> float:
+    return (s[1] - s[0]).total_seconds() / 3600.0
+
+
+def _mean(win) -> float:
+    h = sum(_hours(s) for s in win)
+    return sum(_hours(s) * s[2] for s in win) / h
+
+
+def _windows(segs, need_h):
+    """Every consecutive window that lasts at least `need_h` hours, shortest
+    such from each start. If no segment is that long, each whole segment."""
+    out = []
+    for seg in segs:
+        for i in range(len(seg)):
+            h, j = 0.0, i
+            while j < len(seg) and h < need_h - 1e-9:
+                h += _hours(seg[j])
+                j += 1
+            if h >= need_h - 1e-9:
+                out.append(seg[i:j])
+    return out or [seg for seg in segs]
+
+
+def need_hours(kwh, kw, slots) -> float:
+    """How long a run must last: `kwh` at `kw`, and at least one slot."""
+    one = min((_hours(s) for s in slots), default=1.0)
+    if not (kwh and kw) or kwh <= 0 or kw <= 0:
+        return one
+    return max(one, float(kwh) / float(kw))
+
+
+def plan(points, now: datetime, *, required_eur_kwh: float, charge_kwh,
+         charge_kw, sell_kwh, sell_kw, horizon: timedelta = HORIZON,
+         ref_eur_kwh=None) -> RunPlan:
+    """The run plan for the next `horizon`. Ties go to the earliest window."""
+    if not (isinstance(required_eur_kwh, (int, float))
+            and math.isfinite(required_eur_kwh) and required_eur_kwh >= 0):
+        raise ValueError("required_eur_kwh must be a finite number >= 0")
+    slots = firm_slots(points, now, horizon)
+    if len(slots) < 2:
+        return RunPlan(None, (), None, None, NO_PRICES)
+    segs = _segments(slots)
+    wins = _windows(segs, need_hours(charge_kwh, charge_kw, slots))
+    best = min(wins, key=lambda w: (round(_mean(w), 9), w[0][0]))
+    cheap = Run(best[0][0], best[-1][1], _mean(best))
+    base = cheap.mean_eur_kwh if ref_eur_kwh is None else min(
+        cheap.mean_eur_kwh, float(ref_eur_kwh))
+    level = base + float(required_eur_kwh)
+    # Expensive: clears the spread, strictly dearer than the cheap mean, and
+    # not part of the cheap run itself (a threshold of 0 must not overlap).
+    dear = [s for s in slots
+            if s[2] >= level and s[2] > cheap.mean_eur_kwh
+            and not (cheap.start <= s[0] < cheap.end)]
+    give_segs = _segments(dear)
+    give = tuple(Run(g[0][0], g[-1][1], _mean(g)) for g in give_segs)
+    worth = any(s[0] >= cheap.end and s[2] >= cheap.mean_eur_kwh
+                + float(required_eur_kwh) for s in dear)
+    if not give:
+        return RunPlan(cheap, (), None, level, NOT_WORTH)
+    # Sell: inside one give run, never over a slot priced below 0.
+    sellable = [part for g in give_segs
+                for part in _segments([s for s in g if s[2] >= 0.0])]
+    sell = None
+    if sellable:
+        sw = _windows(sellable, need_hours(sell_kwh, sell_kw, slots))
+        top = max(sw, key=lambda w: (round(_mean(w), 9),
+                                     -w[0][0].timestamp()))
+        sell = Run(top[0][0], top[-1][1], _mean(top))
+    return RunPlan(cheap, give, sell, level, None, worth)
+
+
+def keep_started(old: RunPlan | None, new: RunPlan, now: datetime) -> RunPlan:
+    """A run under way keeps going to its end (no flapping on a new plan): the
+    cheap run, the give run and the sell run each come from `old` while `old`
+    holds `now` in it. The rest is `new`. A safety or peak rule can still stop
+    a run at any tick; that is not decided here."""
+    if old is None or not old.on:
+        return new
+    cheap = old.cheap if old.cheap and old.cheap.holds(now) else new.cheap
+    sell = old.sell if old.sell and old.sell.holds(now) else new.sell
+    g_old = old.give_at(now)
+    give = new.give
+    if g_old is not None:
+        give = (g_old,) + tuple(g for g in new.give
+                                if g.start >= g_old.end)
+    if cheap is new.cheap and sell is new.sell and g_old is None:
+        return new
+    worth = old.charge_worth if cheap is old.cheap else new.charge_worth
+    return RunPlan(cheap, give, sell, new.level_eur_kwh if new.on
+                   else old.level_eur_kwh, None if give else new.reason,
+                   worth)

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
@@ -130,11 +131,16 @@ class SaveRefused(Exception):
     own sentences, byte for byte; `changed` names the keys that moved.
     """
 
-    def __init__(self, kind, problems=(), changed=(), stored=None):
+    def __init__(self, kind, problems=(), changed=(), stored=None,
+                 moved=None):
         self.kind = kind
         self.problems = list(problems)
         self.changed = list(changed)
         self.stored = stored
+        # UX-13 P4: the keys the OTHER surface changed - stored-on-open
+        # against stored-now - when the caller knows what it opened. None
+        # when it does not. `changed` also holds the operator's own edits.
+        self.moved = None if moved is None else list(moved)
         super().__init__(f"save refused ({kind})")
 
 
@@ -287,7 +293,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 +308,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 +336,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 +354,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
@@ -355,7 +364,7 @@ async def problems_and_ranges(opts: dict, hass=None):
 
 
 async def save(selfcfg: SelfConfig, proposed: dict, expect: str, *,
-               hass=None) -> dict:
+               hass=None, base=None) -> dict:
     """Validate, compare-and-swap, then write. Refuse rather than half-do.
 
     Returns `{"fingerprint": <the new one>}` on success. Raises `SaveRefused`
@@ -378,11 +387,17 @@ async def save(selfcfg: SelfConfig, proposed: dict, expect: str, *,
     genuinely wants what the other surface wrote replaced, the page reloads,
     shows them what changed, and they save again from THAT - which is a
     decision made in front of the difference rather than through it.
+
+    `base`, when given, is the blob the page opened (the one `expect` is the
+    fingerprint of). A stale refusal then also names the keys that moved
+    underneath it, so the page does not list the operator's own edits among
+    the settings "changed elsewhere" (UX-13 P2 test, finding a).
     """
     problems = await problems_for(proposed, hass)
     if problems:
-        _LOG.warning("panel REFUSED to save: %d configuration problem(s); "
-                     "nothing written. 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()
@@ -390,10 +405,15 @@ async def save(selfcfg: SelfConfig, proposed: dict, expect: str, *,
     actual = fingerprint(stored)
     if actual != expect:
         changed = changed_keys(stored, proposed)
-        _LOG.warning("panel REFUSED to save: the stored options changed "
-                     "underneath this page (keys: %s); nothing written",
-                     ", ".join(changed) or "none this page also edited")
-        raise SaveRefused("stale", changed=changed, stored=stored)
+        moved = (changed_keys(base, stored)
+                 if isinstance(base, dict) and fingerprint(base) == expect
+                 else None)
+        keys = changed if moved is None else moved
+        _LOG.warning("The settings page did not save, because the settings "
+                     "changed while it was open (keys: %s).",
+                     ", ".join(keys) or "none this page also edited")
+        raise SaveRefused("stale", changed=changed, stored=stored,
+                          moved=moved)
 
     await selfcfg.write_options(proposed)
     _LOG.info("options saved from the ingress panel; a restart is needed "

goodwe_controller/app/setuponly.py

@@ -0,0 +1,90 @@
+"""UX-15: setup-only mode. A new install serves the setup wizard and commands
+nothing. The rule and the argument are in DECISIONS/UX-15-setup-only-mode.md.
+
+`applies()` says when: the startup gate's only refusal is that no inverter is
+named. `serve()` then runs the ingress page on a `SetupOnly` stand-in for the
+controller. Nothing that can command is built: no Controller, no inverter, no
+MQTT, no meter task. Its HomeAssistant is read-only, so a service call refuses
+before anything is sent (hass.py), and `/action` refuses too (web.py).
+"""
+
+import asyncio
+import contextlib
+import logging
+import signal
+from datetime import datetime, timezone
+
+from . import messages, web
+from .inverter import roster_entries
+from .validate import actuator_writers, no_power_request_problem
+
+_LOG = logging.getLogger("goodwe.setup")
+
+
+def applies(opts: dict, problems) -> bool:
+    """True when the options name no inverter at all and that is the gate's
+    only refusal. Anything else refused keeps the exit 78 (CFG-01)."""
+    return (not actuator_writers(opts) and not roster_entries(opts)
+            and list(problems) == [no_power_request_problem()])
+
+
+class SetupOnly:
+    """What web.build_app() needs from a controller, and nothing that writes.
+
+    It holds no inverter and no publisher. `hass` must be read-only."""
+
+    setup_only = True
+    auto = False            # control is never started here
+    grid = None             # no meter is read here
+    inverters = ()
+
+    def __init__(self, opts: dict, hass, store):
+        if getattr(hass, "read_only", False) is not True:
+            raise ValueError("setup-only mode needs a read-only HomeAssistant")
+        self.o, self.hass, self.store = opts, hass, store
+        self.events: list[str] = []
+        self.hint = ""
+
+    def log_event(self, msg: str, hint: str | None = None) -> None:
+        stamp = datetime.now(timezone.utc).strftime("%H:%M:%S")
+        self.events.insert(0, f"{stamp} {msg}")
+        del self.events[40:]
+        if hint is not None:
+            self.hint = f"{datetime.now().astimezone():%H:%M} {hint}"
+
+    def status_payload(self, lang: str = "en") -> dict:
+        return {"setup_only": True, "mode": "setup_only",
+                "banner": messages.banner_setup_only(), "level": "warn",
+                "rows": [["Control", "not started, in setup"]],
+                "checks": [{"ok": False, "warn": True,
+                            "text": messages.row_setup_only()}],
+                "hint": self.hint, "events": list(self.events)}
+
+    async def handle_action(self, what):
+        # web.py answers 409 before it gets here. Nothing is done either way.
+        _LOG.warning("The page asked for an action in setup, so nothing "
+                     "was done.")
+        return None
+
+    async def shutdown(self) -> None:
+        """Nothing to wind down: nothing was ever commanded."""
+
+
+async def serve(opts: dict, hass, store, *, port: int) -> None:
+    """Serve the page in setup-only mode until the Supervisor stops us."""
+    controller = SetupOnly(opts, hass, store)
+    _LOG.warning("No inverter is named yet, so the add-on is in setup and "
+                 "controls nothing. Open its page to finish setup.")
+    controller.log_event("setup-only mode: no inverter named, nothing is "
+                         "commanded", hint=messages.hint("setup_only"))
+    runner = await web.start(controller, port=port)
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        with contextlib.suppress(NotImplementedError):
+            loop.add_signal_handler(sig, stop.set)
+    try:
+        await stop.wait()
+    finally:
+        await runner.cleanup()
+        _LOG.info("stopped")

goodwe_controller/app/shadow.py

@@ -279,6 +279,8 @@ that write is issued rather than skipped as unchanged.
 """
 from __future__ import annotations
 
+from . import messages
+
 # ⚠️ CFG-03's mirror. `test_defaults_pin.py` part 2 discovers every
 # module-level name ending in OPTION_DEFAULTS and asserts each value
 # reproduces config.yaml EXACTLY, so this table cannot drift from the shipped
@@ -316,11 +318,8 @@ WIRE_W = 0.0
 #: a cap that does not bind - and a number invented for the row would be a
 #: second helping of the defect this constant exists to disclose.
 SIZED_FROM_METER = (
-    "⚠️ AND ITS SIZE CAME FROM THE BILLED-QUARTER METER, WHICH HAS ONLY THE "
-    "HOUSE IN IT WHILE THE BATTERY IS HELD AT 0 W. A live run sizes the same "
-    "trade against a meter the battery is moving, so this is an UPPER BOUND "
-    "and not a prediction; how far under it a live run lands is a closed-loop "
-    "question and a shadow run cannot answer it")
+    "This is an upper limit, not a forecast, because the meter did not see "
+    "the battery move.")
 
 
 def mode(opts: dict) -> str:
@@ -371,18 +370,18 @@ def why(opts: dict, *, control_started: bool) -> str:
     # discount. What is true in every live state is that what this add-on
     # decides reaches the inverter; whether control is RUNNING is the
     # `Stopped` banner's question and it is answered there.
+    # UX-08: the same four rungs, in plain words. The setting is named by its
+    # value, "automatic" for `auto`, so each rung still reads differently.
     m = mode(opts)
+    live = "what the add-on decides reaches the inverters"
+    inert = "the add-on decides but sends nothing"
     if m == "off":
-        return ("off (shadow_mode: off) - NOT in shadow mode: what this "
-                "add-on decides DOES reach the inverter")
+        return f"Off, {live}"
     if m == "on":
-        return ("on (shadow_mode: on) - decisions are recorded and nothing "
-                "is commanded")
+        return f"On, {inert}"
     if control_started:
-        return ("off (shadow_mode: auto, control is started) - NOT in shadow "
-                "mode: what this add-on decides DOES reach the inverter")
-    return ("on (shadow_mode: auto, control is stopped) - decisions are "
-            "recorded and nothing is commanded")
+        return f"Off (automatic, control is started), {live}"
+    return f"On (automatic, control is stopped), {inert}"
 
 
 def words(opts: dict, *, control_started: bool, would_w: float | None,
@@ -409,10 +408,10 @@ def words(opts: dict, *, control_started: bool, would_w: float | None,
     that decided it did not apply, which is the shape of defect this card is
     about. TEST-14's rule with a new name on it.
 
-    ⚠️ AND THE PHRASE IS "ON THIS CYCLE", UNCONDITIONALLY, NOT ONLY WHEN THE
+    ⚠️ AND THE PHRASE IS "THIS CYCLE", UNCONDITIONALLY, NOT ONLY WHEN THE
     CAVEAT FIRES. Every number a shadow run records was reached from a plant
-    that did not respond; "WOULD HAVE COMMANDED -2 000 W" reads as a forecast
-    of a live run and no number here is one. The ⚠️ below is the STRONGER,
+    that did not respond; "would ask for -2 000 W" alone reads as a forecast
+    of a live run and no number here is one. UX-08 2d put it in plain words. The ⚠️ below is the STRONGER,
     conditional statement about the cycles where the answer can be multiples
     out - see this module's header for the measured table.
 
@@ -429,19 +428,19 @@ def words(opts: dict, *, control_started: bool, would_w: float | None,
     if not engaged(opts, control_started=control_started):
         return head
     if would_w is None:
-        return (f"{head}; no decision has been reached yet - the inverter is "
-                f"held at {WIRE_W:.0f} W")
+        return (f"{head}. No decision yet, the inverters stay at "
+                f"{WIRE_W:.0f} W.")
     # ⚠️ THE THOUSANDS SEPARATOR IS SWAPPED ON THE NUMBER ALONE. Applied to
     # the whole sentence it ate the comma out of `head` - and `head` is the
     # half that says WHICH RUNG decided, which is the claim MUTATION.md's
     # masking rule says must survive.
     num = f"{float(would_w):+,.0f}".replace(",", " ")
-    out = (f"{head}; ON THIS CYCLE WOULD HAVE COMMANDED {num} W, inverter "
-           f"held at {WIRE_W:.0f} W")
+    out = (f"{head}. This cycle it would ask for {num} W, the inverters stay "
+           f"at {WIRE_W:.0f} W.")
     if sized_from_meter:
         out += f" {SIZED_FROM_METER}"
     if reason:
-        out += f" - {reason}"
+        out += f" Why: {reason}."
     return out
 
 
@@ -471,25 +470,17 @@ def log_line(*, would_w: float, reason: str, sized_from_meter: bool) -> str:
 def banner(opts: dict, *, control_started: bool, latched: tuple = ()) -> tuple:
     """`(level, text)` for the top of the status page, or `None` when live.
 
-    ⚠️ IT NAMES A STANDING LATCH AND GOES RED FOR ONE. The shadow banner sits
-    ABOVE every other branch of the cascade, because "the battery is not being
-    controlled" is the one sentence that may never be displaced - but a
-    failsafe latch that is up while the controller is inert is up when it
-    stops being inert, and an operator who turns shadow mode off without
-    clearing it gets a battery that will not move and a green page that
-    never mentioned why. So the latch is carried INTO the shadow banner
-    rather than losing its own.
+    ⚠️ IT GOES RED FOR A STANDING LATCH. The shadow banner sits ABOVE every
+    other branch of the cascade, because "the battery is not controlled" is
+    the one sentence that may never be displaced - but a failsafe latch that
+    is up while the controller is inert is up when it stops being inert. So the
+    banner says a safety stop outlasts shadow mode, and each latch keeps its
+    own red row below, which names it and says how it clears. The words are
+    `messages.banner_shadow()`'s (UX-09); `latched` names them for callers.
     """
     if not engaged(opts, control_started=control_started):
         return None
-    text = ("SHADOW MODE - the battery is NOT being controlled. Every "
-            f"inverter is held at {WIRE_W:.0f} W and nothing this add-on "
-            "decides reaches the inverter.")
-    if latched:
-        return ("bad", text + " ⚠️ A FAILSAFE LATCH IS STILL UP ("
-                + ", ".join(latched) + ") and it will still be up when shadow "
-                "mode is turned off.")
-    return ("warn", text)
+    return ("bad" if latched else "warn", messages.banner_shadow(bool(latched)))
 
 
 def problems(opts: dict) -> list:
@@ -510,9 +501,6 @@ def problems(opts: dict) -> list:
     text = str("" if raw is None else raw).strip().lower()
     if text in MODES:
         return []
-    return [f"shadow_mode is {raw!r}, which is not one of "
-            + ", ".join(f"'{m}'" for m in MODES)
-            + ". 'auto' leaves the battery alone while control is stopped and "
-              "commands it once control is started; 'on' records every "
-              "decision and commands nothing at all; 'off' is ordinary "
-              "control."]
+    return [f"{messages.setting('shadow_mode')} is {messages.shown(raw)}. Choose "
+            + ", ".join(f"'{m}'" for m in MODES[:-1])
+            + f" or '{MODES[-1]}'."]

goodwe_controller/app/solarfc.py

@@ -0,0 +1,254 @@
+"""OPT-11 P4: the solar forecast, read from a Home Assistant sensor.
+
+Pure: HA state dicts and the time in, a `Forecast` (or None and why) out.
+main.py reads the entities; dayplan.py uses the answer. FCST-01 replaces
+this later with the add-on's own forecast (owner answer, 2026-09-27).
+
+Two options name the sensors: `pv_forecast_entity`, the solar energy still
+to come TODAY, and `pv_forecast_tomorrow_entity`, TOMORROW's (optional; it
+is only needed for a cheap run before midnight). Supported, by the entities
+they create (DOCS.md lists them):
+
+* Forecast.Solar (HA core): `sensor.energy_production_today_remaining` and
+  `sensor.energy_production_tomorrow`. The state only; no hourly split.
+* Solcast PV Forecast (HACS `solcast_solar`):
+  `sensor.solcast_pv_forecast_forecast_remaining_today` and
+  `..._forecast_tomorrow`, with `detailedForecast` (or `detailedHourly`):
+  `[{period_start, pv_estimate}]`, kW per period.
+* Open-Meteo Solar Forecast (HACS `open_meteo_solar_forecast`):
+  `sensor.energy_production_today_remaining` / `..._tomorrow`, with
+  `wh_period`: `{period start: Wh}`.
+
+Any other sensor whose state is energy in Wh, kWh or MWh works too, as a
+state only. The unit is read, never guessed (the rule `pv.watts()` has).
+Without an hourly split, the day's energy is spread over a fixed bell from
+06:00 to 20:00 local time (`BELL_FROM_H`, `BELL_TO_H`).
+
+A reading older than `FRESH_S`, or from before local midnight, is stale,
+and a stale or missing forecast is no forecast: the day plan is off and
+every mode acts as in P3 option A.
+"""
+
+import math
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from .hass import BAD_STATES
+from .tariff import BILLING_TZ
+
+KWH_PER = {"Wh": 0.001, "kWh": 1.0, "MWh": 1000.0}
+
+# Stale after 3 h. The integrations above refresh at least hourly, so a
+# 2 h limit would flag a site whose hourly poll was missed once.
+FRESH_S = 3 * 3600.0
+
+# The bell a state-only forecast is spread over, in local hours.
+BELL_FROM_H, BELL_TO_H = 6.0, 20.0
+
+# Why there is no forecast (the page words are in ui_text `home_words`).
+NOT_SET, MISSING, UNIT, STALE, BAD = (
+    "not_set", "missing", "unit", "stale", "bad")
+
+
+@dataclass(frozen=True)
+class Day:
+    """One day's forecast: `kwh` still to come (today) or in all (tomorrow),
+    and the hourly split if the sensor has one: `((start, end, kwh), ...)`."""
+    day0: datetime              # local midnight, as UTC
+    kwh: float
+    periods: tuple = ()
+
+
+@dataclass(frozen=True)
+class Forecast:
+    today: Day
+    tomorrow: Day | None
+    at: datetime                # when the sensor last reported
+
+    def between(self, t0: datetime, t1: datetime) -> float | None:
+        """kWh the sun should give between `t0` (now or later) and `t1`.
+        None when the span reaches the sunny hours of a day with no
+        forecast (tomorrow, when its sensor is not set)."""
+        if t1 <= t0:
+            return 0.0
+        last = self.tomorrow or self.today
+        if t1 > last.day0 + timedelta(days=1, hours=BELL_FROM_H):
+            return None
+        total = 0.0
+        for day in (self.today, self.tomorrow):
+            if day is None:
+                continue
+            a = max(t0, day.day0)
+            b = min(t1, day.day0 + timedelta(days=1))
+            if b > a:
+                total += _day_between(day, a, b, t0)
+        return total
+
+
+def _local_hour(t: datetime) -> float:
+    lt = t.astimezone(BILLING_TZ)
+    return lt.hour + lt.minute / 60.0 + lt.second / 3600.0
+
+
+def _bell(h: float) -> float:
+    """Cumulative share of a day's sun by local hour `h` (0..1)."""
+    if h <= BELL_FROM_H:
+        return 0.0
+    if h >= BELL_TO_H:
+        return 1.0
+    x = (h - BELL_FROM_H) / (BELL_TO_H - BELL_FROM_H)
+    return (1.0 - math.cos(math.pi * x)) / 2.0
+
+
+def _hours_since(day0, t):
+    return (t - day0).total_seconds() / 3600.0
+
+
+def _day_between(day: Day, a: datetime, b: datetime, now: datetime) -> float:
+    if day.periods:
+        out = 0.0
+        for s, e, kwh in day.periods:
+            lo, hi = max(a, s), min(b, e)
+            if hi > lo:
+                out += kwh * (hi - lo).total_seconds() / (e - s).total_seconds()
+        return out
+    # State only: `kwh` is what is left from `max(now, day0)` to the day's
+    # end, spread over the bell.
+    h_from = _hours_since(day.day0, max(now, day.day0))
+    left = 1.0 - _bell(h_from)
+    if left <= 1e-9:
+        return 0.0
+    share = (_bell(_hours_since(day.day0, b))
+             - _bell(_hours_since(day.day0, a))) / left
+    return day.kwh * max(0.0, share)
+
+
+def _parse_time(v):
+    try:
+        t = datetime.fromisoformat(str(v).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        return None
+    return t if t.tzinfo else t.replace(tzinfo=timezone.utc)
+
+
+def _periods(attrs: dict, day0: datetime) -> tuple:
+    """The hourly split, if the sensor has one, for the day at `day0`."""
+    d1 = day0 + timedelta(days=1)
+    out = []
+    for key in ("detailedForecast", "detailedHourly"):
+        rows = attrs.get(key)
+        if isinstance(rows, list) and rows:
+            starts = []
+            for r in rows:
+                if not isinstance(r, dict):
+                    continue
+                t = _parse_time(r.get("period_start"))
+                try:
+                    kw = float(r.get("pv_estimate"))
+                except (TypeError, ValueError):
+                    continue
+                if t is not None and math.isfinite(kw) and kw >= 0:
+                    starts.append((t, kw))
+            starts.sort()
+            for i, (t, kw) in enumerate(starts):
+                step = (starts[i + 1][0] - t if i + 1 < len(starts)
+                        else timedelta(minutes=30 if key ==
+                                       "detailedForecast" else 60))
+                if step <= timedelta(0) or step > timedelta(hours=1):
+                    step = timedelta(minutes=30 if key == "detailedForecast"
+                                     else 60)
+                if day0 <= t < d1:
+                    out.append((t, t + step,
+                                kw * step.total_seconds() / 3600.0))
+            if out:
+                return tuple(out)
+    wh = attrs.get("wh_period")
+    if isinstance(wh, dict) and wh:
+        rows = []
+        for k, v in wh.items():
+            t = _parse_time(k)
+            try:
+                e = float(v)
+            except (TypeError, ValueError):
+                continue
+            if t is not None and math.isfinite(e) and e >= 0:
+                rows.append((t, e / 1000.0))
+        rows.sort()
+        for i, (t, kwh) in enumerate(rows):
+            nxt = rows[i + 1][0] if i + 1 < len(rows) else t + timedelta(
+                hours=1)
+            if nxt - t > timedelta(hours=1) or nxt <= t:
+                nxt = t + timedelta(hours=1)
+            if day0 <= t < d1:
+                out.append((t, nxt, kwh))
+    return tuple(out)
+
+
+def _day(state, day0, now, *, today):
+    """`(Day, None)` or `(None, why)` from one sensor's state dict."""
+    if state is None:
+        return None, MISSING
+    raw = str(state.get("state", "")).strip()
+    if raw.lower() in BAD_STATES:
+        return None, MISSING
+    try:
+        v = float(raw)
+    except ValueError:
+        return None, BAD
+    attrs = state.get("attributes") or {}
+    unit = str(attrs.get("unit_of_measurement") or "").strip()
+    if unit not in KWH_PER:
+        return None, UNIT
+    kwh = v * KWH_PER[unit]
+    if not math.isfinite(kwh) or kwh < 0:
+        return None, BAD
+    periods = _periods(attrs, day0)
+    if periods and today:
+        # The split is the whole day; keep what is still to come, scaled so
+        # it adds up to the state (the state is what the integration says
+        # is left).
+        left = sum(k * max(0.0, min(1.0, (e - max(s, now)).total_seconds()
+                                    / (e - s).total_seconds()))
+                   for s, e, k in periods)
+        if left > 1e-6:
+            f = kwh / left
+            periods = tuple((s, e, k * f) for s, e, k in periods)
+    return Day(day0, kwh, periods), None
+
+
+def _reported(state):
+    ts = [_parse_time(state.get(k)) for k in
+          ("last_reported", "last_updated", "last_changed")]
+    ts = [t for t in ts if t is not None]
+    return max(ts) if ts else None
+
+
+def read(today_state, tomorrow_state, now: datetime, *,
+         configured=True):
+    """`(Forecast, None)` or `(None, why)`. `tomorrow_state` may be None
+    (the option is not set, or the sensor is missing): the forecast then
+    covers today only."""
+    if not configured:
+        return None, NOT_SET
+    here = now.astimezone(BILLING_TZ)
+    d0 = datetime(here.year, here.month, here.day, tzinfo=BILLING_TZ)
+    nd = d0.date() + timedelta(days=1)
+    d1 = datetime(nd.year, nd.month, nd.day, tzinfo=BILLING_TZ)
+    day0, day1 = d0.astimezone(timezone.utc), d1.astimezone(timezone.utc)
+    today, why = _day(today_state, day0, now, today=True)
+    if today is None:
+        return None, why
+    at = _reported(today_state)
+    # A reading from before local midnight is yesterday's "left today" (0
+    # after sunset) until the integration refreshes: stale, not a dark day.
+    if at is None or at < day0 or (now - at).total_seconds() > FRESH_S \
+            or (at - now).total_seconds() > 300:
+        return None, STALE
+    tomorrow = None
+    if tomorrow_state is not None:
+        t, _w = _day(tomorrow_state, day1, now, today=False)
+        t_at = _reported(tomorrow_state)
+        if t is not None and t_at is not None and t_at >= day0 \
+                and (now - t_at).total_seconds() <= FRESH_S:
+            tomorrow = t
+    return Forecast(today, tomorrow, at), None

goodwe_controller/app/static/app.css

@@ -0,0 +1,246 @@
+/* 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}
+.plist .prow{display:grid;gap:6px}
+.plist .pf{display:flex;flex-direction:column;gap:2px}
+.plist .pf>select.sel{width:100%}
+input.txt.time{width:5.5em;text-align:center;font-variant-numeric:tabular-nums}
+.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}
+/* UX-13 P4: the setup wizard */
+.steps{display:flex;gap:4px;margin:4px 0 12px}
+.steps i{flex:1;height:6px;border-radius:3px;background:var(--track)}
+.steps i.done{background:var(--accent)} .steps i.cur{background:var(--accent);opacity:.55}
+.msg.ok{background:var(--ok-bg);color:var(--ok)}
+.sev.bad{background:var(--bad-bg);color:var(--bad)} .sev.warn{background:var(--warn-bg);color:var(--warn)}
+.checklist li{display:flex;gap:8px;align-items:flex-start;overflow-wrap:anywhere}
+.kettle .row{margin-top:8px}
+/* UX-13 P3: the Batteries screen and the Simple settings view */
+.bcard .hd{display:flex;align-items:center;gap:10px;margin-bottom:10px}
+.bcard .name{font-weight:700;font-size:16px}
+.bcard .modebox .lbl{display:block;margin-bottom:4px}
+.bcard .modebox .help{font-size:13px;color:var(--muted);margin-top:4px}
+.bcard.off .modebox{opacity:.6}
+.bcard .kv dd{overflow-wrap:anywhere}
+.switch:disabled{opacity:.45;cursor:not-allowed}
+select.sel:disabled{opacity:.6}
+.simple .card>.row{margin-bottom:4px}
+.vhide{display:none!important}
+.simple .card>.f{border-top:0;padding-top:0}
+.simple .f>.head{display:flex;justify-content:space-between;align-items:center;gap:8px;flex-wrap:wrap}
+.simple .card .lbl{font-weight:600;font-size:15px}
+.simple .inv .hd{border-bottom:0}
+.simple .inv .f{border-top:0;padding-top:0}

goodwe_controller/app/static/app.js

@@ -0,0 +1,490 @@
+"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 () {
+  // P5: English or Dutch, by the browser's language. A word missing in Dutch
+  // falls back to English, key by key (app/uitext.py does the same).
+  const ALL = JSON.parse(document.getElementById("ui-text").textContent);
+  const LANG = /^nl\b/i.test(navigator.language || "") ? "nl" : "en";
+  const merge = (a, b) => {
+    if (!b || typeof a !== "object" || typeof b !== "object" || Array.isArray(a)) return b ?? a;
+    const out = Object.assign({}, a);
+    for (const k in b) out[k] = k in a ? merge(a[k], b[k]) : b[k];
+    return out;
+  };
+  const WORDS = LANG === "en" ? ALL.en : merge(ALL.en, ALL[LANG]);
+  document.documentElement.lang = LANG;
+  const T = WORDS.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 dec = (x) => (LANG === "nl" ? x.replace(".", ",") : x);
+  const kw = (w) => dec((Math.abs(Number(w)) / 1000).toFixed(1));
+  const eur = (v) => "€" + dec(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?lang=" + LANG, { 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();
+  }
+  // `force`: redraw the battery cards even under a focused mode list, after
+  // the person used it (P3).
+  async function refresh(force) {
+    if (busy) return;
+    busy = true;
+    try { S = await getStatus(); render(force === true); }
+    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.setup_only === true ? t("setup_only.name") : S.banner;
+    $("#pill").replaceChildren(h("span", { class: "dot" + dot, "aria-hidden": "true" }), h("span", {}, words));
+  }
+
+  function render(force) {
+    renderPill();
+    const structured = S.now && S.plan && !S.home_error;
+    // UX-15: setup-only mode commands nothing and has no control to offer.
+    const setup = S.setup_only === true;
+    banner($("#home-banner"), S.level, setup ? t("setup_only.name") : S.banner, structured ? S.state.sub : setup ? t("setup_only.description") : "", 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, setup);
+    renderDetails(!structured && !setup);
+    renderBatteries(force);
+    document.dispatchEvent(new CustomEvent("ux13:status"));
+  }
+
+  /* ---------------- 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, setup) {
+    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" : "");
+    btn.hidden = !!setup;
+    $("#btn-setup").hidden = !setup;
+    $("#c-ctl .more").hidden = !!setup;
+    $("#ctl-text").textContent = structured ? S.control.text : setup ? t("setup_only.control") : "";
+    $("#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 (UX-13 P3) ---------------- */
+  // One card per battery. With battery modes on (`mode_key` in /status) each
+  // card has an On/Off switch and a mode list, sent as `pack_use` and
+  // `pack_mode` through /action (OPT-11 P1). Selling has no switch while it
+  // is off (owner decision 2026-09-29). The Now, Today and Why lines are
+  // homeview.py's sentences. The Simple settings view draws the same switch
+  // and list into its own card (simpleHost).
+  const MODES = ["solar_first", "leftover_solar", "cheap_hours"];
+  const say = (text, vars) => Object.keys(vars).reduce((x, k) => x.replace("{" + k + "}", vars[k]), text);
+  let packBusy = false;
+  let simpleHost = null;
+  async function packAct(what, b, value) {
+    if (packBusy) return;
+    packBusy = true;
+    try {
+      const r = await fetch("action", { method: "POST", headers: { "Content-Type": "application/json" },
+                                        body: JSON.stringify({ action: what, unit: b.name, value: value }) });
+      const j = await r.json().catch(() => ({}));
+      if (!r.ok) toast(j.error || t("toast.failed"));
+      else if (what === "pack_use") toast(say(value ? t("batteries.toast.on") : t("batteries.toast.off"), { name: b.name }));
+      else toast(say(t("batteries.toast.mode"), { name: b.name, mode: t("batteries.choice." + value + ".name") }));
+    } catch (e) { toast(t("toast.failed")); }
+    finally { packBusy = false; }
+    await refresh(true);
+  }
+  function onSwitch(b, i, where, lid) {
+    const sw = h("button", { type: "button", class: "switch", role: "switch", id: "bsw-" + where + i,
+                             "aria-checked": String(b.use), "aria-labelledby": lid,
+                             onclick: () => packAct("pack_use", b, !b.use) });
+    return h("span", { class: "swrap" }, sw, h("span", { class: "swtext", "aria-hidden": "true" }, b.use ? t("batteries.on") : t("batteries.off")));
+  }
+  function modeSelect(b, i, where, lid) {
+    return h("select", { class: "sel", id: "bsel-" + where + i, "aria-labelledby": lid, disabled: !b.use,
+                         onchange: (e) => packAct("pack_mode", b, e.target.value) },
+      ...MODES.map((k) => h("option", { value: k, selected: b.mode_choice === k }, t("batteries.choice." + k + ".name"))));
+  }
+  function todayLines(b) {
+    if (!b.today || !b.today.length) return b.today_line || "–";
+    return b.today.map((r) => h("div", {}, r.from + " " + t("plan.time_to") + " " + r.to + ": " + r.what));
+  }
+  function batteryCard(b, i) {
+    const modes = b.mode_key != null;
+    const lid = "bname-" + i;
+    const lvl = b.level_pct == null ? "–" : Math.round(b.level_pct) + " %";
+    const stored = b.stored_kwh != null ? " · " + dec(b.stored_kwh.toFixed(1)) + " kWh " + t("batteries.stored").toLowerCase() : "";
+    return h("div", { class: "card bcard" + (modes && !b.use ? " off" : "") },
+      h("div", { class: "hd" },
+        h("div", { class: "grow" }, h("div", { class: "name", id: lid }, b.name),
+          h("div", { class: "tiny muted" }, b.capacity_kwh ? dec(Number(b.capacity_kwh).toFixed(1)) + " kWh" : "")),
+        modes ? onSwitch(b, i, "c", lid) : null),
+      modes ? h("div", { class: "modebox" },
+        h("label", { class: "lbl small", for: "bsel-c" + i }, t("batteries.mode")),
+        modeSelect(b, i, "c", null),
+        h("div", { class: "help" }, t("batteries.choice." + b.mode_key + ".description"))) : null,
+      levelBar(b.level_pct, b.name),
+      h("dl", { class: "kv" },
+        h("dt", {}, t("batteries.level")), h("dd", {}, lvl + stored),
+        h("dt", {}, t("batteries.now")), h("dd", {}, b.now),
+        h("dt", {}, t("batteries.today")), h("dd", {}, todayLines(b)),
+        h("dt", {}, t("batteries.why")), h("dd", { class: "muted" }, b.why || "–")));
+  }
+  function simpleRow(b, i) {
+    const lid = "bsname-" + i;
+    return h("div", { class: "inv" },
+      h("div", { class: "hd" }, h("span", { class: "grow", id: lid }, b.name), onSwitch(b, i, "s", lid)),
+      h("div", { class: "f" }, h("label", { class: "lbl", for: "bsel-s" + i }, t("batteries.mode")),
+        h("div", { class: "ctl" }, modeSelect(b, i, "s", null)),
+        h("div", { class: "help" }, b.now + " " + (b.why || ""))));
+  }
+  // Rebuild without losing the focused control, and never under an open list
+  // or a request in flight.
+  function keepFocus(fn) {
+    const id = document.activeElement && document.activeElement.id;
+    fn();
+    if (id && /^bs(w|el)-/.test(id)) { const e = document.getElementById(id); if (e) e.focus(); }
+  }
+  // The modes-off card's button opens Settings on the Installer view, where
+  // the "Battery modes" switch is (settings.js sets window.UX13.settingsView).
+  $("#batt-off a").addEventListener("click", () => { if (window.UX13.settingsView) window.UX13.settingsView("installer"); });
+  function renderBatteries(force) {
+    if (!S || !S.batteries) { $("#bcards").replaceChildren(); return; }
+    const a = document.activeElement;
+    if (!force && (packBusy || (a && a.tagName === "SELECT" && /^bsel-/.test(a.id)))) return;
+    const modes = S.modes_on === true || S.batteries.some((b) => b.mode_key != null);
+    $("#batt-off").hidden = modes;
+    $("#batt-how").hidden = !modes;
+    const docs = $("#batt-docs");
+    if (S.control && S.control.docs_url) { docs.href = S.control.docs_url; docs.hidden = false; } else docs.hidden = true;
+    if (S.state && ["shadow", "stopped", "alarm"].includes(S.state.kind)) banner($("#batt-banner"), S.level, S.state.pill, S.state.sub, S.level === "bad" ? "alert" : null);
+    else $("#batt-banner").replaceChildren();
+    keepFocus(() => {
+      $("#bcards").replaceChildren(...S.batteries.map(batteryCard));
+      // OPT-11 P4: the solar forecast line under the cards.
+      const sl = $("#batt-solar"), line = modes && S.solar ? S.solar.line : "";
+      if (sl) { sl.textContent = line || ""; sl.hidden = !line; }
+      if (simpleHost && simpleHost.isConnected) {
+        simpleHost.replaceChildren(...(modes ? S.batteries.map(simpleRow)
+          : [h("p", { class: "small muted", style: "margin:4px 0" }, t("batteries.modes_off.name") + ". " + t("batteries.description"))]));
+      }
+    });
+  }
+
+  /* ---------------- 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.
+  // `first`: the page opened with no route, so settings.js may open the setup
+  // wizard on a new install (UX-13 P4).
+  window.UX13 = { h, ask, toast, t, words: WORDS, lang: LANG, maint: (what) => ask(what, () => simple(what)), first: !location.hash,
+                  // P3: the Simple settings view's battery card, drawn from /status.
+                  batteries: (host) => { simpleHost = host; if (S) renderBatteries(); refresh(); },
+                  status: () => S, kw };
+
+  /* ---------------- 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,176 @@
+<!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="btn primary" id="btn-setup" href="#setup" hidden data-t="setup_only.open"></a>
+      <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="batt-banner"></div>
+  <div class="card" id="batt-off" hidden>
+    <h2 data-t="batteries.modes_off.name"></h2>
+    <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>
+  <div id="bcards"></div>
+  <p class="small muted" id="batt-solar" hidden></p>
+  <details class="grp" id="batt-how" hidden>
+    <summary><span class="grow"><strong data-t="batteries.how.name"></strong><span class="small muted gdesc" data-t="batteries.how.description"></span></span><span class="chev" aria-hidden="true">&#8250;</span></summary>
+    <div class="body small">
+      <p data-t="batteries.how.solar_first.description"></p>
+      <p data-t="batteries.how.leftover_solar.description"></p>
+      <p data-t="batteries.how.off.description"></p>
+      <p class="muted" data-t="batteries.how.rules.description"></p>
+      <p><a id="batt-docs" hidden target="_top" rel="noopener" data-t="control.docs"></a></p>
+    </div>
+  </details>
+</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>
+  <div class="row" style="margin-bottom:8px">
+    <div class="seg" role="radiogroup" id="set-view" data-s-label="view.name">
+      <button type="button" role="radio" aria-checked="true" data-v="simple" data-s="view.simple"></button>
+      <button type="button" role="radio" aria-checked="false" data-v="installer" tabindex="-1" data-s="view.installer"></button>
+    </div>
+    <span class="tiny muted grow" id="set-desc"></span>
+  </div>
+  <div id="set-banner" aria-live="polite"></div>
+  <div id="simple" class="simple" hidden></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" id="wz">
+    <div class="row spread"><h2 id="wz-title" style="margin:0" data-s="setup.name"></h2><span class="tiny muted" id="wz-count"></span></div>
+    <div class="steps" id="wz-steps" aria-hidden="true"></div>
+    <p class="small muted" id="wz-desc" style="margin:0 0 6px"></p>
+    <div id="wz-banner" aria-live="polite"></div>
+    <div id="wz-body"><p class="small muted" data-s="loading"></p></div>
+    <div class="row spread" id="wz-nav" style="margin-top:14px">
+      <button class="btn" id="wz-back" type="button" data-s="setup.back"></button>
+      <button class="btn primary" id="wz-next" type="button" data-s="setup.next"></button>
+    </div>
+  </div>
+  <p class="tiny muted" data-s="setup.description"></p>
+</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,941 @@
+"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.
+   P4: the Setup tab's wizard is the same page model, drawn one step at a
+   time from each field's `wizard` step, and saved through the same routes. */
+(function () {
+  const ROOT = window.UX13.words;       // English or Dutch (app.js)
+  const W = ROOT.settings;
+  const { h, ask, toast, maint, lang } = 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 view = null;           // "settings" or "setup": the tab drawing V
+  let STEPS = {};            // wizard step -> refusals that block it
+  // P3: "simple" (the default, for home owners) or "installer". Remembered in
+  // this browser only; a blocked storage just means Simple each time.
+  let mode = "simple";
+  try { if (localStorage.getItem("ux13.settings.view") === "installer") mode = "installer"; } catch (e) { /* no storage */ }
+  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) redrawView(); 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;
+  }
+  // P5: time windows, each a start, an end, its days and a price. The add-on
+  // builds the tariff from the rows and names the first overlap or gap.
+  function periodList(f, card) {
+    const P = W.periods;
+    const arr = () => (Array.isArray(get(f, card)) ? get(f, card) : []);
+    const box = h("div", { class: "elist plist" });
+    if (!Array.isArray(get(f, card))) return h("div", { class: "msg info" }, W.derive.custom_profile.description);
+    arr().forEach((row, i) => {
+      const set = (k, v) => { const a = clone(arr()); a[i][k] = v; put(f, card, a); };
+      const say = (what) => P.window + " " + (i + 1) + ", " + what;
+      const time = (k) => {
+        const e = h("input", { class: "txt time", type: "text", inputmode: "numeric", maxlength: "5", placeholder: "00:00",
+                               value: row[k] == null ? "" : row[k], autocomplete: "off", spellcheck: "false", "aria-label": say(P[k]) });
+        e.addEventListener("input", () => set(k, e.value.trim()));
+        return e;
+      };
+      const days = h("select", { class: "sel", "aria-label": say(P.days) });
+      for (const [v, label] of f.days || []) days.append(h("option", { value: v, selected: v === row.days }, label));
+      days.addEventListener("change", () => set("days", days.value));
+      const price = h("input", { class: "num", type: "number", inputmode: "decimal", step: "0.01",
+                                 value: row.price == null ? "" : row.price, "aria-label": say(P.price) });
+      price.addEventListener("input", () => set("price", price.value === "" || isNaN(+price.value) ? null : +price.value));
+      const cell = (label, ...kids) => h("label", { class: "pf" }, h("span", { class: "tiny muted" }, label), ...kids);
+      box.append(h("div", { class: "erow prow" },
+        h("div", { class: "row spread" }, h("strong", { class: "small" }, P.window + " " + (i + 1)),
+          h("button", { type: "button", class: "btn link tiny", onclick: () => { const a = clone(arr()); a.splice(i, 1); put(f, card, a, true); } }, W.remove)),
+        h("div", { class: "row" }, cell(P.from, time("from")), cell(P.to, time("to")),
+          cell(P.price, h("span", { class: "row" }, price, f.unit ? h("span", { class: "unit" }, f.unit) : null))),
+        cell(P.days, days)));
+    });
+    box.append(h("button", { type: "button", class: "btn", onclick: () => {
+      const a = arr(), last = a[a.length - 1];
+      put(f, card, clone(a).concat([{ from: last ? last.to : "00:00", to: "24:00", days: last ? last.days : "mon-sun", price: null }]), true);
+    } }, "+ " + P.add));
+    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,
+                     period_list: periodList };
+
+  /* ---------------- rows, cards and groups ---------------- */
+  function keyText(f, card) {
+    if (view === "setup") return "";     // the wizard shows no keys
+    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 = gid === "simple" ? "" : keyText(f, card);     // Simple shows no keys
+    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 && !["slider", "number", "locked", "period_list"].includes(f.control) ? " (" + 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)), view === "setup" ? null : 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);
+    }
+    renderSimple();
+    paint();
+    window.scrollTo(0, y);
+  }
+
+  /* ---------------- Settings, Simple (P3) ---------------- */
+  // The fields the layout marks `simple`, each in its own card with when it
+  // applies, and the batteries' switches and modes (runtime state, applied at
+  // once) drawn by app.js from /status. The Installer rows stay built but
+  // hidden, so the save bar counts every unsaved change in either view.
+  const chip = (applies) => h("span", { class: "chip " + (applies === "now" ? "now" : "rs") }, ROOT.applies[applies].name);
+  // A note with {kw} is filled from /status (app.js sends ux13:status).
+  function fillNotes() {
+    const st = window.UX13.status();
+    const mp = st && st.month_peak;
+    document.querySelectorAll("#simple [data-kw-note]").forEach((e) => {
+      const ok = mp && mp.peak_w != null;
+      e.hidden = !ok;
+      e.textContent = ok ? e.dataset.kwNote.replace("{kw}", window.UX13.kw(mp.peak_w) + " kW") : "";
+    });
+  }
+  // OPT-11 P4: the solar forecast card shows the add-on's forecast line.
+  function fillSolar() {
+    const st = window.UX13.status();
+    const line = st && st.solar ? st.solar.line : "";
+    document.querySelectorAll("#simple [data-solar-note]").forEach((e) => {
+      e.textContent = line || "";
+      e.hidden = !line;
+    });
+  }
+  document.addEventListener("ux13:status", fillNotes);
+  document.addEventListener("ux13:status", fillSolar);
+  function simpleField(f) {
+    const row = fieldRow(f, null, "simple");
+    row.querySelector(".head").append(chip(f.applies));
+    const n = f.note && W.simple.note[f.note];
+    if (n && n.description.includes("{kw}")) {
+      row.append(h("div", { class: "small muted", "data-kw-note": n.description, hidden: true }));
+    } else if (n) {
+      // A plain note replaces the option's installer help on this view.
+      const help = row.querySelector(".help");
+      if (help) help.textContent = n.description;
+    }
+    if (f.note === "forecast") row.append(h("div", { class: "small muted", "data-solar-note": "", hidden: true }));
+    return h("div", { class: "card" }, row);
+  }
+  function renderSimple() {
+    const host = $("#simple");
+    host.replaceChildren();
+    if (mode !== "simple") return;
+    const cards = allFields().filter((f) => f.simple).map(simpleField);
+    const batts = h("div", {});
+    cards.splice(Math.min(1, cards.length), 0, h("div", { class: "card" },
+      h("div", { class: "row spread" }, h("div", { class: "lbl" }, W.simple.batteries.name), chip("now")), batts));
+    host.append(...cards, h("p", { class: "small muted", style: "margin:4px 2px" }, W.simple.more.description + " ",
+      h("button", { type: "button", class: "btn link", onclick: () => setMode("installer", true) }, W.simple.installer)));
+    window.UX13.batteries(batts);
+    fillNotes();
+  }
+  // `remember`: only the person's own pick of a view is kept for next time;
+  // a jump to Installer (a link, a setting to fix) is not.
+  function setMode(v, redraw, remember) {
+    mode = v;
+    if (remember) try { localStorage.setItem("ux13.settings.view", v); } catch (e) { /* no storage */ }
+    document.querySelectorAll("#set-view [role=radio]").forEach((b) => {
+      const on = b.dataset.v === v;
+      b.setAttribute("aria-checked", String(on)); b.tabIndex = on ? 0 : -1;
+    });
+    $("#set-desc").textContent = v === "simple" ? W.simple.description : W.description;
+    $("#simple").hidden = v !== "simple";
+    ["#set-search", "#groups", "#set-nomatch"].forEach((id) => { $(id).classList.toggle("vhide", v === "simple"); });
+    if (redraw && M && view === "settings") render();
+  }
+  document.querySelectorAll("#set-view [role=radio]").forEach((b, i, all) => {
+    b.addEventListener("click", () => setMode(b.dataset.v, true, true));
+    b.addEventListener("keydown", (e) => {
+      const d = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }[e.key];
+      if (!d) return;
+      e.preventDefault();
+      const j = all[(i + d + all.length) % all.length];
+      setMode(j.dataset.v, true, true); j.focus();
+    });
+  });
+  setMode(mode, false);
+  window.UX13.settingsView = (v) => setMode(v, true);
+
+  /* ---------------- 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 = view === "setup" || mode === "simple" ? "" : $("#set-search").value.trim().toLowerCase();
+    // A message counts as shown only beside a row of the view on screen.
+    const onScreen = (r) => view === "setup" || (mode === "simple") === (r.gid === "simple");
+    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 && onScreen(r)) 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 = !(view === "settings" && 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); }
+  // `extra` asks for more, e.g. the wizard's live checks. Returns the answer,
+  // or null when it failed or a newer check overtook it.
+  async function validate(extra) {
+    const seq = ++vseq;
+    try {
+      const r = await fetch("config/validate", { method: "POST", headers: { "Content-Type": "application/json" },
+                                                 body: JSON.stringify(Object.assign({ model: V, lang }, extra || {})) });
+      const b = await r.json();
+      if (seq !== vseq) return null;
+      MSG = b.messages || [];
+      DEVICE = b.device_note || "";
+      STEPS = b.steps || {};
+      paint();
+      return b;
+    } catch (e) { return null; /* 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=" + lang, { 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();
+    if (view === "setup") drawStep(); else render();
+    validate();
+  }
+  function firstBad() {
+    if (view === "settings" && mode === "simple" && !ROWS.some((x) => x.gid === "simple" && x.tiers && x.tiers.has("bad") && x.visible)
+        && ROWS.some((x) => x.tiers && x.tiers.has("bad") && x.visible)) setMode("installer", true);
+    const r = ROWS.find((x) => x.tiers && x.tiers.has("bad") && x.visible && (view !== "settings" || (mode === "simple") === (x.gid === "simple")));
+    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 });
+  }
+  // The one save path, for the Installer view and the wizard. After a stale
+  // refusal the page holds the new token, so a second press saves. `base` is
+  // the model the page opened: only what changed since then is written, onto
+  // what is stored now (UX-15 F2).
+  async function postSave(extra) {
+    const r = await fetch("config/save", { method: "POST", headers: { "Content-Type": "application/json" },
+                                           body: JSON.stringify(Object.assign({ model: V, base: ORIG, fingerprint: FP, lang }, extra || {})) });
+    const b = await r.json().catch(() => ({}));
+    if (r.status === 409 && b.kind === "stale") FP = b.fingerprint || FP;
+    return { r, b };
+  }
+  // The settings another surface changed (not this page's own edits).
+  function staleText(b) {
+    const names = (b.changed_fields || []).map((k) => { const f = findField(k); return f ? f.label : k; });
+    return W.stale.description + (names.length ? " " + names.join(", ") + "." : "");
+  }
+  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, b } = await postSave();
+      if (r.ok) { toast(W.toast.saved); await load("saved"); return; }
+      if (r.status === 409 && b.kind === "stale") {
+        banner("bad", W.stale.name, staleText(b));
+        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 = ""; } });
+
+  /* ---------------- the setup wizard (P4) ---------------- */
+  const WS = W.setup;
+  const WZ = { step: 1, kettle: null, shadowOn: true, done: "", checked: null };
+  function redrawView() { if (view === "setup") drawStep(); else render(); }
+  function allFields() {
+    const out = [];
+    for (const g of M.layout.groups) for (const p of g.parts) for (const f of p.fields) out.push(f);
+    return out;
+  }
+  const say = (text, vars) => Object.keys(vars || {}).reduce((t, k) => t.replace("{" + k + "}", vars[k]), text);
+  function watts(w, signed) {
+    const n = String(Math.round(Math.abs(w))).replace(/\B(?=(\d{3})+(?!\d))/g, " ");
+    return (signed && w < 0 ? "-" : "") + n + " W";
+  }
+  function line(tier, text) {
+    const icon = { ok: "✓", bad: "×", warn: "!", info: "i" }[tier] || "i";
+    return h("li", {}, h("span", { class: "sev " + tier, "aria-hidden": "true" }, icon),
+      h("span", {}, h("span", { class: "sr" }, (W.tier[tier] || "") + ": "), text));
+  }
+
+  // Step 1's kettle test. The table is app/uilayout.py's KETTLE; this is
+  // uipage.kettle() (test_setup.py grades that one) on the page.
+  function kettleSource() { const K = M.setup.kettle; return K.sources[V[K.source]] || null; }
+  function kettleSig(src) { return JSON.stringify([V[M.setup.kettle.source], src.read.map(([k]) => V[k] || "")]); }
+  function kettleOutcome(src, before, after) {
+    const d = after - before;
+    if (Math.abs(d) < M.setup.kettle.min_w) return { say: "none", sets: null, d };
+    const o = src[d > 0 ? "up" : "down"];
+    return { say: o.say, sets: o.sets, d };
+  }
+  function kettleOk() {
+    const src = kettleSource();
+    return !src || !!(WZ.kettle && WZ.kettle.sig === kettleSig(src) && WZ.kettle.ok);
+  }
+  async function readMeter(src) {
+    let total = 0;
+    for (const [key, sign] of src.read) {
+      if (!V[key]) return null;
+      const r = await fetch("ha/entities?entity=" + encodeURIComponent(V[key]), { cache: "no-store" })
+        .then((x) => (x.ok ? x.json() : null)).catch(() => null);
+      if (!r || r.watts == null) return null;
+      total += sign * r.watts;
+    }
+    return total;
+  }
+  function kettleBox() {
+    const src = kettleSource();
+    const box = h("div", { class: "f kettle" }, h("div", { class: "lbl" }, WS.kettle.name));
+    if (!src) { box.append(h("div", { class: "help" }, WS.kettle.self.description)); return box; }
+    const sig = kettleSig(src);
+    if (WZ.kettle && WZ.kettle.sig !== sig) WZ.kettle = null;     // another meter: test again
+    const k = WZ.kettle || { sig };
+    box.append(h("div", { class: "help" }, WS.kettle.description));
+    // A skip after the reading went down still says it went down (UX-15).
+    const said = k.say === "skipped" && k.wrong ? "skipped_down" : k.say;
+    const tone = { ok: "ok", flip: "info", none: "warn", unread: "bad", skipped: "warn", skipped_down: "warn" }[said] || "bad";
+    const words = said ? WS.kettle[said] : k.before != null ? WS.kettle.before : null;
+    if (words) box.append(h("div", { class: "msg " + (k.say ? tone : "info"), role: "status" },
+      say(words.description, { w: k.before != null ? watts(k.before, true) : "", d: k.d != null ? watts(k.d) : "" })));
+    const busy = (b) => { b.disabled = true; };
+    const read = h("button", { type: "button", class: "btn" }, k.before != null && !k.ok ? WS.kettle.again : WS.kettle.read);
+    read.addEventListener("click", async () => {
+      busy(read);
+      const sig = kettleSig(src);           // the entity may have changed since drawing
+      if (k.sig !== sig) { k.before = null; k.ok = false; k.sig = sig; }
+      const w = await readMeter(src);
+      if (w == null) WZ.kettle = Object.assign({}, k, { sig, say: "unread" });
+      else if (k.before == null || k.ok) WZ.kettle = { sig, before: w, wrong: !k.ok && !!k.wrong };
+      else {
+        const o = kettleOutcome(src, k.before, w);
+        // `wrong`: the reading went the way no option can fix. A skip after
+        // that keeps saying so on the last step (review R2).
+        const wrong = o.say === "none" ? !!k.wrong : o.sets == null;
+        WZ.kettle = { sig, before: o.say === "none" ? k.before : null, say: o.say, d: o.d, ok: o.sets != null, wrong };
+        if (o.sets) { Object.assign(V, o.sets); queueValidate(); }
+      }
+      drawStep();
+    });
+    const row = h("div", { class: "row" }, read);
+    if (!k.ok) row.append(h("button", { type: "button", class: "btn link", onclick: () => {
+      WZ.kettle = { sig: kettleSig(src), say: "skipped", ok: true, skipped: true, wrong: !!k.wrong }; drawStep();
+    } }, WS.kettle.skip));
+    box.append(row);
+    return box;
+  }
+
+  // Step 6: the shadow switch, the checks, and Save and restart.
+  // The shadow switch goes only on the model the wizard posts, never into V,
+  // which the Installer view saves too (review R3).
+  function shadowValue() {
+    const s = M.setup.shadow;
+    return WZ.shadowOn ? s.on : (ORIG[s.field] !== s.on ? ORIG[s.field] : s.off);
+  }
+  function posted() { return Object.assign({}, V, { [M.setup.shadow.field]: shadowValue() }); }
+  function shadowRow() {
+    const lid = "wzs";
+    const b = h("button", { type: "button", class: "switch", role: "switch", "aria-checked": String(WZ.shadowOn), "aria-labelledby": lid });
+    b.addEventListener("click", () => { WZ.shadowOn = !WZ.shadowOn; drawStep(); });
+    return h("div", { class: "f inline" },
+      h("div", {}, h("div", { class: "lbl", id: lid }, WS.shadow.name), h("div", { class: "help" }, WS.shadow.description)),
+      h("div", { class: "ctl" }, b));
+  }
+  async function runChecks() {
+    const list = $("#wz-checks");
+    if (list) list.replaceChildren(line("info", WS.check.running.description));
+    clearTimeout(vtimer);
+    const b = await validate({ setup: true, model: posted() });
+    WZ.checked = b;
+    if (!list || !list.isConnected) return b;
+    if (!b) { list.replaceChildren(line("bad", WS.check.failed.description)); return b; }
+    const items = [], seen = new Set();
+    const add = (tier, text) => { if (!seen.has(text)) { seen.add(text); items.push([tier, text]); } };
+    const bad = (b.messages || []).filter((m) => m.tier === "bad");
+    if (!bad.length) add("ok", WS.check.pass.description);
+    for (const m of bad) add("bad", m.text);
+    for (const m of b.setup || []) add(m.tier, m.text);
+    if (b.device_note) add("info", b.device_note);
+    const src = kettleSource();
+    if (!src) add("info", WS.kettle.self.description);
+    else if (WZ.kettle && WZ.kettle.skipped) add("warn", (WZ.kettle.wrong ? WS.kettle.skipped_wrong : WS.kettle.skipped).description);
+    else if (kettleOk()) add("ok", WS.kettle.tested.description);
+    const rank = { bad: 0, warn: 1, ok: 2, info: 3 };
+    items.sort((a, z) => rank[a[0]] - rank[z[0]]);
+    list.replaceChildren(...items.map(([t, x]) => line(t, x)));
+    WZ.blocked = items.some(([t]) => t === "bad");
+    return b;
+  }
+  function finalBox() {
+    const again = h("button", { type: "button", class: "btn", onclick: runChecks }, WS.check.again);
+    setTimeout(runChecks, 0);
+    return [h("div", { class: "subhead" }, WS.check.name),
+      h("ul", { class: "plain checklist small", id: "wz-checks", "aria-live": "polite" }), h("div", { class: "row" }, again),
+      shadowRow()];
+  }
+  function wzBanner(level, title, sub, button, onClick) {
+    const host = $("#wz-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))));
+  }
+  async function finish() {
+    const b = await runChecks();
+    if (!b) { toast(WS.check.failed.description); return; }
+    if (WZ.blocked) { toast(WS.check.blocked.description); return; }
+    const shadow = shadowValue() === M.setup.shadow.on;
+    // In setup-only mode nothing runs yet, so no inverter is set to 0 W first.
+    const dlg = M.setup_only ? (shadow ? WS.dialog_setup : WS.dialog_setup_live) : (shadow ? WS.dialog : WS.dialog_live);
+    ask(dlg, async () => {
+      wzBanner();
+      let res;
+      try { res = await postSave({ setup: "done", model: posted() }); } catch (e) { toast(W.toast.failed); return; }
+      const { r, b: body } = res;
+      if (r.status === 409 && body.kind === "stale") { wzBanner("bad", W.stale.name, staleText(body)); return; }
+      if (r.status === 422) {
+        MSG = body.messages || []; STEPS = body.steps || {};
+        const first = Object.keys(STEPS).map(Number).sort((a, z) => a - z).find((n) => STEPS[n] > 0);
+        if (first) WZ.step = first;
+        drawStep(); toast(W.toast.blocked.description); firstBad();
+        return;
+      }
+      if (!r.ok) { toast(W.toast.failed); return; }
+      let restarted = true;
+      try {
+        const rr = await fetch("config/restart", { method: "POST", headers: { "Content-Type": "application/json" },
+                                                   body: JSON.stringify({ confirm: "restart" }) });
+        restarted = rr.ok;
+      } catch (e) { /* the add-on stops answering while it restarts */ }
+      WZ.done = restarted ? (shadow ? "done" : "done_live") : "restart_failed";
+      drawStep();
+      if (!restarted) await load("saved");      // still running: read what is stored
+    });
+  }
+  function drawDone() {
+    const w = WS[WZ.done];
+    $("#wz-count").textContent = "";
+    $("#wz-steps").replaceChildren();
+    $("#wz-desc").textContent = "";
+    $("#wz-nav").hidden = true;
+    ROWS.length = 0;
+    if (WZ.done === "restart_failed") wzBanner("warn", w.name, w.description, W.restart, restart);
+    else wzBanner("ok", w.name, w.description);
+    $("#wz-body").replaceChildren(h("a", { class: "btn primary", href: "#home" }, WS.home));
+  }
+  function drawStep() {
+    if (!M) return;
+    if (WZ.done) { drawDone(); return; }
+    const S = M.setup, n = WZ.step, words = WS.steps[n];
+    $("#wz-nav").hidden = false;
+    $("#wz-title").textContent = words.name;
+    $("#wz-count").textContent = say(WS.step, { n, total: S.steps });
+    $("#wz-steps").replaceChildren(...Array.from({ length: S.steps }, (_x, i) =>
+      h("i", { class: i + 1 < n ? "done" : i + 1 === n ? "cur" : null })));
+    $("#wz-desc").textContent = words.description;
+    ROWS.length = 0;
+    const body = [];
+    if (n === 1 && !M.setup_needed) body.push(h("div", { class: "msg info" }, WS.done_before.description));
+    for (const f of allFields()) if (f.wizard === n && f.key !== S.shadow.field) body.push(fieldRow(f, null, "wz"));
+    if (n === 1) body.push(kettleBox());
+    if (n === 5) body.push(h("p", { class: "small muted" }, WS.modes_later.description));
+    if (n === S.final) body.push(...finalBox());
+    $("#wz-body").replaceChildren(...body);
+    $("#wz-back").textContent = n === 1 ? WS.not_now : WS.back;
+    $("#wz-next").textContent = n === S.final ? WS.finish : S.optional.includes(n) ? WS.skip : WS.next;
+    paint();
+  }
+  $("#wz-back").addEventListener("click", () => {
+    if (WZ.step === 1) { location.hash = "#home"; return; }
+    WZ.step -= 1; drawStep(); window.scrollTo(0, 0);
+  });
+  $("#wz-next").addEventListener("click", async () => {
+    if (!M) return;
+    const btn = $("#wz-next");
+    btn.disabled = true;
+    try {
+      const n = WZ.step;
+      if (n === M.setup.final) { await finish(); return; }
+      clearTimeout(vtimer);
+      const b = await validate();
+      if (!b) { toast(W.toast.failed); return; }
+      if (n === 1 && !kettleOk()) { toast(WS.kettle.needed.description); return; }
+      if ((STEPS[n] || 0) > 0) { toast(W.toast.blocked.description); firstBad(); return; }
+      WZ.step = n + 1; drawStep(); window.scrollTo(0, 0);
+    } finally { btn.disabled = false; }
+  });
+
+  document.addEventListener("ux13:tab", (e) => {
+    view = e.detail === "settings" || e.detail === "setup" ? e.detail : null;
+    if (view && !M) load(); else if (view) { redrawView(); validate(); } else savebar();
+  });
+  // app.js chose the first tab before this file ran.
+  const sel = document.querySelector(".tab[aria-selected=true]");
+  if (sel && (sel.dataset.hash === "settings" || sel.dataset.hash === "setup")) { view = sel.dataset.hash; load(); }
+  // First run: opened with no route, on a site the add-on says is new
+  // (uipage.setup_needed), the page goes to Setup by itself.
+  else if (window.UX13.first) {
+    load().then(() => { if (M && M.setup_needed && location.hash === "#home") location.hash = "#setup"; });
+  }
+})();

goodwe_controller/app/static_tariff.py

@@ -204,6 +204,7 @@ import math
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 
+from . import messages
 from .price import (
     MAX_PLAUSIBLE_EUR_KWH, Absence, PricePoint, PriceProduct, PriceRead,
     Uncertainty, _Outcome, brussels, load_prices, price_option,
@@ -262,9 +263,8 @@ def _minutes(value, field: str) -> int:
     parts = text.split(":")
     if len(parts) != 2:
         raise ProfileInvalid(
-            f"{field} is {value!r}; it must be \"HH:MM\" local Belgian time, "
-            f"e.g. \"22:00\". A bare hour or a decimal is refused rather than "
-            f"guessed at - 7.5 could be 07:30 or 07:50.")
+            f"{field} is {value!r}. Write it as \"HH:MM\" in Belgian time, "
+            f"for example \"22:00\".")
     try:
         h, m = int(parts[0]), int(parts[1])
     except ValueError:
@@ -272,9 +272,8 @@ def _minutes(value, field: str) -> int:
                              f"integers, e.g. \"07:00\"")
     if not (0 <= m < 60) or not (0 <= h <= 24) or (h == 24 and m != 0):
         raise ProfileInvalid(
-            f"{field} is {value!r}, which is not a time of day. Hours run 0-23, "
-            f"minutes 0-59; \"24:00\" is accepted only as an END meaning "
-            f"midnight at the end of the day.")
+            f"{field} is {value!r}, which is not a time of day. Use 00:00 to "
+            f"23:59, or \"24:00\" as an end time.")
     return h * 60 + m
 
 
@@ -286,11 +285,8 @@ def _days(value, field: str) -> frozenset:
     """
     if value is None:
         raise ProfileInvalid(
-            f"{field} is missing. Name the days this period applies to - "
-            f"\"mon-fri\", \"sat,sun\" or \"all\". It is required rather than "
-            f"defaulted to every day, because a Belgian night tariff that "
-            f"silently covered the weekend too would misprice 48 h a week with "
-            f"nothing reporting it.")
+            f"{field} is missing. Name the days, for example \"mon-fri\", "
+            f"\"sat,sun\" or \"all\".")
     tokens = []
     if isinstance(value, (list, tuple)):
         for item in value:
@@ -367,10 +363,8 @@ def _price(value, field: str, means: str = None) -> float:
         raise ProfileInvalid(f"{field} is {value!r}, which is not finite")
     if abs(out) > MAX_PLAUSIBLE_EUR_KWH:
         raise ProfileInvalid(
-            f"{field} is {out} EUR/kWh, beyond +-{MAX_PLAUSIBLE_EUR_KWH}. The "
-            f"usual cause is a figure in cents or in EUR/MWh - 34 instead of "
-            f"0.34 - which would make every hour look like an emergency. Same "
-            f"bound the fetched feeds are held to (price.py `_validate_raw`).")
+            f"{field} is {out} EUR/kWh, beyond +-{MAX_PLAUSIBLE_EUR_KWH}. "
+            f"Write the price in EUR/kWh, for example 0.34 and not 34.")
     return out
 
 
@@ -422,9 +416,8 @@ class StaticProfile:
         self.option = option
         if not self.periods:
             raise ProfileInvalid(
-                f"{option} has no periods. A profile with no periods is "
-                f"not a fixed tariff, it is an absent one - leave the option "
-                f"empty to say that on purpose (§11.4 then applies).")
+                f"{option} has no periods. Add at least one, or leave the "
+                f"setting empty.")
         _check_tiling(self.periods, option=option)
 
     # -- what kind of tariff this is, DERIVED --------------------------------
@@ -558,10 +551,7 @@ def _raise_gap(weekday, start, end, option="static_profile"):
     raise ProfileInvalid(
         f"{option} leaves {DAY_NAMES[weekday]} "
         f"{_hhmm(start)}-{_hhmm(end)} with no period, so those hours have no "
-        f"price. Refused rather than defaulted: an invented price is one an "
-        f"optimiser would trade on, and §11.4 already says what a missing price "
-        f"means. Add a period covering it - remember a window written "
-        f"\"22:00-07:00 mon-fri\" does NOT cover Saturday morning.")
+        f"price. Add a period that covers them.")
 
 
 def _raise_overlap(weekday, over, end, periods, option="static_profile"):
@@ -569,9 +559,8 @@ def _raise_overlap(weekday, over, end, periods, option="static_profile"):
     names = [p.name for p in periods if p.covers(weekday, start)]
     raise ProfileInvalid(
         f"{option} gives {DAY_NAMES[weekday]} {_hhmm(start)}-"
-        f"{_hhmm(end)} {n} prices at once ({', '.join(names)}). Two prices for "
-        f"one hour means one of them silently wins on list order. Narrow one of "
-        f"the windows or split the day selector.")
+        f"{_hhmm(end)} {n} prices at once ({', '.join(names)}). Make the "
+        f"periods stop overlapping.")
 
 
 def parse_static_profile(value, *, option: str = "static_profile",
@@ -609,28 +598,21 @@ def parse_static_profile(value, *, option: str = "static_profile",
             value = json.loads(text)
         except ValueError as e:
             raise ProfileInvalid(
-                f"{option} is not valid JSON ({e}). It is a JSON object "
-                f"with a \"periods\" list, on one line, e.g.\n"
-                f'  {{"periods": [{{"name":"day","from":"07:00","to":"22:00",'
-                f'"days":"mon-fri","eur_per_kwh":0.34}}, ...]}}\n'
-                f"Leave it empty for a dynamic-only or price-free site.")
+                f"{messages.not_valid(option, e)}. Copy the example from the "
+                f"documentation, or leave it empty if you have no fixed "
+                f"tariff.")
 
     if isinstance(value, dict):
         tz = str(value.get("timezone", "") or "").strip().lower()
         if tz not in SUPPORTED_TZ:
             raise ProfileInvalid(
                 f"{option}.timezone is {value.get('timezone')!r}. Only "
-                f"Europe/Brussels is supported: the shipped image carries no tz "
-                f"database (see app/price.py), so any other zone could not be "
-                f"honoured and would be silently treated as Brussels - which is "
-                f"wrong by an hour for part of the year.")
+                f"Europe/Brussels is supported.")
         rows = value.get("periods")
         if rows is None:
             raise ProfileInvalid(
-                f"{option} has no \"periods\" list. Even a fully-fixed "
-                f"tariff is written as one period covering 00:00-24:00 all days "
-                f"- one shape for both products, so nothing downstream branches "
-                f"on which kind of site this is.")
+                f"{option} has no \"periods\" list. A fixed price is one "
+                f"period from 00:00 to 24:00 on all days.")
     else:
         rows = value
 
@@ -1137,18 +1119,39 @@ class TariffPlan:
         for 76 % of a 40-hour soak and mixed 900/3600 s for 70 %, and no HTTP
         surface said either.
         """
+        # UX-08: plain words, every figure in its own slot as before.
         if not self.has_prices:
-            return f"no tariff - {self.read.reason}"
-        tag = {"provider": self.read.provider, "static": "static_profile",
-               "fallback": "static_profile (feed down)"}.get(self.origin,
-                                                             self.origin)
+            return f"no prices, {self.read.reason}"
+        tag = {"provider": "the price feed", "static": "your fixed tariff",
+               "fallback": "your fixed tariff, because the feed is down"}.get(
+                   self.origin, self.origin)
+        what = {PriceProduct.DAY_AHEAD: "day-ahead prices",
+                PriceProduct.REALTIME: "real-time prices",
+                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"{self.product.value} from {tag}, "
-                f"{self.n_points} points over {self.hours} h, "
-                f"{self.n_firm} firm / {self.n_carried} carried"
-                + (f", {'+'.join(str(g) for g in gaps)} s spacing"
-                   if gaps else "")
-                + (", provisional" if self.provisional else ""))
+        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", {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:
@@ -1218,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(
@@ -1242,21 +1245,22 @@ def static_status(opts: dict, now: datetime):
         plan = static_plan(opts, now, now + timedelta(days=MEAN_WINDOW_DAYS),
                            now=now)
     except ProfileInvalid as e:
-        _LOG.warning("static_profile is unusable (%s); no cheap window. This "
-                     "should have been refused at startup - see validate.py", e)
-        return False, f"static_profile unusable: {e}"
+        _LOG.warning("static_profile cannot be used (%s), so there is no "
+                     "cheap window. The start-up check should have refused "
+                     "it.", e)
+        return False, f"Fixed tariff cannot be used: {e}"
     if not plan.has_prices:
-        return False, "no static profile"
+        return False, "No fixed tariff set"
     cheap = plan.cheap_now(now)
     window = plan.window_at(now)
     price = plan.price_at(now)
     when = plan.profile.next_change(now)
     until = "" if when is None else f" until {brussels(when):%H:%M}"
-    kind = ("fixed" if plan.product is PriceProduct.FIXED else "day/night")
-    return cheap, (f"{kind}: {window}{until} at {price:.4f} EUR/kWh, "
-                   f"mean {plan.mean_eur_kwh():.4f} over "
-                   f"{MEAN_WINDOW_DAYS} d - "
-                   f"{'CHEAP window' if cheap else 'not a cheap window'}")
+    kind = ("Fixed" if plan.product is PriceProduct.FIXED else "Day/night")
+    return cheap, (f"{kind} tariff, {window}{until}: {price:.4f} EUR/kWh, "
+                   f"{'cheap' if cheap else 'not cheap'} against the "
+                   f"{MEAN_WINDOW_DAYS}-day average of "
+                   f"{plan.mean_eur_kwh():.4f}")
 
 
 async def resolve_tariff(opts: dict, since: datetime, until: datetime,
@@ -1349,17 +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("§11.4: %s, and no static_profile is configured to fall "
-                     "back to. The plan is provisional and arbitrage is off; "
-                     "self-consumption, peak shaving and reserve management "
-                     "continue (§6, §10.1).", 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("§11.4: %s - falling back to the static profile, plan marked "
-                 "PROVISIONAL, arbitrage 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
 
 
@@ -328,8 +338,8 @@ def migrate_unit_keys(store, unit: str, roster=None) -> MigrationReport:
         # ⚠️ NOT MARKED DONE. A migration that lost state must run again on the
         # next start rather than be recorded as finished - the one thing worse
         # than a failed migration is a failed migration a later version skips.
-        _LOG.error("per-inverter store migration LOST STATE and has not been "
-                   "marked done: %s", rep.explain())
+        _LOG.error("Moving the saved state to one part per inverter lost "
+                   "data, so it is not marked done: %s", rep.explain())
     return rep
 
 
@@ -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,15 +576,21 @@ 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
 
 
+STATE_PATH = "/data/state.json"
+
+
 class Store:
-    def __init__(self, path: str = "/data/state.json"):
-        self.path = path
+    def __init__(self, path: str | None = None):
+        self.path = path or STATE_PATH
         self.data = dict(DEFAULTS)
+        # UX-13 P4: True when this boot found no state file, i.e. a new /data.
+        # Only the setup wizard's first-run rule reads it (uipage.setup_needed).
+        self.fresh = False
         self.load()
 
     def load(self) -> None:
@@ -589,6 +604,7 @@ class Store:
                           self.data.get("phase"), self.data.get("last_completed"),
                           self.data.get("sign_tripped"))
         except FileNotFoundError:
+            self.fresh = True
             _LOG.info("no saved state, starting fresh")
         except (json.JSONDecodeError, OSError) as err:
             # A corrupt state file must not stop the controller: losing the

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 -------------------------------------------------------
@@ -813,6 +822,22 @@ class PeakTracker:
             held_w=averager.held_net_w)
 
 
+def next_quarter(p: Projection, max_hold_s: float) -> Projection:
+    """SAFETY-91: `p` past its block's end, before the next block's first
+    telegram: the next quarter, projected from the held reading (the averager
+    credits it there). `p` itself otherwise, or when that reading is too old
+    to be credited. DECISIONS/SAFETY-91-held-battery-last.md."""
+    if p.block_start is None or p.elapsed_s < QUARTER_S \
+            or p.elapsed_s * (1.0 - p.covered_frac) > float(max_hold_s):
+        return p
+    held = max(p.held_w, 0.0)
+    return Projection(projected_w=held, elapsed_w=held,
+                      elapsed_s=p.elapsed_s - QUARTER_S, covered_frac=1.0,
+                      complete=True,
+                      block_start=p.block_start + timedelta(seconds=QUARTER_S),
+                      held_w=p.held_w)
+
+
 @dataclass(frozen=True)
 class _ClosedBlock:
     """A block reconstructed from a checkpoint. Shaped like `p1.QuarterBlock` so

goodwe_controller/app/ui_text/en.json

@@ -0,0 +1,455 @@
+{
+  "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"},
+    "inverters.modes": {"name": "Battery modes"},
+    "tariff.selling": {"name": "Charging and selling on price"},
+    "tariff.feed": {"name": "Price feed details"},
+    "safety.peak": {"name": "Peak limit", "description": "The add-on aims a little below your limit, to be safe."},
+    "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."},
+    "periods": {"name": "Time windows and prices", "description": "One price per kWh for each time window, 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"},
+    "period_days": {"mon-sun": "Every day", "mon-fri": "Monday to Friday", "sat,sun": "Saturday and Sunday", "mon": "Monday", "tue": "Tuesday", "wed": "Wednesday", "thu": "Thursday", "fri": "Friday", "sat": "Saturday", "sun": "Sunday"}
+  },
+  "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."},
+    "setup_only": {"name": "Setup: nothing is controlled yet", "description": "Nothing is sent to any inverter until setup is saved and the add-on restarts.", "control": "Control starts after setup.", "open": "Open Setup"},
+    "batteries": {"name": "Batteries", "description": "To choose a mode for each battery, turn on battery modes in the settings.", "level": "Level", "now": "Now", "stored": "Stored", "mode": "Mode", "settings": "Change inverter settings",
+      "on": "On", "off": "Off",
+      "choice": {
+        "solar_first": {"name": "Solar first", "description": "Charges from solar before the other batteries and covers the house."},
+        "leftover_solar": {"name": "Leftover solar", "description": "Gets solar the others cannot take, and gives power in expensive hours."},
+        "cheap_hours": {"name": "Cheap hours only", "description": "Charges in the cheapest hours and gives power in the expensive ones."},
+        "off": {"name": "Off", "description": "Rests, and helps only when the peak limit needs it."}
+      },
+      "today": "Today", "why": "Why",
+      "modes_off": {"name": "Battery modes are off"},
+      "how": {"name": "How the modes work", "description": "Which battery gets solar first, and when each gives power.",
+        "solar_first": {"description": "Solar first gets spare solar before the other batteries, and covers the house at any hour."},
+        "leftover_solar": {"description": "Leftover solar gets the solar the Solar first batteries cannot take, and saves its power for expensive hours."},
+        "cheap_hours": {"description": "Cheap hours only charges in the cheapest hours and gives power in the expensive ones."},
+        "off": {"description": "Off rests the battery and starts no monthly cycle, but the peak limit may still use it."},
+        "rules": {"description": "The peak limit and the safety stops come first, and while one battery charges from the grid the others rest."}},
+      "toast": {"on": "{name} is on.", "off": "{name} is off.", "mode": "{name}: {mode}."}},
+    "settings": {"name": "Settings", "description": "The settings are grouped by task below.", "open": "Open the settings page"}
+  },
+  "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.",
+    "view": {"name": "Settings view", "simple": "Simple", "installer": "Installer"},
+    "simple": {"description": "The choices a home owner makes.",
+      "note": {"month_peak": {"description": "This month's peak so far: {kw}."}, "shadow": {"description": "Use Always on while you test a new installation."}, "forecast": {"description": "With a forecast, a battery buys only what the sun will not give."}},
+      "batteries": {"name": "Batteries"},
+      "more": {"description": "Looking for the meter, inverters or prices?"},
+      "installer": "Open the installer view"},
+    "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",
+    "periods": {"window": "Window", "from": "From", "to": "To", "days": "Days", "price": "Price", "add": "Add a time window"},
+    "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", "ok": "Passed"},
+    "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."},
+      "no_periods": {"description": "Add at least one time window."},
+      "period_time": {"description": "Window {row}: write each time as hours and minutes, like 07:00 or 24:00."},
+      "period_zero": {"description": "Window {row} starts and ends at the same time, so change one of them."},
+      "period_price": {"description": "Window {row}: enter a price per kWh."},
+      "period_price_range": {"description": "Window {row}: enter the price in euro per kWh, like 0.34."},
+      "period_overlap": {"description": "Windows {a} and {b} both cover {day} {from} to {to}, so change one of them."},
+      "period_gap": {"description": "No window covers {day} {from} to {to}, so add one or widen one."},
+      "unknown": {"description": "The page cannot store this choice, so reload the page."}
+    },
+    "setup": {
+      "name": "Setup",
+      "description": "For installers: six steps to a working site, and each can be changed later under Settings.",
+      "done_before": {"description": "This site is set up already, so a change here replaces its stored settings."},
+      "step": "Step {n} of {total}",
+      "back": "Back",
+      "next": "Next",
+      "skip": "Next, or skip",
+      "finish": "Save and restart",
+      "not_now": "Not now",
+      "steps": {
+        "1": {"name": "Your meter", "description": "The add-on steers the grid reading to zero, so it needs your meter first."},
+        "2": {"name": "Inverters and batteries", "description": "One card for each inverter with a battery, with its entities in Home Assistant."},
+        "3": {"name": "Solar", "description": "Optional, so skip this step if the add-on should not record solar production."},
+        "4": {"name": "Prices", "description": "What you pay per kWh, so the batteries can charge when power is cheap."},
+        "5": {"name": "Peak limit", "description": "The grid stays under this limit, averaged over each 15-minute period."},
+        "6": {"name": "Check and start", "description": "The add-on checks everything with its own start checks, then restarts."}
+      },
+      "modes_later": {"description": "After setup, turn on battery modes to choose a mode for each battery on the Batteries screen."},
+      "kettle": {
+        "name": "Check the direction",
+        "description": "Read the meter, switch on a kettle, then read the meter again.",
+        "read": "Read the meter",
+        "again": "Read again",
+        "skip": "Skip this test",
+        "before": {"description": "The meter reads {w} now, so switch on a kettle and press Read again."},
+        "unread": {"description": "The meter cannot be read now, so check the entity and try again."},
+        "none": {"description": "The reading moved only {d}, so switch the kettle on and read again."},
+        "ok": {"description": "Good, the reading went up by {d} when the kettle came on."},
+        "flip": {"description": "The reading went down by {d}, so the add-on flips its sign for you."},
+        "wrong_signed": {"description": "The reading went down by {d}, so choose “One grid power entity” above, which can flip it."},
+        "wrong_dsmr": {"description": "The reading went down by {d}, so check that import and export are not swapped."},
+        "self": {"description": "The add-on reads this meter itself, so Home shows its direction after the restart."},
+        "skipped": {"description": "The meter direction is not tested, so check it on Home after the restart."},
+        "skipped_wrong": {"description": "The kettle test saw the meter reading go down, so check its direction in step 1 before you start control."},
+        "skipped_down": {"description": "The reading went down when the kettle came on, so check the meter's direction before you start control."},
+        "tested": {"description": "The meter direction was tested with a kettle."},
+        "needed": {"description": "Do the kettle test first, or skip it."}
+      },
+      "check": {
+        "name": "What the add-on checked",
+        "running": {"description": "Checking with the add-on's own start checks."},
+        "pass": {"description": "The add-on's start checks pass."},
+        "failed": {"description": "The check did not run, so try again."},
+        "again": "Check again",
+        "blocked": {"description": "Fix the items marked in red, then check again."}
+      },
+      "dialog": {"name": "Save and restart?", "description": "Every inverter is set to 0 W while the add-on restarts, and shadow mode keeps them at 0 W after that.", "yes": "Save and restart"},
+      "dialog_live": {"name": "Save and restart?", "description": "Every inverter is set to 0 W while the add-on restarts, and then the new settings apply.", "yes": "Save and restart"},
+      "dialog_setup": {"name": "Save and restart?", "description": "The add-on restarts with these settings, and shadow mode keeps every inverter at 0 W.", "yes": "Save and restart"},
+      "dialog_setup_live": {"name": "Save and restart?", "description": "The add-on restarts with these settings, and then they apply.", "yes": "Save and restart"},
+      "done": {"name": "Setup is done", "description": "The add-on restarts in shadow mode now, so open Home in a minute to see what it would do."},
+      "done_live": {"name": "Setup is done", "description": "The add-on restarts now, so open Home in a minute to start control."},
+      "restart_failed": {"name": "Saved, not running yet", "description": "The restart did not go through, so press Restart now to apply the settings."},
+      "home": "Open Home"
+    }
+  },
+  "home_words": {
+    "mode_house": "Follows the house",
+    "modes": {"solar_first": "Solar first", "leftover_solar": "Leftover solar", "cheap_hours": "Cheap hours only", "off": "Off"},
+    "attn_shadow": "Shadow mode is on",
+    "attn_shadow_body": "The add-on decides everything, but every inverter stays at 0 W.",
+    "zero_held": "Held at 0 W",
+    "zero_going": "Going to 0 W",
+    "verdict": {
+      "held": "Held at 0 W",
+      "stopped": "Stopped",
+      "cycle": "Monthly cycle today",
+      "trade": "Trading on price",
+      "house": "Follows the house"
+    },
+    "pill": {
+      "running": "Running",
+      "shadow": "Shadow mode",
+      "stopped": "Stopped",
+      "alarm": "Needs you now",
+      "warning": "Running, with a warning"
+    },
+    "banner_sub": {
+      "running": "The batteries follow the plan below.",
+      "shadow": "The plans below say what the add-on would do.",
+      "stopped": "Start control below when you are ready.",
+      "alarm": "See Needs attention below for what to do.",
+      "warning": "See Needs attention below."
+    },
+    "tile": {
+      "not_set_up": "Not set up",
+      "no_reading": "No reading",
+      "producing": "Producing",
+      "not_producing": "Not producing",
+      "needs_solar": "Needs a solar reading",
+      "not_adding_up": "Readings do not add up",
+      "using": "Using",
+      "taking": "Taking from the grid",
+      "feeding": "Feeding in",
+      "balanced": "Balanced",
+      "giving": "Giving power",
+      "charging": "Charging",
+      "resting": "Resting"
+    },
+    "now": {
+      "no_reading": "No reading from this battery.",
+      "would_rest": "{zero}. Would rest now.",
+      "would_give": "{zero}. Would give {kw} now.",
+      "would_charge": "{zero}. Would charge {kw} now.",
+      "held": "{zero} until the alarm clears.",
+      "stopped": "{zero} while control is stopped.",
+      "cycle_drain": "Monthly cycle: emptying.",
+      "cycle_charge": "Monthly cycle: refilling.",
+      "cycle_hold": "Monthly cycle: holding full.",
+      "cycle": "Monthly cycle under way.",
+      "giving": "Giving {kw} now.",
+      "charging": "Charging {kw} now.",
+      "resting": "Resting now.",
+      "off_resting": "Off. Resting now.",
+      "off_peak": "Off, but gives {kw} for the peak limit.",
+      "off_going": "Off. Still at {kw}, going to 0 W."
+    },
+    "why": {
+      "no_reading": "No reading, so the add-on cannot tell.",
+      "held": "An alarm stopped control. See Needs attention.",
+      "stopped": "Control is stopped.",
+      "shadow": "Shadow mode: the add-on only shows what it would do.",
+      "cycle": "The monthly cycle keeps its level reading right.",
+      "cycle_mode": "The monthly cycle comes first. Its mode resumes after.",
+      "off": "You switched it off.",
+      "off_peak": "The peak limit comes before Off. It rests again after.",
+      "refuses_give": "The battery refuses to give power. The add-on tries again every 15 minutes.",
+      "refuses_charge": "The battery refuses to charge. The add-on tries again every 15 minutes.",
+      "peak": "The peak limit needs power from the batteries.",
+      "modes_off": "Battery modes are off, so it follows the house.",
+      "solar_first": "Solar first: it gets spare solar before the others.",
+      "leftover": "It gets the solar that Solar first batteries cannot take.",
+      "leftover_alone": "No Solar first battery is on, so it gets solar first.",
+      "covers_house": "It gives power to cover the house.",
+      "other_refuses": "{name} refuses to give power, so this battery takes over.",
+      "other_cycle": "{name} is emptying for its monthly cycle. This one does not charge.",
+      "grid_charge": "Prices are low, so it charges from the grid.",
+      "rests_charge": "Another battery charges from the grid, so it rests.",
+      "selling": "Prices are high, so it sells to the grid.",
+      "expensive": "Prices are high, so it covers the house.",
+      "saves": "Saves its power for {at}.",
+      "saves_later": "Saves its power for higher prices.",
+      "no_prices": "No prices, so it follows the house.",
+      "no_spread": "Prices differ too little, so it follows the house.",
+      "sun_fills": "Enough sun is forecast, so it does not charge from the grid.",
+      "tops_up": "Too little sun is forecast, so it charges some from the grid.",
+      "no_forecast": "No solar forecast, so it charges from solar only."
+    },
+    "solar": {"line": "Solar still to come today: {kwh}, we count on {count}. Updated {at}.", "no_forecast": "No solar forecast now, so Leftover solar charges from solar only.", "learning": "The add-on is learning your house's use. The plan starts after one full day."},
+    "today": {
+      "not_planned": "Not planned yet.",
+      "no_runs": "No cheap or expensive hours left today.",
+      "off": "Off, so no monthly cycle today.",
+      "house": "Follows the house.",
+      "house_would": "Would follow the house.",
+      "stopped": "Nothing planned while control is stopped.",
+      "held": "Nothing planned until the alarm clears."
+    },
+    "head": {
+      "held": "Every inverter is at 0 W until the alarm clears.",
+      "held_going": "Every inverter goes to 0 W until the alarm clears.",
+      "stopped": "Control is stopped, so nothing is planned.",
+      "cycle": "A battery runs its monthly cycle today.",
+      "trade": "Charges in the cheapest hour, gives power in the dearest.",
+      "house": "Charges from spare solar and covers the house.",
+      "shadow": "Shadow mode: this is what the add-on would do.",
+      "cycle_would": "A battery would run its monthly cycle today.",
+      "trade_would": "Would charge when cheapest and give power when dearest.",
+      "house_would": "Would charge from spare solar and cover the house."
+    },
+    "run": {
+      "grid_what": "Charges up to {kwh} from the grid.",
+      "grid_what_would": "Would charge up to {kwh} from the grid.",
+      "grid_why": "Lowest published price, {eur} per kWh.",
+      "grid_amount": "Costs up to {eur}.",
+      "give_what": "Gives up to {kwh}, to the house first.",
+      "give_what_would": "Would give up to {kwh}, to the house first.",
+      "give_why": "Highest published price, {eur} per kWh.",
+      "sell_what": "Sells up to {kwh}, to the house first.",
+      "sell_what_would": "Would sell up to {kwh}, to the house first.",
+      "cheap_why": "Cheapest hours, about {eur} per kWh.",
+      "dear_why": "Expensive hours, about {eur} per kWh.",
+      "give_amount": "Worth up to {eur} at that price.",
+      "cycle_start": "Starts the monthly battery cycle.",
+      "cycle_start_would": "Would start the monthly battery cycle.",
+      "cycle_now": "Runs the monthly battery cycle now.",
+      "cycle_now_would": "Would run the monthly battery cycle now.",
+      "cycle_why": "Empties, refills and holds full, so the level reads right.",
+      "cycle_why_would": "Would empty, refill and hold full, so the level reads right.",
+      "cycle_amount_unknown": "How long depends on the battery.",
+      "cycle_amount": "Takes about {hours} hours.",
+      "peak_what": "Gives power to stay under {kw}.",
+      "peak_what_would": "Would give power to stay under {kw}.",
+      "peak_why": "The peak limit comes before everything else.",
+      "house_what": "Follows the house.",
+      "house_what_would": "Would follow the house.",
+      "house_why": "Charges from spare solar, gives power when the house needs it.",
+      "house_why_would": "Would charge from spare solar, give power when the house needs it.",
+      "house_amount": "Amounts depend on the sun and the house."
+    },
+    "no_trade": {
+      "not_covered": "No trading on price: nothing measures the 15-minute peak.",
+      "no_prices": "No trading on price yet: no prices have arrived.",
+      "peak": "No trading on price now: the peak limit comes first.",
+      "not_firm": "No trading on price yet: the prices are not published.",
+      "not_worth": "No trading on price today. The price gap is too small.",
+      "no_level": "No trading on price now: a battery level is unknown."
+    },
+    "tomorrow_trade": {
+      "grid": "Tomorrow: charges at {at}, {eur} per kWh.",
+      "grid_would": "Tomorrow: would charge at {at}, {eur} per kWh.",
+      "give": "Tomorrow: gives power at {at}, {eur} per kWh.",
+      "give_would": "Tomorrow: would give power at {at}, {eur} per kWh."
+    },
+    "cycle_waits": "{name} waits its turn for the monthly cycle.",
+    "step_in": "The batteries step in above {kw}.",
+    "step_in_would": "The batteries would step in above {kw}.",
+    "period": "This 15-minute period is heading for {kw}.",
+    "prices": {
+      "now": "Price now {eur} per kWh, all in.",
+      "today": "Today: lowest {lo} at {lo_at}, highest {hi} at {hi_at}.",
+      "none": "No prices for today."
+    },
+    "tomorrow": {
+      "known": "Tomorrow's prices are in.",
+      "unknown": "Tomorrow's prices usually arrive after 13:00."
+    },
+    "region": {
+      "preset": "Levies and VAT: {region}, {year} figures.",
+      "own": "Levies and VAT: your own figure."
+    },
+    "peak_not_covered": "No peak limit: this meter does not measure 15-minute periods.",
+    "control": {
+      "shadow": "Shadow mode: every inverter stays at 0 W.",
+      "running": "Control is running.",
+      "stopped": "Control is stopped. Every inverter is at 0 W."
+    },
+    "attn": {
+      "controller": "Control is not running",
+      "meter": "Meter reading",
+      "meter_frozen": "Meter reading may be stuck",
+      "freeze_check": "Stuck meter check",
+      "month_peak": "This month's peak",
+      "peak_guard": "Peak limit",
+      "peak_forecast": "Peak limit forecast",
+      "sensor": "Battery readings",
+      "control": "Inverter control",
+      "power_too_high": "Power request too high",
+      "not_keeping_up": "Battery is not keeping up",
+      "write": "Power request not accepted",
+      "direction": "Power went the wrong way",
+      "site_direction": "Power went the wrong way",
+      "circulating": "Inverters working against each other",
+      "delivery": "An inverter is not delivering",
+      "estop": "Emergency stop",
+      "pv": "Solar reading",
+      "none": "Inverter connection"
+    },
+    "months": ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]
+  }
+}

goodwe_controller/app/ui_text/nl.json

@@ -0,0 +1,378 @@
+{
+  "groups": {
+    "meter": {"name": "Meter", "description": "Waar de meting van het net vandaan komt."},
+    "inverters": {"name": "Omvormers en batterijen", "description": "De omvormers die de add-on regelt, en uw zonnepanelen."},
+    "tariff": {"name": "Tarief en prijzen", "description": "Wat u per kWh betaalt en terugkrijgt."},
+    "safety": {"name": "Veiligheidsgrenzen", "description": "De piekgrens, starten en stoppen, en de veiligheidsstops."},
+    "maintenance": {"name": "Onderhoud", "description": "De maandelijkse batterijcyclus en het logboek."},
+    "tuning": {"name": "Afstelling van de regeling", "description": "Alleen voor support, want deze zijn gemeten op echte hardware."}
+  },
+  "parts": {
+    "meter.timing": {"name": "Timing"},
+    "inverters.solar": {"name": "Zonnepanelen"},
+    "inverters.modes": {"name": "Batterijmodi"},
+    "tariff.selling": {"name": "Laden en verkopen op prijs"},
+    "tariff.feed": {"name": "Details van de prijsfeed"},
+    "safety.peak": {"name": "Piekgrens", "description": "De add-on mikt iets onder uw grens, voor de zekerheid."},
+    "safety.start": {"name": "Starten en stoppen"},
+    "safety.stops": {"name": "Veiligheidsstops", "description": "Gemeten op echte hardware, dus laat ze zoals ze zijn."},
+    "maintenance.support": {"name": "Support"}
+  },
+  "fields": {
+    "solar": {"name": "Omvormers van de zonnepanelen", "description": "De vermogenssensor van elke zonne-omvormer, die de add-on bijhoudt maar niet gebruikt om te regelen."},
+    "contract": {"name": "Uw contract", "description": "Hoe uw leverancier elke kWh prijst die u van het net afneemt."},
+    "region": {"name": "Regio", "description": "Vult nettarieven, heffingen en btw in voor het getoonde jaar, nog niet voor Wallonië of Brussel, dus kijk uw factuur na."},
+    "fallback": {"name": "Prijs als de feed wegvalt", "description": "Gebruikt als de prijsbron niet antwoordt."},
+    "fixed_price": {"name": "Prijs per kWh, alles inbegrepen", "description": "Energie, kosten van de leverancier, nettarieven, heffingen en btw samen."},
+    "day_price": {"name": "Dagprijs, weekdagen 07:00 tot 22:00", "description": "Alles inbegrepen, zoals op uw factuur."},
+    "night_price": {"name": "Nacht- en weekendprijs", "description": "Alles inbegrepen, zoals op uw factuur."},
+    "periods": {"name": "Tijdvakken en prijzen", "description": "Eén prijs per kWh voor elk tijdvak, alles inbegrepen, zoals op uw factuur."}
+  },
+  "choices": {
+    "contract": {"none": "Geen prijzen", "fixed": "Vaste prijs", "daynight": "Dag en nacht", "dynamic": "Dynamisch, per uur", "custom": "Andere tijdvakken"},
+    "fallback": {"none": "Geen", "fixed": "Eén prijs", "daynight": "Dag en nacht", "custom": "Andere tijdvakken"},
+    "region": {"flanders": "Vlaanderen, Fluvius Antwerpen", "own": "Ik vul zelf een bedrag in"},
+    "meter_source": {"off": "Eén entiteit voor netvermogen", "ha_dsmr": "Entiteiten voor afname en injectie", "mqtt_p1": "Meter via MQTT", "ha_signed": "Eén entiteit voor nettovermogen", "homewizard_local": "HomeWizard-meter op het netwerk"},
+    "meter_phases": {"1": "1 fase", "3": "3 fasen"},
+    "shadow_mode": {"auto": "Automatisch", "on": "Altijd aan", "off": "Uit"},
+    "price_provider": {"generic_dayahead": "Day-aheadprijs van de markt", "custom_formula": "Uw eigen prijsformule", "manual_csv": "Een prijsbestand"},
+    "log_level": {"trace": "Alles, voor support", "debug": "Uitgebreid, om een probleem te vinden", "info": "Normaal", "warning": "Waarschuwingen en fouten", "error": "Alleen fouten"},
+    "period_days": {"mon-sun": "Elke dag", "mon-fri": "Maandag tot vrijdag", "sat,sun": "Zaterdag en zondag", "mon": "maandag", "tue": "dinsdag", "wed": "woensdag", "thu": "donderdag", "fri": "vrijdag", "sat": "zaterdag", "sun": "zondag"}
+  },
+  "applies": {"restart": {"name": "Geldt na een herstart"}, "now": {"name": "Geldt meteen"}},
+  "home": {
+    "app": {"name": "Batterij-add-on"},
+    "tabs": {"home": "Start", "batteries": "Batterijen", "settings": "Instellingen", "setup": "Installatie", "label": "Schermen"},
+    "now": {"name": "Nu", "description": "Elke 3 seconden bijgewerkt.", "solar": "Zonnepanelen", "house": "Huis", "grid": "Net", "batteries": "Batterijen"},
+    "plan": {
+      "name": "Plan voor vandaag",
+      "description": "Wijs een staaf of blok aan voor details, of tik erop op een telefoon.",
+      "cheap": "Lage prijs",
+      "dear": "Hoge prijs",
+      "estimate": "Schatting",
+      "grid": "Laadt van het net",
+      "give": "Levert stroom",
+      "cycle": "Maandelijkse batterijcyclus",
+      "peak": "Piekgrens",
+      "house": "Volgt het huis",
+      "now": "nu",
+      "time_to": "tot",
+      "per_kwh": "per kWh",
+      "cheap_tip": "laag voor vandaag",
+      "dear_tip": "hoog voor vandaag",
+      "estimate_tip": "schatting op basis van gisteren",
+      "none_tip": "Geen prijs bekend",
+      "no_prices": {"description": "Geen prijzen voor vandaag, dus de grafiek toont alleen het plan."},
+      "list": "Het plan in woorden",
+      "average_tip": "gemiddelde van het uur"
+    },
+    "peak": {"name": "Piekgrens", "this_month": "Piek van deze maand", "limit": "Grens", "none": "Nog niets gemeten", "unreadable": "Nu niet leesbaar"},
+    "attention": {"name": "Vraagt aandacht", "nothing": "Niets om na te kijken", "to_look": "na te kijken", "details": "Details", "alarm": "Alarm", "warning": "Waarschuwing", "info": "Info"},
+    "control": {"name": "Regeling", "stop": "Regeling stoppen", "start": "Regeling starten", "maint_start": "Nu een batterijcyclus starten", "maint_abort": "Batterijcyclus stoppen", "docs": "Documentatie van de add-on", "more": "Meer acties"},
+    "details": {"name": "Details voor installateurs", "rows": "Statusregels", "checks": "Controles", "event": "Laatste gebeurtenis"},
+    "dialog": {
+      "cancel": "Annuleren",
+      "stop": {"name": "Regeling stoppen?", "description": "Elke omvormer gaat naar 0 W tot u de regeling opnieuw start.", "yes": "Regeling stoppen"},
+      "start": {"name": "Regeling starten?", "description": "De add-on regelt de batterijen weer en heft een veiligheidsstop op.", "yes": "Regeling starten"},
+      "maint_start": {"name": "Batterijcyclus starten?", "description": "De batterij loopt leeg, laadt weer op en blijft vol, wat enkele uren duurt.", "yes": "Cyclus starten"},
+      "maint_abort": {"name": "Batterijcyclus stoppen?", "description": "Elke omvormer gaat even naar 0 W, daarna gaat de regeling verder.", "yes": "Cyclus stoppen"}
+    },
+    "toast": {"started": "Regeling gestart.", "stopped": "Regeling gestopt.", "done": "Klaar.", "failed": "Dat lukte niet. Probeer opnieuw."},
+    "offline": {"name": "Add-on niet bereikbaar", "description": "De pagina probeert het elke 3 seconden opnieuw."},
+    "setup_only": {"name": "Installatie: nog niets wordt geregeld", "description": "Er gaat niets naar een omvormer tot de installatie bewaard is en de add-on herstart.", "control": "De regeling start na de installatie.", "open": "Installatie openen"},
+    "batteries": {"name": "Batterijen", "description": "Zet batterijmodi aan in de instellingen om per batterij een modus te kiezen.", "level": "Laadniveau", "now": "Nu", "stored": "Opgeslagen", "mode": "Modus", "settings": "Instellingen van omvormers wijzigen",
+      "on": "Aan", "off": "Uit",
+      "choice": {
+        "solar_first": {"name": "Eerst zonne-energie", "description": "Laadt met zonne-energie vóór de andere batterijen en dekt het huis."},
+        "leftover_solar": {"name": "Overschot zonne-energie", "description": "Krijgt zonne-energie die de andere niet opnemen, en levert in dure uren."},
+        "cheap_hours": {"name": "Alleen goedkope uren", "description": "Laadt in de goedkoopste uren en levert in de dure uren."},
+        "off": {"name": "Uit", "description": "Rust, en helpt alleen als de piekgrens haar nodig heeft."}
+      },
+      "today": "Vandaag", "why": "Waarom",
+      "modes_off": {"name": "Batterijmodi staan uit"},
+      "how": {"name": "Zo werken de modi", "description": "Welke batterij eerst zonne-energie krijgt, en wanneer elke batterij levert.",
+        "solar_first": {"description": "Eerst zonne-energie krijgt het overschot vóór de andere batterijen, en dekt het huis op elk uur."},
+        "leftover_solar": {"description": "Overschot zonne-energie krijgt wat de batterijen met Eerst zonne-energie niet opnemen, en spaart haar stroom voor dure uren."},
+        "cheap_hours": {"description": "Alleen goedkope uren laadt in de goedkoopste uren en levert in de dure uren."},
+        "off": {"description": "Uit laat de batterij rusten en start geen maandelijkse cyclus, maar de piekgrens mag haar nog gebruiken."},
+        "rules": {"description": "De piekgrens en de veiligheidsstops gaan voor, en terwijl een batterij van het net laadt rusten de andere."}},
+      "toast": {"on": "{name} staat aan.", "off": "{name} staat uit.", "mode": "{name}: {mode}."}},
+    "settings": {"name": "Instellingen", "description": "De instellingen staan hieronder per taak.", "open": "Instellingen openen"}
+  },
+  "choices_later": {"region": {"wallonia": "Wallonië, nog geen standaardwaarde", "brussels": "Brussel, nog geen standaardwaarde"}},
+  "choice_help": {
+    "meter_source": {
+      "off": {"description": "Een Home Assistant-entiteit met het netvermogen in W, positief als u van het net afneemt."},
+      "ha_dsmr": {"description": "Twee Home Assistant-entiteiten van de DSMR-integratie, een voor afname en een voor injectie."},
+      "mqtt_p1": {"description": "De meetwaarden komen via MQTT binnen op een topic dat u opgeeft."},
+      "ha_signed": {"description": "Eén Home Assistant-entiteit met het nettovermogen, positief bij afname."},
+      "homewizard_local": {"description": "De add-on leest een HomeWizard-meter op uw netwerk en merkt een vastgelopen meter op."}
+    }
+  },
+  "settings": {
+    "name": "Instellingen",
+    "description": "Elke instelling, per taak.",
+    "view": {"name": "Weergave van de instellingen", "simple": "Eenvoudig", "installer": "Installateur"},
+    "simple": {"description": "De keuzes die een eigenaar maakt.",
+      "note": {"month_peak": {"description": "De piek van deze maand tot nu: {kw}."}, "shadow": {"description": "Kies Altijd aan terwijl u een nieuwe installatie test."}, "forecast": {"description": "Met een prognose koopt een batterij alleen wat de zon niet geeft."}},
+      "batteries": {"name": "Batterijen"},
+      "more": {"description": "Zoekt u de meter, de omvormers of de prijzen?"},
+      "installer": "De installateursweergave openen"},
+    "classic": "Klassieke instellingen",
+    "search": {"name": "Instelling zoeken", "description": "Zoek een instelling, bijvoorbeeld piek of meter."},
+    "no_match": {"description": "Geen instelling past bij uw zoekopdracht."},
+    "loading": "Instellingen laden",
+    "load_failed": {"name": "Instellingen niet leesbaar", "description": "De add-on kon zijn bewaarde instellingen niet lezen, dus gebruik Klassieke instellingen of het tabblad Configuratie."},
+    "footer": {"description": "Elke wijziging gaat door de startcontroles van de add-on voor ze bewaard wordt."},
+    "to_fix": "op te lossen",
+    "to_check": "na te kijken",
+    "changed": "gewijzigd",
+    "on": "Aan",
+    "off": "Uit",
+    "not_set": "Niet ingesteld",
+    "locked": "Vergrendeld",
+    "change": "Wijzigen",
+    "support": {"description": "Deze zijn gemeten op echte hardware, dus wijzig ze alleen als support erom vraagt."},
+    "picker": {"choose": "Kies een entiteit", "search": {"description": "Zoek op naam of entiteit-id."}, "all": "Alle entiteiten tonen", "use": "Deze entiteit-id gebruiken", "clear": "Wissen", "missing": "Niet in Home Assistant", "none": {"description": "Niets gevonden, dus kijk de entiteit na in Ontwikkelhulpmiddelen."}},
+    "add_inverter": "Omvormer toevoegen",
+    "inverter": "Omvormer",
+    "remove": "Verwijderen",
+    "add_row": "Regel toevoegen",
+    "add_solar": "Zonne-omvormer toevoegen",
+    "periods": {"window": "Tijdvak", "from": "Van", "to": "Tot", "days": "Dagen", "price": "Prijs", "add": "Tijdvak toevoegen"},
+    "reversed": "Meet negatief",
+    "phase": "Fase",
+    "raw_roster": {"description": "Deze lijst met omvormers kan alleen op het tabblad Configuratie gewijzigd worden."},
+    "region_year": "cijfers van {year}",
+    "hour": "{hour}:00 UTC",
+    "preset": {"description": "Ingevuld door de regio hierboven, dus kies een eigen bedrag om het te wijzigen."},
+    "cycle": {"name": "Een cyclus met de hand starten", "description": "Dezelfde acties als op Start, die elk eerst om bevestiging vragen."},
+    "savebar": {"label": "Niet bewaarde wijzigingen", "one": "wijziging niet bewaard", "many": "wijzigingen niet bewaard", "discard": "Verwerpen", "save": "Bewaren", "saving": "Bezig met bewaren"},
+    "saved": {"name": "Bewaard, nog niet actief", "description": "De add-on werkt met de instellingen waarmee hij startte tot u hem herstart."},
+    "differs": {"name": "Bewaarde instellingen zijn niet actief", "description": "Sommige bewaarde instellingen verschillen van wat nu draait, dus herstart de add-on om ze toe te passen."},
+    "stale": {"name": "Elders gewijzigd", "description": "Deze instellingen zijn elders gewijzigd terwijl u bewerkte, dus bewaar opnieuw om de uwe te houden of verwerp om de andere te laden."},
+    "other": "Andere meldingen",
+    "restart": "Nu herstarten",
+    "dialog": {"name": "Add-on herstarten?", "description": "Elke omvormer gaat naar 0 W terwijl de add-on herstart, daarna gelden de nieuwe instellingen.", "yes": "Nu herstarten"},
+    "toast": {"saved": "Bewaard. Herstart om toe te passen.", "discarded": "Wijzigingen verworpen.", "failed": "Dat lukte niet. Probeer opnieuw.", "blocked": {"description": "Los de rood gemarkeerde instellingen op en bewaar opnieuw."}, "restarting": {"description": "Herstart gevraagd, dus deze pagina antwoordt even niet."}},
+    "tier": {"bad": "Oplossen", "warn": "Nakijken", "info": "Opmerking", "ok": "In orde"},
+    "derive": {
+      "raw_roster": {"description": "Deze lijst met omvormers kan alleen op het tabblad Configuratie gewijzigd worden."},
+      "no_inverter": {"description": "Voeg minstens één omvormer toe."},
+      "flat_named": {"description": "Voeg een tweede omvormer toe voor u deze een naam geeft."},
+      "no_source": {"description": "Kies waar de dynamische prijzen vandaan komen."},
+      "custom_profile": {"description": "Deze tijdvakken kunnen alleen op het tabblad Configuratie gewijzigd worden."},
+      "no_price": {"description": "Vul een prijs per kWh in."},
+      "no_periods": {"description": "Voeg minstens één tijdvak toe."},
+      "period_time": {"description": "Tijdvak {row}: schrijf elk tijdstip als uren en minuten, zoals 07:00 of 24:00."},
+      "period_zero": {"description": "Tijdvak {row} begint en eindigt op hetzelfde uur, dus wijzig een van beide."},
+      "period_price": {"description": "Tijdvak {row}: vul een prijs per kWh in."},
+      "period_price_range": {"description": "Tijdvak {row}: vul de prijs in euro per kWh in, zoals 0,34."},
+      "period_overlap": {"description": "Tijdvakken {a} en {b} vallen allebei op {day} {from} tot {to}, dus wijzig er een."},
+      "period_gap": {"description": "Geen tijdvak dekt {day} {from} tot {to}, dus voeg er een toe of maak er een breder."},
+      "unknown": {"description": "De pagina kan deze keuze niet bewaren, dus laad de pagina opnieuw."}
+    },
+    "setup": {
+      "name": "Installatie",
+      "description": "Voor installateurs: zes stappen naar een werkende installatie, en elke stap kan later gewijzigd worden onder Instellingen.",
+      "done_before": {"description": "Deze installatie is al ingesteld, dus een wijziging hier vervangt de bewaarde instellingen."},
+      "step": "Stap {n} van {total}",
+      "back": "Terug",
+      "next": "Volgende",
+      "skip": "Volgende, of overslaan",
+      "finish": "Bewaren en herstarten",
+      "not_now": "Niet nu",
+      "steps": {
+        "1": {"name": "Uw meter", "description": "De add-on stuurt de netmeting naar nul, dus eerst is uw meter nodig."},
+        "2": {"name": "Omvormers en batterijen", "description": "Eén kaart per omvormer met een batterij, met zijn entiteiten in Home Assistant."},
+        "3": {"name": "Zonnepanelen", "description": "Niet verplicht, dus sla deze stap over als de add-on de zonneproductie niet moet bijhouden."},
+        "4": {"name": "Prijzen", "description": "Wat u per kWh betaalt, zodat de batterijen laden als stroom goedkoop is."},
+        "5": {"name": "Piekgrens", "description": "Het net blijft onder deze grens, gemiddeld over elk kwartier."},
+        "6": {"name": "Nakijken en starten", "description": "De add-on kijkt alles na met zijn eigen startcontroles en herstart dan."}
+      },
+      "modes_later": {"description": "Zet na de installatie batterijmodi aan om per batterij een modus te kiezen op het scherm Batterijen."},
+      "kettle": {
+        "name": "Richting nakijken",
+        "description": "Lees de meter af, zet een waterkoker aan en lees de meter opnieuw af.",
+        "read": "Meter aflezen",
+        "again": "Opnieuw aflezen",
+        "skip": "Deze test overslaan",
+        "before": {"description": "De meter geeft nu {w} aan, dus zet een waterkoker aan en druk op Opnieuw aflezen."},
+        "unread": {"description": "De meter is nu niet leesbaar, dus kijk de entiteit na en probeer opnieuw."},
+        "none": {"description": "De meting veranderde maar {d}, dus zet de waterkoker aan en lees opnieuw af."},
+        "ok": {"description": "Goed, de meting steeg met {d} toen de waterkoker aanging."},
+        "flip": {"description": "De meting daalde met {d}, dus de add-on keert het teken voor u om."},
+        "wrong_signed": {"description": "De meting daalde met {d}, dus kies hierboven “Eén entiteit voor netvermogen”, die het kan omkeren."},
+        "wrong_dsmr": {"description": "De meting daalde met {d}, dus kijk na of afname en injectie niet omgewisseld zijn."},
+        "self": {"description": "De add-on leest deze meter zelf, dus Start toont de richting na de herstart."},
+        "skipped": {"description": "De richting van de meter is niet getest, dus kijk ze na op Start na de herstart."},
+        "skipped_wrong": {"description": "Bij de waterkokertest daalde de meting, dus kijk de richting na in stap 1 voor u de regeling start."},
+        "skipped_down": {"description": "De meting daalde toen de waterkoker aanging, dus kijk de richting van de meter na voor u de regeling start."},
+        "tested": {"description": "De richting van de meter is getest met een waterkoker."},
+        "needed": {"description": "Doe eerst de waterkokertest, of sla hem over."}
+      },
+      "check": {"name": "Wat de add-on nakeek", "running": {"description": "Bezig met de startcontroles van de add-on."}, "pass": {"description": "De startcontroles van de add-on zijn in orde."}, "failed": {"description": "De controle liep niet, dus probeer opnieuw."}, "again": "Opnieuw nakijken", "blocked": {"description": "Los de rood gemarkeerde punten op en kijk dan opnieuw na."}},
+      "dialog": {"name": "Bewaren en herstarten?", "description": "Elke omvormer gaat naar 0 W terwijl de add-on herstart, en de schaduwmodus houdt ze daarna op 0 W.", "yes": "Bewaren en herstarten"},
+      "dialog_live": {"name": "Bewaren en herstarten?", "description": "Elke omvormer gaat naar 0 W terwijl de add-on herstart, daarna gelden de nieuwe instellingen.", "yes": "Bewaren en herstarten"},
+      "dialog_setup": {"name": "Bewaren en herstarten?", "description": "De add-on herstart met deze instellingen, en de schaduwmodus houdt elke omvormer op 0 W.", "yes": "Bewaren en herstarten"},
+      "dialog_setup_live": {"name": "Bewaren en herstarten?", "description": "De add-on herstart met deze instellingen, en dan gelden ze.", "yes": "Bewaren en herstarten"},
+      "done": {"name": "Installatie is klaar", "description": "De add-on herstart nu in schaduwmodus, dus open Start over een minuut om te zien wat hij zou doen."},
+      "done_live": {"name": "Installatie is klaar", "description": "De add-on herstart nu, dus open Start over een minuut om de regeling te starten."},
+      "restart_failed": {"name": "Bewaard, nog niet actief", "description": "De herstart lukte niet, dus druk op Nu herstarten om de instellingen toe te passen."},
+      "home": "Start openen"
+    }
+  },
+  "home_words": {
+    "mode_house": "Volgt het huis",
+    "modes": {"solar_first": "Eerst zonne-energie", "leftover_solar": "Overschot zonne-energie", "cheap_hours": "Alleen goedkope uren", "off": "Uit"},
+    "attn_shadow": "Schaduwmodus staat aan",
+    "attn_shadow_body": "De add-on beslist alles, maar elke omvormer blijft op 0 W.",
+    "zero_held": "Op 0 W gehouden",
+    "zero_going": "Gaat naar 0 W",
+    "verdict": {"held": "Op 0 W gehouden", "stopped": "Gestopt", "cycle": "Vandaag maandelijkse cyclus", "trade": "Handelt op prijs", "house": "Volgt het huis"},
+    "pill": {"running": "Actief", "shadow": "Schaduwmodus", "stopped": "Gestopt", "alarm": "Heeft u nu nodig", "warning": "Actief, met een waarschuwing"},
+    "banner_sub": {"running": "De batterijen volgen het plan hieronder.", "shadow": "De plannen hieronder tonen wat de add-on zou doen.", "stopped": "Start de regeling hieronder als u klaar bent.", "alarm": "Zie Vraagt aandacht hieronder voor wat u moet doen.", "warning": "Zie Vraagt aandacht hieronder."},
+    "tile": {"not_set_up": "Niet ingesteld", "no_reading": "Geen meting", "producing": "Produceert", "not_producing": "Produceert niet", "needs_solar": "Zonnemeting nodig", "not_adding_up": "Metingen kloppen niet", "using": "Verbruikt", "taking": "Neemt af van het net", "feeding": "Injecteert", "balanced": "In evenwicht", "giving": "Levert stroom", "charging": "Laadt", "resting": "Rust"},
+    "now": {
+      "no_reading": "Geen meting van deze batterij.",
+      "would_rest": "{zero}. Zou nu rusten.",
+      "would_give": "{zero}. Zou nu {kw} leveren.",
+      "would_charge": "{zero}. Zou nu {kw} laden.",
+      "held": "{zero} tot het alarm weg is.",
+      "stopped": "{zero} zolang de regeling gestopt is.",
+      "cycle_drain": "Maandelijkse cyclus: leegmaken.",
+      "cycle_charge": "Maandelijkse cyclus: opladen.",
+      "cycle_hold": "Maandelijkse cyclus: vol houden.",
+      "cycle": "Maandelijkse cyclus bezig.",
+      "giving": "Levert nu {kw}.",
+      "charging": "Laadt nu {kw}.",
+      "resting": "Rust nu.",
+      "off_resting": "Uit. Rust nu.",
+      "off_peak": "Uit, maar levert {kw} voor de piekgrens.",
+      "off_going": "Uit. Nog {kw}, gaat naar 0 W."
+    },
+    "why": {
+      "no_reading": "Geen meting, dus de add-on weet het niet.",
+      "held": "Een alarm stopte de regeling. Zie Vraagt aandacht.",
+      "stopped": "De regeling is gestopt.",
+      "shadow": "Schaduwmodus: de add-on toont alleen wat hij zou doen.",
+      "cycle": "De maandelijkse cyclus houdt de meting van het laadniveau juist.",
+      "cycle_mode": "De maandelijkse cyclus gaat voor. Daarna volgt ze weer haar modus.",
+      "off": "U hebt haar uitgezet.",
+      "off_peak": "De piekgrens gaat voor op Uit. Daarna rust ze weer.",
+      "refuses_give": "De batterij weigert te leveren. De add-on probeert het elke 15 minuten opnieuw.",
+      "refuses_charge": "De batterij weigert te laden. De add-on probeert het elke 15 minuten opnieuw.",
+      "peak": "De piekgrens vraagt vermogen van de batterijen.",
+      "modes_off": "Batterijmodi staan uit, dus ze volgt het huis.",
+      "solar_first": "Eerst zonne-energie: ze krijgt het overschot vóór de andere.",
+      "leftover": "Ze krijgt de zonne-energie die de batterijen met Eerst zonne-energie niet opnemen.",
+      "leftover_alone": "Geen batterij met Eerst zonne-energie staat aan, dus zij krijgt eerst zonne-energie.",
+      "covers_house": "Ze levert stroom om het huis te dekken.",
+      "other_refuses": "{name} weigert te leveren, dus deze batterij neemt het over.",
+      "other_cycle": "{name} loopt leeg voor haar maandelijkse cyclus. Deze laadt niet.",
+      "grid_charge": "De prijs is laag, dus ze laadt van het net.",
+      "rests_charge": "Een andere batterij laadt van het net, dus deze rust.",
+      "selling": "De prijs is hoog, dus ze verkoopt aan het net.",
+      "expensive": "De prijs is hoog, dus ze dekt het huis.",
+      "saves": "Spaart haar stroom voor {at}.",
+      "saves_later": "Spaart haar stroom voor hogere prijzen.",
+      "no_prices": "Geen prijzen, dus ze volgt het huis.",
+      "no_spread": "De prijzen verschillen te weinig, dus ze volgt het huis.",
+      "sun_fills": "Er is genoeg zon voorspeld, dus ze laadt niet van het net.",
+      "tops_up": "Te weinig zon voorspeld, dus ze laadt wat van het net.",
+      "no_forecast": "Geen zonneprognose, dus ze laadt alleen met zonne-energie."
+    },
+    "solar": {"line": "Nog verwachte zon vandaag: {kwh}, we rekenen op {count}. Bijgewerkt om {at}.", "no_forecast": "Nu geen zonneprognose, dus Overschot zonne-energie laadt alleen met zon.", "learning": "De add-on leert eerst het verbruik van uw huis. Het plan start na één volle dag."},
+    "today": {
+      "not_planned": "Nog niet gepland.",
+      "no_runs": "Vandaag geen goedkope of dure uren meer.",
+      "off": "Uit, dus vandaag geen maandelijkse cyclus.",
+      "house": "Volgt het huis.",
+      "house_would": "Zou het huis volgen.",
+      "stopped": "Niets gepland zolang de regeling gestopt is.",
+      "held": "Niets gepland tot het alarm weg is."
+    },
+    "head": {
+      "held": "Elke omvormer staat op 0 W tot het alarm weg is.",
+      "held_going": "Elke omvormer gaat naar 0 W tot het alarm weg is.",
+      "stopped": "De regeling is gestopt, dus er is niets gepland.",
+      "cycle": "Een batterij doet vandaag zijn maandelijkse cyclus.",
+      "trade": "Laadt in het goedkoopste uur, levert stroom in het duurste.",
+      "house": "Laadt met zonne-overschot en dekt het huis.",
+      "shadow": "Schaduwmodus: dit is wat de add-on zou doen.",
+      "cycle_would": "Een batterij zou vandaag zijn maandelijkse cyclus doen.",
+      "trade_would": "Zou laden als het goedkoopst is en leveren als het duurst is.",
+      "house_would": "Zou laden met zonne-overschot en het huis dekken."
+    },
+    "run": {
+      "grid_what": "Laadt tot {kwh} van het net.",
+      "grid_what_would": "Zou tot {kwh} van het net laden.",
+      "grid_why": "Laagste gepubliceerde prijs, {eur} per kWh.",
+      "grid_amount": "Kost tot {eur}.",
+      "give_what": "Levert tot {kwh}, eerst aan het huis.",
+      "give_what_would": "Zou tot {kwh} leveren, eerst aan het huis.",
+      "give_why": "Hoogste gepubliceerde prijs, {eur} per kWh.",
+      "sell_what": "Verkoopt tot {kwh}, eerst aan het huis.",
+      "sell_what_would": "Zou tot {kwh} verkopen, eerst aan het huis.",
+      "cheap_why": "Goedkoopste uren, ongeveer {eur} per kWh.",
+      "dear_why": "Dure uren, ongeveer {eur} per kWh.",
+      "give_amount": "Tot {eur} waard aan die prijs.",
+      "cycle_start": "Start de maandelijkse batterijcyclus.",
+      "cycle_start_would": "Zou de maandelijkse batterijcyclus starten.",
+      "cycle_now": "Doet nu de maandelijkse batterijcyclus.",
+      "cycle_now_would": "Zou nu de maandelijkse batterijcyclus doen.",
+      "cycle_why": "Maakt leeg, laadt op en houdt vol, zodat het laadniveau klopt.",
+      "cycle_why_would": "Zou leegmaken, opladen en vol houden, zodat het laadniveau klopt.",
+      "cycle_amount_unknown": "Hoe lang hangt af van de batterij.",
+      "cycle_amount": "Duurt ongeveer {hours} uur.",
+      "peak_what": "Levert stroom om onder {kw} te blijven.",
+      "peak_what_would": "Zou stroom leveren om onder {kw} te blijven.",
+      "peak_why": "De piekgrens gaat voor alles.",
+      "house_what": "Volgt het huis.",
+      "house_what_would": "Zou het huis volgen.",
+      "house_why": "Laadt met zonne-overschot, levert als het huis vraagt.",
+      "house_why_would": "Zou laden met zonne-overschot, leveren als het huis vraagt.",
+      "house_amount": "Hoeveel hangt af van de zon en het huis."
+    },
+    "no_trade": {
+      "not_covered": "Geen handel op prijs: niets meet de kwartierpiek.",
+      "no_prices": "Nog geen handel op prijs: er zijn geen prijzen binnen.",
+      "peak": "Nu geen handel op prijs: de piekgrens gaat voor.",
+      "not_firm": "Nog geen handel op prijs: de prijzen zijn niet gepubliceerd.",
+      "not_worth": "Vandaag geen handel op prijs. Het prijsverschil is te klein.",
+      "no_level": "Nu geen handel op prijs: een laadniveau is onbekend."
+    },
+    "tomorrow_trade": {"grid": "Morgen: laadt om {at}, {eur} per kWh.", "grid_would": "Morgen: zou laden om {at}, {eur} per kWh.", "give": "Morgen: levert stroom om {at}, {eur} per kWh.", "give_would": "Morgen: zou stroom leveren om {at}, {eur} per kWh."},
+    "cycle_waits": "{name} wacht zijn beurt af voor de maandelijkse cyclus.",
+    "step_in": "De batterijen springen bij boven {kw}.",
+    "step_in_would": "De batterijen zouden bijspringen boven {kw}.",
+    "period": "Dit kwartier gaat richting {kw}.",
+    "prices": {"now": "Prijs nu {eur} per kWh, alles inbegrepen.", "today": "Vandaag: laagste {lo} om {lo_at}, hoogste {hi} om {hi_at}.", "none": "Geen prijzen voor vandaag."},
+    "tomorrow": {"known": "De prijzen van morgen zijn binnen.", "unknown": "De prijzen van morgen komen meestal na 13:00."},
+    "region": {"preset": "Heffingen en btw: {region}, cijfers van {year}.", "own": "Heffingen en btw: uw eigen bedrag."},
+    "peak_not_covered": "Geen piekgrens: deze meter meet geen kwartieren.",
+    "control": {"shadow": "Schaduwmodus: elke omvormer blijft op 0 W.", "running": "De regeling is actief.", "stopped": "De regeling is gestopt. Elke omvormer staat op 0 W."},
+    "attn": {
+      "controller": "Regeling is niet actief",
+      "meter": "Meting van de meter",
+      "meter_frozen": "Meter staat mogelijk vast",
+      "freeze_check": "Controle op vastgelopen meter",
+      "month_peak": "Piek van deze maand",
+      "peak_guard": "Piekgrens",
+      "peak_forecast": "Prognose voor de piekgrens",
+      "sensor": "Metingen van de batterij",
+      "control": "Regeling van de omvormer",
+      "power_too_high": "Vermogensvraag te hoog",
+      "not_keeping_up": "Batterij kan niet volgen",
+      "write": "Vermogensvraag niet aanvaard",
+      "direction": "Vermogen de verkeerde kant op",
+      "site_direction": "Vermogen de verkeerde kant op",
+      "circulating": "Omvormers werken elkaar tegen",
+      "delivery": "Een omvormer levert niet",
+      "estop": "Noodstop",
+      "pv": "Meting van de zonnepanelen",
+      "none": "Verbinding met de omvormer"
+    },
+    "months": ["januari", "februari", "maart", "april", "mei", "juni", "juli", "augustus", "september", "oktober", "november", "december"]
+  }
+}

goodwe_controller/app/uilayout.py

@@ -0,0 +1,347 @@
+"""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")
+PERIOD_LIST = "period_list"     # P5: time windows, each with its own price
+CONTROLS = (CHOICE, ENTITY, ENTITY_LIST, TOGGLE, SEGMENTED, SLIDER, NUMBER,
+            TEXT, SELECT, LOCKED, INVERTER_LIST, SOLAR_LIST, PERIOD_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)
+    note: str = ""              # P3: a line under it on Settings, Simple
+
+    @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),)),
+        # OPT-11: the switch that turns battery modes on. Each battery's mode
+        # and on/off switch are runtime state on the Batteries screen.
+        Part("modes", (
+            Field("battery_modes_enabled", TOGGLE),
+            # OPT-11 P4: the solar forecast; today's also on Settings, Simple.
+            Field("pv_forecast_entity", ENTITY, kind="energy", simple=True,
+                  note="forecast"),
+            Field("pv_forecast_tomorrow_entity", ENTITY, kind="energy"),
+            Field("solar_trust_pct", SLIDER, "%", step=5),
+        )),
+    )),
+    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),
+            Field("ui.periods", PERIOD_LIST, "€/kWh", step=0.01,
+                  show=(("ui.fallback", "==", "custom"),), 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, note="month_peak"),
+            Field("peak_margin_w", SLIDER, "W", step=10),   # SAFETY-79
+            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,
+                  note="shadow"),
+            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),
+)
+
+# --------------------------------------------------------------------------- #
+# UX-13 P4: the setup wizard. Its fields are the ones with `wizard=` above; this
+# is what the table cannot say per field (DECISIONS/UX-13-setup-wizard.md).
+# --------------------------------------------------------------------------- #
+WIZARD_STEPS = 6
+FINAL_STEP = WIZARD_STEPS       # a refusal on no wizard field is shown here
+OPTIONAL_STEPS = (3,)           # solar: "Next, or skip"
+
+# Step 1's kettle test. Per meter source Home Assistant reads: the page fields
+# read before and after a kettle is switched on, each with the sign it adds to
+# the grid reading, and what each direction means as (outcome, fields it
+# sets). Sets None: the options cannot fix it, so the step is not passed. A
+# source not listed is read by the add-on itself, so the page cannot test it.
+KETTLE_SOURCE = "meter_source"
+KETTLE_MIN_W = 500.0            # a kettle is 2 000 W, a house wobbles less
+KETTLE = {
+    "off": ((("meter_entity", 1),),
+            {"up": ("ok", {"meter_invert": False}),
+             "down": ("flip", {"meter_invert": True})}),
+    "ha_signed": ((("p1_net_entity", 1),),
+                  {"up": ("ok", {}), "down": ("wrong_signed", None)}),
+    "ha_dsmr": ((("p1_import_entity", 1), ("p1_export_entity", -1)),
+                {"up": ("ok", {}), "down": ("wrong_dsmr", None)}),
+}
+# Step 6 starts the site in shadow mode unless the installer switches it off:
+# (field, value when on, value when off).
+SHADOW = ("shadow_mode", "on", "auto")
+
+# 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,488 @@
+"""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 or time windows (P5) 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
+import re
+
+from .price import FLEMISH_TAXES_COMPONENTS_EUR_KWH, MAX_PLAUSIBLE_EUR_KWH
+from .static_tariff import (DAY_NAMES, MINUTES_PER_DAY, Period, ProfileInvalid,
+                            parse_static_profile)
+
+__all__ = ["options_to_ui", "ui_to_options", "ui_to_options_partial",
+           "REGION_PRESETS", "PERIOD_DAYS",
+           "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="", **values):
+        super().__init__(text)
+        self.code, self.field = code, field
+        self.values = values    # the sentence's {placeholders} (P5)
+        self.keys = ()          # the option keys the failed derivation writes
+
+
+# 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
+
+
+# --- 3b. the time-window editor (UX-13 P5) ---------------------------------- #
+# Each row is {"from", "to", "days", "price"} and, when read from a stored
+# profile, its "name". `days` is one of these; a profile with any other day set
+# is edited in the Configuration tab only (`ui.periods` is None).
+PERIOD_DAYS = ("mon-sun", "mon-fri", "sat,sun") + DAY_NAMES
+_DAYSETS = {d: frozenset(range(7)) if d == "mon-sun" else
+            frozenset(range(5)) if d == "mon-fri" else
+            frozenset((5, 6)) if d == "sat,sun" else
+            frozenset((DAY_NAMES.index(d),)) for d in PERIOD_DAYS}
+_TIME = re.compile(r"^\s*(\d{1,2}):(\d{2})\s*$")
+
+
+def _hhmm(minute) -> str:
+    return f"{minute // 60:02d}:{minute % 60:02d}"
+
+
+def _periods_decode(raw):
+    """The rows for a stored profile: [] when unset, None when it cannot be
+    shown as rows (unparsable, or days the editor has no choice for)."""
+    try:
+        prof = parse_static_profile(raw) if isinstance(raw, str) else None
+    except ProfileInvalid:
+        return None
+    if prof is None:
+        return [] if isinstance(raw, str) else None
+    rows = []
+    for p in prof.periods:
+        days = next((d for d, s in _DAYSETS.items() if s == p.days), None)
+        if days is None:
+            return None
+        rows.append({"from": _hhmm(p.start_min), "to": _hhmm(p.end_min),
+                     "days": days, "price": p.eur_per_kwh, "name": p.name})
+    return rows
+
+
+def _minute(text, *, end):
+    """"07:00" -> 420, "24:00" -> 1440 as an end, else None."""
+    m = _TIME.match(str(text or ""))
+    if not m:
+        return None
+    h, mi = int(m.group(1)), int(m.group(2))
+    if mi > 59 or h > 24 or (h == 24 and (mi or not end)):
+        return None
+    return h * 60 + mi
+
+
+def _periods_json(rows) -> str:
+    """The static_profile for the editor's rows, or DeriveError naming the
+    first problem: a bad time, an empty price, an overlap or a gap."""
+    if not rows:
+        raise DeriveError("add at least one time window", "no_periods",
+                          "ui.periods")
+    periods = []
+    for i, row in enumerate(rows, start=1):
+        row = row if isinstance(row, dict) else {}
+        start = _minute(row.get("from"), end=False)
+        end = _minute(row.get("to"), end=True)
+        if start is None or end is None:
+            raise DeriveError(f"window {i} has a bad time", "period_time",
+                              "ui.periods", row=i)
+        end = end or MINUTES_PER_DAY            # "00:00" as an end
+        if start == end:
+            raise DeriveError(f"window {i} is empty", "period_zero",
+                              "ui.periods", row=i)
+        price = _num(row.get("price"))
+        if price is None:
+            raise DeriveError(f"window {i} needs a price", "period_price",
+                              "ui.periods", row=i)
+        if abs(price) > MAX_PLAUSIBLE_EUR_KWH:
+            raise DeriveError(f"window {i}'s price is out of range",
+                              "period_price_range", "ui.periods", row=i)
+        if row.get("days") not in _DAYSETS:
+            raise DeriveError(f"window {i} has no days", "unknown",
+                              "ui.periods")
+        name = str(row.get("name") or "").strip() or f"window{i}"
+        periods.append(Period(name=name, start_min=start, end_min=end,
+                              days=_DAYSETS[row["days"]],
+                              eur_per_kwh=price))
+    _tiling(periods)
+    return json.dumps({"periods": [
+        {"name": p.name, "from": _hhmm(p.start_min),
+         "to": _hhmm(p.end_min), "days": row["days"],
+         "eur_per_kwh": p.eur_per_kwh}
+        for p, row in zip(periods, rows)]})
+
+
+def _tiling(periods):
+    """Each minute of the week in exactly one window, as static_tariff.py
+    requires. The first overlap or gap, by day and time, is the error."""
+    for day in range(7):
+        start, kind, rows = None, None, None
+        for minute in range(MINUTES_PER_DAY + 1):
+            here = [i for i, p in enumerate(periods, start=1)
+                    if minute < MINUTES_PER_DAY and p.covers(day, minute)]
+            now = ("gap" if not here else "overlap" if len(here) > 1
+                   else None) if minute < MINUTES_PER_DAY else "end"
+            if kind is not None and (now != kind or (kind == "overlap"
+                                                     and here != rows)):
+                values = {"day": DAY_NAMES[day], "from": _hhmm(start),
+                          "to": _hhmm(minute)}
+                if kind == "gap":
+                    raise DeriveError("a time has no window", "period_gap",
+                                      "ui.periods", **values)
+                raise DeriveError("two windows cover one time",
+                                  "period_overlap", "ui.periods",
+                                  a=rows[0], b=rows[1], **values)
+            if now in ("gap", "overlap") and kind is None:
+                start, kind, rows = minute, now, here
+
+
+def _tariff_decode(o):
+    raw = o.get("static_profile", "")
+    kind, fixed, day, night = _profile_decode(raw)
+    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, "ui.periods": _periods_decode(raw)}
+
+
+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":
+        rows = m.get("ui.periods")
+        if rows is not None:
+            out["static_profile"] = _periods_json(rows)
+        elif "static_profile" not in keep:
+            raise DeriveError("odd tariff windows are edited in the "
+                              "Configuration tab", "custom_profile",
+                              "ui.contract")
+        else:
+            # Days the editor cannot show: kept as stored.
+            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."""
+    out, errors = ui_to_options_partial(model)
+    if errors:
+        raise errors[0]
+    return out
+
+
+def ui_to_options_partial(model: dict):
+    """(blob, [DeriveError]): every derivation that can be made, and the
+    stored values (`keep`) for each one that cannot. For the checks only, so a
+    step can be blocked by its own field and the rest still checked (UX-15
+    F1). Never saved: `ui_to_options()` raises instead."""
+    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.")}
+    errors = []
+    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})
+            continue
+        try:
+            out.update(encode(model, keep))
+        except DeriveError as err:
+            err.keys = keys
+            errors.append(err)
+            out.update({k: copy.deepcopy(keep[k]) for k in keys if k in keep})
+    return out, errors

goodwe_controller/app/uipage.py

@@ -0,0 +1,403 @@
+"""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 os
+import re
+
+from . import uilayout as L
+from . import uitext
+from . import uimodel as U
+from .configui import help_of, label_of, problems_by_field, split_group
+from .validate import power_request_entities
+
+# A choice the page cannot make, only keep. None since P5's period editor.
+ONLY_IF_HELD = ()
+_TIERS = ("bad", "warn", "info")
+
+
+def ui_text(lang="en") -> dict:
+    """The page words in `lang`, English where Dutch has no key (P5)."""
+    return copy.deepcopy(uitext.words(lang))
+
+
+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,
+           "wizard": fld.wizard, "simple": fld.simple, "note": fld.note,
+           "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.control == L.PERIOD_LIST:
+        # P5: the day choices of one time window, in the editor's order.
+        names = T["choices"]["period_days"]
+        out["days"] = [[d, names.get(d, d)] for d in U.PERIOD_DAYS]
+    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(lang)
+    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)."""
+    return _settle(U.ui_to_options(model), stored)
+
+
+def to_options_partial(model: dict, stored: dict | None = None):
+    """(blob, [DeriveError]) for the checks: `uimodel.ui_to_options_partial`,
+    settled like `to_options`. Never saved (UX-15 F1)."""
+    out, errors = U.ui_to_options_partial(model)
+    return _settle(out, stored), errors
+
+
+def only_edits(mine: dict, base: dict, stored: dict) -> dict:
+    """The blob to save: `stored`, with the keys whose value in `mine` (this
+    page's model) differs from `base` (the model it opened) set to `mine`'s.
+    A key this page never edited keeps what is stored now, even when another
+    surface changed it meanwhile (UX-13 P4 test, F2)."""
+    edits = {k: v for k, v in mine.items()
+             if k not in base or not _same(v, base[k])}
+    gone = {k for k in base if k not in mine}
+    out = {k: copy.deepcopy(edits.get(k, v)) for k, v in stored.items()
+           if k not in gone}
+    out.update({k: copy.deepcopy(v) for k, v in edits.items()
+                if k not in out})
+    return out
+
+
+def _settle(out: dict, stored: dict | None) -> dict:
+    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, lang="en") -> dict:
+    T = uitext.words(lang)
+    words = T["settings"]["derive"]
+    text = words.get(err.code, words["unknown"])["description"]
+    args = dict(getattr(err, "values", None) or {})
+    # A time window's day is shown by name (P5 period editor).
+    if "day" in args:
+        args["day"] = T["choices"]["period_days"].get(args["day"], args["day"])
+    return {"field": err.field or None, "card": None, "tier": "bad",
+            "text": uitext.say(text, **args)}
+
+
+def derive_messages(errors, problems, notes, model, keys, lang="en"):
+    """The page's messages when part of the model could not become options:
+    each conversion's own sentence beside its field, then the checks of the
+    rest. A refusal or note about a key the failed conversion writes is left
+    out, because it judges the stored value, not what the page shows."""
+    failed = {k for err in errors for k in err.keys}
+    by_key, unanchored = problems_by_field(problems, keys)
+    kept = [t for k, texts in by_key.items() if k not in failed
+            for t in texts] + list(unanchored)
+    kept = [p for p in problems if p in kept]
+    notes = [n for n in notes if not set(n.keys or ()) & failed]
+    return ([derive_message(err, lang) for err in errors]
+            + anchors(kept, notes, model, keys))
+
+
+# --------------------------------------------------------------------------- #
+# 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))
+
+
+# --------------------------------------------------------------------------- #
+# UX-13 P4: the setup wizard (DECISIONS/UX-13-setup-wizard.md)
+# --------------------------------------------------------------------------- #
+# Store keys (app/store.py), not options. SETUP_DONE is written when the
+# wizard saves. STARTED is the one control's Start and Stop write.
+SETUP_DONE = "setup_done"
+STARTED = "auto"
+
+
+def setup_needed(stored: dict, store_data, started, fresh=False) -> str | None:
+    """Why the page opens the wizard by itself, or None.
+
+    "no_power_request": the stored options name no inverter to control, so
+    the add-on cannot start on them. "first_start": a new install. This boot
+    found no Store file (`fresh`), the wizard never saved and control was never
+    started or stopped. `fresh` is what tells a new install from an old site
+    that was never started, e.g. one left in shadow for weeks (TEST-23).
+    `store_data` is the Store's dict (None: unknown, so no), `started` is
+    whether control is started now."""
+    if not power_request_entities(stored or {}):
+        return "no_power_request"
+    if store_data is None or not fresh:
+        return None
+    if store_data.get(SETUP_DONE) or STARTED in store_data or started:
+        return None
+    return "first_start"
+
+
+def setup_spec() -> dict:
+    """What the wizard needs beyond each field's step: read off the table."""
+    kettle = {}
+    for source, (read, outcomes) in L.KETTLE.items():
+        kettle[source] = {"read": [[f, sign] for f, sign in read]}
+        for way, (say, sets) in outcomes.items():
+            kettle[source][way] = {"say": say, "sets": sets}
+    field, on, off = L.SHADOW
+    return {"steps": L.WIZARD_STEPS, "final": L.FINAL_STEP,
+            "optional": list(L.OPTIONAL_STEPS),
+            "kettle": {"source": L.KETTLE_SOURCE, "min_w": L.KETTLE_MIN_W,
+                       "sources": kettle},
+            "shadow": {"field": field, "on": on, "off": off}}
+
+
+def kettle(source, before_w, after_w):
+    """The kettle test's verdict, as the page reaches it (settings.js
+    `kettleOutcome`): (outcome, fields it sets or None, change in W), or None
+    for a source the page cannot read."""
+    spec = L.KETTLE.get(source)
+    if spec is None:
+        return None
+    change = float(after_w) - float(before_w)
+    if abs(change) < L.KETTLE_MIN_W:
+        return "none", None, change
+    say, sets = spec[1]["up" if change > 0 else "down"]
+    return say, (dict(sets) if sets is not None else None), change
+
+
+def step_of(field_key, model) -> int:
+    """The wizard step a sentence on this page field blocks: the field's own
+    step while it is shown, else the last step, which lists everything."""
+    fld = L.field(field_key) if field_key else None
+    if fld is None or not fld.wizard or not L.visible(fld, model):
+        return L.FINAL_STEP
+    return fld.wizard
+
+
+def step_problems(messages, model) -> dict:
+    """{"1": n, ...}: how many refusals block each wizard step."""
+    out = {str(n): 0 for n in range(1, L.WIZARD_STEPS + 1)}
+    for m in messages:
+        if m.get("tier") == "bad":
+            out[str(step_of(m.get("field"), model))] += 1
+    return out

goodwe_controller/app/uitext.py

@@ -0,0 +1,51 @@
+"""UX-13 P5: the page's words, app/ui_text/<lang>.json, in English or Dutch.
+
+One file per language with the same keys. A key missing from a language falls
+back to English, key by key, the way the Supervisor's translations do.
+test_ui_text.py holds both files to STYLE.md and to each other.
+"""
+
+import copy
+import io
+import json
+import os
+
+DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "ui_text")
+LANGS = ("en", "nl")
+_CACHE: dict = {}
+
+
+def lang_of(value) -> str:
+    """"nl", "nl-BE" or "nl_NL" -> "nl"; anything else -> "en"."""
+    head = str(value or "").strip().lower().replace("_", "-").split("-")[0]
+    return head if head in LANGS else "en"
+
+
+def raw(lang: str) -> dict:
+    """One language file as written, without the English fallback."""
+    if lang not in _CACHE:
+        with io.open(os.path.join(DIR, f"{lang}.json"), encoding="utf-8") as f:
+            _CACHE[lang] = json.load(f)
+    return _CACHE[lang]
+
+
+def _merge(base, over):
+    if not (isinstance(base, dict) and isinstance(over, dict)):
+        return copy.deepcopy(over)
+    out = copy.deepcopy(base)
+    for k, v in over.items():
+        out[k] = _merge(base.get(k), v) if k in base else copy.deepcopy(v)
+    return out
+
+
+def words(lang="en") -> dict:
+    """Every word in `lang`, English where a key is missing."""
+    lang = lang_of(lang)
+    return raw("en") if lang == "en" else _merge(raw("en"), raw(lang))
+
+
+def say(template: str, **values) -> str:
+    """Fill `{name}` placeholders, as settings.js `say()` does."""
+    for k, v in values.items():
+        template = template.replace("{" + k + "}", str(v))
+    return template

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,70 @@ 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.
+UX-13 P4's setup wizard uses the same routes. The one thing it adds that is
+not options is a Store key, `setup_done`, written when the wizard's save
+succeeds, so the page stops opening the wizard by itself (uipage.setup_needed).
+UX-15's setup-only mode serves these routes from `setuponly.SetupOnly`, which
+commands nothing; there `/action` answers 409.
+OPT-11 P1 adds two `/action` values, `pack_use` and `pack_mode`, which set one
+battery's on/off switch or mode in the store (Controller._pack_action); P3 adds
+`pack_sell`, that battery's selling switch. They
+are the only actions that name a battery; the configuration routes still reach
+none of them.
 """
 
+import io
+import json
 import logging
+import os
+from datetime import datetime, timezone
 
 from aiohttp import web
 
-from . import selfconfig
+from . import messages, selfconfig, uipage, uitext
+from .haentities import EntityCache
+from .homeview import region_of
+from .validate import config_notes, setup_checks
 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>
+# OPT-11: the per-battery actions, which name a battery and a value.
+PACK_ACTIONS = ("pack_use", "pack_mode", "pack_sell")
 
-<div class="card">
-  <table id="live"></table>
-</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/<lang>.json (English
+# and, since P5, Dutch; the page picks by the browser's language). 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")
 
-<div class="card">
-  <div class="k">Commissioning</div>
-  <ul id="checks"></ul>
-</div>
 
-<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>
+def _read(path):
+    with io.open(path, encoding="utf-8") as f:
+        return f.read()
 
-<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({lang: uitext.raw(lang) for lang in uitext.LANGS},
+                         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
@@ -125,11 +100,8 @@ refresh(); setInterval(refresh, 3000);
 # them too, and says so, because a green page that is green for a reason the
 # operator cannot see is the exact failure this add-on keeps refusing to ship.
 DEVICE_NOTE = (
-    "%s did not report a range, so the two checks that compare a configured "
-    "ceiling against what the device itself accepts were skipped - here and at "
-    "startup, identically. Everything else was checked. If the device answers "
-    "later and disagrees, the add-on refuses to start then, with the same "
-    "message you would have seen here.")
+    "%s did not report its power range, so two checks were skipped, here and "
+    "at start. If they fail later, the add-on will not start then.")
 
 
 def build_app(controller, selfcfg=None) -> web.Application:
@@ -143,12 +115,34 @@ 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()
+    # UX-13 P4: the blobs /config/model handed out, by fingerprint, so a stale
+    # save can name only the keys that moved underneath the page (finding a).
+    handed: dict = {}
+
+    def hand_out(options):
+        fp = selfconfig.fingerprint(options)
+        handed.pop(fp, None)
+        handed[fp] = options
+        while len(handed) > 16:
+            handed.pop(next(iter(handed)))
+        return fp
+
+    def store_data():
+        store = getattr(controller, "store", None)
+        data = getattr(store, "data", None)
+        return data if isinstance(data, dict) else None
 
     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())
+    async def status(request):
+        # UX-13 P5: Home's sentences in the page's language, English or Dutch.
+        lang = uitext.lang_of(request.query.get("lang"))
+        if lang == "en":
+            return web.json_response(controller.status_payload())
+        return web.json_response(controller.status_payload(lang=lang))
 
     async def action(request):
         try:
@@ -156,7 +150,21 @@ def build_app(controller, selfcfg=None) -> web.Application:
         except ValueError:
             raise web.HTTPBadRequest(text="expected JSON")
         what = body.get("action")
-        result = await controller.handle_action(what)
+        if getattr(controller, "setup_only", False):
+            # UX-15: nothing to start or stop until setup is saved.
+            return web.json_response(
+                {"ok": False, "error": messages.row_setup_only()}, status=409)
+        if what in PACK_ACTIONS:
+            # OPT-11: one battery's switch or mode. Store state for the named
+            # battery, applied on the next cycle; nothing is written here.
+            result = await controller.handle_action(
+                what, unit=body.get("unit"), value=body.get("value"))
+            if isinstance(result, dict) and "error" in result:
+                return web.json_response({"ok": False,
+                                          "error": result["error"]},
+                                         status=400)
+        else:
+            result = await controller.handle_action(what)
         if result is None:
             raise web.HTTPBadRequest(text=f"unknown action {what!r}")
         return web.json_response({"ok": True, "result": result})
@@ -165,15 +173,31 @@ 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.
+
+        With `stored` (a save) and the `base` model the page opened, only the
+        keys this page changed are written onto what is stored now, so a save
+        after a stale refusal keeps the other surface's changes (UX-15 F2)."""
         try:
             body = await request.json()
         except ValueError:
             raise web.HTTPBadRequest(text="expected JSON")
+        model = body.get("model")
+        if isinstance(model, dict):
+            mine = uipage.to_options(model, stored)
+            base = body.get("base")
+            if stored is not None and isinstance(base, dict):
+                was, _errors = uipage.to_options_partial(base, stored)
+                mine = uipage.only_edits(mine, was, stored)
+            return body, mine, 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.
@@ -198,10 +222,25 @@ def build_app(controller, selfcfg=None) -> web.Application:
                             info.get("translations") or {}, lang)
         model.update({
             "options": options,
-            "fingerprint": selfconfig.fingerprint(options),
+            "fingerprint": hand_out(options),
             "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),
+            # UX-13 P4: the setup wizard, and why it opens by itself.
+            "setup": uipage.setup_spec(),
+            "setup_needed": uipage.setup_needed(
+                options, store_data(), bool(getattr(controller, "auto", False)),
+                fresh=getattr(getattr(controller, "store", None), "fresh",
+                              False) is True),
+            # UX-15: this process serves setup only and commands nothing.
+            "setup_only": getattr(controller, "setup_only", False) is True,
         })
         return web.json_response(model)
 
@@ -218,16 +257,60 @@ 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 = await request.json()
+        except ValueError:
+            raise web.HTTPBadRequest(text="expected JSON")
+        model = _body.get("model")
+        errors = []
+        if isinstance(model, dict):
+            # UX-15 F1: a part the page cannot turn into options blocks its
+            # own step, and everything else is still checked.
+            options, errors = uipage.to_options_partial(model)
+        else:
+            model, options = None, _body.get("options")
+            if not isinstance(options, dict):
+                raise web.HTTPBadRequest(text="expected an options object")
+        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.derive_messages(errors, problems, notes, model,
+                                       _keys_of(options),
+                                       uitext.lang_of(_body.get("lang")))
+                if errors
+                else uipage.anchors(problems, notes, model, _keys_of(options)))
+            payload["steps"] = uipage.step_problems(payload["messages"], model)
+        if _body.get("setup"):
+            payload["setup"] = [n._asdict() for n in await _setup_checks(options)]
         return web.json_response(payload)
 
+    async def _setup_checks(options):
+        """The wizard's live checks: a list at most a few seconds old, and
+        what the running add-on already knows (its meter, today's prices)."""
+        rows, age = await entities.get(max_age=5.0)
+        if age is not None and age >= 30.0:
+            rows = None             # Home Assistant is not answering
+        try:
+            prices = (controller.status_payload().get("plan") or {}).get(
+                "prices") or []
+            known = sum(1 for p in prices if p.get("eur_kwh") is not None)
+        except Exception:  # noqa: BLE001 - a display figure, never a failure
+            known = None
+        return setup_checks(options, entities=rows, running=controller.o,
+                            meter_now_w=getattr(controller, "grid", None),
+                            prices_known=known)
+
     def _keys_of(options):
         # ⚠️ THE ANCHOR LIST IS THE KEYS OF THE BLOB UNDER TEST, and that is
         # sound only because the page posts the WHOLE blob it read - which is
@@ -238,33 +321,78 @@ 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:
+            model = posted["model"]
+            _opts, errors = uipage.to_options_partial(model, stored_now)
+            lang = uitext.lang_of(posted.get("lang"))
+            messages_ = [uipage.derive_message(e, lang) for e in errors]
+            return web.json_response(
+                {"kind": "invalid", "problems": [], "by_key": {},
+                 "unanchored": [], "messages": messages_,
+                 "steps": uipage.step_problems(messages_, model)},
+                status=422)
         expect = str(body.get("fingerprint") or "")
         try:
             result = await selfconfig.save(selfcfg, options, expect,
-                                           hass=controller.hass)
+                                           hass=controller.hass,
+                                           base=handed.get(expect))
         except selfconfig.SaveRefused as refused:
             if refused.kind == "stale":
                 stored = refused.stored or {}
+                # The fields to look at are the ones the OTHER surface moved,
+                # not this page's own edits (UX-13 P2 test, finding a).
+                moved = (refused.changed if refused.moved is None
+                         else refused.moved)
                 return web.json_response(
                     {"kind": "stale", "changed": refused.changed,
+                     "moved": refused.moved,
+                     "changed_fields": (uipage.fields_of(moved, 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
                      # is not a force door: it takes a second, deliberate press
                      # made in front of what changed.
-                     "fingerprint": selfconfig.fingerprint(stored)},
+                     "fingerprint": hand_out(stored)},
                     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))
+                payload["steps"] = uipage.step_problems(payload["messages"],
+                                                        model)
+            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)
         controller.log_event("configuration saved from the panel - "
-                             "not applied until the add-on restarts")
+                             "not applied until the add-on restarts",
+                             hint=messages.hint("settings_saved"))
+        # `handed` keeps `expect`: another page may have opened the same blob.
+        store = getattr(controller, "store", None)
+        if (model is not None and body.get("setup") == "done"
+                and store is not None):
+            store.set(uipage.SETUP_DONE,
+                      datetime.now(timezone.utc).isoformat(timespec="seconds"))
         return web.json_response({"ok": True, **result})
 
     async def config_restart(request):
@@ -288,9 +416,20 @@ def build_app(controller, selfcfg=None) -> web.Application:
         except selfconfig.SupervisorUnavailable as err:
             _LOG.error("restart request failed: %s", err)
             return web.json_response({"error": str(err)}, status=502)
-        controller.log_event("restart requested from the configuration panel")
+        controller.log_event("restart requested from the configuration panel",
+                             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]
+        one = str(request.query.get("entity", "") or "")[:255]
+        if one:
+            # UX-13 P4's kettle test: one entity, read now.
+            return web.json_response(await entities.reading(one))
+        return web.json_response(await entities.payload(kind))
+
     app = web.Application()
     app.add_routes([
         web.get("/", index),
@@ -301,12 +440,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/config.yaml

@@ -1,5 +1,5 @@
 name: GoodWe RS485 Controller
-version: "0.12.0"
+version: "0.15.0"
 slug: goodwe_controller
 description: >-
   Drives a GoodWe ES/BP battery inverter over RS485 by emulating its smart
@@ -146,6 +146,18 @@ options:
   # options blob, and the upgrade leaves an add-on that cannot start.
   inverters: []
   estop_fitted: false
+  # OPT-11: battery modes. Off by default, so an install that has not turned
+  # them on behaves exactly as before. When on, each battery gets an on/off
+  # switch and a mode on the Batteries screen, kept in the add-on's store.
+  # DECISIONS/OPT-11-battery-modes.md.
+  battery_modes_enabled: false
+  # OPT-11 P4: a Home Assistant solar forecast (kWh left today; tomorrow's is
+  # optional) and how much of it to count on. Read only with battery modes
+  # on; empty means no day plan (P3 option A). app/solarfc.py lists the
+  # integrations whose sensors fit.
+  pv_forecast_entity: ""
+  pv_forecast_tomorrow_entity: ""
+  solar_trust_pct: 70
 
   # TEL-11 - THE SITE'S PV PRODUCTION, IN WATTS, AND IT IS READ BY NOTHING THAT
   # DECIDES ANYTHING. Optional, empty on every install that does not set it, and
@@ -285,6 +297,8 @@ options:
   # protects the shallower pack with the deeper pack's number.
   bms_soc_floor: 10
   peak_cap_w: 3500
+  # SAFETY-79: the peak guard aims this many watts under peak_cap_w.
+  peak_margin_w: 50
   peak_forecast_entity: ""
 
   # The peak guard can COMMAND a discharge to hold a billed quarter under
@@ -943,6 +957,10 @@ schema:
       capacity_kwh: float(0.1,200)?
 
   estop_fitted: bool
+  battery_modes_enabled: bool
+  pv_forecast_entity: str?
+  pv_forecast_tomorrow_entity: str?
+  solar_trust_pct: int(30,100)
   # TEL-11. Optional, and OPTIONAL WITHOUT A COMPANION RULE - unlike
   # `price_now_entity`/`price_avg_entity`, which are legal only while
   # `price_provider` is `off` and make the add-on REFUSE TO START otherwise.
@@ -1013,6 +1031,7 @@ schema:
   max_w: int(100,5000)
   bms_soc_floor: int(0,50)
   peak_cap_w: int(500,15000)
+  peak_margin_w: int(0,500)
   peak_forecast_entity: str?
 
   # SAFETY-24. No "off" value: a guard that can command a discharge does not get

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
+}