Merge release/1.0 (afd6af0) into SAFETY-73-per-unit-refusal

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

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

@@ -0,0 +1,69 @@
+# 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.
+
+## 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.