nwp500-python 9.12.0__tar.gz → 9.12.2__tar.gz

{nwp500_python-9.12.0 → nwp500_python-9.12.2}/CHANGELOG.rst

@@ -2,6 +2,489 @@
 Changelog
 =========
 
+Version 9.12.2 (2026-10-25)
+===========================
+
+Changed
+-------
+
+- **The heat book prices its runs as cooled to the air, on the
+  record.** Pricing each run at the loop's return instead, the pipe
+  resting 7.84 °F over the air and cooling on 0.464 h, books the fitted
+  pairs no better (17,018 BTU mean absolute error against 16,991 on 87
+  pairs). The book is unchanged. See :doc:`/how-to/calibrate-simulator`.
+
+- **The recovery fit's held-out error is draws inside recoveries.**
+  The latest recoveries come out about 25 min short at every
+  compressor fit tried. Those with under 2 gal of hot water and 5
+  minutes of circulation inside them come out 0.1 min short (20 of
+  35); each hot gallon inside a recovery adds about 4.7 min. The fit is
+  unchanged: fitted on the draw-light recoveries alone, the constant
+  scores worse on the held-out draw-light ones (14.2 min against 11.6).
+  See :doc:`/explanation/simulator`.
+
+- **The compressor's engineering values are not fittable on the
+  record.** The condenser approach (10 °F), clearance ratio (0.05) and
+  polytropic exponent (1.17) stay. The compressor constant absorbs
+  each: refitting it with each moved over a wide range changed the
+  held-out recovery error by under 0.7 min. See
+  :doc:`/reference/simulator-inputs`.
+
+- **Hand-set values checked against the record.** None changes.
+  ``TankParams.lower_zone_share`` 0.5 stays: refitting the compressor
+  constant at 0.435-0.5 moved the held-out recovery error by under
+  0.7 min. ``ControllerParams.tou_cap_f`` 3.6 °F stays at the device's
+  threshold: the probe's 3.42 °F at a capped stop is one probe step
+  past it, as a full recovery ends past its setpoint.
+  ``ReadinessParams.probe_resolution_f`` is a round 1 °F and is now
+  tagged as a default, not a measurement. The unused
+  ``engine.RESOLUTION_F`` is gone. The humidity default of 50 % stays:
+  holding every recovery there instead of its own reading moved the
+  mean duration error by 0.4 min. ``calibration.SETTLE_MINUTES`` 45
+  stays: ``ua_ref`` was 4.44-4.48 at 30 to 90 min. The recovery screen
+  (``MIN_MINUTES_PER_F``, ``MAX_MINUTES_PER_F``) stays: fitting with
+  the 12 it drops moved the compressor constant 0.2 %.
+  ``sim_adapters.FLOW_HOLD``, ``sim_home_assistant.PUMP_ON_RPM`` and
+  ``PUMP_STALE`` say what the record shows of them. See
+  :doc:`/reference/simulator-inputs` and
+  :doc:`/explanation/standby-loss`.
+
+- **A window opening drops a running element mode: from the record.**
+  The simulator drops an element mode to the heat pump at a window's
+  start, which was assumed from one device run at a TOU switch-on. The
+  record has 18 openings with an element mode in force (2026-01-01 to
+  10-02): every one dropped it within 2 s, 15 at the window's scheduled
+  start and 3 at TOU switched back on inside a window. The model is
+  unchanged. See :doc:`/how-to/schedule-operation`.
+
+Fixed
+-----
+
+- **Without an air sensor, the standby loss is fitted on the heater's
+  idle reading.** It was fitted on the heater's running reading,
+  interpolated from one run to the next, on the quiet windows with a
+  run within ``HEATER_AIR_BRACKET`` (6 h, now removed) of both ends.
+  The night air dips below that line: at one installation, against a
+  sensor beside the heater, those windows read 3.9 °F warm on average
+  (7.8 °F on windows over 12 h), and the loss 5 % high on 150 of 378
+  windows, 21 % high on 54 from 2026-06-25. The idle reading, the
+  cabinet's less ``sim_adapters.IDLE_CABINET_WARM_F``, reads every
+  window: the loss comes out 0.7 % high on all 378, and 0.3 % low on
+  the 188 from 2026-06-25 (2.2 % low with the cabinet's warmth measured
+  before then). The frame has a new column, ``heater_cabinet_f``. See
+  :doc:`/how-to/calibrate-simulator`.
+
+- **The site's standby loss and gap constant are the refits that
+  score better held out.** ``site_example_params`` kept the earlier
+  standby law (``UA`` 4.605, exponent 0.186, no bottom loss) and gap
+  constant (60.06 h), though the calibration with ``keep_better`` on
+  the record replaces both. Fitted on 378 quiet windows to 2026-10-24,
+  the law is a flat ``UA`` of 4.48 BTU/hr per °F with a 90.8 BTU/hr
+  bottom loss (gate 1.83 °F). The gap constant, fitted on 127 windows
+  with that bottom loss opening the gaps it relaxes, is 26.7 h. Held
+  out, the pair tracks the probes' fall within 0.066 °F/h against
+  0.096 (56 windows) and the gap at 0.69 °F² against 1.78 (32
+  windows). Recalibrated with them as the base, every group keeps
+  them. The compressor, power and COP terms keep theirs (the refits
+  scored no better). See :doc:`/explanation/standby-loss`.
+
+- **The ungated circulation share is the library's own fit.**
+  ``site_example_params``' ``DrawParams.ungated_observability`` was
+  0.398, measured outside the library at the run model's earlier
+  terms, and the library's ``fit_ungated_observability`` never
+  reproduced it (0.200 at those terms on the same record). It is now
+  0.263, that fit on 165 windows from April to October at the current
+  run model; 0.117 on the windows since September. It prices the runs
+  inside a metered COP cycle: held out, the latest 45 cycles' median
+  error is 6.1 % against 6.3 % with 0.398. See
+  :doc:`/explanation/standby-loss`.
+
+- **High Demand's element restarts later in a stint.** After the entry
+  run the simulator never ran High Demand's element again. On the
+  record it restarts the upper element with the upper zone about 4 °F
+  short of the setpoint (the four restarts of 2026-04-26/27 at 3.78 to
+  4.14 °F, each about 3 minutes to the setpoint), the measured
+  ``ElementParams.upper_reengages_below_setpoint_f`` (4.1 °F) that
+  nothing read. The controller now starts it there
+  (``controller.later_upper_on``, trigger ``high_demand_upper_short``,
+  also in ``attribution``). Electric's later starts are still not
+  modelled and still flagged: no Electric stint on record ran half an
+  hour. See :doc:`/explanation/simulator`.
+
+- **A circulation run's return is not at the air.** The run model took
+  the returning water at the air beside the heater and the pipe as
+  cooled between runs. On 123 runs with the compressor off (April to
+  October), the return rested about 7 °F above the heater's air, and a
+  run within an hour of another took about half the heat of one after
+  a long rest. ``CirculationParams`` gains ``return_rest_offset_f`` and
+  ``return_cool_tau_h`` (defaults 0, the old form): the inflow is the
+  air plus the offset, and a run's gallons are scaled by the share of
+  the pipe cooled since the last run (``circulation.cooled_share``).
+  ``calibration.fit_return`` fits the volume and both terms together;
+  ``measure_runs`` records each run's rest, and ``run_heat_btu``,
+  ``metered_withdrawn`` and ``fit_ungated_observability`` take the
+  terms. The site's terms are 19.36 gal, 7.84 °F and 0.464 h, a
+  cross-validated error of 268 BTU a run against 767 for the old form.
+  The volume is effective: the long runs on the record never brought
+  hot water back. Snapshot and window runs are now ``(minutes, upper,
+  rest hours, minutes run before)``, and a run a snapshot takes up
+  partway is priced from where it was. See :doc:`/reference/simulator-inputs` and
+  :doc:`/explanation/standby-loss`.
+
+- **The R-134a properties are CoolProp's.** The refrigerant table,
+  cited as "ASHRAE Standard 34" (a safety classification, not a property
+  table), had the saturated vapour density about 4x low and the liquid
+  enthalpy 14 to 40 BTU/lb high, so the condenser's latent heat fell to
+  9.7 BTU/lb at 160 °F against a true 52.7. It is now CoolProp 8.0.0's
+  every 5 °F. On the record's mixed-tank heating, the model's rate now
+  falls 24 BTU/hr per °F of tank and rises 48 per °F of air, against
+  the record's 28 and 53 (the old table: 12 and 34). The site's
+  compressor constant is refit to 0.0160 ft³/s, a compressor of about
+  8 cc at 3,500 rpm (the old 0.0499 was four times that, to make up the
+  density). The power scale is carried to 1.640 and the COP terms to
+  0.688 and 0.002. The durations score the same: 27.0 min mean error
+  on 177 recoveries, against 27.2.
+- **The compressor fit holds the evaporator approach.** With the true
+  properties the durations no longer place the approach: K and the
+  approach together reached the site's error from 6.9 °F, where the
+  evaporator coil reads 19.6 °F below the air. ``fit_compressor`` now
+  fits ``compressor_constant`` alone, at the parameters'
+  ``evap_approach_f``. ``CompressorParams.evap_approach_f`` defaults to
+  the coil's 19.56 °F and is labelled measured. ``K_BOUNDS`` is
+  0.004-0.08, and ``INITIAL_K``, ``INITIAL_APPROACH_F`` and
+  ``APPROACH_BOUNDS`` are gone. See :doc:`/reference/simulator-inputs`.
+
+- **The circulation share's story.** ``DrawParams.ungated_observability``
+  was described as the probes' share of a run's heat. The loop heat it
+  divides counts all the loop's flow as the tank's, but the return
+  feeds the mixing valve's cold port as well as the tank's inlet, and
+  that split is not measured. The share is the split and any probe
+  shortfall together (its refit to 0.263 is above). See
+  :doc:`/explanation/standby-loss`.
+
+- **The upper zone's hold through a recovery rests on the record.** The
+  two-zone model warms the lower zone alone while the tank is
+  stratified and holds the upper where it started. On 30 compressor-only
+  recoveries the upper probe fell a median 0.54 °F while the gap was
+  over 3 °F and rose to 1.26 °F above its start over the gap's last 2 to
+  3 °F, so the hold stays. See :doc:`/explanation/simulator`.
+
+- **The outlet lag is the tank's.** ``ReadinessParams.delivered_lag_gal``
+  (5 gal) was described as mostly the pipe to the fixture. Both bath
+  figures behind it, 7.3 gal at the tub spout and 5.3 at the valve
+  outlet, were taken net of the pipe to each thermometer, and they
+  differ by calibration, not place. The lag is the tank water above the
+  upper probe, and the field is now labelled the heater's. The value is
+  unchanged. See :doc:`/reference/simulator-inputs`.
+
+- **The draw windows' reach rests on the record.** ``HEATER_DRAW_REACH``
+  stays 60 minutes. Its reason was that a draw "can come that much
+  earlier than any the forecast has seen", which nothing measured. On 44
+  complete forecast issues (98 long draws), 60 minutes covered 94.9% of
+  long draws and 30 minutes 89.8%; the five covered only at 60 fell
+  either side of a 30-minute window. See :doc:`/how-to/simulate-heater`.
+
+- **The heater's idle air reading is corrected.** Idle, the heater's
+  own air sensor reads its cabinet: on the record (February to October)
+  6.2 °F above a sensor beside the heater on average, 9.3 in February to
+  4.8 in October. ``sim_adapters.environment(status)``, and so the live
+  scenario and a replay without recorded air, now take
+  ``IDLE_CABINET_WARM_F`` (6.2 °F) off an idle reading. That cuts the
+  average error from 6.3 to 2.2 °F. The ``ambient_from_idle_cabinet``
+  reason still names it. See :doc:`/reference/simulator-inputs`.
+
+- **The Home Assistant air fit settles 5 minutes into a run.**
+  ``sim_home_assistant.RUN_SETTLE`` was 2 minutes, against the book's 5
+  (``sim_adapters.HEATER_AIR_SETTLE``). It is now that constant. On the
+  record the reading runs a median 2.1 °F warm in a run's third minute
+  and 1.8 in its fifth.
+
+- **The fan airflow's source.** ``CompressorParams.fan_airflow_cfm``
+  (229) was cited as the NWP500's specification. No airflow is
+  published; the manual's 229 is the 50 gal model's shipping weight in
+  pounds. The value stays: on 178 recorded recoveries the latent term it
+  sizes is at most about 150 BTU/hr, humidity's own effect is not
+  resolved, and the term off scored 0.6 min worse held out.
+
+- **The 50 and 80 gal models are scaled by rated storage.** Their tank
+  volume, the book's count of it and its empty point were scaled from
+  the 65's by nominal size (48.6 and 77.8 gal). The manual's
+  specification table rates them at 45.2 and 76.1 gal, against the
+  65's 63.2. ``defaults.NOMINAL_GAL`` is now ``RATED_GAL``.
+
+- **A held mode landing over the setpoint starts nothing.** On
+  2026-09-21 Energy Saver, held through a TOU window, landed at its
+  close with the upper tank 18.7 °F above a 107.6 °F setpoint and the
+  lower tank 20.9 °F under it. Nothing started for 9 h 56 min, and the
+  start came 2 min 17 s into a circulation run. The simulation started
+  the compressor at the landing, and again on the lower trigger, since
+  it treated Energy Saver's trigger as a plain level test. Three rules
+  change:
+
+  - A mode write starts the compressor on a short lower tank
+    (``mode_write_lower_starts_f``) out of an element mode whatever the
+    upper tank, as before (19 of 19), and otherwise only with the upper
+    tank short too.
+  - Energy Saver holds the lower trigger while the upper tank is at or
+    above the setpoint, as Heat Pump does, and a draw's drop under the
+    setting starts it. ``tou_triggers.LOWER_HOLD_MODE`` is now
+    ``LOWER_HOLD_MODES``, and ``autonomous_start`` takes
+    ``drop_starts``.
+  - A mode write held in a window is judged as a write in the window is
+    (``window_write_starts_f``). Before, it always charged a start. Two
+    held Energy Saver writes with the compressor off, 2.4 °F short and
+    27.5 °F over, started nothing for hours.
+
+  Documented in :doc:`/explanation/what-starts-a-recovery`.
+
+- **A recovery that ends during a draw books only what follows.** The
+  book anchored at such a recovery's end and then booked the movement
+  again from its start, on the premise that the probes at the anchor
+  showed none of it, the cold water lying below the lower probe. The
+  lower probe falls at once with a draw. On the record from 2026-02-14
+  to 10-24 the rule fired 5 times, each a circulation run with at most
+  0.03 gal of household draw, and walked to the next clean anchor it
+  scored a mean absolute error of 9.92 gal against 9.55 without it.
+  ``book_steps`` and ``calibration.book_walk`` now book the movement
+  from the anchor's own step on, its probes reading the step's start.
+
+- **A draw window runs cold once its delivery falls below the line.**
+  A window counted as depleted only when the delivery fell more than
+  3.4 °F below the line or stayed below it more than 3 minutes, an
+  allowance for the upper probe dipping during a draw. That dip was
+  measured during an Electric recovery on 2026-09-20, with no draw, and
+  no draw on the record shows one: on 535 clean draws the upper probe's
+  fall by the draw's end was a median 0.00-0.72 °F by size, and none
+  came back 1 °F or more within 10 minutes. The simulated delivery has
+  no transient either, so the allowance only hid real crossings, up to
+  about 1.7 gal past the line. Removed: ``ReadinessParams.dip_f`` and
+  ``dip_min``. A parameters document that still carries them loads, and
+  ``unknown_fields`` doesn't name them.
+
+- **The evaporator moves 0.6 °F per °F of air, not one for one.** The
+  compressor's physics held the evaporator a fixed approach below the
+  air, so its capacity followed the air too closely. Over 377
+  compressor runs at one installation, the coil read 6.7 + 0.596 × the
+  air beside the heater (air 48-86 °F), and a free fit on 142 recorded
+  recoveries' durations chose a slope of 0.62. With the coil's slope and
+  the compressor constant and approach refit (0.0499 and 18.69 °F at
+  65 °F air, on the old refrigerant table; both are replaced above),
+  the 35 recoveries held out came out 32.0 min off on
+  average, against 34.2 for the fixed approach refit on the same split
+  and 36.5 as shipped. The bias below 60 °F air went from +14.3 to
+  +4.4 min, and above 75 °F from -7.6 to +3.5. The coil's live reading
+  (``active_cycle``'s ``evaporator_f``) now sits in the same frame: as
+  the evaporator it fits with an offset of 0.0 °F. Added:
+  ``CompressorParams.evap_air_slope`` (1, a fixed approach, for a
+  document without it) and ``physics.compressor.evaporator_f`` and
+  ``EVAP_REF_AIR_F``. ``evap_approach_f`` is now the approach at 65 °F
+  air.
+
+- **The heat book converts gallons at the mains, not the pipe at
+  rest.** A book built from a record converted its heat to gallons at
+  the inlet probe's median over the last 3 hours. At rest the probe
+  tracks the air around the pipe. Now the book reads the mains from the
+  long draws in its own record, as ``cold_supply`` does: the probe's
+  median over the last 2 minutes of each household draw of 11 minutes
+  or more with circulation off. Without one it takes
+  ``BookParams.inlet_default_f``. Over 2026-09-21 to 10-24, against the
+  plateaus, the inlet's mean error went from 3.85 °F (up to 14.2) to
+  0.97 °F (up to 3.3). ``Booked.inlet_measured_share`` is now 1 when the
+  inlet is read from a long draw and 0 when it is the default. Added:
+  ``book.mains_f``. Removed: ``BookParams.inlet_window_s``. A parameters
+  document that still carries it loads, and ``unknown_fields`` doesn't
+  name it. The docs now give the mains by season
+  (:doc:`/explanation/draws`): ``draw.inlet_temp_f``, 72.4 °F, is a
+  September value.
+
+- **A draw's probe response follows the tank's gap.** A delivered draw
+  moved the probes the same way whatever the tank's state: the bulk
+  fell by its apparent heat and the gap opened 1.235 °F per withdrawn
+  gallon. The recorded lower probe falls further the wider the gap at
+  the draw. Now the water let in reaches the lower probe by a share
+  that grows with the gap, and the upper probe falls 0.05 °F per
+  delivered gallon (``physics.draw.probes_after_draw``). On 535 clean
+  draws from 2026-02-21 to 10-23, the lower probe's mean absolute error
+  10 minutes after the draw went from 0.48 to 0.35 °F under 1 gal, 1.68
+  to 0.91 at 1-3 gal, 3.70 to 2.12 at 3-8 gal, 6.72 to 3.52 at 8-20 gal
+  and 8.78 to 6.48 over 20 gal; its bias went from -1.75 to -0.03 °F
+  with the probes within 3 °F and from +1.62 to -0.10 with them apart.
+  On the 136 draws from 08-01, held out of the fit, the lower probe's
+  error went from 2.79 to 1.91 °F. Added: ``DrawParams.reach_gate_f``,
+  ``reach_offset_f``, ``reach_gal`` and ``upper_f_per_gal``;
+  ``physics.draw.probes_after_draw``, ``DEFAULT_REACH_GATE_F``,
+  ``DEFAULT_REACH_OFFSET_F``, ``DEFAULT_REACH_GAL`` and
+  ``DEFAULT_UPPER_F_PER_GAL``; and the ``draw_reach_gate_f``,
+  ``draw_reach_offset_f``, ``draw_reach_gal`` and
+  ``draw_upper_f_per_gal`` arguments of ``decay.project_decay`` and
+  ``decay.draw_step``. ``draw_step``'s ``draw_observability`` takes
+  None, which leaves the tank as it was. Removed:
+  ``DrawParams.gap_open_f_per_gal``; ``physics.draw.gap_opened_f`` and
+  ``DEFAULT_GAP_OPEN_F_PER_GAL``; the ``draw_gap_open_f_per_gal``
+  arguments of ``decay.project_decay`` and ``decay.draw_step``; and
+  ``draw_step``'s ``tank``. ``DrawParams.observability`` still prices a
+  draw's heat and turns delivered draws on. A parameters document that
+  still carries ``gap_open_f_per_gal`` loads, and ``unknown_fields``
+  doesn't name it.
+
+- **The heat book counts all its heat.** The book held back the heat
+  that landed in a draw's cold water, the heat pump's and the lower
+  element's, until that water passed 100 °F, or until the lower probe,
+  having read it below 100 °F, read 100 °F again. On the two recorded drawdowns where it held
+  heat back, its answer at the start under-read the gallons delivered
+  to the line by about 9 gal; counting all of it read within about 4.
+  Now all booked heat is drawable, the deliverable gallons, readiness
+  and the upper zone through a draw alike, and a spent tank's delivery
+  falls to the inlet. Removed: ``BookParams.cold_release_f``;
+  ``Booked.cold_gal``, ``cold_f``, ``cold_seen``, ``withheld_btu`` and
+  ``observed``; ``book.projected_release``; ``book.Step.lower_element``;
+  ``WalkCarry.drawn`` and ``bottom``; the ``withheld_btu`` arguments of
+  ``book.deliverable_from_heat``, ``probe_line_gal`` and
+  ``delivery.deliverable``; ``calibration.withheld_btu`` and
+  ``zone_empty_point`` (with nothing held back it is ``empty_point``'s
+  median); and ``book_walk``'s ``withheld``, ``cold_gal``, ``cold_f``,
+  ``cold_gal_after`` and ``cold_f_after`` columns. ``Booked.heated``
+  takes one heat, ``ready.Added`` has one ``heat_btu`` in place of
+  ``bottom_btu`` and ``top_btu``, and ``book.draw_out`` returns the
+  heat alone. ``zone_empty_btu`` keeps its value. A parameters document
+  that still carries ``cold_release_f`` loads, and ``unknown_fields``
+  doesn't name it.
+
+- **With a heat book, a draw moves the lower probe at once.** With a
+  book, the simulated lower probe held where a draw found it until the
+  book's cold region reached about 9 gal, then settled over 5 hours
+  toward the draw's calibrated response, which left it 3 to 10 °F warm
+  after draws of 3 to 20 gal. The recorded lower probe falls on every
+  draw at once and neither rebounds nor keeps falling. Now a draw moves
+  the lower probe by its calibrated draw response at once, as it does
+  without a book; the book still takes the upper probe down. Removed
+  with the old behavior: ``BookParams.lower_probe_gal``,
+  ``front_width_gal`` and ``front_settle_min``; their fits
+  ``calibration.front_frame``, ``fit_front``, ``FrontFit``,
+  ``settle_tails``, ``fit_front_settle`` and ``SettleFit``;
+  ``book.front_share``, ``front_start_gal``, ``lower_after_draw_f`` and
+  ``front_cannot_move``; ``physics.draw.settled_lower_f`` and
+  ``unsettled_after_f``; ``HeatLedger.front_moves_at``,
+  ``LedgerZones.settle_min`` and ``inlet_f``, ``AfterDraw.lower_f``,
+  ``spent`` and ``inlet_f``, ``UpperAhead.inlet_f`` and
+  ``DrawTaken.heating``; and ``draw_lower`` of ``TankPhysics.coast``
+  and ``decay.project_decay``. ``simulate``'s ``draw_hold_factor`` is
+  gone too: it held a recovery for a share of each draw the probes were
+  taken to miss, which nothing measured. A recovery model now reads
+  ``lead_draws`` without it. A parameters document that still carries
+  the removed ``book`` terms loads, and ``unknown_fields`` doesn't name
+  them.
+
+- **A Home Assistant restart no longer loses the heat book.** A restart
+  leaves the heater and the flow unknown for a few minutes, and the book
+  broke there: there was no book until the next anchor, often hours
+  later. ``book_from_changes`` and ``HomeAssistantBook`` now walk across
+  a span the heater wasn't heard or an entity was unavailable, holding
+  each value from before it, as if it were seen. The flow holds a
+  minute and the pump's speed five, so a draw or a run going in doesn't
+  run on for the whole outage.
+
+- **Readiness reads the tank from its probes.** Without a heat book,
+  the deliverable gallons are now the tank's heat as its two probes
+  place it, as the book's anchor reads it, plus ``delivered_lag_gal``,
+  for any state with the upper probe at or above the line. A tank whose
+  probes read full no longer has 13.5 gal taken off; a tank with its
+  probes apart reads its probes' heat instead of 0; a cold lower probe
+  no longer caps the answer at 6.5 gal; and a running heater no longer
+  holds the answer back, now or along a projected recovery. With
+  evidence, the answer is the larger of the evidence's and the probes'.
+  On one installation, a drawdown from 136.4/111.4 °F delivered 31.1 gal
+  where this says 34.5, and two from uniform tanks matched it.
+  ``sim.delivery.probes_gal`` replaces ``full_tank_floor_gal`` and
+  ``hot_to_the_lower_probe``. Removed: ``ReadinessParams.full_hidden_gal``,
+  ``cold_lower_cutoff_f``, ``cold_lower_cap_gal`` and
+  ``full_setpoint_band_f``; ``calibration.cold_lower_cap``;
+  ``Deliverable.thermocline_unlocated``, ``colder_than_evidence``,
+  ``no_evidence`` and ``from_probes``; ``TankNow.heating``; the
+  ``setpoint_f`` and ``heating`` arguments of ``delivery.deliverable``;
+  and the reasons ``thermocline_unlocated``, ``colder_than_all_evidence``,
+  ``no_evidence_for_state`` and ``estimated_from_probes``
+  (``ready.NO_EVIDENCE_FOR_STATE``, ``ESTIMATED_FROM_PROBES``). A
+  parameters document that still carries the removed parameters loads
+  without them (``params.RETIRED_FIELDS``).
+
+- **The heat book anchors while the heat pump runs.** The book anchored
+  only when a recovery ended, so a book lost to a restart, or an old one
+  drifting, waited for the recovery's end, often hours. Now a step with
+  the heat pump running alone, both probes within ``uniform_band_f`` and
+  nothing drawn or circulated in it anchors too, once the heat pump has
+  run the new ``BookParams.anchor_run_min`` (15 minutes of its running
+  time) since a draw after the last anchor. The book walked along a
+  simulation anchors the same way. A quiet tank after a draw still
+  doesn't anchor: in a mixed tank the lower probe shows only about a
+  third of a small draw's heat.
+
+- **A draw flow can count tank water.** The heat book read every
+  gallon of its flow as delivered through the mixing valve, debiting
+  only its hot share of tank water. A flow from a meter or a detector
+  on the heater's hot outlet counts tank gallons, so the book debited
+  about a quarter of each draw too little (a 141 °F tank behind a valve
+  delivering 122 °F) and promised hot water that wasn't there. ``book_from_history``,
+  ``book_from_changes``, ``fit_book`` and ``HomeAssistantBook`` take a
+  new ``flow_volume``: ``"delivered"``, the default and the reading
+  until now, or ``"tank"``, each gallon priced at the upper probe less
+  the inlet. ``simulate run`` reads it from ``[home_assistant]``'s
+  ``draw_flow_volume``. The shipped empty points
+  (``BookParams.empty_btu``, ``zone_empty_btu``) were booked as
+  delivered gallons, so a tank-water book takes them refit on its own
+  record (``calibration.empty_point``, keeping ``zone_empty_btu`` as far
+  below it): booked as tank water, a drawdown leaves less heat at the
+  line.
+
+Removed
+-------
+
+- **The COP fit's lead share.** With a meter, the COP fit charged a
+  share of the draws in the 30 minutes before each cycle, because the
+  start reading was taken to miss their cold water. The probes see a
+  draw's cold water at once, and on the record the term did not earn
+  its place: trained on 221 metered cycles (2026-02-14 to 2026-10-24)
+  and scored on the latest 55, it fitted a share of 0.19 and scored a
+  median relative error of 0.077 against 0.082 without it, and a mean
+  of 0.116 against 0.112. ``calibration.metered_lead``,
+  ``PowerFit.lead_share``, ``CopCycle.lead_wh``, the snapshots'
+  ``draw_lead_gal`` and the ``lead`` arguments of ``calibrate``,
+  ``fit_power``, ``fit_cop_scale`` and ``cop_cycles`` are gone;
+  ``solve_cop_scale`` returns ``(scale, startup_wh)`` and
+  ``solve_cop_fit`` ``(scale, startup_wh, lift_coeff)``. A draw in the
+  30 minutes before a cycle still keeps it out of the draw-free fit
+  (``DRAW_LEAD``). The site's COP terms were fitted without a meter
+  and are unchanged.
+
+Version 9.12.1 (2026-10-23)
+===========================
+
+Fixed
+-----
+
+- **simulate run books the tank from Home Assistant.** Given the
+  sources' ``[home_assistant.heater]`` table and the new
+  ``draw_flow`` entity, the run walks from the tank's booked heat
+  (``HomeAssistantBook``), and "deliverable now" reads it: a tank with
+  its probes apart read 0 gal from the probes alone, the history
+  unused.
+
+Added
+-----
+
+- **simulate run's bath and showers.** The table gives the bath and
+  the whole showers the tank is ready for (``sim.time_to_ready``), and
+  when the heat pump has the bath ready; ``--bath`` and ``--shower``
+  give the volumes.
+
+Changed
+-------
+
+- **The package's metadata is in pyproject.toml.** Name, dependencies,
+  extras, classifiers and the ``nwp-cli`` entry point moved from
+  ``setup.cfg`` to the standard ``[project]`` table, and ``setup.py`` is
+  gone. The built package installs the same files and requirements.
+
 Version 9.12.0 (2026-10-23)
 ===========================
 
@@ -111,7 +594,7 @@ Changed
   says so in ``defaults_used`` (#232). They raised in every walk, and a
   book left them unpriced. ``sim_adapters.with_circulation_terms`` does
   this for the books.
-- A status in Standby is Power Off, as the NaviLink app counts it (#232).
+- A status in Standby counts as Power Off (#232).
   It raised.
 - ``book_from_changes`` books from the flow's first reading when its
   history starts later than the window, rather than raising (#232).
@@ -487,7 +970,7 @@ Added
   ``TOUPeriod``, the cloud's model, reading the controller's 40-slot table
   whole (a ``TOU_PLAN`` read's payload byte is the last slot, not a
   length; ``build_tou_read()``). ``write_tou_records()`` stores a plan of
-  up to twelve intervals (``build_tou_write()``: the NaviLink app's clock
+  up to twelve intervals (``build_tou_write()``: an 8-byte clock
   header, then the records in the read layout) and reads it back. It
   refuses to write over a longer stored plan, whose extra intervals no
   Bluetooth write can clear, and raises ``TouWriteError`` when the
@@ -498,8 +981,8 @@ Added
   (``MSCD``) and ``SoftwareInfoBlock`` (``MSWD``) use the cloud models'
   field names for the fields matched against them.
   ``read_sub_status()`` decodes the ``SSD`` block into two DIP-switch
-  words (``SubStatus``), using the layout Navien's boiler service toolkit
-  reads; it is unconfirmed on the NWP500.
+  words (``SubStatus``), using the boiler layout; it is unconfirmed on
+  the NWP500.
   ``read_status()`` returns live status: the class-50 session command 200
   makes the heater push the ``RTMD`` block about every 300 ms until the
   connection closes, and ``RealTimeStatus`` decodes the fields checked
@@ -524,10 +1007,10 @@ Added
   (``/user/get-push-settings``, ``/user/set-push-settings``),
   ``record_filter_change()`` / ``record_cip_change()`` and
   ``get_filter_history()`` / ``get_cip_history()`` (the cloud's maintenance
-  log; dates are sent ``YYYY-M-D`` without zero padding, as the app does),
+  log; dates are sent ``YYYY-M-D`` without zero padding),
   ``get_display_preferences()`` / ``set_display_preferences()``
-  (``/device/preferences/format``; the cloud rejects it for the NWP500,
-  the app only uses it for the IoT-module hydro unit), ``get_user_profile()`` (``/user/info``),
+  (``/device/preferences/format``; the cloud rejects it for the NWP500;
+  it serves the IoT-module hydro unit), ``get_user_profile()`` (``/user/info``),
   ``get_firmware_detail()`` (``/firmware/info``; ``run_time`` is the
   estimated update time in minutes), ``delete_tou()``
   (``DELETE /device/tou``), ``get_manufacture_id()``,
@@ -537,24 +1020,24 @@ Added
   ``get_app_version()`` (unauthenticated; a 403 maintenance notice is
   returned as ``server_check_text``; ``nwp500.get_app_version()`` asks
   before sign-in, without a client). ``set_push_settings()`` keeps the
-  current value of a flag left ``None``, since the app always sends
-  every flag. ``get_error_history()`` entries carry the list's
+  current value of a flag left ``None``, since the cloud expects every
+  flag. ``get_error_history()`` entries carry the list's
   ``timeZone`` (``time_zone``, ``occurred_at_local``). New models: ``PushSettings``,
   ``DeviceInstaller``, ``FirmwareDeviceGroup``, ``FirmwareDetail``,
   ``DisplayPreferences``, ``SimpleDevice``, ``DeviceErrorHistoryEntry``,
   ``MaintenanceHistoryEntry``, ``UserProfile``, ``AppVersionInfo``. Push
   flags are 1 = on, 2 = off, the reverse of the device's on/off flags, and
   decode to ``True``/``False``/``None``. ``Device.installer`` and
-  ``Device.alarm_info`` are parsed from ``/device/info`` as the app does;
+  ``Device.alarm_info`` are parsed from ``/device/info``;
   ``TOUSchedule.nickname`` is modelled.
 - **AWS credentials renew without the password.**
   ``NavienAuthClient.refresh_session()`` posts to ``/auth/session/refresh``
   with the access token and updates only the AWS credential fields the
-  server returns, as the app does when the MQTT connection fails with an
-  auth error. ``secured_sign_in()`` posts to ``/user/secured-sign-in`` with
+  server returns; it is the step used when the MQTT connection fails with
+  an auth error. ``secured_sign_in()`` posts to ``/user/secured-sign-in`` with
   the access token and overlays whatever token fields come back (observed
-  live: the AWS credentials only; the JWTs are kept), which the app uses
-  for auto-login. When the AWS credentials expire, ``ensure_valid_token()``
+  live: the AWS credentials only; the JWTs are kept), the auto-login
+  step. When the AWS credentials expire, ``ensure_valid_token()``
   and the context manager's stored-token check now try session refresh,
   then secured sign-in, and only then the password sign-in; both token
   steps are skipped when the access token has expired and cannot be
@@ -569,14 +1052,14 @@ Added
   control command it publishes on ``cmd/52/navilink-{mac}/res/ctrl-fail``
   instead of acknowledging it; the library silently dropped that message.
   It is now parsed into ``ControlFailResponse``
-  (``ControlFailCode.DHW_CONTROL_INTERVAL_EXCEEDED`` = 2 is the only code
-  the app interprets: the previous DHW control was too recent) and emitted
+  (``ControlFailCode.DHW_CONTROL_INTERVAL_EXCEEDED`` = 2 is the only known
+  code: the previous DHW control was too recent) and emitted
   as the ``control_failed`` client event (``ControlFailedEvent`` with
   ``own_command`` and ``reason``) for every device subscription, with a
   WARNING log. ``subscribe_control_fail_response()`` /
   ``unsubscribe_control_fail_response()`` add a plain callback.
 - **MQTT Last-Will and app-connection presence.** Set
-  ``MqttConnectionConfig.last_will_device`` to register the app's Last-Will
+  ``MqttConnectionConfig.last_will_device`` to register a Last-Will
   on ``evt/52/navilink-{mac}/app-connection`` (``event.connection.status``
   0, QoS 1) so other clients learn when this one drops; every rebuilt
   connection carries it. ``subscribe_app_connection()`` /
@@ -584,24 +1067,22 @@ Added
   ``AppConnectionEvent`` and emit ``app_connection_received``
   (``AppConnectionReceivedEvent``). New ``MqttTopicBuilder`` helpers
   ``control_fail_response_topic()`` and ``app_connection_topic()``.
-- **``DeviceStatus.air_filter_remaining_hours``**: the app's remaining
+- **``DeviceStatus.air_filter_remaining_hours``**: the remaining
   filter life (``None`` when the reminder period is 0, else clamped at 0).
-- **``DeviceStatus.minor_code``** (``minorCode``): the secondary alarm code
-  the app shows as ``R%03d``; 101 is the one it lets the user reset.
+- **``DeviceStatus.minor_code``** (``minorCode``): the secondary alarm code,
+  formatted as ``R%03d``; 101 is the one a user can reset.
   Defaults to 0 for payloads that omit it.
-- **``DhwOperationSetting.STANDBY`` (0)**, the app's
-  ``MgppOperationMode.STANDBY``. ``DeviceStatus.dhw_operation_setting``
+- **``DhwOperationSetting.STANDBY`` (0)**, the device's Standby mode.
+  ``DeviceStatus.dhw_operation_setting``
   previously rejected a 0. It is status-only: ``set_dhw_mode()`` refuses
   it, as it now refuses any id outside 1-6. ``sim_adapters.settings()``
   refuses a Standby status, which the simulator does not model.
-- **``DREvent.GRID_EMERGENCY`` (6).** The app declares CPE and Grid
-  Emergency both as id 5 but decodes ``drEventStatus`` by array position,
-  so raw 6 is Grid Emergency; ``CPE`` (5) stays "Customer Peak Event".
+- **``DREvent.GRID_EMERGENCY`` (6).** Raw 6 is Grid Emergency; ``CPE`` (5) stays "Customer Peak Event".
 - **``UnitType``** NCB700 (22), NFB700_H (24), CAS_NFB700_H (25),
   NPF_SYSTEM (514); **``DeviceType``** IOT_MODULE (8), NFB700_MAIN (50),
-  NFB700_SUB (51) (the app's names; ``NPF700_MAIN``/``NPF700_SUB`` remain
-  as aliases) and ``HPWH`` as an alias of 52, which is the NWP500
-  (``DefineData.HPWH_MODEL``), not an NPF700 WiFi module. A dumped device
+  NFB700_SUB (51) (``NPF700_MAIN``/``NPF700_SUB`` remain as aliases) and
+  ``HPWH`` as an alias of 52, which is the NWP500, not an NPF700 WiFi
+  module. A dumped device
   of type 50 or 51 now names it ``NFB700_MAIN`` or ``NFB700_SUB``.
 - **A recovery model's inputs, through ``nwp500.sim.simulate``** (#165).
   Beside ``recovery=``, ``simulate`` takes what a learned model was
@@ -955,11 +1436,10 @@ Added
 
 Changed
 -------
-- **Recirculation mode values follow the NaviLink app.** ``RecirculationMode``
-  had 2 and 3 swapped and 4 wrong: the app's
-  ``MgppRecirculationOperationMode`` (sent by ``recirc-mode`` and decoded
-  from ``recircOperationMode``) is 1 Always on, 2 Weekly, 3 HotButton only,
-  4 No recirculation. The members are now ``ALWAYS_ON``, ``WEEKLY``,
+- **Recirculation mode values corrected.** ``RecirculationMode``
+  had 2 and 3 swapped and 4 wrong: the recirculation mode (sent by
+  ``recirc-mode`` and decoded from ``recircOperationMode``) is 1 Always
+  on, 2 Weekly, 3 HotButton only, 4 No recirculation. The members are now ``ALWAYS_ON``, ``WEEKLY``,
   ``HOT_BUTTON_ONLY`` and ``OFF``; ``ALWAYS`` remains as an alias of
   ``ALWAYS_ON``. **Behaviour change:** ``BUTTON``, ``SCHEDULE`` and
   ``TEMPERATURE`` are removed, since their meanings were wrong; code that
@@ -970,7 +1450,7 @@ Changed
   ``"ALWAYS"``) and ``"WEEKLY"`` for 2 (was ``"BUTTON"``); code keyed on
   the old strings must follow.
 - **Reservation mode 5 is Power Off, not Vacation.** Weekly-schedule
-  entries carry the app's ``MgppReservationMode`` (0 not reserved, 1 Heat
+  entries carry a reservation mode (0 not reserved, 1 Heat
   Pump, 2 Electric, 3 Energy Saver, 4 High Demand, 5 Power Off; there is
   no vacation entry), now the ``ReservationMode`` enum.
   ``ReservationEntry.mode_name`` resolves through it, so a mode-5 entry
@@ -984,20 +1464,19 @@ Changed
   (``update_reservations(kept=)``). Changing such an entry needs a mode
   of 1-5. The simulator's reservation entries take the same numbering
   (``sim.inputs.EntryMode``); only 1-4 are modelled, as before.
-- **``dr_override_status`` is an on/off flag, not hours.** The app decodes
-  it with its 0/1/2 on-off enum and shows "DR applied" when it is 2. The
+- **``dr_override_status`` is an on/off flag, not hours.** It is a 0/1/2
+  on-off value, and 2 means DR applied. The
   field stays an ``int`` but no longer carries an ``hours`` unit; the new
   ``DeviceStatus.dr_override_active`` is True when it is 2.
-- **Air-filter life comes from ``cumulated_op_time_eva_fan``.** The app
-  computes remaining filter life as ``air_filter_alarm_period -
-  cumulated_op_time_eva_fan`` and never reads ``air_filter_alarm_elapsed``.
+- **Air-filter life comes from ``cumulated_op_time_eva_fan``.** Remaining
+  filter life is ``air_filter_alarm_period - cumulated_op_time_eva_fan``;
+  ``air_filter_alarm_elapsed`` is not part of it.
   The two descriptions were the wrong way round; ``cumulated_op_time_eva_fan``
   is fan hours since the last filter reset and ``air_filter_alarm_elapsed``
   is unconfirmed.
-- **``signal_app_connection()`` sends the app's message shape.** It
+- **``signal_app_connection()`` sends the Last-Will message shape.** It
   published ``{clientID, timestamp}``, a shape nothing reads. It now
-  publishes the NaviLink app's ``RequestLastWill`` envelope with
-  ``event.connection.status`` 1.
+  publishes the Last-Will envelope with ``event.connection.status`` 1.
 - Sign-in and ``/auth/refresh`` requests now send the library's
   ``User-Agent`` and ``Content-Type`` headers, as every other request does.
 - **The heater's own air reading is not as close as documented in
@@ -1029,15 +1508,14 @@ Changed
   describe both fields as differences.
 - **Vacation accepts 1-99 days** (#155). ``set_dhw_mode()`` (vacation),
   ``set_vacation_days()`` and ``set_vacation_duration()`` rejected anything
-  over 30 days. The NaviLink app's vacation picker and the front panel
-  (User's Information Manual, section 3.4.5) both offer 1-99, so the
-  library now accepts the same. The ``vacation`` and
+  over 30 days. The front panel (User's Information Manual, section
+  3.4.5) offers 1-99, so the library now accepts the same. The ``vacation`` and
   ``vacation-duration`` CLI commands follow.
 
 Fixed
 -----
-- ``FirmwareInfo.device_group`` was typed as a string; the app reads an
-  object ``{groupSeq, unitNum}`` (plus a top-level ``deviceGroupUnitNo``).
+- ``FirmwareInfo.device_group`` was typed as a string; the cloud returns
+  an object ``{groupSeq, unitNum}`` (plus a top-level ``deviceGroupUnitNo``).
   It is now ``FirmwareDeviceGroup``, with a bare string still accepted.
 - ``convert_tou()`` hard-coded ``userType: "O"``; it now sends the
   signed-in user's type from the sign-in response, defaulting to ``"O"``.
@@ -1072,8 +1550,6 @@ Documentation
   physics with a learned correction, and are removed. The "cold starts
   about 55 min short" figure is replaced by the recorded errors by time
   left. The lower trigger's in-window wait is given with its full count.
-- ``unknown-values``, ``tank-energy`` and the MQTT protocol reference now
-  cite the current NaviLink app release they were checked against.
 - ``docs/openapi.yaml`` and ``rest_api.rst`` describe every endpoint above
   plus ``POST /auth/session/refresh`` and ``POST /user/secured-sign-in``;
   ``mqtt_protocol.rst`` documents ``res/ctrl-fail`` and the
@@ -1111,13 +1587,12 @@ Documentation
   - The ambient effect on the compressor is about 1.18x, not 1.7x; the
     standby soak's figures, the 60 h gap prior and the circulation runs
     behind the lower-zone drop are stated as measured.
-- **Docs that contradicted the code or the vendor's sources** (#155). Each
+- **Docs that contradicted the code or the protocol** (#155). Each
   now has one value with its source:
 
   - The mode-ID table in ``device_features.rst`` numbered Energy Saver 2,
     High Demand 3 and Electric 4. The IDs are Electric 2, Energy Saver 3,
-    High Demand 4, as in ``DhwOperationSetting`` and the NaviLink app's
-    ``MgppOperationMode``.
+    High Demand 4, as in ``DhwOperationSetting``.
   - ``track-energy.rst`` used ``comp_running_minute_total`` and
     ``heater1/2_running_minute_total``, which do not exist. Lifetime run
     times come from the diagnostics query, in hours
@@ -1148,12 +1623,11 @@ Documentation
 - **Flow-rate units corrected** (#154). The protocol reference said
   ``currentDhwFlowRate`` and ``recircDhwFlowRate`` were tenths of a GPM and
   ``cumulatedDhwFlowRate`` was gallons, while the properties treated them as
-  tenths of an LPM and as litres. The properties are right. Navien's
-  NaviLink app (2.01.02, decompiled) shows ``currentDhwFlowRate`` as
-  ``raw / 10`` LPM in Celsius and ``raw / 3.785 / 10`` GPM in Fahrenheit.
+  tenths of an LPM and as litres. The properties are right.
+  ``currentDhwFlowRate`` is ``raw / 10`` LPM in Celsius and
+  ``raw / 3.785 / 10`` GPM in Fahrenheit.
   The NWP500 manual lists the panel's water-flow reading in LPM even though
-  the panel defaults to GPM. The app's diagnostics screen shows the heater's
-  hot-water volume totals in whole litres in either setting. Flow rates are
+  the panel defaults to GPM. Flow rates are
   0.1 LPM and the cumulative counter is whole litres in both unit systems.
   ``device_status.rst``, ``data_conversions.rst`` and ``mqtt_protocol.rst``
   now say so, and ``DiagnosticsDhwUsage`` documents its units (litres, hours,
@@ -1164,7 +1638,7 @@ Documentation
   fixed ``"GPM"`` or ``"gal"`` ``unit_of_measurement``, which contradicted
   their raw units. ``get_field_unit()``, which was already driven by
   ``device_class``, returns the same units as before. New tests pin both
-  flow properties to the app's formula in each unit system.
+  flow properties to these formulas in each unit system.
 
 Version 9.4.3 (2026-10-01)
 ==========================
@@ -1335,31 +1809,30 @@ Fixed
 Version 9.4.0 (2026-09-12)
 ==========================
 
-This release realigns the MQTT command set with what the NaviLink app
-sends. The app (version 2.03.00) was decompiled and its request
-builder compared with the library; every query it sends now has a
-method, six commands it never sends were removed, and the recirculation
-schedule write was corrected. Breaking changes are listed under
+This release realigns the MQTT command set with the NaviLink protocol.
+Every query in the protocol now has a method, six commands that are not
+part of it were removed, and the recirculation schedule write was
+corrected. Breaking changes are listed under
 *Removed* and *Changed*.
 
 Added
 -----
 - **Installer diagnostics query.** ``request_diagnostics()`` /
   ``subscribe_diagnostics()`` and the ``nwp-cli diagnostics`` command
-  return the lifetime counters the app's installer screen shows: heat
+  return the device's lifetime installer counters: heat
   pump and element energy, days since installation, fault event counts,
   demand-response operation times, hot-water draw statistics and
   component run times and start counts, as
   :class:`~nwp500.models.DeviceDiagnostics`. The device answers the
   ``st/td/rd`` query with packed hex; the NaviLink cloud decodes it into
-  JSON only when the reply topic has the app's five-segment form, so the
+  JSON only when the reply topic has the five-segment form, so the
   library requests that form. Verified live: the energies and compressor
   and element run times match the energy query's lifetime totals.
 - **Monthly energy query.** ``request_energy_usage_monthly()`` /
   ``subscribe_energy_usage_monthly()`` and ``nwp-cli energy --years``
   return one entry per year with twelve per-month items. Verified live.
 - **Hourly energy query.** ``request_energy_usage_hourly()`` /
-  ``subscribe_energy_usage_hourly()`` send the app's per-hour query. The
+  ``subscribe_energy_usage_hourly()`` send the per-hour query. The
   NWP500 tested never answered it in four attempts, so it has no CLI
   command.
 - **Recirculation schedule read.** ``request_recirculation_schedule()``
@@ -1376,46 +1849,43 @@ Added
   ``subscribe_firmware_download_info()`` and ``nwp-cli firmware info``
   return :class:`~nwp500.models.FirmwareDownloadInfo`. The device replies
   on its own topic rather than a client-keyed one. Verified live.
-- **Session end.** ``end_session()`` sends the ``st/end`` query the app
-  sends whenever it leaves a device. No reply to it has been observed.
+- **Session end.** ``end_session()`` sends the ``st/end`` query that
+  ends a session with a device. No reply to it has been observed.
   Unlike other commands it is never queued while disconnected (it raises
   ``MqttNotConnectedError``), since a session end replayed after a
   reconnect would end the new session.
 - ``MqttConnectionConfig.send_session_end_on_disconnect`` (default
   ``True``) controls whether ``disconnect()`` sends it.
 - ``subscribe_firmware_commit_response()`` receives the reply to
-  ``commit_firmware_update()``, which is requested on the app-form
+  ``commit_firmware_update()``, which is requested on the five-segment
   ``res/commit-ota`` topic that no other subscription covers.
-- **Controls with app builder cases that had no method:**
-  ``set_vacation_duration(days)`` (``goout-day``; the app has a builder
-  case but no screen that calls it; verified live to change the day count
-  without changing the operation mode),
+- **Controls that had no method:**
+  ``set_vacation_duration(days)`` (``goout-day``; verified live to change
+  the day count without changing the operation mode),
   ``set_air_filter_life(hours)`` (``air-filter-life``; the wire value is
-  hours divided by 500, matching the app's 0 or 1000-10000 picker;
+  hours divided by 500, for 0 or 1000-10000 hours;
   verified live) and ``reset_condenser_fault()`` (``cond-fault-reset``,
-  installer-level in the app; acknowledged live, clearing effect not
+  an installer-level control; acknowledged live, clearing effect not
   observable without a fault). CLI: ``vacation-duration``,
   ``filter-life``, ``reset-condenser-fault``.
-- **Command codes** for every member of the app's ``DeviceControlMGPP``
-  enum, with the declared-but-never-sent ones annotated.
+- **Command codes** for every known control command, with the
+  declared-only ones annotated.
 - ``EnergyUsageResponse.type_of_usage``, ``get_year_data()``,
   ``MonthlyEnergyData.day`` and ``EnergyUsageDay.ep_usage`` /
-  ``water_usage`` (declared by the app; not reported by the NWP500).
+  ``water_usage`` (part of the protocol; not reported by the NWP500).
 
 Changed
 -------
-- **Recirculation schedule models take the app's entry shape** (breaking).
+- **Recirculation schedule models take the reservation entry shape** (breaking).
   :class:`~nwp500.models.RecirculationScheduleEntry` is now
   ``enable``/``week``/``hour``/``min``/``mode``/``param`` like a
-  reservation entry (``mode`` is the entry's pump on/off toggle in the
-  app's editor) and :class:`~nwp500.models.RecirculationSchedule` carries
+  reservation entry (``mode`` is the entry's pump on/off toggle) and :class:`~nwp500.models.RecirculationSchedule` carries
   ``reservation_use`` plus ``reservation`` instead of ``schedule``. The
   previous start/end window fields were not what the device accepts.
 - ``MonthlyEnergyData.month`` is optional: monthly-query entries have no
   month.
 - **``NavienMqttClient.disconnect()`` now sends ``st/end``** to every
-  device that was passed to any subscription, as the NaviLink app does
-  when it leaves a device. The publishes go straight to the connection,
+  device that was passed to any subscription. The publishes go straight to the connection,
   never into the offline command queue, stop if the connection drops,
   are bounded by a short timeout and never fail the disconnect. What it
   does to other clients connected to the same device (for example a Home
@@ -1439,12 +1909,12 @@ Fixed
 -----
 - **``configure_recirculation_schedule()`` published to the wrong topic
   with the wrong keys.** It sent ``{"schedule": [...]}`` on the bare
-  ``ctrl`` topic; the app publishes RECIR_RESERVATION on
-  ``ctrl/recirc-rsv/rd`` with ``reservationUse`` and ``reservation`` and
-  asks for the echo on ``recirc-rsv/rd``.
+  ``ctrl`` topic; RECIR_RESERVATION goes on ``ctrl/recirc-rsv/rd``
+  with ``reservationUse`` and ``reservation`` and asks for the echo on
+  ``recirc-rsv/rd``.
 - **``commit_firmware_update()`` published to the bare ``ctrl`` topic.**
-  The app publishes OTA_COMMIT on ``ctrl/commit-ota`` and asks for the
-  reply on ``res/commit-ota``; the library now does the same. Not
+  OTA_COMMIT goes on ``ctrl/commit-ota`` and asks for the reply on
+  ``res/commit-ota``; the library now does the same. Not
   exercised against a device.
 - **Unsubscribing could remove the wrong handler.** When one callback was
   registered for more than one device-wildcard subscription (status,
@@ -1458,8 +1928,8 @@ Fixed
 - Recirculation read-backs in hex carry the unused ``param`` as ``0xFF``
   and in JSON as ``-1``; the model normalizes to ``-1`` so the two compare
   equal.
-- **Protocol documentation** rewritten from the decompiled request
-  builder and live captures: real topic structure, the anti-legionella
+- **Protocol documentation** rewritten from the protocol and live
+  captures: real topic structure, the anti-legionella
   modes (``anti-leg-on [days]`` / ``anti-leg-off``, not
   ``anti-legionella-setting``), the message example that paired the
   weekly-reservation code with ``dhw-temperature``, the undocumented
@@ -1476,17 +1946,16 @@ Fixed
 
 Removed
 -------
-- **Six MQTT commands the NaviLink app never sends** (breaking):
+- **Six MQTT commands that are not part of the protocol** (breaking):
   ``check_firmware_update()``, ``reconnect_wifi()``, ``reset_wifi()``,
   ``set_freeze_protection_temperature()``, ``run_smart_diagnostic()`` and
   ``update_weekly_reservation()`` with
   ``subscribe_weekly_reservation_response()`` and the
   ``WeeklyReservationEntry`` / ``WeeklyReservationSchedule`` models. The
-  app's enum declares the first five codes but its request builder has
-  no case for them, so the library's ``ota-check``, ``wifi-reconnect``,
-  ``wifi-reset``, ``frez-temp`` and ``smart-diagnostic`` mode strings were
-  invented. The app's weekly schedule is the ordinary reservation
-  program: it writes with 16777226 on ``ctrl/rsv/rd``
+  first five codes are declared only, so the library's ``ota-check``,
+  ``wifi-reconnect``, ``wifi-reset``, ``frez-temp`` and
+  ``smart-diagnostic`` mode strings were invented. The weekly schedule is
+  the ordinary reservation program: it is written with 16777226 on ``ctrl/rsv/rd``
   (``update_reservations()``), never with 33554438 or a ``rsv-weekly/rd``
   topic. The ``CommandCode`` members stay, annotated as declared only.
 
@@ -1552,12 +2021,10 @@ Removed
   waited for a reply on ``res/tou/rd``. No reply ever comes: a live device
   with TOU provisioned (``program_reservation_use`` true, a valid controller
   serial, and a plan the REST API returns in full) stayed silent for 45
-  seconds. ``ctrl/tou/rd`` with that command code is the *write* - it is what
-  :meth:`~nwp500.NavienMqttClient.configure_tou_schedule` publishes and what
-  the vendor app publishes from its TOU editor
-  (``TouScheduleViewmodel.setPublishMgppControlTou``), and the device answers
-  on ``res/tou/rd`` only to confirm such a write. The vendor app reads TOU
-  over REST, which is the only TOU read the protocol has.
+  seconds. ``ctrl/tou/rd`` with that command code is the *write*: it is what
+  :meth:`~nwp500.NavienMqttClient.configure_tou_schedule` publishes, and the
+  device answers on ``res/tou/rd`` only to confirm such a write. REST is the
+  only TOU read the protocol has.
 
   Beyond returning nothing, the call published a write-shaped command with no
   schedule attached. This device ignored it (``touStatus`` was unchanged
@@ -1598,10 +2065,9 @@ Fixed
   unknown keys, so the field silently reported its ``False`` default on
   every device regardless of whether a thermostatic mixing valve was
   supported. The CLI's "Mixing Valve" capability row was wrong for the
-  same reason. The misspelling is Navien's own: it appears in the vendor
-  app's ``KDResponseMgppDid$Feature`` class and in
-  ``docs/reference/protocol/device_features.rst``, which documented the
-  wire spelling correctly all along.
+  same reason. The misspelling is Navien's own:
+  ``docs/reference/protocol/device_features.rst`` documented the wire
+  spelling correctly all along.
 
 - **``firmware_payload_capture.py`` captured almost nothing.** Its wildcards
   covered ``cmd/{type}/{client_id}/res/#`` and the event topic, but the device
@@ -1677,10 +2143,6 @@ Changed
 - **Status flags now preserve the device's unknown state.** The protocol
   encodes these flags as ``0 = unknown, 1 = OFF, 2 = ON``, and the library
   was collapsing 0 to ``False``, inventing an OFF the device never claimed.
-  Confirmed against Navien's own NaviLink app (2.03.00, versionCode 141),
-  which decodes exactly this set of fields through an enum declared
-  ``UNKNOWN(0), OFF(1), ON(2)``; two sibling enums render their zero as
-  ``"-"`` and ``"Not Applied"`` rather than as an off state.
 
   Affected: ``operation_busy``, ``comp_use``, ``anti_legionella_use``,
   ``anti_legionella_operation_busy``, ``heat_upper_use``, ``heat_lower_use``,
@@ -1692,7 +2154,7 @@ Changed
   this is the wanted shape: ``None`` renders as "Unknown" instead of writing
   a fabricated OFF into the recorder database.
 
-- ``OnOffFlag`` gains the vendor's ``UNKNOWN = 0`` member. It previously
+- ``OnOffFlag`` gains an ``UNKNOWN = 0`` member. It previously
   started at ``OFF = 1``, leaving the device's reserved value unrepresented.
 
 - The CLI renders these flags as ``Unknown`` rather than ``No``. Both
@@ -1717,7 +2179,7 @@ Added
   report. ``converters.device_bool_to_python`` is unchanged and remains
   correct for capability flags.
 - New ``docs/explanation/unknown-values.rst`` recording which field families
-  use 0 as a sentinel and which do not, with the app evidence for each.
+  use 0 as a sentinel and which do not, with the evidence for each.
 
 Removed
 -------
@@ -1746,8 +2208,6 @@ Fixed
 - ``dhwTemperature`` is documented as an outlet temperature but is
   measured inside the tank: it tracks ``tankUpperTemperature`` to within
   one 0.5 degC step, and the device has no sensor downstream of itself.
-  Navien's own app agrees, labelling it "DHW Temp." beside the tank
-  thermistors and showing ``dischargeTemperature`` separately.
 - ``docs/explanation/tank-energy.rst`` tabulated ``totalEnergyCapacity``
   and ``availableEnergyCapacity`` at ten times their raw wire values,
   under column headings naming the raw protocol fields. The series had
@@ -1765,19 +2225,16 @@ Fixed
   in the changelog, the model field description and the protocol
   reference.
 - New ``docs/explanation/tank-energy.rst`` records what the two fields
-  measure and the calibration evidence behind the scale change,
-  including that Navien's own NaviLink app (2.03.00, versionCode 141)
-  reads neither field, so no vendor-side corroboration exists.
-
-- Documented that **temperature fields carry no sentinel at all**. The app
-  has no out-of-band constant (no ``0xFFFF``/``-999``/``-1``), no zero-guard
-  in any display path, and formats whatever arrives, so a temperature of
-  zero means zero. This closes a recurring source of bugs where zero-as-none
+  measure and the calibration evidence behind the scale change.
+
+- Documented that **temperature fields carry no sentinel at all**. There
+  is no out-of-band constant (no ``0xFFFF``/``-999``/``-1``), so a
+  temperature of zero means zero. This closes a recurring source of bugs where zero-as-none
   was applied to temperature converters and reported working sensors as
   missing during cold-weather operation.
-- Documented that capability flags are a distinct case: the app hides a
-  feature's entire UI when its DID ``Use`` flag reads 0, so 0 there means
-  "not fitted" and the existing ``bool`` mapping is correct.
+- Documented that capability flags are a distinct case: a DID ``Use``
+  flag of 0 means "not fitted", so the existing ``bool`` mapping is
+  correct.
 
 Version 9.2.1 (2026-07-30)
 ==========================
@@ -2071,8 +2528,8 @@ Bug Fixes
   (default 300 s, ``None`` to disable) are now discarded at send time.
 - **Fix Fahrenheit conversion for sub-zero temperatures** (ASYMMETRIC
   formula): the rounding used Python's floored ``%``, which is always
-  non-negative, while the firmware/app uses a truncated remainder. Raw
-  ``-11`` (-5.5 °C) decoded to 22 °F instead of the app's 23 °F. Now
+  non-negative, while the firmware uses a truncated remainder. Raw
+  ``-11`` (-5.5 °C) decoded to 22 °F instead of 23 °F. Now
   uses ``math.fmod`` semantics.
 - **Fix freeze protection default limits**: the defaults (43/65) were
   Fahrenheit display values stored in raw half-Celsius fields, decoding
@@ -2501,7 +2958,7 @@ Fixed
 - **Vacation mode sent wrong MQTT command**: ``set_vacation_days()`` used
   ``CommandCode.GOOUT_DAY`` (33554466), which the device silently accepted
   but did not activate vacation mode; the operating mode remained unchanged.
-  HAR capture of the official Navien app confirms the correct command is
+  A HAR capture of NaviLink traffic confirms the correct command is
   ``DHW_MODE`` (33554437) with ``param=[5, days]``
   (``DhwOperationSetting.VACATION``). The valid range has also been corrected
   from 1-365 to 1-30 to match the device's actual constraint.
@@ -2574,7 +3031,7 @@ Added
 -----
 - **OpenEI Client Module**: New ``OpenEIClient`` async client (``nwp500.openei``) for browsing utility rate plans from the OpenEI API by zip code. Supports listing utilities, filtering rate plans, and fetching plan details. API key read from ``OPENEI_API_KEY`` environment variable.
 - **Convert TOU API**: ``NavienAPIClient.convert_tou()`` sends raw OpenEI rate data to the Navien backend for server-side conversion into device-ready TOU schedules with season/week bitfields and scaled pricing.
-- **Update TOU API**: ``NavienAPIClient.update_tou()`` applies a converted TOU rate plan to a device, matching the mobile app's ``PUT /device/tou`` endpoint.
+- **Update TOU API**: ``NavienAPIClient.update_tou()`` applies a converted TOU rate plan to a device through the cloud's ``PUT /device/tou`` endpoint.
 - **ConvertedTOUPlan Model**: New Pydantic model for parsed ``convert_tou()`` results (utility, name, schedule).
 - **CLI ``tou rates``**: Browse utilities and rate plans for a zip code (``nwp500 tou rates 94903``).
 - **CLI ``tou plan``**: View converted rate plan details with decoded pricing (``nwp500 tou plan 94903 "EV Rate A"``).
@@ -2588,8 +3045,8 @@ Changed
 
 Fixed
 -----
-- **Week Bitfield Encoding**: Fixed MGPP week bitfield encoding to match NaviLink APK protocol. Sunday is now correctly bit 7 (128), Monday bit 6 (64), ..., Saturday bit 1 (2); bit 0 is unused. Affects all reservation and TOU schedule operations. Verified against reference captures.
-- **Enable/Disable Convention**: Fixed reservation and TOU enable/disable flags to use standard device boolean convention (1=OFF, 2=ON) instead of inverted logic. This aligns with other device binary sensors and matches app behavior. Global reservation status now correctly shows DISABLED when ``reservationUse=1``.
+- **Week Bitfield Encoding**: Fixed MGPP week bitfield encoding to match the NaviLink protocol. Sunday is now correctly bit 7 (128), Monday bit 6 (64), ..., Saturday bit 1 (2); bit 0 is unused. Affects all reservation and TOU schedule operations. Verified against reference captures.
+- **Enable/Disable Convention**: Fixed reservation and TOU enable/disable flags to use standard device boolean convention (1=OFF, 2=ON) instead of inverted logic. This aligns with other device binary sensors. Global reservation status now correctly shows DISABLED when ``reservationUse=1``.
 - **Reservation Set Command Timeout**: Fixed ``reservations set`` subscription pattern that had extra wildcards preventing response matching. Command now receives confirmations correctly.
 - **Intermittent Fetch Bug**: Tightened MQTT topic filter for reservation fetch from ``/res/`` to ``/res/rsv/`` with content validation to prevent false matches on unrelated response messages.
 
@@ -3532,7 +3989,7 @@ Version 6.0.4 (2025-11-21)
 Fixed
 -----
 
-- **Temperature Conversion Accuracy**: Corrected temperature conversion logic based on analysis of the decompiled mobile application. Previous conversions used approximations; new logic uses exact formulas from the app:
+- **Temperature Conversion Accuracy**: Corrected temperature conversion logic. Previous conversions used approximations; new logic uses the exact formulas the protocol uses:
 
   - Replaced ``Add20`` validator with ``HalfCelsiusToF`` for fields transmitted as half-degrees Celsius
   - Replaced ``DeciCelsiusToF`` with ``PentaCelsiusToF`` for fields scaled by factor of 5
@@ -4401,7 +4858,7 @@ Fixed
   - Power-off now uses command code ``33554433``
   - Power-on now uses command code ``33554434``
   - DHW mode control now uses command code ``33554437``
-  - Discovered through network traffic analysis of official app
+  - Discovered through network traffic analysis
 
 - **Bug**: MQTT topic pattern matching with wildcards