UX-15: setup-only mode, and the wizard fixes F1, F2, meter, step 1

A new install names no inverter. When that is the startup gate's only
refusal, the add-on now serves the setup wizard in setup-only mode instead
of exiting 78. It builds no controller, MQTT client or meter task, its
HomeAssistant is read-only (every service call refuses before sending),
Controller refuses a read-only HomeAssistant, and /action answers 409.
Any other refusal still exits 78. DECISIONS/UX-15-setup-only-mode.md.

Wizard fixes from the UX-13 P4 test:
- F1: /config/validate converts what it can, so a conversion error blocks
  its own step and the live checks still run; save 422 carries steps.
- F2: saves send the model the page opened (base); only keys this page
  changed are written onto the blob stored now.
- A meter entity missing from Home Assistant is red on the last step.
- Step 1 says the reading went down after a skip that followed a fall.

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

goodwe_controller/app/hass.py

@@ -51,10 +51,18 @@ class Outage:
 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?")
@@ -181,7 +189,17 @@ 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}",

goodwe_controller/app/main.py

@@ -87,9 +87,11 @@ from .watchdog import (
     AGAINST_METER, AGAINST_OWN_POWER, SIGN_OPTION_DEFAULTS,
     SignWatchdog, SignWatchdogConfig, loop_is_following,
 )
+from . import setuponly
 from . import web
 
 OPTIONS_PATH = "/data/options.json"
+INGRESS_PORT = 8099
 _LOG = logging.getLogger("goodwe")
 
 # ⚠️ `UNIT_A` NOW LIVES IN app/inverter.py AND IS RE-EXPORTED HERE, because the
@@ -375,6 +377,11 @@ class Controller:
     def __init__(self, opts: dict, hass: HomeAssistant, store, mqtt_pub, *, stop,
                  peak_db_path: str = "/data/tariff.db",
                  price_history_path: str = "/data/price_history.json"):
+        # UX-15: a read-only HomeAssistant belongs to setup-only mode, which
+        # builds no controller. Refused here so no controller can hold one.
+        if getattr(hass, "read_only", False) is True:
+            raise ValueError("a controller cannot run on a read-only "
+                             "HomeAssistant (setup-only mode)")
         self.o = opts
         self.hass = hass
         self.store = store
@@ -6011,6 +6018,15 @@ async def amain() -> None:
             _dev_min, _dev_max, _ = await hass.limits(_sp)
             _LOG.info("setpoint device %s reports range %s…%s W", _sp, _dev_min, _dev_max)
         _problems = validate_startup_config(opts, _dev_min, _dev_max)
+        # UX-15: a new install names no inverter. When that is the ONLY
+        # refusal it serves the setup wizard in setup-only mode, which builds
+        # nothing that commands and returns when stopped. Any other refusal
+        # still exits 78 (DECISIONS/UX-15-setup-only-mode.md).
+        if _problems and setuponly.applies(opts, _problems):
+            await setuponly.serve(
+                opts, HomeAssistant(session, read_only=True), store,
+                port=INGRESS_PORT)
+            return
         if _problems:
             refuse(_problems)
             raise ConfigRefused(_problems)
@@ -6054,7 +6070,7 @@ async def amain() -> None:
 
         stop = asyncio.Event()
         controller = Controller(opts, hass, store, pub, stop=stop)
-        runner = await web.start(controller, port=8099)
+        runner = await web.start(controller, port=INGRESS_PORT)
 
         loop = asyncio.get_running_loop()
         for sig in (signal.SIGTERM, signal.SIGINT):

goodwe_controller/app/messages.py

@@ -382,6 +382,16 @@ def banner_stopped() -> str:
     return "Stopped — the inverters are set to 0 W"
 
 
+def banner_setup_only() -> str:
+    """UX-15: setup-only mode, where the add-on serves the page and commands
+    nothing (app/setuponly.py)."""
+    return "Setup: the add-on controls nothing until setup is done"
+
+
+def row_setup_only() -> str:
+    return "No inverter is named yet, so finish Setup and restart the add-on."
+
+
 def banner_shadow(latched: bool) -> str:
     """SAFETY-10: first in the cascade, never displaced by another banner.
 
@@ -861,6 +871,7 @@ HINTS = {
     "control_stopped": "Control stopped",
     "settings_saved": "Settings saved, they apply after a restart",
     "restart_requested": "Restart requested from the settings page",
+    "setup_only": "In setup, nothing is sent to any inverter",
     "roster": "Inverter list read: {n} inverters",
     "maint_history": "Maintenance history did not move over cleanly",
     "stop_restored": "{unit}: an earlier safety stop is back, it stays at 0 W",
@@ -952,6 +963,8 @@ def status_samples() -> list:
         ("banner_peak_reserve", None, banner_peak_reserve()),
         ("banner_power_too_high", None, banner_power_too_high()),
         ("banner_shadow", None, banner_shadow(False)),
+        ("banner_setup_only", None, banner_setup_only()),
+        ("row_setup_only", AMBER, row_setup_only()),
         ("banner_shadow", None, banner_shadow(True)),
         ("row_controller_starting", GREEN, row_controller_starting()),
         ("row_controller_ran", GREEN, row_controller_ran(2)),

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) -> 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/static/app.js

@@ -94,11 +94,13 @@
   function render() {
     renderPill();
     const structured = S.now && S.plan && !S.home_error;
-    banner($("#home-banner"), S.level, S.banner, structured ? S.state.sub : "", S.level === "bad" ? "alert" : null);
+    // UX-15: setup-only mode commands nothing and has no control to offer.
+    const setup = S.setup_only === true;
+    banner($("#home-banner"), S.level, 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);
-    renderDetails(!structured);
+    renderControl(structured, setup);
+    renderDetails(!structured && !setup);
     renderBatteries();
   }
 
@@ -270,12 +272,15 @@
     badge.textContent = n; badge.hidden = !n;
     badge.classList.toggle("bad", list.some((a) => a.severity === "alarm"));
   }
-  function renderControl(structured) {
+  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" : "");
-    $("#ctl-text").textContent = structured ? S.control.text : "";
+    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;

goodwe_controller/app/static/index.html

@@ -72,6 +72,7 @@
     <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>

goodwe_controller/app/static/settings.js

@@ -533,10 +533,12 @@
     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.
+  // 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, fingerprint: FP }, extra || {})) });
+                                           body: JSON.stringify(Object.assign({ model: V, base: ORIG, fingerprint: FP }, extra || {})) });
     const b = await r.json().catch(() => ({}));
     if (r.status === 409 && b.kind === "stale") FP = b.fingerprint || FP;
     return { r, b };
@@ -624,8 +626,10 @@
     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));
-    const tone = { ok: "ok", flip: "info", none: "warn", unread: "bad", skipped: "warn" }[k.say] || "bad";
-    const words = k.say ? WS.kettle[k.say] : k.before != null ? WS.kettle.before : null;
+    // 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; };
@@ -715,7 +719,9 @@
     if (!b) { toast(WS.check.failed.description); return; }
     if (WZ.blocked) { toast(WS.check.blocked.description); return; }
     const shadow = shadowValue() === M.setup.shadow.on;
-    ask(shadow ? WS.dialog : WS.dialog_live, async () => {
+    // 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; }

goodwe_controller/app/store.py

@@ -581,9 +581,12 @@ def migrate_maint_keys(store, unit: str, roster) -> MigrationReport:
     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).

goodwe_controller/app/ui_text/en.json

@@ -79,6 +79,7 @@
     },
     "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": {"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": "Battery modes and on and off switches arrive in a later update.", "level": "Level", "now": "Now", "stored": "Stored", "mode": "Mode", "settings": "Change inverter settings"},
     "settings": {"name": "Settings", "description": "The settings are grouped by task below.", "open": "Open the settings page"}
   },
@@ -192,6 +193,7 @@
         "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."}
       },
@@ -206,6 +208,8 @@
       "shadow": {"name": "Start in shadow mode", "description": "Recommended, because every inverter then stays at 0 W until you turn shadow mode off under Settings."},
       "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."},

goodwe_controller/app/uimodel.py

@@ -20,7 +20,8 @@ import json
 from .price import FLEMISH_TAXES_COMPONENTS_EUR_KWH
 from .static_tariff import ProfileInvalid, parse_static_profile
 
-__all__ = ["options_to_ui", "ui_to_options", "REGION_PRESETS",
+__all__ = ["options_to_ui", "ui_to_options", "ui_to_options_partial",
+           "REGION_PRESETS",
            "arbitrage_from_batteries", "DeriveError", "COUNT", "GROWN"]
 
 
@@ -32,6 +33,7 @@ class DeriveError(ValueError):
     def __init__(self, text, code="", field=""):
         super().__init__(text)
         self.code, self.field = code, field
+        self.keys = ()          # the option keys the failed derivation writes
 
 
 # The page model's inverter count, which show conditions read, and what adding
@@ -337,14 +339,31 @@ def options_to_ui(options: dict) -> dict:
 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})
-        else:
+            continue
+        try:
             out.update(encode(model, keep))
-    return out
+        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

@@ -186,7 +186,32 @@ def to_options(model: dict, stored: dict | None = None) -> dict:
     """The options blob for a posted page model. A value equal to the stored
     one is written as stored, in the stored key order, so a save that changed
     nothing writes an identical blob (the browser reads 3.0 as 3)."""
-    out = U.ui_to_options(model)
+    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]):
@@ -202,6 +227,21 @@ def derive_message(err: U.DeriveError) -> dict:
             "text": text}
 
 
+def derive_messages(errors, problems, notes, model, keys):
+    """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) for err in errors]
+            + anchors(kept, notes, model, keys))
+
+
 # --------------------------------------------------------------------------- #
 # Where a sentence goes on the page
 # --------------------------------------------------------------------------- #

goodwe_controller/app/validate.py

@@ -808,6 +808,14 @@ class ConfigRefused(Exception):
         super().__init__(problems[0] if problems else "configuration refused")
 
 
+def no_power_request_problem() -> str:
+    """Rule 1's refusal: no inverter to control. UX-15's setup-only mode
+    starts when this is the only refusal (app/setuponly.py)."""
+    return (f"{S('setpoint_entity')} is empty, so the add-on cannot control "
+            "the inverter. Set it to the ESPHome number entity for the "
+            "setpoint.")
+
+
 def validate_startup_config(opts: dict, dev_min=None, dev_max=None,
                             notes: list | None = None) -> list[str]:
     """Return the list of reasons this configuration must not be started.
@@ -828,9 +836,7 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None,
     # --- 1. an actuator to write to, and AT MOST ONE WRITER PER ACTUATOR -----
     writers = actuator_writers(opts)
     if not writers:
-        problems.append(
-            f"{S('setpoint_entity')} is empty, so the add-on cannot control the "
-            "inverter. Set it to the ESPHome number entity for the setpoint.")
+        problems.append(no_power_request_problem())
     # SAFETY-28. The §1.5 non-goal, graded on the writers rather than on the
     # count of option keys. Read `actuator_writers()` for why the old check went
     # green on the very config this one is here to refuse.
@@ -1704,6 +1710,14 @@ WATT_ENTITY_KEYS = (
     "p1_phase_export_entities", "batt_entity", "peak_forecast_entity")
 
 
+# The meter entities each `meter_source` reads through Home Assistant.
+METER_ENTITY_KEYS = {
+    "off": ("meter_entity",),
+    SOURCE_HA_SIGNED: ("p1_net_entity", "p1_phase_net_entities"),
+    SOURCE_HA: ("p1_import_entity", "p1_export_entity",
+                "p1_phase_import_entities", "p1_phase_export_entities")}
+
+
 def _entities_read(opts: dict) -> list[tuple[str, str, str]]:
     """(key, inverter name or "", entity id) for each entity the add-on reads
     with these options. Keys the chosen meter source or roster shape ignores
@@ -1716,12 +1730,7 @@ def _entities_read(opts: dict) -> list[tuple[str, str, str]]:
                 out.append((key, where, e.strip()))
 
     source = str(opts.get("meter_source") or "off").strip()
-    by_source = {"off": ("meter_entity",),
-                 SOURCE_HA_SIGNED: ("p1_net_entity", "p1_phase_net_entities"),
-                 SOURCE_HA: ("p1_import_entity", "p1_export_entity",
-                             "p1_phase_import_entities",
-                             "p1_phase_export_entities")}
-    for key in by_source.get(source, ()):
+    for key in METER_ENTITY_KEYS.get(source, ()):
         add(key, opts.get(key))
     entries = roster_entries(opts)
     if not entries:
@@ -1844,7 +1853,7 @@ def setup_checks(opts: dict, *, entities: dict | None, running=None,
     entity exists in Home Assistant (a write to a missing one is answered 200,
     SAFETY-77, so only the entity list can tell), the battery levels read, and
     prices are known. Tier "ok", "info", "warn", or "bad" for a missing power
-    request entity, which the wizard will not save. Reads nothing itself:
+    request or meter entity, which the wizard will not save. Reads nothing itself:
     `entities` is Home Assistant's list by id (None when it did not answer),
     `running` the options this process started with, `meter_now_w` its meter
     reading and `prices_known` how many of today's hours have a price.
@@ -1855,7 +1864,11 @@ def setup_checks(opts: dict, *, entities: dict | None, running=None,
         _advise(notes, "bad", ("setpoint_entity",), "Home Assistant is not "
                 "answering, so press Check again once it is back.")
     else:
-        _entity_notes(notes, opts, entities, bad=("setpoint_entity",))
+        # A missing meter entity is red too (UX-15): with the kettle test
+        # skipped, nothing else on the way to the save would catch it.
+        meter_keys = {k for keys in METER_ENTITY_KEYS.values() for k in keys}
+        _entity_notes(notes, opts, entities,
+                      bad=("setpoint_entity",) + tuple(sorted(meter_keys)))
     meter = _meter_check(notes, opts, entities, running, meter_now_w)
     batts = [_card_checks(notes, who, entry, entities)
              for who, entry in _cards(opts)]

goodwe_controller/app/web.py

@@ -31,6 +31,8 @@ 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.
 """
 
 import io
@@ -136,6 +138,10 @@ def build_app(controller, selfcfg=None) -> web.Application:
         except ValueError:
             raise web.HTTPBadRequest(text="expected JSON")
         what = body.get("action")
+        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)
         result = await controller.handle_action(what)
         if result is None:
             raise web.HTTPBadRequest(text=f"unknown action {what!r}")
@@ -149,14 +155,23 @@ def build_app(controller, selfcfg=None) -> web.Application:
         """(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."""
+        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):
-            return body, uipage.to_options(model, stored), model
+            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")
@@ -202,6 +217,8 @@ def build_app(controller, selfcfg=None) -> web.Application:
                 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)
 
@@ -219,11 +236,19 @@ def build_app(controller, selfcfg=None) -> web.Application:
         be a second opinion about a rule it does not own.
         """
         try:
-            _body, options, model = await _proposed(request)
-        except DeriveError as err:
-            return web.json_response({"problems": [], "by_key": {},
-                                      "unanchored": [], "notes": [],
-                                      "messages": [uipage.derive_message(err)]})
+            _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, notes=notes)
@@ -237,8 +262,10 @@ def build_app(controller, selfcfg=None) -> web.Application:
         if unread:
             payload["device_note"] = DEVICE_NOTE % ", ".join(sorted(set(unread)))
         if model is not None:
-            payload["messages"] = uipage.anchors(problems, notes, model,
-                                                 _keys_of(options))
+            payload["messages"] = (
+                uipage.derive_messages(errors, problems, notes, model,
+                                       _keys_of(options)) 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)]
@@ -286,10 +313,14 @@ def build_app(controller, selfcfg=None) -> web.Application:
                 return web.json_response({"error": str(err)}, status=502)
         try:
             body, options, model = await _proposed(request, stored_now)
-        except DeriveError as err:
+        except DeriveError:
+            model = posted["model"]
+            _opts, errors = uipage.to_options_partial(model, stored_now)
+            messages_ = [uipage.derive_message(e) for e in errors]
             return web.json_response(
                 {"kind": "invalid", "problems": [], "by_key": {},
-                 "unanchored": [], "messages": [uipage.derive_message(err)]},
+                 "unanchored": [], "messages": messages_,
+                 "steps": uipage.step_problems(messages_, model)},
                 status=422)
         expect = str(body.get("fingerprint") or "")
         try: