UX-10 review: the line as logged gets the red-alarm shape, clamp lines at 30 words, plain HA 400

Part 6 checked the quoted reason alone, so title + reason + tails logged
as 4+ sentences. It now also checks the whole line (at most 3 sentences,
none over 30 words); 25 lines failed and are rewritten (one-sentence
wrappers, two-sentence circulation and peak reasons, STALE_READING's
fixed limits on a DEBUG line). The clamp lines for one inverter are
pinned at 30 words with OUTPUT_CLAMP and the numbers kept. Home
Assistant's bare '400: Bad Request' while it loads becomes one plain
line; still WARNING, throttled, a failed write.

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

.gitea/infra-pin

@@ -0,0 +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").
+ecd3864d9376a990c267dfb399eb2dae4e56c76b

.gitea/workflows/checks.yml

@@ -3,12 +3,35 @@
 # of real coverage including a wall-clock cadence test, and not one machine ever
 # ran them. Every merge here was a human reading a diff.
 #
-# ⚠️ NO `paths:` FILTER, AND ITS ABSENCE IS LOAD-BEARING. Branch protection on
-# release/1.0 requires the context `checks / unit (pull_request)`. Gitea leaves a
-# required context it never receives PENDING forever, so the moment this workflow
-# learns to sit a PR out, that PR becomes unmergeable. Condition a STEP if you
+# ⚠️ NO EVENT FILTER OF ANY KIND - NO `paths:`, AND SINCE CI-9 NO `branches:`
+# EITHER - AND THAT ABSENCE IS LOAD-BEARING. Branch protection on release/1.0
+# requires the context `checks / unit (pull_request)`. Condition a STEP if you
 # must; never the workflow.
 #
+# ⚠️ CI-01 WROTE THE REASON DOWN WRONG, AND THE WRONG REASON WAS THE SAFE-
+# SOUNDING ONE. It said an unreceived required context sits PENDING forever, so
+# a sat-out pull request becomes unmergeable - annoying, but fail-safe. That is
+# not what this Gitea does. MEASURED on Gitea 1.27.3, 2026-09-19, throwaway
+# PR #94: when a workflow exists but its event filter does not match, Gitea does
+# not stay silent. It POSTS the required context itself, with state `skipped`:
+#
+#   GET /api/v1/repos/admin/goodwe-addon/commits/<head sha>/statuses
+#     [{"status":"skipped","context":"checks / unit (pull_request)",
+#       "description":"Skipped","target_url":""}]      <- no run, no job, no url
+#
+#   GET /api/v1/repos/admin/goodwe-addon/commits/<head sha>/status
+#     {"state":"success","total_count":1}              <- the rollup LAUNDERS it
+#
+# and Gitea's merge gate accepts it. Same PR, same head sha, one status on it
+# and that status a skip, POST .../pulls/94/merge answered 409 `head out of
+# date` - the 409 being a deliberately wrong `head_commit_id` in the probe, i.e.
+# the request had ALREADY CLEARED BRANCH PROTECTION. The control, a required
+# context with no status at all, answered 405 `Not all required status checks
+# successful`. So the true failure mode is the exact inverse of the one written
+# here before: sitting a pull request out does not make it unmergeable, it makes
+# it MERGEABLE WITHOUT EVER BEING TESTED, and the badge says success while it
+# happens. Fail-open, not fail-closed. Do not reintroduce a filter here.
+#
 # ⚠️ THE RUNNER IS SHARED WITH THE OTHER REPO'S RIG. `goodwe-runner` on
 # 192.168.2.147 carries the labels `self-hosted` and `goodwe-rig` and is
 # registered `:host`, and it is the only runner there is - so this job wears the
@@ -23,9 +46,116 @@
 # that step; a green from this workflow is a claim about content that can land.
 name: checks
 
+# ⚠️ CI-9: `pull_request:` TAKES NO `branches:` LIST, ON PURPOSE. It used to
+# read `branches: [release/1.0, master]`, which meant a STACKED pull request -
+# one whose base is another feature branch rather than a release branch - did
+# not match, and so was skipped, laundered to `success`, and mergeable untested
+# by the mechanism described at the top of this file.
+#
+# ⚠️ AND RETARGETING DID NOT REPAIR IT, WHICH IS WHAT MADE THIS P1. The skip is
+# a COMMIT STATUS ON THE HEAD SHA, not a property of the pull request, so moving
+# the base afterwards leaves it exactly where it was. Observed live on PR #93
+# (2026-09-19): retargeted TEL-10 -> release/1.0, and the 10:05:00 `skipped`
+# stayed attached to head a6af332 with the rollup still reading success. It was
+# caught by a human who forced a real execution by reopening the pull request
+# (run 799, 10:56). Reproduced deliberately on throwaway PR #94: retargeted onto
+# a branch carrying a byte-identical copy of release/1.0's protection rule, and
+# the single `skipped` status survived the retarget unchanged - no new run, no
+# new status - and still cleared the gate.
+#
+# ⚠️ WHY NOT FIX THIS AT THE GATE INSTEAD, which would be the better place. It
+# cannot be done. Gitea's branch protection cannot express "this context must be
+# SUCCESS" as opposed to "this context must be PRESENT AND NOT FAILING". The
+# whole of its status-check vocabulary is two fields - `enable_status_check`
+# (bool) and `status_check_contexts` (a list of globs MATCHING CONTEXT NAMES) -
+# confirmed against this server's own schema at /swagger.v1.json, definitions
+# EditBranchProtectionOption and CreateBranchProtectionOption. There is no field
+# for the required STATE anywhere in either. The success/skip comparison lives
+# in Gitea's compiled code, so the only lever left is upstream of it: make sure
+# the context is never a skip in the first place. Hence this block.
+#
+# ⚠️ WHAT THIS COSTS, stated honestly, because it is a real trade. Every pull
+# request now runs the full suite, including the intermediate steps of a stack
+# that nobody intends to merge on its own. A run is ~8 minutes wall clock
+# (run 799: 7m55s) on a runner that is `capacity: 1` and shared with the other
+# repo's rig, so each extra run is ~8 minutes of slot that a rig campaign then
+# queues behind.
+#
+# SCALE OF THE NEW WORK, re-derived from the API and stated with its denominator,
+# because the first version of this paragraph had a made-up one. Counting the 93
+# pull requests that predate this ticket (#1..#93; CI-9's own #94..#98 excluded,
+# and note /pulls caps a page at 50, so this needs paging to see at all): 92 were
+# opened against release/1.0 and would have run anyway, and exactly ONE was
+# stacked - #2, TEL-01 -> SAFETY-04, closed unmerged, 2026-08-24. No pull request
+# has ever targeted `master`, so half the old filter was dead from the start.
+#
+# ⚠️ THAT 92 IS AN UPPER BOUND, NOT A CENSUS, and the reason is this very bug.
+# The API reports a pull request's CURRENT base, so one that was opened stacked
+# and later retargeted is recorded against its final base and is invisible here.
+# #93 is precisely that case - opened 2026-09-19T10:05:00 on TEL-10, retargeted,
+# merged into release/1.0 at 11:05:26 the same morning, under three hours before
+# CI-9 was opened - and it counts in the 92. So the true historical stacking rate
+# is somewhere above 1/93, and unmeasurable from here.
+#
+# The bill is therefore small today and grows with however much stacking the team
+# adopts. It is worth paying: the alternative is that the cheap case stays
+# untested and indistinguishable from the tested one.
+#
+# ⚠️ THIS DOES NOT CHANGE GITEA'S ACCEPTANCE OF A `skipped` REQUIRED CONTEXT -
+# that half is in its compiled code and is not reachable from this repository.
+# The CONSEQUENCE, though, is very largely closeable from here, and is closed:
+# after this edit there is nothing in this repository that produces a skip -
+# there is exactly one workflow file, it now has no event filter of any kind,
+# and the other candidate cause was MEASURED and is not one. The `guard the
+# trigger` step below then keeps it that way mechanically rather than by asking
+# the next editor to read this comment.
+#
+# ⚠️ READ THE BLIND SPOTS ON THAT STEP BEFORE TRUSTING THE SENTENCE ABOVE.
+# "Mechanically" holds only for a reintroduced filter that still names the
+# PR's own base. For blind spots 1 and 3 the defence IS this comment, because
+# the guard lives inside the workflow that a filter makes Gitea skip. Blind
+# spot 3 is the one that matters: a filter naming a branch THIS pull request
+# does not target is itself skipped, lands green and untested, and then every
+# subsequent pull request the filter DOES NOT NAME is skipped too. That is the
+# gate off, silently.
+#
+# ⚠️ THAT DIRECTION IS THE WHOLE POINT AND IT IS EASY TO WRITE BACKWARDS. A
+# pull request that MATCHES the filter still runs; it is the one the filter
+# excludes that Gitea sits out, reports `skipped`, and the rollup launders
+# into `success`. An earlier draft of this very clause said "matching it is
+# skipped", which is the inverse of the measurement and contradicted the
+# paragraph directly below.
+#
+# ⚠️ AND THE DANGEROUS ONE IS NOT `branches: [main]`, WHICH AT LEAST LOOKS
+# WRONG. It is `branches: [release/1.0]`, which looks like tightening onto the
+# protected branch and is what a careful person would write. Every day-to-day
+# pull request still runs and still goes green, so nothing appears broken -
+# and the only thing switched off is the `release/1.0` -> `master` release
+# PR, i.e. the one whose content reaches an installed system. SEC-2 made that
+# PR the mandated release path (docs/RELEASE.md), so this is now a live route
+# rather than a hypothetical one.
+#
+# Closing it needs a SECOND permanently unfiltered workflow posting its own
+# context, with that context added to the `status_check_contexts` of BOTH
+# `release/1.0` AND `master` - both carry the rule since SEC-2, and adding it
+# to one alone leaves the hole open on the other. A forge change, with the
+# owner.
+#
+# THE MEASUREMENT, because the obvious guess is wrong and was nearly written
+# here as fact. A skip-ci keyword in a commit message (`[skip ci]`, `[ci skip]`,
+# `[no ci]`, `[skip actions]`, `[actions skip]`) does NOT behave like a filter
+# miss. On throwaway PR #94, head b36effb, commit subject ending `[skip ci]`:
+#
+#   .../commits/b36effb/statuses   ->  []                  <- NO status, not a skip
+#   .../commits/b36effb/status     ->  {"state":"pending"} <- so the rollup is pending
+#   POST .../pulls/94/merge        ->  405 Not all required status checks successful
+#
+# i.e. skip-ci is FAIL-CLOSED - it withholds the context entirely, which is the
+# pending-forever behaviour CI-01's header wrongly attributed to a filter miss.
+# It blocks the merge rather than laundering it, so it needs no fix and no
+# app.ini change. Only the filter miss ever posted a `skipped`.
 on:
   pull_request:
-    branches: [release/1.0, master]
   workflow_dispatch:
 
 # ⚠️ NO `concurrency:` BLOCK, AND ITS ABSENCE IS AS LOAD-BEARING AS THE MISSING
@@ -156,8 +286,9 @@ jobs:
         run: |
           set -eu
           rm -rf "$WS" && mkdir -p "$WS/goodwe-addon" && cd "$WS/goodwe-addon"
-          git init -q .
-          git remote add origin "$(echo "$URL" | sed "s#://#://x-access-token:${TOKEN}@#")"
+          git init -q . && git remote add origin "$URL"
+          # Token as an env-set header: not in argv or .git/config (TOOL-9).
+          export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: token $TOKEN"
           if [ -n "$PRNUM" ]; then
             # Two fetches, not one, so that a failure to reach either ref fails
             # HERE with the ref in the message, rather than inside the merge
@@ -224,6 +355,165 @@ jobs:
             exit 1
           fi
 
+      # ⚠️ THE GUARD ON THE TRIGGER. THIS STEP EXISTS BECAUSE PROSE ALREADY
+      # FAILED IN THIS FILE, ONCE, FOR TWENTY DAYS.
+      #
+      # `git show 9c1a23328a` is CI-01's first commit. It shipped the header
+      # "⚠️ NO `paths:` FILTER, AND ITS ABSENCE IS LOAD-BEARING" and the line
+      # `branches: [release/1.0, master]` IN THE SAME COMMIT, EIGHTEEN LINES
+      # APART. The comment forbade one kind of event filter while the code
+      # directly above the job carried another, and nobody caught it through 84
+      # merges until the gate let a stacked pull request through. So the whole of
+      # CI-9's fix rests on an invariant - "checks.yml has no event filter" -
+      # that has already been silently violated in this exact file by the person
+      # who wrote the warning against violating it. A louder comment is not a
+      # remedy for that. A red step is.
+      #
+      # WHY THIS CAN WORK AT ALL, given CI-9 rejected the card's option 3 (a step
+      # that detects its own workflow having been skipped) as impossible. That
+      # option is impossible because a skipped workflow runs no steps, so there
+      # is nothing alive to notice. This is the different, tractable case: it
+      # fires on the pull request that REINTRODUCES a filter, and it does so
+      # whenever the filter being reintroduced STILL NAMES THAT PULL REQUEST'S
+      # OWN BASE - the ordinary case, because a filter put back by hand names
+      # the release branch people are actually targeting. The edit then has to
+      # get past this step before it can start causing skips. It is a ratchet,
+      # not a skip detector.
+      #
+      # ⚠️ AND IT IS THE HEAD'S WORKFLOW THAT DECIDES WHETHER ANYTHING RUNS, NOT
+      # THE BASE'S. An earlier draft of this comment claimed the reintroducing
+      # pull request "is still graded by the unfiltered workflow which is on the
+      # base today". That was wrong, it contradicted the checkout step's own note
+      # a few lines below, and the error was not cosmetic: it made this step
+      # sound like an unconditional ratchet, which is exactly the false comfort
+      # CI-9 exists to stamp out. MEASURED on PR #101 - head carrying a filter
+      # that excludes the base, base carrying the unfiltered workflow - and the
+      # result was no run at all, the context posted `skipped`, the rollup
+      # reading `success`, and the gate CLEARED (409). Gitea takes the workflow
+      # file from refs/pull/<n>/head, so a head that filters itself out is simply
+      # never graded, and nothing on the base can reach out and stop it. That is
+      # what blind spot 3 below is made of.
+      #
+      # WHAT IT INSPECTS is the MERGED tree in $WS - the content that would
+      # actually land on the base - not the branch tip and not the copy of this
+      # file that Gitea used to decide whether to run. Those are three different
+      # trees here (see the long note on the checkout step) and only the merged
+      # one is the thing being authorised.
+      #
+      # ⚠️ THREE ACKNOWLEDGED BLIND SPOTS. NOT ONE OF THEM IS CLOSEABLE FROM
+      # INSIDE THIS FILE, and the reason is the same in all three: each is a case
+      # where THIS WORKFLOW IS ITSELF THE THING THAT GETS SKIPPED, and a guard
+      # that lives inside a skipped workflow does not run. Closing them needs a
+      # SECOND, permanently unfiltered workflow whose own context is added to
+      # release/1.0's `status_check_contexts`, so that something survives to
+      # report when this file is sat out. That is a forge change and the
+      # repository owner's decision; it is being put to them separately and is
+      # deliberately NOT held as a blocker on CI-9.
+      #
+      #   1. A reintroduced `paths:` filter crafted to exclude the reintroducing
+      #      pull request's OWN diff would skip that pull request, so this step
+      #      would not run to object to it.
+      #
+      #   2. An edit that lands on a feature branch through a stacked pull
+      #      request is graded by the HEAD's workflow, so a filter already
+      #      present in the head hides the edit from this step - until that
+      #      branch is proposed for release/1.0, where (unless it is case 3) the
+      #      base matches the reintroduced filter and this step runs and bites.
+      #      Caught at the release boundary, which is the boundary that matters.
+      #
+      #   3. ⚠️ THE WORST OF THE THREE, AND WORSE THAN BOTH OF THE OTHERS PUT
+      #      TOGETHER: a reintroduced `branches:` filter that simply DOES NOT
+      #      NAME THE BASE escapes this step entirely, because the pull request
+      #      carrying it is itself skipped. It takes no craft and no malice to
+      #      write - `branches: [main]` copied out of a GitHub template, or a
+      #      tidy-up to `[master]`, a branch that NO pull request in this
+      #      repository's history has ever targeted - and it arrives as a
+      #      skipped, laundered, untested merge into release/1.0.
+      #
+      #      What makes it categorically worse is what happens the moment after.
+      #      Once that file is ON release/1.0, every subsequent pull request is
+      #      graded against it and every one of them is skipped too. This is not
+      #      the stacked case leaking through a crack; it is the gate off
+      #      completely, for everything, silently, with every badge green. The
+      #      only thing standing between the repository and that state today is
+      #      a human reading this file - which is precisely the kind of defence
+      #      this step exists because it has already failed once (9c1a23328a).
+      #
+      # It is deliberately a FAILURE and not a warning: a warning would leave
+      # the required context green, which is the precise defect CI-9 is about.
+      - name: guard the trigger - refuse a checks.yml that has regained an event filter
+        run: |
+          set -eu
+          f="$WS/goodwe-addon/.gitea/workflows/checks.yml"
+          test -f "$f" || { echo "checks.yml is missing from the merged tree."; exit 1; }
+          # Walk the top-level `on:` block of the MERGED file. Full-line comments
+          # at column 0 are skipped outright - this file's own prose quotes
+          # `paths:` and `branches:` many times and must not trip its own guard -
+          # and an inline `#` is trimmed from any line that is kept.
+          bad=$(awk '
+            function scan(t) {
+              sub(/#.*/, "", t)
+              if (t ~ /(^|[^A-Za-z0-9_-])(branches|branches-ignore|paths|paths-ignore|tags|tags-ignore|types)[[:space:]]*:/)
+                return 1
+              return 0
+            }
+            /^[[:space:]]*#/ { next }
+            /^("on"|'"'"'on'"'"'|on)[[:space:]]*:/ {
+              inon = 1
+              rest = $0; sub(/^[^:]*:/, "", rest)
+              if (scan(rest)) print NR ": " $0
+              next
+            }
+            inon == 1 {
+              if ($0 ~ /^[[:space:]]*$/) next
+              if ($0 ~ /^[[:space:]]/) { if (scan($0)) print NR ": " $0; next }
+              inon = 0
+            }
+          ' "$f")
+          if [ -n "$bad" ]; then
+            echo "REFUSED: checks.yml has regained an event filter in its \`on:\` block."
+            echo "$bad"
+            echo
+            echo "  A filter means some pull request stops matching this workflow. Gitea does"
+            echo "  not stay silent about a workflow it sits out - it posts the required context"
+            echo "  \`checks / unit (pull_request)\` itself with state \`skipped\`, the combined"
+            echo "  status rolls that up as \`success\`, and the merge gate ACCEPTS it. That is"
+            echo "  CI-9: a pull request merged on a workflow that never ran a step. It was"
+            echo "  reproduced by merging PR #96 for real through a protected branch."
+            echo
+            echo "  Branch protection cannot save you here - it can require that a context is"
+            echo "  PRESENT, never that it is SUCCESS - so the filter is the whole defence."
+            echo "  If you genuinely need to narrow what runs, condition a STEP, never the"
+            echo "  workflow. See the \`on:\` block's comments for the measurements."
+            exit 1
+          fi
+          echo "OK: the \`on:\` block of the merged checks.yml carries no event filter."
+
+      # CI-12: the infra repo at the ONE pinned commit in .gitea/infra-pin (read
+      # from the merged tree), as the sibling test_freeze.py looks for. Any
+      # failure here fails the job; the tests step below refuses the stub.
+      - name: check out admin/goodwe at the pin in .gitea/infra-pin
+        env:
+          URL: ${{ github.server_url }}/admin/goodwe.git
+          # Read access to admin/goodwe only; this job's own token cannot see it.
+          TOKEN: ${{ secrets.INFRA_READ_TOKEN }}
+        run: |
+          set -eu
+          # `|| true`: under pipefail a missing or comment-only pin would skip the FAIL line (TOOL-9).
+          PIN=$(grep -v '^#' "$WS/goodwe-addon/.gitea/infra-pin" | tr -d '[:space:]') || true
+          echo "$PIN" | grep -Eq '^[0-9a-f]{40}$' || { echo "FAIL: .gitea/infra-pin holds '$PIN', not a full 40-hex SHA."; exit 1; }
+          test -n "$TOKEN" || { echo "FAIL: secret INFRA_READ_TOKEN is not available to this run (a fork PR?)."; exit 1; }
+          rm -rf "$WS/goodwe" && mkdir -p "$WS/goodwe" && cd "$WS/goodwe"
+          git init -q .
+          # The token goes in a header via env: not in argv, and not in .git/config,
+          # which is mounted into the tests' container and outlives a failed job.
+          GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: token $TOKEN" \
+            git fetch -q "$URL" "$PIN" || { echo "FAIL: could not fetch admin/goodwe at $PIN."; exit 1; }
+          git -c advice.detachedHead=false checkout -qf FETCH_HEAD
+          test "$(git rev-parse HEAD)" = "$PIN"
+          test -f sim/hwsim.py || { echo "FAIL: admin/goodwe@$PIN has no sim/hwsim.py."; exit 1; }
+          echo "infra: admin/goodwe @ $(git log --oneline -1)"
+
       - name: build the test image (shipped deps, from apk - see .gitea/ci/Dockerfile)
         run: |
           set -eu
@@ -244,16 +534,9 @@ jobs:
       # shorter timeout - a 60 s limit was tried during CI-01 and reported
       # exactly the false hang the docstring predicts.
       #
-      # ⚠️ WHAT THIS RUN DOES NOT COVER, stated because a pass here would
-      # otherwise over-claim. test_freeze.py's third section wants the infra
-      # repo's `sim/hwsim.py` to drive a real HTTP meter through the real
-      # transport. admin/goodwe is PRIVATE (checked via the API) and this
-      # workflow's GITHUB_TOKEN is minted for THIS repository only, so hwsim is
-      # absent here and `find_hwsim()` returns None. The rest of the file runs
-      # and passes. It does so SILENTLY - the file prints nothing to say the
-      # hwsim section was skipped - so "test_freeze.py: PASS" below is a weaker
-      # claim than it looks. That belongs to whoever owns test_freeze.py next;
-      # naming it here is the least this gate can do about it.
+      # test_freeze.py part 3 runs against the real `sim/hwsim.py` from the
+      # checkout above; GOODWE_REQUIRE_HWSIM=1 makes it fail rather than use its
+      # stub (CI-12). Lines a test prints with a `CI: ` prefix are echoed on PASS.
       # ⚠️ PYTHONDONTWRITEBYTECODE=1 IS BELT AND BRACES, NOT A FIX FOR A LIVE
       # HOLE. TEST-15 measured this runner's actual exposure and found none: the
       # checkout below is bind mounted `:ro`, so the interpreter physically
@@ -269,7 +552,7 @@ jobs:
       - name: the add-on's own tests
         run: |
           set -eu
-          docker run --rm -e PYTHONDONTWRITEBYTECODE=1 -v "$WS:/w:ro" goodwe-addon-checks:1 sh -eu -c '
+          docker run --rm -e PYTHONDONTWRITEBYTECODE=1 -e GOODWE_REQUIRE_HWSIM=1 -v "$WS:/w:ro" goodwe-addon-checks:1 sh -eu -c '
             cd /w/goodwe-addon/goodwe_controller
             set -- test_*.py
             if [ "$1" = "test_*.py" ]; then
@@ -282,6 +565,7 @@ jobs:
               start=$(date +%s)
               if python3 "$f" > /tmp/out 2>&1; then
                 echo "PASS  $f  ($(( $(date +%s) - start ))s)"
+                grep "^CI: " /tmp/out || true
               else
                 echo "FAIL  $f  ($(( $(date +%s) - start ))s)"
                 tail -40 /tmp/out

.gitea/workflows/infra-pin.yml

@@ -0,0 +1,46 @@
+# CI-12: goes red when admin/goodwe release/1.0 has moved past .gitea/infra-pin.
+# It runs on add-on activity only; admin/goodwe's own `addon-pin` workflow
+# covers a move of release/1.0 there. Deliberately NOT a required check: it
+# reports; `checks / unit` stays the only gate. How to bump: README.md,
+# "CI and the infra pin".
+name: infra-pin
+
+on:
+  pull_request:
+  push:
+    branches: [release/1.0]
+
+jobs:
+  fresh:
+    runs-on: [self-hosted, goodwe-rig]
+    timeout-minutes: 30   # seconds of work; the rest is queueing for the shared slot
+    steps:
+      - name: compare .gitea/infra-pin with admin/goodwe release/1.0
+        env:
+          SELF: ${{ github.server_url }}/${{ github.repository }}.git
+          INFRA: ${{ github.server_url }}/admin/goodwe.git
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          INFRA_TOKEN: ${{ secrets.INFRA_READ_TOKEN }}   # admin/goodwe is private
+        run: |
+          set -eu
+          D=$(mktemp -d) && trap 'cd / && rm -rf "$D"' EXIT && cd "$D"
+          git init -q .
+          # The pin of the commit this event is about (the PR head, or the push).
+          # Token as an env-set header: not in argv or .git/config (TOOL-9).
+          GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: token $TOKEN" \
+            git fetch -q --depth 1 "$SELF" "$GITHUB_SHA" || { echo "FAIL: could not fetch $GITHUB_SHA here."; exit 1; }
+          # `|| true`: under the runner's pipefail a missing or comment-only pin
+          # would stop here on git's error instead of the FAIL line below (TOOL-9).
+          PIN=$(git show FETCH_HEAD:.gitea/infra-pin | grep -v '^#' | tr -d '[:space:]') || true
+          test -n "$PIN" || { echo "FAIL: .gitea/infra-pin is missing at $GITHUB_SHA, or holds only comments."; exit 1; }
+          test -n "$INFRA_TOKEN" || { echo "FAIL: secret INFRA_READ_TOKEN is not available to this run (a fork PR?)."; exit 1; }
+          # Header via env, as in checks.yml: the token stays out of argv.
+          HEAD=$(GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: token $INFRA_TOKEN" \
+            git ls-remote "$INFRA" refs/heads/release/1.0 | cut -f1) || true
+          test -n "$HEAD" || { echo "FAIL: could not read admin/goodwe release/1.0."; exit 1; }
+          if [ "$PIN" != "$HEAD" ]; then
+            echo "STALE: .gitea/infra-pin is $PIN but admin/goodwe release/1.0 is $HEAD."
+            echo "       Test against $HEAD and bump the pin (README.md, \"CI and the infra pin\")."
+            exit 1
+          fi
+          echo "OK: .gitea/infra-pin $PIN is admin/goodwe release/1.0 HEAD."

FIELD-GUIDE.md

@@ -4,6 +4,10 @@ The guide technicians carry is the PDF:
 
 **`docs/GoodWe-RS485-Field-Guide.pdf`** — 10 pages, A4, print it double-sided.
 
+⚠️ **Outdated: it is v0.1.0.** Its `slew_w` row is corrected in `build_guide.py`
+and `field-guide.html`, but the PDF has not been rebuilt (see below). Where the
+guide disagrees with `goodwe_controller/DOCS.md`, DOCS.md wins.
+
 It covers, in the order the work is done: pre-visit checks, hardware, firmware,
 add-on install and configuration, how to read the Web UI, the six commissioning
 gates, the e-stop (and the statement a site without one must sign), proving a
@@ -18,7 +22,8 @@ copy cannot drift from the PDF someone is holding in a cellar.
 python3 docs/build_guide.py     # regenerates field-guide.html and the PDF
 ```
 
-Requires Chrome or Chromium (used headless for print-to-PDF). Screenshots live
+Requires Chrome or Chromium (used headless for print-to-PDF); `CHROME` in the
+script is a Windows path, so edit it on any other machine. Screenshots live
 in `docs/img/` and are base64-embedded, so `field-guide.html` is standalone.
 
 ⚠️ **Every section must stay under the A4 printable height** (1039 px at 96 dpi

README.md

@@ -30,9 +30,11 @@ goodwe_controller/         the add-on
                            returns, run against its own release image
 firmware/goodwe-master.yaml  ESPHome config for the T-CAN485
 estop/rs485_log.py           optional RS485 e-stop / bus witness
-docs/GoodWe-RS485-Field-Guide.pdf  the guide techs carry (10pp, A4)
+docs/GoodWe-RS485-Field-Guide.pdf  the guide techs carry (10pp, A4; outdated)
 docs/build_guide.py          its single source - rebuilds the HTML and PDF
 FIELD-GUIDE.md             how to edit and rebuild the guide
+docs/RELEASE.md            how a change reaches the battery - `master` is
+                           protected, releases go via PR from `release/1.0`
 ```
 
 **Picking this up after a break? Read `HANDOVER.md` first** — current state,
@@ -48,6 +50,9 @@ https://gittea.kammenstraatha.duckdns.org/admin/goodwe-addon
 
 then install **GoodWe RS485 Controller**.
 
+Then turn on **Watchdog** on the add-on's Info tab — see
+[Before you start](goodwe_controller/DOCS.md#before-you-start).
+
 ⚠️ **The repository must be PUBLIC for this to work.** Home Assistant clones it
 anonymously; against a private repo the store shows nothing and gives no useful
 error. If it must stay private, install locally instead: copy
@@ -77,8 +82,8 @@ machine itself dying:
 2. **Wind-down before firmware updates** — 0 W written before the update starts.
 3. **RS485 e-stop (optional)** — writes 0 W after 30 s of total bus silence.
 
-Sites sold without the e-stop must have the acknowledgement in `FIELD-GUIDE.md`
-§10 signed.
+Sites sold without the e-stop must have the client acknowledgement in the field
+guide (Step 7b) signed.
 
 ## Development
 
@@ -100,6 +105,12 @@ has the mechanism, the measurement, and what the flags do not do. They are not u
 each assertion corresponds to a rule whose absence produced an observed failure
 on real hardware, and the comments in `control.py` say which.
 
+### CI and the infra pin
+
+CI (`.gitea/workflows/checks.yml`) runs every `test_*.py`, with `admin/goodwe` checked out next to this repo at the commit in `.gitea/infra-pin`, so `test_freeze.py` grades against the real `sim/hwsim.py`. If that checkout fails, the job fails. The local stub is used only in local runs, and it prints `STUB USED` when it is.
+The pin tracks `admin/goodwe` **release/1.0**, not master. Two non-required checks go red when release/1.0 has moved past the pin: `infra-pin / fresh` here, on any add-on PR or push to release/1.0, and `addon-pin / fresh` in `admin/goodwe`, on every push to its release/1.0. Nothing re-runs `addon-pin` after a bump, so it stays red on that admin/goodwe commit; `infra-pin / fresh` green on the bump is the all-clear.
+**Bump the pin** whenever either is red. Set `.gitea/infra-pin` to the new release/1.0 SHA (`git ls-remote <gitea>/admin/goodwe.git refs/heads/release/1.0`) in a PR, and let `checks / unit` grade the tests against it. CI reads `admin/goodwe` with the Actions secret `INFRA_READ_TOKEN`.
+
 ## Compatibility
 
 **Check the serial number, not the model name.** Characters 6-8 of the serial are

STYLE.md

@@ -0,0 +1,63 @@
+# 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.
+- **Log line** (WARNING/ERROR): one line, at most 25 words, with the numbers that matter. The reasoning goes on a DEBUG line. Log lines stay in English and are not translated. A reason text a line quotes (`%s`) keeps its reason code (`OUTPUT_CLAMP`, `STALE_READING`), because that is the evidence an installer searches for. The reason itself has 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 reason with the real code and checks it. 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/RELEASE.md

@@ -0,0 +1,116 @@
+# Releasing — how a change reaches the battery
+
+`master` is the **default branch**, and the default branch is what the Home
+Assistant Supervisor clones when it installs or updates this add-on. Whatever
+sits on `master` is what runs on a real 5 kW inverter. Treat a push to `master`
+as a deployment, because that is what it is.
+
+---
+
+## 1. `master` is protected — releases go through a pull request
+
+Until 2026-09-23 `master` had **no protection of any kind**. Every gate this
+repo built (CI-01, CI-9) sat on `release/1.0`, the branch that does *not* ship.
+On 2026-09-22 version 0.10.1 went straight onto `master` — no pull request, no
+CI run, no reviewer — and it succeeded (commit `0f14c2a`, the only commit on
+`master` that carries no `(#NN)` merge suffix). SEC-2 closed that.
+
+**The release path is now:**
+
+1. Merge the work into `release/1.0` as usual, via a pull request that goes
+   green. Bump `version:` in `goodwe_controller/config.yaml` on that branch —
+   the Supervisor keys the built image by `version:`, so without a bump nothing
+   is offered and nothing changes.
+2. Open a pull request **`release/1.0` → `master`**. Do not push to `master`;
+   it will be refused by the pre-receive hook:
+
+   ```
+   remote: error: Not allowed to push to protected branch master
+   ! [remote rejected] ... (pre-receive hook declined)
+   ```
+
+3. Wait for `checks / unit (pull_request)` to go **green** on that pull request.
+   The workflow in `.gitea/workflows/checks.yml` carries **no `branches:`
+   filter**, so a `master` base matches and a real run happens — verified on
+   throwaway PR #107 (base `master`), which queued a genuine run.
+
+   ⚠️ Green means green. A `skipped` status is laundered into a `success`
+   rollup by this Gitea and the merge gate accepts it — see the long note at
+   the top of `.gitea/workflows/checks.yml`. Never add an event filter there.
+
+4. Merge the pull request. `required_approvals` is **0**, so a green check is
+   the whole gate; there is no second pair of eyes unless someone asks for one.
+
+5. **Reload the store.** Merging to `master` does not, by itself, offer the
+   update. The Supervisor only sees the new version after:
+
+   ```bash
+   ssh root@192.168.2.158 "ha store reload && ha addons update local_goodwe_controller"
+   ```
+
+   Until `ha store reload` runs, the add-on page still shows the old version
+   and the release looks like it did nothing.
+
+Note that `release/1.0` is normally an *ancestor* of `master` between releases,
+so a `release/1.0 → master` pull request is empty until new commits land on
+`release/1.0`. That is expected; it means there is nothing to release yet.
+
+---
+
+## 2. Branch protection — before and after SEC-2
+
+Forge is Gitea at `192.168.2.147:3000`, repo `admin/goodwe-addon`. Read it back
+with `GET /api/v1/repos/admin/goodwe-addon/branch_protections`.
+
+**Before (2026-09-23):**
+
+| branch | protected | status check required | context | approvals |
+|---|---|---|---|---|
+| `master` (default) | **no rule at all** | — | — | — |
+| `release/1.0` | yes | yes | `checks / unit (pull_request)` | 0 |
+
+**After:**
+
+| branch | protected | status check required | context | approvals |
+|---|---|---|---|---|
+| `master` (default) | yes | yes | `checks / unit (pull_request)` | 0 |
+| `release/1.0` | yes (unchanged) | yes | `checks / unit (pull_request)` | 0 |
+
+Both rules are otherwise identical: `enable_push: false`,
+`enable_force_push: false`, `block_admin_merge_override: true`, no whitelists,
+no file patterns. `required_approvals` stays at **0** on purpose — raising it
+would block the review agent from merging, and nobody asked for it.
+
+The default branch was **not** changed. Changing it would change what the
+Supervisor clones, which is a different decision from this one.
+
+### How the gate was proven to actually bite
+
+A protection rule on this forge can *appear* satisfied while having checked
+nothing, so the rule was tested rather than trusted. The discriminator is a
+merge `POST` carrying a deliberately wrong `head_commit_id`: Gitea evaluates
+branch protection *before* it checks the head, so
+
+* `409 head out of date` → the request **cleared** protection;
+* `405 Not all required status checks successful` → protection **refused** it.
+
+Read the *message*, not just the code: `405` is also returned as
+`Please try again later` for a pull request with **no commits**, which has
+nothing to do with protection. An empty pull request on an unprotected base
+gives that same `405` (verified, throwaway PR #110), so an empty
+`release/1.0 → master` reports it too.
+
+Validated against a control on an unprotected base (PR #106), which answered
+`409` while its check was still pending — i.e. protection was no obstacle
+there. On `master` (PR #107) the same probe answered `405` while pending, and
+`409` once the check was genuinely green. A direct `git push` to `master` was
+rejected by the pre-receive hook with `master`'s SHA unmoved.
+
+---
+
+## 3. Rolling back
+
+There is no force-push escape hatch: `enable_force_push` is `false` on both
+branches. To undo a bad release, land a revert on `release/1.0`, bump the
+version again, and take it through §1. The `/addons/` rollback for the
+reference install is in `HANDOVER.md`.

docs/build_guide.py

@@ -95,7 +95,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
 <div class="page" id="p1">
   <div class="hdr">
     <div><h1>GoodWe RS485 Controller</h1>
-         <div class="sub">Field installation &amp; commissioning guide — v0.1.0</div></div>
+         <div class="sub">Field installation &amp; commissioning guide — v0.1.0, <b>outdated</b>: where it disagrees with DOCS.md, DOCS.md wins</div></div>
     <small>Installer copy</small>
   </div>
 
@@ -503,7 +503,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
   <table>
     <tr><th style="width:30mm">Setting</th><th style="width:16mm">Value</th><th>Reason</th></tr>
     <tr><td><code>gain</code></td><td>0.6</td><td>Inverter needs 3–6 s to settle (1.4 s dead time, 94 % by 3.3 s) against a ~5 s cycle. <b>At the limit — do not raise</b></td></tr>
-    <tr><td><code>slew_w</code></td><td>1000</td><td>Most of a correction in the first cycle without running far ahead of the hardware</td></tr>
+    <tr><td><code>slew_w</code></td><td>0</td><td>0 follows the rail (<code>max_w</code>&nbsp;/&nbsp;9). A faster fixed value is <b>refused at startup</b> (SAFETY-39) — see DOCS.md</td></tr>
     <tr><td><code>deadband_w</code></td><td>15</td><td>Measured residual: mean 15.4 W, max 27 W. At 10 W the command never rests</td></tr>
     <tr><td><code>saturation_w</code> / <code>cycles</code></td><td>500 / 3</td><td>Divergence = inverter at a limit → magnitude may fall, never rise. <b>The 3-cycle term is essential</b>: tested instantly it fires on every large correction</td></tr>
     <tr><td><code>step_w</code></td><td>10</td><td>Register is 1 W but response lands on a ~17.6 W ladder. Finer is meaningless</td></tr>

docs/field-guide.html

@@ -60,7 +60,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
 <div class="page" id="p1">
   <div class="hdr">
     <div><h1>GoodWe RS485 Controller</h1>
-         <div class="sub">Field installation &amp; commissioning guide — v0.1.0</div></div>
+         <div class="sub">Field installation &amp; commissioning guide — v0.1.0, <b>outdated</b>: where it disagrees with DOCS.md, DOCS.md wins</div></div>
     <small>Installer copy</small>
   </div>
 
@@ -468,7 +468,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
   <table>
     <tr><th style="width:30mm">Setting</th><th style="width:16mm">Value</th><th>Reason</th></tr>
     <tr><td><code>gain</code></td><td>0.6</td><td>Inverter needs 3–6 s to settle (1.4 s dead time, 94 % by 3.3 s) against a ~5 s cycle. <b>At the limit — do not raise</b></td></tr>
-    <tr><td><code>slew_w</code></td><td>1000</td><td>Most of a correction in the first cycle without running far ahead of the hardware</td></tr>
+    <tr><td><code>slew_w</code></td><td>0</td><td>0 follows the rail (<code>max_w</code>&nbsp;/&nbsp;9). A faster fixed value is <b>refused at startup</b> (SAFETY-39) — see DOCS.md</td></tr>
     <tr><td><code>deadband_w</code></td><td>15</td><td>Measured residual: mean 15.4 W, max 27 W. At 10 W the command never rests</td></tr>
     <tr><td><code>saturation_w</code> / <code>cycles</code></td><td>500 / 3</td><td>Divergence = inverter at a limit → magnitude may fall, never rise. <b>The 3-cycle term is essential</b>: tested instantly it fires on every large correction</td></tr>
     <tr><td><code>step_w</code></td><td>10</td><td>Register is 1 W but response lands on a ~17.6 W ladder. Finer is meaningless</td></tr>

goodwe_controller/CHANGELOG.md

@@ -1,5 +1,623 @@
 # Changelog
 
+## 0.12.0
+
+**A MINOR BUMP FOR ONE NEW OPTION: `pv_entities` ([[TEL-12]]), for sites with
+more than one PV inverter.** The option surface moves **76 keys -> 77**,
+`options:` and `schema:` in step. 0.11.0's `pv_entity` takes one entity; a roof
+with two or three inverters, each publishing its own power sensor into Home
+Assistant, could only record one of them. `pv_entities` is a list, and the
+Configuration tab renders it as a repeatable field, so you add your second and
+third inverter there rather than in YAML.
+
+⚠️ **UNSET, NOTHING CHANGES.** `pv_entities` ships as `[]`, which is what every
+install that presses *Update* lands on, and empty means "use `pv_entity`" - so
+an install with no PV entity still has no PV channel, and an install with one
+`pv_entity` keeps exactly the single-entity channel 0.11.0 gave it. **No rule was
+added to `validate.py`**, which mentions neither key, so **a stored options blob
+that starts the add-on on 0.11.0 starts it on 0.12.0**. There is no
+`SystemExit(78)` to plan around on this hop.
+
+⚠️ **IT IS INSTRUMENTATION ONLY, NOT A CONTROL INPUT.** `app/control.py`,
+`allocator.py`, `arbiter.py`, `peakguard.py` and the watchdogs are not in this
+release's diff; the runtime files that move are `app/pv.py`, `app/main.py`,
+`app/mqtt.py`, `config.yaml` and `translations/`. `tools/tel11_pv_trace.py`,
+extended for this card, hashes the controller's decisions on 0.11.0 and on this
+tree: the control document is **`846a10a5b89e…` with PV unset and with one
+entity, on both trees** - the same hash TEL-11 recorded - and with a
+three-entity roster it equals each grid world's unset document, including every
+cell where one inverter is dead. Neither the total nor any partial total reaches
+a decision. With PV unset or with one entity, the **telemetry** is byte-identical
+to 0.11.0's as well.
+
+Contents of this release, in merge order since 0.11.0 (`cccb2fa`):
+
+| | |
+|---|---|
+| `f863eca` | TEL-12 - several PV inverters, and one absent member is an absent TOTAL **⚠️ NEW OPTIONAL OPTION, EMPTY ON EVERY EXISTING INSTALL** |
+
+### TEL-12 — `pv_entities`: the PV channel for a roof with several inverters
+
+**WHAT TO DO ON A SITE WITH MORE THAN ONE PV INVERTER.** List every inverter's
+power sensor under `pv_entities`:
+
+```yaml
+pv_entities:
+  - sensor.pv_east_power
+  - sensor.pv_west_power
+  - sensor.pv_garage_power
+```
+
+`sensor.goodwe_pv_power` then carries the **site total**. Each entity's own
+`unit_of_measurement` is read, so a kW inverter beside a W one sums correctly;
+a sensor with no unit or a non-power unit is refused by name on the status
+page, as in 0.11.0.
+
+⚠️ **`pv_entities` REPLACES `pv_entity` - IT DOES NOT ADD TO IT.** When the list
+is set, `pv_entity` is not read at all. **If you are upgrading from 0.11.0 with
+`pv_entity` already set, the inverter it names must also be in the list**, or it
+drops out of the total. Put it in the list and it is **counted once**, not
+twice - that is why the rule is replacement: under a union, the natural action
+(put all your inverters in the new field) would double-count the one the old
+key already names. While both keys are set the status page shows a caution
+saying which one won - *"`pv_entities` is set, so `pv_entity` is IGNORED - the N
+entities in the list are what is summed. Clear `pv_entity` to remove this
+caution"*. It is a caution, never a refusal to start and never a NOT READY row.
+A repeated id inside the list is also counted once.
+
+⚠️ **IF ANY CONFIGURED PV ENTITY IS ABSENT, THE PUBLISHED TOTAL IS `unknown` -
+NOT THE SUM OF THE ONES THAT ANSWERED.** Three inverters configured and one
+`unavailable`: `sensor.goodwe_pv_power` goes to `unknown` and the recorder
+stores a **gap**. The sum of the other two would be a smaller number
+indistinguishable from a real one, and a week later it would read as *"there
+was less sun than there was"* - the conclusion this channel exists to test
+rather than to manufacture. **A gap in the history, never an understated
+number.** The status page, read live, still gives you the diagnostic: `PV  —`
+plus a caution that says there is **no site total**, names the missing entity
+and its reason, and lists what the others reported. An inverter honestly
+reporting **0 W** is summed, not treated as absent - shading and nightfall are
+real zeros.
+
+| what happened | `sensor.goodwe_pv_power` | the status page |
+|---|---|---|
+| neither key set | the entity does not exist | no row |
+| all three answer, 1200 W + 2.1 kW + 450 W | `3750.0` | `PV  3 750 W` |
+| all three answer, one of them `0 W` | the sum of the two others | the sum |
+| one (or more) `unavailable` / missing / bad unit | `unknown` - a recorder gap | `PV  —` + a caution naming what is missing |
+
+⚠️ **THE FIX FOR A MISSING INVERTER IS NOT A TEMPLATE SENSOR THAT SUMS THEM.**
+You can still point `pv_entity` at one if you prefer, but a template sensor
+summing an `unavailable` source yields the partial total silently - the same
+defect one layer down, where this add-on cannot see it or report it.
+
+**WHY A SECOND KEY, RATHER THAN MAKING `pv_entity` A LIST.** Because an 0.11.0
+install that has `pv_entity` set would not start. Measured against Supervisor
+**2026.08.0** by `tools/supervisor_shape_probe.py` §G: with `pv_entity` declared
+as a list, the string an 0.11.0 install has persisted is refused -
+`Invalid list for option 'pv_entity'` - and a shipped `[]` default does not
+rescue it, because the Supervisor's merge keeps your stored string. The one
+single-key spelling that accepts both shapes, `match(.*)?`, validates nothing
+(it accepts the integer `417`) and renders as a plain text box, so you could not
+add a second inverter in the UI. So `pv_entity` stays a string, and the same
+probe shows an 0.11.0 options blob - `pv_entity` set, no `pv_entities` key at
+all - validating against this version untouched. ⚠️ **Rolling back to 0.11.0 is
+also safe**: a schema without `pv_entities` drops the key with a warning and
+leaves `pv_entity` standing.
+
+**Why it matters now:** [[OPT-10]] needs a week of PV history to attribute the
+surplus that left the reference site while the pack had room, and that site has
+several PV inverters. The week starts when the site total is recorded.
+
+**Full account: `DECISIONS/TEL-12-several-pv-inverters.md`, with the operator's
+version under "Several PV inverters" in `DOCS.md`.**
+
+### If you are crossing from a version older than 0.10.0
+
+⚠️ **THIS SECTION IS NOT THE ONE THAT CAN REFUSE YOU - `## 0.10.0` BELOW IS.**
+Updating installs 0.12.0 in one step, so every validator rule added in
+0.8.0, 0.9.0 and 0.10.0 arrives at the same moment. Two of them can refuse a
+config nobody has edited: [[SAFETY-39]]'s **rule 10** (added in 0.8.0) against
+0.7.0's shipped default `slew_w: 1000` - the ceiling is **555.6 W** on a 5000 W
+rail - and [[TARIFF-07]]'s three withdrawn `price_provider` ids,
+**`engie_dynamic`, `totalenergies_dynamic` and `eneco_eddy`**, each still
+refused by name at startup on 0.12.0. Neither is new here, and a site already on
+0.10.0 or later has already met both. **The full account of both, including
+what to set instead of each withdrawn id, is in `## 0.10.0`**, which withdrew
+them and is not superseded by this section.
+
+`tools/predeploy_check.py` checks your live options against this version's
+validator before you press *Update*, and on this tree reports a real version
+change from 0.11.0. ⚠️ **Pass it the bare options dict - the `data.options`
+object - NOT the whole `ha apps info --raw-json` document.** Handed the wrapped
+export it currently prints CLEARED while having checked nothing ([[SAFETY-60]],
+open). Extract the options first, e.g. `jq '.data.options'`.
+
+## 0.11.0
+
+**A MINOR BUMP, AND ONE NEW OPTION IS THE WHOLE REASON FOR THE SECOND DIGIT:
+`pv_entity` ([[TEL-11]]).** The option surface moves - **75 keys -> 76**,
+`options:` and `schema:` in step - which is the same test 0.8.0, 0.9.0 and
+0.10.0 were each cut on. ⚠️ **AND UNLIKE 0.10.0, NOTHING HERE CAN REFUSE A
+STORED OPTIONS BLOB.** No key was removed, no default moved, no enum widened,
+and **no rule was added to `validate.py`** - the validator does not mention
+`pv_entity` at all, because nothing else reads it and it cannot conflict with
+anything. The new key is `str?` - **note the trailing `?`, it is OPTIONAL** -
+with an `options:` default of `""`, so a blob written on 0.10.0 or 0.10.1 does
+not carry it, the Supervisor's merge supplies the empty string, and the empty
+string is *off*. ⚠️ **A stored options blob that starts the add-on on 0.10.1
+starts it on 0.11.0. There is no `SystemExit(78)` to plan around on this hop**,
+and a site that presses *Update* and changes nothing else gets an add-on that
+behaves exactly as its 0.10.1 did.
+
+⚠️ **WHAT YOU ARE ACTUALLY DECIDING, IN ONE LINE EACH. TWO TICKETS HERE ARE
+OBSERVABLE ON AN INSTALLED ADD-ON, AND NEITHER CHANGES A WATT.**
+
+* [[SAFETY-56]] - **three messages stop naming your hardware as the fault** in a
+  state where the add-on cannot tell a dead register from a battery that is
+  simply empty at its BMS floor. **Text only; the behaviour is measured
+  byte-identical.** If you have ever opened Developer Tools because the add-on
+  told you a sensor had failed, and found the sensor working, this is that
+  defect. On the reference install the state it misdiagnoses arrives on most
+  nights and on every cloudy morning after a deep discharge.
+* [[TEL-11]] - **one new optional key, `pv_entity`, and nothing whatever happens
+  until you fill it in.** Set it and the add-on records what your solar is
+  producing beside what the meter and the battery are doing. ⚠️ **It is not a
+  control input and it does not change what the loop does.**
+
+⚠️ **THERE IS NO CONTROL-LAW CHANGE IN THIS RELEASE, WHICH IS WORTH SAYING
+BECAUSE 0.10.0 HAD ONE AND NOTHING IN ITS PREAMBLE COULD WARN YOU.**
+`app/control.py` is not in this release's diff at all, and neither are
+`allocator.py`, `arbiter.py`, `arbitrage.py`, `clamp.py`, `peakguard.py`,
+`maintenance.py` or `watchdog.py`. The runtime files that move are
+`app/freshness.py` and `app/main.py` (SAFETY-56's three sentences), and
+`app/pv.py` - new - with `app/main.py`, `app/mqtt.py`, `config.yaml` and
+`translations/` (TEL-11). Contrast [[SAFETY-48]] in `## 0.10.0`, which altered
+what the inverter is asked to do while touching no option, no default and no
+validator rule, so that nothing a config check could see would mention it. This
+release has nothing of that shape in it.
+
+⚠️ **IF YOU ARE CROSSING FROM A VERSION OLDER THAN 0.10.0, THIS SECTION IS
+STILL NOT THE ONE THAT CAN REFUSE YOU - `## 0.10.0` BELOW IS.** `ha addons
+update` does not walk the versions; it installs 0.11.0 in one step, so every
+validator rule added in 0.8.0, 0.9.0 and 0.10.0 arrives at the same moment as
+this section's nothing. Two of them can refuse a config that nobody has edited:
+
+> [[SAFETY-39]]'s **rule 10**, added in 0.8.0, against 0.7.0's own shipped
+> default `slew_w: 1000` - the ceiling is 2/18 of the site rail, which is
+> **555.6 W** on a 5000 W rail.
+>
+> [[TARIFF-07]]'s three withdrawn `price_provider` ids - **`engie_dynamic`,
+> `totalenergies_dynamic` and `eneco_eddy`** - each of which is **still refused
+> by name at startup on 0.11.0**, with the same message and for the same
+> measured reasons: a 404 from a gateway with no route, a TLS handshake against
+> a hostname the certificate does not cover, and a 404 with an empty body.
+
+⚠️ **NEITHER OF THOSE IS NEW IN 0.11.0, AND NEITHER IS NEWS TO A SITE ALREADY ON
+0.10.0 OR 0.10.1 - IT HAS ALREADY MET THEM.** They are restated here only
+because this is now the newest section, and a reader who opens the newest section
+and stops would otherwise never meet the one class of thing that can stop the
+add-on starting. **The full account of both is in `## 0.10.0` below**: what to
+set instead of each withdrawn id, which tariff a site left on one of them has
+really been running, why the refusal *is* the migration, and why all three ids
+stay in `config.yaml`'s `price_provider` enum even though `PROVIDERS` is down to
+three. **That is the section that withdrew them, it is where the evidence is,
+and it is not superseded by this one.** ⚠️ The reference install is on
+`price_provider: off` and at `slew_w: 400`, so neither applies to it.
+`tools/predeploy_check.py` checks both against your live options blob before you
+press *Update*, and on this tree it reports a real version change rather than
+0.10.1's no-op.
+
+Contents of this release, in merge order since 0.10.1 (`b0b24e5`):
+
+| | |
+|---|---|
+| `c9aaf7f` | SAFETY-56 - the gate cannot tell a dead register from a pack that cannot comply, so stop saying it can **⚠️ TEXT ONLY, BEHAVIOUR BYTE-IDENTICAL** |
+| `94da37f` | TEL-11 - PV production stops being invisible, and stays out of the control law **⚠️ NEW OPTIONAL OPTION, UNSET ON EVERY EXISTING INSTALL** |
+
+⚠️ **TWO MORE MERGES LANDED IN THIS WINDOW AND ARE DELIBERATELY NOT IN THE TABLE
+ABOVE: [[CI-9]]'S FOLLOW-UP (`9f6b9f1`) AND [[SEC-2]] (`239e120`). THE RULE IS
+[[PKG-15]]'S - AUDIENCE, NOT IMPORTANCE - AND BOTH FAIL IT THE SAME WAY.** This
+file is the **add-on's** release note: the text the Supervisor renders beside the
+version number, read by somebody deciding whether to press *Update* on a battery
+that is currently regulating. A row here has to be something that reader can act
+on.
+
+* **CI-9's follow-up changes one file, `.gitea/workflows/checks.yml`**, exactly
+  as CI-9 itself did, and it is comment-only within that file. It is not under
+  `goodwe_controller/`, it is not in `predeploy_check.py`'s `RUNTIME` tuple, it
+  is not in the built image, and **there is no version of this add-on on which an
+  operator can observe it.** `## 0.10.0` excluded CI-9 on exactly that reasoning;
+  excluding the follow-up on any other reasoning would make the rule mean
+  nothing.
+* **SEC-2 adds `docs/RELEASE.md` and two lines to `README.md`, and this one is
+  the closer call, so here is the whole of it.** SEC-2 is by some distance the
+  more consequential of the two: it is the ticket that made `master` refuse a
+  direct push, and it is *why this release reaches you as a pull request into
+  `release/1.0` and then into `master`, rather than as a push straight to the
+  branch the Supervisor clones* - which is how 0.10.1 got there. It is also
+  **purely a procedure for whoever cuts a release**; both files sit outside
+  `goodwe_controller/`, neither is in the image, and no install can tell whether
+  that document exists or what it says. An operator reading it learns nothing
+  about 0.11.0 that helps them decide whether to take it. So it is excluded, and
+  it is excluded under the same sentence as CI-9: ⚠️ **importance to this
+  repository is not the test. Observability on an installed add-on is.**
+
+⚠️ **AND BOTH ARE WRITTEN DOWN, JUST NOT HERE.** CI-9's follow-up is PR #102 plus
+the comment block at the top of `.gitea/workflows/checks.yml`, which carries the
+measurements in full; SEC-2 is PR #108 plus `docs/RELEASE.md` itself, which is
+now the canonical account of the release path and is the procedure this release
+followed. ⚠️ **If a later CI or packaging ticket changes what the shipped image
+contains, it belongs in this table.** Neither of these does.
+
+### SAFETY-56 — three messages stop blaming healthy hardware
+
+⚠️ **NOTHING THE ADD-ON DOES CHANGES. THREE THINGS IT SAYS DO.** Same
+conjunction, same limits, same `MISSING`, same 0 W command, same NOT READY row,
+same [[SAFETY-57]] release at 32 s. `tools/safety56_behaviour_trace.py` is what
+says so rather than a commit message: it hashes a document with no sentence
+anywhere in it, built from **2390 one-second reads replayed out of the committed
+2026-09-21 bus capture**, a **66-cell command × register grid stepped 120 times
+each**, and **six driven controller worlds**. That document is
+`6030175ed2ab9a41…` on `release/1.0` and on this tree, byte for byte, while the
+sentences differ. ⚠️ **And the tool REFUSES to report "behaviour unchanged" when
+the sentence halves agree**, so an identical pair is a result rather than one
+tree compared with itself.
+
+**THE DEFECT, AND IT IS NOT A TYPO.** [[SAFETY-37]]'s freshness gate fires when a
+battery-power register holds one value while the standing command moves. That
+conjunction is satisfied by **two disjoint worlds**:
+
+1. the register has stopped reporting reality - which is what the gate was built
+   to catch; or
+2. **reality is not moving**, because the source cannot comply with the command.
+   A BMS refusing a discharge at its floor holds the pack still under any
+   setpoint, and a register reporting that honestly publishes the same unchanged
+   number a dead one does.
+
+**Nothing the gate is handed separates them, and three sentences asserted the
+first.** ⚠️ **On the one episode this repository has measured, it was the
+second.** On 2026-09-21 the pack read **11 %** for the whole 850 s hold, **every
+command inside that hold was a discharge**, and the register **answered the first
+CHARGE command three seconds later**. All three numbers are read off the
+committed capture by `test_freshness.py` part 11a rather than typed there. The
+register was healthy and truthful throughout, and the add-on said it had failed.
+
+**THE THREE SURFACES, so you can recognise what moved:**
+
+| where you read it | what 0.10.1 said | what 0.11.0 says |
+|---|---|---|
+| the **action log** and the **status page** — both quote `freshness.py`'s `STALE_READING:` line verbatim, through `_read_unit()` and `stale_note()` | `… the reading is not following, so it is reported as MISSING` | `… TWO THINGS LOOK LIKE THIS AND THIS GATE CANNOT TELL THEM APART: the register may have stopped reporting reality, or the source may be unable to comply with the command …` |
+| the **add-on log**, at ERROR, from `main.py` | `SAFETY-37: <unit> battery-power register is not following its own command` | `SAFETY-37: <unit> battery-power reading did not move under a command that did, WHICH IS NOT BY ITSELF A VERDICT ON THE REGISTER` |
+| the **readiness row** on the diagnostics page | `battery power: <entity> is missing or not numeric` | `battery power: no usable value this cycle from <entity> - and this row cannot tell which of two things that is … Confirm the entity in Developer Tools before replacing it` |
+
+⚠️ **THE THIRD ROW IS THE ONE THAT COST AN OPERATOR AN EVENING, AND IT IS THE
+WORST THING A DIAGNOSTIC CAN DO: IT ASSERTED A FALSE FACT ABOUT A NAMED
+ENTITY.** It read *"is missing or not numeric"* for **any** `None`, and one of
+the ways that value becomes `None` is the freshness gate withholding a reading
+that is present, numeric and updating - `Freshness.reading()` returns `None`
+there **by design**. So the operator opened Developer Tools on the entity the row
+named, found it working, and had every reason to conclude the diagnostics were
+broken. **It is fixed by saying less, not by looking harder:** the row does not
+branch on the gate's state, because the gate already has a surface of its own -
+`stale_note()` rides `liveness_notes()` a few rows below with the whole
+`STALE_READING` sentence in it - so your discriminator is *"is that row there?"*,
+and this row's only job is to stop pre-empting the answer.
+
+⚠️ **WHAT IT DOES NOT GIVE YOU IS WHICH OF THE TWO IT WAS.** Naming which would
+need the SoC and the pack floor, and those are deliberately not `freshness.py`'s
+inputs - they are [[TEL-08]]'s and [[SAFETY-32]]'s numbers, on their own rows.
+**SoC is STATED in these sentences and never WIRED into them**: part 11b drives
+the same two worlds at 50 % and at 11 % and the sentence does not move one byte.
+What changed is that the add-on now tells you it cannot tell, instead of guessing
+and blaming your hardware. **The reading rule is unchanged from
+`### SAFETY-57` below**: if the stale/withdrawn pair keeps repeating, the unit
+really does want looking at; if it happens once at a low SoC and stops, the pack
+was empty and the site has resumed.
+
+⚠️ **AND THE THREE WORDINGS SHARE NO HELPER, ON PURPOSE.** Two of them are log
+lines about a **behaviour** and the third is a banner about an **entity**; they
+answer different questions ("what did the register do" against "can I trust this
+entity"), and one helper serving both would have to drop whichever half the other
+caller does not need - and the half it dropped would be the operator's next step.
+
+**Full account: `DECISIONS/SAFETY-56-what-the-gate-cannot-tell-apart.md`.**
+
+### TEL-11 — `pv_entity`: PV production gets recorded, and stays out of the control law
+
+⚠️ **UNSET, THIS IS NOT A CHANGE AT ALL - AND THAT IS MEASURED RATHER THAN
+ASSERTED.** `pv_entity` ships empty, which is what **every** install that
+upgrades into this version lands on. Empty means the add-on **reads no entity,
+announces no entity, publishes no topic, shows no status row and adds no page
+row.** `tools/tel11_pv_trace.py` drives five grid behaviours × eight
+PV-sensor behaviours through 24 cycles of the **shipped** `Controller`, on
+`release/1.0` and on this tree, and hashes two separate documents - one of
+**control** decisions and one of **telemetry**:
+
+| document | tree | `pv_entity` | sha256 |
+|---|---|---|---|
+| control | `release/1.0` | unset | `846a10a5b89e3210…` |
+| control | TEL-11 | unset | `846a10a5b89e3210…` |
+| control | TEL-11 | **set** | `846a10a5b89e3210…` |
+| telemetry | `release/1.0` | unset | `a443a6ceaffe072b…` |
+| telemetry | TEL-11 | unset | `a443a6ceaffe072b…` |
+| telemetry | TEL-11 | **set** | `4e6d1cb289a95722…` |
+
+**Read the two `unset` rows first.** They are byte-identical in **both**
+documents, which is a stronger claim than "the control path is untouched": an
+install that does not set the option sees no change of any kind, announcements
+and status rows included. **Then read the `set` row of the control document** -
+identical again, while telemetry moves. ⚠️ The tool **REFUSES** unless the two
+trees' `app/` fingerprints differ and unless exactly one side reacts to the
+option, so a matching pair cannot be two runs of the same tree.
+
+⚠️ **IT IS NOT A CONTROL INPUT, AND IT DOES NOT CHANGE WHAT THE LOOP DOES.** It
+is instrumentation and nothing else. It is not read by the control law, the
+allocator, the arbiter, the peak guard, the maintenance cycle or any watchdog; it
+is **not part of `inputs_ok`**, so a PV integration that breaks cannot stop your
+battery being regulated; and its status row is a **caution** (`warn`), never a
+`bad` row, so a telemetry channel can never put a battery site into NOT READY.
+`test_pv.py` part 6 drives 40 cycles of the real `cycle()` and asserts the
+commands are bit-identical across unset / no reading / 0 W / 8 kW, with a
+**computed** census of all 33 modules under `app/` showing the material is
+mentioned in exactly three of them: `pv.py`, `main.py`, `mqtt.py`. Wiring
+production into the control law would be a behaviour change on a system driving a
+real battery - and it would destroy the measurement, because the loop would then
+be reacting to the thing being measured.
+
+**WHAT YOU GET IF YOU DO SET IT.** One new MQTT-discovery sensor,
+`sensor.goodwe_pv_power`, `device_class: power` and ⚠️ **`state_class:
+measurement`** - which is the point of the row, because that is what puts the
+number into the recorder's long-term statistics, and a week of statistics is what
+the attribution needs. **Positive is producing.** The unit is **read off your
+entity's own `unit_of_measurement`** - `mW`, `W`, `kW`, `MW`, `GW`, `TW`, Home
+Assistant's own power units, every factor an exact power of ten. A sensor with
+**no** unit, or with a unit that is not power, is **refused by name, and the
+status page says which entity and which unit.** There is deliberately no
+magnitude heuristic: nothing can separate 30 W of dusk from 30 kW of noon, and a
+silent factor of 1000 in the one channel that exists to be believed a week later
+is worse than a refusal you can read.
+
+⚠️ **ABSENCE IS PUBLISHED AS `unknown`, NOT AS 0 AND NOT SKIPPED. THIS IS THE
+DESIGN DECISION WORTH YOUR ATTENTION.**
+
+| what happened | `sensor.goodwe_pv_power` | the status page |
+|---|---|---|
+| `pv_entity` not set | the entity does not exist | no row at all |
+| set, sensor answered 4100 W | `4100.0` | `PV  4 100 W` |
+| set, sensor answered 0 W | `0.0` | `PV  0 W` |
+| set, sensor unavailable / missing / bad unit | `unknown` | `PV  —`, plus a caution naming the reason |
+
+The last two rows are why the key is shaped this way. `publish()` normally
+**drops** a `None`, which is right for `circulation` - there the last figure
+standing beats a zero that reads as health - and **exactly wrong here**: a
+dropped row leaves Home Assistant holding the last number it was told, for ever,
+and the recorder then draws a **flat line through the outage**, which is
+indistinguishable from a measurement. Anyone reading that week back would
+conclude the sun was not shining, ⚠️ **which is precisely the conclusion this
+channel exists to TEST rather than to manufacture.** So the absence is published,
+using Home Assistant's own no-value payload (`mqtt/const.py` declares
+`PAYLOAD_NONE = "None"` and `mqtt/sensor.py` tests it *before* the numeric
+branch), the entity's state becomes **`unknown`**, and the recorder stores a
+**gap**. A failed read also **clears** the previous good one: the value never
+outlives its own sensor.
+
+⚠️ **WHY IT IS A HOME ASSISTANT ENTITY AND NOT A REGISTER.** The RS485 bus this
+add-on speaks carries the **battery** inverter it drives. On nearly every site the
+PV inverter is a different box from a different vendor on its own connection,
+reporting into Home Assistant through its own integration - so this takes
+whatever `sensor.*` your PV integration already provides, **any brand Home
+Assistant can read**, and nothing anywhere assumes it is on the bus.
+
+**THERE IS NO `pv_invert`, AND THAT IS NOT AN OVERSIGHT.** `meter_invert` and
+`batt_invert` exist because those two quantities are **bipolar and are read by
+the control path**, where a reversed sensor hands the site a plausible number it
+acts on. Production is unipolar and is read by **nothing**, so a reversed sensor
+cannot mislead a decision, and it announces itself as **−4 kW at noon** in the
+very history this key exists to create. A flag would only let an installer hide
+it. There is no negative-value alarm either: a PV inverter's own standby draw
+makes a small negative reading at night ordinary, so any threshold would be a
+number nobody has measured.
+
+⚠️ **WHAT THIS RELEASE DOES NOT DO, AND IT IS THE REASON THE CARD EXISTS.** It
+does not answer [[OPT-10]]'s question. That card measured this site over sixteen
+days: the pack reached 90 % SoC on **two** of them, and **20.5 kWh of surplus
+left the site while the pack still had room** - 12.6 kWh of it with the battery
+not charging at all - and it could not say **why**, because PV production was
+recorded **nowhere**. Three causes need three different fixes (no irradiance:
+nothing to fix; a charge-power limit; the optimiser declining to charge, which is
+the only software defect), and guessing between them is how an optimiser gets
+tuned to solve a cloud problem. **0.11.0 adds the channel. The attribution needs
+a week of history through it, and is OPT-10's own card.** So the reason to set
+`pv_entity` on the day you take this update is that the clock on that week starts
+when you do.
+
+**Full account: `DECISIONS/TEL-11-pv-production.md`, with the operator's version
+under "PV production" in `DOCS.md`.**
+
+## 0.10.1
+
+**A PATCH RELEASE, AND ONE TICKET IS THE WHOLE OF IT: [[SAFETY-57]].** The last
+place moves because this is a bug fix to a version that has shipped and is
+regulating a battery, not a change to what the add-on offers. **The option
+surface does not move at all** - no key added, none removed, no default changed,
+no enum widened, no rule added to `validate.py` - so ⚠️ **a stored options blob
+that starts the add-on on 0.10.0 starts it on 0.10.1**, and there is no
+`SystemExit(78)` to plan around on this hop. If you are on 0.10.0, the only
+question worth your time is whether you have been hit by what it fixes, and
+`### SAFETY-57` below is written to answer exactly that.
+
+⚠️ **WHY THIS IS A NEW NUMBER RATHER THAN A FOLD INTO 0.10.0, WHICH IS THE
+REASON THE TICKET EXISTS.** The Supervisor decides that an update is available
+by comparing `config.yaml`'s version string with the one the box reports.
+0.10.0 is installed and running, so a fix delivered inside `## 0.10.0` would
+leave every box reporting `0.10.0` believing it was already current - the
+PKG-06/PKG-07 no-op, in the form where the tree it hides is a safety fix.
+0.10.0's own section argued it could still be folded into; ⚠️ **that argument
+was explicitly conditional on 0.10.0 never having been installed, and the
+condition has fired** - see the closing note at the end of `## 0.10.0` below.
+
+⚠️ **IF YOU ARE CROSSING FROM A VERSION OLDER THAN 0.10.0, THIS SECTION IS
+NOT THE ONE THAT CAN REFUSE YOU - `## 0.10.0` BELOW IS.** `ha addons update`
+does not walk the versions; it installs 0.10.1 in one step, so every validator
+rule added in 0.8.0, 0.9.0 and 0.10.0 arrives at the same moment as this
+section's nothing. Two of them can refuse a config that nobody has edited:
+[[SAFETY-39]]'s **rule 10** against 0.7.0's own shipped default `slew_w: 1000`,
+and [[TARIFF-07]]'s three withdrawn `price_provider` ids - **`engie_dynamic`,
+`totalenergies_dynamic` and `eneco_eddy`** - each of which is still refused by
+name at startup on this version, with the same message. Both are written out in
+full under `## 0.10.0`, and `tools/predeploy_check.py` checks both against your
+live options before you press *Update*.
+
+Contents of this release, in merge order since 0.10.0 (`cb3f686`):
+
+| | |
+|---|---|
+| `b9f7bd0` | SAFETY-57 - the stale-reading verdict gets an exit, because its own consequence is what stopped it being tested **⚠️ MEASURED ON THE LIVE SITE** |
+
+⚠️ **AND THAT IS THE WHOLE TABLE, WHICH IS THE POINT OF A PATCH NUMBER.**
+[[TEL-10]] and [[SAFETY-48]] also merged after `cb3f686`, but [[PKG-15]] folded
+both into `## 0.10.0` **before 0.10.0 was installed**, so they shipped under
+that number and are recorded there rather than here. [[CI-9]] and [[PKG-15]]
+itself touch `.gitea/workflows/checks.yml` and this file only - nothing an
+operator can observe on an installed add-on - and are excluded for the reason
+`## 0.10.0` already gives. ⚠️ **Two defects that the reference install's own
+field history found are NOT in this release**: [[SAFETY-56]] (the stale-reading
+message says *"is not following its own command"* when the true cause is an
+empty pack, and the NOT READY row that goes with it) and [[SAFETY-58]] (a trip
+on the first read after a rest). Both were open when this section was cut, both
+are wording or bound changes rather than deadlocks, and neither was allowed to
+delay this one. ⚠️ **[[SAFETY-56]] HAS SINCE BEEN FIXED AND IS IN `## 0.11.0`
+ABOVE.** The wording quoted in this paragraph is what **0.10.1 actually ships**
+and is left standing for that reason - if the box in front of you reports
+`0.10.1`, that is the sentence it will print at you. It is not what 0.11.0 says.
+[[SAFETY-58]] is still open.
+
+### SAFETY-57 — the stale-reading verdict gets an exit
+
+⚠️ **WHETHER YOU WANT THIS UPDATE, AND HOW TO TELL.** On 0.10.0 the add-on
+can enter a state it cannot leave: the command is parked at **0 W**, the
+battery-power reading is gated to **MISSING**, and the only condition that
+would clear the gate is one that a parked command cannot produce. **It is a
+deadlock, not a slow recovery.** On the reference site on 2026-09-21 it held
+for about **thirteen minutes while the house exported 2.4 kW**, and it ended
+only because a human restarted the add-on.
+
+**Recognising it costs one look at the status page and one at the log:**
+
+| | |
+|---|---|
+| the setpoint | sits at **exactly 0 W** and does not move, while the house is plainly importing or exporting |
+| the battery-power sensor | is **flat at one number** for the whole of it - on the live episode, −3 W for 850 s |
+| the action log | carries a `STALE batt` line and **no** clearing line after it |
+
+**What ends it on 0.10.0 is a restart of the add-on**, and a restart is enough -
+nothing is latched to disk and the pack is not harmed. ⚠️ **But nothing ends it
+by itself**, and the replay below says the wait can run to hours. On 0.10.1 the
+state releases itself after a bounded **32 s** and the register is re-graded
+from scratch.
+
+⚠️ **IT IS NOT AN EMERGENCY AND IT IS NOT COSMETIC.** The pack is not at
+risk in this state - 0 W is the safe command, and it is the command §11.1 rule 1
+asks for on a missing input. What is lost is the site's own control while it
+lasts: the battery neither charges nor discharges, so a solar export goes to the
+grid and an evening load comes off it.
+
+⚠️ **WHAT IT FIXES, ON THE OWNER'S OWN BATTERY.** [[SAFETY-37]]'s freshness gate
+reports a battery-power register as MISSING when it stops following its own
+command, and a missing input is `command 0 W and keep commanding` (§11.1
+rule 1). The gate's only exit was *"an arrival carrying a different number"* —
+**and at 0 W nothing is asking the register to be anywhere.** The state had no
+exit reachable from inside it, and the log line said the opposite.
+
+Measured off the RS-485 bus, 2026-09-21, and committed as
+`scenarios/safety57-2026-09-21/`:
+
+| | |
+|---|---|
+| 10:51:24 | 0x0518 reaches **−3 W**. The pack is at 11 %, the loop has just reversed out of a charge, and the BMS refuses the discharge. The register is **healthy and truthful**. |
+| 10:51:29 | the command reaches **+1060 W**, 800 W of travel |
+| 10:52:00 | the gate arms. `Inverter.batt` becomes `None` |
+| 10:52:21 | **the site commands 0 W — on the wire, in the capture** |
+| … | the register does not change value for **850 s**. The setpoint does not change value for **790 s**. The house exports 2.4 kW throughout |
+| ~11:04 | **a human restarts the add-on.** That is what ends it |
+
+It had been escaping by luck - and ⚠️ **on this episode it did not escape at
+all.** `0x0518` answered the same −3 W on 90 consecutive responses and never
+once carried a different number between 10:51:24 and 11:05:35. The register did
+not move.
+
+⚠️ **AND WHY IT USUALLY DOES MOVE IS NOT SOMETHING THIS REPOSITORY HAS
+MEASURED.** An earlier draft of this entry named a BMS keep-alive pulse as the
+thing that twitches the register, stated as fact; **no committed capture
+identifies such a pulse**, distinguishes one from the register simply following
+a command, or sizes it. The honest statement is that the register changes value
+for reasons that belong to the battery's firmware. What IS measured is how long
+it goes without changing: replaying the committed 16-day loop capture through
+the shipped conjunction finds **93 trips** whose wait has a **median of 143 s**
+and a worst case of **5 h 57 m**, with **16 of the 93** at or beyond this
+episode's **790 s**. That figure is stronger than the firmware story it
+replaces, and it needs no firmware story at all.
+
+**The rule, and it is [[SAFETY-13]]'s shape one module over** — which latches
+get an exit, not how long the block lasts:
+
+> the verdict is withdrawn when the obligation that produced it has been gone
+> for `RELEASE_S`, and the register is then re-graded from scratch.
+
+`RELEASE_S` is **17.0 s**, the obligation window already derived in
+`freshness.py` — 6.0 s of plant, one 10 s ESPHome publish, one 1 s add-on read.
+It is the **floor** of its band rather than a preference: below it the release
+pre-empts the cheaper exit (the register answering by itself), and being wrong
+*long* is the failure being fixed. **The whole parked interval is now
+`stale_input_s` + `RELEASE_S` = 32 s**, bounded by two shipped numbers and by
+nothing the battery does. On the live episode: telemetry back at **10:52:39
+instead of 11:05:35**, with **0x0518 still answering the same −3 W**.
+
+⚠️ **WHAT IT COSTS, AND IT IS NOT SMALL.** A register that is dead for good is
+re-graded for ever. Driven over 1201 reads at the shipped defaults: the held
+number reaches a consumer on **630 reads (52.5 %)** against 35 (2.9 %) before.
+That is payable only because **one re-grading window is 35 s and the two
+consumers hold for 75 s and 85 s** — neither can reach a verdict inside one,
+and the re-trip that ends each window hands them a `None`, which *clears* their
+windows. **No detection SAFETY-37 had is given back**: a permanent `None`
+clears those same windows for ever too. What the site gets back is its
+meter-derived control, and the command was never derived from `batt`.
+
+⚠️ **THAT 35 s HOLDS WHILE THE OBLIGATION COMES BACK, AND ONLY THEN - IT IS NOT
+A UNIVERSAL BOUND, AND THE FIXTURE THAT GRADES IT CANNOT SHOW OTHERWISE.** A
+window closes when the gate re-arms, and the gate needs a command that is
+*moving* to re-arm against. If the release lands where the site then regulates
+below `MOVE_W`, nothing re-arms, the window never closes, and the held number
+reaches a consumer for an unbounded time - where before this card a `None` did.
+The driver behind the 35 < 75 < 85 inequality puts a 1300 W obligation back on
+every release, so it is the one shape that cannot produce that case. On the
+shipped roster of **one** inverter neither consumer can reach it anyway - the
+per-unit sign watchdog is compared against the **meter** at `n_units <= 1`, and
+`circulating_w()` is identically `0.0` there - so this is **a stated gap rather
+than a covered one**, and it needs a second inverter to bite.
+
+⚠️ **WHAT YOU WILL SEE.** A new `STALE WITHDRAWN <unit>` line in the action log
+beside the existing `STALE <unit>` one, and a log warning that says in its own
+words that **nothing has been learned about the register**. If the pair repeats
+every ~70 s, the register really is not following and the unit needs looking at;
+if it happens once and stops, the pack was simply empty and the site has
+resumed. The stale line's escape clause was also corrected — it used to promise
+a clearance the state could not produce. ⚠️ Its **diagnosis** half still says
+*"is not following its own command"*, which is wrong in a different way when the
+pack is merely empty; that wording is [[SAFETY-56]]'s and is deliberately
+untouched here.
+
+⚠️ **AND THAT IS NOW A STATEMENT ABOUT 0.10.1 ONLY — [[SAFETY-56]] REWROTE THE
+DIAGNOSIS HALF, AND `## 0.11.0` ABOVE CARRIES THE NEW WORDING.** The quotation
+above is left exactly as it stands because it is what the 0.10.1 image prints,
+and a reader on 0.10.1 needs to recognise it. The same applies to the reading
+rule in the paragraph above: on 0.11.0 the add-on no longer asserts that
+*"the register really is not following"* — it names both explanations and says
+it cannot tell them apart — so *"the pair repeats → look at the unit, it happens
+once and stops → the pack was empty"* stops being a correction of the message
+and becomes the message's own advice. Nothing about **what** the gate does moved
+in either card.
+
 ## 0.10.0
 
 ⚠️ **A CONFIG THAT IS LEGAL ON 0.9.0 IS REFUSED ON 0.10.0, AND THAT - NOT THE
@@ -87,8 +705,20 @@ check.
   **and** is refused by name (rule 11), so the reinterpretation is never
   silent; no blob written before 0.10.0 can carry one.
 
-⚠️ **AND IF YOU ARE UPGRADING FROM 0.7.0 - WHICH THE REFERENCE INSTALL IS -
-THE REFUSAL THAT CAN STOP YOU IS IN 0.8.0'S SECTION, NOT IN THIS ONE.** `ha
+⚠️ **AND 0.10.0 CHANGES THE CONTROL LAW ITSELF, WHICH NOTHING ABOVE AND NO
+CONFIG CHECK WILL TELL YOU ABOUT.** [[SAFETY-48]] bounds how far the
+integrator may run ahead of the command on the cycles where the slew limit is
+what stopped the command moving. It adds no option, moves no default and
+refuses no blob, so every check in this preamble passes it in silence - and it
+is the one change here that alters what the inverter is ASKED TO DO on a tree
+that is otherwise configured identically. ⚠️ **What it is measured to buy is
+less EXPORT. It is NOT a lower capacity-tariff peak, and your billed quarter
+should not be expected to improve.** The whole account, including what it costs
+and what it does not establish, is `### SAFETY-48` below.
+
+⚠️ **AND IF YOU ARE UPGRADING FROM 0.7.0 - WHICH THE REFERENCE INSTALL WAS
+WHEN THIS WAS WRITTEN, AND HAS NOT BEEN SINCE 2026-09-20 - THE REFUSAL THAT CAN
+STOP YOU IS IN 0.8.0'S SECTION, NOT IN THIS ONE.** `ha
 addons update` does not walk the versions; it installs 0.10.0 in one step, so
 **every validator rule added in 0.8.0 and 0.9.0 lands at the same moment as
 0.10.0's own**, and a config that has not been looked at since 0.7.0 meets all
@@ -109,7 +739,10 @@ fire only on a roster entry that USES `capacity_kwh`, a key that did not exist
 `slew_w` against the ceiling and `price_provider` against the withdrawn list
 BEFORE `ha addons update`**, with `tools/predeploy_check.py`, which does both.
 
-✅ **RUN AGAINST THIS RELEASE: CLEARED, exit 0.**
+✅ **RUN AGAINST THIS RELEASE: CLEARED, exit 0.** ⚠️ This is the record of
+a run made on 2026-09-19, when the reference box was still on 0.7.0. That
+crossing has since been made; the box is on 0.10.0 and the transcript below is
+history rather than the state of any install.
 
     docker run --rm -v <repo>:/w:ro -v <dir>:/opt:ro goodwe-addon-checks:1 \
       python3 /w/goodwe_controller/tools/predeploy_check.py \
@@ -120,6 +753,21 @@ BEFORE `ha addons update`**, with `tools/predeploy_check.py`, which does both.
       live options pass this version's validator
       CLEARED for deploy.
 
+⚠️ **THAT RUN WAS MADE ON PKG-14'S TREE, AND [[PKG-15]] DID NOT RE-RUN IT.
+HERE IS WHY IT STILL HOLDS, CHECKED RATHER THAN ASSUMED.** The two tickets
+folded in below touch three files between them - `app/control.py`,
+`app/main.py` and `app/mqtt.py` - and **`config.yaml` is not among them**, so
+the option surface and the 75 defaults the blob is merged over are byte-for-
+byte what that run measured. `app/validate.py` imports neither `main` nor
+`mqtt`; from `control` it imports exactly `SLEW_RAIL_FRAC`, `LOOP_TICK_S` and
+`PLANT_SETTLE_S`, and all three are **unchanged** (`2.0`, `18.0`, and their
+quotient) - [[SAFETY-48]] adds `SLEW_LEAD_STEPS` and reads it inside
+`compute()`, which the validator never calls. ⚠️ **And the tool's OTHER half -
+the no-op check - did not run at all in that transcript**, because it is
+gated on `shipped == deployed` and the box reported `0.7.0` at the time. It is
+the half that refuses this fold on a box already running 0.10.0 - ⚠️ **which
+the reference box now is**; see the closing note below the contents table.
+
 **The option surface: 71 keys -> 75, `options:` and `schema:` in step.** Four
 new keys, and none of them can refuse a blob written before it existed:
 `price_formula`, `price_export_formula` and `price_taxes_profile` are `str?` -
@@ -158,6 +806,44 @@ image does - PKG-13, UX-04, SAFETY-31, ARCH-02, INSTR-01. The count that
 matters for the no-op check is `tools/predeploy_check.py`'s own: **28 runtime
 commits since `86bdf49`**, of which the table below accounts for 21.
 
+⚠️ **RE-MEASURED BY [[PKG-15]] ON 2026-09-19, AFTER FOLDING [[TEL-10]] AND
+[[SAFETY-48]] INTO THIS SECTION: 32 RUNTIME COMMITS SINCE `86bdf49`, OF WHICH
+THE TABLE BELOW NOW ACCOUNTS FOR 24.** Re-derived with `is_runtime()` itself
+rather than by adding to the old figure. The other eight are the three misfiled
+tickets in the table above - SAFETY-43 two commits, SAFETY-44 three, TEST-21
+two - plus `cb3f686`, PKG-14's own bump, which edits `config.yaml` and is
+therefore a runtime commit by that function's rule; it was `HEAD` when PKG-14
+counted, so `last..HEAD` excluded it then and includes it now. The three
+misfiled tickets are still misfiled and still [[PKG-08]]'s card; nothing below
+moves them.
+
+⚠️ **THE VERSION WAS NOT BUMPED FOR THE FOLDS ABOVE, AND THAT ARGUMENT HAS
+NOW EXPIRED. THIS SECTION IS CLOSED.** As written on 2026-09-19 it ran: 0.10.0
+was cut on 2026-09-16, had never been built or pulled anywhere, the reference
+install was on 0.7.0 and this repository carried exactly one tag (`v0.2.1`) and
+no release - so the string `0.10.0` did not yet name a tree anyone was running,
+the PKG-06/PKG-07 no-op could not apply, and cutting 0.11.0 would have burned a
+number on a release that never left the repository. ⚠️ **IT WAS STATED AS
+CONDITIONAL ON THAT REMAINING TRUE, AND IT STOPPED BEING TRUE ON 2026-09-20 AT
+ABOUT 22:18 CEST**, when 0.10.0 was installed on the reference site as a
+repository add-on (slug `68285ac7_goodwe_controller`) and began regulating a
+real battery. **0.10.0 has been built and pulled, and the reference install is
+on 0.10.0, not on 0.7.0.**
+
+⚠️ **AND THE FIELD HISTORY IS NOW THE STRONGEST EVIDENCE IN THIS FILE, WHICH
+IS WHY THE CORRECTION IS WORTH ITS SPACE.** That install has since run a full
+day-night cycle on 0.10.0 - an empty pack, a guard trip, a 2 h 47 min saturation
+freeze, the [[SAFETY-57]] deadlock and a clean recovery - and **two defects came
+out of it that no test in this repository had reached**: [[SAFETY-56]] and
+[[SAFETY-57]]. So nothing may be folded into this section again, and
+`tools/predeploy_check.py` enforces that by itself: run against a box already
+reporting `0.10.0` it refuses with `THE DEPLOY WOULD BE A NO-OP` and names the
+runtime commits since the bump. **SAFETY-57's fix is in `## 0.10.1` above**,
+which is what a patch number is for. ⚠️ **AND SAFETY-56'S IS IN `## 0.11.0`**,
+which is where it went because it landed after 0.10.1 had already been cut. Both
+defects named in this paragraph are now fixed; this section, and `## 0.10.1`
+below it, describe images that still contain them, and are left saying so.
+
 Contents of this release, in merge order since 0.9.0 (`86bdf49`):
 
 | | |
@@ -180,6 +866,176 @@ Contents of this release, in merge order since 0.9.0 (`86bdf49`):
 | `8f82dd4` | SAFETY-45 - a price-driven charge is SIZED by the capacity-tariff guard instead of being switched on and off by it **⚠️ CONTROL STABILITY** |
 | `e6da478` | SAFETY-10 - shadow mode: the whole decision path runs and nothing reaches the inverter **⚠️ NEW OPTION, DEFAULT-ON FOR A NEW INSTALL** |
 | `587495e` | SAFETY-47 - what a shadow run can show you, and the watts on its status row **⚠️ CORRECTS THREE CLAIMS SAFETY-10 SHIPPED** |
+| `660d079` | TEL-10 - the loop's integrator stops being invisible: three new site sensors **⚠️ THREE NEW ENTITIES** |
+| `186a044` | SAFETY-48 - the integrator's lead over the command is bounded at one slew step **⚠️ THE CONTROL LAW CHANGED** |
+| _this branch_ | SAFETY-57 - the stale-reading verdict gets an exit, because its own consequence is what stopped it being tested **⚠️ MEASURED ON THE LIVE SITE** |
+
+⚠️ **[[CI-9]] ALSO MERGED INTO `release/1.0` IN THIS WINDOW AND IS
+DELIBERATELY NOT IN THE TABLE ABOVE, NOR ANYWHERE ELSE IN THIS FILE.** It
+changes exactly one file, `.gitea/workflows/checks.yml`, which is not under
+`goodwe_controller/` at all: it is not in the built image, it is not in
+`predeploy_check.py`'s `RUNTIME` list, and there is no version of this add-on
+on which an operator can observe it. This file is the **add-on's** release note
+- the text the Supervisor puts beside the version number - and the rule PKG-15
+applied is that a row here has to be something the person deciding whether to
+press *Update* could act on. CI-9 is not; the repository's history and PR #95
+are where it is written down, and they have it in full. ⚠️ **THE RULE IS ABOUT
+THE AUDIENCE, NOT ABOUT IMPORTANCE.** CI-9 repaired a merge gate that was
+grading the wrong tree, which is the same class of defect this ticket exists to
+clean up after - and it is still not an operator-facing change. If a future CI
+ticket changes what the shipped image contains, it belongs here; this one does
+not.
+
+### SAFETY-48 — the integrator's lead over the command is bounded, and the control law changed
+
+⚠️ **THIS CHANGES WHAT THE INVERTER IS ASKED TO DO.** It is the only entry in
+0.10.0 that does so without touching an option, a default or the validator, so
+nothing in this section's preamble and no run of `tools/predeploy_check.py`
+will warn you about it. `app/control.py` is in the diff; `config.yaml` is not.
+
+**The defect is a missing case, not a wrong constant.** `compute()` freezes the
+integrator when the inverter is not following, and the comment beside that
+block states the requirement outright — *the INTEGRATOR must stop accumulating,
+not only the command*. But `frozen` was computed from one signal,
+`abs(prev_w - actual_w) > saturation_w`, and **slew-limiting never entered it**.
+The integrator moves `gain × error` per cycle while the command may move at
+most `slew_w`, so the integrator outruns the command whenever
+`|error| > slew_w / gain` — **667 W** at the live tuning, against a measured
+median grid error of **1114 W** at the onset of a recorded episode. ⚠️
+[[SAFETY-39]]'s retune made this **more** frequent, not less: a smaller step is
+a lower threshold.
+
+**What ships** bounds the integrator's **lead over the command** at one slew
+step, inside the branch where the slew is what bound the command, and only in
+the leading direction. Nothing else in the law moves: the output clamp, the
+saturation freeze, the deadband and the 10 W quantisation are unchanged, and
+`test_control.py`'s exhaustive `i_w=None` equivalence sweep against the
+transcribed release/1.0 law still passes untouched — the cap moves `i_w`, not
+`target`.
+
+⚠️ **WHAT IT IS MEASURED TO BUY IS LESS EXPORT — AND EXPLICITLY NOT A LOWER
+CAPACITY-TARIFF PEAK. DO NOT EXPECT YOUR BILLED QUARTER TO IMPROVE.** Replayed
+over 256 252 recorded meter instants spanning 16.00 days of this install
+(`scenarios/loop-2026-09-02_2026-09-17`, committed), same ticks, same
+disturbance, same plant, same seed:
+
+| | release/1.0 | SAFETY-48 |
+|---|---:|---:|
+| **export kWh** | **39.61** | **34.07** |
+| wasted throughput kWh | 4.67 | 3.19 |
+| battery sign reversals | 2992 | 2770 |
+| median recovery s | 232 | 199 |
+| unrecovered (>900 s) | 53 | 31 |
+| worst \|i_w − prev_w\| W | 9200 | 800 |
+
+That is **5.54 kWh less export — 14 % of the replayed figure**, and ⚠️ **the
+direction is what is robust, not the size**: across every plant and tuning
+variant swept it falls, by between ~4 % (at `gain: 0.3`) and ~16 % (at a
+re-fitted gain/offset), the median variant landing near an eighth. At `gain: 0.3` and at `slew_w` set to the rail the
+mean-quarter effect is a tie (−0.17 W and **+0.16 W**), because
+`|error| > slew_w / gain` is rarely satisfied in those regimes and there is
+little for the cap to bite on.
+
+⚠️ **AND THE BILLED QUARTER IS NOT A CLAIM THIS RELEASE MAKES.** The A/B above
+also shows the worst 15-minute average **offtake** moving 3739 → 3434 W, and
+that figure exists at **one plant model**. `fit_plant()` selects a 7.5 s
+inverter lag on battery-power RMS, which separates it from 2.5 s by **0.3 %**,
+while the instrument's own fidelity measure — replayed export against the
+**29.43 kWh this install actually exported** — prefers 2.5 s by the whole 35 %
+gap. Swept properly: **at every lag ≤ 5.0 s, including the one that best
+reproduces the recorded export, release/1.0's worst quarter is already 3434 W
+and this change moves it by exactly zero.** The lag is not identified by this
+recording, and identifying it needs a driven step response that does not exist
+yet. **What this release can say about the billed quantity is that it does not
+make it worse at any lag tried — not that it improves it.**
+
+⚠️ **AND EVERY NUMBER ABOVE IS SIMULATED.** The replay is a first-order plant
+model with a 375 W RMS residual; it prints its own fidelity first and it
+reproduces **39.6 kWh** of export where the install exported **29.4**, i.e. it
+is ~35 % pessimistic about the loop's tracking. Only the **delta** is claimed.
+Nothing here drove an inverter.
+
+**What it costs, stated rather than smoothed:**
+
+* ⚠️ **The cap does move a saturation-frozen integrator**, because it runs
+  before the freeze block and is not gated on `frozen`. Of 79 160 frozen ticks
+  it changed `i_w` on **1095**, and on **679** of those it moved it further out
+  on the side it was already on — putting back magnitude the freeze had just
+  let fall, which is the one direction the freeze's own rule forbids. Worst
+  case **2424 W**. It never overrides a *same-cycle* refusal.
+* **Two committed numbers moved.** [[SAFETY-13]]'s released command settles at
+  −800 W and −1200 W where release/1.0 settled at −1190 W and −2390 W, because
+  there is less wound integrator to settle onto; the property asserted is that
+  it stops at the frozen integrator rather than at the rail.
+* ⚠️ **[[SAFETY-39]]'s claim that "the slew does not own the over-absorption"
+  is now FALSE — inverted**, on the independent first-order plant
+  `test_control.py` writes for itself: 1005/1109/1285/1330 W rising with a
+  slower slew becomes 729/550/424/326 falling. Two plant models that share
+  nothing agree on the sign. SAFETY-39's record carries a forward reference to
+  this one.
+* **The form the card originally asked for was rejected on measurement**, and
+  this is the least lag-sensitive result in the work: reusing the asymmetric
+  freeze on a carried slew flag moves the worst quarter-hour offtake
+  3739 → **3935 W** at the fitted plant, and across the lag sweep it is the
+  worst of the three at **every lag from 2.5 s upward** — 3732 / 3711 / 3935 /
+  4326 W against release/1.0's 3434 / 3434 / 3739 / 3954 — with a tie at lag
+  0.0, and it is worse at **every top-N cut** of the quarters. It also raises
+  the mean quarter (+2.73 W).
+
+`DECISIONS/SAFETY-48-bounding-the-integrator-lead.md` carries all of it,
+including §8, *what this card does NOT establish*.
+
+### TEL-10 — the loop's integrator stops being invisible
+
+**Three new MQTT sensors, and nothing in the control path moved.**
+`app/control.py` is not in this diff: `compute()`, its returned `Decision` and
+every constant it reads are identical to release/1.0.
+
+`self.i_w` has been a separate quantity from the command since [[SAFETY-04]]
+and left the process **nowhere at all** — no entity, no attribute, no log line.
+The investigation behind SAFETY-48 could only *reconstruct* it from the grid
+trace plus a replay; the reconstruction reproduced about a third of the
+engagements it was checked against and was discarded, so a control card had to
+be argued from a measurement nobody could stand behind. It could not have been
+made to work, either: `i_w` depends on every cycle before it, including the
+ones where the arbiter overrode the loop and `main.py` re-seeded it — and that
+re-seed is invisible in the grid trace.
+
+| entity | topic | unit | what it is |
+|---|---|---|---|
+| `Loop integrator` | `goodwe_loop_integrator` | W | the accumulator **after** this cycle — before the output clamp, the slew limit and quantisation |
+| `Loop integrator lead` | `goodwe_loop_integrator_lead` | W | that value minus **the command `compute()` was handed**, i.e. the one the previous cycle left standing |
+| `Loop reason` | `goodwe_loop_reason` | — | the control law's own word for this cycle: `tracking`, `deadband`, `i-clamped`, `clamped`, `slew-limited`, `saturated-freeze`, `freeze-released` or `not-running` |
+
+⚠️ **`Loop integrator lead` IS NOT A SUBTRACTION OF TWO PUBLISHED ROWS, WHICH
+IS WHY IT IS ITS OWN ENTITY.** `Setpoint` is the **arbiter's** output after
+every strategy has had its say, and it is **this** cycle's; the lead is
+measured against the command `compute()` was given, which is the previous one.
+On any cycle the arbiter overrode the loop the two differ — and that is exactly
+the cycle on which the integrator was re-seeded, so a dashboard doing the
+subtraction would get a different number precisely where it matters.
+
+⚠️ **`Loop reason` IS NOT THE `Why` ROW AND NOT `Controller status`.** Both of
+those carry the *arbiter's* sentence — `loop -> -5000 W` — which names the
+winning claim and its watts and has never carried that claim's own reason.
+`slew-limited`, the value [[SAFETY-48]] above is entirely about, appears in
+neither. Measured on one cycle: arbiter `'loop -> -5000 W'`, loop `'i-clamped'`.
+
+⚠️ **NOTHING EXISTING IS RENAMED, RE-TYPED OR RE-ORDERED.** The three are
+**appended** after the nine messages release/1.0 already announces, and all
+nine stay **byte-identical**. ⚠️ Eight of them also stay **first**, which is
+what `test_mqtt.py` part 1's prefix comparison grades; the ninth,
+`goodwe_ctl/availability`, is byte-identical but deliberately moves to **last**,
+so a prefix comparison cannot cover it and the check on the next line pins it
+in its new position instead. **They are SITE rows, not per-unit ones** — there
+is one integrator, so a per-unit copy would invent N of a thing there is one of
+— and they therefore appear at **every** roster length, **including a roster of
+one**, where the per-unit machinery announces nothing new at all.
+
+Both numbers carry `state_class: measurement`, so the recorder keeps long-term
+statistics for them. `DOCS.md` has the operator account, including how to read
+a standing lead: the cycles needed to unwind it are that lead divided by
+`slew_w`.
 
 ### SAFETY-47 — what a shadow run can show you, and the watts on its status row
 

goodwe_controller/DECISIONS/SAFETY-39-slew-against-the-rail.md

@@ -187,6 +187,23 @@ over-absorption. So the rig does not choose the number — **the constraint
 chooses it, and the rig says what the constraint does and does not buy.** That
 is the same relationship the 2026-08-22 table had to its own three columns.
 
+⚠️ **FORWARD REFERENCE, ADDED BY SAFETY-48 — THIS TABLE AND THIS SENTENCE ARE
+TRUE OF release/1.0's LAW AND FALSE OF THE ONE THAT REPLACED IT.** Nothing above
+is retracted: re-run on release/1.0 today the same rig prints the same column
+(958 / 1107 / 1133 / 1058 / 987 / 1029 / 1150 / 1143 / 1081 W), flat,
+non-monotone, 800 better than 556. Under SAFETY-48's lead cap the **same script
+on the same plant** prints 777 / 734 / 663 / 563 / 553 / 507 / 435 / 358 / 321 W
+— falling monotonically, so a slower slew is now *better* and the sentence above
+inverts. The mechanism SAFETY-39 identified is exactly why: `slew_w` bounds the
+OUTPUT while the integrator goes on accumulating `gain · error`, so slowing the
+slew used to buy nothing; bound the integrator's lead and it starts to.
+`tools/slew_sim.py --slew` now names which of the two laws it is running under
+before it narrates the column, and
+`DECISIONS/SAFETY-48-bounding-the-integrator-lead.md` §6 carries both tables and
+the independent confirmation from `test_control.py`'s own plant model. ⚠️ **This
+does NOT re-open the choice of 556**: the constraint picks the number, the rig
+does not, and that is unchanged in both laws.
+
 ⚠️ **A single step is not evidence here.** The deadband, the 10 W quantisation
 and the phase of the step against the tick move the result by hundreds of watts,
 non-monotonically. The first cut of this derivation was a single step and ranked

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-48-bounding-the-integrator-lead.md

@@ -0,0 +1,551 @@
+# SAFETY-48 — the slew step ceiling reaches the integrator, and what it bounds is the LEAD
+
+**Status:** decided and implemented on branch `SAFETY-48`, on top of `TEL-10`.
+**Card:** SAFETY-48 — *"the integrator goes on winding while the command is
+slew-limited"*.
+**Nothing here reached the inverter.** The live install still runs `slew_w: 400`
+applied by hand on 2026-09-05 12:00 and `release/1.0`'s control law. This branch
+does not deploy and does not bump the version.
+
+---
+
+## 0. The four things a reader should take away
+
+1. **It is a missing case, not a wrong constant, and the arithmetic says so.**
+   The integrator moves `gain * error` a cycle and the command moves at most
+   `slew_w`, so the integrator outruns the command whenever
+   `|error| > slew_w / gain` — 667 W at the live shape. SAFETY-39's retune made
+   `slew_w` **smaller**, which makes that threshold **lower**. §1.
+2. ⚠️ **THE FORM THE CARD ASKED FOR RAISES THE BILLED QUANTITY, AND THAT IS WHY
+   IT IS NOT WHAT SHIPPED.** Reusing the asymmetric freeze on a carried slew
+   flag cuts export 13 % and moves the worst quarter-hour average **offtake**
+   from 3739 W to **3935 W**, with the mean quarter +2.7 W — and on the billed
+   quarter it is worse at **every plant lag where release/1.0 produces a peak
+   at all** (a tie at lag 0, worse at 2.5 / 5.0 / 7.5 / 10.0 s) and at **every
+   top-N cut of the quarters**, which makes this the least lag-sensitive result
+   in the card. The harm is a tail redistribution inside quarters that already
+   net to offtake, not a weaker answer to import in aggregate. §3, §3a.
+3. **What ships bounds the LEAD at one slew step, only where the slew is what
+   stopped the command, and only in the leading direction.** The robust result
+   is the **export reduction — 39.6 → 34.1 kWh, and it falls at every plant and
+   tuning tried** — with wasted throughput 4.67 → 3.19 kWh, sign reversals
+   2992 → 2770 and median recovery 232 → 199 s. ⚠️ **The billed quarter is not
+   something this card can claim.** It reads 3739 → **3434 W** at the fitted
+   plant lag of 7.5 s; at every lag ≤ 5.0 s — including the one that best
+   reproduces the recorded export — release/1.0 is *already* at 3434 W and this
+   card moves it by exactly zero. The lag is not identified by the data. §4,
+   §3a.
+4. **Two committed numbers moved and neither is a silent edit.** SAFETY-13's
+   released command settles lower, because there is less wound integrator to
+   settle onto; and SAFETY-39's *"the slew does not own the over-absorption"* is
+   now **false — inverted, on its own independent plant model.** §5, §6.
+
+---
+
+## 1. The defect, in the terms the code uses
+
+`compute()` freezes the integrator with an asymmetric rule, and the comment
+beside it states the requirement outright:
+
+> the requirement is that the INTEGRATOR stop accumulating, not only the command
+
+But `frozen` is computed from **one** signal:
+
+```python
+saturated_now = abs(prev_w - actual_w) > tuning.saturation_w   # not tracking
+```
+
+Slew-limiting never enters it. When the command hits the step ceiling the
+integrator keeps winding at `gain * error` until it reaches `integrator_max_w`,
+and the unwind afterwards is `integrator_max_w / slew_w` cycles — 12.5 at the
+live shape, about a minute at the meter's measured tick.
+
+⚠️ **AND THE RETUNE MADE IT MORE FREQUENT, NOT LESS.** `|error| > slew_w / gain`
+is 1667 W at `slew_w: 1000` and **667 W** at `slew_w: 400`. The measured median
+grid error at the onset of a recorded episode is 1114 W — above the second
+threshold and below the first. This is why SAFETY-39 did not fix it, and the
+mechanism is the same one §6 shows inverting.
+
+## 2. How it was measured, and what the measurement cannot say
+
+`tools/replay_recorded_loop.py`, over **16.00 days / 256 252 meter instants** of
+the live install's own recorder, exported read-only.
+
+**Real:** the disturbance (`D = grid + batt` at every recorded meter instant —
+the house with this loop's own battery taken back out, which is exogenous and
+therefore valid to drive a counterfactual with); the tick (the meter's own
+recorded instants, median **5.01 s**); and the control law, imported out of the
+checkout. The "before" law is the **same file** with the SAFETY-48 block removed
+by a named substitution and exec'd into a fresh namespace — never a
+transcription — and a missing or duplicated anchor is a **refusal** with
+`NOTHING HAS BEEN MEASURED` on it, because an instrument that quietly compared
+the shipped law with itself would report the card as changing nothing.
+
+**Modelled:** the inverter (pure delay 7.5 s + first-order lag 2.0 s +
+`batt = 0.973 × cmd − 22.4 W`, fitted on this same recording above the SoC
+floor, residual **375 W RMS**); the pack (SoC integrated, discharge refused at
+or below the floor); and **everything else the arbiter does** — the recorded
+setpoint is the arbiter's output after the peak guard, the SoC clamps,
+maintenance and arbitrage, while the replay runs `compute()` alone.
+
+⚠️ **THE ABSOLUTE FIGURES ARE PESSIMISTIC BY ABOUT A THIRD AND THE TOOL PRINTS
+IT ON EVERY RUN.** Replaying the before-law reproduces 39.6 kWh of export where
+the install actually exported **29.4 kWh** over the same window. The delta is
+what this instrument is for: both laws run on the same ticks, the same
+disturbance, the same plant and the same seed.
+
+⚠️ **THE SoC FILTER ON THE PLANT FIT IS THE WHOLE FIT, AND IT IS A FINDING IN
+ITS OWN RIGHT.** This install spends **36 % of its ticks at or below a 10 % SoC
+with the command standing near 2 kW and the battery delivering nothing.** Fitted
+over all ticks the recording says `batt = 0.50 × cmd − 396 W, r = 0.70` — a
+plant that follows half the command, which no inverter does. Above the floor the
+same data says `batt = 1.00 × cmd − 28 W, r = 0.977`. The floor is the PACK and
+is modelled separately.
+
+## 3. The form the card asked for, and the number that refused it
+
+The card asked for the asymmetric rule already in service for saturation, on a
+flag carried across cycles the way `sat_count` is. It was built — from
+release/1.0's own source, one substitution per change — and measured on the same
+16 days through the same pipeline:
+
+| | release/1.0 | **form A** — carried slew flag + the asymmetric freeze | **SAFETY-48** — the lead cap |
+|---|---:|---:|---:|
+| export kWh | 39.61 | 34.43 | **34.07** |
+| import kWh | 116.07 | 110.62 | 111.20 |
+| battery sign reversals | 2992 | **2656** | 2770 |
+| wasted throughput kWh | 4.67 | **2.99** | 3.19 |
+| **worst 15-min offtake W** | 3739 | ⚠️ **3935** | **3434** |
+| mean quarter-hour offtake delta | — | ⚠️ **+2.73 W** | **−2.39 W** |
+| worst quarter-hour delta | — | +992 W | +532 W |
+| recovery median s | 232 | **184** | 199 |
+| recovery p99 s | 849 | **781** | 850 |
+| recovery max s | 901 | 890 | 898 |
+| unrecovered (> 900 s) | 53 | **26** | 31 |
+| \|i_w − prev_w\| p99 W | 3361 | 1534 | **800** |
+| \|i_w − prev_w\| max W | 9200 | 6912 | **800** |
+
+**Form A wins on four rows and loses on the one that is billed.** The capacity
+tariff (*capaciteitstarief*) bills the month's worst quarter-hour average
+offtake, and form A raises it by **196 W** — and raises the MEAN quarter by
+2.7 W, so this is systematic and not one unlucky quarter. It does so in **five
+of the six** plant and tuning variants in `--sensitivity`; the sixth is a tie.
+
+The per-cycle mechanism is that a frozen integrator stops at
+`prev + gain·error(first cycle)`, which is `(1 − gain)` short of what the site
+needs — 40 % short at `gain: 0.6`.
+
+⚠️ **AND THE SENTENCE THAT USED TO FOLLOW THAT ONE WAS TOO BIG FOR THE DATA.**
+It read *"for an IMPORT it is offtake, so a large import is answered too weakly
+for as long as the ramp lasts"*. The aggregate does not show a weaker answer to
+import: form A cuts total import by **5.45 kWh** and export by **5.18 kWh**
+against release/1.0, and paired tick by tick it delivers **8.56 kWh LESS**
+offtake energy on the ticks release/1.0 spent importing (lower on 38 229 such
+ticks, higher on 19 669). What form A moves is the **TAIL, within quarters that
+already net to offtake** — the worst quarter goes 3739 → 3935 W, the top five
+3260 → 3300 W, the top fifty 1880.0 → 1882.7 W. The capacity tariff bills the
+worst quarter and nothing else, so a redistribution that leaves the mean alone
+and lifts the maximum is exactly the trade that is refused here. The conclusion
+is unchanged; the causal sentence is now the one the data supports.
+
+⚠️ **THE CARD SAID "do not invent a second rule", AND THE MEASUREMENT SAYS TO.**
+That instruction is recorded here rather than quietly dropped. What ships is a
+different rule; the paragraph above is why.
+
+## 3a. ⚠️ The plant lag is NOT identified by this recording, and the billed quarter is the claim that depends on it
+
+`fit_plant()` picks `lag 7.5 s` because it minimises **battery-power RMS**. That
+objective barely distinguishes the candidates — 375.3 W at 7.5 s against 376.4 W
+at 2.5 s, **0.3 %** — while the tool's *own* printed fidelity measure, replayed
+export against the **29.43 kWh this install actually exported**, prefers 2.5 s by
+the whole of the 35 % gap the header warns about. Two measures on the same data
+disagree, and nothing here breaks the tie.
+
+So the sweep has to be read as a sensitivity, not as a confirmation:
+
+| plant lag | fit RMS W | replayed export kWh (release/1.0) | **worst 15-min offtake W:** release/1.0 | form A | SAFETY-48 | mean quarter ΔW |
+|---:|---:|---:|---:|---:|---:|---:|
+| 0.0 | 392.3 | 23.5 | **3434** | 3434 | **3434** | +0.53 |
+| 2.5 | **376.4** | **28.9** ← nearest 29.43 | **3434** | ⚠️ 3732 | **3434** | −0.59 |
+| 5.0 | 378.0 | 32.1 | **3434** | ⚠️ 3711 | **3434** | −1.02 |
+| 7.5 | **375.3** ← chosen | 39.6 | 3739 | ⚠️ 3935 | **3434** | −2.39 |
+| 10.0 | 384.2 | 75.4 | 3954 | ⚠️ 4326 | **3434** | −4.65 |
+
+(The RMS column is `fit_plant()`'s own inner sweep pinned to one lag — best `tau`
+and a re-fitted gain/offset at that lag. The export and quarter columns follow
+`--sensitivity`'s convention instead: only the lag is substituted into the
+global fit, everything else held. That is why the lag 5.0 and 10.0 export
+figures are the ones already printed in §7b.)
+
+⚠️ **AT EVERY LAG ≤ 5.0 s THE IMPROVEMENT IS NOT AN IMPROVEMENT — IT IS AN
+ABSENCE.** release/1.0's worst quarter is *already* 3434 W there and SAFETY-48
+changes it by **exactly zero**. §7b's paragraph used to read the `3434 → 3434`
+rows as "the direction does not move"; that is the wrong reading. The direction
+has nothing to move: at those plants release/1.0 never produces a quarter worse
+than 3434 W in the first place, and the 3739 → 3434 W headline exists only at
+the single longest lag `fit_plant()` happens to select. **The peak claim is a
+property of the plant model, not of the card.** What the card can claim on the
+billed quantity is that it does not make it worse, at any lag.
+
+⚠️ **AND THE ONE RESULT HERE THAT IS NOT LAG-SENSITIVE IS THE FORM-A
+REJECTION.** Form A's worst quarter is the worst of the three at **every lag
+where release/1.0 produces a peak at all** — 3732, 3711, 3935, 4326 against
+release/1.0's 3434, 3434, 3739, 3954 at lags 2.5 / 5.0 / 7.5 / 10.0, and a tie
+at lag 0.0 where both sit at 3434. It is worse at every top-N cut of the
+quarters at the fitted plant (top-1 3934.6 against 3738.7, top-5 3299.7 against
+3260.5, top-10 2890.6 against 2871.0, top-50 1882.7 against 1880.0, top-100
+1481.7 against 1479.0), and it raises the mean quarter. §3 understated this: the rejection does not rest on one unlucky
+quarter at one plant, which is exactly the objection a lag-sensitive result
+invites.
+
+⚠️ **WHAT WOULD SETTLE IT IS NOT IN THIS RECORDING.** Both objectives above are
+computed from the same four recorded entities, and they disagree; nothing else
+in the capture breaks the tie, and this card did not go looking for a third
+objective after seeing which lag each of the first two preferred. A driven step
+response — the command timestamped where it is written rather than where Home
+Assistant recorded it — is what identifies a lag. That is a rig measurement and
+it is not this card. Until it exists, the export reduction is what this card
+delivers and the peak figure is a plant-model artefact.
+
+## 4. What ships
+
+```python
+    slew = slew_limit_w(tuning)
+    slewed = max(prev_w - slew, min(prev_w + slew, target))
+    if slewed != target:
+        reason = "slew-limited"
+        _lead_cap = SLEW_LEAD_STEPS * slew
+        if target > slewed:
+            i_w = min(i_w, slewed + _lead_cap)
+        elif target < slewed:
+            i_w = max(i_w, slewed - _lead_cap)
+    target = slewed
+```
+
+Four properties, and each of them is a decision:
+
+* **It is inside the branch**, and ⚠️ **that placement was a SURVIVOR of all
+  thirty files until a check was written for it.** Applying it to every cycle
+  instead — `i_w = max(target - cap, min(target + cap, i_w))` after
+  `target = slewed`, −92 B — is **bit-identical on the shipped configuration**:
+  0 of 256 246 ticks differ over the 16-day recording. The two separate **only**
+  where `integrator_max_w` is set ABOVE `max_w` — the configuration `control.py`
+  says is the only way its `clamped` reason is reachable. There the integrator
+  is *deliberately* allowed above the rail, and an unconditional cap would drag
+  it back to the command every cycle and make the option inert.
+  `test_telemetry.py` part 4 drives that configuration, and the unconditional
+  form is red on it.
+
+  ⚠️ **THE COUNT OF SEPARABLE STATES IS DECORATION AND THREE SWEEPS DISAGREE
+  ABOUT IT.** This card's grid gave **2050 of 257 400**; an independent review
+  measured **1220 of 246 064**; a third, smaller grid (four tunings × 7 `prev_w`
+  × 9 `grid_w` × 5 `actual_w` × 8 `i_w` including `None` × 4 `sat_count`) gives
+  **776 of 40 320** — and that third one is spelled out here precisely because
+  the first two are not, which is the whole reason they cannot be reconciled.
+  No count here should be read as exact without the grid beside it. All three
+  agree on the load-bearing part, which is **where**: every separable state sits
+  in the `integrator_max_w > max_w` tuning and nowhere else.
+
+  ⚠️ **AND AN EARLIER DRAFT OF THIS BULLET GAVE THE WRONG REASON AND THE WRONG
+  NUMBER.** It said the two forms differ on 118 ticks because an unconditional
+  cap would pull the integrator toward a command the SATURATION freeze is
+  pinning. That 118 was measured against a *different* pair — a band applied
+  after quantisation, at the very end of `compute()` — and the saturation story
+  does not apply to the placement actually being compared, which sits before
+  the freeze. The figures above are the ones that were measured on the pair the
+  sentence names.
+
+  ⚠️ **AND THE SATURATION STORY IS NOT MERELY INAPPLICABLE — IT IS BACKWARDS.
+  THE NARROW CAP THAT SHIPPED *DOES* MOVE A SATURATION-FROZEN INTEGRATOR.** It
+  sits before the freeze block and is not gated on `frozen`. Measured on the
+  same 16 days at the live shape: of **79 160** frozen ticks the cap changed
+  `i_w` on **1095**, and on **679** of those it moved it further out on the side
+  it was already on — putting back magnitude the freeze had just let fall, which
+  is the one direction the freeze's rule ("may fall, never rise") exists to
+  forbid. Worst case **2424 W**, at
+  `prev_w −3400 W, grid +4697 W, actual −4144 W, sat_count 2 → 3`: the freeze
+  leaves the integrator at **−176 W**, the slew binds, and the cap drags it to
+  **−2600 W**. It never overrides a *same-cycle* refusal — the freeze clipped
+  `moved` on 75 512 ticks and the slew bound on none of them — but the claim
+  that this placement leaves the frozen path alone is false, and §5 is where
+  that shows up in a committed number.
+* **It is written one-sided, and that is a CLARITY choice, not a correctness
+  one.** ⚠️ **An earlier draft of this file and of the comment in `control.py`
+  said the two-sided band `max(slewed - cap, min(slewed + cap, i_w))` was a bug
+  that would drag a TRAILING integrator up toward the command. That was
+  invented, and the sweep said so: the two spellings agree on 205 920 of
+  205 920 cases** across four tunings, every sign of `prev_w`, `grid_w`,
+  `actual_w` and `i_w`, and the `i_w=None` path. `target` is monotone in `i_w`,
+  so when the slew binds `i_w` lies on the same side of `slewed` as `target`
+  does and the other clamp cannot reach. The one-sided form stays because it
+  NAMES the side the lead is on; the equivalence is recorded so the next reader
+  finds a measurement instead of an argument.
+* **It moves `i_w` and not `target`.** This cycle's command is already decided;
+  what is bounded is what gets CARRIED. That is also why the exhaustive
+  `i_w=None` equivalence sweep in `test_control.py` is untouched — it compares
+  `(target_w, sat_count, frozen, reason)`, none of which this moves.
+* **The cap is in STEPS, not watts**, for SAFETY-39's reason: a watt figure is a
+  constant that outlives the `slew_w` it was derived against. `SLEW_LEAD_STEPS`
+  moves with `slew_limit_w()` and therefore with the rail.
+
+⚠️ **ONE STEP, AND NOT ZERO.** `i_w = slewed` is full back-calculation, and
+`control.py`'s own docstring says what that costs: passing `i_w=None` *"reduces
+this function to the exact velocity form it replaced"*. A zero cap makes `i_w`
+identically the command on every cycle, which is that collapse written from the
+other end. Measured, it is **better** — export 32.02 kWh against 34.07, mean
+quarter −3.69 W against −2.39 — and it is still refused, because it throws away
+the reason the accumulator was split out at all. That 2 kWh is the price of
+keeping the bounded form, and it is stated rather than hidden.
+
+⚠️ **TWO LEADS, AND CONFUSING THEM IS HOW A CHECK GETS WRITTEN WRONG.** The cap
+bounds `i_w − target`, the command this cycle EMITS, at one step — which is what
+makes the unwind one cycle. `Decision.i_w − prev_w`, which is what TEL-10's
+`loop_lead` publishes, is measured against the command the PREVIOUS cycle left
+standing, and the emitted command is itself one step further on: the published
+figure is bounded by **two** steps. Both bounds are asserted, each against its
+own number.
+
+### The two recorded deadlocks, driven rather than argued
+
+`control.py` names two encodings that produce a permanently stuck loop, and a
+gate written on the integrator is exactly the edit that brings them back.
+Neither is reachable here and both are test cases in `test_telemetry.py` part 4:
+
+* **the shrink-only encoding** — *"only corrections that shrink |i_w|"* is
+  unsatisfiable for both signs whenever the correction is larger than twice the
+  integrator, and the loop then sits at its last value forever (measured before
+  the fix: 0 W held indefinitely into a 2 kW import). SAFETY-48 is not a shrink
+  rule; it caps the lead beyond one slew step and only while the slew binds.
+* **`i_w == 0.0`** — `main.py` resets the integrator to exactly 0.0 on every
+  stop and every reseed, and *"may not wind further in the direction it is
+  already pushing"* has no referent there. SAFETY-48 does not touch that gate;
+  the first push from zero is driven and asserted to move.
+
+And a third, specific to this card: **the cap cannot latch.** The flag is not
+carried, and after the cap `|i_w − slewed| = cap`, so the next cycle's command
+covers it in one step and the slew stops binding — after which the integrator
+accumulates freely again. The driven check asserts the command still walks all
+the way to the rail on a railed export.
+
+## 5. What this card COSTS, stated rather than smoothed
+
+**SAFETY-13's release buys back less.** That card's own scenario — a second
+writer holding the pack at +700 W, the command pinned, then released — settles
+at **−800 W** where release/1.0 settled at −1190 W against an integrator of
+−1194 W; and its sibling run settles at **−1200 W** where release/1.0 settled at
+−2390 W. The property AC 4 asserts is unchanged: the released command stops at
+the frozen integrator and not at the rail.
+
+⚠️ **AND THE TWO MOVED FOR TWO DIFFERENT REASONS, WHICH THE ONE-LINE EXPLANATION
+"how far that integrator had been allowed to wind" COVERS ONLY HALF OF.** Gating
+the cap on `not frozen` — one line, `if frozen: _lead_cap = float("inf")`, so
+the cap becomes a no-op while frozen — puts **part 5 back at release/1.0's
+−1190 W exactly**. That run moved because the cap **fires on frozen cycles**
+(§4). **Part 4(b) does not come back**: it is −1200 W gated and −1200 W shipped,
+against release/1.0's −2390 W, because *that* one moved for the winding reason.
+Both literals in `test_control.py` were re-baselined **with the reason beside
+them**, and the second is now asserted against `i_w` rather than against a
+number.
+
+**The alternative that avoids it was measured and rejected.** Gating the cap on
+`not frozen` as above gives export **34.71 kWh** (against 34.07), worst quarter
+**3434 W** (the same as shipped), wasted **3.49 kWh** (against 3.19) — and a
+worst observed lead of **4961 W**, i.e. no bound at all on the quantity this
+card exists to bound. A bound with an exception large enough to drive a truck
+through is not a bound. ⚠️ These four figures replace an earlier set (34.9,
+3461 W, 3.5 kWh, 4966 W) that does not reproduce on this tree with the gate
+spelled as above; the gate spelling is written out here so the next reader can
+re-run it rather than re-derive it.
+
+**One quarter-hour in 1534 is 532 W worse.** The billed figure is a MAXIMUM, and
+at the fitted plant lag the maximum improves (3739 → 3434 W); no quarter under
+SAFETY-48 reaches release/1.0's own worst. The mean moves the right way. The
+tail is reported because a maximum over 1534 quarters is decided by one of them
+— and §3a is the reason that improvement is not claimed as a benefit of the
+card: at every shorter plant lag release/1.0's own maximum is already 3434 W.
+
+## 6. The independent confirmation, which arrived as a failing check
+
+`test_control.py`'s SAFETY-39 section drives a family of 51 synthetic export
+steps through a **first-order plant this file writes itself** — no relation to
+the replay, no recorded data in it at all. It carried this assertion:
+
+> ⚠️ THE SLEW DOES NOT OWN THE OVER-ABSORPTION … Quartering the slew from 1000
+> to 250 does not reduce the over-absorption at all
+
+and it was right about the mechanism and therefore wrong about the conclusion:
+`slew_w` bounds the OUTPUT while the integrator accumulates `gain · error`, so a
+slower slew left the integrator winding for longer. Worst case over the family:
+
+| `slew_w` | release/1.0 | this branch |
+|---|---:|---:|
+| 1000 | 1005 W | **729 W** |
+| 0 (the rail, 556) | 1109 W | **550 W** |
+| 400 (the live interim) | 1285 W | **424 W** |
+| 250 | 1330 W | **326 W** |
+
+**The ranking inverts.** Before: slower is worse, monotonically. After: slower is
+better, monotonically. Two plant models that share nothing agree on the sign,
+which is worth more than either alone — and it means SAFETY-39's *"gain is the
+next constant to re-derive"* is now only half true: with the lead bounded, the
+slew owns a share of the over-absorption it did not own before. `gain` is still
+not touched here, for SAFETY-39's own reason: two live control-law constants
+moving in one release makes the next measurement uninterpretable.
+
+⚠️ **AND THE RIG SAYS THE SAME THING, WHICH MEANS TWO COMMITTED TRANSCRIPTS
+CHANGED MEANING UNDER THIS CARD.** `tools/slew_sim.py --slew` runs the same
+derivation on admin/goodwe's `plantsim.Plant`, a third model again. Worst-case
+over-absorption over its 51-step family, `slew_w` from 1000 down to 250:
+
+| `slew_w` | 1000 | 800 | 700 | 600 | 556 | 500 | 400 | 300 | 250 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| release/1.0 | 958 | 1107 | 1133 | 1058 | 987 | 1029 | 1150 | 1143 | 1081 |
+| **this branch** | 777 | 734 | 663 | 563 | 553 | 507 | 435 | 358 | 321 |
+
+release/1.0's row is flat and non-monotone and **800 really is better than 556**
+on that column — SAFETY-39 measured it correctly and its §3 sentence is true of
+the law it was written against. This branch's row falls monotonically. So
+SAFETY-39's record is not retracted; it is given a **forward reference**, and
+`slew_sim.py`'s own narration now reads `SLEW_LEAD_STEPS` out of the control law
+it imported and says which of the two tables it is printing. MUTATION.md habit 8
+— a committed transcript is a check, and a transcript whose prose contradicts
+its own table is a failing one.
+
+## 7. Verified by breaking it
+
+**The law.** `test_telemetry.py` part 4 and `test_control.py`'s SAFETY-39
+section. The mutation table is in `test_telemetry.py`'s header.
+
+**The instrument** (MUTATION.md habit 8 — anything under `tools/` that a
+document quotes is subject to the battery):
+
+| # | mutation to `app/control.py` | what the instrument did |
+|---|---|---|
+| I2 | the whole SAFETY-48 block deleted | **REFUSED**, exit 1, `NOTHING HAS BEEN MEASURED` — not a zero delta |
+| I3 | the anchor line itself edited | **REFUSED**, same message |
+| I3b | `SLEW_LEAD_STEPS = 1000` — the cap present but inert | **every row +0.00**, which is the honest report that the block is doing nothing |
+| I4 | `SLEW_LEAD_STEPS = 0` — full back-calculation | every row moves further; this is the rejected form's number in §4 |
+
+I3b is the one that matters: it proves the delta in §3 is caused by the block
+and not by the two runs differing for some other reason.
+
+**The law**, driven in the CI image on a purged tree, fingerprinted before,
+after and after the revert:
+
+| # | mutation to `app/control.py` | bytes | reds |
+|---|---|---:|---|
+| L1 | the whole SAFETY-48 block deleted | −195 B | 5 in `test_telemetry.py`, 4 in `test_control.py` |
+| L2 | `SLEW_LEAD_STEPS = 0` — the velocity form | +0 B | 4 + 3 |
+| L3 | `SLEW_LEAD_STEPS = 12` — a cap above the rail | +1 B | 4 + 3 |
+| L4 | the cap applied unconditionally, outside the slew branch | −92 B | 1 + 0 — **and it was a SURVIVOR of all thirty files before that check existed** |
+| L5a | the `min`/`max` FUNCTION names exchanged | +0 B | 5 + 5, one of them `test_control.py`'s own "frozen integrator never deadlocks" over 13 041 states |
+| L5b | the two BRANCH BODIES exchanged — the other reading of "the cap on the wrong side" | +0 B | 5 + 4, and it does **not** reach the deadlock sweep |
+| L6 | the lead measured against `prev_w` rather than the command emitted | +0 B | 6 + 3 |
+
+⚠️ **L5 AND L6 ARE BOTH ZERO BYTES** — `min`/`max` and `slewed`/`prev_w` are
+each the same length — so no fingerprint and no byte delta can see either, and
+one of L5a's reds is `test_control.py`'s own *"frozen integrator never
+deadlocks"* sweep over 13 041 states, written by SAFETY-13 for a different
+reason.
+
+⚠️ **THREE OF THESE COUNTS WERE WRONG AND ARE RE-MEASURED ABOVE, WHICH IS
+MUTATION.md's REPORTING RULE 3 APPLIED TO THIS CARD'S OWN TABLE.** The earlier
+row gave L5 as 2 + 5 and L6 as 4 + 3; driven again in the CI image on a `cp -a`
+of this tree, purged, `:ro`, one file at a time, they are **5 + 5** and
+**6 + 3**. ⚠️ **AND "L5" NAMED TWO DIFFERENT MUTATIONS.** "`min`/`max` swapped"
+can mean the function names exchanged or the branch bodies exchanged; they are
+both red, they are both the cap on the wrong side, and they give different
+counts (5 + 5 against 5 + 4) and reach different checks. A row that writes one
+number for a mutation a reader cannot re-derive from its own description is a
+row that cannot be re-run, so both spellings are listed. The directions in the
+original table were all correct; the counts were decoration, and decoration in
+a mutation table reads as evidence.
+
+## 7b. The transcript, quoted rather than summarised
+
+`python3 tools/replay_recorded_loop.py --sensitivity`, on this branch, 58 s:
+
+```
+THE RECORDING: 256252 meter instants over 16.00 days, loop-2026-09-02_2026-09-17
+    tick   p5 4.77 s   median 5.01 s   p95 7.86 s   (control.LOOP_TICK_S says 2.0)
+    the recorded command: extremes -5000 / +5000 W  ->  max_w 5000;  most common step above 100 W is 400 W, 9924 times  ->  slew_w 400
+    the fitted inverter: lag 7.5 s, tau 2.0 s, batt = 0.9731 x cmd -22.4 W, residual 375 W RMS above the SoC floor
+
+FIDELITY - the BEFORE law replayed against the recording it came from
+    setpoint  r=0.887  mean     +601 W simulated vs     +739 W recorded
+    grid      r=0.682  mean     +195 W simulated vs     +239 W recorded
+    export       39.61 kWh simulated vs    29.43 kWh recorded  ->  the model is +35 % PESSIMISTIC about the loop's tracking
+
+THE A/B, same ticks, same disturbance, same plant, same seed
+                                 release/1.0     SAFETY-48       delta
+    export kWh                         39.61         34.07       -5.54   the cost
+    import kWh                        116.07        111.20       -4.86
+    battery sign reversals           2992.00       2770.00     -222.00
+    wasted throughput kWh               4.67          3.19       -1.48
+    worst 15-min offtake W           3738.67       3433.94     -304.74   ⚠️ THE BILLED ONE
+    recovery events                   549.00        612.00      +63.00
+    recovery median s                 232.06        199.04      -33.01
+    recovery p99 s                    849.00        849.94       +0.94
+    recovery max s                    901.06        898.40       -2.66
+    unrecovered (>900 s)               53.00         31.00      -22.00
+    |i_w - prev_w| p99 W             3361.12        800.00    -2561.12
+    |i_w - prev_w| max W             9200.00        800.00    -8400.00
+    slew-limited ticks              16392.00      11654.00    -4738.00
+    mean quarter delta W                                         -2.39   over 1534 quarters
+    worst quarter delta W                                      +532.27
+
+SENSITIVITY - the ranking, not the watts
+      variant                               export kWh           worst quarter W   mean quarter dW
+      plant lag 5.0 s                32.1 ->     27.2         3434 ->     3434             -1.02
+      plant lag 10.0 s               75.4 ->     68.3         3954 ->     3434             -4.65
+      plant tau 8 s                  56.5 ->     49.8         3995 ->     3605             -3.30
+      gain 1.0135, offset -26        46.8 ->     39.3         3713 ->     3434             -3.27
+      slew_w 555.6 (the rail)        36.5 ->     34.4         3434 ->     3434             -0.17
+      gain 0.3                       28.1 ->     27.0         3434 ->     3434             +0.16
+
+    (58 s)
+```
+
+⚠️ **`--sensitivity` IS THE RANKING AND NOT THE WATTS.** The export figure moves
+by a factor of two across these plants; what does not move is the direction —
+**on export**. ⚠️ **THE `worst quarter W` COLUMN IS NOT THE SAME KIND OF
+EVIDENCE AND THIS PARAGRAPH USED TO TREAT IT AS IF IT WERE.** Three of its six
+rows read `3434 -> 3434`, and that is not "the direction holds": it is
+release/1.0 *already sitting at 3434 W* on those plants, with nothing for the
+card to improve. §3a sweeps the lag properly and finds the same thing at every
+lag ≤ 5.0 s. The billed-quarter improvement in the A/B table above exists at one
+plant, the one `fit_plant()` selects by an objective that separates it from its
+neighbour by 0.3 %.
+
+Two rows deserve naming rather than rounding: at `slew_w: 555.6` (the rail) and
+at `gain: 0.3` the mean quarter-hour delta is −0.17 W and **+0.16 W** — ties,
+not improvements. Both are regimes where `|error| > slew_w / gain` is rarely
+satisfied (1333 W at `gain: 0.3`, 926 W at the rail against a measured median
+onset error of 1114 W), so there is little for the card to bite on. That is the
+mechanism agreeing with itself, and it is also the honest answer to "would this
+still be worth shipping if the tuning moved": at `gain: 0.3` it would not be.
+
+## 8. What this card does NOT establish
+
+* **Nothing here drives an inverter.** The replay is a model with a 375 W
+  residual and no arbiter in it. The closed-loop answer comes from the rig or
+  from a live run — SAFETY-47 records why a shadow run cannot give it.
+* **The live tick is 5.0 s, not `LOOP_TICK_S`'s 2.0 s**, measured off 9924
+  recorded 400 W steps and off the meter's own cadence. It is wrong in the SAFE
+  direction (a slower meter makes `validate.py` rule 10 conservative) and is NOT
+  changed here — re-deriving `SLEW_RAIL_FRAC` is a refusal boundary on a live
+  install and belongs to its own card. It is recorded in the tool's header and
+  printed on every run.
+* **The brief's plant figure was close but not exact.** It quoted
+  `delivered = 1.0135 × command − 26 W, r = 0.992` at a 4–6 s publish lag. On
+  this 16-day window, above the SoC floor, the same relation measures
+  `1.00 × command − 28 W, r = 0.977` at a best-fit pure delay of **7.5 s**. The
+  conclusion — the inverter is a pure follower and the plant is not the problem
+  — survives; the coefficients are the ones in §2.
+* **The brief's cost figure is larger than this measurement.** It quoted ~14 kWh
+  of avoidable export and 65 % of site export inside 7.9 % of the time. Measured
+  here: **5.5 kWh** avoidable of 39.6 kWh modelled (29.4 kWh recorded), with
+  42 % of export inside the 6.3 % of ticks that are slew-limited and 69 % within
+  ±60 s of one, over 15.3 % of the time. The concentration claim holds; the
+  avoidable-kWh figure does not, and the difference is not reconcilable from
+  here because the reconstruction it came from was discarded.

goodwe_controller/DECISIONS/SAFETY-56-what-the-gate-cannot-tell-apart.md

@@ -0,0 +1,181 @@
+# SAFETY-56 — what the gate cannot tell apart, said in the sentence
+
+**Text only. No behaviour changes in this card**, and §5 is the measurement that
+says so: the same stimuli through the tree before and after produce a
+**byte-identical** trace of every verdict, every `reading()`, every `inputs_ok`
+and every readiness row's `(ok, warn)`.
+
+---
+
+## 1. The defect
+
+0.10.1 is regulating a real GW5000S-BP. Two messages tell the operator that
+healthy hardware has failed.
+
+**The log line**, as emitted on the reference site on 2026-09-21:
+
+> SAFETY-37: inverter-a battery-power register **is not following its own
+> command** - STALE_READING: -3 unchanged for 36 s while the standing command
+> moved 800 W to +1600 W - **the reading is not following**, so it is reported
+> as MISSING rather than as a measurement … Treating it as MISSING, which
+> commands 0 W.
+
+**The readiness row**, at the same moment:
+
+> NOT READY — battery power: `sensor.kelder_goodwe_master_stage1_goodwe_inverter_ac_power`
+> **is missing or not numeric**
+
+That entity was present, numeric and updating.
+
+**SAFETY-37's conjunction is correct and is not touched by this card** —
+`unchanged > 35 s AND |command| > 250 W AND |travel| > 250 W`. A register
+genuinely stuck against a real command is exactly what it should catch, and a
+pack that cannot comply is a state the site must stop in too. What was wrong is
+what the sentences **concluded** from it.
+
+## 2. Two worlds satisfy the conjunction
+
+| | the register | the pack |
+|---|---|---|
+| **DEAD** | has stopped reporting reality | is doing what it was told |
+| **REFUSED** | is reporting reality correctly | cannot comply — the BMS is refusing at its floor |
+
+A refused pack holds still under any setpoint, so an honest register publishes
+the same unchanged number a dead one does. **Nothing `freshness.py` is handed
+separates them.** All three sentences asserted DEAD.
+
+## 3. The live episode was REFUSED, and it is measured, not argued
+
+Off the committed capture `scenarios/safety57-2026-09-21/bus-a-2026-09-21-1030-1110.log.gz`,
+whose bytes and decoder are already graded by `test_freshness.py` part 10a:
+
+| | |
+|---|---|
+| the register | answered **-3 W for 850 s**, 10:51:24 → 11:05:34 |
+| the commands during that hold | **+260, +660, +1060 W** — discharge only, never a charge |
+| pack SoC throughout | **11 %** |
+| first **charge** command after the restart | 11:05:31 at **-400 W** |
+| the register moves | **11:05:34** — **3 s**, inside one 17.0 s obligation window |
+
+**A register that answers a reversed command inside one obligation window had
+not stopped reporting.** What would not move was the pack. The sentence the
+operator read named the one thing in the loop that was telling the truth.
+
+⚠️ What this does **not** establish: that no register is ever intermittently
+wrong. It excludes a register that had simply stopped; it cannot exclude one
+that was wrong and then right. That is the point — the new sentence claims
+neither.
+
+## 4. The fix, and why it is three sentences and not one helper
+
+Each message states **what was observed** and names **both** explanations.
+
+| where | before | after |
+|---|---|---|
+| `app/freshness.py` `_grade()` | *"…+1600 W - the reading is not following, so it is reported as MISSING…"* | *"…+1600 W. **TWO THINGS LOOK LIKE THIS AND THIS GATE CANNOT TELL THEM APART**: the register may have stopped reporting reality, or the source may be unable to comply with the command - a pack the BMS is refusing holds still under any setpoint, and an honest register then reads exactly like a frozen one. Either way the number cannot be read as this command's effect, so it is reported as MISSING…"* |
+| `app/main.py` `_read_unit()` | *"SAFETY-37: %s battery-power **register is not following its own command** - %s."* | *"SAFETY-37: %s battery-power reading **did not move under a command that did, WHICH IS NOT BY ITSELF A VERDICT ON THE REGISTER** - %s."* |
+| `app/main.py` `checks()` | *"{label}: {entity} **is missing or not numeric**"* | *"{label}: **no usable value this cycle from** {entity} - **and this row cannot tell which of two things that is**: the entity is missing or not numeric, or it is publishing a number that this controller is withholding (a freshness gate does exactly that, and names itself in a row of its own). Confirm the entity in Developer Tools before replacing it"* |
+
+**Three sentences, three wordings, no shared helper.** The first two are a log
+line about a **behaviour**; the third is a banner about a named **entity**, and
+the two answer different questions ("what did the register do" against "can I
+trust this entity"). A helper serving both would have to drop whichever half
+the other caller does not need, and the half it dropped would be the
+operator's next step. The log line names the pair **once**, inside the `%s` it
+already interpolates, rather than in both of its own halves.
+
+**No new input, and SoC is not wired.** `BOUNDS["soc"]` stays *STATED, NOT
+WIRED*; telling the two worlds apart needs the pack floor (SAFETY-32's number)
+and SoC (TEL-08's wiring), and a message honest about its own ambiguity needs
+neither. Part 11b drives the two worlds at **50 %** and **11 %** SoC and
+asserts the sentence does not move one byte.
+
+**The readiness row does not branch.** `inv.batt_fresh.stale` is on the same
+object at the same moment, and the row deliberately does not ask it: the same
+loop renders the grid and SoC rows, which have no gate, and a branch per row
+would be a second place where "why is this None" is decided. The gate already
+has a surface — `stale_note()` rides `liveness_notes()` a few rows below with
+the whole STALE_READING sentence in it — so the operator's discriminator is
+*"is that row there?"*, and part 11d asserts that row is **present in REFUSED
+and absent in ABSENT**.
+
+## 5. Behaviour is byte-identical, measured
+
+`tools/safety56_behaviour_trace.py` prints two documents from one stimulus set.
+The `behaviour` half contains **no sentence**: only `stale`, `reading()`,
+`releases`, `held`, the window bookkeeping, `inputs_ok`, and every readiness
+row's `(ok, warn)`. Run in the CI image, purged, `:ro`, against
+`origin/release/1.0` **archived out of git** and against this branch:
+
+| | |
+|---|---|
+| the committed live capture | **2390 reads**, 7 verdict edges |
+| a swept grid of command × register schedules | **66 cells × 120 reads** — 1060 stale reads, 1309 `MISSING` readings, 6 releases |
+| six driven controller worlds through the shipped read path | DEAD, REFUSED, ABSENT, HEALTHY, RELEASE, RETRIP — every read's `(batt, inputs_ok, stale)` and every `checks()` row's `(ok, warn)` |
+| **result** | `6030175ed2ab9a4143e86e89a71d45c8ab041ac1c00121a3e3e023cd2b08996c` **on both trees** |
+
+⚠️ **AND THE CONTROL IS INSIDE THE TOOL, BECAUSE AN IDENTITY BETWEEN TWO TREES
+THAT ARE THE SAME TREE IS HABIT 4.** `--compare` refuses to report "behaviour
+unchanged" unless the `sentences` halves **differ**. This card's first
+invariance run was exactly that mistake — it archived a branch whose edits were
+not committed yet, so `before` and `after` were the same code and the identity
+was perfect and worthless.
+
+Both of the tool's refusals are **driven**, not asserted:
+
+| | |
+|---|---|
+| the same file compared with itself | `REFUSED: the sentences halves are IDENTICAL…`, exit **2** |
+| `MOVE_W` 250.0 → 240.0 in the after tree | `BEHAVIOUR MOVED at 'sweep_stale_reads' / 'sweep_missing_reads' / 'sweep_trace'`, exit **1** |
+| this card | `OK: sentences differ, behaviour is byte-identical.`, exit **0** |
+
+## 6. The mutation battery
+
+Each in its own `mktemp`'d copy (habit 18), purged on the host, mounted `:ro`,
+graded by `tools/mutation_run.sh` in the CI image.
+
+| | mutation | Δ bytes | named reds |
+|---|---|---|---|
+| M1 | `_grade()` reverted to *"the reading is not following"* | -402 | **3** |
+| M2 | the log line reverted to *"register is not following its own command"* | -80 | **2** |
+| M3 | the row reverted to *"{entity} is missing or not numeric"* | -619 | **2** |
+| M4 | *register* and *source* transposed between the two explanations | **0** | **1** |
+| M5 | the second explanation deleted, the first kept | -216 | **1** |
+| M6 | *"CANNOT TELL THEM APART"* replaced by *"IN ORDER OF LIKELIHOOD"* | -13 | **1** |
+| M7 | the REFUSED world's ground truth set to the DEAD world's | 0 | **2** |
+| M8 | the row's second cause deleted | -309 | **1** |
+| M9 | `label` and `entity` transposed in the row | **0** | **3** |
+| M10 | M1 + M2 + M3 together, i.e. exactly what 0.10.1 ships | -1101 | **5** |
+| M11 | the accusation literals replaced by one that matches nothing | 0 | **1** |
+
+⚠️ **M9's first run was a defect in this card's own check, and it is the one
+worth reading.** The row was fetched with `[...][0]`. Transposing `label` and
+`entity` makes the row unfindable, so the run died on an `IndexError` — a red
+with **no name attached**, with every check after that line **ungraded**. That
+is FCST-06's shape exactly. `_s56_row()` now returns a named absence instead of
+raising, and a precondition grades it: **0 named reds before, 3 after.**
+
+⚠️ **M11 is the other one aimed inward.** `not any(...)` over an empty list is
+True, and so is one over three mistyped literals. The positive control runs the
+same predicate against the three sentences **as 0.10.1 shipped them** and
+requires it to find an accusation in every one, and every literal to match at
+least one of them (habit 7: vary one thing from an accepted baseline).
+
+## 7. What part 11 does not grade
+
+* It does not show the live episode was a BMS refusal beyond doubt — see §3.
+* It does not grade English. A sentence that named both explanations and then
+  said something useless about them would pass.
+* The `no entity configured` branch beside the rewritten row is untouched and
+  ungraded: a blank entity really is the only thing it can be.
+* The **grid-power and battery-SoC rows** go through the same rewritten line and
+  have no freshness gate today, so for them the second cause is a hypothesis
+  about this controller rather than a live possibility. That is weaker than the
+  battery-power case and is the price of not branching per row. A gate on either
+  signal — TEL-08 would be one — makes it exact.
+* **SAFETY-58 is not touched** (the first read after a long rest trips before a
+  healthy register could answer), and neither is the 710/790 disagreement
+  between `test_freshness.py` and the changelog. Both are separate cards; the
+  second has a **fourth site** at
+  `DECISIONS/SAFETY-57-the-exit-from-a-stale-verdict.md:274` that a fix written
+  off the PR table alone would miss.

goodwe_controller/DECISIONS/SAFETY-57-the-exit-from-a-stale-verdict.md

@@ -0,0 +1,388 @@
+# SAFETY-57 — the stale-reading verdict gets an exit, because its own consequence is what stopped it being tested
+
+**Status:** decided and implemented on branch `SAFETY-57`, off `origin/master` @ `6f5e8e3`
+(content-identical to `release/1.0` @ `8a57361`).
+**Card:** SAFETY-57 — *"the freshness gate has no exit reachable from inside the state it creates"*.
+**Nothing here reached the inverter.** No contact was made with 192.168.2.158 or
+192.168.2.221. The one live system touched is `sniffer@192.168.2.167`, a
+**passive** RS-485 listener with no address on the bus, and it was read only.
+
+---
+
+## 0. The five things a reader should take away
+
+1. **The live episode is reproduced from the wire, not modelled.** The capture
+   is committed, the decoder is committed, and the box that produced it was
+   running the defect — so the `0 W` in the trace *is* the add-on's own
+   `inputs missing → command 0 W`. §2.
+2. **Option 2 from the card — "do not arm the gate when the command is 0 W" —
+   already holds, and it is not the bug.** `_grade()` has required
+   `|standing| >= MOVE_W` since SAFETY-37. The trip happened at **+1060 W** and
+   the stuck state is at **0 W**; they are different moments. §3.
+3. **The decision is not "how long", it is "when".** The verdict is withdrawn
+   when the **obligation that produced it is no longer standing** — SAFETY-13's
+   shape one module over. The 17.0 s is the obligation window that was already
+   derived in the file, taken at the **floor** of its band, and which half is
+   safe is the **opposite** of SAFETY-13's. §4.
+4. **It costs 52 % exposure on a permanently dead register, and that number is
+   in the suite so it cannot be forgotten.** It is payable only because one
+   re-grading window (35 s) is shorter than both consumer holds (75 s, 85 s).
+   **No detection SAFETY-37 had is given back.** §5.
+5. **The battery had been rescuing this code by accident.** 93 trips in the
+   committed 16-day capture; median wait for the BMS keep-alive pulse that
+   cleared them **143 s**, worst **5 h 57 m**. §6.
+
+---
+
+## 1. What was there, in the terms the code uses
+
+`freshness.py`, `Freshness.submit()` and `_grade()`:
+
+```python
+if self.changed_mono is None or value != self.held:
+    ...
+    self.stale = False          # the only place the latch is cleared
+def _grade(self, standing_w, now_mono):
+    if self.stale or self.changed_mono is None:
+        return                  # sets the latch; never clears it
+```
+
+and `main.py:1777`, `inv.batt = inv.batt_fresh.reading()`, where `reading()`
+answers `None` while `stale`. `inputs_ok` sees the `None`, the site holds for
+`stale_input_s`, then files `Claim.set("safety", P_SAFETY, 0.0, "inputs
+missing")` and keeps filing it.
+
+The reason the latch exists is written in the class docstring and it is a good
+one: without it the verdict oscillates at about 1 Hz, because declaring the
+reading stale drops the command below `MOVE_W`, which un-arms the conjunction,
+which hands the held number straight back.
+
+**The defect is that the only thing that ends it is an arrival carrying a
+different number — and the state's own output is what stops the register being
+asked for one.** The log line promised the opposite, in the same sentence that
+announced the 0 W:
+
+> *Treating it as MISSING, which commands 0 W. It clears itself the moment the
+> register reports a different value.*
+
+---
+
+## 2. Reproducing it, from the wire
+
+`scenarios/safety57-2026-09-21/bus-a-2026-09-21-1030-1110.log.gz` is 3840
+verbatim frames off the RS-485 pair, 10:30–11:10 Europe/Brussels, decoded by
+`tools/decode_bus_capture.py`. The decoder reports **0 unparsed, 0 bad CRC,
+0 unknown shapes**, and its mode→sign convention is **graded off the capture**
+rather than trusted: 298 commands at or under −1000 W are each answered one
+obligation window later by a negative register reading, and not one positive.
+
+| capture time | on the wire |
+|---|---|
+| 10:51:14 | `0x0518` = **−447 W**; the loop is charging |
+| 10:51:19 | the command reverses: EMS **mode 3**, 260 W of discharge |
+| 10:51:24.7 | `0x0518` = **−3 W**. The pack is at **11 %**, the BMS refuses the discharge, the inverter idles. **The register is healthy and truthful.** |
+| 10:51:29.7 | the command reaches **+1060 W**. 800 W of travel |
+| 10:52:21.7 | the setpoint is written **0 W** — this is the add-on's own §11.1 rule 1, recorded on the wire |
+| …850.0 s | `0x0518` does not change value |
+| …790.0 s | the setpoint does not change value |
+| ~11:04 | **a person restarts the add-on** — not visible in this file, and the only thing that ends the episode |
+| 11:05:31.7 | the restarted loop commands **−400 W of charge**, which the pack accepts at 11 % |
+| 11:05:34.7 | `0x0518` = **−137 W** |
+
+⚠️ **THE CAPTURE IS CLOSED-LOOP FOR THE WHOLE PARKED INTERVAL**, which is why
+this is a reproduction and not a simulation: the box was running 0.10.0, so
+every command in the trace is the shipped code's own. The only event inside the
+window the file cannot account for is the human restart.
+
+Replaying the shipped `_read_unit` loop at 1 Hz against those two series
+(`test_freshness.py` part 10b):
+
+| | stale at | clear at | parked |
+|---|---|---|---|
+| **before** (`release_s = inf`) | 10:52:00 | 11:05:35 | **815 s**, and `reading()` is `None` on all **812** reads from the trip to the first command a human put on the wire, with the register at −3.0 W in every one of them |
+| **after** | 10:52:00 | **10:52:39** | **39 s**, with `0x0518` still answering the same **−3 W** |
+
+⚠️ **THE COUNTERFACTUAL IS `release_s = inf`, AND IT IS GRADED RATHER THAN
+CLAIMED.** With an infinite bound `_release()` never fires, `_open_window()` is
+only ever called where the register moves, and the window pair is the
+change-stamp pair — byte-for-byte the pre-SAFETY-57 conjunction. Part 10b
+asserts that by driving part 1's own fresh/stale pair through both bounds and
+comparing the verdict streams.
+
+The replay also found a **one-read trip at 10:48:14** that clears one second
+later. That is a pre-existing false positive and it is now recorded as
+survivor 5 — §7.
+
+---
+
+## 3. What the card's option 2 actually buys, which is nothing here
+
+The card offered *"do not arm the gate when the command being graded is 0 W"*
+and warned that it might hold already. **It does, and it has since SAFETY-37**:
+`_grade()` returns at `abs(standing_w) < self.bound.move_w`, and
+`test_freshness.py` part 4 has a named check on that term, added because a
+mutation removing it survived.
+
+The warning in the card is the right one and it is worth writing down: **the
+trip and the stuck state are different moments.** The gate armed at **+1060 W**,
+where the conjunction is entirely correct — a command travelled 800 W and the
+register did not move for 35 s. The site then went to **0 W** *because of the
+verdict*. An entry-side rule cannot reach a state that is entered legitimately
+and then persists. **The defect is the exit, and nothing else in the conjunction
+is touched by this card.**
+
+Option 3 — probing with a small non-zero command — was not taken and does not
+need to be. It writes to a real actuator to test an assumption, and §4's rule
+does not need a probe: the site's *normal* control resuming is the test, and it
+is gated behind the same `inputs_ok` everything else is.
+
+---
+
+## 4. The decision: which verdicts get an exit, and what the bound is
+
+> The stale verdict holds as before, **unless** the obligation that produced it
+> is no longer standing — `|standing| < MOVE_W` — **and** it has been gone
+> longer than the register would have needed to answer it. On a release the
+> latch clears and a **new grading window** opens at that instant.
+
+This is [[SAFETY-13]]'s §4 in a different module, and deliberately so: that card
+established the house answer to "a latch with no exit" and its answer was *not*
+a plain time bound but a **predicate plus a time bound**, where the predicate
+says whether the state can end on its own. Here the predicate is that **the
+question is no longer being asked.** A register under a 0 W command is obliged
+to be nowhere, so a verdict about whether it is following cannot be tested, and
+a verdict that cannot be tested may not stand for ever.
+
+### 4.1 Why the window has to re-open, and what happens if it does not
+
+`_grade()` compares the register's unchanged time against `unchanged_s` and the
+command's travel against the command standing when the window opened. If a
+release cleared the latch **without** re-opening the window, the first read at
+which the resumed command travels 250 W would re-trip immediately — the
+register would never get the 17 s in which it could answer, and the live
+episode's recovery (a charge the pack **accepts**) would be killed inside two
+seconds. Mutating exactly that (`graded_from` re-anchored to `changed_mono`,
++82 B) takes four named checks red.
+
+The new window is `BATT_UNCHANGED_S` = **35 s**, the same bound as entry,
+because it is the same question — *does this register follow the commands issued
+from now on?* — and there is no principled shorter answer to it. It is also the
+number the exposure argument in §5 rests on, so it is not free to move.
+
+### 4.2 `RELEASE_S` = `BATT_OBLIGED_S` = 17.0 s, and which half is safe
+
+The quantity needed is *has the register had its chance to answer the command
+standing now?*, and `freshness.py` already derives it as the floor of
+`BATT_UNCHANGED_S`'s band:
+
+```
+6.0 s   plant          goodwe/NOTES.md §5.9, measured 2026-08-22
+10.0 s  publisher      firmware/goodwe-master.yaml:181, update_interval: 10s
+1.0 s   this add-on    run_control()'s await asyncio.sleep(1)
+```
+
+⚠️ **IT IS THE FLOOR OF ITS BAND, NOT A SENSITIVITY PREFERENCE** — the mirror of
+`MOVE_W` taking the **ceiling** of its own for the mirrored reason.
+
+| | the question | the safe half | why |
+|---|---|---|---|
+| SAFETY-13's `SETTLE_CYCLES` | may the plant still be the **explanation**? | the **longer** half | a shorter bound stops believing the plant too early, and then it accuses |
+| this one | may the verdict still be **tested**? | the **shorter** half | being wrong *long* is the failure being fixed; being wrong *short* costs one re-grading window, and §5 bounds that |
+
+Below 17.0 s the release pre-empts the **cheaper exit** — the register answering
+the new 0 W command by itself, which clears the latch on evidence rather than on
+a timer. That is graded behaviourally rather than asserted: a register that
+answers at +16 s clears by **movement** at `release_s = 17.0` with `releases`
+still 0, and by **timer** at `release_s = 5.0`.
+
+The family is computed and printed (habit 10): `5, 16, 17, 18, 35, inf` give
+six distinct release instants, so no check in the file can confuse two of them.
+
+### 4.3 Two clocks, and the operator reads the register's
+
+`changed_mono` / `unchanged_s()` remain facts about the **register**: after a
+release they go on reporting that it has not moved for 850 s, because it has
+not. `graded_from` / `graded_s()` are the **verdict's** window. They coincide
+until the first release. Collapsing them either lies to the operator or defeats
+the re-grading, and both directions are mutated red.
+
+The stale sentence's `unchanged for N s` slot carries the **register's** number;
+a re-trip appends a clause naming the window and the grade count, so the two
+durations cannot be read as one number that moved (habit 14).
+
+---
+
+## 5. What it costs, measured
+
+Driven against a register frozen for good, 1201 reads, shipped defaults
+(`test_freshness.py` part 10c):
+
+| | parked | the held number reaches a consumer | releases |
+|---|---|---|---|
+| before | 1166 s | **35 reads (2.9 %)** | 0 |
+| after | 571 s | **630 reads (52.5 %)** | 17 |
+
+⚠️ **52 % IS PAID EVERY CYCLE, NOT OCCASIONALLY.** The period is
+`stale_input_s` (15 s) + `RELEASE_S` (17 s) parked, then one 35 s window.
+
+It is payable because of one inequality, and it is the inequality
+`test_freshness.py` part 6 has graded against the shipped `config.yaml` since
+SAFETY-37:
+
+```
+35 s  (the re-grading window)  <  75 s  (circulation_hold_s)  <  85 s  (unit_sign_disagree_s)
+```
+
+Every unbroken run of exposure is **exactly one window**, so neither consumer
+can reach a verdict inside one, and the re-trip that ends each run hands them a
+`None`, which **clears** their windows rather than accumulating into them.
+
+**And nothing SAFETY-37 detects is given back**, which is the half that makes
+this a trade rather than a regression: a permanent `None` clears those same two
+windows for ever as well, so on the shipped-before module those detectors are
+*equally* unable to speak about the unit. What the held number does reach for
+35 s is `site_batt_w`, the anti-windup input of `control.compute()` — which
+answers a large unexplained divergence by **freezing the output**, the
+conservative direction and SAFETY-13's business — and the command itself is
+derived from the **P1 meter**, never from `batt`.
+
+### 5.1 The narrowing this does NOT take, named so the next card can
+
+The live episode's register refused a **discharge** into an 11 % pack and then
+followed a **charge** three seconds later. A refusal in one direction is not
+evidence about the other, and a gate that knew the pack's floor could re-grade
+on the first command that crosses it instead of on a timer — which would shrink
+the 52 % above. That needs SoC, which this module deliberately does not take
+(see the `soc` row and TEL-08), and the pack floor, which is SAFETY-32's number.
+It is **not needed to give the state an exit**, and folding it in here would
+make the exit depend on a second measurement being right.
+
+---
+
+## 6. The measurement that says the old exit was luck
+
+`scenarios/loop-2026-09-02_2026-09-17/` replayed at 1 Hz through the shipped
+conjunction (`test_freshness.py` part 8b): **93 trips in 16 days.** The only
+thing that could clear any of them was the register carrying a different number,
+and that took:
+
+| | |
+|---|---|
+| minimum | 0.6 s |
+| **median** | **143.4 s** |
+| maximum | **21440.1 s** (5 h 57 m) |
+| at or over the live episode's 710 s | **17 of 93** |
+
+The short waits are the BMS keep-alive pulse — SAFETY-50 measured its ceiling at
+508 W — twitching `0x0518` and satisfying the clearing rule **by accident**.
+Over a fifth of the trips are cleared in under 20 s by something nothing in this
+add-on asked for.
+
+⚠️ **WHAT THAT REPLAY IS AND IS NOT.** The capture runs 2026-09-02…17 and
+0.10.0 — the first version carrying this gate — was cut on 2026-09-16, so the
+setpoint column is an **ungated** controller's. That makes each trip an honest
+register-versus-command divergence off the real bus, and it makes the post-trip
+command column something a gated box would **not** have written. The figure
+taken from it is therefore the only one that does not depend on the command at
+all — how long this register goes without changing value — and it **under**-states
+the wait, because a site parked at 0 W gives the register even less reason to
+move than the one recorded here.
+
+---
+
+## 7. Survivors, and the two things the battery found
+
+The battery is 22 mutations over `app/freshness.py`, `app/main.py` and
+`tools/decode_bus_capture.py`, plus one over the committed capture itself. All
+run through `ci_run.sh`, a mirror of `checks.yml`'s own step: a purged copy of
+the tree, bind-mounted `:ro`, one file at a time, `PYTHONDONTWRITEBYTECODE=1`.
+Per MUTATION.md habit 18 the harness's scratch file is `mktemp`ed per
+invocation and the tree is fingerprinted **after the revert** as well as before;
+every revert restored the recorded sha256 and byte count.
+
+**21 red, 1 argued equivalent, 0 unexplained survivors.** The table is in the
+PR body. Two of them are worth keeping here.
+
+### 7.1 The equivalent mutant, argued rather than rounded off
+
+Swapping `_release()` and `_grade()` in `submit()` is a **zero-byte** edit and
+survived the whole battery. **It is not a missing fixture and no fixture can
+close it**: `_grade()` acts only when `|standing| >= move_w` and `_release()`
+only when `|standing| < move_w`, so at most one of them can do anything on any
+read, whichever runs first.
+
+⚠️ **THE FIRST VERSION OF THE CODE CLAIMED THE ORDER WAS LOAD-BEARING**, in a
+`⚠️` comment, with a reason that sounded right. It was false, and the battery is
+what said so — **MUTATION.md habit 22 exactly, one card later: an explanation in
+a comment is a claim, and this one had not been run.** The comment now states
+the disjointness, and part 10 pins **that** — at 0, 100, 249, 250, 251 and
+1300 W — instead of pinning an order that is not observable.
+
+### 7.2 The sibling that survived, which is habit 11 earning its place
+
+`_release()`'s obligation test is `abs(standing_w) >= self.bound.move_w`.
+Swapping `move_w` for `unchanged_s` — comparing **watts against 35** — survived
+the file at **+5 B**, because **every fixture rested at exactly 0 W**, and 0 is
+below both 35 and 250. They separate only in the band between them, and a site
+can sit there: a peak-guard floor, a shadow substitution, any claim that wins
+with a small non-zero number. Closed by a three-point fixture at 0 / 100 / 300 W
+that asserts the 100 W case releases and the 300 W case does not.
+
+### 7.3 ⚠️ And the instrument lied once, which is habit 16's second half
+
+The first form of the `graded_from` mutation was
+`float(self.changed_mono or now_mono)`. It reported a **survivor at +21 B**, and
+the tree fingerprint showed the edit really was on disk and really did run.
+`changed_mono` is **0.0** in the dead-register fixture, and `0.0 or x` is `x` —
+so the mutant was a *no-op on the fixture*, for a Python truthiness reason that
+has nothing to do with the property under test. Rewritten as an explicit
+`is None` test (+82 B) it is red on four named checks.
+
+**A mutation is subject to every habit in MUTATION.md, including habit 4.** A
+purge, a fingerprint and a byte delta all say the edit is present; none of them
+says the edit *changed the answer on this stimulus*. MUTATION.md gains habit 19
+for it.
+
+---
+
+## 8. What this does NOT fix, said plainly
+
+**It does not tell a BMS refusal apart from a dead register**, and it does not
+try to. Both are re-graded on the same timer. §5.1 names what telling them apart
+would need.
+
+**It does not make the diagnosis right.** The line the operator reads still says
+*"battery-power register is not following its own command"*, which is wrong in a
+different way when the pack is simply empty. That wording is **SAFETY-56's**,
+together with `main.py`'s NOT READY row, and it is deliberately untouched here —
+two cards editing one sentence is how one of them silently loses. Only the
+**escape clause** was rewritten, because this card is what made the old one
+false, and part 10h has a named check asserting the diagnosis half is still
+there so that rewrite has to be a deliberate act.
+
+> ⚠️ **SINCE SUPERSEDED, WHICH IS WHAT THAT CHECK WAS FOR.** [[SAFETY-56]] is
+> the deliberate act: all three sentences now name **both** explanations and
+> accuse neither, and part 10h's check is inverted — it requires the accusation
+> to be **gone**. Nothing else in this section moved; the escape clause above is
+> still this card's and is untouched by it. See
+> `DECISIONS/SAFETY-56-what-the-gate-cannot-tell-apart.md`, and
+> `test_freshness.py` part 11 for the graded pair of worlds.
+
+**Survivor 5 is older than this card and is not closed by it.** After a long
+rest the unchanged clock is already past 35 s, so the **first** read carrying a
+travelled command trips the gate — before the 17.0 s in which a healthy register
+could have answered it. The live capture contains one (10:48:14, cleared one
+second later). Its size is one `stale_input_s` hold, during which `cycle()`
+returns at `inputs missing {n}s` and commands nothing differently. Fixing it
+means measuring the unchanged clock from when the **obligation** appeared rather
+than from the register's last move, which re-derives the 35.0 s bound and is a
+different card.
+
+**Nothing was measured on two inverters.** Inverter B does not physically exist
+(`goodwe/NOTES.md` §1.1b). Every two-unit figure in `test_freshness.py` is two
+copies of A's behaviour with different numbers passed in.
+
+**No deploy is proposed.** 0.10.0 is on the reference install and this branch's
+CHANGELOG row is filed under it only because `test_version_gate.py` part 11b
+requires the newest heading to be a version. Moving it, and deciding whether a
+version is cut, is a PKG card's.

goodwe_controller/DECISIONS/SAFETY-61-control-task-death.md

@@ -0,0 +1,106 @@
+# SAFETY-61 — the control task's death ends the process
+
+## 0. The defect
+
+`amain()` started `run_control()` as a bare task and waited on `stop`. Nothing
+watched the task. An uncaught exception in `read_inputs()`, `cycle()` or
+`publish()` ended the task silently, and `stop` was never set. The web UI, P1
+and tariff tasks kept running, and the Supervisor saw a healthy container. The
+traceback appeared only at shutdown. The ESP32's layer-1 veto zeroed the
+inverter about 30 s later, so the hardware was safe. The pack then sat at 0 W
+indefinitely while the add-on showed green.
+
+`test_control_task.py` reproduces this on the pre-fix tree. The child process
+reaches its 40 s deadline, has written no 0 W, and has logged nothing.
+
+## 1. Decision: exit with status 70 after the ordinary wind-down
+
+A done-callback on the control task (`control_task_done()`) handles the death.
+It logs the traceback at CRITICAL at the moment of death, then sets `stop`.
+`amain()` then runs the same wind-down that SIGTERM runs (`shutdown()` →
+`command_site_zero()`, then cancel, then clean up). After that it raises
+`ControlTaskDied`, and `main()` turns that into `SystemExit(70)` (sysexits
+EX_SOFTWARE). A normal stop and `run_control()`'s own refusal path both set
+`stop` before the task ends, so the callback ignores them. The refusal still
+exits with 78.
+
+**Why not restart the loop in the same process:**
+
+* `cycle()` writes controller state before its awaits: `cycle_at`,
+  `peak_guard`, `allocation`, then `target`/`reason`, then the writes. An
+  exception between those steps leaves the controller half-updated. A loop
+  restarted in the same process would continue from a state that no boot ever
+  produces. A process restart rebuilds the controller from the Store, which is
+  the path every boot already runs.
+* An unbounded retry is the invisible spin the card forbids. A bounded retry
+  would reimplement the Supervisor watchdog's own throttle: 10 restarts per
+  30 min, and 5 attempts with backoff (`apps/const.py`).
+
+## 2. What happens after the exit, verified rather than assumed
+
+* **Exit status reaches Docker.** The add-on image (s6-overlay, `init: false`,
+  `CMD /run.sh`) was run with `exec python3 -c 'raise SystemExit(70)'`.
+  `docker inspect` gave ExitCode 70. The same test with exit 0 gave 0, and an
+  uncaught exception gave 1.
+* **Supervisor 2026.08.0** (`ghcr.io/home-assistant/amd64-hassio-supervisor`,
+  source read from the image):
+  * A non-zero container exit is recorded as `ContainerState.FAILED`
+    (`docker/monitor.py`). The Supervisor logs *"App … exited with non-zero
+    exit code 70"* at ERROR (`apps/app.py container_state_changed`).
+  * The Supervisor restarts the add-on **only if the per-install Watchdog
+    toggle is on**. `watchdog_container()` returns when `not self.watchdog`.
+    The toggle defaults to **off** (`apps/validate.py`:
+    `vol.Optional(ATTR_WATCHDOG, default=False)`).
+  * Add-on containers get **no Docker restart policy**. The only
+    `restart_policy=` in the Supervisor belongs to the observer.
+  * `boot: auto` in `config.yaml` only controls starting at host boot. The
+    `watchdog:` key in `config.yaml` is a health-check URL, not a restart
+    policy, and this add-on does not set it.
+* **So on a default install the add-on stays stopped after this exit.** The UI
+  shows it as stopped, its log holds the traceback, and the Supervisor log holds
+  an ERROR line. The pack is at 0 W, which is the same physical state as before
+  this card. The difference is that 0 W is written immediately instead of after
+  the ~30 s veto, and the add-on no longer shows green. With the Watchdog toggle
+  on, the Supervisor restarts the add-on.
+* **Not verified:** an actual restart by a running Supervisor. That would need a
+  live Supervisor, and the only one available is the live house.
+
+## 3. Left open for the owner
+
+* Whether `DOCS.md` should tell installers to enable Watchdog. DOCS.md is not
+  this card's file.
+* Setting the Watchdog toggle from inside the add-on (`/addons/self/options`)
+  was rejected here, because it would change a user setting without the user
+  knowing.
+
+## 4. Scope: the siblings, and why they are not supervised
+
+* `run_tariff_refresh()` and the P1 HTTP and HA transports already catch
+  `Exception` inside their loops by design, and the values they feed are
+  age-bounded downstream.
+* The P1 MQTT source *returns* on purpose when it is misconfigured. Making every
+  long-lived task's end exit the process would turn that deliberate fail-safe
+  into a restart loop.
+* Only the control task is supervised.
+
+## 5. `hass.py`: an undecodable body is an absence
+
+A non-JSON `200` served as `text/html` was **already** treated as an absence,
+because aiohttp's `ContentTypeError` is a `ClientError`. The reads that actually
+escaped were these three:
+
+* a malformed body labelled `application/json`, which raises `JSONDecodeError`
+  (a `ValueError`);
+* a JSON body that is not an object, which raises `AttributeError` in
+  `number()` and `limits()`;
+* an undecodable error body in `call()`, which raises `UnicodeDecodeError`.
+
+All three were measured against aiohttp 3.13.5. The first two now read as
+`None`, and the third is now a failed write (`False`).
+
+## 6. Status row
+
+`checks()` now starts with a *control loop* row showing how long ago the loop
+last completed a pass. The row turns red once that age exceeds
+`FIRMWARE_INGEST_VETO_S`. The heartbeat is sent from this loop, so past that age
+layer 1 has zeroed the inverter.

goodwe_controller/DECISIONS/TEL-11-pv-production.md

@@ -0,0 +1,353 @@
+# TEL-11 — the PV production channel
+
+*What was decided, what it was decided against, and what the evidence was.*
+
+## 0. The problem, in OPT-10's numbers
+
+Over sixteen days at the reference site the pack reached 90 % SoC on **two** of
+them, and **20.5 kWh of surplus left the site while the pack still had room** —
+**12.6 kWh** of it with the battery **not charging at all**. That single
+measurement is upstream of most of what else was found that week: the nightly
+floor, SAFETY-37's misdiagnosis, the SAFETY-57 deadlock, a 2 h 47 min saturation
+freeze.
+
+It cannot be **attributed**, because **PV production is recorded nowhere in this
+system**. Three causes need three different fixes:
+
+| cause | fix |
+|---|---|
+| there was no irradiance | none — the site behaved correctly |
+| production was there, charge power was limited | a limit, somewhere |
+| production was there, the pack had room, the optimiser declined | **the only software defect** |
+
+Guessing between them is how an optimiser gets tuned to solve a cloud problem.
+**This card adds the channel and does not do the attribution.** Ship it, let it
+record a week, OPT-10 picks it up with data.
+
+## 1. It is an HA entity, not a register — and that is a product decision
+
+The RS485 bus this add-on speaks carries the **battery** inverter it drives. On
+nearly every site the PV inverter is a different box from a different vendor,
+reporting into Home Assistant through its own integration; it is **not** on this
+bus and there is no reason it would be. So the signal comes from an entity:
+`pv_entity` takes whatever `sensor.*` the site's PV integration provides, any
+brand HA can read.
+
+Reading a register would have been cheaper on one house and wrong for a fleet —
+the trade [[product-not-one-house]] names.
+
+## 2. The sign convention: **positive is production**, and there is no `pv_invert`
+
+> Reversed by TEL-14 (flag and negative caution): `DECISIONS/TEL-14-pv-sign.md`.
+
+### The convention is derived, not assumed
+
+Two sign rules already ship, and both are recorded in `DOCS.md`'s *Sources*
+table rather than inferred here:
+
+* `meter_entity` — **positive must mean importing** (`meter_invert` flips it);
+* `batt_entity` — **`+` = discharging** (`batt_invert` flips it).
+
+Both are *"positive = power arriving at the house's AC bus"*. Production arrives
+there too, so **positive = producing** is the continuation of the shipped
+convention rather than a fresh choice.
+
+### Why an invert flag would be over-building
+
+The question is not "could a sensor be reversed" — it could. It is what a flag
+would **buy**, and the answer is nothing, for two reasons that do not apply to
+the two keys it would sit beside:
+
+1. **Those two quantities are read by the control path; this one is read by
+   nothing.** `inv.batt` feeds SAFETY-30's per-unit sign check and SAFETY-31's
+   circulating-power sensor (`_read_unit()`'s own docstring says so), so a
+   reversed battery sensor hands the site a plausible number it then **acts**
+   on — a latch that trips when it should not, or does not trip when it should.
+   `pv_w` reaches no decision at all (§4), so a reversed PV sensor cannot
+   mislead one.
+2. **Production is unipolar, so the error is self-announcing.** Battery power
+   and grid power are legitimately negative half the time, which is exactly why
+   a flipped sign is invisible in them. A PV array does not consume: a reversed
+   sensor reads **−4 kW at noon**, in the first day of the very history this card
+   exists to create. An invert flag would let an installer *hide* that by
+   flipping it to something that looks right, and a second place for the sign to
+   be wrong is a second thing to get wrong.
+
+So: the convention is documented in `config.yaml`, both translations, `DOCS.md`
+and `app/pv.py`, the value is published **exactly as the sensor reports it**,
+and there is no flag. `test_pv.py` part 1 pins `-8 W` through unchanged.
+
+### And no negative-value alarm either
+
+The tempting middle path — warn when the reading is negative — needs a
+threshold, because a PV inverter's own standby draw makes a small negative
+reading at night entirely ordinary. Any threshold here would be a number nobody
+measured, in a card whose whole subject is not fabricating numbers. The
+published row is the detector.
+
+## 3. Absence is never zero, and it is not "dropped" either
+
+This is the constraint that shaped the publication, and the obvious
+implementation fails it.
+
+`MqttPublisher.publish()` **skips** a `None` value. That is right for
+`circulation` — its note in `main.py` says a missing per-unit reading should
+leave the last figure standing rather than publish a zero that reads as health —
+and it is **exactly wrong here**: a skipped row leaves Home Assistant holding
+the last number it was told, *forever*, and the recorder then draws a **flat
+line at that value through the outage**. Read back a week later that is
+indistinguishable from a real measurement, and if the last value happened to be
+small it manufactures precisely the *"there was no surplus to store"* conclusion
+the card exists to **test**.
+
+So TEL-11 publishes the absence, using Home Assistant's own mechanism:
+
+> `homeassistant/components/mqtt/const.py`: `PAYLOAD_NONE = "None"`.
+> `homeassistant/components/mqtt/sensor.py`, in the state-message handler:
+> `if payload == PAYLOAD_NONE: self._attr_native_value = None; return` — and it
+> is tested **before** the numeric branch, so it holds for a row carrying
+> `device_class: power`.
+> (github.com/home-assistant/core, branch `dev`, retrieved 2026-09-24. The
+> shipped MQTT-sensor documentation says the same thing in its `state_topic`
+> entry: *"a 'None' value will set the sensor to an unknown state"*.)
+
+The entity therefore goes to **`unknown`** and the recorder stores a **gap**.
+`mqtt.ABSENT_AS_UNKNOWN` is a one-key set and `test_pv.py` part 3 asserts both
+that the pv row gets this treatment **and that `circulation` still does not** —
+widening the rule silently would be a behaviour change to another card's row.
+
+⚠️ **What was NOT built, and why.** A per-entity `availability` block
+(`availability_mode: all`, an extra retained topic) would also produce a
+distinguishable state — `unavailable` rather than `unknown` — but it needs a
+second topic, a second retained message, a change to `_payload()`'s
+byte-order-sensitive key construction, and it survives restarts only if the
+retention is right. The payload route is one branch in `publish()` and one
+constant, and it is graded as **bytes on the topic** rather than as a claim
+about HA's availability handling.
+
+### Three states, not two
+
+| state | frame | wire | page |
+|---|---|---|---|
+| no source (`pv_entity` unset) | no `pv` key | no topic, no entity | no row |
+| no reading | `pv: None` | `goodwe_ctl/pv` = `None` | `PV —` + a caution naming the reason |
+| zero watts | `pv: 0.0` | `goodwe_ctl/pv` = `0.0` | `PV 0 W` |
+
+A failed read also **clears** the last good value (`_read_pv()` assigns on every
+call), so a reading never outlives its own sensor. `test_pv.py` part 2 drives a
+good read followed by a dead one, because a fixture that answers the same thing
+forever cannot reach that failure — MUTATION.md habit 9's shape.
+
+## 4. It must not become a control input, and that is graded twice
+
+### In the suite
+
+`test_pv.py` part 6 drives twelve cycles of the real `Controller.cycle()`
+against a 6 kW export and asserts the commands written to the inverter are
+**bit-identical** across `unset` / `no reading` / `0 W` / `8 kW` of production,
+with a precondition check that the stimulus commands something at all (habit 1).
+`inputs_ok` is asserted not to move either: a broken PV integration is **not** a
+missing input, because nothing computes with it.
+
+A computed census (habit 12 — the scope is derived from the tree, not typed)
+then reports which of the 33 modules under `app/` mention the material in any
+spelling, comments included. It is **three**: `pv.py`, `main.py`, `mqtt.py`. The
+scanner's own red direction is exercised on every run.
+
+### Across trees, by hash
+
+`tools/safety56_behaviour_trace.py` is the pattern; `tools/tel11_pv_trace.py` is
+this card's version of it, and **its control clause had to be different**, which
+is worth stating because the difference is the interesting part.
+
+SAFETY-56 changed wording and had to show behaviour did not move, so its
+`--compare` **refuses** unless the `sentences` halves **differ** — otherwise the
+two runs might be one tree twice. TEL-11's headline claim is the opposite shape:
+with the option unset, **nothing** differs. "The documents are identical" is the
+*result*, so it cannot also be the control. The two things proved instead are:
+
+* the two runs came from **different trees** (`app/*.py` sha256 + byte count,
+  compared, and an identity is **refused**);
+* **exactly one** side reacts to `pv_entity` — that side is the HEAD, the other
+  is a tree that does not have the option. Neither, or both, is refused.
+
+It drives 41 stimulus cells (5 grid worlds × 8 PV schedules, plus a run stopped
+part-way) and prints two documents per setting: `control` — every command
+written, every `self.target`, `inputs_ok`, the loop's three fields, the
+arbiter's resolution, the maintenance phase, tick by tick, **with no TEL-11
+material in it** — and `telemetry`, which is everything the card is allowed to
+move.
+
+Measured, in the CI image, on purged trees:
+
+```
+  HEAD is B; baseline is A (it does not react to `pv_entity`).
+  tree      A 73296909170ec789237d6e704cce9ab0d9f83b3df1495a14d2497285c3041a12
+  tree      B d5011b6a18e2e3803dc09cac0214b0378fa4c7388fc0ad8ad89b832a5c92af48
+  control   A unset 846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   B unset 846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   B set   846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  telemetry A unset a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
+  telemetry B unset a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
+  telemetry B set   4e6d1cb289a957223ad0205f732a6fec6110ce1f2032c98ad60694e67625274f
+OK  1/3  UNSET: control AND telemetry are byte-identical to the baseline tree.
+OK  2/3  SET: the control document is byte-identical with the channel switched on.
+OK  3/3  CONTROL OF THE CONTROL: the telemetry document DOES move when the
+         option is set (42 stimulus cells differ).
+```
+
+Note what clause 1 claims and clause 2 does not: **unset** is identical in
+`control` *and* `telemetry`, which is stronger than "the control path is
+untouched" — an install that does not set the option sees no change of any kind,
+including its announcement and its status rows. **Set** is identical in
+`control` only, which is the whole of "instrumentation, not an input".
+
+## 5. Genuinely optional — and not a second `price_now_entity`
+
+`price_now_entity` / `price_avg_entity` are legal **only** while
+`price_provider` is `off`, and the add-on **refuses to start** otherwise. That
+is the trap this card was told not to rebuild, and it is avoided structurally
+rather than by intention:
+
+* `validate.py` does not mention `pv_entity` at all. It cannot conflict with
+  anything, because nothing else reads it.
+* the MQTT row lives in `OPTIONAL_SENSORS`, not `SENSORS`, and
+  `discovery_payloads()`'s new `include` argument **defaults to empty**. So a
+  caller that has never heard of `pv_entity` — every fixture in `test_mqtt.py`,
+  `tools/rehearse_roster.py`, anything written next year — announces exactly
+  what it announced before. `p1_age` solves the same problem the other way
+  round, with `omit`, because it is announced by default and withdrawn when the
+  meter is off; getting that direction wrong here would have left most installs
+  with an entity nothing feeds, which is the hazard `omit`'s own note names.
+* the read is gated on the option, so an unset install makes **no state call at
+  all** — not a read that fails quietly.
+* there is **no status row** when it is unset. `peak_forecast_entity` nags when
+  it is unset because an unset forecast leaves a money guard without an input;
+  this is instrumentation, and a permanent caution on every install that never
+  asked for a PV channel is the warning spam the card forbids.
+* when it **is** set and the read fails, the row is `ok=False, warn=True` — a
+  **caution**. `status_payload()` builds `NOT READY` out of rows that are
+  neither `ok` nor `warn`, so a telemetry channel can never put a battery site
+  into `NOT READY`.
+
+## 6. The unit is read off the entity, and an unreadable one is refused
+
+`read_inputs()` guesses kW-or-W for `peak_forecast_entity` with
+`abs(raw) < 50`, and that is safe there: nobody's quarter-hour demand forecast
+is 50 W. It is **not** safe here — 30 W of real production at dusk is an
+ordinary reading, and that heuristic would publish it as 30 kW.
+
+So `pv.watts()` reads the entity's own `unit_of_measurement` and converts
+against Home Assistant's own `UnitOfPower` table (`mW`, `W`, `kW`, `MW`, `GW`,
+`TW`; every factor an exact power of ten). A sensor with **no** unit, or a unit
+outside that table, is **refused by name** and the status page says which. The
+refusal is loud; a guess would be silent, and a factor of 1000 in the one
+channel that exists to be believed a week later is the worse failure.
+
+⚠️ `BTU/h` is in HA's enum and is deliberately **not** in the table: its factor
+is a measured conversion rather than a decimal shift, no PV integration
+publishes in it, and a fabricated constant is what this repository's whole
+process exists to prevent. It lands in the refusal, by name, and `test_pv.py`
+part 1 pins that.
+
+## 7. The mutation battery
+
+Every check this card adds was driven by the mutation that defeats the claim it
+names. Method: `cp -a` of the tree per mutation into a **unique** directory,
+the edit applied there, `__pycache__` purged, the suites run in the CI image
+with the tree bind-mounted `:ro`, one file at a time. **The shipped tree is
+never edited**, so habit 18's revert hazard — SAFETY-37's harness killed between
+the edit and the `cp` that put the file back, and two harnesses sharing one
+backup path — is closed by construction rather than by a verified revert. Each
+row below records the byte delta, the file's sha256 before and after, and that
+the mutated line was **read back off disk** before the run started.
+
+| # | mutation | file | bytes | sha256 (first 16) before → after | red on |
+|---|---|---|---|---|---|
+| M1 | the `pv` row moved into `SENSORS`, i.e. announced on every install | `mqtt.py` | −79 B | `328d249b9d698ef6` → `532d3954c023bf3d` | 3 named in `test_mqtt.py`, 1 in `test_pv.py` |
+| M2 | `publish()` drops a `None` `pv` row again, so HA keeps the last number | `mqtt.py` | −98 B | `328d249b9d698ef6` → `dd54be458f446475` | 1 named (the acceptance criterion itself) |
+| M3 | `ABSENT_AS_UNKNOWN` widened past the one key it was written for | `mqtt.py` | +23 B | `328d249b9d698ef6` → `8fe571ebff3dacf4` | 1 named (`circulation` must still be dropped) |
+| M4 | a dead sensor reported as **0 W** instead of an absence | `pv.py` | −1 B | `55ba7471e9995436` → `9eecc34152b7ac12` | 4 named |
+| M5 | `_read_pv()` assigns only on a good read — a value outlives its sensor | `main.py` | +46 B | `c4d2cab34e50b5fd` → `189802aa69ce166d` | 2 named |
+| M6 | the unit is read and then ignored — a kW sensor published as watts | `pv.py` | −18 B | `55ba7471e9995436` → `ab19ef66c52f9379` | 2 named |
+| **M7** | **`self.grid = self.grid − self.pv_w` in `read_inputs()` — PV wired into the control path** | `main.py` | +106 B | `c4d2cab34e50b5fd` → `c38216edb7c5c8db` | **2 named, plus `tel11_pv_trace.py` clause 2/3 on 26 of the 41 stimulus cells** |
+| M8 | `optional_keys()` returns `("pv",)` unconditionally | `mqtt.py` | −52 B | `328d249b9d698ef6` → `86ff23efe3088ad8` | 3 named |
+| M9 | the PV caution made a `bad` row, i.e. a dead sensor is a `NOT READY` | `main.py` | +1 B | `c4d2cab34e50b5fd` → `45c74cab89943564` | 1 named |
+| M10 | the read gate removed — an unset option is read once a second forever | `main.py` | −10 B | `c4d2cab34e50b5fd` → `b67baa8aba3019e8` | 2 named, **plus two crashes** |
+
+`on_disk = True` for all ten: the mutated line was grepped back out of the file
+after the edit and before the run (MUTATION.md reporting rule 2), and no
+mutation is size-preserving, so rule 1's `+0 B` caveat does not arise.
+
+⚠️ **M10's two extra reds are CRASHES, not named checks, and that is recorded
+rather than tidied away.** Every `Hass` double in `test_inverter.py` and
+`test_telemetry.py` predates this read and has no `state()` method, so an
+unconditional PV read is an `AttributeError` rather than a failed assertion —
+habit 20's shape, a red with no name attached. Fixing those fixtures would be a
+change to what *their* checks report and belongs to whoever next touches them;
+this card's own fixture has `state()` and grades the property by name.
+
+⚠️ **M7's trace limb is where the two halves meet.** The mutant moves the
+control document on 26 of 41 cells — every cell whose PV schedule produces a
+READING. The five `none` cells and the five `zero` cells do **not** move, which
+is correct and is worth seeing: subtracting nothing, and subtracting zero,
+change nothing. A battery that only drove a dead sensor would have reported this
+mutation as a survivor for the third time.
+
+The clean tree those `before` hashes belong to: `app/main.py`
+`c4d2cab34e50b5fd`, `app/mqtt.py` `328d249b9d698ef6`, `app/pv.py`
+`55ba7471e9995436`.
+
+### ⚠️ M7 was a SURVIVOR on the first battery, and the fixture was the reason
+
+The card's **central** mutation — `self.grid = self.grid - self.pv_w` in
+`read_inputs()`, i.e. exactly the defect the whole card forbids — came back
+**green** on a six-file run at **+106 B**, on disk, purged, genuinely running.
+
+The property did not hold; the fixture could not reach it. `test_pv.py` part 6
+drove a **6 kW export over 12 cycles**, which puts the loop **against its
+rail**: the command moves `slew_w` every cycle and −6000 W and −14 000 W of
+apparent error produce the **same ramp, tick for tick**. MUTATION.md habit 23,
+with a saturated actuator in place of a coinciding value — and the habit's list
+of no-op-prone constructs is all *expressions*, so this is worth its own entry,
+which it now has.
+
+The fixture now drives a **600 W import the loop settles on**, with a
+responsive meter (`grid = base − batt`) so the error actually closes, asserts
+the resting target is well inside the rail, and asks habit 23's own question as
+its own check: **shift the meter by the same 8 kW and confirm the commands
+really would have moved.** On the first fixture that question answers *no*, in
+one line. Every number in the table above is from the battery re-run against
+the fixed tree.
+
+⚠️ **A red count is a property of the suite as much as of the mutation.** These
+name **this** tree at this commit; a later card that adds or re-bases a check
+moves the number with the mutation untouched. Re-measure rather than inherit.
+
+## 8. What none of this covers, with shapes
+
+* **Home Assistant itself.** That `None` renders as `unknown` and that the
+  recorder keeps a gap is read out of HA's source and quoted in §3; no HA runs
+  in this suite. What is graded here is the bytes this add-on publishes.
+* **Whether the operator's sensor tells the truth.** A sensor wired backwards,
+  or reporting DC where AC was meant, or a string instead of the array, is
+  published faithfully. §2 is the argument for why that is the right failure
+  mode; it is not a claim that it cannot happen.
+* **A roster of more than one.** The row is a **site** row — there is one PV
+  array as far as this add-on is concerned — so nothing per-unit exists to
+  separate, and every fixture is the shipped roster of one.
+* **The attribution.** This card records production. Whether the 20.5 kWh was
+  cloud, a limit or the optimiser is OPT-10's, and it needs a week of this
+  channel's history before it can be asked.
+* **`tools/`, the firmware and the ingress HTML** are outside part 6's census.
+* **The identity is only as wide as the stimulus.** `tel11_pv_trace.py` prints
+  its 41 cells with the documents for exactly that reason.
+
+## 9. No `CHANGELOG.md` entry
+
+`test_version_gate.py` 11b refuses a newest `## ` heading that is not
+`config.yaml`'s `version:`, and opening an `## Unreleased` section would mean
+taking a packaging decision this card does not get to take. The operator account
+is in `DOCS.md`; the release note belongs to the next PKG ticket, which should
+say that **0.10.1 → next** adds one optional key, announces no new entity on an
+install that does not set it, and changes no control behaviour.

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

@@ -0,0 +1,361 @@
+# TEL-12 — several PV inverters, and why a partial total is worse than none
+
+TEL-11 shipped `pv_entity` as a single `str?` in 0.11.0. The owner of the
+reference site reported **within minutes of it going live** that they have
+several PV inverters and could configure one.
+
+That is not a property of one house. A multi-string or multi-orientation roof
+routinely carries two or three inverters, each publishing its own power sensor
+into Home Assistant, and the add-on is sold to clients. So the channel had to
+become a roster.
+
+**OPT-10 is blocked on this and cannot start recording until it lands.** Which
+sets the bar: the number this channel publishes has to be one an attribution can
+believe, or the week of history OPT-10 is waiting for is worse than no history.
+
+---
+
+## 1. The surface: `pv_entities` beside `pv_entity`, and the measurement that
+decided it
+
+Two candidates, and they differ on exactly one question nobody in this
+repository could answer by reading: **does Supervisor accept a stored STRING for
+a key whose schema has become a LIST?** 0.11.0 shipped `pv_entity: str?`; the
+live install *has* a string persisted in it; and an upgrade that refuses that
+string leaves an add-on which will not start — CFG-04 §B's trap, in the other
+direction, with the schema needed to fix it pinned to the version that cannot be
+installed.
+
+It was measured, against the release image, by a new **§G** of
+`tools/supervisor_shape_probe.py` — the instrument CFG-04 built for exactly this
+kind of question:
+
+```
+docker run --rm -v "$PWD:/w:ro" -v "$PWD/tools:/probe:ro" --entrypoint python3 \
+  ghcr.io/home-assistant/amd64-hassio-supervisor:2026.08.0 \
+  /probe/supervisor_shape_probe.py
+```
+
+```
+== G. TEL-12: the SHAPE of a several-inverter PV option ==
+  PASS  the shipped defaults with a 0.11.0 `pv_entity` STRING on top are ACCEPTED - the baseline every refusal below is varied from
+        pv_entity='sensor.pv_power' pv_entities=[]
+  PASS  ⭐ THE MEASUREMENT THAT DECIDED THE SURFACE: with `pv_entity` declared as a LIST, the string an 0.11.0 install has persisted is REFUSED, and the refusal names the key - so that shape would leave the live add-on unable to start on upgrade
+        Invalid list for option 'pv_entity' in GoodWe RS485 Controller (local_goodwe_controller)
+  PASS  ...and a shipped `pv_entity: []` DEFAULT does not rescue it: deepmerge's list strategy is `override`, so the operator's string survives the merge and is refused anyway
+        Invalid list for option 'pv_entity' in GoodWe RS485 Controller (local_goodwe_controller)
+  PASS  ...(the list shape itself is fine - it is only the STORED STRING it refuses, which is what makes this a migration and not a schema question)
+        a list value validates
+  PASS  ⚠️ ONE SPELLING DOES ACCEPT BOTH - `match(.*)?` - AND IT IS REJECTED FOR A DIFFERENT REASON, MEASURED HERE: it validates NOTHING. A string passes, a list passes, and so does the integer 417; and the Configuration tab renders it as a plain text box rather than a repeatable field, so an operator cannot enter a second inverter in the UI at all
+        string=True list=True integer-417=True ui=[{"name": "pv_entity", "optional": true, "type": "string"}]
+  PASS  ⭐ THE SHIPPED SHAPE: an 0.11.0 blob - `pv_entity` a string, no `pv_entities` key at all, because it did not exist when that blob was written - validates against THIS manifest, with the new key defaulted to the empty list. The live install upgrades without touching its options
+  PASS  ...and a three-entity roster validates, per-entry, with both keys set - which the add-on resolves by REPLACEMENT and says so on its status page
+        ["sensor.pv_east", "sensor.pv_west", "sensor.pv_garage"]
+  PASS  ⭐ ...and the shipped `options:` block with ONLY `pv_entities` removed is REFUSED, BY NAME - `Missing option 'pv_entities' in root`. That is why the `pv_entities: []` default is load-bearing, exactly as `inverters: []` is: Supervisor treats a nested list as required unless its element is an OPTIONAL scalar, and `- str` is not one
+        Missing option 'pv_entities' in root in GoodWe RS485 Controller (local_goodwe_controller)
+  PASS  ...and the Configuration tab renders it as a REPEATABLE string field (`multiple: true`), so an operator adds their second and third inverter in the UI rather than in YAML
+        [{"name": "pv_entity", "optional": true, "type": "string"}, {"name": "pv_entities", "multiple": true, "required": true, "type": "string"}]
+  PASS  a DOWNGRADE to a schema without `pv_entities` drops the key with a warning rather than refusing, and leaves `pv_entity` standing - so rolling back to 0.11.0 returns the install to its single entity rather than bricking it
+
+== all cases passed ==
+```
+
+| Claim | Evidence |
+|---|---|
+| **Option 1 — `pv_entity` becomes a list — cannot ship** | §G: `Invalid list for option 'pv_entity'` on the string an 0.11.0 install has stored |
+| …and a `[]` default does not rescue it | §G: `_OPTIONS_MERGER`'s list strategy is `override`, so the operator's string survives the merge and is refused anyway |
+| …and it is not a *schema* problem | §G: a list **value** validates fine against a list schema. It is a **migration**, and a migration is a bigger ticket than this |
+| **One key CAN carry both shapes** — `match(.*)?` | §G, and reported even though it *passes*, because "no spelling accepts both" would have been a **false reason** to reject option 1 |
+| …and it loses anyway, for a measured reason | §G: it validates nothing at all — a string, a list, and the integer `417` all pass — and the Configuration tab renders it as a plain text box, so an operator cannot add a second inverter in the UI |
+| **Option 2 — `pv_entities` beside `pv_entity` — ships** | §G: the 0.11.0 blob validates untouched, the new key defaults to `[]`, three entities validate, the UI renders `multiple: true` |
+| `pv_entities: []` in `options:` is load-bearing | §G: the shipped defaults **minus only that key** are refused with `Missing option 'pv_entities' in root` — CFG-04 §B's isolated counterfactual, for this key |
+| A downgrade is not the trap in reverse | §G: a schema without the key **drops** it and leaves `pv_entity` standing |
+
+`p1_phase_import_entities` (`options: []` + `schema: - str`) is the shipped
+precedent for the pair; nothing new was invented.
+
+**So the surface is uglier than option 1 and that is the correct trade.** The
+cleanest surface that breaks the one install this card exists to fix is not the
+cleanest surface.
+
+### And `pv_entities` REPLACES `pv_entity` rather than extending it
+
+CFG-04's rule for `inverters:` ("declared, it REPLACES those six keys"), applied
+to the only upgrade path that matters. The install being upgraded **has**
+`pv_entity` set, to inverter A. Opening the Configuration tab, the natural action
+is to put *all* the inverters in the new repeatable field — and under a union
+rule that **double-counts A** unless the operator also remembers to clear the old
+key. A doubled total is the same defect as a partial one pointing the other way,
+in the one channel that exists to be believed a week later.
+
+Under replacement the effective roster is exactly what one key says, and no
+arithmetic depends on a de-duplication rule the operator has to know about. It
+de-duplicates *within* the list (a site cannot have two sensors with one
+entity_id, so a repeated id is a typo that would double that inverter), and
+`Controller.checks()` prints a **caution** whenever both keys are set saying
+which one won — a replacement nobody is told about is the "one of which silently
+wins" `config.yaml` refuses elsewhere.
+
+⚠️ It is a **caution and never a refusal to start**. `validate.py` still does not
+mention either key. A telemetry channel that could stop a battery site from
+starting would be observability with a foot in the control path.
+
+---
+
+## 2. ⚠️⚠️ The decision the card turns on: absence of ONE is absence of the TOTAL
+
+Three inverters configured, one `unavailable`. The sum of the other two is **a
+smaller number indistinguishable from a real one.** Fed into OPT-10's
+attribution it reads as *"there was less PV than there was"* — which is the "no
+irradiance" conclusion the channel exists to **test** rather than to manufacture.
+
+Two designs were genuinely available:
+
+**(a) publish the total as absent** — `pv.total()` answers `None`, the topic
+carries HA's own `None`, the entity goes to `unknown`, the recorder stores a gap.
+
+**(b) publish the partial sum alongside a count of how many contributed.**
+
+**(a) shipped.** It wins on the one question that matters, which is *who reads
+the number and when*:
+
+* The **MQTT row** is read back **cold**, a week later, by OPT-10 and by anything
+  that plots `sensor.goodwe_pv_power` over that week. A partial sum there is a
+  smaller number indistinguishable from a real one, and the count that would
+  have qualified it lives in a **second entity with its own history** — so
+  believing the total requires joining two recorder series by timestamp to find
+  out which samples to distrust. Nobody re-derives that. And it is worse than a
+  gap in exactly the direction that matters: **a gap makes the attribution say
+  "I do not know"; a partial makes it say something false.**
+* The **status page** is read **live**, by a human who wants the diagnostic. So
+  the partial information is *not* thrown away — the row names every entity that
+  did report, with its watts, and every one that did not, with its reason, and
+  states plainly that there is no site total. Different reader, different
+  instant, different rule.
+
+A count published beside the total would also carry **no information** in the
+state (a) admits: the total is published *only* when every entity contributed, so
+the count would be the constant `len(roster)`.
+
+And this **extends** TEL-11's rule rather than weakening it. `mqtt.py`'s
+`ABSENT_AS_UNKNOWN` is still exactly one key and `publish()`'s `None` handling is
+untouched: the line that turns an absence into HA's `unknown` did not have to
+change, because "absence is never zero" already covered this one layer up.
+
+### The mirror, which matters just as much
+
+A member honestly reporting **0 W** is **summed**, not treated as absent. The
+test is `watts is None`, never falsiness. Shading, a tripped string and
+nightfall are all real zeros, and a roster that blanked the site whenever one
+member read zero would report an absence **on every clear evening** and defeat
+the channel from the other end.
+
+### ⚠️ And the answer is NOT "document a template sensor that adds them up"
+
+An operator may legitimately prefer one, and `pv_entity` will happily point at
+it. Shipping it as *the* answer pushes the absence problem onto them unseen: a
+template sensor summing an `unavailable` source silently yields the partial
+total — the same defect one layer down, in a place this add-on cannot see or
+report. DOCS.md says so in those terms.
+
+### The three published states, side by side
+
+| what happened | frame | `goodwe_ctl/pv` | status page |
+|---|---|---|---|
+| no roster at all | no `pv` key | no topic, no entity | no row |
+| 1200 / 2100 / 450 W, all three | `pv: 3750.0` | `3750.0` | `PV  3 750 W` + one ok row naming all three |
+| all three answer, one of them `0 W` | `pv: 1650.0` | `1650.0` | `PV  1 650 W` |
+| one of the three `unavailable` | `pv: None` | `None` → `unknown`, recorder **gap** | `PV  —` + a caution naming the missing entity, its reason, and what the others reported |
+| all three gone | `pv: None` | as above | as above |
+
+---
+
+## 3. Still not a control input
+
+Unchanged, and re-proved at the new roster size.
+`tools/tel11_pv_trace.py` was **extended rather than replaced** — the file name
+still says TEL-11 because `DECISIONS/TEL-11-pv-production.md` §5 and
+`test_pv.py`'s mutation table quote it, and a renamed instrument makes both
+references dangle for no gain.
+
+It now produces **three** document sets per tree — `unset`, `one`, `multi` — and
+grades five claims. The roster cells live in their own document precisely so
+`unset` and `one` keep the `control` hashes TEL-11 recorded; appending cells to
+an existing document would have moved a hash whose stability is itself the
+evidence.
+
+```
+$ python3 tools/tel11_pv_trace.py --compare base.json head.json
+  HEAD is B; baseline is A - its roster cells ARE its unset cells, which is what a tree that has never heard of `pv_entities` does with them.
+  supports_roster   A False / B True   (self-reported; the verdict above is MEASURED)
+  tree      A fa92ba6a6fc6d49c0f87a494e03b530a8575212a0b2c3046629cb400ef2ae0d4
+  tree      B 0b39198015b6a5a3f7538d4157d77ecadc89311daef18fce883762d94d8351eb
+  control   A unset 846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   B unset 846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   A one   846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   B one   846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   A multi 2aafbfedfb9cc939082b36eeb7493289808fb21cd41113322d4817de0e414a30
+  control   B multi 2aafbfedfb9cc939082b36eeb7493289808fb21cd41113322d4817de0e414a30
+  telemetry A unset a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
+  telemetry B unset a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
+  telemetry A one   4e6d1cb289a957223ad0205f732a6fec6110ce1f2032c98ad60694e67625274f
+  telemetry B one   4e6d1cb289a957223ad0205f732a6fec6110ce1f2032c98ad60694e67625274f
+  telemetry A multi d269168ffece375027c2c18ea33631a961ff92775781884a0592d6a37d78845c
+  telemetry B multi 550a49a73f39267ba28b1e78cd12b8f5c71ef7269bbbd2e12112696be0fef1ff
+OK  1/5  UNSET: control AND telemetry are byte-identical to the baseline tree. …
+OK  2/5  ONE ENTITY: control AND telemetry are byte-identical to 0.11.0's single-entity path - the same commands, the same payloads, the same status rows, the same announcement.
+OK  3/5  CONTROL, ONE ENTITY: the control document is byte-identical with the channel switched on - PV reaches no decision.
+OK  4/5  CONTROL, THREE ENTITIES: every roster cell's control document equals its grid world's `unset` one - 30 cells over 5 grid worlds, covering three healthy entities, one dead at EVERY position, all three dead and one honestly reporting 0 W. Neither the total nor any PARTIAL total reaches a decision, and the document is byte-identical to the BASELINE tree's for the same cells.
+OK  5/5  CONTROL OF THE CONTROL: the telemetry document DOES move under a roster (30 stimulus cells differ from their grid world's unset telemetry), so 1/5-4/5 are identities this instrument could have broken. AND in no cell with a dead member does the PV row carry the partial sum of the survivors, while every cell whose members all ANSWER publishes its total - including the one where a member honestly reports 0 W.
+$ echo $?
+0
+```
+
+**The control hash is unmoved: `846a10a5b89e…` on `unset` and on `one`, on both
+trees.** The roster control document `2aafbfedfb9c…` is byte-identical between
+the two trees, which is the strongest available form of the claim — the baseline
+runs those cells with a key it has never heard of, so its control document for
+them *is* 0.11.0's.
+
+⚠️ **2/5 is a claim TEL-11 could not make.** TEL-11's baseline had no channel at
+all to be identical to; TEL-12's baseline is 0.11.0, so "one entity behaves
+exactly as 0.11.0 does" is a real cross-tree identity over **both** documents.
+`pv.total()` passes a single entity's `(watts, why)` through verbatim for exactly
+this reason, and `Controller.checks()` keeps 0.11.0's two f-strings in a
+`len(...) == 1` branch rather than generalising them.
+
+### ⚠️ TEL-11's `--compare` refusal had to change, and that is a finding
+
+TEL-11's rule was *"exactly ONE side's `set` document may differ from its own
+`unset` — that side is the HEAD"*. It was correct evidence when written, because
+`release/1.0` predated `pv_entity` entirely. `release/1.0` is 0.11.0 now, **both**
+sides react to `pv_entity`, and that refusal fires on **every honest run**. The
+discriminator is the roster instead: only the HEAD has heard of `pv_entities`, so
+only the HEAD's `multi` document fails to reduce to its own `unset` one.
+
+It is asserted from the **documents**, not from `tree.supports_roster` — a
+self-report is the tree describing itself, whereas "this side's behaviour did not
+move when `pv_entities` was set" is the tree being measured. `supports_roster` is
+printed beside the verdict so a disagreement between the two is visible.
+
+See MUTATION.md habit 24.
+
+---
+
+## 4. Mutation battery
+
+Twelve mutations, each on a **fresh `cp -a`** of the clean worktree (never
+reverted — habit 18 / TARIFF-09's method), `__pycache__` purged before the run
+and the tree checked for one afterwards, byte delta from `stat` and the edit
+confirmed on disk with `cmp`, suites run in the CI image with `checks.yml`'s own
+command one file at a time under a `:ro` mount.
+
+| mutation | bytes | reds |
+|---|---|---|
+| N1 `total()` returns the partial sum, not an absence | +42 B | 6 named in `test_pv.py` + 1 crash |
+| **N1b ⭐ THE REJECTED DESIGN: the partial sum with a contributor count** | −282 B | **10 named + the trace `REFUSED 5/5`** |
+| N2 absence tested by falsiness (`not w`) | −4 B | 2 named |
+| N3 `pv_entities` UNIONS with `pv_entity` | −27 B | 3 named |
+| N4 the de-duplication dropped | −15 B | 1 named |
+| N5 `sum` → `max` over the roster | **+0 B** | 6 named |
+| N6 the roster-of-one stops passing `why` through | +13 B | 8 named |
+| N7 `optional_keys()` back to reading `pv_entity` | −6 B | 1 named + 1 crash |
+| N8 `self.grid -= self.pv_w` in `read_inputs()` | +106 B | 3 named + the trace (52 cells on 2/5, 26 on 3/5, 10 on 4/5) |
+| N9 the roster caution made a `bad` row (NOT READY) | +1 B | 1 named |
+| N10 `entity_is_ignored()` always False | +10 B | 2 named |
+| N11 `pv_entities: []` deleted from `options:` | −18 B | 2 named in `test_translations.py` + `11 CASE(S) FAILED` in the probe |
+
+**No survivors.**
+
+⚠️ **N5 is `+0 B` — the risky delta.** `sum` and `max` are the same three
+characters, so neither the file size nor its mtime moved, and TEST-15's
+stale-bytecode defect is exactly what manufactures a survivor there. The run was
+on a fresh purged copy and `cmp` confirmed the edit on disk before it started.
+
+⚠️ **N1b is the row that matters, and it is not a defect.** It is the *other*
+defensible design, implemented and run. The point is that the checks and the
+instrument can **tell the two apart** — an unexamined partial sum is what the
+card forbids, so a check that could not see one would be decoration:
+
+```
+REFUSED 5/5: THE PARTIAL SUM IS ON THE WIRE at [('EXPORT-6K/EAST-DEAD', '2550.0'),
+('EXPORT-6K/GARAGE-DEAD', '3300.0'), ('EXPORT-6K/WEST-DEAD', '1650.0'),
+('IMPORT-3K/EAST-DEAD', '2550.0'), ('IMPORT-3K/GARAGE-DEAD', '3300.0'),
+('IMPORT-3K/WEST-DEAD', '1650.0')] … - a smaller number indistinguishable from a
+real one, which is the defect this card exists to prevent.
+```
+
+⚠️ **N8's 1/5 stays GREEN and that is correct rather than a miss.** With no PV
+entity configured `pv_w` is `None` and the leak cannot fire — which is what makes
+1/5 a claim about the **default** and 2/5–4/5 the claims about the channel.
+
+### The fixture values are the design (habit 10 and habit 23)
+
+`test_pv.py` carries **two** rosters over the same three entities, because the
+two claims need different magnitudes and one fixture cannot serve both.
+
+* **Parts 8–10: 1200 W + 2.1 kW + 450 W = 3750 W.** The sum is separable from
+  max (2100), min (450), first (1200), last (450), mean (1250), count (3) and
+  every partial of itself (2550 / 1650 / 3300) — the family is computed, printed
+  and asserted non-colliding as its own precondition. One member is in **kW** so
+  "correct against their own units" is exercised. **Not one member is zero**: a
+  member contributing 0 W could go absent without moving the sum of the rest, and
+  a fixture like that cannot tell "published the absence" from "published the
+  partial sum" — habit 23 with a coinciding value in the *fixture* rather than in
+  the plant, which is precisely the trap the brief named. Absence is driven at
+  **every position** of the roster, not at one (habit 10's fixture-as-a-SET), and
+  each position's partial is **derived from the fixture** rather than typed
+  beside it.
+* **Part 6: 1500 W + 4.5 kW + 2000 W = 8000 W.** Sized so every *partial*
+  (6500 / 3500 / 6000) would still **move** a loop settling on a 600 W import.
+  Habit 23's own question is asked twice — shift the meter by 8000 W, and again
+  by 3500 W, the smallest partial any single dead member could produce — because
+  a leak of the partial is a different mutation leaking a smaller number.
+
+### Two false results this card produced, and what they were
+
+Both were in the **instrument**, and both are recorded rather than tidied away.
+
+1. `partial_w`/`partial_wire` were first written **inside** each telemetry cell.
+   They are a fact about the *stimulus*, produced by the tool and identical on
+   both trees — so every roster cell differed from its unset reference for a
+   reason that was not behaviour, and the HEAD/baseline discriminator fired on
+   *both* sides. They live in a separate top-level `partials` map now.
+2. The `WEST-ZERO` cell (all three answer, one honestly reporting 0 W) had its
+   **true total** labelled as its "partial". 5/5 then refused the *shipped* tree
+   for publishing 1650 W, which it is required to publish. A cell with no dead
+   member has no partial to leak, and `never` is `None` there.
+
+---
+
+## 5. What none of this can see
+
+* **Home Assistant itself.** That `None` on the state topic renders as state
+  `unknown` and that the recorder keeps a gap is read out of HA's source and
+  quoted in `app/mqtt.py`; whether the long-term statistics table then
+  interpolates across the gap is HA's behaviour, and OPT-10 will be reading it.
+* **Whether the operator's sensors are telling the truth.** A sensor wired
+  backwards reads −4 kW at noon and is summed as −4 kW. There is deliberately no
+  `pv_invert` — §2 of the TEL-11 record is the argument, and it holds at a roster.
+* **A roster larger than three.** Three is the smallest size at which the sum
+  separates from the reduction family *and* absence can be driven at every
+  position. Nothing here says what twenty entities do to a cycle's latency — the
+  read is `asyncio.gather`ed across the roster for exactly that reason, so a slow
+  sensor costs what one costs, but that is an argument rather than a measurement.
+* **A PV roster combined with a two-inverter battery roster.** No fixture
+  crosses CFG-04's `inverters:` with `pv_entities`.
+* **The real MQTT transport, and wall-clock behaviour.** As TEL-11.
+
+---
+
+## 6. Not deployable as merged
+
+`config.yaml` stays at `0.11.0`, so `tools/predeploy_check.py` reports a NO-OP
+until PKG cuts a version. A CHANGELOG entry is **wanted** and was deliberately
+not written: `test_version_gate.py` 11b forbids an `## Unreleased` heading and
+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/TEL-14-pv-sign.md

@@ -0,0 +1,83 @@
+# TEL-14 — the PV sign, declared per entity
+
+Owner report on 0.12.0: `sensor.espressif_vermogen` (ESPHome clamp) and
+`sensor.kwh_meter_actueel_vermogen` (kWh meter in the PV circuit) read
+**positive for consumption, negative for production**. At night the page said
+"✓ PV production: 13 W" — standby draw. By day production would publish negative.
+
+## 1. This reverses TEL-11 §2, and why
+
+TEL-11 §2 refused a `pv_invert` on two grounds. "PV is read by nothing in the
+control path" still holds: the flip lives in `pv.total()`, and `test_pv.py`
+part 12 re-runs part 6's 40-cycle identity with a flip set. "A reversed sensor
+announces itself" did not survive a real site: these sensors follow a different
+convention, read a plausible small positive number at night, and the only other
+fix is a template sensor, the place TEL-12 §2 says goes quietly wrong.
+
+## 2. The shape: a parallel list, `pv_invert_entities`
+
+Measured by `tools/supervisor_shape_probe.py` §H (Supervisor 2026.08.0, against
+a 0.12.0 blob); re-run it for the transcript.
+
+| shape | schema | why it lost / won |
+|---|---|---|
+| (a) `-sensor.x` prefix | accepted | invisible: the sign is a syntax only the description explains, in a field an installer fills with the entity picker's text |
+| (b) parallel list | accepted, 0.12.0 blob unchanged | **ships**: its own labelled, translated field ("PV entities whose sign is reversed"); an installer lists the odd ones out |
+| (c) dicts on `pv_entities` | **refuses 0.12.0's stored strings** | bricks the upgrade — TEL-12's trap again |
+| (c2) dicts as a third key | accepted | per-entry labels render raw (`entity`, `invert`) — probe §F; and a third PV surface |
+| (d) global bool | accepted | one sign cannot describe inverter + meter in one roster |
+
+(b)'s known cost is a typo in the second list: `pv.stray_inverts()` turns it into
+a named caution. `[]` in `options:` is load-bearing (§H, isolated counterfactual).
+Default `[]` flips nothing, so every 0.12.0 install is byte-identical (part 12).
+
+## 3. The negative caution: per entity, below −50 W
+
+The owner's two meters draw ~13 W at night, so a *correctly* signed meter reads
+about −13 W then. −50 W clears that with room for a few such devices behind one
+entity; a reversed sensor by day reads hundreds to thousands of watts below
+zero. It is tested **per entity, not on the total** (a deviation from the brief):
+three correct meters at −20 W sum to −60 W and must stay quiet, while a reversed
+−1500 W hidden inside a positive total must not. It is a caution, never `bad`;
+a wrong threshold costs a spurious or missed caution, never data. The text says
+ADD (unflipped) or REMOVE (already flipped).
+
+## 4. Mutations
+
+Fresh `cp -a` each, `__pycache__` purged, CI image, `:ro`, `--network none`;
+`test_pv.py` only unless stated. T1-T12 at 7559d21; M2/M5 are review #1628's,
+red since B1 (merged into release/1.0 @ 43b2740).
+
+| # | mutation | bytes | reds |
+|---|---|---|---|
+| T1 | flip ignored in `total()` | −45 | 9 |
+| T2 | flip applied to every member | −7 | 6 |
+| T3 | `0.0 - w` → `-w` | −5 | 1 |
+| T4 | flip written as `abs()` | −1 | 2 |
+| T5 | `_read_pv()` stops passing the flip | −26 | 7 |
+| T6 | caution threshold −50 → 0 W | −17 | 3 |
+| T7 | `[sign inverted]` marker dropped | −39 | 3 |
+| T8 | negative caution made `bad` | +1 | 1 |
+| T9 | `stray_inverts()` always empty | −50 | 1 |
+| T10 | `inverted()` stops stripping | −8 | 1 |
+| T11 | ADD/REMOVE advice swapped | +4 | 2 |
+| T12 | `pv_invert_entities: []` deleted from `options:` | −25 | 2 test_translations + 17 probe |
+| M2 | `stray_inverts()` roster ignores `pv_entity` | +15 | 2 (REPORTED CASE, PADDING) |
+| M5 | `_read_pv()` flip set not stripped | +25 | 1 (PADDING) |
+
+## 5. History
+
+OPT-10's `sensor.goodwe_pv_power` recorded since 2026-09-24 on an install with
+such sensors carries the old sign; nothing rewrites it.
+
+## 6. CHANGELOG entry for the next PKG cut
+
+Not written into `CHANGELOG.md`: `test_version_gate.py` 11b/11d refuse an
+`## Unreleased` heading (measured on this branch: 4 reds). For PKG to paste:
+
+> **`pv_invert_entities` (TEL-14).** A PV sensor that reads negative while
+> producing — typically a kWh meter or power clamp in the PV circuit — can now
+> be listed under *PV entities whose sign is reversed* in the Configuration tab;
+> its sign is flipped before the sum and the status page marks it. Empty (the
+> default) changes nothing. ⚠️ PV history recorded before you set it keeps the
+> old sign.

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

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

goodwe_controller/MUTATION.md

@@ -811,6 +811,177 @@ Cheap habits fall out of it, and all of them are now used in this repository:
     retrofitted: guarding another card's section is a change to what its
     checks report, and it belongs to whoever next touches it.
 
+21. ⚠️ **A CHECK CAN BE GREEN UNDER ITS OWN CARD'S NAMED MUTATION, AND TWICE
+    IN ONE FILE THE REASON WAS THAT THE WRONG QUANTITY EVENTUALLY REACHES THE
+    RIGHT VALUE.** TEL-10's acceptance was *"a run that winds the integrator
+    into the bound must show the published number reaching the bound"*, and its
+    named mutation was *"publish `prev_w` instead of `i_w`"*. The check was
+    **GREEN** on the mutant: the command reaches the same bound too, twelve
+    cycles later, and a check that only reads the VALUE cannot tell the two
+    apart. The same file's *"a stopped controller publishes `not-running`"* was
+    green under deleting that branch's assignments outright (−45 B and −67 B),
+    because the fixture STARTED stopped and `__init__` writes the same values.
+    Both are habit 4 - the data could not reach the failure - and both were
+    found by the card's own battery. The fixes are the shape to copy:
+    * where two quantities CONVERGE, grade the **order or the interval**, not
+      the value: "the integrator reaches the bound BEFORE the command does",
+      and a PLATEAU (the lead sits at exactly −800 W for eight consecutive
+      cycles) rather than a maximum, because a maximum is one tick and a
+      plateau is the shape;
+    * where a branch WRITES a value the constructor also writes, the fixture
+      has to pass THROUGH the other state first. Stop the controller part-way
+      through a run that has already wound the integrator to −5000 W, so a row
+      left standing is a WRONG row and not merely an unset one.
+
+22. ⚠️ **AN EXPLANATION IN A COMMENT IS A CLAIM, AND SAFETY-48 SHIPPED TWO THAT
+    WERE INVENTED.** A gate was written one-sided (`if target > slewed: min(...)
+    elif target < slewed: max(...)`) under a comment saying the two-sided band
+    `max(lo, min(hi, i_w))` was a BUG that would drag a trailing integrator
+    toward the command, with a worked example. It is not a bug and the example
+    was wrong: `target` is monotone in `i_w`, so the other clamp cannot reach,
+    and the two spellings agree on **205 920 of 205 920** swept states. A second
+    bullet said two placements of the same cap *"differ on 118 of 256 252
+    ticks"*; that 118 had been measured against a **different pair** and the
+    placement actually being compared is bit-identical on the shipped
+    configuration - 0 of 256 246 ticks. Both sentences were plausible, both were
+    load-bearing for a design choice, and neither had been run.
+    **The rule: a comment that says "X would be wrong" is subject to the same
+    battery as a check - BUILD X AND MEASURE IT.** Where the answer is
+    "equivalent", say so with the sweep size and keep the spelling for what it
+    NAMES; where the answer is a number, quote the run it came from. An
+    invented justification for a correct decision is still a defect, and it is
+    the kind a reviewer cannot see because the code is right.
+
+23. ⚠️ **THE MUTATION IS SUBJECT TO EVERY HABIT ABOVE, HABIT 4 INCLUDED - AND
+    THE PURGE, THE FINGERPRINT AND THE BYTE DELTA ALL SAY IT TOOK.** SAFETY-57's
+    battery reported a **survivor at +21 B** for a mutation of
+    `Freshness._open_window()`: `self.graded_from = float(now_mono)` rewritten
+    as `float(self.changed_mono or now_mono)`, which is meant to re-anchor the
+    verdict's window to the register's own history and so delete the card's
+    whole exit. The harness purged, the tree fingerprint showed the edit on
+    disk, the delta was non-zero, and the mutant really did run. It was still a
+    survivor for a reason that has nothing to do with the property: in the
+    fixture the register never moves after `t = 0`, so `changed_mono` is
+    **`0.0`** - and `0.0 or x` is `x`. **The mutant was a no-op on that
+    stimulus.** Rewritten with an explicit `is None` test (+82 B) it is red on
+    four named checks.
+
+    Stale bytecode is a mutation that never *ran*. This is a mutation that ran
+    and could not *change the answer* on the data it was given, which is habit 4
+    exactly, one level up - and none of the three things a mutation report is
+    required to state (MUTATION.md's own list) can see it, because all three are
+    about the file rather than about the stimulus. Two rules:
+    * **Ask of every survivor what it would have had to change, and check that
+      the fixture reaches that value.** Here: "does any fixture have a non-zero
+      `changed_mono` at the moment `_open_window()` is called?" The answer was
+      no, and it is one line to ask.
+    * **Prefer a mutation that CANNOT be a no-op.** `or`, `and`, truthiness on
+      a numeric, a default argument and a `getattr` fallback all have a value at
+      which the mutant and the shipped tree coincide. An explicit comparison,
+      a constant swap or a deleted statement does not.
+
+    ⚠️ Note where this one was found: in the battery of a card whose whole
+    subject is a check that cannot reach the failure it names. **Second
+    instance in an instrument rather than in a check since habit 16, and the
+    third overall.**
+
+    ⚠️ **AND THE SAME CARD'S BATTERY CAUGHT A HABIT-22 COMMENT IN THE FIX
+    ITSELF, WHICH IS WHY THESE TWO BELONG NEXT TO EACH OTHER.**
+    `freshness.py` shipped `⚠️ RELEASE BEFORE GRADE, AND THE ORDER IS
+    LOAD-BEARING` with a worked reason. Swapping the two calls is **zero bytes**
+    and survived the battery: `_grade()` acts only when `|standing| >= move_w`
+    and `_release()` only when `|standing| < move_w`, so at most one can act on
+    any read and the order is **not observable**. Habit 22 says build X and
+    measure it; the battery is what builds X. The comment now states the
+    disjointness and the suite pins **that** - at 0, 100, 249, 250, 251 and
+    1300 W - rather than an order nothing depends on.
+
+    ⚠️ **SECOND INSTANCE, TEL-11, AND THE NO-OP WAS A SATURATED RAIL RATHER
+    THAN A VALUE.** The card's whole subject is that a PV reading must never
+    reach the control law, so its central mutation is
+    `self.grid = self.grid - self.pv_w` in `read_inputs()` - **+106 B**, on
+    disk, purged, genuinely running - and it came back a **SURVIVOR** of a
+    six-file battery. The property held in no sense: the fixture drove a 6 kW
+    export over 12 cycles, which puts the loop **against its rail**, and a
+    command moving `slew_w` every cycle produces the SAME ramp for -6000 W and
+    for -14000 W of apparent error. The mutant ran and could not change the
+    answer.
+    Two things generalise past PV:
+    * **A SATURATED ACTUATOR IS A VALUE AT WHICH EVERY INPUT COINCIDES.** The
+      habit-23 list above names `or`, `and`, truthiness, default arguments and
+      `getattr` fallbacks - all *expressions* with a coinciding value. A rail,
+      a clamp, a slew limit, a deadband and a latched alarm are the same hazard
+      in the **plant**: they are where a controller's output stops being a
+      function of its input. A fixture that parks there cannot separate any two
+      inputs, and this repository's control fixtures park there by default,
+      because the dramatic stimulus is the saturating one.
+    * **SO THE PRECONDITION IS NOT "DOES IT COMMAND SOMETHING", IT IS "DOES IT
+      REST SOMEWHERE THE MUTATION COULD MOVE IT FROM".** `test_pv.py` part 6
+      now drives a 600 W import the loop SETTLES on, asserts the resting target
+      is well inside the rail, and asks habit 23's own question as a check:
+      shift the METER by the same 8 kW and confirm the commands really would
+      have moved. On the first fixture that question answers NO, in one line,
+      and it is the line that turns the identity into evidence.
+
+24. **A REFUSAL DEFINED RELATIVE TO "THE BASELINE LACKS THIS FEATURE" DIES ON
+    THE RELEASE THAT SHIPS THE FEATURE — AND IT DIES AS A FALSE REFUSAL, WHICH
+    IS THE LOUD DIRECTION.** TEL-11 built `tools/tel11_pv_trace.py` to grade a
+    cross-tree identity, and because "the documents are identical" was its
+    *result* rather than its warning sign, it had to prove instead that the two
+    runs came from different trees and that **exactly one side reacts to
+    `pv_entity`**. That was correct evidence: `release/1.0` predated the option
+    entirely, so a side that reacted to it was the HEAD by construction.
+
+    TEL-11 then **merged**, `release/1.0` became 0.11.0, and the baseline for
+    the next card reacts to `pv_entity` too. `--compare` now answers
+    `REFUSED: set differs from unset on ['A', 'B']` on every honest run — the
+    instrument refuses its own shipped tree. TEL-12 found it on the first
+    comparison it ran.
+
+    * **A discriminator is a fact about a MOMENT, not about a card.** "The
+      baseline does not have X" is true until X ships and then false forever.
+      Write the discriminator against something the NEXT baseline still will not
+      have — TEL-12's is the roster key, not the channel — and say in the tool
+      which fact it rests on, so the next card can see what it has to replace.
+    * **Prefer a discriminator that is MEASURED over one the tree REPORTS.**
+      `tree.supports_roster` is the tree describing itself and would have been
+      one line; the shipped test is "this side's roster cells ARE its unset
+      cells", which is the tree being measured. Both are printed, side by side,
+      so a disagreement between the self-report and the measurement is visible
+      rather than silently trusted.
+    * ⚠️ **And this is the SAFE direction of the same defect, which is why it
+      was found in ten minutes rather than in a review.** A stale refusal is a
+      developer chasing a failure they cannot explain (the false-red case at the
+      top of this file). A stale *identity* — an instrument that goes on printing
+      OK because its reference drifted into agreement — is the survivor-
+      manufacturing direction, and nothing announces it. Ask of every cross-tree
+      instrument: *what does this print when the feature it is about has been in
+      the baseline for a year?*
+
+    TEL-12's own battery produced two more instrument defects of the ordinary
+    kind, both recorded in `DECISIONS/TEL-12-several-pv-inverters.md` §4: a
+    stimulus annotation written into the document being compared (so every cell
+    differed for a reason that was not behaviour, and the discriminator fired on
+    both sides), and a fixture cell whose TRUE total was labelled as its
+    "partial" (so the check refused the shipped tree for publishing a number it
+    is required to publish). ⚠️ **Both were caught by running the instrument
+    against the shipped tree BEFORE running it against a mutant** — which is the
+    one ordering rule that separates "the instrument is wrong" from "the tree is
+    wrong", and `test_mqtt.py` part 8's first line ("the shipped module satisfies
+    every property this instrument grades") is the same rule as a check.
+
+    ⚠️ **AND TEL-12's SUBJECT WAS HABIT 23 IN THE FIXTURE ITSELF.** The card adds
+    a SUM over a roster, and the defect it exists to prevent is publishing the
+    partial sum when a member is absent. A fixture whose absent member
+    contributes **0 W** cannot see that defect at all: the partial and the full
+    total are **the same number**, so "published the absence" and "published the
+    partial" produce identical output. That is a rail in the *arithmetic* rather
+    than in the plant — the same hazard as TEL-11's saturated actuator, one
+    domain over. `test_pv.py`'s roster is three distinct non-zero contributions
+    in two different units, absence is driven at **every position** rather than
+    at one (habit 10), and each position's partial is **computed from the
+    fixture** and asserted to differ from the true total as its own precondition.
+
 And the mutation-table consequence: **a variant is not covered because a
 near-miss of it is.** DEV-02's table listed the *actuator* variant of the
 per-unit claim defect (`device`/`supervised` filed without `inv`), which the

goodwe_controller/app/allocator.py

@@ -246,11 +246,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()})")

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,46 @@ 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 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 +292,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 +377,72 @@ 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
         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
+            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 +468,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 +477,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 +496,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

@@ -191,6 +191,80 @@ SETTLE_CYCLES = math.ceil(PLANT_SETTLE_DOWN_S / LOOP_TICK_S)  # 12
 # edge rather than in prose, because it is a property of two files agreeing.
 _SAT_COUNT_CAP = SETTLE_CYCLES + 1                           # 13
 
+# ---------------------------------------------------------------------------
+# SAFETY-48. HOW FAR THE INTEGRATOR MAY STAND AHEAD OF THE COMMAND.
+#
+# ⚠️ THE MISSING CASE, AND IT IS A CASE AND NOT A CONSTANT. The freeze below
+# stops the integrator accumulating, and the comment beside it says what the
+# requirement is: "the INTEGRATOR stop accumulating, not only the command". But
+# `frozen` is computed from ONE signal - `abs(prev_w - actual_w) >
+# saturation_w`, the inverter not tracking - and SLEW-LIMITING NEVER ENTERS IT.
+# When the command hits the step ceiling, the integrator goes on winding at
+# `gain * error` until it reaches `integrator_max_w`.
+#
+# The arithmetic, and it is the whole card:
+#
+#     the integrator moves   gain * error   per cycle
+#     the command moves at most      slew   per cycle
+#     so the integrator outruns the command whenever
+#
+#         |error|  >  slew / gain
+#
+# At the live install's shape (gain 0.6, slew_w 400) that is 667 W. The median
+# grid error at the onset of a recorded episode is 1114 W. This is why
+# SAFETY-39's `slew_w` retune did not fix it: a smaller step makes the
+# threshold LOWER, so the case fires more often, not less.
+#
+# ⚠️ WHAT IS BOUNDED IS THE LEAD, NOT THE INTEGRATOR. Two forms were measured
+# over 16.0 days of the live install's own recorded disturbances
+# (`tools/replay_recorded_loop.py`, and DECISIONS/SAFETY-48 has the table):
+#
+#   (a) reuse the asymmetric freeze on a carried slew flag - "may not wind
+#       further in the direction it is already pushing", exactly as saturation
+#       does. It cuts export 13 % AND RAISES THE BILLED QUANTITY: the worst
+#       quarter-hour average OFFTAKE goes 3739 -> 3935 W and the mean quarter
+#       moves +2.7 W, in five of six plant and tuning variants, and on the
+#       billed quarter it is worse at every plant lag where release/1.0
+#       produces a peak at all (a tie at lag 0, worse at 2.5/5/7.5/10 s)
+#       and at every top-N cut of the quarters.
+#
+#       ⚠️ AND THE MECHANISM IS A REDISTRIBUTION, NOT A WEAKER ANSWER. An
+#       earlier draft of this line said a frozen integrator undershoots by
+#       (1 - gain) "so a large import is answered too weakly". The aggregate
+#       does not show that: form A cuts total import by 5.45 kWh, and paired
+#       tick by tick against release/1.0 it delivers 8.56 kWh LESS offtake
+#       energy on the ticks release/1.0 was importing. What it moves is the
+#       TAIL - within quarters that already net to offtake, the worst of them
+#       gets worse - and the capacity tariff bills the worst quarter and
+#       nothing else. That is the wrong trade here and the reason this is not
+#       the fix that ships.
+#
+#   (b) cap how far the integrator may LEAD the command, one slew step. Export
+#       39.6 -> 34.1 kWh, wasted throughput 4.7 -> 3.2 kWh, sign reversals
+#       2992 -> 2770, worst quarter-hour offtake 3739 -> 3434 W at the fitted
+#       plant lag (⚠️ AND AT NO SHORTER ONE: at every lag <= 5.0 s release/1.0
+#       is already at 3434 W and this changes it by zero - DECISIONS/SAFETY-48
+#       §3a), median recovery 232 -> 199 s. It is what ships.
+#
+# ⚠️ AND THE CAP IS NOT ZERO. `i_w = slewed` is full back-calculation, and this
+# module's own docstring says what that costs: passing `i_w=None` "reduces this
+# function to the exact velocity form it replaced". A zero cap makes `i_w`
+# identically the command on every cycle, which is that same collapse written
+# from the other end - it measures 32.0 kWh, better than (b) by 2 kWh, and it
+# throws away the reason the accumulator was split out at all. One step is the
+# smallest cap that is not that.
+#
+# WHAT THE NUMBER MEANS: the command can cover a one-step lead in ONE cycle, so
+# the worst-case unwind after a reversal is one cycle instead of
+# `integrator_max_w / slew_w` - 12.5 cycles at the live shape, ~60 s at the
+# meter's measured 5.0 s tick.
+#
+# ⚠️ IT IS IN STEPS RATHER THAN IN WATTS FOR SAFETY-39's REASON, WHICH IS THE
+# REASON THIS FILE KEEPS RE-LEARNING. A watt figure is a constant that outlives
+# the `slew_w` it was derived against; expressed in steps it moves with
+# `slew_limit_w()` and therefore with the rail.
+SLEW_LEAD_STEPS = 1
+
 
 @dataclass(frozen=True)
 class Tuning:
@@ -266,6 +340,12 @@ 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
 
 
 def slew_limit_w(tuning: Tuning) -> float:
@@ -489,6 +569,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
@@ -500,6 +581,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"
 
@@ -507,6 +589,83 @@ def compute(
     slewed = max(prev_w - slew, min(prev_w + slew, target))
     if slewed != target:
         reason = "slew-limited"
+        # --- SAFETY-48: the step ceiling reaches the integrator too ---------
+        # ⚠️ INSIDE THIS BRANCH AND NOWHERE ELSE - AND THE REASON IS NOT THE
+        # SATURATION FREEZE. An earlier draft of this comment said that applied
+        # unconditionally the cap "would also pull the integrator toward a
+        # command the SATURATION freeze is pinning", and priced that at 118 of
+        # 256 250 ticks. Both halves were invented, and MUTATION.md habit 22 is
+        # what fell out of it. The 118 had been measured against a DIFFERENT
+        # pair - a band applied after quantisation, at the very end of
+        # `compute()`. On the pair the sentence actually names - this same cap
+        # moved out of this branch to just after `target = slewed` - the two
+        # forms are BIT-IDENTICAL on the shipped configuration: 0 of 256 246
+        # ticks differ over the 16-day recording. They separate only where
+        # `integrator_max_w` is deliberately set ABOVE `max_w`, the one
+        # configuration this file says can reach its `clamped` reason; there
+        # the integrator is meant to run above the rail and an unconditional
+        # cap would drag it back to the command every cycle and make the option
+        # inert. THAT is why the cap stays in the branch, and
+        # `test_telemetry.py` part 4 drives it. (The separable-state COUNT is a
+        # property of whatever grid was swept - 2050 of 257 400 on this card's,
+        # 1220 of 246 064 on the review's, 776 of 40 320 on a third - so the
+        # claim to carry forward is WHERE they separate, not how many.)
+        #
+        # ⚠️ AND THE HALF A READER WILL OTHERWISE ASSUME AWAY: THIS CAP DOES
+        # MOVE A SATURATION-FROZEN INTEGRATOR. It runs BEFORE the freeze block
+        # below and is not gated on `frozen`. Measured over the same recording
+        # at the live shape: of 79 160 frozen ticks the cap changed `i_w` on
+        # 1095 of them, and on 679 of those it moved it FURTHER OUT on the side
+        # it was already on - putting back magnitude the freeze had just let
+        # fall, which is the one direction the freeze's own rule ("may fall,
+        # never rise") exists to forbid. Worst case 2424 W, and the worked tick
+        # is `prev_w -3400 W, grid +4697 W, actual -4144 W, sat_count 2 -> 3`:
+        # the freeze leaves the integrator at -176 W, the slew binds, and the
+        # cap drags it to -2600 W. It never overrides a SAME-CYCLE refusal -
+        # the freeze clipped `moved` on 75 512 ticks and the slew bound on none
+        # of them - but it does not leave the frozen path alone either.
+        #
+        # ⚠️ AND THAT IS WHERE SAFETY-13's SETTLE VALUES WENT. Gating this cap
+        # on `not frozen` puts `test_control.py` part 5 back at release/1.0's
+        # -1190 W exactly; part 4(b)'s -2390 -> -1200 W does NOT come back,
+        # because that one moved for the other reason - the winding BEFORE the
+        # freeze is bounded now. The gate is refused anyway: measured the same
+        # way it leaves a worst observed lead of 4961 W, i.e. no bound at all
+        # on the quantity this card exists to bound. DECISIONS/SAFETY-48 §5
+        # carries the rest of the price.
+        #
+        # ⚠️ WRITTEN ONE-SIDED, AND IT IS **EQUIVALENT** TO THE TWO-SIDED BAND
+        # `max(slewed - cap, min(slewed + cap, i_w))` - MEASURED, NOT REASONED.
+        # An earlier draft of this comment claimed the two-sided spelling was a
+        # bug that would drag a TRAILING integrator up toward the command. That
+        # is false and the sweep said so: `target` is monotone in `i_w`
+        # (`target = clamp(clamp(i_w, +-limit), +-max_w)`) and `slewed` is
+        # `target` pulled toward `prev_w`, so whenever the slew binds, `i_w`
+        # lies on the same side of `slewed` as `target` does and the other
+        # clamp cannot reach. The two spellings agree on **205 920 of 205 920**
+        # cases across four tunings, every sign of `prev_w`, `grid_w`,
+        # `actual_w` and `i_w`, and the `i_w=None` path.
+        #
+        # It stays one-sided because it SAYS which side the lead is on - the
+        # side the command wanted to move and could not - and because a reader
+        # reaching for the band spelling should find the sweep rather than an
+        # argument. ⚠️ The "descending" case is NOT an exception to the rule: a
+        # command falling from +2400 W toward an integrator at +100 W has an
+        # integrator 2300 W ahead of it IN THE DIRECTION OF TRAVEL, and it is
+        # pulled back to one step beyond the emitted command exactly as a
+        # rising one is.
+        #
+        # ⚠️ `i_w` IS CHANGED AND `target` IS NOT. This cycle's command is
+        # already decided; what is bounded is what gets CARRIED. That is also
+        # why the exhaustive `i_w=None` equivalence sweep in test_control.py is
+        # untouched by this card: it compares `(target_w, sat_count, frozen,
+        # reason)`, none of which this moves, and the seeded path re-seeds from
+        # `prev_w` next cycle anyway.
+        _lead_cap = SLEW_LEAD_STEPS * slew
+        if target > slewed:
+            i_w = min(i_w, slewed + _lead_cap)
+        elif target < slewed:
+            i_w = max(i_w, slewed - _lead_cap)
     target = slewed
 
     if frozen:
@@ -589,7 +748,8 @@ def compute(
     target = round(target / step) * 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))
 
 
 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/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

@@ -175,6 +175,124 @@ only one of them is WIRED - see `BOUNDS` below and the note on SoC.
   integrator, and K. It does NOT owe a second freshness mechanism - `Freshness`
   below takes its obligation term from the caller precisely so that an energy
   integral can be handed in where command travel is handed in here.
+
+
+THE EXIT, AND WHY THE FIRST VERSION OF THIS MODULE DID NOT HAVE ONE (SAFETY-57)
+==============================================================================
+⚠️ THE VERDICT ABOVE IS ABOUT AN OBLIGATION, AND ITS OWN CONSEQUENCE REMOVES
+THE OBLIGATION. Declaring the reading stale makes `Controller.inputs_ok` False,
+which commands 0 W (§11.1 rule 1). At 0 W nothing is asking the register to be
+anywhere - `|standing| >= MOVE_W` is false, so the conjunction cannot arm - and
+the class docstring's clearing rule, "an arrival carrying a DIFFERENT number",
+asks the register for evidence that only a command could have produced. A pack
+sitting at its BMS floor answers the same integer watt for hours. **The state
+had no exit reachable from inside it**, and the operator-facing line said the
+opposite: *"It clears itself the moment the register reports a different
+value."*
+
+MEASURED ON THE LIVE SITE, 2026-09-21, and committed as
+`scenarios/safety57-2026-09-21/` - a passive RS-485 capture, decoded by
+`tools/decode_bus_capture.py`:
+
+    10:51:24.7   0x0518 reaches -3 W. The pack is at 11 % and the loop has just
+                 reversed from -447 W of charge into discharge; the BMS refuses
+                 and the inverter idles. The register is HEALTHY and TRUTHFUL.
+    10:51:29.7   the standing command reaches +1060 W. 800 W of travel, and the
+                 register is obliged to follow it.
+    10:52:00     the conjunction arms. `Inverter.batt` becomes None.
+    10:52:21.7   the site commands 0 W - on the wire, in the capture.
+    ...          0x0518 does not change value for 850.0 s. The setpoint does not
+                 change value for 790.0 s. Nothing in this add-on can end it.
+    11:04        a human restarts the add-on.
+    11:05:31.7   the restarted loop commands -400 W of charge, which the pack
+                 ACCEPTS at 11 %, and the register moves 3 s later.
+
+⚠️ AND IT HAD BEEN ESCAPING BY LUCK. This BMS emits a keep-alive pulse of a few
+hundred watts, which twitches 0x0518 and satisfies the clearing rule by
+accident. Replaying the committed 16-day loop capture
+(`scenarios/loop-2026-09-02_2026-09-17/`) through the shipped conjunction at
+1 Hz gives **93 trips**, and the time from each trip to the register's next
+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.
+
+THE RULE, and it is SAFETY-13's shape one module over - "which latches get an
+exit, not how long the block lasts":
+
+    RELEASE  <=>  the verdict is standing
+                  AND |standing command| < MOVE_W has held continuously for
+                      >= RELEASE_S
+
+On a release the latch clears and a NEW grading window opens at that instant:
+the register is re-graded, from scratch, against the commands issued AFTER it.
+Nothing about the register's own history is rewritten - `changed_mono`,
+`held` and `unchanged_s()` go on reporting that the register has not moved for
+850 s, because it has not.
+
+⚠️ `RELEASE_S` IS `BATT_OBLIGED_S`, 17.0 s, AND IT IS THE FLOOR OF ITS BAND
+RATHER THAN A PREFERENCE - the mirror of `MOVE_W` taking the ceiling of its
+own. The question the bound answers is *has the register had its chance to
+answer the command that is now standing?*, and that is exactly the 17.0 s
+already derived above: 6.0 s of plant, one 10 s publish, one 1 s read. Below it
+the release happens before the cheaper exit - the register moving by itself -
+could have occurred. Which half is safe is the opposite of SAFETY-13's, and for
+the reason that card states in its §4.2 table: being wrong LONG here is the
+failure being fixed (a site parked while it exports), and being wrong SHORT
+costs one re-grading window, which is bounded below.
+
+WHAT A RELEASE COSTS, MEASURED AND NOT ABSORBED - AND IT IS NOT SMALL. For the
+duration of the new window the consumers get the held number again, which is
+the exposure this module was written to close. Driven at the live install's
+shape against a register frozen for good (`test_freshness.py` part 10c), over
+1200 s:
+
+    shipped     parked 1166 s, the held number reaches a consumer  35 s   2.9 %
+    SAFETY-57   parked  571 s, the held number reaches a consumer 630 s  52.5 %
+
+⚠️ **52 % IS THE PRICE OF THE EXIT AND IT IS PAID EVERY CYCLE**, not an
+occasional slip. The period is the whole of `stale_input_s` (15 s) + `RELEASE_S`
+(17 s) parked, then one `BATT_UNCHANGED_S` (35 s) window of re-grading. It is
+bounded by construction, and that bound is the one thing that makes it payable:
+
+    the new window is AT MOST BATT_UNCHANGED_S = 35 s, and 35 < 75 < 85 - the
+    circulation hold and the per-unit sign hold. NEITHER CONSUMER CAN REACH A
+    VERDICT INSIDE ONE WINDOW, and a re-trip returns them a None, which CLEARS
+    both windows rather than accumulating into them.
+
+That inequality is the same one part 6 already grades, and it is why the window
+is `BATT_UNCHANGED_S` rather than a number chosen to make the table above look
+better. Neither detector can be made to say anything by a held number under
+this scheme - which is exactly the state the shipped code leaves them in as
+well, since a permanent None clears both windows for ever. **So nothing that
+SAFETY-37 detects is given back.** What the held number does reach for those
+35 s is `site_batt_w`, the anti-windup input of `control.compute()`, which
+responds to a large unexplained divergence by FREEZING the output - the
+conservative direction, and SAFETY-13's business. And the command itself is
+derived from the P1 meter, never from `batt`, so a site regulating through a
+re-grading window is regulating on the signal it always regulates on.
+
+**A register frozen under a command that never travels 250 W is still not
+detected at all** (survivor 2, unchanged), and a dead publisher whose value
+alternates is still invisible (survivor 3).
+
+⚠️ AND THE NARROWING THIS DOES NOT TAKE, named so the next card can. The live
+episode's register refused a DISCHARGE into an 11 % pack and then followed a
+CHARGE immediately; a refusal in one direction is not evidence about the other,
+and a gate that knew the pack's floor could re-grade on the first command that
+crosses it instead of on a timer. That needs SoC, which this module deliberately
+does not take (see the `soc` row), and the pack floor, which is SAFETY-32's
+number. It would shrink the 52 % above; it is not needed to give the state an
+exit, and mixing it in here would make the exit depend on a second measurement
+being right.
+
+⚠️ WHAT THIS DOES NOT DO, because the temptation is to call it a fix for the
+whole episode: it does not tell a BMS refusal apart from a dead register. The
+site above was parked for 790 s by a register that was working perfectly, and
+after this change it is parked for `stale_input_s + RELEASE_S` instead - about
+32 s on the shipped default - and then regrades. Telling the two apart needs
+the pack's own floor, which is SAFETY-32's number and not this module's input;
+the wording the operator reads about it is SAFETY-56's.
 """
 
 import time
@@ -211,6 +329,19 @@ BATT_UNCHANGED_S = 35.0
 # and goes red if the two drift.
 MOVE_W = 250.0
 
+# SAFETY-57. How long the obligation must have been ABSENT before a standing
+# verdict is withdrawn and the register re-graded. See the module docstring's
+# last section for the live episode this exists for and for which half of the
+# band is the safe one.
+#
+# ⚠️ IT IS `BATT_OBLIGED_S` AND NOT A NEW NUMBER, and that identity is the
+# derivation rather than a convenience. The question is "has the register had
+# its chance to answer the command standing NOW?", which is the same physical
+# quantity the floor of `BATT_UNCHANGED_S`'s band is: 6.0 s of plant, one 10 s
+# ESPHome publish, one 1 s add-on read. Releasing sooner would throw away the
+# cheaper exit - the register moving by itself - before it could have happened.
+RELEASE_S = BATT_OBLIGED_S   # 17.0
+
 
 @dataclass(frozen=True)
 class Bound:
@@ -219,6 +350,7 @@ class Bound:
     signal: str
     unchanged_s: float
     move_w: float
+    release_s: float
     wired: bool
     derivation: str
 
@@ -233,13 +365,19 @@ BOUNDS = {
         signal="batt (0x0518, AC power, S16, 1 W, 10 s publish)",
         unchanged_s=BATT_UNCHANGED_S,
         move_w=MOVE_W,
+        release_s=RELEASE_S,
         wired=True,
         derivation="settle 6.0 + publish 10.0 + read 1.0 = 17.0 s floor; "
-                   "circulation_hold_s 75 s ceiling; band [34.0, 37.5]"),
+                   "circulation_hold_s 75 s ceiling; band [34.0, 37.5]. "
+                   "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"),
     "soc": Bound(
         signal="soc (0x050E, pack SoC, U16, 1 %, 10 s publish)",
         unchanged_s=float("inf"),
         move_w=float("inf"),
+        release_s=float("inf"),
         wired=False,
         derivation="TEL-08. Command travel is the WRONG obligation term for "
                    "SoC - a rested pack holds a percent for hours under a 0 W "
@@ -263,10 +401,33 @@ class Freshness:
     Declaring the reading stale makes `Controller.inputs_ok` False, which
     commands 0 W (§11.1 rule 1), which drops the standing command below
     `MOVE_W`, which un-arms the conjunction, which would return the held number
-    to the consumers - and round again every read. So the ONLY thing that clears
-    the latch is an arrival carrying a DIFFERENT number, which is exactly the
-    evidence the verdict was about. A register that is working clears it on its
-    next 10 s publish; a register that is not, does not.
+    to the consumers - and round again every read. So an arrival carrying a
+    DIFFERENT number clears the latch, which is exactly the evidence the verdict
+    was about. A register that is working clears it on its next 10 s publish; a
+    register that is not, does not.
+
+    ⚠️ AND IT IS NOT THE ONLY THING THAT CLEARS IT ANY MORE (SAFETY-57), BECAUSE
+    THAT MADE THE STATE INESCAPABLE FROM INSIDE. The command the verdict itself
+    produces is 0 W, and at 0 W the register is obliged to be nowhere - so
+    "report a different value" is evidence a parked site cannot ask for. The
+    live site sat at 0 W for 790 s on 2026-09-21 with a register that was
+    working correctly, and was freed by a human. `_release()` below withdraws a
+    verdict whose obligation has been gone for `bound.release_s`, and opens a
+    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.
+
+    ⚠️ 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
+    different number. `graded_from` / `standing_at_grade` are the window the
+    VERDICT is computed over, which a release re-opens. They are the same thing
+    until the first release and diverge afterwards, and `unchanged_s()` - the
+    number an operator reads - is always the register's.
     """
 
     def __init__(self, bound: Bound):
@@ -281,10 +442,20 @@ class Freshness:
         # ability to fetch it.
         self.held = None
         self.changed_mono = None
-        # The standing command at that same instant. The conjunction compares
-        # against THIS, not against the previous cycle's command: what matters
-        # is whether the register has followed anything since it last moved.
-        self.standing_at_change = None
+        # SAFETY-57. The window the VERDICT is graded over, as opposed to the
+        # register's own history above, and the standing command at the instant
+        # it opened. The conjunction compares against THIS, not against the
+        # previous cycle's command: what matters is whether the register has
+        # followed anything since the current question was put to it. A register
+        # that moves opens a window, so until the first release these two are
+        # the change-stamps; `_release()` is where they diverge.
+        self.graded_from = None
+        self.standing_at_grade = 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
+        self.released_at = None
+        self.releases = 0
         self.stale = False
         self.reason = ""
         self.arrivals = 0
@@ -311,20 +482,67 @@ class Freshness:
         if self.changed_mono is None or value != self.held:
             self.held = value
             self.changed_mono = float(now_mono)
-            self.standing_at_change = (None if standing_w is None
-                                       else float(standing_w))
-            # Movement is the ONLY thing that clears the latch. See the class
-            # docstring on the 1 Hz oscillation this prevents.
+            self._open_window(standing_w, now_mono)
+            # Movement clears the latch, because it is exactly the evidence the
+            # verdict was about. See the class docstring on the 1 Hz oscillation
+            # the latch prevents, and `_release()` for the other way out.
             self.stale = False
             self.reason = ""
         self.last = value
+        # ⚠️ THE ORDER OF THESE TWO IS NOT OBSERVABLE, AND THIS COMMENT SAYS SO
+        # BECAUSE THE FIRST VERSION OF IT CLAIMED THE OPPOSITE. Swapping them is
+        # a ZERO-BYTE edit and it SURVIVED the battery; the reason is structural
+        # rather than a missing fixture, so no fixture could have closed it:
+        # `_grade()` acts only when `|standing| >= move_w` and `_release()` only
+        # when `|standing| < move_w`, so at most one of them can do anything on
+        # any given read, whichever runs first. Release is written first because
+        # 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._grade(standing_w, now_mono)
 
+    def _open_window(self, standing_w, now_mono) -> None:
+        """Start grading the register again, from this instant (SAFETY-57).
+
+        Called when the register moves - the window and the register's history
+        coincide there - and when a verdict is withdrawn, where they do not.
+        """
+        self.graded_from = float(now_mono)
+        self.standing_at_grade = (None if standing_w is None
+                                  else float(standing_w))
+
+    def _release(self, standing_w, now_mono) -> None:
+        """SAFETY-57. Withdraw a verdict whose obligation is no longer standing.
+
+        ⚠️ THE TIMER RUNS ON THE COMMAND, NOT ON THE VERDICT. `rested_since` is
+        maintained on every arrival, latched or not, so the elapsed rest is the
+        real one and not "time since we last looked". An obligation reappearing
+        resets it to None, which is the whole point: a site that goes back to
+        asking the register for 250 W of movement has put the question back, and
+        the verdict stands until the question is withdrawn again.
+        """
+        obliged = (standing_w is not None
+                   and abs(float(standing_w)) >= self.bound.move_w)
+        if obliged:
+            self.rested_since = None
+            return
+        if self.rested_since is None:
+            self.rested_since = float(now_mono)
+        if not self.stale:
+            return
+        if float(now_mono) - self.rested_since < self.bound.release_s:
+            return
+        self.released_at = float(now_mono)
+        self.releases += 1
+        self.stale = False
+        self.reason = ""
+        self._open_window(standing_w, now_mono)
+
     def _grade(self, standing_w, now_mono) -> None:
         """The conjunction. Sets the latch; never clears it."""
-        if self.stale or self.changed_mono is None:
+        if self.stale or self.graded_from is None:
             return
-        held_s = self.unchanged_s(now_mono)
+        held_s = self.graded_s(now_mono)
         if held_s < self.bound.unchanged_s:
             return
         # ⚠️ BOTH None GUARDS ARE FOR A CALLER THAT DOES NOT KNOW ITS OWN
@@ -333,30 +551,93 @@ class Freshness:
         # consumer today. They are here for TEL-08, whose obligation term is an
         # energy integral that has nothing to say until it has a window - and
         # "nothing to say" must withhold the verdict, not manufacture one.
-        if standing_w is None or self.standing_at_change is None:
+        if standing_w is None or self.standing_at_grade is None:
             return
         standing_w = float(standing_w)
         if abs(standing_w) < self.bound.move_w:
             return
-        moved_w = abs(standing_w - self.standing_at_change)
+        moved_w = abs(standing_w - self.standing_at_grade)
         if moved_w < self.bound.move_w:
             return
         self.stale = True
+        # ⚠️ THE SENTENCE SAYS "unchanged", SO IT GETS THE REGISTER'S OWN
+        # NUMBER, NOT THE WINDOW'S. They are the same until the first release
+        # and different afterwards, and an operator comparing this line against
+        # a history graph is reading the register.
+        shown_s = self.unchanged_s(now_mono)
+        # ⚠️ SAFETY-56. THE OBSERVATION IS A FACT, THE DIAGNOSIS WAS NOT, AND
+        # THE SENTENCE NOW STOPS WHERE THE EVIDENCE DOES. The conjunction above
+        # is satisfied by TWO disjoint worlds, and nothing this object is handed
+        # separates them:
+        #   (1) the register has stopped reporting reality - what the gate was
+        #       built for - or
+        #   (2) reality is not moving, because the SOURCE cannot comply with
+        #       the command. A pack the BMS is refusing at its floor holds
+        #       still under any setpoint, and a register reporting that
+        #       truthfully publishes the same unchanged number a dead one does.
+        # The live 2026-09-21 episode was (2) - the pack read 11 % for the
+        # whole 850 s hold, the commands were discharge-only, and the register
+        # answered the first CHARGE command within one obligation window
+        # (test_freshness.py 11a measures all three off the committed capture)
+        # - and this sentence asserted (1), which sent the operator to look at
+        # healthy hardware.
+        # Naming both is what the module can honestly say. Naming WHICH would
+        # need SoC and the pack floor - deliberately not this module's inputs
+        # (see the `soc` row in BOUNDS and the docstring's last section), and
+        # TEL-08's and SAFETY-32's numbers rather than this sentence's.
+        #
+        # ⚠️ AND IT IS NOT SHARED WITH `main.py`'s NOT READY ROW, WHICH SAYS
+        # THE SAME AMBIGUITY IN DIFFERENT WORDS ON PURPOSE. This sentence is a
+        # LOG LINE about a behaviour, quoted verbatim by `note()` onto the
+        # status page and by `_read_unit()` into the action log; that one is a
+        # BANNER about a named ENTITY, and the two answer different questions
+        # ("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.
+        # 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, 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} unchanged for {held_s:.0f} s "
-            f"while the standing command moved {moved_w:.0f} W to "
-            f"{standing_w:+.0f} W - the reading is not following, 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)")
+            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."""
+        """Seconds since an arrival carried a different number. Status page.
+
+        ⚠️ THE REGISTER'S CLOCK, NEVER THE VERDICT'S (SAFETY-57). A release
+        re-opens the grading window; it does not make the register younger, and
+        an operator reading "unchanged for 12 s" off a register that has held
+        one value for 850 s would be reading this module's bookkeeping back as a
+        measurement. `graded_s()` is the other one and is named differently for
+        that reason.
+        """
         if self.changed_mono is None:
             return None
         return max(0.0, float(now_mono) - self.changed_mono)
 
+    def graded_s(self, now_mono) -> float | None:
+        """Seconds the CURRENT verdict window has been open (SAFETY-57).
+
+        Equal to `unchanged_s()` until the first release, and shorter after one.
+        """
+        if self.graded_from is None:
+            return None
+        return max(0.0, float(now_mono) - self.graded_from)
+
     def reading(self):
         """What the consumers get: the value, or None when it cannot be trusted.
 
@@ -366,6 +647,13 @@ class Freshness:
         rather than accumulating it, and `circulation.circulating_w` returns None
         for a roster with a missing term, which clears the circulation window
         too. This module is the thing that was missing between them.
+
+        ⚠️ AND IT CAN GO BACK TO BEING A NUMBER WITHOUT THE REGISTER MOVING
+        (SAFETY-57). That is the exit, and it is bounded rather than free: the
+        window a release opens is `bound.unchanged_s` = 35 s, shorter than both
+        consumer holds (75 s and 85 s), so neither can reach a verdict inside
+        one - and a re-trip hands them a None, which CLEARS their windows. See
+        the module docstring's last section.
         """
         return None if self.stale else self.last
 
@@ -373,6 +661,26 @@ class Freshness:
         """One line for the status page. Empty when there is nothing to say."""
         return f"{unit_name}: {self.reason}" if self.stale else ""
 
+    def release_note(self, unit_name: str) -> str:
+        """SAFETY-57's release, for the log. Empty when nothing was withdrawn.
+
+        ⚠️ IT NAMES WHAT IS AND IS NOT BEING CLAIMED, because a line reading
+        "recovered" would be a lie: nothing has been learned about the register.
+        The verdict was withdrawn because it can no longer be tested, and the
+        next 35 s are the test.
+        """
+        if self.released_at is None:
+            return ""
+        return (f"{unit_name}: STALE_WITHDRAWN after the standing command sat "
+                f"below {self.bound.move_w:.0f} W for "
+                f"{self.bound.release_s:.0f} s. NOTHING HAS BEEN LEARNED ABOUT "
+                f"THE REGISTER - it is still holding {self.held:+.0f} - but a "
+                f"verdict about a command that is no longer standing cannot be "
+                f"tested, and the 0 W this one produces is what stopped it "
+                f"being tested. The register is now re-graded over a fresh "
+                f"{self.bound.unchanged_s:.0f} s window; if it still does not "
+                f"follow, this returns")
+
 
 def monotonic() -> float:
     """The clock this module's callers use, in one place so tests can find it.

goodwe_controller/app/hass.py

@@ -16,6 +16,38 @@ _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)
+
+
+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 HomeAssistant:
@@ -58,13 +90,28 @@ 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()
-                return await resp.json()
-        except (aiohttp.ClientError, TimeoutError) as err:
+                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:
             self._moan(f"read:{entity_id}", "read %s failed: %s", entity_id, err)
             return None
+        if not isinstance(obj, dict):
+            self._moan(f"shape:{entity_id}", "read %s: not a state object: %.80r",
+                       entity_id, 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."""
@@ -106,18 +153,39 @@ class HomeAssistant:
                 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.ClientError, TimeoutError) as err:
+        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",
                        domain, service, err)
             return False

goodwe_controller/app/inverter.py

@@ -123,6 +123,7 @@ 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
@@ -407,21 +408,24 @@ 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 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/mqtt.py

@@ -117,6 +117,82 @@ SENSORS = [
     ("loop_reason", "goodwe_loop_reason", "Loop reason", None, None, None, "mdi:sigma"),
 ]
 
+# --- TEL-11: rows that exist ONLY when the operator configured a source ------
+#
+# ⚠️ A SECOND LIST RATHER THAN A TENTH ENTRY IN `SENSORS`, AND THE DEFAULT IS
+# WHAT MAKES IT ONE. `SENSORS` is announced by every caller of
+# `discovery_payloads()`; `OPTIONAL_SENSORS` is announced only by a caller that
+# ASKS, so a caller that has not been taught about `pv_entity` - `test_mqtt.py`'s
+# fixtures, `tools/rehearse_roster.py`, anything written next year - announces
+# exactly what it announced before. `p1_age` solves the same problem the other
+# way round, with `omit`, because `p1_age` is announced by DEFAULT and withdrawn
+# when the meter is off; this one does not exist by default and appears when a
+# source for it does. Getting that direction wrong is the hazard `omit`'s own
+# note names: an entity that exists and is never fed is a worse signal than one
+# that does not exist at all, and MOST installs will never set `pv_entity`.
+#
+# ⚠️ `state_class: measurement` IS THE WHOLE POINT OF THE ROW. It is what puts
+# the number into the recorder's long-term statistics, and a week of statistics
+# is what OPT-10 needs to say whether the surplus that left this site was cloud,
+# a charge-power limit, or the optimiser declining to charge.
+OPTIONAL_SENSORS = [
+    ("pv", "goodwe_pv_power", "PV power", "W", "power", "measurement", None),
+]
+
+# ⚠️ HA's OWN "this sensor has no value" PAYLOAD, and the one place this add-on
+# spells it. `homeassistant/components/mqtt/const.py` declares
+# `PAYLOAD_NONE = "None"` and `mqtt/sensor.py` tests it BEFORE the numeric
+# branch - `if payload == PAYLOAD_NONE: self._attr_native_value = None` - so the
+# entity's state becomes `unknown` rather than a number. (Read out of
+# github.com/home-assistant/core `dev` on 2026-09-24; the shipped MQTT-sensor
+# documentation says the same thing in its `state_topic` entry: "a 'None' value
+# will set the sensor to an unknown state".)
+PAYLOAD_NONE = "None"
+
+# The keys whose ABSENCE MUST BE PUBLISHED rather than skipped. ⚠️ THIS IS THE
+# DIFFERENCE BETWEEN "no PV reported" AND "PV reported 0 W" IN A WEEK OF
+# HISTORY, AND WITHOUT IT THE CHANNEL LIES IN THE WORSE DIRECTION. `publish()`
+# below drops a `None` - which is right for `circulation`, where the last figure
+# standing is better than a zero that reads as health - but a DROPPED pv row
+# leaves Home Assistant holding the last number it was told, forever, and the
+# recorder then draws a flat line at that value through an outage. Someone
+# reading it back would conclude the sun was not shining, which is precisely the
+# conclusion this card exists to TEST rather than to manufacture.
+ABSENT_AS_UNKNOWN = frozenset({"pv"})
+
+
+def optional_keys(opts: dict) -> tuple:
+    """Which `OPTIONAL_SENSORS` rows this configuration has a source for.
+
+    ⚠️ ONE ANSWER TO "IS THE PV ROW LIVE", read by the ANNOUNCEMENT (through
+    `MqttPublisher`) and by `Controller.publish()`. `announced_units()` above
+    exists for exactly this reason and says it in full: two spellings of one
+    predicate is how an entity gets announced that nothing feeds, or fed on a
+    topic nothing announced.
+
+    ⚠️ AND SINCE TEL-12 IT IS `pv.entities()` RATHER THAN A SECOND READING OF
+    THE OPTION - `Controller.pv_roster` is the SAME call. TEL-11 got away with
+    two spellings because both were `bool()` of one string; with `pv_entities`
+    beside `pv_entity`, and `pv_entities` REPLACING it, a second spelling is how
+    the row gets announced off one key and summed off the other. ⚠️ THE ROW IS
+    ONE SITE TOTAL AT EVERY ROSTER SIZE: there is deliberately no per-entity
+    topic, because the recorder statistic OPT-10 reads back is the site figure
+    and a per-inverter breakdown is a dashboard question the operator's own PV
+    integration already answers.
+    """
+    # ⚠️ THE IMPORT IS FUNCTION-LOCAL AND THAT IS NOT A STYLE CHOICE. This
+    # module is EXEC'D STANDALONE, outside its package, by `test_mqtt.py`
+    # part 8's mutation harness - which says so in its own comment, and whose
+    # honesty depends on it ("`app/mqtt.py` imports nothing from this package,
+    # which is what makes exec'ing it standalone honest rather than a stub").
+    # A module-scope `from . import pv` turns that whole instrument into an
+    # `ImportError` before it grades anything. `tools/tel11_pv_trace.py`'s
+    # `_load()` is the same decision for the same kind of reason. Measured, not
+    # assumed: move this line to module scope and test_mqtt.py part 8 dies.
+    from . import pv as _pv
+    return ("pv",) if _pv.entities(opts) else ()
+
+
 BASE = "goodwe_ctl"
 AVAILABILITY = f"{BASE}/availability"
 
@@ -299,15 +375,23 @@ def _payload(name, object_id, unique_id, state_topic, device,
     return cfg
 
 
-def discovery_payloads(units=(), omit=()) -> list:
+def discovery_payloads(units=(), omit=(), include=()) -> list:
     """Every `(topic, payload)` this add-on announces, in announcement order.
 
     Split out of `_announce()` so that the acceptance criterion can be graded as
     a DIFF OF THE ANNOUNCED PAYLOADS against `release/1.0`, rather than as a
     reading of the code. `_announce()` publishes exactly this list and nothing
     else, which is itself checked.
+
+    `include` names `OPTIONAL_SENSORS` keys to announce. ⚠️ IT DEFAULTS TO
+    NOTHING AND THE ROWS GO LAST, so no existing row's POSITION moves under any
+    configuration - not the site rows, not the per-unit ones. Order is part of
+    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).
     """
     omit = set(omit)
+    include = [k for k in include if k not in omit]
     out = []
     for key, object_id, name, unit, dev_class, state_class, icon in SENSORS:
         if key in omit:
@@ -336,12 +420,19 @@ def discovery_payloads(units=(), omit=()) -> list:
                          unique_id,
                          f"{BASE}/{unit_state_key(slug, key)}",
                          device, unit, dev_class, state_class, icon)))
+    for key, object_id, name, unit, dev_class, state_class, icon in OPTIONAL_SENSORS:
+        if key not in include:
+            continue
+        out.append((
+            f"homeassistant/sensor/{BASE}_{key}/config",
+            _payload(name, object_id, f"{BASE}_{key}", f"{BASE}/{key}",
+                     DEVICE, unit, dev_class, state_class, icon)))
     return out
 
 
 class MqttPublisher:
     def __init__(self, host, port, username=None, password=None, omit=(),
-                 units=()):
+                 units=(), include=()):
         # `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
@@ -353,6 +444,10 @@ class MqttPublisher:
         # per-unit is announced, so every caller that has not been taught about
         # the roster keeps publishing what it published before.
         self.units = [str(u) for u in units]
+        # TEL-11. `mqtt.optional_keys(opts)` - the shipped predicate, not a
+        # 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]
         self.enabled = mqtt is not None and bool(host)
         self.client = None
         if not self.enabled:
@@ -389,7 +484,8 @@ class MqttPublisher:
         # announcement, so the check that diffs it against `release/1.0` is
         # 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):
+        for topic, cfg in discovery_payloads(self.units, self.omit,
+                                             self.include):
             self.client.publish(topic, json.dumps(cfg), retain=True)
         self.client.publish(AVAILABILITY, "online", retain=True)
 
@@ -399,7 +495,16 @@ class MqttPublisher:
         try:
             for key, value in values.items():
                 if value is None:
-                    continue
+                    # ⚠️ TEL-11. A DROPPED ROW IS NOT AN ABSENT ROW. Skipping
+                    # leaves Home Assistant holding the last value it was told,
+                    # which is what `circulation` wants (its note in main.py
+                    # says why) and is exactly wrong for a measurement somebody
+                    # will read back as history: a flat line at the last number
+                    # is indistinguishable from a real one. See
+                    # `ABSENT_AS_UNKNOWN`.
+                    if key not in ABSENT_AS_UNKNOWN:
+                        continue
+                    value = PAYLOAD_NONE
                 self.client.publish(f"{BASE}/{key}", str(value))
         except OSError as err:  # pragma: no cover
             _LOG.debug("MQTT publish failed: %s", err)

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

@@ -395,33 +395,34 @@ not need re-testing. Nothing here indexes a phase.
 
 from dataclasses import dataclass
 
+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"
 
@@ -485,17 +486,29 @@ class PeakDecision:
     reason: str = ""
 
     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.
 
@@ -553,8 +566,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
 
 
@@ -730,9 +744,9 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         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)"))
+            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:
@@ -794,17 +808,18 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
             ceiling_from=from_where, 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}), and {wanted:+.0f} W from the battery would "
+                f"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
@@ -813,13 +828,15 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         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}), 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 "")))
 
 
 def charge_headroom_w(decision) -> float | None:

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

@@ -0,0 +1,274 @@
+"""TEL-11/TEL-12 - the site's PV production, read from Home Assistant entities.
+
+WHY THIS IS AN ENTITY AND NOT A REGISTER. This add-on's RS485 bus carries the
+BATTERY inverter it drives. A household's PV inverter is, on nearly every site,
+a different box from a different vendor that reports into Home Assistant
+through its own integration - so the only place a product can read production
+for an arbitrary install is an HA entity. `pv_entities` therefore takes whatever
+`sensor.*` the site's own PV integration provides.
+
+⚠️ AND THERE IS USUALLY MORE THAN ONE OF THEM, WHICH IS TEL-12. TEL-11 shipped
+`pv_entity` as a single string and the owner of the reference site reported
+within minutes of 0.11.0 going live that they have SEVERAL PV inverters and
+could configure one. That is not a property of one house: a multi-string or
+multi-orientation roof routinely carries two or three inverters, each
+publishing its own power sensor. `entities()` below is the roster and `total()`
+is the site figure over it.
+
+⚠️ AND A PARTIAL TOTAL IS WORSE THAN NO TOTAL, WHICH IS THE WHOLE OF TEL-12.
+Three inverters configured, one `unavailable`, and the sum of the other two is A
+SMALLER NUMBER INDISTINGUISHABLE FROM A REAL ONE. Fed into OPT-10's attribution
+that reads as "there was less PV than there was" - which is the "no irradiance"
+conclusion the card exists to TEST rather than to manufacture. So `total()`
+answers `None` the moment ANY configured entity is absent. See the note on
+`total()` for the alternative that was weighed and why it lost.
+
+WHY THE CHANNEL EXISTS AT ALL. OPT-10 measured that 20.5 kWh of surplus left the
+site in 16 days while the pack had room, 12.6 kWh of it with the battery not
+charging at all - and could not say WHY, because PV production is recorded
+NOWHERE. Three causes need three different fixes (no irradiance: nothing to fix;
+a charge-power limit; the optimiser declining to charge - the only software
+defect), and guessing between them is how an optimiser gets tuned to solve a
+cloud problem. This module is the missing measurement and NOTHING ELSE.
+
+⚠️ NOTHING HERE MAY EVER REACH A CONTROL DECISION, AND THAT IS THE CARD'S FIRST
+CONSTRAINT RATHER THAN A STYLE NOTE. The add-on regulates a real battery; adding
+production as a term of the control law would be an unrequested behaviour change
+AND it would destroy the measurement, because the loop would then be reacting to
+the quantity being measured. `tools/tel11_pv_trace.py` is what says the path is
+untouched: it grades a control document that contains none of this material on
+both trees and with `pv_entity` set and unset.
+
+⚠️ ABSENCE IS NEVER ZERO, AND THAT IS THE SECOND CONSTRAINT. Every refusal below
+returns `None` with a REASON, never `0.0`. A PV channel that reported 0 W for a
+dead sensor would manufacture exactly the "there was no surplus to store"
+conclusion the card exists to TEST - and it would do it silently, in a week of
+recorder history nobody would re-derive. `app/hass.py`'s own note on `state()`
+is the same rule one layer down. ⚠️ TEL-12 EXTENDS THAT RULE RATHER THAN
+WEAKENING IT: at a roster of three, "one of them is absent" is an absence of the
+SITE figure, and it publishes as an absence. A partial sum is a second way of
+reporting 0-where-there-was-production, one layer up, and it is refused for the
+same reason.
+
+THE SIGN CONVENTION: POSITIVE IS PRODUCTION, as for `meter_entity` and
+`batt_entity` ("power arriving at the house's AC bus"). TEL-14: a kWh meter or
+power clamp in the PV circuit reads the other way, so `pv_invert_entities`
+flips the sign per entity. See `DECISIONS/TEL-14-pv-sign.md`.
+"""
+
+from .hass import BAD_STATES
+
+# Home Assistant's OWN power units, each as the number of watts one of it is.
+# ⚠️ READ OUT OF HA, NOT LISTED FROM MEMORY: `UnitOfPower` in
+# `homeassistant/const.py` (github.com/home-assistant/core, `dev`, retrieved
+# 2026-09-24) declares mW, W, kW, MW, GW, TW and BTU/h. Every factor here is an
+# exact power of ten, so none of them is a number anybody chose.
+#
+# ⚠️ BTU/h IS IN HA's ENUM AND DELIBERATELY NOT HERE. Its factor (0.293071…)
+# is a measured conversion rather than a decimal shift, no PV integration
+# publishes in it, and a wrong constant in the one channel that exists to
+# attribute a 20.5 kWh shortfall is worse than a refusal an operator can read.
+# It lands in the "not a power unit" refusal below, BY NAME.
+WATTS_PER = {
+    "mW": 0.001,
+    "W": 1.0,
+    "kW": 1000.0,
+    "MW": 1000000.0,
+    "GW": 1000000000.0,
+    "TW": 1000000000000.0,
+}
+
+# What `watts()` answers when there is nothing to report. ⚠️ THE REASON IS PART
+# OF THE RETURN VALUE, not a log line: it is what the status page prints, and an
+# absence whose cause is invisible sends an operator to look at the wrong box.
+UNIT_KEY = "unit_of_measurement"
+
+
+def watts(state: dict | None) -> tuple:
+    """`(watts, why)` from a Home Assistant state object.
+
+    `watts` is `None` whenever there is no reading - and `why` then says which
+    of the five refusals it was, in words an operator can act on. On a good read
+    `why` is the unit the value was read in, because "1234 W" and "1234, unit
+    unknown" are different claims and the page has to be able to make the first.
+
+    ⚠️ THE UNIT IS READ OFF THE ENTITY AND NOT ASSUMED, AND THERE IS NO
+    MAGNITUDE HEURISTIC. `read_inputs()` guesses kW-or-W for
+    `peak_forecast_entity` with `abs(raw) < 50`, which is safe there because
+    nobody's quarter-hour demand forecast is 50 W. It is NOT safe here: 30 W of
+    real production at dusk is an ordinary reading, and that heuristic would
+    publish it as 30 kW - a fabricated number, in the channel whose entire
+    purpose is to be believed a week later. A sensor whose unit this cannot read
+    is REFUSED rather than guessed at.
+    """
+    if state is None:
+        # `hass.state()` answers None for a non-existent entity, a 404 and a
+        # transport failure alike. All three are "no reading", and HA does not
+        # consider a non-existent entity an error - see `hass.state()`.
+        return None, "no state (entity missing, or the read failed)"
+    raw = str(state.get("state", "")).strip()
+    if raw.lower() in BAD_STATES:
+        # ⚠️ THE SAME LIST `hass.number()` REFUSES ON, IMPORTED RATHER THAN
+        # RESPELLED. A second copy of it is how one path starts treating
+        # `unavailable` as a number the other one rejects.
+        return None, f"entity is {raw or 'empty'}"
+    try:
+        value = float(raw)
+    except ValueError:
+        return None, f"state {raw!r} is not numeric"
+    unit = str((state.get("attributes") or {}).get(UNIT_KEY) or "").strip()
+    if not unit:
+        return None, ("no unit_of_measurement on the entity - it cannot be "
+                      "read in watts")
+    if unit not in WATTS_PER:
+        return None, (f"unit {unit!r} is not one of "
+                      f"{', '.join(WATTS_PER)} - it cannot be read in watts")
+    return value * WATTS_PER[unit], unit
+
+
+# --- TEL-12: the ROSTER, and the SITE figure over it --------------------------
+
+def entities(opts: dict) -> tuple:
+    """Every PV entity this configuration names, in configured order. TEL-12.
+
+    ⚠️ ONE ANSWER TO "WHICH ENTITIES ARE THE PV CHANNEL", and it is the answer
+    BOTH sides read. `Controller.pv_roster` is this call and
+    `mqtt.optional_keys()` is `bool()` of this call, so the thing that decides
+    whether the row is ANNOUNCED, the thing that decides whether it is READ and
+    the thing that decides HOW MANY entities are summed cannot disagree. TEL-11
+    already had that discipline for one entity and spelled the predicate TWICE
+    - `str(opts.get("pv_entity") or "").strip()` in `main.py` and again in
+    `mqtt.py`. Two spellings of one predicate is how an entity gets announced
+    that nothing feeds; a roster makes it how a SUM gets taken over a different
+    list from the one that was announced. It is one function now.
+
+    ⚠️ `pv_entities` REPLACES `pv_entity` RATHER THAN EXTENDING IT, and that is
+    CFG-04's shipped precedent (`inverters:` replaces the six flat keys) applied
+    to the only upgrade path that matters. The install this card exists for HAS
+    `pv_entity` set, to inverter A. Opening the Configuration tab, the natural
+    action is to put ALL the inverters in the new repeatable field - and under a
+    UNION rule that double-counts A unless the operator also remembers to clear
+    the old key. A doubled total is the same defect as a partial one in the
+    other direction, in the one channel that exists to be believed a week later.
+    Under REPLACE the effective roster is exactly what one key says, and no
+    arithmetic depends on a de-duplication rule the operator has to know about.
+    ⚠️ `Controller.checks()` says WHICH key is in use whenever both are set, so
+    the replacement is stated on the page rather than being silent.
+
+    ⚠️ AND IT DE-DUPLICATES WITHIN THE LIST, ORDER PRESERVED. A site cannot have
+    two sensors with one entity_id, so a repeated id in the list is never a
+    second inverter - it is a typo that would DOUBLE that inverter's production
+    in the total. `dict.fromkeys` is the order-preserving spelling.
+    """
+    listed = [e for e in (str(x or "").strip()
+                          for x in (opts.get("pv_entities") or [])) if e]
+    if listed:
+        return tuple(dict.fromkeys(listed))
+    one = str(opts.get("pv_entity") or "").strip()
+    return (one,) if one else ()
+
+
+def entity_is_ignored(opts: dict) -> bool:
+    """Is a set `pv_entity` being REPLACED by a set `pv_entities`? TEL-12.
+
+    ⚠️ HERE RATHER THAN IN `Controller.checks()`, for the reason `entities()`
+    exists: the rule and the sentence that reports the rule must not be two
+    readings of the options. This is the negative half of `entities()`' first
+    branch and it is spelled once, beside it, where an edit to one is in front
+    of whoever is editing the other.
+    """
+    return bool(str(opts.get("pv_entity") or "").strip()
+                and [x for x in (opts.get("pv_entities") or [])
+                     if str(x or "").strip()])
+
+
+def inverted(opts: dict) -> frozenset:
+    """The entity ids `pv_invert_entities` flips. TEL-14."""
+    return frozenset(e for e in (str(x or "").strip()
+                                 for x in (opts.get("pv_invert_entities") or []))
+                     if e)
+
+
+def stray_inverts(opts: dict) -> list:
+    """`pv_invert_entities` entries naming no entity in the roster - a typo
+    that would otherwise leave a sign unflipped with nothing said. TEL-14."""
+    roster = set(entities(opts))
+    return sorted(e for e in inverted(opts) if e not in roster)
+
+
+# TEL-14: a reading below this is not standby draw. A correctly signed meter in
+# the PV circuit reads a few watts NEGATIVE at night (the owner's: 13 W); -50 W
+# clears that with room for a couple of such devices on one entity, while a
+# reversed sensor in daylight reads hundreds to thousands of watts below zero.
+NEGATIVE_W = -50.0
+
+
+def total(readings, flip=frozenset()) -> tuple:
+    """`(watts, why, parts)` - the SITE's production, or an ABSENCE. TEL-12.
+
+    `readings` is `[(entity_id, state), ...]` in `entities()` order, one entry
+    per configured entity, each `state` shaped as `hass.state()` returns.
+
+    `parts` is `[(entity_id, watts, why), ...]` - EVERY entity's own answer from
+    `watts()`, kept because the operator surfaces have to be able to name which
+    sensor is missing. `watts` is the sum when every entity answered, and `None`
+    otherwise; `why` always says which of those it was, in words a status page
+    can print.
+
+    ⚠️ ONE OR MORE ABSENT -> THE TOTAL IS ABSENT. NOT THE PARTIAL SUM. This is
+    the decision the card turns on and it was taken deliberately against the
+    alternative, which was to publish the partial sum ALONGSIDE a count of how
+    many entities contributed. Both are defensible; this one wins on the ONE
+    question that matters, which is who reads the number and when:
+
+      * the MQTT row is read back COLD, a week later, by OPT-10's attribution
+        and by whatever plots `sensor.goodwe_pv_power` over that week. A partial
+        sum there is a smaller number indistinguishable from a real one, and the
+        count that would have qualified it lives in a SECOND entity with its own
+        history - so believing the total requires joining two recorder series by
+        timestamp to find out which samples to distrust. Nobody re-derives that,
+        which is the same "nobody will re-derive it" TEL-11's note names. And it
+        is worse than a gap in exactly the direction that matters: a gap makes
+        the attribution say "I do not know", a partial sum makes it say "there
+        was less sun than there was".
+      * the STATUS PAGE is read LIVE, by a human, who wants the diagnostic. So
+        the partial information is not thrown away - `Controller.checks()` names
+        every entity that DID report, with its watts, and every one that did
+        not, with its reason, in a row that states plainly that there is no site
+        total. Different reader, different instant, different rule.
+
+    A count published beside the total would also carry no information in the
+    state this function actually admits: the total is published ONLY when every
+    entity contributed, so the count would be the constant `len(parts)`.
+
+    ⚠️ AND `0 W` IS STILL A READING AT EVERY ROSTER SIZE - the test is
+    `watts is None`, never falsiness. An inverter honestly reporting 0 W at dusk
+    beside two that are producing must give the SUM of the three, not blank the
+    site: shading, a tripped string and nightfall are all real 0s, and a roster
+    that went to `unknown` whenever one member read zero would report an absence
+    on every clear evening and defeat the channel from the other end.
+
+    ⚠️ TEL-14: `flip` is `inverted(opts)`; each member's sign is applied HERE,
+    before the sum, so every surface reads the corrected figure. `0.0 - w`
+    rather than `-w`, so a flipped 0 W is `0.0` and never `-0.0` on the wire.
+    """
+    parts = [(ent, w if w is None or ent not in flip else 0.0 - w, why)
+             for ent, (w, why) in ((e, watts(st)) for e, st in readings)]
+    if not parts:
+        # No roster. `Controller` does not call this in that state - the gate is
+        # `pv_roster` - but a reader of `parts` should never have to wonder.
+        return None, "not configured", parts
+    if len(parts) == 1:
+        # ⚠️ AT ONE ENTITY THIS IS `watts()` AND NOTHING ELSE: the same value
+        # and the SAME `why` string, passed through rather than re-composed, so
+        # 0.11.0's single-entity surfaces are byte-identical rather than
+        # similar. `tools/tel11_pv_trace.py` grades that identity across trees.
+        return parts[0][1], parts[0][2], parts
+    missing = [(ent, why) for ent, w, why in parts if w is None]
+    if missing:
+        return None, (
+            f"only {len(parts) - len(missing)} of {len(parts)} entities are "
+            f"reporting and a partial sum would understate production: "
+            + "; ".join(f"{ent} - {why}" for ent, why in missing)), parts
+    return (sum(w for _e, w, _y in parts),
+            f"{len(parts)} entities", parts)

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
@@ -381,8 +382,9 @@ async def save(selfcfg: SelfConfig, proposed: dict, expect: str, *,
     """
     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,8 +392,8 @@ 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",
+        _LOG.warning("The settings page did not save, because the settings "
+                     "changed while it was open (keys: %s).",
                      ", ".join(changed) or "none this page also edited")
         raise SaveRefused("stale", changed=changed, stored=stored)
 

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/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,8 +576,8 @@ 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
 
 

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

goodwe_controller/app/validate.py

@@ -322,6 +322,7 @@ WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
 
 import logging
 
+from . import messages
 from .arbitrage import enabled as arbitrage_on
 from .control import SLEW_RAIL_FRAC, LOOP_TICK_S, PLANT_SETTLE_S
 from .custom_formula import (
@@ -342,6 +343,30 @@ from .watchdog import SIGN_OPTION_DEFAULTS
 
 _LOG = logging.getLogger("goodwe.config")
 
+
+class _WarnOnce(logging.Filter):
+    """UX-10: a settings warning is said once per start. The validator runs
+    twice at start (before the first cycle and again once the inverter's range
+    is known), and a warning about options that have not changed is the same
+    news both times. Refusals are ERROR and pass untouched."""
+
+    def __init__(self):
+        super().__init__()
+        self.seen = set()
+
+    def filter(self, record):
+        if record.levelno != logging.WARNING:
+            return True
+        text = record.getMessage()
+        if text in self.seen:
+            return False
+        self.seen.add(text)
+        return True
+
+
+WARN_ONCE = _WarnOnce()
+_LOG.addFilter(WARN_ONCE)
+
 # ⚠️ A MIRROR OF A FIRMWARE CONSTANT, AND IT CANNOT BE IMPORTED. The firmware
 # threshold is a compile-time YAML substitution baked into the ESP32 image
 # (`max_age_s: "30"`, master/goodwe-master-stage4-failsafe.yaml), so nothing at
@@ -571,6 +596,17 @@ def _unit_label(opts: dict, index: int) -> str:
     return f" ({name or f'inverters[{index}]'})"
 
 
+def S(key: str, where: str = "") -> str:
+    """A setting as a refusal names it; `where` is `_unit_label()`'s " (name)"."""
+    return messages.setting(key, where.strip().strip("()"))
+
+
+def _labels(keys, joiner: str = "and") -> str:
+    """Several settings, each with its key: the config panel files a refusal
+    under every key it names (`configui.problems_by_field()`)."""
+    return f" {joiner} ".join(S(k) for k in keys)
+
+
 def _roster_problems(opts: dict) -> list[str]:
     """Rule 9 (CFG-04): the `inverters:` roster, refused where it cannot mean
     what it says.
@@ -625,11 +661,9 @@ def _roster_problems(opts: dict) -> list[str]:
     if raw is None or raw == "" or raw == []:
         return problems
     if not isinstance(raw, (list, tuple)):
-        return [f"inverters is {type(raw).__name__} {raw!r}, and it must be a "
-                "LIST of inverter objects - one per inverter, each naming its "
-                "own name, setpoint_entity and max_w. A single inverter needs "
-                "no list at all: leave `inverters` empty and the flat "
-                "setpoint_entity/soc_entity/batt_entity/max_w keys describe it."]
+        return [f"{S('inverters')} is {type(raw).__name__} {raw!r}, not a list. "
+                "Add one entry per inverter, or leave it empty for a single "
+                "inverter."]
 
     entries = roster_entries(opts)
     seen: dict = {}
@@ -637,45 +671,31 @@ def _roster_problems(opts: dict) -> list[str]:
         where = f"inverters[{i}]"
         if not isinstance(entry, dict):
             problems.append(
-                f"{where} is {type(entry).__name__} {entry!r}, and every entry "
-                "must be an object with at least name, setpoint_entity and "
-                "max_w.")
+                f"{where} in the “Inverter list” is {messages.shown(entry)}. Each entry needs "
+                "a name, a setpoint entity and an inverter rating.")
             continue
         name = str(entry.get("name") or "").strip()
         if not name:
             problems.append(
-                f"{where} has no name. Every inverter needs one: the Store "
-                "namespaces this unit's SAFETY-02 latch, its heartbeat and its "
-                "write bookkeeping under it, so two unnamed units would share "
-                "one namespace and a trip caused by one would latch the other. "
-                "Any short identifier works - inverter-a, inverter-b, garage.")
+                f"{where} in the “Inverter list” has no name. Give every "
+                "inverter a short name, for example inverter-a.")
         elif name in seen:
             problems.append(
-                f"{where} and {seen[name]} are both called {name!r}. The Store "
-                "keys every per-unit latch under the unit's name, so two units "
-                "with one name share one SAFETY-02 latch and one heartbeat "
-                "deadline - a trip caused by either would stop both, and an "
-                "operator clearing it would clear both. Give them different "
-                "names.")
+                f"{where} and {seen[name]} are both called {name!r}. Give every "
+                "inverter its own name.")
         else:
             seen[name] = where
         who = f"{where} ({name})" if name else where
         if not str(entry.get("setpoint_entity") or "").strip():
             problems.append(
-                f"{who} has no setpoint_entity, so this add-on cannot command "
-                "it. It would sit in the roster, take a share of the site "
-                "target every cycle and deliver none of it, while the status "
-                "page showed a site running at full strength. Give it the "
-                "ESPHome number entity that carries ITS setpoint, or remove "
-                "the entry.")
+                f"{who} has no {S('setpoint_entity')}, so the add-on cannot "
+                "control it. Set its ESPHome number entity, or remove the "
+                "entry.")
         if _number(entry, "max_w", None) is None or (_number(entry, "max_w", None) or 0) <= 0:
             problems.append(
-                f"{who} has no usable max_w (got {entry.get('max_w')!r}). It is "
-                "the supervised cap on what may be written to THIS inverter, it "
-                "is not shared with any other unit and it is deliberately not "
-                "inherited from the flat max_w - a rating borrowed from a "
-                "sibling is exactly what DEV-02 removed. State this unit's own "
-                "rating in watts.")
+                f"{who} has no usable {S('max_w')}: it is "
+                f"{messages.shown(entry.get('max_w'))}. Set this inverter's own rating in "
+                "watts.")
 
     # --- (f) and (g): OPT-09's capacity, which is optional but not partial ---
     stated, blank = [], []
@@ -694,35 +714,21 @@ def _roster_problems(opts: dict) -> list[str]:
             val = None
         if val is None or not (val > 0.0):
             problems.append(
-                f"{who} has capacity_kwh {raw!r}, which is not a usable number "
-                "of kilowatt-hours. It is THIS pack's usable capacity and it is "
-                "read to weight the split of the site target by ENERGY headroom "
-                "rather than by power rating; a zero or an unparseable value is "
-                "a pack the split would quietly stop preferring while the box "
-                "still shows a value. State it in kWh, or leave it empty on "
-                "every entry.")
+                f"{who} has {S('capacity_kwh')} {messages.shown(raw)}, which is not a usable "
+                "number. Set it in kWh, or leave it empty on every inverter.")
         else:
             stated.append(who)
     if stated and blank:
         problems.append(
-            f"capacity_kwh is stated on {', '.join(stated)} and left empty on "
-            f"{', '.join(blank)}. It is OPTIONAL but it is not PARTIAL: the "
-            "split weights one pack's energy headroom against another's, so a "
-            "pack measured in kWh beside a sibling that weighs a dimensionless "
-            "1.0 is not a comparison - the add-on answers 'no opinion' for the "
-            "whole roster and the value you filled in changes nothing. State a "
-            "capacity for every inverter, or for none of them.")
+            f"{S('capacity_kwh')} is set on {', '.join(stated)} but empty on "
+            f"{', '.join(blank)}. Set it on every inverter, or on none.")
 
     flat_sp = str(opts.get("setpoint_entity") or "").strip()
     if entries and flat_sp:
         problems.append(
-            f"setpoint_entity is set to {flat_sp} AND an inverters list of "
-            f"{len(entries)} is declared. The flat setpoint_entity/soc_entity/"
-            "batt_entity/max_w keys are the SINGLE-inverter shape and are not "
-            "read at all once a roster exists, so this config declares an "
-            "actuator that nothing will ever write - a site running quietly "
-            "smaller than its own configuration. Move that inverter into the "
-            "list as its own entry and clear setpoint_entity.")
+            f"{S('setpoint_entity')} is set to {flat_sp}, but the "
+            f"{S('inverters')} is also filled in. Move that inverter into the "
+            "list and clear this setting.")
     return problems
 
 
@@ -760,17 +766,14 @@ def validate_unit_ranges(units, *, skip_entity: str = "") -> list[str]:
         name = getattr(unit, "name", entity)
         if dev_max is not None and cap > float(dev_max):
             problems.append(
-                f"{name}: max_w is {cap:.0f} W but {entity} accepts at most "
-                f"{float(dev_max):.0f} W - THE DEVICE WINS, so the {cap:.0f} W "
-                f"configured for this inverter would silently never happen. "
-                f"Lower this entry's max_w to {float(dev_max):.0f} W or less.")
+                f"{name}: {S('max_w')} is {cap:.0f} W, but {entity} accepts at "
+                f"most {float(dev_max):.0f} W. Lower this inverter's rating to "
+                f"{float(dev_max):.0f} W or less.")
         elif dev_min is not None and -cap < float(dev_min):
             problems.append(
-                f"{name}: max_w is {cap:.0f} W, so this controller may command "
-                f"{-cap:.0f} W, but {entity} accepts no less than "
-                f"{float(dev_min):.0f} W - THE DEVICE WINS on the charge side. "
-                f"Lower this entry's max_w to {abs(float(dev_min)):.0f} W or "
-                "less.")
+                f"{name}: {S('max_w')} is {cap:.0f} W, but {entity} accepts no "
+                f"less than {float(dev_min):.0f} W when charging. Lower this "
+                f"inverter's rating to {abs(float(dev_min)):.0f} W or less.")
     return problems
 
 
@@ -803,11 +806,8 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     writers = actuator_writers(opts)
     if not writers:
         problems.append(
-            "setpoint_entity is not set, so this add-on has no actuator: every "
-            "write is a no-op, the device's own rating is never read, and the "
-            "ESP32 heartbeat that holds off the layer-1 failsafe never happens. "
-            "It would run, look healthy, and move no energy at all. Set it to "
-            "the ESPHome number entity that carries the setpoint.")
+            f"{S('setpoint_entity')} is empty, so the add-on cannot control the "
+            "inverter. Set it to the ESPHome number entity for the setpoint.")
     # 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.
@@ -822,15 +822,9 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     for actuator, who in sorted(writers.items()):
         if len(who) > 1:
             problems.append(
-                f"{len(who)} configured writers can reach the one actuator "
-                f"{actuator}: {', '.join(who)}. specs §1.5 makes any "
-                "configuration in which two writers can reach one actuator a "
-                "non-goal - two independent setpoints on one inverter is the "
-                "arbitration problem this add-on refuses to have, and at "
-                "runtime it is a meter-emulation target being written twice a "
-                "second by two strategies that cannot see each other. Give "
-                "each actuator exactly one writer, or point the second one at "
-                "its own entity.")
+                f"{len(who)} settings point at the same inverter entity "
+                f"{actuator}: {', '.join(who)}. Give each inverter its own "
+                "setpoint entity.")
 
     # --- 9. CFG-04's roster, graded BEFORE anything reads a per-unit number --
     # ⚠️ FIRST, THOUGH IT IS THE NEWEST RULE. Rules 5 and 6 below now ask the
@@ -861,7 +855,8 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     # has answered; it is not called from here because at startup no device has.
     max_w = _number(opts, "max_w", 2000.0)
     if max_w is None:
-        problems.append(f"max_w {opts.get('max_w')!r} is not a number")
+        problems.append(f"{S('max_w')} is {messages.shown(opts.get('max_w'))}, which is not "
+                        "a number. Set it in watts.")
     # ⚠️ config.yaml's int(100,5000) already blocks this on a real install, so
     # the check is not for the Supervisor path - it is because
     # validate_startup_config() is now also sim/inject.py's entry point and can
@@ -872,24 +867,19 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     # nonsense config it is.
     elif max_w <= 0:
         problems.append(
-            f"max_w is {max_w:.0f} W and must be positive - it is a magnitude, "
-            "not a signed setpoint. At or below zero the arbiter's supervised "
-            f"limit becomes lo={-max_w:.0f} / hi={max_w:.0f}, which is a "
-            "contradiction it resolves to 0 W, so the controller would look "
-            "like it was tripping rather than misconfigured.")
+            f"{S('max_w')} is {max_w:.0f} W. Set it above 0 W.")
     elif dev_max is not None and max_w > dev_max:
         problems.append(
-            f"max_w is {max_w:.0f} W but {opts.get('setpoint_entity') or 'the setpoint device'} accepts at "
-            f"most {dev_max:.0f} W - THE DEVICE WINS, so the {max_w:.0f} W you "
-            f"configured would silently never happen. Lower max_w to "
-            f"{dev_max:.0f} W or less, or point setpoint_entity at a device that "
-            f"can take {max_w:.0f} W.")
+            f"{S('max_w')} is {max_w:.0f} W, but "
+            f"{opts.get('setpoint_entity') or 'the setpoint entity'} accepts at "
+            f"most {dev_max:.0f} W. Lower the rating to {dev_max:.0f} W or "
+            "less.")
     elif dev_min is not None and -max_w < dev_min:
         problems.append(
-            f"max_w is {max_w:.0f} W, so this controller may command "
-            f"{-max_w:.0f} W, but {opts.get('setpoint_entity') or 'the setpoint device'} accepts no less "
-            f"than {dev_min:.0f} W - THE DEVICE WINS on the charge side. Lower "
-            f"max_w to {abs(dev_min):.0f} W or less.")
+            f"{S('max_w')} is {max_w:.0f} W, but "
+            f"{opts.get('setpoint_entity') or 'the setpoint entity'} accepts no "
+            f"less than {dev_min:.0f} W when charging. Lower the rating to "
+            f"{abs(dev_min):.0f} W or less.")
 
     # --- 3. a meter that can actually read -----------------------------------
     # ⚠️ Not a second copy of these rules - p1.py owns them, because
@@ -898,9 +888,10 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     phases = _number(opts, "meter_phases", 1.0)
     max_age_s = _number(opts, "meter_max_age_s", 30.0)
     if phases is None or max_age_s is None:
-        problems.append("meter_phases and meter_max_age_s must both be numbers "
-                        f"(got {opts.get('meter_phases')!r} / "
-                        f"{opts.get('meter_max_age_s')!r})")
+        problems.append(f"{S('meter_phases')} and {S('meter_max_age_s')} must "
+                        f"both be numbers. They are "
+                        f"{messages.shown(opts.get('meter_phases'))} and "
+                        f"{messages.shown(opts.get('meter_max_age_s'))}.")
     else:
         problems.extend(validate_meter_options(opts, int(phases), max_age_s))
 
@@ -921,15 +912,9 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     if (is_enabled(opts) and max_age_s is not None
             and max_age_s > FIRMWARE_INGEST_VETO_S):
         problems.append(
-            f"meter_max_age_s is {max_age_s:.0f} s but the ESP32 firmware vetoes "
-            f"any P1 sample at {FIRMWARE_INGEST_VETO_S:.0f} s and forces the "
-            "layer-1 failsafe - THE FIRMWARE WINS, and it wins silently. This "
-            f"add-on would treat a {max_age_s - 1:.0f} s reading as fresh and "
-            "keep commanding, while the inverter sat at 0 W with a healthy-"
-            "looking meter on the status page. Lower meter_max_age_s to "
-            f"{FIRMWARE_INGEST_VETO_S:.0f} s or less (30 s is the tested value), "
-            "or rebuild the firmware with a matching max_age_s and update "
-            "validate.FIRMWARE_INGEST_VETO_S.")
+            f"{S('meter_max_age_s')} is {max_age_s:.0f} s, but the control "
+            f"board stops the inverter after {FIRMWARE_INGEST_VETO_S:.0f} s. "
+            f"Set it to {FIRMWARE_INGEST_VETO_S:.0f} s or less.")
 
     # --- 5. a sign watchdog that can actually fire ---------------------------
     # ⚠️ Strictly `>=`, matching the predicate exactly: watchdog.py tests
@@ -956,19 +941,15 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     caps = [cap for _, cap in caps_ix]
     weakest = min(caps) if caps else None
     if sign_w is None:
-        problems.append(f"sign_disagree_w {opts.get('sign_disagree_w')!r} is not a number")
+        problems.append(f"{S('sign_disagree_w')} is "
+                        f"{messages.shown(opts.get('sign_disagree_w'))}, which is not a "
+                        "number. Set it back to 300 W.")
     elif weakest is not None and weakest > 0 and sign_w >= weakest:
         where = _unit_label(opts, min(caps_ix, key=lambda p: p[1])[0])
         problems.append(
-            f"sign_disagree_w is {sign_w:.0f} W but max_w{where} is "
-            f"{weakest:.0f} W, so "
-            "the SAFETY-02 sign-disagreement watchdog can never fire: the "
-            "arbiter never lets a command exceed max_w, and the watchdog needs "
-            f"a command over {sign_w:.0f} W. It would sit there reporting "
-            "'armed' on the status page while being incapable of tripping - the "
-            f"one runaway failure mode this system has actually observed. Lower "
-            f"sign_disagree_w below {weakest:.0f} W (300 W is the measured "
-            "default), or raise max_w.")
+            f"{S('sign_disagree_w')} is {sign_w:.0f} W, not below "
+            f"{S('max_w', where)} at {weakest:.0f} W, so this safety stop can "
+            f"never trip. Lower it or raise the rating.")
 
     # ⚠️ AND THE SAME RULE FOR SAFETY-30's PER-UNIT THRESHOLD, WHICH IS A
     # SEPARATE COMPARISON AND THEREFORE A SEPARATE WAY TO DISARM. It grades a
@@ -1014,20 +995,15 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     unit_where = (_unit_label(opts, min(caps_ix, key=lambda p: p[1])[0])
                   if caps_ix else "")
     if unit_sign_w is None:
-        problems.append(f"unit_sign_disagree_w "
-                        f"{opts.get('unit_sign_disagree_w')!r} is not a number")
+        problems.append(f"{S('unit_sign_disagree_w')} is "
+                        f"{messages.shown(opts.get('unit_sign_disagree_w'))}, which is not a "
+                        "number. Set it back to "
+                        f"{SIGN_OPTION_DEFAULTS['unit_sign_disagree_w']:.0f} W.")
     elif weakest is not None and weakest > 0 and unit_sign_w >= weakest:
         problems.append(
-            f"unit_sign_disagree_w is {unit_sign_w:.0f} W but max_w{unit_where}"
-            f" is {weakest:.0f} W, so the SAFETY-30 per-inverter sign-disagreement "
-            "watchdog can never fire: no inverter is ever commanded past max_w, "
-            f"and the watchdog needs a command over {unit_sign_w:.0f} W. At two "
-            "inverters that is the guard which catches a unit doing the "
-            "OPPOSITE of what it was told while its sibling covers for it at "
-            "the meter - the case the site-level watchdog is structurally "
-            f"blind to. Lower unit_sign_disagree_w below {weakest:.0f} W "
-            f"({SIGN_OPTION_DEFAULTS['unit_sign_disagree_w']:.0f} W is the "
-            "measured default), or raise max_w.")
+            f"{S('unit_sign_disagree_w')} is {unit_sign_w:.0f} W, not below "
+            f"{S('max_w', unit_where)} at {weakest:.0f} W, so this safety stop "
+            f"can never trip. Lower it or raise the rating.")
 
     # --- 6. a maintenance charge the ceiling can actually accommodate --------
     # ⚠️ Strictly `>`, matching the arbiter exactly. The shaping is
@@ -1100,18 +1076,14 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     maint_where = _unit_label(opts, maint_index)
     if charge_w is None:
         problems.append(
-            f"maintenance_charge_w {opts.get('maintenance_charge_w')!r} is not a number")
+            f"{S('maintenance_charge_w')} is "
+            f"{messages.shown(opts.get('maintenance_charge_w'))}, which is not a number. Set "
+            "it in watts.")
     elif maint_cap is not None and maint_cap > 0 and charge_w > maint_cap:
         problems.append(
-            f"maintenance_charge_w is {charge_w:.0f} W but max_w{maint_where} is "
-            f"{maint_cap:.0f} W, so a maintenance charge in a cheap window can "
-            "never happen: the shaping asks the arbiter for at most "
-            f"{-charge_w:.0f} W while the supervised limit allows no less than "
-            f"{-maint_cap:.0f} W, which is a contradiction it resolves to 0 W - "
-            "THE CEILING WINS, and what you would see is an ARBITER "
-            "CONTRADICTION line that reads like a bug rather than like these "
-            f"two numbers. Lower maintenance_charge_w to {maint_cap:.0f} W or "
-            f"less, or raise max_w to at least {charge_w:.0f} W.")
+            f"{S('maintenance_charge_w')} is {charge_w:.0f} W, but the "
+            f"{S('max_w', maint_where)} is {maint_cap:.0f} W, so the monthly "
+            f"recharge cannot run. Lower it to {maint_cap:.0f} W or less.")
 
     # --- 10. a slew rate the plant can actually follow -----------------------
     # ⚠️ SAFETY-39. The one rule here that grades a RATIO rather than a
@@ -1140,34 +1112,19 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     slew_w = _number(opts, "slew_w", 0.0)
     rail = site_rail_w(opts)
     if slew_w is None:
-        problems.append(f"slew_w {opts.get('slew_w')!r} is not a number")
+        problems.append(f"{S('slew_w')} is {messages.shown(opts.get('slew_w'))}, which is "
+                        "not a number. Set it to 0 to follow the inverter "
+                        "rating.")
     elif slew_w < 0:
         problems.append(
-            f"slew_w is {slew_w:.0f} W and must not be negative - it is a "
-            "magnitude, and 0 means 'follow max_w' (the recommended setting).")
+            f"{S('slew_w')} is {slew_w:.0f} W and cannot be negative. Set it to "
+            "0 to follow the inverter rating.")
     elif slew_w and rail is not None and rail > 0:
         bound = SLEW_RAIL_FRAC * rail
         if slew_w > bound + 1.0:
-            ticks = rail / slew_w
             problems.append(
-                f"slew_w is {slew_w:.0f} W against a site rail of {rail:.0f} W, "
-                f"so the loop crosses its whole output range in {ticks:.1f} "
-                f"cycles - {ticks * LOOP_TICK_S:.0f} s at the {LOOP_TICK_S:.0f} s "
-                f"tick this site was measured running - while the plant takes "
-                f"{PLANT_SETTLE_S:.0f} s to settle (goodwe/NOTES.md §5.10, a "
-                "1.78 kW step). The controller would command its entire range "
-                "before it could observe its answer to the first step, which is "
-                "not a slow loop, it is a loop that MANUFACTURES the error it "
-                "then chases: measured on this system 2026-09-05, a 3.4 kW "
-                "export drove the setpoint 380 -> 5000 W in five ticks, the "
-                "battery to -5154 W past a 5000 VA rating, and the grid from "
-                "3.4 kW of export to 2.8 kW of import. The stated limit - the "
-                "command moves at most slew_w per cycle, so it cannot jump "
-                "ahead of the inverter - is untrue at this rail; THE PLANT "
-                f"WINS, and it has no status row. Set slew_w to 0, which means "
-                f"'follow the rail' and resolves to {bound:.0f} W here and "
-                "moves on its own if the rail does, or write a value at or "
-                f"below {bound:.0f} W. Lower is always accepted.")
+                f"{S('slew_w')} is {slew_w:.0f} W, too fast for a {rail:.0f} W "
+                f"site. Set it to 0 or to at most {bound:.0f} W.")
 
     # --- 7. two price sources on one site ------------------------------------
     problems.extend(_price_problems(opts))
@@ -1198,32 +1155,23 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
         where = _unit_label(opts, _ix)
         if soc_floor is None or bms_floor is None:
             problems.append(
-                f"peak_soc_floor and bms_soc_floor{where} must both be numbers "
-                f"(got {opts.get('peak_soc_floor')!r} / {_raw!r})")
+                f"{S('peak_soc_floor')} and {S('bms_soc_floor', where)} must "
+                f"both be numbers. They are {messages.shown(opts.get('peak_soc_floor'))} and "
+                f"{messages.shown(_raw)}.")
         elif soc_floor <= bms_floor:
             problems.append(
-                f"peak_soc_floor is {soc_floor:.0f} % but the pack's own cut-out "
-                f"(bms_soc_floor{where}) is {bms_floor:.0f} %, so SAFETY-07's forced "
-                "discharge has no EMS-side bound at all - THE BMS WINS, and it is "
-                "the pack's protection rather than yours. The guard would report a "
-                "SoC floor on its status page while being incapable of ever being "
-                "the thing that stops the discharge, and the symptom of that is a "
-                "battery repeatedly sitting at the BMS limit with no record of why "
-                f"- which looks exactly like the SoC drift the maintenance cycle "
-                f"exists to correct. Raise peak_soc_floor above {bms_floor:.0f} % "
-                f"(the shipped default is "
-                f"{PEAK_OPTION_DEFAULTS['peak_soc_floor']:.0f} %), or correct "
-                f"bms_soc_floor{where} if it does not match this pack.")
+                f"{S('peak_soc_floor')} is {soc_floor:.0f} %, not above the "
+                f"{S('bms_soc_floor', where)} of {bms_floor:.0f} %. Raise the "
+                f"reserve above {bms_floor:.0f} %, or correct the cut-out "
+                "level.")
 
     # --- warnings: real, but not worth refusing over -------------------------
     integ = opts.get("integrator_max_w")
     integ_w = None if not integ else _number(opts, "integrator_max_w", None)
     if integ_w is not None and max_w is not None and integ_w > max_w:
         _LOG.warning(
-            "integrator_max_w %.0f W is above max_w %.0f W. Not refused - the "
-            "arbiter still bounds the wire to +-max_w - but the only thing the "
-            "extra headroom buys is more wrong-direction power to unwind after "
-            "saturation. 0 (follow max_w) is the recommended value.",
+            "integrator_max_w %.0f W is above max_w %.0f W. This is allowed, "
+            "but it only adds overshoot, so 0 is recommended.",
             integ_w, max_w)
 
     # ⚠️ THE SIBLING OF RULE 6, AND NOT THE SAME CASE - see the docstring. The
@@ -1246,15 +1194,13 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     if (disch_w is not None and maint_cap is not None and maint_cap > 0
             and disch_w > maint_cap):
         _LOG.warning(
-            "maintenance_discharge_w %.0f W is above max_w%s %.0f W. Not "
-            "refused - the drain phase SETS the setpoint and the arbiter clamps "
-            "it to %.0f W and names the clamp ('limited by supervised(max_w)'), "
-            "so nothing is silent and the cycle still completes. But it drains "
-            "at %.0f W, not the %.0f W you configured, and the drain phase has "
-            "a 720 min timeout. Lower it to %.0f W or raise max_w to remove the "
-            "surprise.",
-            disch_w, maint_where, maint_cap, maint_cap, maint_cap, disch_w,
-            maint_cap)
+            "maintenance_discharge_w %.0f W is above max_w%s %.0f W, so "
+            "draining runs at %.0f W. Lower it to %.0f W or raise max_w.",
+            disch_w, maint_where, maint_cap, maint_cap, maint_cap)
+        _LOG.debug(
+            "Not refused: the drain phase sets the setpoint, the arbiter "
+            "clamps it to %.0f W and names the clamp, and the drain phase has "
+            "a 720 min timeout.", maint_cap)
 
     return problems
 
@@ -1306,43 +1252,19 @@ def _price_problems(opts: dict) -> list[str]:
         # fall back to, the site has had no tariff at all - a worse state, and
         # one this message must not paper over.
         been_running = (
-            f"the static day/night tariff in static_profile"
+            f"the {S('static_profile')}"
             if str(opts.get("static_profile", "") or "").strip()
-            else "NOTHING AT ALL - static_profile is empty too, so there was "
-                 "no tariff to fall back to either")
+            else "no tariff at all")
         problems.append(
-            f"price_provider is {pid!r}, which WAS a shipped plugin and has "
-            f"been WITHDRAWN (TARIFF-07). This is not a typo and you did not "
-            f"mistype it - the add-on offered this id, accepted it, and has "
-            f"said nothing at every startup since. "
-            f"⚠️ IT HAS NEVER FETCHED A PRICE, HERE OR ANYWHERE: "
-            f"{RETIRED_PROVIDERS[pid]}. Every fetch it ever made ended in "
-            f"SourceUnavailable, and §11.4 turns that into a SILENT fall back "
-            f"- so what this site has actually been running since the day the "
-            f"id was set is {been_running}. Nothing you could see would have "
-            f"differed from a working provider that simply never found a cheap "
-            f"hour, which is why you are being told now rather than left on "
-            f"it. WHAT TO DO: set price_provider to 'generic_dayahead' for the "
-            f"wholesale EPEX BE day-ahead curve, to which the add-on adds your "
-            f"price_markup_eur_kwh and price_taxes_eur_kwh - that APPROXIMATES "
-            f"a Belgian dynamic tariff and cannot reproduce your supplier's "
-            f"B x spot + A formula, so the level will be off even when the "
-            f"shape is right; or 'manual_csv' to enter all-in prices you "
-            f"compute yourself; or 'off' to run on static_profile "
-            f"deliberately. There is deliberately NO alias to your old "
-            f"supplier: aliasing would need your contract's own two "
-            f"coefficients, which live behind your klantenzone login and are "
-            f"in no public index, so the add-on would have to invent the "
-            f"numbers it prices your battery against.")
+            f"{S('price_provider')} is {pid!r}, which was withdrawn and never "
+            f"fetched a price. This site ran on {been_running}. Choose "
+            "'generic_dayahead', 'manual_csv' or 'off'.")
         return problems      # nothing below can be judged against a dead id
 
     if pid != "off" and pid not in PROVIDERS:
         problems.append(
-            f"price_provider is {pid!r}, which is not a shipped plugin. The "
-            f"ids that exist are: off, {', '.join(sorted(PROVIDERS))}. "
-            "Refused rather than defaulted, per the §14 warning box - a "
-            "silent fall back to 'off' would look exactly like a working "
-            "provider that happens never to find a cheap hour.")
+            f"{S('price_provider')} is {pid!r}, which does not exist. Choose "
+            f"one of: off, {', '.join(sorted(PROVIDERS))}.")
         return problems          # nothing below can be judged against an unknown id
 
     # ⚠️ THE HA-SIDE OVERLAP THE PM TOLD US TO DECIDE ABOUT, DECIDED HERE.
@@ -1386,19 +1308,9 @@ def _price_problems(opts: dict) -> list[str]:
                 if str(opts.get(k, "") or "").strip()]
     if pid != "off" and ha_price:
         problems.append(
-            f"price_provider is {pid!r} AND {' and '.join(ha_price)} "
-            f"{'is' if len(ha_price) == 1 else 'are'} set, which is two price "
-            "sources on one site. THE HOME ASSISTANT ENTITIES WIN: they are "
-            "what main.py reduces to the `cheap` flag the maintenance cycle "
-            "reads, and read_inputs() never looks at the other source once "
-            "they are set. The provider series is consumed - "
-            "app/static_tariff.py builds a tariff plan and an arbitrage "
-            "verdict, and app/arbitrage.py trades on it off a background "
-            "refresh - but the `cheap` flag those entities own is a separate "
-            "decision they would silently keep. Clear "
-            "price_now_entity and price_avg_entity to use the "
-            f"{pid!r} plugin, or set price_provider to 'off' to keep the "
-            "Home Assistant sensors.")
+            f"{S('price_provider')} is {pid!r}, but {_labels(ha_price)} would "
+            f"win over it. Clear {'it' if len(ha_price) == 1 else 'them'}, or "
+            "set the source to 'off'.")
 
     # ⚠️ THE SAME RULE FOR THE SOURCE TARIFF-03 ADDED, AND THIS ONE IS A LIVE
     # CONFLICT RATHER THAN A LATENT ONE. main.py's read_inputs() takes `cheap`
@@ -1407,14 +1319,9 @@ def _price_problems(opts: dict) -> list[str]:
     # day/night tariff has no way to see that it lost.
     if ha_price and str(opts.get("static_profile", "") or "").strip():
         problems.append(
-            f"static_profile is set AND {' and '.join(ha_price)} "
-            f"{'is' if len(ha_price) == 1 else 'are'} set, which is two "
-            "tariff sources feeding one cheap-window flag. THE HOME ASSISTANT "
-            "ENTITIES WIN: main.py reads them first and never looks at the "
-            "static profile, so the day/night tariff you typed would decide "
-            "nothing and nothing would say so. Clear price_now_entity and "
-            "price_avg_entity to use static_profile, or clear static_profile "
-            "to keep the Home Assistant sensors.")
+            f"{S('static_profile')} is set, but {_labels(ha_price)} would win "
+            f"over it. Clear the fixed tariff or "
+            f"{'the entity' if len(ha_price) == 1 else 'the two entities'}.")
 
     # ⚠️ THE PROFILE ITSELF, PARSED AT STARTUP RATHER THAN AT 02:00. A profile
     # that does not tile the day has hours with no price, and the only ways to
@@ -1427,16 +1334,15 @@ def _price_problems(opts: dict) -> list[str]:
             profile = parse_static_profile(raw_profile)
         except ProfileInvalid as e:
             profile = None
-            problems.append(f"static_profile cannot be used: {e}")
+            problems.append(f"“{messages.LABELS['static_profile']}” cannot be used. {e}")
         if profile is not None and profile.product is not None \
                 and len(set(profile.prices)) == 1:
             _LOG.info(
-                "static_profile carries one distinct price (%.4f EUR/kWh "
-                "all-in), so this site is priced as FULLY FIXED. Arbitrage is "
-                "off by arithmetic - a flat series has no spread - and the "
-                "add-on runs self-consumption only, which is §9.2's handling "
-                "for this product. Peak shaving, reserve management and the "
-                "maintenance cycle are unaffected.", profile.prices[0])
+                "static_profile has one price (%.4f EUR/kWh all-in), so this "
+                "site has a fully fixed price. A flat price has no spread to "
+                "trade on, so the add-on uses the battery for self-consumption "
+                "only. Peak limiting, the reserve and battery maintenance are "
+                "not affected.", profile.prices[0])
 
     # ⚠️ TARIFF-17: THE TAXES PERIOD TABLE, PARSED AT STARTUP RATHER THAN AT
     # 03:00, FOR `static_profile`'s REASON ONE OPTION OVER. This table is read
@@ -1452,7 +1358,7 @@ def _price_problems(opts: dict) -> list[str]:
         try:
             taxes_table = parse_taxes_profile(raw_taxes_profile)
         except ProfileInvalid as e:
-            problems.append(f"{TAXES_PROFILE_OPTION} cannot be used: {e}")
+            problems.append(f"“{messages.LABELS[TAXES_PROFILE_OPTION]}” cannot be used. {e}")
 
     if taxes_table is not None:
         # ⚠️ TWO WRITERS OF ONE QUANTITY, ONE OF WHICH SILENTLY LOSES - the
@@ -1482,21 +1388,12 @@ def _price_problems(opts: dict) -> list[str]:
                          PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"])
         shipped = PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"]
         untouched = (shipped,) + tuple(SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
-        superseded = ", ".join(
-            str(u) for u in SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
         if scalar is not None \
                 and not any(abs(scalar - u) <= 1e-12 for u in untouched):
             problems.append(
-                f"{TAXES_PROFILE_OPTION} is set AND price_taxes_eur_kwh is "
-                f"{scalar} rather than its shipped {shipped}. THE TABLE WINS: "
-                f"the add-on reads the per-period figures and never looks at "
-                f"the scalar, so the number you typed there would decide "
-                f"nothing and nothing would say so. Set price_taxes_eur_kwh "
-                f"back to {shipped}, or clear {TAXES_PROFILE_OPTION} to keep "
-                f"the flat figure. (A scalar still sitting on a SUPERSEDED "
-                f"default - {superseded} - is accepted and NOT refused: "
-                f"that is a number this add-on wrote into your options "
-                f"blob, not one you typed.)")
+                f"{S(TAXES_PROFILE_OPTION)} is set, so "
+                f"{S('price_taxes_eur_kwh')} is not used. Set it back to "
+                f"{shipped} from {scalar}, or clear the table.")
 
         # ⚠️ THE UNITS RUNG, AND IT IS A SECOND QUANTITY RATHER THAN A
         # RESTATEMENT. Every Belgian DSO prints these bands in c EUR/kWh
@@ -1511,13 +1408,8 @@ def _price_problems(opts: dict) -> list[str]:
                         if abs(p.eur_per_kwh) >= 1.0})
         if steep:
             problems.append(
-                f"{TAXES_PROFILE_OPTION} carries {steep} EUR/kWh. Belgian "
-                f"levies and distribution run about 0.05-0.25 EUR/kWh, so "
-                f"these are almost certainly the CENT figures off the tariff "
-                f"card (ORES prints `13,27`, which is 0.1327 EUR/kWh) typed "
-                f"without the conversion - a factor of 100 that would make "
-                f"every hour look like an emergency. Divide by 100, or clear "
-                f"the option.")
+                f"{S(TAXES_PROFILE_OPTION)} has {steep} EUR/kWh, which looks "
+                "like cents. Divide the figures by 100, or clear this setting.")
         negative = sorted({p.eur_per_kwh for p in taxes_table.periods
                            if p.eur_per_kwh < 0})
         if negative:
@@ -1528,10 +1420,9 @@ def _price_problems(opts: dict) -> list[str]:
             # observe. §14's warning box governs CONTRADICTIONS, and this is
             # not one.
             _LOG.warning(
-                "%s carries negative levies %s EUR/kWh. That is accepted, but "
-                "a tax component below zero is usually a sign error: the "
-                "add-on will SUBTRACT it from the published price in those "
-                "hours.", TAXES_PROFILE_OPTION, negative)
+                "%s has negative levies %s EUR/kWh, which are subtracted from "
+                "the price. This is allowed, but it is usually a sign error.",
+                TAXES_PROFILE_OPTION, negative)
 
     # ⚠️ TARIFF-15: THE FORMULA, GRADED AGAINST THE OPERATOR'S OWN CARD, AT
     # STARTUP RATHER THAN AT 03:00.
@@ -1567,25 +1458,15 @@ def _price_problems(opts: dict) -> list[str]:
         or isinstance(raw_formula, dict)
     if pid == "custom_formula" and not has_formula:
         problems.append(
-            "price_provider is 'custom_formula' but price_formula is empty, "
-            "so the add-on has no coefficients to price anything with. Every "
-            "fetch would return no-price-data and §11.4 would fall back "
-            "silently - which is the shape of defect this provider exists to "
-            "remove, arrived at by leaving one field blank. Copy the "
-            "Tariefformule line off your supplier's tariff card, e.g. "
-            "{\"index\":\"epex_be\",\"resolution\":\"hourly\","
-            "\"factor\":0.102,\"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}} "
-            "- see DOCS.md. Or set price_provider to 'generic_dayahead' for "
-            "the wholesale curve with a flat markup.")
+            f"{S('price_provider')} is 'custom_formula', but "
+            f"{S('price_formula')} is empty. Copy the formula from your "
+            "supplier's tariff card, or choose 'generic_dayahead'.")
     elif has_formula:
         try:
             spec = parse_price_formula(raw_formula)
         except FormulaInvalid as e:
             spec = None
-            problems.append(f"price_formula cannot be used: {e}")
+            problems.append(f"“{messages.LABELS['price_formula']}” cannot be used. {e}")
         if spec is not None and pid != "custom_formula":
             # ⚠️ A WARNING AND NOT A REFUSAL. This is not two price sources
             # fighting over one flag - it is one that is simply not wired to
@@ -1594,11 +1475,9 @@ def _price_problems(opts: dict) -> list[str]:
             # silent loser this module's case (a) is about, so it is said out
             # loud rather than left to be discovered from a bill.
             _LOG.warning(
-                "price_formula is filled in but price_provider is %r, so the "
-                "coefficients decide NOTHING - only 'custom_formula' reads "
-                "them. Set price_provider to 'custom_formula' to use them, or "
-                "clear price_formula so the configuration says what the "
-                "add-on is doing.", pid)
+                "price_formula is filled in, but price_provider is %r, so the "
+                "formula is not used. Set price_provider to 'custom_formula' "
+                "or clear price_formula.", pid)
         if spec is not None and pid == "custom_formula":
             taxes = _number(opts, "price_taxes_eur_kwh",
                             PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"])
@@ -1639,7 +1518,7 @@ def _price_problems(opts: dict) -> list[str]:
             xspec = parse_export_formula(raw_export)
         except FormulaInvalid as e:
             xspec = None
-            problems.append(f"{EXPORT_FORMULA_OPTION} cannot be used: {e}")
+            problems.append(f"“{messages.LABELS[EXPORT_FORMULA_OPTION]}” cannot be used. {e}")
         if xspec is not None:
             # ⚠️ THE 6% ASYMMETRY, PRINTED RATHER THAN ASSUMED. The two legs
             # carry INDEPENDENT `vat_pct` values and a Belgian site's are 6 and
@@ -1649,9 +1528,9 @@ def _price_problems(opts: dict) -> list[str]:
             _LOG.info(
                 "%s is set: injection priced as (%g x index %+g) x "
                 "(1 + %g/100) %s, i.e. %.4g x the wholesale price with a "
-                "%+.5f EUR/kWh offset. ⚠️ NO STRATEGY IN THIS ADD-ON READS "
-                "IT: arbitrage.py prices the sell side as displaced IMPORT "
-                "and compares two all-in CONSUMPTION prices, so this option "
+                "%+.5f EUR/kWh offset. No part of the add-on reads it yet: "
+                "trading prices the sell side as displaced import and "
+                "compares two all-in consumption prices, so this setting "
                 "changes no decision the add-on takes today. It is what you "
                 "are shown, and the shape a future export-aware strategy "
                 "would read.",
@@ -1687,20 +1566,18 @@ def _price_problems(opts: dict) -> list[str]:
                 # bounds in `implausible_injection()` are applied, and the
                 # operator is told which of the two checks did NOT run.
                 _LOG.warning(
-                    "%s has no \"card\" block, so its coefficients are "
-                    "UNGRADED: nothing recomputed a printed price from them. "
-                    "That is accepted because it is the real market - Eneco "
-                    "prints its injection formula with no price beside it, so "
-                    "there is nothing to grade against on that card - and "
-                    "refusing would make the published line inexpressible. "
-                    "What IS checked is the shape of the coefficients: the "
-                    "pass-through (%.4g x the wholesale price) and the offset "
-                    "(%+.5f EUR/kWh). If YOUR card prints an injection "
-                    "estimate, add {\"month\": ..., \"index_eur_per_mwh\": "
-                    "..., \"expect_incl_vat\": ...} and the add-on will "
-                    "refuse to start unless your numbers reproduce it.",
+                    "%s has no \"card\" block, so its numbers are not checked "
+                    "against a printed price, only their shape (pass-through "
+                    "%.4g, offset %+.5f EUR/kWh).",
                     EXPORT_FORMULA_OPTION, xspec.passthrough,
                     xspec.offset_eur_kwh)
+                _LOG.debug(
+                    "Accepted because some suppliers (Eneco) print the "
+                    "injection formula with no price beside it. If your card "
+                    "prints an injection estimate, add {\"month\": ..., "
+                    "\"index_eur_per_mwh\": ..., \"expect_incl_vat\": ...} "
+                    "and the add-on refuses to start unless your numbers "
+                    "reproduce it.")
             else:
                 xaged = stale_card(xspec)
                 if xaged:
@@ -1713,11 +1590,9 @@ def _price_problems(opts: dict) -> list[str]:
     # every install TARIFF-02 shipped, none of which could have had one.
     if pid != "off" and not str(opts.get("static_profile", "") or "").strip():
         _LOG.warning(
-            "price_provider is %r but static_profile is empty. §11.4's "
-            "degradation row is 'no price data -> fall back to the static "
-            "profile'; with none configured, a feed outage leaves this site "
-            "with no tariff at all rather than with a coarse one. Not refused, "
-            "but filling it in is what makes that row work.", pid)
+            "price_provider is %r but static_profile is empty, so a price "
+            "feed outage leaves no tariff at all. Fill in static_profile as a "
+            "fallback.", pid)
 
     # ⚠️ OPT-04. THE THREE WAYS `arbitrage_enabled: true` CAN BE A LIE, refused
     # rather than logged, because a strategy that is armed in the UI and cannot
@@ -1732,62 +1607,39 @@ def _price_problems(opts: dict) -> list[str]:
                      PRICE_OPTION_DEFAULTS["cycle_cost_threshold_eur"])
     if thresh is None or thresh < 0:
         problems.append(
-            f"cycle_cost_threshold_eur is "
-            f"{opts.get('cycle_cost_threshold_eur')!r} and must be a "
-            f"non-negative number of EUR/kWh - it is what one round trip COSTS "
-            f"(§10.1). A negative threshold is one that every spread clears, "
-            f"including a spread of nothing, which is arbitrage with the brake "
-            f"removed rather than arbitrage tuned aggressively.")
+            f"{S('cycle_cost_threshold_eur')} is "
+            f"{messages.shown(opts.get('cycle_cost_threshold_eur'))}. Set it to 0 or more, "
+            "in EUR/kWh.")
 
     if arbitrage_on(opts):
         if pid == "off" and not str(opts.get("static_profile", "") or "").strip():
             problems.append(
-                "arbitrage_enabled is on but price_provider is 'off' and "
-                "static_profile is empty, so this site has NO PRICES AT ALL. "
-                "§10.1's priority 3 is 'charge cheap, discharge expensive' and "
-                "there is nothing here to tell cheap from expensive, so the "
-                "strategy would refuse on every cycle forever while the "
-                "configuration said it was running. Configure a price_provider "
-                "or a static_profile, or turn arbitrage_enabled off.")
+                f"{S('arbitrage_enabled')} is on, but the site has no prices. "
+                f"Set {_labels(['price_provider', 'static_profile'], 'or')}, "
+                "or turn trading off.")
         if not is_enabled(opts):
             problems.append(
-                "arbitrage_enabled is on but meter_source is 'off', so there "
-                "is no P1 telegram stream, the capacity-tariff peak guard "
-                "never runs, and nothing measures the 15-minute average this "
-                "strategy's charging would land in. §9.1 gives peak shaving "
-                "priority over arbitrage; an unmeasured peak cannot be shaved, "
-                "so arbitrage would be deliberately creating the billed "
-                "quantity with the one guard that limits it switched off. "
-                "app/arbitrage.py refuses to trade in that state anyway - this "
-                "refuses the configuration that asks it to. Set meter_source, "
-                "or turn arbitrage_enabled off.")
+                f"{S('arbitrage_enabled')} is on, but no meter is set in "
+                f"{S('meter_source')}. Choose a meter, or turn trading off.")
         floor = _number(opts, "arbitrage_soc_floor",
                         PRICE_OPTION_DEFAULTS["arbitrage_soc_floor"])
         ceiling = _number(opts, "arbitrage_soc_ceiling",
                           PRICE_OPTION_DEFAULTS["arbitrage_soc_ceiling"])
         if floor is None or ceiling is None:
             problems.append(
-                f"arbitrage_soc_floor {opts.get('arbitrage_soc_floor')!r} and "
-                f"arbitrage_soc_ceiling {opts.get('arbitrage_soc_ceiling')!r} "
-                f"must both be numbers - they are percentages of pack charge.")
+                f"{S('arbitrage_soc_floor')} and {S('arbitrage_soc_ceiling')} "
+                "must both be numbers, in %.")
         elif floor >= ceiling:
             problems.append(
-                f"arbitrage_soc_floor is {floor:g} % and arbitrage_soc_ceiling "
-                f"is {ceiling:g} %, so there is no band left between them: "
-                f"every state of charge is either at or under the floor (no "
-                f"discharge) or at or over the ceiling (no charge), and the "
-                f"strategy can never act. The floor is the reserve it may not "
-                f"spend and the ceiling is the headroom it may not overfill, "
-                f"so the floor must be the SMALLER number.")
+                f"{S('arbitrage_soc_floor')} is {floor:g} %, not below "
+                f"{S('arbitrage_soc_ceiling')} at {ceiling:g} %. Make the lower "
+                "limit the smaller number.")
 
     if pid == "manual_csv" and not str(opts.get("price_csv_path", "") or "").strip():
         problems.append(
-            "price_provider is 'manual_csv' but price_csv_path is empty, so "
-            "the offline fallback has no file to read. Every fetch would "
-            "return no-price-data with a filesystem error as its reason - "
-            "which is §11.4 behaviour arrived at by accident rather than by "
-            "configuration. Point it at the CSV, or set price_provider to "
-            "'off', which says the same thing on purpose.")
+            f"{S('price_provider')} is 'manual_csv', but "
+            f"{S('price_csv_path')} is empty. Set the path to the CSV file, or "
+            "choose 'off'.")
 
     return problems
 
@@ -1813,11 +1665,9 @@ def refuse(problems: list[str]) -> None:
     at all and even the exit status distinguishes the two.
     """
     _LOG.error("=" * 72)
-    _LOG.error("REFUSING TO START: the add-on configuration is not usable.")
-    _LOG.error("This is a CONFIGURATION problem, not a crash. Nothing is broken;")
-    _LOG.error("the add-on will start as soon as the settings below are fixed.")
-    _LOG.error("Fix them in Settings > Add-ons > GoodWe RS485 Controller >")
-    _LOG.error("Configuration, then start the add-on again.")
+    _LOG.error("The add-on did not start, because its settings have problems.")
+    _LOG.error("Nothing is broken. Fix the settings below, then start it again.")
+    _LOG.error("They are on the add-on's Configuration tab.")
     _LOG.error("-" * 72)
     for i, problem in enumerate(problems, 1):
         _LOG.error("  %d. %s", i, problem)

goodwe_controller/app/web.py

@@ -31,7 +31,7 @@ import logging
 
 from aiohttp import web
 
-from . import selfconfig
+from . import messages, selfconfig
 from .config_page import CONFIG_PAGE
 from .configui import changed_keys, field_model, problems_by_field
 
@@ -125,11 +125,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:
@@ -264,7 +261,8 @@ def build_app(controller, selfcfg=None) -> web.Application:
             _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"))
         return web.json_response({"ok": True, **result})
 
     async def config_restart(request):
@@ -288,7 +286,8 @@ 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})
 
     app = web.Application()
@@ -305,8 +304,16 @@ def build_app(controller, selfcfg=None) -> web.Application:
     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.10.0"
+version: "0.12.0"
 slug: goodwe_controller
 description: >-
   Drives a GoodWe ES/BP battery inverter over RS485 by emulating its smart
@@ -93,7 +93,7 @@ options:
   # against a sibling's numbers; an entry silently inheriting `soc_entity` would
   # rebuild that defect in YAML. `name`, `setpoint_entity`, `max_w` and
   # `bms_soc_floor` are therefore REQUIRED of every entry (the schema below enforces it, and
-  # validate.py rule 9 enforces it again for the callers the Supervisor never
+  # validate.py rules 8 and 9 enforce it again for the callers the Supervisor never
   # sees). An omitted `soc_entity`/`batt_entity` means THIS UNIT HAS NO SUCH
   # SENSOR - `inputs_ok` already stops the site for that - and never means
   # "use the other one's".
@@ -147,6 +147,76 @@ options:
   inverters: []
   estop_fitted: false
 
+  # 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
+  # when it is empty the add-on reads no entity, announces no entity, publishes
+  # no topic and shows no status row.
+  #
+  # ⚠️ AN HA ENTITY AND NOT A REGISTER, BECAUSE MOST SOLAR INVERTERS ARE NOT ON
+  # THIS BUS. The RS485 bus this add-on speaks carries the BATTERY inverter it
+  # drives; a household's PV inverter is normally a different box from a
+  # different vendor, reporting into Home Assistant through its own integration.
+  # So this takes whatever `sensor.*` the site's PV integration provides, any
+  # brand Home Assistant can read.
+  #
+  # POSITIVE IS PRODUCTION. An entity that reads the other way round goes in
+  # `pv_invert_entities` below - see DECISIONS/TEL-14-pv-sign.md.
+  #
+  # ⚠️ THE ENTITY'S OWN `unit_of_measurement` IS WHAT IS BELIEVED - W, kW, MW
+  # and the rest of Home Assistant's power units. A sensor with no unit, or with
+  # a unit that is not power, is REFUSED and the status page says which: there
+  # is no magnitude heuristic that can tell 30 W of dusk from 30 kW of noon, and
+  # a factor of 1000 in the one channel that exists to be believed a week later
+  # is worse than a refusal an operator can read.
+  pv_entity: ""
+
+  # TEL-12 - THE SAME CHANNEL WHEN THE ROOF HAS SEVERAL INVERTERS, WHICH IS THE
+  # ORDINARY CASE AND NOT AN EDGE ONE. A multi-string or multi-orientation roof
+  # routinely carries two or three PV inverters, each publishing its own power
+  # sensor; 0.11.0 shipped `pv_entity` as a single string and the reference
+  # site's owner reported within minutes that they could configure one of
+  # theirs. List them all here and the row carries the SITE total.
+  #
+  # ⚠️ DECLARED, THIS REPLACES `pv_entity` - it does not extend it. Set both and
+  # ONLY this list is read, and the status page says so. That is CFG-04's rule
+  # for `inverters:` applied to the upgrade path this key exists for: the
+  # install being upgraded HAS `pv_entity` set, and an operator who adds all
+  # their inverters to this list while the old key still names one of them would
+  # DOUBLE that inverter under a union rule. Clear `pv_entity` when you fill
+  # this in.
+  #
+  # ⚠️ AND IF ANY ONE OF THEM IS NOT REPORTING, THERE IS NO SITE TOTAL - the row
+  # publishes `unknown` and the recorder records a GAP. It does NOT publish the
+  # sum of the ones that answered: two of three inverters add up to a smaller
+  # number that is indistinguishable from a real one, and a week later that
+  # reads as "there was less sun than there was" - the exact conclusion this
+  # channel exists to TEST rather than to manufacture. The status page names
+  # which entity is missing and why, and lists what the others reported, because
+  # a human reading it live wants the diagnostic; the recorded number does not,
+  # because nobody re-derives a week of history. See
+  # DECISIONS/TEL-12-several-pv-inverters.md.
+  #
+  # ⚠️ THE FIX IS NOT A TEMPLATE SENSOR THAT SUMS THEM. You may legitimately
+  # prefer one, but a template sensor summing an `unavailable` source yields the
+  # partial total silently - the same defect one layer down, in a place this
+  # add-on cannot see or report.
+  #
+  #   pv_entities:
+  #     - sensor.pv_east_power
+  #     - sensor.pv_west_power
+  #     - sensor.pv_garage_power
+  #
+  # Each entity's OWN `unit_of_measurement` is read, so a kW inverter beside a W
+  # one sums correctly. Empty is the shipped default and means "use `pv_entity`,
+  # which is also empty" - i.e. no PV channel at all, which is every install.
+  pv_entities: []
+
+  # TEL-14. Every PV entity listed here (in `pv_entity` or `pv_entities`) has
+  # its sign flipped, for a kWh meter or power clamp that reads production as
+  # negative. Per entity, because one roster can mix both conventions. `[]` is
+  # load-bearing like `pv_entities: []`; see DECISIONS/TEL-14-pv-sign.md.
+  pv_invert_entities: []
+
   # ==========================================================================
   # METER - where the grid reading comes from
   # ==========================================================================
@@ -156,7 +226,7 @@ options:
   # ha_signed reads ONE signed HA entity (+ import / - export), which is what a
   # HomeWizard P1 publishes and what ha_dsmr cannot consume.
   # homewizard_local skips Home Assistant entirely and polls the meter's own
-  # local API. ⚠️ It is the ONLY mode whose sensor.p1_sample_age_s measures when
+  # local API. ⚠️ It is the ONLY mode whose sensor.goodwe_p1_sample_age measures when
   # the meter REPORTED rather than when the value last CHANGED - HA emits
   # nothing at all for a repeated reading - so it is the only mode a firmware
   # watchdog may threshold. See DOCS.md.
@@ -848,12 +918,13 @@ schema:
   # batteries, whereas an absent capacity has an honest answer - no opinion
   # about the split, every unit weighs 1.0, which is what shipped.
   #
-  # ⚠️ THREE KEYS ARE REQUIRED PER ENTRY AND THAT IS DELIBERATE. An entry with
+  # ⚠️ FOUR KEYS ARE REQUIRED PER ENTRY AND THAT IS DELIBERATE. An entry with
   # no `name` has no Store namespace and would share another unit's SAFETY-02
   # latch; one with no `setpoint_entity` is a unit nothing can command; one with
   # no `max_w` would have to borrow a rating, which is the sibling-grading
-  # defect DEV-02 removed. The optional pair is the sensors, whose absence
-  # honestly means "this unit reports none".
+  # defect DEV-02 removed; `bms_soc_floor` is SAFETY-32's (options block above).
+  # The optional keys are the sensors, whose absence honestly means "this unit
+  # reports none", and `capacity_kwh`.
   #
   # ⚠️ THIS BLOCK IS DECLARED BEFORE `max_w:` ON PURPOSE. `max_w` now appears
   # TWICE under `schema:` - once nested here, once flat below - and a reader
@@ -872,6 +943,41 @@ schema:
       capacity_kwh: float(0.1,200)?
 
   estop_fitted: bool
+  # 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.
+  # Nothing in validate.py mentions this key: it cannot conflict with anything,
+  # because nothing else reads it.
+  pv_entity: str?
+
+  # TEL-12. ⚠️ A SECOND KEY RATHER THAN A LIST SHAPE ON `pv_entity`, AND THAT IS
+  # A MEASUREMENT AND NOT A PREFERENCE. `pv_entity` shipped in 0.11.0 as `str?`
+  # and the reference site has a string persisted in it. Declared as a list,
+  # Supervisor 2026.08.0 answers that stored string with
+  #
+  #   Invalid list for option 'pv_entity' in GoodWe RS485 Controller
+  #
+  # and `deepmerge`'s list strategy is `override`, so a shipped `[]` default does
+  # NOT rescue it - the operator's string stands and is refused. That is CFG-04
+  # §B's trap in the other direction: an add-on that will not start, and the
+  # schema needed to fix it pinned to the version that cannot be installed. The
+  # only single-key spelling Supervisor accepts for BOTH shapes is `match(.*)?`,
+  # which validates nothing at all (it admits a number, a dict, any list of
+  # anything) and renders as a plain text box. Measured, both of them, by
+  # `tools/supervisor_shape_probe.py` §G - the transcript is in
+  # DECISIONS/TEL-12-several-pv-inverters.md §1.
+  #
+  # ⚠️ AND `pv_entities: []` IN THE `options:` BLOCK IS LOAD-BEARING, exactly as
+  # `inverters: []` is. §G measures the same isolated counterfactual: the
+  # shipped defaults MINUS only this key are refused with `Missing option
+  # 'pv_entities' in root`, which is every options blob written before 0.12.
+  # `p1_phase_import_entities` is the shipped precedent for the pair.
+  pv_entities:
+    - str
+  # TEL-14. A parallel list, not a prefix or a dict: measured by
+  # tools/supervisor_shape_probe.py section H, DECISIONS/TEL-14-pv-sign.md.
+  pv_invert_entities:
+    - str
 
   # ==========================================================================
   # METER - where the grid reading comes from

goodwe_controller/named_absence.py

@@ -0,0 +1,99 @@
+"""Read a value a check prints or grades without raising (TEST-26).
+
+Each test file is one script, so an IndexError in a print or a check name
+kills every check after it (MUTATION.md, FCST-06). Read through these instead,
+and conjoin `present(x)` in the check so the absence grades as a named FAIL.
+
+`ABSENT` values never raise: they format as `<ABSENT ...>` under any spec,
+index and attribute to themselves, compare unequal AND not-unequal, and are
+falsy. `not x`, `"a" not in x` and `all(... for _ in x)` are therefore TRUE of
+one, which is why the check needs the `present()` term. `int()`, `range()` and
+use as a list index still raise: guard those with `present()`.
+"""
+
+_NAN = float("nan")
+
+
+class Absent:
+    __slots__ = ("what",)
+
+    def __init__(self, what):
+        object.__setattr__(self, "what", what)
+
+    def __repr__(self):
+        return f"<ABSENT {self.what}>"
+
+    __str__ = __repr__
+
+    def __format__(self, spec):
+        return repr(self)
+
+    def __bool__(self):
+        return False
+
+    def __eq__(self, other):
+        return False
+
+    __ne__ = __lt__ = __le__ = __gt__ = __ge__ = __eq__
+
+    def __hash__(self):
+        return id(self)
+
+    def __getitem__(self, _):
+        return self
+
+    def __getattr__(self, _):
+        return self
+
+    def __call__(self, *_a, **_k):
+        return self
+
+    def __len__(self):
+        return 0
+
+    def __iter__(self):
+        return iter(())
+
+    def __contains__(self, _):
+        return False
+
+    def __float__(self):
+        return _NAN
+
+    def _same(self, *_):
+        return self
+
+    __add__ = __radd__ = __sub__ = __rsub__ = __mul__ = __rmul__ = _same
+    __truediv__ = __rtruediv__ = __floordiv__ = __rfloordiv__ = _same
+    __mod__ = __rmod__ = __neg__ = __pos__ = __abs__ = __round__ = _same
+
+
+def present(*xs):
+    """True when none of `xs` is an ABSENT stand-in."""
+    return not any(isinstance(x, Absent) for x in xs)
+
+
+def nth(seq, i=0, what=None):
+    """`seq[i]`, or an ABSENT saying how many items there were."""
+    n = 0 if seq is None else len(seq)
+    if -n <= i < n:
+        return seq[i]
+    return Absent(what or f"[{i}] of {n} item(s)")
+
+
+def first(it, what="no match"):
+    """`next(it)`, or ABSENT when it is exhausted."""
+    return next(iter(it), Absent(what))
+
+
+def field(mapping, key, what=None):
+    """`mapping[key]`, or ABSENT when the key (or the mapping) is missing."""
+    try:
+        return mapping[key]
+    except (KeyError, IndexError, TypeError):
+        return Absent(what or f"key {key!r}")
+
+
+def given(x, what="None"):
+    """`x`, or ABSENT when it is None - so `:.2f` and arithmetic cannot raise."""
+    return Absent(what) if x is None else x