TEL-11: PV production stops being invisible, and stays out of the control law

OPT-10 measured that this site's pack reaches 90 % SoC on 2 days of 16 and that
20.5 kWh of surplus left the site 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, which
is the only software defect) and guessing between them is how an optimiser gets
tuned to solve a cloud problem. This card adds the channel. It does not do the
attribution.

AN HA ENTITY, NOT A REGISTER, AND THAT IS A PRODUCT DECISION. This add-on's
RS485 bus 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. `pv_entity` takes whatever `sensor.*` the site's
own PV integration provides, any brand HA can read.

POSITIVE IS PRODUCTION, AND THERE IS NO `pv_invert`. The convention is derived
rather than assumed: `meter_entity` is positive when IMPORTING and `batt_entity`
is positive when DISCHARGING (DOCS.md, Sources), both of which are "power
arriving at the house's AC bus", and production arrives there too. Those two
keys carry invert flags because they are BIPOLAR and are READ BY THE CONTROL
PATH - `inv.batt` feeds SAFETY-30's per-unit sign check and SAFETY-31's
circulating-power sensor, so a reversed sensor hands the site a plausible number
it acts on. Production is unipolar and is read by nothing: a reversed sensor
announces itself as -4 kW at noon in the very history this card creates, and a
flag would only let an installer hide it. 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 measured.

ABSENCE IS NEVER ZERO, AND "DROPPED" IS NOT ABSENT. `publish()` SKIPS a None,
which is right for `circulation` and exactly wrong here: a skipped row leaves
Home Assistant holding the last number forever and the recorder draws a FLAT
LINE through the outage, which is indistinguishable from a measurement and
manufactures the "there was no surplus" conclusion this card exists to TEST. So
the absence is published, with HA's own payload: `mqtt/const.py` declares
`PAYLOAD_NONE = "None"` and `mqtt/sensor.py` tests it BEFORE the numeric branch,
so the entity's state becomes `unknown` and the recorder stores a GAP. Read out
of home-assistant/core `dev` on 2026-09-24 and quoted at the constant.
`ABSENT_AS_UNKNOWN` is a one-key set and the suite asserts `circulation: None`
is STILL dropped.

THE UNIT IS READ OFF THE ENTITY. `mW`, `W`, `kW`, `MW`, `GW`, `TW` - HA's own
`UnitOfPower`, 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.
`read_inputs()`'s `abs(raw) < 50` kW-or-W guess is safe for a quarter-hour
demand forecast and is NOT safe here: 30 W of dusk is an ordinary reading and
that heuristic would publish it as 30 kW.

GENUINELY OPTIONAL, AND NOT A SECOND `price_now_entity`. validate.py does not
mention the key - it cannot conflict with anything, because nothing else reads
it. The MQTT row lives in a new `OPTIONAL_SENSORS` list whose `include` argument
DEFAULTS TO EMPTY, so every caller that has never heard of `pv_entity` -
test_mqtt.py's fixtures, tools/rehearse_roster.py, anything written next year -
announces exactly what it announced before. Unset: no state call at all, no
entity, no topic, no status row, no page row. Set and failing: a CAUTION
(`ok=False, warn=True`), never a `bad` row, so a telemetry channel can never put
a battery site into NOT READY.

IT MUST NOT BECOME A CONTROL INPUT, AND THAT IS GRADED TWICE. `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
(33 modules under app/) showing the material is mentioned in exactly three:
pv.py, main.py, mqtt.py. `tools/tel11_pv_trace.py` is the cross-tree half -
`safety56_behaviour_trace.py`'s pattern with a DIFFERENT control clause, because
this card's claim is that nothing differs rather than that only sentences do: it
REFUSES unless the two `app/` fingerprints differ and unless exactly one side
reacts to the option. Measured on 41 stimulus cells:

    control   release/1.0 unset  846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
    control   TEL-11      unset  846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
    control   TEL-11      set    846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
    telemetry release/1.0 unset  a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
    telemetry TEL-11      unset  a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
    telemetry TEL-11      set    4e6d1cb289a957223ad0205f732a6fec6110ce1f2032c98ad60694e67625274f

UNSET is byte-identical in BOTH documents, which is stronger than "the control
path is untouched": an install that does not set the option sees no change of
any kind, announcement and status rows included.

⚠️ AND THE CARD'S CENTRAL MUTATION WAS A SURVIVOR ON THE FIRST BATTERY.
`self.grid -= self.pv_w` in `read_inputs()` - +106 B, on disk, purged, genuinely
running - came back GREEN, because the fixture drove a 6 kW export over 12
cycles, which puts the loop AGAINST ITS RAIL: a command moving `slew_w` every
cycle produces the same ramp for -6000 W and for -14 000 W of apparent error.
MUTATION.md habit 23 with a saturated ACTUATOR in place of a coinciding value,
and it is in that file now as the habit's second instance. The fixture now
drives a 600 W import the loop SETTLES on, against a responsive meter, 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.

Evidence: 31/31 suites green in the CI image, checks.yml's exact command, purged
tree, `:ro`. Ten mutations, NO survivors, each on its own `cp -a` of the tree so
habit 18's revert hazard is closed by construction - table in
`DECISIONS/TEL-11-pv-production.md` §7 with byte deltas and sha256s.

⚠️ THIS IS A RUNTIME CHANGE BEHIND AN UNCHANGED VERSION, AND
`tools/predeploy_check.py` WILL REFUSE IT. `app/`, `config.yaml` and
`translations/` are all in its `RUNTIME` tuple and `config.yaml` still reads
0.10.1, so the gate reports a NO-OP deploy until a version is cut. That is PKG's
call and this card does not take it.

No CHANGELOG section: `test_version_gate.py` 11b refuses a newest `## ` heading
that is not config.yaml's `version:`, and opening one would mean taking that
same packaging decision. The operator account is in DOCS.md.

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

goodwe_controller/DOCS.md

@@ -139,6 +139,7 @@ either direction, and the check is mutation-tested both ways.
 | `batt_invert` | | Flip if needed |
 | `capacity_kwh` | | This pack's usable capacity. Read only to divide the site target between packs by **energy** headroom — see below |
 | `setpoint_entity` | yes | The ESPHome `number.*_goodwe_setpoint_w` |
+| `pv_entity` | | Optional. Your **solar** inverter's power sensor, `+` = producing. Measurement only — it changes no control behaviour. See [PV production](#pv-production-pv_entity-tel-11) |
 
 Use the ESP32's readings rather than the inverter's cloud or dongle sensors:
 those serve cached values, and a stale reading here ends the maintenance charge
@@ -413,6 +414,97 @@ and `Inverter B` — are two names to the validator and one id once slugged. The
 add-on gives the second one a `_2` suffix so nothing collides, but the ids you
 get then depend on roster order. Give your inverters plainly different names.
 
+### PV production (`pv_entity`, TEL-11)
+
+**Optional, off by default, and it changes no control behaviour whatsoever.**
+Set it and the add-on records what your solar is producing beside what the
+meter and the battery are doing. Leave it empty and the add-on reads no entity,
+announces no entity, publishes no topic and shows no row — which is what every
+install that upgrades into this version does.
+
+#### Why it is a Home Assistant entity and not a register
+
+This add-on's RS485 bus 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
+`pv_entity` takes whatever `sensor.*` your PV integration already provides —
+any brand Home Assistant can read. It does not have to be on the bus, and there
+is no assumption anywhere that it is.
+
+#### What it is for
+
+OPT-10 measured this site over sixteen days: the battery reached 90 % 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. Three different
+things produce that number and they need three different fixes:
+
+* there was no irradiance to store — nothing to fix;
+* production was there and something limited the charge power;
+* production was there, the battery could take it, and the optimiser declined.
+
+Only the third is a software defect, and **none of them can be told apart
+without a record of production.** This entity is that record. The attribution
+itself is OPT-10's, with a week of history behind it.
+
+#### The sign, and why there is no `pv_invert`
+
+**Positive must mean producing.** That is the same convention as the two sign
+rules the add-on already ships — `meter_entity` is positive when **importing**
+and `batt_entity` is positive when **discharging**, both of which are "power
+arriving at the house" — and production arrives there too.
+
+`meter_invert` and `batt_invert` exist because those two quantities are
+**bipolar and are read by the control path**: a reversed battery sensor is a
+perfectly plausible number that the per-inverter sign failsafe then acts on.
+Production is unipolar and is read by **nothing**, so a reversed sensor here
+cannot mislead a decision — and it announces itself immediately as −4 kW at
+noon in the very history this entity creates. A flag would only hide it, so
+there is not one. If your sensor really is inverted, fix it where it is
+produced.
+
+#### The unit is read off the entity
+
+The add-on reads your entity's own `unit_of_measurement` and converts: `mW`,
+`W`, `kW`, `MW`, `GW`, `TW` — Home Assistant's own power units. A sensor with
+**no** unit, or with a unit that is not one of those, is **refused**, and the
+status page says which entity and which unit. That is deliberate: there is no
+magnitude test that can separate 30 W of dusk from 30 kW of noon, so a guess
+here would be a silent factor of 1000 in the one channel that exists to be
+believed a week later.
+
+#### ⚠️ Absence is never zero
+
+| what happened | `sensor.goodwe_pv_power` | on 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 the point. A dead sensor publishes Home Assistant's own
+"no value" payload, so the entity goes to **`unknown`** and the recorder stores
+a **gap** — not a flat line at the last number it saw. Reading a week of
+history back, *"no PV was reported"* and *"PV reported 0 W"* are different
+pictures, which is exactly the distinction the whole card exists to preserve.
+
+A failed read also **clears** the previous good one: the value never outlives
+its own sensor.
+
+#### ⚠️ What it does NOT do
+
+It is **instrumentation**. It is not an input to 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 the
+battery being regulated; and its status row is a **caution**, never a
+`NOT READY`. 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.
+
+`tools/tel11_pv_trace.py` is what says so rather than claims it: it drives 41
+stimulus worlds through the shipped controller and hashes a document of control
+decisions containing none of this material, on this tree and on `release/1.0`,
+with the option set and unset.
+
 ### P1 meter ingestion
 
 `meter_entity` above expects one signed sensor, which usually means a template