UX-08 2d: plain log lines, the rest of the status page, and DOCS

Every WARNING and ERROR line is one plain line of at most 25 words, with
no card ids, capitals or semicolons; the reasoning of the ten longest is
on a DEBUG line. The ux08 allowlist is empty and its cap is 0 (43 -> 0).

The status page: the month-peak and peak-guard rows, the stale-reading
row, the top table (Why, Tariff, Arbitrage, Shadow mode, labels), the
Stopped banner and the line under the buttons, which now shows the plain
hint of each event instead of the raw action log. The Supervisor question
at start logs one line with a real reason.

Refusals are counted as shown (labels expanded, long cases driven), seven
were shortened, the card and parse errors lost their internals, a blank
value reads "empty", and the panel no longer files inverters.max_w under
the flat max_w. Option names lose "(JSON)", the NL texts are checked too.

DOCS gets a glossary (control board, isolator, Developer Tools) and card
ids move from headings to a "For installers" line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LyR88rXETvwhTgx6yHE39p

goodwe_controller/app/messages.py

@@ -10,6 +10,7 @@ per title; the body ends with a link to it.
 import os
 import re
 from dataclasses import dataclass
+from datetime import datetime
 
 # Severity (STYLE.md section 3). An ALARM may use up to three sentences so
 # that no action a person must take is lost; everything else gets one.
@@ -335,13 +336,13 @@ def banner_circulating() -> str:
 
 
 def banner_site_direction() -> str:
-    return "Total command and meter point opposite ways. All inverters at 0 W."
+    return "Total power went the wrong way. All inverters at 0 W."
 
 
 def banner_direction(several: bool) -> str:
     if several:
-        return "An inverter's own power opposes its command. It is at 0 W."
-    return "Command and meter point opposite ways. Inverter set to 0 W."
+        return "An inverter's own power went the wrong way. Set to 0 W."
+    return "The meter saw power go the wrong way. Inverter at 0 W."
 
 
 def banner_not_delivering(units) -> str:
@@ -350,6 +351,10 @@ def banner_not_delivering(units) -> str:
     return f"{names(units)} {verb} not delivering. Control keeps running."
 
 
+def banner_stopped() -> str:
+    return "Stopped — the inverters are set to 0 W"
+
+
 def banner_shadow(latched: bool) -> str:
     """SAFETY-10: first in the cascade, never displaced by another banner.
 
@@ -502,9 +507,15 @@ def row_commands_refused(name, held_s, limit_s) -> str:
 
 
 def row_control(lo_w, hi_w, unit=None) -> str:
-    def w(v):
-        return "?" if v is None else signed_watts(v)
-    return f"Inverter control{for_unit(unit)}: ready, from {w(lo_w)} to {w(hi_w)}"
+    """The inverter's own range: charging below 0 W, giving power above it."""
+    head = f"Inverter control{for_unit(unit)}: ready"
+    if lo_w is None or hi_w is None or lo_w > 0 or hi_w < 0:
+        def w(v):
+            return "?" if v is None else signed_watts(v)
+        return f"{head}, from {w(lo_w)} to {w(hi_w)}"
+    if abs(float(lo_w)) == float(hi_w):
+        return f"{head}, up to {watts(hi_w)} each way"
+    return f"{head}, {watts(lo_w)} charging, {watts(hi_w)} giving"
 
 
 # Rows: the two loop alarms. The names are the notification titles, so the
@@ -541,9 +552,9 @@ def row_write_refused(unit=None) -> str:
 # Rows: the direction checks (SAFETY-02/30).
 def row_direction_trip(unit=None) -> str:
     """Per inverter. `unit` only at several inverters, graded on its own power."""
-    what = (f"{unit}: command and its own power point opposite ways, so it is"
-            if unit else "Command and meter point opposite ways, so the "
-                         "inverter is")
+    what = (f"{unit}'s own power went against what the add-on asked, so it is"
+            if unit else
+            "Grid power went against what the add-on asked, so the inverter is")
     return (f"{what} set to 0 W. Find out why, then start control. A restart "
             f"does not clear this.")
 
@@ -557,9 +568,9 @@ def row_direction_check(held_s, hold_s, unit=None) -> str:
 
 
 def row_site_direction_trip() -> str:
-    return ("Total command and meter point opposite ways, so every inverter is "
-            "set to 0 W. The cause is the total, not one inverter. Only starting "
-            "control clears this.")
+    return ("Grid power went against the add-on's total request, so every "
+            "inverter is set to 0 W. The cause is the total, not one inverter. "
+            "Only starting control clears this.")
 
 
 def row_site_direction_check(held_s, hold_s) -> str:
@@ -575,10 +586,15 @@ def row_circulating_trip() -> str:
             "0 W. The meter cannot see this. Only starting control clears this.")
 
 
+CHECK_CIRCULATING = "Check for inverters working against each other"
+
+
 def row_circulating_check(now_w, held_s, hold_s) -> str:
-    return ("Circulating power check: on"
-            + (f", now {watts(now_w)}" if now_w else "")
-            + (f", for {held_s:.0f} of {seconds(hold_s)}" if held_s else ""))
+    if held_s:
+        return (f"{CHECK_CIRCULATING}: {watts(now_w or 0)} for {held_s:.0f} of "
+                f"{seconds(hold_s)}")
+    return (f"{CHECK_CIRCULATING}: on"
+            + (f", now {watts(now_w)}" if now_w else ""))
 
 
 def row_one_inverter(check: str) -> str:
@@ -676,6 +692,184 @@ def row_pv_stray(n) -> str:
             f"entity in use")
 
 
+# Rows: this month's peak and the peak guard (UX-08 phase 2d). The detail
+# (the projection's reason, the store's state at start) is in the add-on log.
+def row_month_peak(peak_w, at, frac) -> str:
+    """`at` is the local start of the 15-minute period that set the peak."""
+    return (f"Month peak: {watts(peak_w)} on {at.day} {at:%b} at {at:%H:%M}, "
+            f"{frac * 100:.0f} % of the peak limit")
+
+
+def row_month_peak_none() -> str:
+    return "Month peak: none recorded yet this month"
+
+
+def row_month_peak_unreadable() -> str:
+    """The store did not answer. This is not a zero peak (TARIFF-01)."""
+    return "Month peak: cannot be read, so only the peak limit is used"
+
+
+def row_periods_measured(n) -> str:
+    """TARIFF-13's coverage figure. `n` is an int, or a text when unreadable."""
+    shown = n if isinstance(n, int) else "cannot be read"
+    return f"15-minute periods measured this month: {shown}"
+
+
+def row_peak_guard_idle(projected_w, limit_w, month_peak: bool) -> str:
+    """The projection first and the limit second (SAFETY-38's ordered pair)."""
+    limit = (f"this month's {watts(limit_w)} peak" if month_peak
+             else f"the {watts(limit_w)} peak limit")
+    return f"Peak guard: idle, heading for {watts(projected_w)}, under {limit}"
+
+
+def row_peak_guard_quiet() -> str:
+    return "Peak guard: idle"
+
+
+BLIND_WORDS = {
+    "no_block": "waiting for meter readings",
+    "gap": "meter readings have a gap",
+    "frozen": "meter reading is stuck",
+}
+
+
+def row_peak_guard_blind(why: str) -> str:
+    """`why` is a key of BLIND_WORDS. The battery may give power, not charge."""
+    return (f"Peak guard: {BLIND_WORDS[why]}, so the battery does not charge "
+            f"meanwhile")
+
+
+def row_peak_guard_on(floor_w, limit_w, *, shadow: bool = False) -> str:
+    if shadow:
+        return (f"Peak guard: would ask for {watts(floor_w)} to stay under "
+                f"{watts(limit_w)}")
+    return (f"Peak guard: asks the battery for {watts(floor_w)} to stay under "
+            f"{watts(limit_w)}")
+
+
+def row_battery_stuck(unit) -> str:
+    """SAFETY-37/56. A fact, not a verdict: the reading may be stuck, or the
+    battery may be refusing, and the add-on cannot tell which."""
+    return (f"{unit}: battery power reading stopped changing, so it is not used "
+            f"for now")
+
+
+# The top of the page: why the battery does what it does (the "Why" line).
+WHY_WINNER = {
+    "loop": "Keeping the grid near zero",
+    "peak": "Keeping under the peak limit",
+    "arbitrage": "Trading on the price",
+    "maintenance": "Battery maintenance",
+    "failsafe": "Safety stop, power went the wrong way",
+    "sign_site": "Safety stop, total power went the wrong way",
+    "circulation": "Safety stop, inverters worked against each other",
+    "stopped": "Control is stopped",
+    "inputs missing": "A reading is missing",
+    "no claim was made": "Nothing asked for power",
+}
+WHY_LIMIT = {
+    "peak(quarter peak)": "the peak limit",
+    "peak(blind)": "no charging while the meter is unclear",
+    "peak(SoC floor)": "the peak reserve",
+    "supervised": RATING,
+    "device": "the inverter's own limit",
+    "pack": "the battery level",
+    "reserve": "the battery reserve",
+    "maintenance": "battery maintenance",
+}
+
+
+def why(winner, target_w, bound_by=None, *, contradiction=False) -> str:
+    """`winner` is the arbiter's winning source, or its reason for the two
+    that share a source ("stopped", "inputs missing", "no claim was made").
+    `bound_by` is `Resolution.bound_by`, e.g. "peak(quarter peak)"."""
+    if contradiction:
+        return "Two limits clash, so every inverter is set to 0 W"
+    out = f"{WHY_WINNER.get(winner, 'Other')}: {signed_watts(target_w)}"
+    if bound_by:
+        limit = WHY_LIMIT.get(bound_by) or WHY_LIMIT.get(
+            str(bound_by).split("(")[0], "another limit")
+        out += f", held back by {limit}"
+    return out
+
+
+def why_waiting(missing_s) -> str:
+    """A reading went missing a moment ago: control holds and waits."""
+    return f"A reading is missing for {seconds(missing_s)}, control waits"
+
+
+# The last thing that happened, shown under the buttons. The add-on keeps its
+# own technical record of each event (`Controller.events`); the page shows
+# these words instead. Every `log_event()` call names one (test_messages.py).
+HINTS = {
+    "control_started": "Control started",
+    "control_stopped": "Control stopped",
+    "settings_saved": "Settings saved, they apply after a restart",
+    "restart_requested": "Restart requested from the settings page",
+    "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",
+    "battery_stuck": "{unit}: battery power reading stopped changing",
+    "battery_back": "{unit}: battery power reading is used again",
+    "bad_value": "The add-on made an invalid power value, inverters set to 0 W",
+    "write_blocked": "{unit}: a power request was blocked, it is set to 0 W",
+    "all_blocked": "A power request was blocked, inverters set to 0 W",
+    "write_cut": "{unit}: " + T_OUTPUT_CLAMP.lower(),
+    "write_slow": "{unit}: the inverter answered too slowly, trying again",
+    "direction": "{unit}: power went the wrong way, it is set to 0 W",
+    "site_direction": "Total power went the wrong way, inverters set to 0 W",
+    "circulating": T_CIRCULATING + ", all set to 0 W",
+    "not_delivering": T_NOT_DELIVERING,
+    "peak_on": "Peak guard started",
+    "peak_off": "Peak guard idle",
+    "peak_blind": "Peak guard cannot read the meter well",
+    "peak_saturated": T_PEAK_SATURATED,
+    "peak_reserve": T_PEAK_RESERVE,
+    "meter_frozen": T_METER_FROZEN,
+    "power_too_high": T_OUTPUT_CLAMP,
+    "not_keeping_up": T_LOOP_BOUND,
+    "trade_charge": "Trading: charging while the price is low",
+    "trade_give": "Trading: giving power while the price is high",
+    "trade_off": "Trading: waiting for a better price",
+    "split": "The power split between inverters changed",
+    "clash": "Two limits clash, inverters set to 0 W",
+    "no_setpoint": "An inverter has no “Setpoint entity”, inverters stay at 0 W",
+    "unit_dropped": "{unit} left out of control, the others take its share",
+    "units_back": "Every inverter is back in control",
+    "unmet": "The inverters cannot give {w} of the power asked",
+    "unmet_gone": "The inverters can give all the power asked again",
+    "shadow_on": "Shadow mode on, inverters stay at 0 W",
+    "shadow_off": "Shadow mode off, the add-on controls the battery",
+    "shadow_decision": "Shadow mode: would ask the battery for {sw}",
+    "refused": "Settings refused, the add-on log shows why",
+    "inputs_missing": "A reading is missing, inverters set to 0 W",
+    "inputs_back": "All readings are back",
+    "stop_cleared": "{unit}: safety stop cleared by starting control",
+    "site_stop_cleared": "Safety stop cleared by starting control",
+    "not_delivering_cleared": "{unit}: not-delivering alarm cleared",
+    "maintenance": "Battery maintenance: {phase}",
+    "maint_paused": "Maintenance charging paused to stay under the peak limit",
+}
+
+
+def hint(key: str, **kw) -> str:
+    """The plain words for one event. `w` is formatted as watts, `sw` as
+    watts with their sign (positive gives power, negative charges)."""
+    if "w" in kw:
+        kw["w"] = watts(kw["w"])
+    if "sw" in kw:
+        kw["sw"] = signed_watts(kw["sw"])
+    return HINTS[key].format(**kw)
+
+
+def hint_samples() -> list:
+    """`(key, text)` for every hint, rendered, for the test."""
+    kw = {"n": 2, "unit": "inverter-b", "w": 1200, "sw": -1200,
+          "phase": "drain"}
+    return [(k, hint(k, **{f: kw[f] for f in kw if "{" + f + "}" in v}))
+            for k, v in HINTS.items()]
+
+
 RED, AMBER, GREEN = "bad", "warn", "ok"
 
 
@@ -769,6 +963,24 @@ def status_samples() -> list:
         ("row_pv_negative", AMBER, row_pv_negative(2, 3, -1500, False)),
         ("row_pv_negative", AMBER, row_pv_negative(1, 1, -1500, True)),
         ("row_pv_stray", AMBER, row_pv_stray(2)),
+        ("banner_stopped", None, banner_stopped()),
+        ("row_control", GREEN, row_control(-4000, 5000, "inverter-b")),
+        ("row_month_peak", GREEN, row_month_peak(
+            4998, datetime(2026, 8, 12, 19, 15), 0.83)),
+        ("row_month_peak_none", GREEN, row_month_peak_none()),
+        ("row_month_peak_unreadable", AMBER, row_month_peak_unreadable()),
+        ("row_periods_measured", GREEN, row_periods_measured(120)),
+        ("row_periods_measured", GREEN, row_periods_measured("unreadable")),
+        ("row_peak_guard_idle", GREEN, row_peak_guard_idle(1300, 2500, True)),
+        ("row_peak_guard_idle", GREEN, row_peak_guard_idle(1300, 2500, False)),
+        ("row_peak_guard_quiet", GREEN, row_peak_guard_quiet()),
+        *(("row_peak_guard_blind", AMBER, row_peak_guard_blind(k))
+          for k in BLIND_WORDS),
+        ("row_peak_guard_on", AMBER, row_peak_guard_on(1200, 2500)),
+        ("row_peak_guard_on", AMBER, row_peak_guard_on(1200, 2500,
+                                                       shadow=True)),
+        ("row_battery_stuck", AMBER, row_battery_stuck("inverter-b")),
+        ("row_circulating_check", GREEN, row_circulating_check(0, 0, 60)),
     ]
 
 
@@ -843,6 +1055,27 @@ LABELS = {
 }
 
 
+def shown(value) -> str:
+    """A setting's value inside a refusal: `'abc'`, `5`, or `empty` for a value
+    that is missing or blank, never Python's `None` (UX-08 2d)."""
+    if value is None or (isinstance(value, str) and not value.strip()):
+        return "empty"
+    return repr(value)
+
+
+def not_valid(option: str, err) -> str:
+    """A setting whose text does not parse, without the parser's own words:
+    `static_profile is not valid near character 6` (UX-08 2d)."""
+    pos = getattr(err, "pos", None)
+    if isinstance(pos, int):
+        return f"{option} is not valid near character {pos + 1}"
+    return f"{option} is not valid"
+
+
+# The units a formula's "units" field may name, as a reader writes them.
+UNIT_WORDS = {"c_eur_per_kwh": "c/kWh", "eur_per_kwh": "EUR/kWh"}
+
+
 def setting(key: str, unit: str = "") -> str:
     """`max_w` -> `“Inverter rating” (max_w)`. For one inverter in a list it is
     `“Inverter rating” for inverter-b (inverters.max_w)`, so the config panel