UX-13 P4 (card 6ab979852f3eca02fb40f69e): the setup wizard for installers, on the Setup tab.
What it does
Six steps, each drawn from the fields whose uilayout.Field has that wizard= step, with P2's controls and P2's save path (/config/validate, /config/save). No route was added, and settings.js still names no option key.
Meter, with the kettle test: reads the meter's entities now (GET ha/entities?entity=, one hass.state() read, in W), then again after a kettle is switched on. The change decides: up keeps meter_invert off, down turns it on. A net entity or import/export pair that goes down blocks the step and says what to check. HomeWizard/MQTT meters are read by the add-on itself, so the page skips the test and says so. It can be skipped; the last step then warns.
Inverters and batteries: P2's cards.
Solar: optional ("Next, or skip").
Prices: contract, source, region, prices.
Peak limit: battery modes say "comes in a later update" (OPT-11 is not built).
Check and start: the real validator's refusals, plus validate.setup_checks(). These are the meter reading as the add-on will see it; each power request entity exists in HA via the entity list (a write can't tell, SAFETY-77), and red if missing; battery levels read; battery power with its direction; solar sign; prices known. "Start in shadow mode" is on by default (shadow_mode: on). Save and restart is a confirmed dialog that names the 0 W, then save (setup: "done"), then the intent-token restart.
A step moves on only when no refusal sits on one of its shown fields (uipage.step_problems, returned as steps by validate). Anything else blocks step 6, which lists it.
First run (uipage.setup_needed, DECISIONS/UX-13-setup-wizard.md)
The page opens #setup by itself only when it was opened with no route, and /config/model says why:
no_power_request: the stored options name no inverter to control.
first_start: the Store has no setup_done and no auto key (Start/Stop never pressed), and control is not started.
A running site, or one that ever started or stopped control, is never sent there. The wizard's save writes setup_done; an Installer-view save does not.
Open for the owner: the add-on exits 78 before serving the page when no power request entity is set, which is what a brand-new install ships. So the installer fills in "Inverter setpoint entity" on the Configuration tab first. A setup-only page on a refused config would change the CFG-01 gate and UX-02 §4, so it is not built here.
P2 test finding (a)
/config/model remembers the last 16 blobs it handed out, by fingerprint. A stale save compares that blob with what is stored now (SaveRefused.moved), so the banner lists only the other surface's changes. changed stays as it was for the classic page's theirs→mine list. The browser run found one more case, now fixed and tested: two pages open the same blob, and the other one saves first.
Tests
test_setup.py covers:
the steps and tables;
the kettle sign logic and the page's copy of it;
which refusal blocks which step (unit and HTTP);
first-run detection on new vs existing sites (unit, the 5 TEST-23 option files, and HTTP with the Store marker);
the live checks (18 cases and HTTP);
the wizard save through the P2 path writing a valid 78-key blob;
the stale fix;
the STYLE scan: every wizard string and every rendered check is one sentence of at most 25 words.
test_settings.py: the stale 409 now names exactly the other surface's field.
Supervisor validator:tools/ux13_wizard_blobs.py produces every plan from a new install and three TEST-23 sites: 112 blobs, of which the shipped validator accepts 88. The other 24 are the arbitrage site with a plan that has no meter or no prices, which step 6 lists. 88 of 88 were accepted by ghcr.io/home-assistant/amd64-hassio-supervisor:2026.08.0AppOptions, offline (--network none), 78 keys each. A control run on the same checker refused an out-of-range value, a bad enum and a missing key.
Headless Chromium click-through, 29/29, against tools/ux13_demo.py new and running:
a new install opens #setup; the kettle test goes up, then flips, then goes up again, and the toggle follows;
Next is blocked before the kettle test;
a typed missing power request entity is red on step 6 and Save is refused;
once fixed, all checks are green, the dialog names the 0 W, "Setup is done", and the stored blob is right (shadow on, 4.2 kW, day/night);
setup_needed is cleared and a reload stays on Home;
the stale banner names only "Peak limit";
a running site stays on Home, and its Setup says "set up already";
390 px shows no side-scroll, in light and dark;
there are no JS errors and no off-prefix requests.
Full suite locally in the CI image: 44/44 test files.
UX-13 P4 (card 6ab979852f3eca02fb40f69e): the setup wizard for installers, on the Setup tab.
## What it does
Six steps, each drawn from the fields whose `uilayout.Field` has that `wizard=` step, with P2's controls and P2's save path (`/config/validate`, `/config/save`). No route was added, and settings.js still names no option key.
1. **Meter**, with the **kettle test**: reads the meter's entities now (`GET ha/entities?entity=`, one `hass.state()` read, in W), then again after a kettle is switched on. The change decides: up keeps `meter_invert` off, down turns it on. A net entity or import/export pair that goes down blocks the step and says what to check. HomeWizard/MQTT meters are read by the add-on itself, so the page skips the test and says so. It can be skipped; the last step then warns.
2. **Inverters and batteries**: P2's cards.
3. **Solar**: optional ("Next, or skip").
4. **Prices**: contract, source, region, prices.
5. **Peak limit**: battery modes say "comes in a later update" (OPT-11 is not built).
6. **Check and start**: the real validator's refusals, plus `validate.setup_checks()`. These are the meter reading as the add-on will see it; each power request entity exists in HA via the entity list (a write can't tell, SAFETY-77), and **red if missing**; battery levels read; battery power with its direction; solar sign; prices known. "Start in shadow mode" is on by default (`shadow_mode: on`). Save and restart is a confirmed dialog that names the 0 W, then save (`setup: "done"`), then the intent-token restart.
A step moves on only when no refusal sits on one of its shown fields (`uipage.step_problems`, returned as `steps` by validate). Anything else blocks step 6, which lists it.
## First run (`uipage.setup_needed`, DECISIONS/UX-13-setup-wizard.md)
The page opens `#setup` by itself only when it was opened with no route, and `/config/model` says why:
- `no_power_request`: the stored options name no inverter to control.
- `first_start`: the Store has no `setup_done` and no `auto` key (Start/Stop never pressed), and control is not started.
A running site, or one that ever started or stopped control, is never sent there. The wizard's save writes `setup_done`; an Installer-view save does not.
**Open for the owner:** the add-on exits 78 before serving the page when no power request entity is set, which is what a brand-new install ships. So the installer fills in "Inverter setpoint entity" on the Configuration tab first. A setup-only page on a refused config would change the CFG-01 gate and UX-02 §4, so it is not built here.
## P2 test finding (a)
`/config/model` remembers the last 16 blobs it handed out, by fingerprint. A stale save compares that blob with what is stored now (`SaveRefused.moved`), so the banner lists only the other surface's changes. `changed` stays as it was for the classic page's theirs→mine list. The browser run found one more case, now fixed and tested: two pages open the same blob, and the other one saves first.
## Tests
- `test_setup.py` covers:
- the steps and tables;
- the kettle sign logic and the page's copy of it;
- which refusal blocks which step (unit and HTTP);
- first-run detection on new vs existing sites (unit, the 5 TEST-23 option files, and HTTP with the Store marker);
- the live checks (18 cases and HTTP);
- the wizard save through the P2 path writing a valid 78-key blob;
- the stale fix;
- the STYLE scan: every wizard string and every rendered check is one sentence of at most 25 words.
- `test_settings.py`: the stale 409 now names exactly the other surface's field.
- **Supervisor validator:** `tools/ux13_wizard_blobs.py` produces every plan from a new install and three TEST-23 sites: 112 blobs, of which the shipped validator accepts 88. The other 24 are the arbitrage site with a plan that has no meter or no prices, which step 6 lists. **88 of 88 were accepted by `ghcr.io/home-assistant/amd64-hassio-supervisor:2026.08.0` `AppOptions`, offline (`--network none`), 78 keys each.** A control run on the same checker refused an out-of-range value, a bad enum and a missing key.
- **Headless Chromium click-through, 29/29**, against `tools/ux13_demo.py new` and `running`:
- a new install opens `#setup`; the kettle test goes up, then flips, then goes up again, and the toggle follows;
- Next is blocked before the kettle test;
- a typed missing power request entity is red on step 6 and Save is refused;
- once fixed, all checks are green, the dialog names the 0 W, "Setup is done", and the stored blob is right (shadow `on`, 4.2 kW, day/night);
- `setup_needed` is cleared and a reload stays on Home;
- the stale banner names only "Peak limit";
- a running site stays on Home, and its Setup says "set up already";
- 390 px shows no side-scroll, in light and dark;
- there are no JS errors and no off-prefix requests.
- Full suite locally in the CI image: 44/44 test files.
TEST-23 was not used.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01LyR88rXETvwhTgx6yHE39p
The Setup tab draws the Installer view's page model one step at a time,
from each field's `wizard` step in app/uilayout.py: meter (with the kettle
test), inverters and batteries, solar (optional), prices, peak limit
(battery modes: "comes in a later update", OPT-11), check and start.
It reuses P2's controls and saves through /config/validate and
/config/save. No route was added.
- First run: /config/model says `setup_needed` when the stored options name
no power request entity, or on a new install (no `setup_done` and no
`auto` in the Store, control not started). The page opens #setup only
when opened with no route. The wizard's save writes `setup_done`.
- Kettle test: GET ha/entities?entity= reads one entity now, in W. The
change decides: up keeps meter_invert off, down turns it on; a net or
import/export meter that goes down blocks the step with what to check.
- Last step: validate.setup_checks() beside the refusals: the meter reads,
each power request entity exists in HA (bad if not, SAFETY-77), battery
levels and power with direction, solar sign, prices. Saves with
shadow_mode on by default, then a confirmed restart naming the 0 W.
- P2 test finding (a): a stale save lists only the keys the other surface
moved (the blob handed out on open, by fingerprint, against stored now).
- test_setup.py; tools/ux13_wizard_blobs.py makes the 88 blobs the wizard
can save; all accepted by Supervisor 2026.08.0 AppOptions (offline).
- DECISIONS/UX-13-setup-wizard.md; DOCS "Setup, for a new install".
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LyR88rXETvwhTgx6yHE39p
I ran the 8 related test files in the CI image (all green), drove tools/ux13_demo.py new over HTTP (3 wizard saves, two tabs, eviction), checked 3 saved blobs with Supervisor 2026.08.0 AppOptions, and ran setup_needed on the real TEST-23 Stores (read-only docker cp). Six points. R1 and R2 block the merge. I will push fixes for all six on this branch unless you refute one.
R1 (blocker): the first-run rule sends both real TEST-23 add-ons to the wizard.test23-addon and test23-addon-arb both have auto_start: false, and neither Store has an auto key (Start/Stop was never pressed, or the volume was restored after a test). setup_needed(options, state.json, started=False) returns first_start for both. test23-addon-arb has been running in shadow (auto + stopped) for weeks. So "a site in shadow" and "an old Store without setup_done" are both redirected. test_setup part 4 passes only because it gives the TEST-23 sites Store({"auto": True}), which they don't have. "Never started" can't tell a new install from an old stopped or shadow site. Fix:first_start also needs a Store that was created at this boot (no /data/state.json at load; Store.fresh). The gate exits 78 before Controller ever writes the Store, so a new install's first good boot is fresh and every existing site is not. Test it with the real TEST-23 Store key sets.
R2 (blocker): skipping the kettle test after a fall hides the fall. For ha_signed and ha_dsmr, a fall sets ok: false, and if (!k.ok) still shows "Skip this test". Skip then records skipped, and step 6 says only "The meter direction is not tested", which is false: it was tested and it went the wrong way. A cloud can fake a fall, so skip may stay. But step 6 must say the reading went down, as a warning that says what to check.
R3: "Start in shadow mode" edits the shared model just by being drawn.drawStep() runs applyShadow() on step 6, which writes V.shadow_mode = "on". V is the Installer view's model too. So opening Setup on a running site, looking at step 6, and then saving a peak change under Settings also saves shadow_mode: on. After the restart the site is in shadow and does not control, and nobody chose that. Fix: keep V untouched and put the shadow value only on the model the wizard posts, for its checks and its save.
R4: with Home Assistant down, the power request entity is not checked, yet the save goes through. When the list is None, setup_checks gives a warn only, so nothing is red and the wizard saves. SAFETY-77 is exactly the case where only the list can tell. Fix: make it red ("press Check again once it is back").
R5: a reversed battery sensor is never flagged. The battery line is "info" and reports the reading's own direction, so the installer has to spot the mistake. The page can flag one case for sure: meter + solar + battery must add up to a house load of 0 W or more. A reversed sensor on a battery that is giving power makes that sum clearly negative. Fix: a warn when every battery and solar reading is known, solar is configured, and the sum is below -300 W, pointing at the battery's direction switch. An idle or charging battery still can't be judged; the info line stays for those.
R6 (STYLE: say what to fix and where): "There is no battery level entity, so the add-on holds 0 W." and "{entity} reads below zero now, so its solar production sign looks reversed." say what is wrong but not what to change or where; "…so the meter has no reading yet" likewise. Each will name the step and the switch. (Refusal sentences keep their keys; that is the shared validator text and the known P5 follow-up.)
Checked and fine:
3 wizard blobs, all saved through /config/save with setup: "done" (flat + kettle flip; two-inverter list + DSMR + day/night; signed + fixed + solar + own levies): accepted by 2026.08.0 AppOptions, 78 keys, none dropped, identical after validation; a control blob with shadow_mode: maybe was refused. The inverter keys stay flat for one inverter and become a list for two, price_taxes_profile is kept as stored, and each diff holds only the keys the plan touched.
Two tabs: B's 409 lists changed_fields == ["peak_cap_w"] (not its own timeout), a second press saves, and an unchanged save is 200. handed holds at most 16 entries; reloads of one blob re-insert it; after a restart it falls back to changed.
ha/entities?entity= on a missing entity gives found: false and the page shows "unread". hass.state() returns None on every failure, so HA being down gives a plain message and no crash.
No inverter write: the wizard only uses validate/save/restart. After the restart shadow_mode: on holds 0 W (shadow.engaged → on is True whatever auto is), the same as a stopped install. setup_done is read only by setup_needed.
Home, /status, classic /config: untouched outside config routes, and test_home and test_settings are green.
## Review of UX-13 P4 at be57b87 (reviewer)
I ran the 8 related test files in the CI image (all green), drove `tools/ux13_demo.py new` over HTTP (3 wizard saves, two tabs, eviction), checked 3 saved blobs with Supervisor 2026.08.0 `AppOptions`, and ran `setup_needed` on the real TEST-23 Stores (read-only `docker cp`). Six points. R1 and R2 block the merge. I will push fixes for all six on this branch unless you refute one.
**R1 (blocker): the first-run rule sends both real TEST-23 add-ons to the wizard.** `test23-addon` and `test23-addon-arb` both have `auto_start: false`, and neither Store has an `auto` key (Start/Stop was never pressed, or the volume was restored after a test). `setup_needed(options, state.json, started=False)` returns `first_start` for both. `test23-addon-arb` has been running in shadow (`auto` + stopped) for weeks. So "a site in shadow" and "an old Store without `setup_done`" are both redirected. test_setup part 4 passes only because it gives the TEST-23 sites `Store({"auto": True})`, which they don't have. "Never started" can't tell a new install from an old stopped or shadow site. **Fix:** `first_start` also needs a Store that was *created* at this boot (no `/data/state.json` at load; `Store.fresh`). The gate exits 78 before `Controller` ever writes the Store, so a new install's first good boot is fresh and every existing site is not. Test it with the real TEST-23 Store key sets.
**R2 (blocker): skipping the kettle test after a fall hides the fall.** For `ha_signed` and `ha_dsmr`, a fall sets `ok: false`, and `if (!k.ok)` still shows "Skip this test". Skip then records `skipped`, and step 6 says only "The meter direction is not tested", which is false: it was tested and it went the wrong way. A cloud can fake a fall, so skip may stay. But step 6 must say the reading went down, as a warning that says what to check.
**R3: "Start in shadow mode" edits the shared model just by being drawn.** `drawStep()` runs `applyShadow()` on step 6, which writes `V.shadow_mode = "on"`. V is the Installer view's model too. So opening Setup on a running site, looking at step 6, and then saving a peak change under Settings also saves `shadow_mode: on`. After the restart the site is in shadow and does not control, and nobody chose that. **Fix:** keep V untouched and put the shadow value only on the model the wizard posts, for its checks and its save.
**R4: with Home Assistant down, the power request entity is not checked, yet the save goes through.** When the list is `None`, `setup_checks` gives a warn only, so nothing is red and the wizard saves. SAFETY-77 is exactly the case where only the list can tell. **Fix:** make it red ("press Check again once it is back").
**R5: a reversed battery sensor is never flagged.** The battery line is "info" and reports the reading's own direction, so the installer has to spot the mistake. The page can flag one case for sure: meter + solar + battery must add up to a house load of 0 W or more. A reversed sensor on a battery that is giving power makes that sum clearly negative. **Fix:** a warn when every battery and solar reading is known, solar is configured, and the sum is below -300 W, pointing at the battery's direction switch. An idle or charging battery still can't be judged; the info line stays for those.
**R6 (STYLE: say what to fix and where):** "There is no battery level entity, so the add-on holds 0 W." and "{entity} reads below zero now, so its solar production sign looks reversed." say what is wrong but not what to change or where; "…so the meter has no reading yet" likewise. Each will name the step and the switch. (Refusal sentences keep their keys; that is the shared validator text and the known P5 follow-up.)
**Checked and fine:**
- 3 wizard blobs, all saved through `/config/save` with `setup: "done"` (flat + kettle flip; two-inverter list + DSMR + day/night; signed + fixed + solar + own levies): **accepted by 2026.08.0 `AppOptions`, 78 keys, none dropped, identical after validation**; a control blob with `shadow_mode: maybe` was refused. The inverter keys stay flat for one inverter and become a list for two, `price_taxes_profile` is kept as stored, and each diff holds only the keys the plan touched.
- Two tabs: B's 409 lists `changed_fields == ["peak_cap_w"]` (not its own timeout), a second press saves, and an unchanged save is 200. `handed` holds at most 16 entries; reloads of one blob re-insert it; after a restart it falls back to `changed`.
- `ha/entities?entity=` on a missing entity gives `found: false` and the page shows "unread". `hass.state()` returns None on every failure, so HA being down gives a plain message and no crash.
- No inverter write: the wizard only uses validate/save/restart. After the restart `shadow_mode: on` holds 0 W (`shadow.engaged` → `on` is True whatever `auto` is), the same as a stopped install. `setup_done` is read only by `setup_needed`.
- Home, /status, classic /config: untouched outside config routes, and test_home and test_settings are green.
R1: first_start also needs a Store created at this boot (Store.fresh), so
old never-started sites (both TEST-23 add-ons, one in shadow) stay on Home.
R2: a kettle skip after a fall says on the last step that the reading went down.
R3: the shadow switch goes only on the model the wizard posts, never into V.
R4: Home Assistant not answering is red on the last step.
R5: meter + solar + battery below -300 W flags a reversed battery sensor.
R6: the live checks say what to change and where.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Nobody refuted any point, so I fixed all six myself on this branch.
R1 fixed.Store.fresh is True only when this boot found no /data/state.json. setup_needed(..., fresh=) returns first_start only for a fresh Store. The gate exits 78 before the controller writes the Store, so a new install's first good boot is fresh. Tests: the real TEST-23 Store key sets (_T23_ADDON, _T23_ARB, and the arb one with shadow_mode: on) → None, also over HTTP. app/store.py is fresh for a new file, not after a save, and not for an unreadable file. ux13_demo new marks its Store fresh. DECISIONS §2 and DOCS are updated.
R2 fixed. The kettle state carries wrong (a fall the options cannot fix) through re-reads and a skip. Step 6 then says "The kettle test saw the meter reading go down, so check its direction in step 1 before you start control." A later rise clears it.
R3 fixed.posted() = V + the shadow value. It is used only for the wizard's check and save requests, and V is never written.
R4 fixed. HA not answering → bad: "Home Assistant is not answering, so press Check again once it is back."
R5 fixed.BALANCE_W = 300. When the meter, every solar entity and every battery reading are known and add up below -300 W → warn: "The readings add up to -1 098 W of house use, so check each battery's “Battery power sign is reversed” switch in step 2." It stays quiet with the switch on, with no solar, with the battery reading unknown, and on the normal fixture.
R6 fixed. New wording: "…so pick one in step 2 or the add-on holds 0 W", "…so turn on its “Reads negative” switch in the Solar step", and "…so check it in Home Assistant before you start". All 40 rendered checks stay one sentence of ≤ 25 words.
Evidence:
Full suite in the CI image: 44/44.
Mutations, all red:
setup_needed ignoring started → 1 FAIL;
the missing power request entity not red (bad=()) → 3 FAIL;
dropping the fresh condition → 2 FAIL (both R1 checks).
Headless Chromium against ux13_demo new and running, 18/18:
A new install opens #setup.
Kettle up → ok. Then a fall on a net entity → "choose “One grid power entity” above", and Next is blocked. After the skip, step 6 lists the fall.
Settings, opened on step 6, shows 2 unsaved changes, not 3.
The dialog names the 0 W. Stored: shadow_mode: on, and setup_needed is cleared. A reload stays on Home.
On the running site: it stays on Home; Setup says "set up already"; Not now → Home. After visiting step 6, Settings has nothing to save.
390 px shows no side-scroll, and there are no JS errors.
## Review fixes pushed: 3198f34 (answers comment 1887)
Nobody refuted any point, so I fixed all six myself on this branch.
- **R1 fixed.** `Store.fresh` is True only when this boot found no `/data/state.json`. `setup_needed(..., fresh=)` returns `first_start` only for a fresh Store. The gate exits 78 before the controller writes the Store, so a new install's first good boot is fresh. Tests: the real TEST-23 Store key sets (`_T23_ADDON`, `_T23_ARB`, and the arb one with `shadow_mode: on`) → None, also over HTTP. `app/store.py` is fresh for a new file, not after a save, and not for an unreadable file. `ux13_demo new` marks its Store fresh. DECISIONS §2 and DOCS are updated.
- **R2 fixed.** The kettle state carries `wrong` (a fall the options cannot fix) through re-reads and a skip. Step 6 then says "The kettle test saw the meter reading go down, so check its direction in step 1 before you start control." A later rise clears it.
- **R3 fixed.** `posted()` = V + the shadow value. It is used only for the wizard's check and save requests, and V is never written.
- **R4 fixed.** HA not answering → **bad**: "Home Assistant is not answering, so press Check again once it is back."
- **R5 fixed.** `BALANCE_W = 300`. When the meter, every solar entity and every battery reading are known and add up below -300 W → warn: "The readings add up to -1 098 W of house use, so check each battery's “Battery power sign is reversed” switch in step 2." It stays quiet with the switch on, with no solar, with the battery reading unknown, and on the normal fixture.
- **R6 fixed.** New wording: "…so pick one in step 2 or the add-on holds 0 W", "…so turn on its “Reads negative” switch in the Solar step", and "…so check it in Home Assistant before you start". All 40 rendered checks stay one sentence of ≤ 25 words.
**Evidence:**
- Full suite in the CI image: 44/44.
- **Mutations**, all red:
- `setup_needed` ignoring `started` → 1 FAIL;
- the missing power request entity not red (`bad=()`) → 3 FAIL;
- dropping the `fresh` condition → 2 FAIL (both R1 checks).
- **Headless Chromium** against `ux13_demo new` and `running`, 18/18:
- A new install opens #setup.
- Kettle up → ok. Then a fall on a net entity → "choose “One grid power entity” above", and Next is blocked. After the skip, step 6 lists the fall.
- Settings, opened on step 6, shows 2 unsaved changes, not 3.
- The dialog names the 0 W. Stored: `shadow_mode: on`, and `setup_needed` is cleared. A reload stays on Home.
- On the running site: it stays on Home; Setup says "set up already"; Not now → Home. After visiting step 6, Settings has nothing to save.
- 390 px shows no side-scroll, and there are no JS errors.
I will merge once CI is green on 3198f34.
admin
merged commit 4de96752ff into release/1.02026-09-28 06:23:16 +02:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
UX-13 P4 (card 6ab979852f3eca02fb40f69e): the setup wizard for installers, on the Setup tab.
What it does
Six steps, each drawn from the fields whose
uilayout.Fieldhas thatwizard=step, with P2's controls and P2's save path (/config/validate,/config/save). No route was added, and settings.js still names no option key.GET ha/entities?entity=, onehass.state()read, in W), then again after a kettle is switched on. The change decides: up keepsmeter_invertoff, down turns it on. A net entity or import/export pair that goes down blocks the step and says what to check. HomeWizard/MQTT meters are read by the add-on itself, so the page skips the test and says so. It can be skipped; the last step then warns.validate.setup_checks(). These are the meter reading as the add-on will see it; each power request entity exists in HA via the entity list (a write can't tell, SAFETY-77), and red if missing; battery levels read; battery power with its direction; solar sign; prices known. "Start in shadow mode" is on by default (shadow_mode: on). Save and restart is a confirmed dialog that names the 0 W, then save (setup: "done"), then the intent-token restart.A step moves on only when no refusal sits on one of its shown fields (
uipage.step_problems, returned asstepsby validate). Anything else blocks step 6, which lists it.First run (
uipage.setup_needed, DECISIONS/UX-13-setup-wizard.md)The page opens
#setupby itself only when it was opened with no route, and/config/modelsays why:no_power_request: the stored options name no inverter to control.first_start: the Store has nosetup_doneand noautokey (Start/Stop never pressed), and control is not started.A running site, or one that ever started or stopped control, is never sent there. The wizard's save writes
setup_done; an Installer-view save does not.Open for the owner: the add-on exits 78 before serving the page when no power request entity is set, which is what a brand-new install ships. So the installer fills in "Inverter setpoint entity" on the Configuration tab first. A setup-only page on a refused config would change the CFG-01 gate and UX-02 §4, so it is not built here.
P2 test finding (a)
/config/modelremembers the last 16 blobs it handed out, by fingerprint. A stale save compares that blob with what is stored now (SaveRefused.moved), so the banner lists only the other surface's changes.changedstays as it was for the classic page's theirs→mine list. The browser run found one more case, now fixed and tested: two pages open the same blob, and the other one saves first.Tests
test_setup.pycovers:test_settings.py: the stale 409 now names exactly the other surface's field.tools/ux13_wizard_blobs.pyproduces every plan from a new install and three TEST-23 sites: 112 blobs, of which the shipped validator accepts 88. The other 24 are the arbitrage site with a plan that has no meter or no prices, which step 6 lists. 88 of 88 were accepted byghcr.io/home-assistant/amd64-hassio-supervisor:2026.08.0AppOptions, offline (--network none), 78 keys each. A control run on the same checker refused an out-of-range value, a bad enum and a missing key.tools/ux13_demo.py newandrunning:#setup; the kettle test goes up, then flips, then goes up again, and the toggle follows;on, 4.2 kW, day/night);setup_neededis cleared and a reload stays on Home;TEST-23 was not used.
🤖 Generated with Claude Code
https://claude.ai/code/session_01LyR88rXETvwhTgx6yHE39p
Review of UX-13 P4 at
be57b87(reviewer)I ran the 8 related test files in the CI image (all green), drove
tools/ux13_demo.py newover HTTP (3 wizard saves, two tabs, eviction), checked 3 saved blobs with Supervisor 2026.08.0AppOptions, and ransetup_neededon the real TEST-23 Stores (read-onlydocker cp). Six points. R1 and R2 block the merge. I will push fixes for all six on this branch unless you refute one.R1 (blocker): the first-run rule sends both real TEST-23 add-ons to the wizard.
test23-addonandtest23-addon-arbboth haveauto_start: false, and neither Store has anautokey (Start/Stop was never pressed, or the volume was restored after a test).setup_needed(options, state.json, started=False)returnsfirst_startfor both.test23-addon-arbhas been running in shadow (auto+ stopped) for weeks. So "a site in shadow" and "an old Store withoutsetup_done" are both redirected. test_setup part 4 passes only because it gives the TEST-23 sitesStore({"auto": True}), which they don't have. "Never started" can't tell a new install from an old stopped or shadow site. Fix:first_startalso needs a Store that was created at this boot (no/data/state.jsonat load;Store.fresh). The gate exits 78 beforeControllerever writes the Store, so a new install's first good boot is fresh and every existing site is not. Test it with the real TEST-23 Store key sets.R2 (blocker): skipping the kettle test after a fall hides the fall. For
ha_signedandha_dsmr, a fall setsok: false, andif (!k.ok)still shows "Skip this test". Skip then recordsskipped, and step 6 says only "The meter direction is not tested", which is false: it was tested and it went the wrong way. A cloud can fake a fall, so skip may stay. But step 6 must say the reading went down, as a warning that says what to check.R3: "Start in shadow mode" edits the shared model just by being drawn.
drawStep()runsapplyShadow()on step 6, which writesV.shadow_mode = "on". V is the Installer view's model too. So opening Setup on a running site, looking at step 6, and then saving a peak change under Settings also savesshadow_mode: on. After the restart the site is in shadow and does not control, and nobody chose that. Fix: keep V untouched and put the shadow value only on the model the wizard posts, for its checks and its save.R4: with Home Assistant down, the power request entity is not checked, yet the save goes through. When the list is
None,setup_checksgives a warn only, so nothing is red and the wizard saves. SAFETY-77 is exactly the case where only the list can tell. Fix: make it red ("press Check again once it is back").R5: a reversed battery sensor is never flagged. The battery line is "info" and reports the reading's own direction, so the installer has to spot the mistake. The page can flag one case for sure: meter + solar + battery must add up to a house load of 0 W or more. A reversed sensor on a battery that is giving power makes that sum clearly negative. Fix: a warn when every battery and solar reading is known, solar is configured, and the sum is below -300 W, pointing at the battery's direction switch. An idle or charging battery still can't be judged; the info line stays for those.
R6 (STYLE: say what to fix and where): "There is no battery level entity, so the add-on holds 0 W." and "{entity} reads below zero now, so its solar production sign looks reversed." say what is wrong but not what to change or where; "…so the meter has no reading yet" likewise. Each will name the step and the switch. (Refusal sentences keep their keys; that is the shared validator text and the known P5 follow-up.)
Checked and fine:
/config/savewithsetup: "done"(flat + kettle flip; two-inverter list + DSMR + day/night; signed + fixed + solar + own levies): accepted by 2026.08.0AppOptions, 78 keys, none dropped, identical after validation; a control blob withshadow_mode: maybewas refused. The inverter keys stay flat for one inverter and become a list for two,price_taxes_profileis kept as stored, and each diff holds only the keys the plan touched.changed_fields == ["peak_cap_w"](not its own timeout), a second press saves, and an unchanged save is 200.handedholds at most 16 entries; reloads of one blob re-insert it; after a restart it falls back tochanged.ha/entities?entity=on a missing entity givesfound: falseand the page shows "unread".hass.state()returns None on every failure, so HA being down gives a plain message and no crash.shadow_mode: onholds 0 W (shadow.engaged→onis True whateverautois), the same as a stopped install.setup_doneis read only bysetup_needed.R1: first_start also needs a Store created at this boot (Store.fresh), so old never-started sites (both TEST-23 add-ons, one in shadow) stay on Home. R2: a kettle skip after a fall says on the last step that the reading went down. R3: the shadow switch goes only on the model the wizard posts, never into V. R4: Home Assistant not answering is red on the last step. R5: meter + solar + battery below -300 W flags a reversed battery sensor. R6: the live checks say what to change and where. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>Review fixes pushed:
3198f34(answers comment 1887)Nobody refuted any point, so I fixed all six myself on this branch.
Store.freshis True only when this boot found no/data/state.json.setup_needed(..., fresh=)returnsfirst_startonly for a fresh Store. The gate exits 78 before the controller writes the Store, so a new install's first good boot is fresh. Tests: the real TEST-23 Store key sets (_T23_ADDON,_T23_ARB, and the arb one withshadow_mode: on) → None, also over HTTP.app/store.pyis fresh for a new file, not after a save, and not for an unreadable file.ux13_demo newmarks its Store fresh. DECISIONS §2 and DOCS are updated.wrong(a fall the options cannot fix) through re-reads and a skip. Step 6 then says "The kettle test saw the meter reading go down, so check its direction in step 1 before you start control." A later rise clears it.posted()= V + the shadow value. It is used only for the wizard's check and save requests, and V is never written.BALANCE_W = 300. When the meter, every solar entity and every battery reading are known and add up below -300 W → warn: "The readings add up to -1 098 W of house use, so check each battery's “Battery power sign is reversed” switch in step 2." It stays quiet with the switch on, with no solar, with the battery reading unknown, and on the normal fixture.Evidence:
setup_neededignoringstarted→ 1 FAIL;bad=()) → 3 FAIL;freshcondition → 2 FAIL (both R1 checks).ux13_demo newandrunning, 18/18:shadow_mode: on, andsetup_neededis cleared. A reload stays on Home.I will merge once CI is green on
3198f34.