nwp500-python 9.4.3__tar.gz → 9.5.0__tar.gz

{nwp500_python-9.4.3 → nwp500_python-9.5.0}/CHANGELOG.rst

@@ -2,8 +2,712 @@
 Changelog
 =========
 
-Unreleased
-==========
+Version 9.5.0 (2026-10-20)
+==========================
+
+Added
+-----
+- **Bluetooth LE access to the controller** (``nwp500.ble``, optional
+  ``ble`` extra). The NWP500 exposes a GATT service that carries the
+  controller's native class-code protocol once the heater is put in pairing
+  mode (with the heater off, hold Back and Power for five seconds; it
+  advertises as ``HPWH1…``). The scan also lists a heater in Wi-Fi setup
+  mode (``HPWH4610``), which answers nothing, and the CLIs pick an
+  ``HPWH1`` heater over it.
+  The package frames and parses those packets (header, class code, address,
+  CRC-16/MODBUS), scans for the heater, and reads data classes with a
+  matched request/reply client; ``python -m nwp500.ble scan`` and
+  ``python -m nwp500.ble read`` dump the blocks. Checked on a unit: it
+  answers a DIP-switch block, error history, four diagnostics counters, the stored
+  time-of-use plan, device info, the controller serial numbers and a
+  software-data block; the boiler parameter classes 51-54 do not answer, so
+  installer parameters are not reachable yet. ``write_block()`` exists for
+  the eventual parameter write and is marked experimental. ``read``
+  dumps the classes the heater answers by default and exits 1 when none
+  answered; the readers that decode a block raise ``CrcMismatchError``
+  on a reply that failed its checksum.
+  ``read_tou_records()`` decodes the stored time-of-use plan into
+  ``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
+  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
+  heater refuses or stores something else. ``TOU_PLAN`` is the only
+  class written so far (``NWP500_WRITABLE_CLASSES``). A read that gets no reply
+  is sent once more, since the first request on a new connection
+  sometimes goes unanswered. ``DeviceInfoBlock`` (``DID``), ``ControllerSerials``
+  (``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.
+  ``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
+  against the MQTT status report, in standby and while heating (operation
+  mode, state number, DHW temperature and setpoint, the six thermistors,
+  superheat and EEV step), under the ``DeviceStatus`` names and
+  conversions. A read ends the stream, and the next ``read_status()``
+  starts it again. The
+  heater's display unit is in no Bluetooth block, so Bluetooth
+  temperatures follow the unit-system preference.
+- ``nwp-cli --backend ble`` (with ``--ble-address`` or a scan) runs
+  ``serial``, ``info`` and ``status`` over Bluetooth without signing in,
+  and refuses other commands. Without ``--backend``, commands use the cloud as before.
+  The handlers run unchanged against ``nwp500.ble.BleMqttAdapter``, which
+  offers the MQTT client methods the heater serves over Bluetooth and
+  raises ``BleUnsupportedError`` for the rest. Bluetooth temperatures use
+  the cloud models' conversion and unit-system preference;
+  ``DeviceInfoBlock.min_operation_temperature()`` follows the preference
+  when ``celsius`` is not given (Fahrenheit without one, as before).
+- **New REST endpoints.** ``NavienAPIClient`` gains
+  ``get_push_settings()`` / ``set_push_settings()``
+  (``/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),
+  ``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``),
+  ``get_firmware_detail()`` (``/firmware/info``; ``run_time`` is the
+  estimated update time in minutes), ``delete_tou()``
+  (``DELETE /device/tou``), ``get_manufacture_id()``,
+  ``get_error_history()`` (``/device/error/list``; installer accounts
+  only, an owner account gets ``COMMON_NOT_AUTHORIZED``), ``update_device_info()``
+  (``/device/change-info``), ``list_simple_devices()`` and
+  ``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
+  ``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;
+  ``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
+  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()``
+  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
+  refreshed. ``re_authenticate()`` tries secured sign-in while the access
+  token is live, then the password sign-in, so a client restored from
+  tokens alone can use it too.
+  The MQTT client's deep reconnect calls ``refresh_session()`` after the
+  forced token refresh. ``AuthTokens`` gained an optional
+  ``aws_credentials_issued_at`` so a renewed AWS expiry survives
+  ``to_dict()``/restore. Stored tokens without the field load as before.
+- **Control failures are parsed and surfaced.** When the device refuses a
+  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
+  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
+  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()`` /
+  ``unsubscribe_app_connection()`` parse the topic into
+  ``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
+  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.
+  Defaults to 0 for payloads that omit it.
+- **``DhwOperationSetting.STANDBY`` (0)**, the app's
+  ``MgppOperationMode.STANDBY``. ``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".
+- **``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
+  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
+  trained with and brings: ``start_hold`` (a start's hold by the
+  minutes since the compressor last stopped), ``running_hold`` (what
+  is left of a running compressor's), ``lead_draws`` (draws recorded
+  before the start), ``draw_hold_factor`` and ``physics_usable``. Each
+  goes to the engine as given. Left at their defaults, no answer
+  changes.
+  Lead draws move the tank as the scenario's own draws do. Like them,
+  they are refused on parameters with no fitted draw response
+  (``draw_model_unsupported``), and those the model reads carry
+  ``draw_uncalibrated`` and ``inlet_temp_modelled`` where they apply.
+- **The air, its humidity and the inlet, live from Home Assistant**
+  (#166).
+
+  - ``nwp500.sim_home_assistant`` reads Home Assistant's REST API,
+    read-only. ``HomeAssistantEnvironment`` is a ``sim_live``
+    environment source:
+
+    - the air is the hourly forecast projected through a
+      ``location_air`` model, anchored to a reading beside the heater at
+      most an hour old (without a model, that reading held);
+    - the humidity is a reading at most an hour old;
+    - the inlet is the plateau of the last 72 hours' long draws, from
+      the inlet probe, the meter and the circulation's runs.
+
+    Units come from each entity's ``unit_of_measurement``. A part that
+    can't be read keeps its default, and the source says why.
+    ``record_inputs`` reads the same entities over a recorded history.
+  - ``nwp500.sim.meter.flow_gpm`` is a meter's flow from its volume
+    reports and its forward rate: the net volume over a trailing 90 s
+    where it holds at the draw line for 120 s, the rate elsewhere. It
+    finds the long draws the inlet plateau needs where the rate alone,
+    silent through a steady draw, misses some.
+  - ``nwp-cli simulate run``, ``snapshot`` and ``calibrate`` take
+    ``--sources FILE`` (or ``NWP500_SOURCES``), a TOML file naming the
+    entities, with the token in an environment variable.
+    ``calibrate`` reads the air, the humidity, the draws and the
+    circulation over the record, which makes the quiet test exact.
+  - ``sim_live.compose`` takes the heater's own air reading when the
+    environment source has none.
+- **An optional heater simulator, ``nwp500.sim``** (#150, first part). The
+  core of a physics simulation of the NWP500: an R-134a compressor model
+  coupled to a two-zone tank, standby loss, the heating elements, draws,
+  and the heater's own controller (start triggers, the TOU hold and
+  recovery cap, the restart lockout, reservation entries, setpoint and
+  mode writes), walked as events by ``nwp500.sim.engine.simulate()``. It
+  is a port of an engine checked against recorded data from one
+  NWP500-65, and returns the same answers to the last bit. Install it
+  with the ``sim`` extra (numpy, pandas, scipy). It performs no I/O,
+  reads no clock and holds no module state, and ``import nwp500`` does
+  not load it. An import-linter contract in ``tox -e lint`` keeps it
+  from importing the MQTT or REST clients, aiohttp, the AWS IoT SDK or
+  ``logging``.
+- **The simulator's API** (#150, second part).
+
+  - ``nwp500.sim.simulate(scenario, params)`` walks a frozen
+    ``Scenario``: the heater's state, settings, history, schedules,
+    environment, draws and the commands under evaluation.
+  - ``recovery()`` answers "when will the tank be hot?", and
+    ``standby()`` projects the tank coasting.
+  - The TOU periods become the windows the heater holds, and the
+    reservations become firings, with the local times in the
+    scenario's zone (``sim.schedules``).
+  - Results name every default they used.
+  - ``default_params(volume_code)`` carries one NWP500-65's parameters,
+    with the tank volume scaled for the 50 and 80 gal models.
+  - ``sim.codec`` reads and writes scenarios as JSON documents.
+  - ``nwp500.sim_adapters`` builds the inputs from ``DeviceStatus``,
+    ``DeviceFeature``, ``ReservationSchedule`` and ``TOUInfo``, reading
+    the raw fields so the unit preference cannot change them. It is
+    where units are crossed: ``environment``, ``loads``, ``write`` and
+    ``reservation_entry`` take a caller's values in the preferred units
+    (degC and litres under ``metric``), and ``path``, ``temperature``
+    and ``volume`` give a result's back in them. The simulator itself
+    works in degF and US gallons.
+  - Docs: a how-to (``docs/how-to/simulate-heater.rst``), from fetching
+    the heater's data to evaluating a change before sending it; a
+    reference of every input, its unit, default and source
+    (``docs/reference/simulator-inputs.rst``); an explanation of the
+    model and its accuracy (``docs/explanation/simulator.rst``); and the
+    API reference.
+
+  - Hot water at the tap: ``nwp500.sim.readiness(state, settings,
+    params)`` gives deliverable gallons now; ``Loads.windows`` judge a
+    shower or a bath (deliverable gallons and margin at the onset, and
+    whether the delivered water ran cold); ``SimulationResult.delivery``
+    is the delivered temperature along the walk (``sim.delivery``).
+  - The heat book (``sim.book``): the tank's heat by bookkeeping, walked
+    through the simulation as the engine's ``HeatLedger`` so a draw that
+    spends it takes the zones down. Started from the caller's knowledge
+    (``full_tank_book``) or their own record, never guessed from the
+    probes.
+  - ``HeaterParams`` gains ``readiness`` (the line, the outlet lag, the
+    fall rate, the dip tolerance, evidence) and ``book`` parts, with one
+    installation's measured defaults and their provenance.
+  - Time to ready: ``nwp500.sim.time_to_ready(scenario, params)`` says
+    whether the tank can run a bath, when it can in the heat pump and
+    in each element mode with the energy to get there, and how many
+    showers it is ready for, along the recovery the heater runs next
+    (``next_recovery``) (``sim.ready``).
+  - ``standby(..., settings=)`` says when the heater would start itself
+    on the coast and why; ``element_mode`` projects a recovery in an
+    element mode.
+  - A walk with draws outside the range the draw terms were fitted over
+    says ``draw_out_of_domain`` (``DrawParams.domain_upper_f``,
+    ``domain_volume_gal``); a write or a written reservation outside the
+    setpoint range the simulation runs is refused.
+
+  **Behaviour notes.** Answers that a client carrying an earlier copy of
+  this engine will see change at the switch:
+
+  - When no ``RecoveryModel`` answers (none given, or it declines) and
+    the physics integration stops at its bound short of the target,
+    there is no recovery and ``simulate`` raises ``SimulationError``.
+    The bound is no longer served as a duration.
+  - A recovery's reasons keep the served recovery's own (a truncated
+    integration, a model's diagnostics) beside ``recovery_low_confidence``.
+  - ``mode_recovery``'s ``upper_end_f`` is the zone's own temperature
+    when the element does not start or has nothing to do.
+  - A draw during a recovery honours ``draws_on`` and is priced on the
+    configured tank, not the 63.2 gal default.
+  - No ``hp_lower_on`` disables only the lower trigger; the upper
+    zone's at a TOU window's opening still starts the heater.
+  - A draw at a draw window's onset counts its cold side when the window
+    is judged.
+  - TOU prices are compared decoded at their own ``decimal_point``; each
+    period is laid out on the dates its day and season masks select
+    before windows that touch are joined across midnight.
+  - Scenario instants are held in UTC, so a horizon is elapsed time
+    across a daylight-saving change; a scenario document keeps which
+    fields were left to their defaults.
+  - ``sim.book.SpanLoss`` lets a client charge a loss the book does not
+    model; without one, the book charges none.
+  - Circulation runs within 10 minutes of each other are one run over
+    the whole schedule, so a coast boundary between them no longer
+    charges each its own displaced volume.
+  - ``default_params()`` has no mixing valve; ``site_example_params()``
+    is the installation the values were fitted at, its valve included
+    (``with_valve``, ``SITE_VALVE``). The core's draw functions default
+    to no valve as well. Each parameter says whether it describes the
+    heater or the installation (``scope_of``), and the frame it was
+    fitted in (``note_of``).
+  - Circulation (``sim.circulation``): an installation's runs
+    (``Loads.circulation``, ``sim_adapters.circulation`` for a weekly
+    schedule) charged as flowing draws and to the heat book while they
+    run, on ``HeaterParams.circulation``; with none, nothing is charged.
+  - The air where the heater stands, from the heater alone and a public
+    forecast: ``sim_adapters.location_air_reading`` (the heater's own
+    reading, only while the compressor runs) and
+    ``sim_adapters.location_air`` (an outdoor forecast projected by
+    ``sim.location_air``, anchored to that reading, with ``fit`` for
+    one's own model). ``time_to_ready`` and ``next_recovery`` take a
+    ``RecoveryModel``.
+  - Calibration from the heater's own record (``sim.calibration``,
+    ``sim_adapters.history`` to build one from ``DeviceStatus``
+    readings): the standby loss law and the zones' mixing constant from
+    quiet windows, then the compressor constant and evaporator approach
+    from heat-pump recoveries that reached their target, then input
+    power and apparent COP against the heater's own power readings, each
+    reported
+    with what it rested on (held-out error, windows used, a fit pinned
+    on a bound). An element run counts as busy in the quiet test, not
+    only the compressor and hot water in use.
+  - ``forecast``: when a recovery must start to have the tank ready at
+    a time, and whether it can (``feasible``, ``shortfall_minutes``),
+    to the heater's own stop threshold or a partial charge, with
+    ``no_heating_required`` (the lower zone at its target, or a zero
+    energy count outside a TOU window), ``not_scheduled``, and the
+    trajectory's electricity, stored heat and COP.
+    ``active_cycle``: what is left of a running recovery, its physics
+    estimate on the evaporator coil's live reading.
+    ``Settings.hp_lower_off_f``, ``hp_upper_on_f`` and
+    ``HeaterState.energy_to_setpoint_wh`` carry what they need, filled
+    by the adapters; ``recovery`` says ``not_scheduled`` in Vacation and
+    Power Off.
+  - The heater's profile (``sim.profile``): its modes and their energy,
+    setpoint range and step, depletion threshold and tank, under a
+    revision digest; and ``recovery_as_of``, a kept recovery aged to
+    now.
+  - The element terms from a heater's raw record (``sim.calibration``):
+    the upper probe's lag and rate as one line from clean stints
+    (``element_stints``, ``fit_element_lag``), where each element
+    switches off and what it draws per metered stint
+    (``element_off_points``, ``element_power``), and the zones' rates
+    and element power on the one-minute grid (``element_grid``,
+    ``fit_element_rates``), each with day-bootstrap intervals.
+  - Draws from a weekly draw forecast (``sim.draw_forecast``): an issue
+    checked whole, its expected draws (rate x per-draw mean, the
+    per-draw volume kept), the heater's draw windows, and the worst case
+    of each window's long draws first (``forecast_loads``,
+    ``simulate(withheld_windows=)``). A draw's domain is now judged by
+    its per-draw volume where it carries one (``Draw.per_draw_gal``),
+    not its fractional expectation.
+  - The mains from an inlet probe (``sim.cold_supply``,
+    ``sim_adapters.cold_supply``): the median plateau of recent long
+    draws with circulation off and the meter reading flow, from minute 9
+    of each; ``on_the_mains`` converts a book's gallons at it.
+  - What the heater did over a range, from its record, as the model
+    reads it: ``sim.record.Record`` (each signal's change rows, its
+    writes and the heater's own drops, TOU switches and window edges,
+    starts with elements corroborated by power;
+    ``sim_adapters.record``), ``sim.attribution`` (why each recorded
+    start happened) and ``sim.observed`` (modes and whether each was in
+    effect, when each source ran, counted and attributed starts, energy
+    per slot, the delivered temperature, and the record's gaps;
+    ``sim_adapters.observe``). ``replay`` reads its writes from the same
+    record.
+  - The readiness evidence and the heat book's own terms from a metered
+    record (``sim.calibration``, ``sim_adapters.draw_frame``): clean
+    draws and their demonstrated volumes reduced to the frontier, with a
+    time-ordered held-out check, and the cap after a cold lower zone;
+    the book's compressor rate, its slope with the air, standby UA and
+    circulation's loss fitted on re-anchors of full tanks
+    (``RecordedBook``, ``fit_book_terms``), its error by anchor age, and
+    the empty points in the book's frame and the drawable one, and the
+    error bands (``book_error_btu``: the p90 pooled over anchors an hour
+    to 18 h old, and the 18-24 h band's, each rounded up to 100 BTU).
+    With a meter, the COP fit prices the heat each cycle's draws and
+    circulation runs took, and the draws just before it
+    (``metered_withdrawn``, ``metered_lead``; ``calibrate(draws=,
+    circulation=)``), as the model's fit did, each run at the flow it
+    ran at (``circulation_flow_at=``, ``flow_lookup``). What could not be fitted
+    keeps the base's value and is named in ``HeaterParams.unfitted``;
+    every answer it reaches says ``physics_uncalibrated``,
+    ``energy_uncalibrated``, ``standby_uncalibrated`` or
+    ``tau_gap_prior``.
+    The probes' share of circulation's heat
+    (``circulation_windows``, ``fit_ungated_observability``), fitted
+    against the displaced volume it is used with.
+    Circulation's terms from its own telemetry: each run's measured heat
+    (``measure_runs``), the displaced volume that prices them
+    (``fit_displaced_gal``), its recent flow and the flow a past run ran
+    at (``recent_flow_gpm``, ``flow_lookup``), as the model fitted them.
+    The book's response to a draw, fitted on the record's long draws by
+    the procedures its values were fitted with: the cold front's place
+    and width (``fit_front``), the lower zone's settling after a draw
+    (``fit_front_settle``) and the upper zone's mixing
+    (``fit_zone_mix``), each with a day bootstrap.
+  - The heat book from a recorded history, as the model kept it:
+    ``sim.book.Step``, ``book_steps`` (the anchor on a quiet full tank
+    after a recovery, or a recovery's end during a draw; every step
+    booked from it; the inlet the median of 3 h of a probe), and
+    ``sim_adapters.book_from_history``, which grids the heater's
+    statuses, a hot-water meter's flow, circulation's runs and flow and
+    an inlet probe onto 10 s steps and books 18 h, else 72 h aged.
+    ``CirculationParams.meter_share`` is the share of a run's flow the
+    meter also reads; ``BookParams`` gains ``history_h``, ``draw_gpm``
+    and ``inlet_window_s``.
+  - ``sim_adapters.replay``: a past scenario from the statuses the
+    heater reported, as the model's replay read its record: the state
+    then, the compressor's last stop and the last heating from their
+    edges, the recorded setpoint and mode changes as writes (but the
+    heater's own drop to Heat Pump at a window), and the TOU switch's
+    changes (``Schedules.tou_switches``, which the walk applies).
+  - The heater's own TOU marker (``Settings.hp_upper_on_f`` raised):
+    ``time_to_ready`` and ``element_mode`` read "in a window now" from
+    it, and ``next_recovery`` lets it override the schedule for a
+    recovery running now (``api.marked_windows``), as the model did;
+    an unknown marker counts as in force. ``simulate(tou_windows_in_force=)``
+    takes the windows to keep, and TOU on with no periods says
+    ``tou_schedule_unknown``. ``element_mode(setpoint_f=)`` projects to a
+    what-if setpoint while the heater's own decides the window test.
+  - ``time_to_ready`` says ``inlet_temp_modelled`` when a booked answer
+    converts at an inlet nobody measured (``inlet_measured=``, or a
+    book whose steps measured it); ``next_recovery``'s coast loses the
+    heat circulation takes on it as well as standby; a served recovery
+    under 0.6 confidence says ``recovery_low_confidence``. ``standby``
+    reports the gallons drawn and the heat they took, circulation's
+    minutes and heat, and the mean air over the coast.
+  - ``default_params()`` names the installation's book, readiness and
+    draw terms in ``HeaterParams.unfitted`` (``INSTALLATION_TERMS``):
+    they are one installation's fits, so answers they reach say
+    ``book_uncalibrated``, ``readiness_uncalibrated`` or
+    ``draw_uncalibrated``. A ``Record`` drops missing readings on entry
+    and takes its installation's cadences and the heater's resting
+    threshold (``drop_within``, ``element_power_slack``,
+    ``resting_upper_on_f``). ``observe(profile=, revision_since=)``
+    names modes by a heater profile. ``schedules.rule_windows`` lays out
+    TOU rules that have no prices, such as a learned schedule. The
+    engine, the tank physics and the physics models are documented as
+    public (:doc:`/reference/python_api/sim`).
+- **``nwp-cli simulate``, and the live sources it composes** (#151).
+
+  - ``nwp500.sim_live`` reads what a scenario needs from the device:
+    ``LiveHeaterSource`` (the state, the settings, the air and the
+    tank size, from one status and one feature read) and
+    ``LiveScheduleSource`` (the reservations over MQTT, the TOU
+    periods over REST, the TOU switch from the status).
+    ``compose()`` awaits them, and any other source with an ``async
+    read()`` (``Given`` for a value in hand), into a ``Scenario``. A
+    read with no reply raises ``LiveReadError``, as does a TOU read
+    that fails while TOU is on. The simulator still imports none of
+    it.
+  - ``nwp-cli simulate run`` walks the heater as it is now, a scenario
+    file, or the heater now with a scenario file laid on it
+    (``--live``). Each part is chosen on its own: a flag
+    (``--start``, ``--hours``, ``--tz``, ``--ambient``,
+    ``--environment``, ``--inlet``, ``--draws``, ``--plan``,
+    ``--params``), then the scenario file, then the device. It prints
+    a table (the heating intervals, the energy by source, readiness,
+    the draw windows and which ran cold, the defaults used), the
+    result document (``--format json``) or the path (``--format
+    csv``). ``nwp-cli simulate snapshot`` writes the heater and its
+    schedules now as a scenario file to edit and replay. Without the
+    ``sim`` extra the commands stop with an install hint.
+    ``examples/simulator/`` has a scenario, a plan and an overlay to
+    start from; :doc:`/how-to/simulate-heater` shows each use.
+- **Record a heater's history and calibrate the simulator to it**
+  (#152).
+
+  - ``nwp500.status_history`` is the history's format: one JSON line
+    per status, ``{"t": <ISO 8601 instant>, "status": <raw payload>}``.
+    ``line()`` writes one and ``read()`` reads them back as
+    ``(instant, DeviceStatus)`` pairs. It does no I/O and needs no
+    extra.
+  - ``nwp-cli simulate record HISTORY`` appends the heater's statuses
+    to a file until stopped, by default asking for one every 30 s.
+  - ``nwp-cli simulate calibrate HISTORY`` fits the standby loss, the
+    compressor and the power to that history
+    (``sim.calibration.calibrate``). It prints a row for each term: the
+    value, what it was fitted from, its error, and whether it was
+    fitted or kept the base's value, and why. ``-o`` writes the fitted
+    ``HeaterParams`` document for ``simulate run --params``. The
+    standby fit needs the air beside the heater, from a sensor
+    (``--air``, a CSV file) or a constant (``--ambient``). Given, that
+    air is the recoveries' air too. The heater's own reading, filled
+    across the gaps between compressor runs, and an outdoor projection
+    both biased the fitted loss, so neither stands in for the air.
+    Without ``--humidity`` the fits get 50 %, their documented default.
+    A gap between statuses of more than 4 times the record's usual
+    spacing (at least 5 minutes) is unobserved, so no quiet window or
+    recovery spans a stopped recording. If a write fails, ``record``
+    stops with an error.
+  - ``sim_adapters.history(..., max_gap=)`` marks such gaps: the
+    sample before one is set to water in use and excluded.
+  - :doc:`/how-to/calibrate-simulator` covers the recording, the air,
+    the report, and what a history cannot tell (the draws, a
+    circulation loop the heater does not run).
+  - Three helpers the issue proposed are left out:
+
+    - **A mains-temperature estimate from the air.** The draw terms
+      were fitted against a measured inlet, so an estimated inlet
+      would bias every draw.
+    - **A draw-timing profile from the "hot water in use" flag.** The
+      flag also fires on circulation, and the expected draws from such
+      a profile never predicted better than no draws.
+    - **A check against the daily energy totals.** Power and COP are
+      fitted cycle by cycle.
+
+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``,
+  ``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
+  sent ``RecirculationMode.BUTTON`` (2) was selecting the weekly schedule.
+  ``RECIRC_MODE_TEXT``, the ``recirc`` CLI command, the recirculation
+  example and the protocol docs follow. ``model_dump()`` writes enum
+  names, so a dumped status now says ``"ALWAYS_ON"`` for 1 (was
+  ``"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
+  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
+  reads "Power Off" instead of "Vacation" and mode 0 reads "Not Reserved".
+  **Behaviour change:** reservation writes (``add_reservation()``,
+  ``update_reservation()``, ``build_reservation_entry()`` and the MQTT
+  reservation validator) now accept mode 1-5 and reject 6, which was never
+  a valid entry mode. An entry already on the heater with mode 6 (earlier
+  versions documented 6 as Power Off) does not block the reservation
+  helpers: they send the entries they did not change as they read them
+  (``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
+  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``.
+  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
+  published ``{clientID, timestamp}``, a shape nothing reads. It now
+  publishes the NaviLink app's ``RequestLastWill`` 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
+  every season.** ``sim_adapters.location_air_reading``,
+  ``sim.location_air`` and the inputs reference said it read the air
+  beside the heater within about 0.35 °F while the compressor runs.
+  Measured against a sensor beside the heater, that held from August
+  to October. From May to July the reading was up to about 2 °F warm,
+  and in a run's first 2 minutes about 2.7 °F warm. The idle reading
+  is about 6 °F warm, not 5.
+- **The CLI logs to stderr.** It logged to stdout, so a warning could
+  land in the middle of ``--json``, ``--raw`` or CSV output piped to
+  another program. Output stays on stdout.
+- **The package root loads its exports on first use** (PEP 562).
+  ``from nwp500 import NavienMqttClient``, ``nwp500.DeviceStatus`` and
+  ``nwp500.mqtt`` work as before, and type checkers read the same names,
+  but ``import nwp500.sim`` and ``nwp500.sim_adapters`` no longer load
+  the clients, aiohttp or the AWS IoT SDK (tested in a fresh
+  interpreter).
+- **Superheat is converted as a difference** (#153).
+  ``DeviceStatus.target_super_heat`` and ``current_super_heat`` converted
+  their raw tenths of a degree Celsius as absolute temperatures, so in
+  Fahrenheit they added 32. Superheat is a temperature difference (suction
+  minus evaporator), so they now use ``DeciCelsiusDelta``, as the
+  ``*_diff_temp_setting`` properties already do. Raw 50 now reads 9.0 degF
+  instead of 41.0 degF. **Behaviour change:** every Fahrenheit value drops
+  by 32, so stored or charted Fahrenheit superheat from earlier versions is
+  32 degF too high. Celsius values are unchanged. The protocol docs now
+  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
+  ``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``).
+  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"``.
+- **A reservation entry turns a powered-off heater on in the
+  simulator.** The controller skipped entries while powered off, as in
+  Vacation, on a misreading of the device test, which found that a
+  powered-off heater fires the entry and turns on in its mode (two
+  runs). ``Settings.powered_off`` tells power-off from Vacation; the
+  entry is judged as a mode write out of power-off, and the result
+  carries ``powered_on_by_entry``. In Vacation entries are still
+  skipped.
+
+Documentation
+-------------
+- **What the device tests and the record measured.** Three new
+  explanation pages: :doc:`/explanation/recovery-speed` (heat output,
+  minutes per degF, compressor power and efficiency, start-up energy,
+  the air's effect, how much of the tank heats),
+  :doc:`/explanation/standby-loss` (the jacket loss, a circulation run's
+  heat and where it shows) and :doc:`/explanation/draws` (the delivered
+  temperature, the probes through a draw, how much hot water is left,
+  reading a cold-supply probe). The element pages gain hours and energy
+  by mode, the off point and the probe's lag; scheduling gains write and
+  entry timing; the simulator's Accuracy section gains time to ready and
+  the lower zone after a draw.
+- **Where the simulator's defaults come from.** A table in
+  :doc:`/reference/simulator-inputs` gives each default parameter's
+  evidence: what it was measured or fitted on, its error, and how far
+  the per-retrain values move between retrains.
+- **Accuracy figures corrected.** ``simulator.rst`` gave 18 % and the
+  13 and 45 min deficit-band errors as physics alone; they scored the
+  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
+  ``app-connection`` event / Last-Will payload; ``diagnose-mqtt.rst`` gains
+  "Why was my command rejected?"; ``maintenance.rst`` gains a "Maintenance
+  Log" section; ``authenticate.rst`` explains the password-free renewal
+  chain.
+- **Less noise.** Implementation notes, the docs' own revision history
+  and where things were ported from are gone from the pages, and
+  section titles are plainer. The ``sim`` extra is listed under
+  :doc:`/reference/installation`'s optional dependencies.
+- **Corrections from the device tests and the recorded history.** The
+  explanation pages, the how-tos, the protocol reference and the
+  simulator's docstrings said things later measurements contradict:
+
+  - High Demand's element starts somewhere in (0.2, 0.4] degC short,
+    not (0.2, 0.7]; Electric ran upper first in the commanded runs, but
+    the record also has the lower running alone; the element-run and
+    mid-stint counts are the record's.
+  - Inside a TOU window the upper tank starts a cycle when it is more
+    than 14.4 degF short, at the opening or later. A setpoint write
+    starts one in 120 of 122 writes leaving the upper tank short (not
+    about 70 %), a lowering to the upper tank or below in none, and in
+    ``HEAT_PUMP`` a draw does not start one while the upper tank is at
+    or above the setpoint. The restart lockout measured 5.5 min.
+  - The simulator's accuracy figures are the ones measured with
+    start-up charged once (3.6 % and 4.4 % low; starts 31 of 40 held
+    out), and the heater's idle air reading is about 6 degF warm.
+  - ``HYBRID_BOOST_MODE`` is also Energy Saver with an element running;
+    ``touStatus`` means TOU is enabled, not that a period is in force.
+  - A device has held at least 32 reservation entries and 20 TOU
+    periods; a list write can be lost with no error, so read it back;
+    a powered-off heater runs its reservation entries; forcing a full
+    recovery with ``tou_override_status`` is untested.
+  - 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
+  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``.
+  - ``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
+    (``DeviceDiagnostics.ta_data.cumulated_op_time_comp``, ``_uhe``,
+    ``_lhe``).
+  - ``currentHeatUse`` is the ``HeatSource`` enum (0-3), not a bool.
+  - ``drEventStatus`` is the ``DREvent`` enum, not a bitfield.
+  - ``tou-recovery-cap.rst`` named ``dhw_outlet_temperature``, Home
+    Assistant's name for ``dhw_temperature``.
+  - Vacation is 1-99 days; the docs said 0-99 in some places, and the
+    library said 1-30.
+  - Anti-legionella heats to 140 degF (60 degC), defaults to a 7-day
+    period, is adjustable from 1 to 30 days and ships disabled (User's
+    Information Manual, section 3.14.2). The scheduling how-to said 158
+    degF, a 14-day default, periods up to 90 days and "mandatory".
+  - ``dhwTemperatureMin`` is the installer's minimum operation
+    temperature: 95-113 degF, factory default 95 degF. 104.9 degF was one
+    unit's setting, not a contradiction.
+  - ``ambientTemperature`` is the air around the unit, per the manual;
+    neither "intake" nor "outlet" is sourced. The heat pump runs only
+    between 41 and 113 degF.
+  - ``docs/explanation/advanced-features.rst`` is removed. Its weather
+    thresholds, COP figures, DR bitfield, stratification tables and code
+    sample were unsourced or wrong, and the sourced material is covered
+    by the protocol reference, ``what-starts-a-recovery`` and
+    ``tank-energy``.
+
+- **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.
+  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
+  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,
+  minutes, counts) instead of calling them unknown. ``unknown-values.rst``
+  notes that on the unit checked, ``cumulatedDhwFlowRate`` and every draw
+  counter read 0 after 392 days in use, so a 0 there does not mean no water
+  was used. Library output is unchanged. The raw fields no longer carry a
+  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.
 
 Version 9.4.3 (2026-10-01)
 ==========================
@@ -54,7 +758,7 @@ Documentation
   running element mode; and the operation setting reports the configured
   mode, not activity. The section's first measurement date is corrected to
   local time (2026-09-19).
-- **New: what the heating elements actually do**
+- **New: what the heating elements do**
   (``docs/explanation/heating-elements.rst``). The four
   ``he*TempSetting`` fields describe the thermostat, and **on entry to
   a mode the thermostat is not what runs the element**: in
@@ -85,7 +789,7 @@ Documentation
   A sampling note with it: the element runs in two very different
   lengths. Of 115 upper-element runs over eight months, 20 lasted under
   a minute (median 16 s), carrying 0.6 kWh against 93 kWh for the rest.
-  They are real elements, and not negligible to the probe - a 20 s burst
+  They are real elements, and not negligible to the probe: a 20 s burst
   is ~0.3 degC. Because ``currentPower`` samples at a median 30 s, a
   one-minute-resampled power series can miss one entirely, making a
   5.5 kW element look like 0.5 kW. Resample power with a maximum.
@@ -97,7 +801,7 @@ Documentation
   ~0.9 degC under the setpoint-tracking ``heUpperOffTempSetting``, not
   to a fixed point. Raising the setpoint in that mode starts the element
   through the entry rule. And ``heUpperOnTempSetting`` rests at 40.5
-  degC reliably only in ``ENERGY_SAVER`` - in ``HEAT_PUMP`` about half
+  degC reliably only in ``ENERGY_SAVER``; in ``HEAT_PUMP``, about half
   the time.
 
   Also documents Energy Saver's entry behaviour (the element engages
@@ -132,7 +836,7 @@ Documentation
   with no exceptions: 104.9 degF on the primary, raised to about the
   setpoint during the afternoon TOU window on the secondary.
   ``energy_to_setpoint`` shifts by the same 2 degC. Because of that,
-  ``usable_energy`` is not always robust to the branch. In the window it
+  ``usable_energy`` does not always hold up across the branch. In the window it
   caps at ``full_recovery_energy`` once ``energy_to_setpoint`` hits 0,
   up to about 3.6 degF short of the setpoint, and under-reads by up to
   561 Wh. The page and the ``usable_energy`` docstring now say so and
@@ -175,7 +879,7 @@ Version 9.4.0 (2026-09-12)
 ==========================
 
 This release realigns the MQTT command set with what the NaviLink app
-actually sends. The app (version 2.03.00) was decompiled and its request
+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
@@ -338,8 +1042,8 @@ Fixed
   The cloud returns ``"error": {"errorCode": null}`` on some devices.
   :class:`~nwp500.models.DeviceErrorSummary` typed the field
   ``ErrorCode | int``, so validation of the whole listing failed and every
-  caller - including the Home Assistant integration, which could no longer
-  set up - lost the device entirely. ``error_code`` is now
+  caller (including the Home Assistant integration, which could no longer
+  set up) lost the device entirely. ``error_code`` is now
   ``ErrorCode | int | None`` and defaults to ``None``: a null means the
   cloud reported no code, which is not the same claim as ``NO_ERROR``.
   Callers that treated the field as always-present should handle ``None``.
@@ -376,8 +1080,8 @@ Added
   :class:`~nwp500.models.DeviceInfo` gains ``model_type_code`` and
   ``installer_id``. ``error`` makes the device's last recorded fault
   readable without an MQTT connection, including while the device is
-  offline. Every new field is optional, so responses that omit them - such
-  as ``/device/info``, which carries no ``error`` block - parse unchanged.
+  offline. Every new field is optional, so responses that omit them (such
+  as ``/device/info``, which carries no ``error`` block) parse unchanged.
   ``error_code`` is typed ``ErrorCode | int`` (validated left to right, so a
   known code becomes an ``ErrorCode`` member and only an unknown one stays a
   plain int) so an unrecognised code cannot make a whole listing unparseable. ``docs/openapi.yaml`` is
@@ -394,17 +1098,17 @@ Removed
   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
+  (``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.
 
   Beyond returning nothing, the call published a write-shaped command with no
-  schedule attached. This device ignored it - ``touStatus`` was unchanged
-  across repeated calls - but a firmware that took it at face value could read
+  schedule attached. This device ignored it (``touStatus`` was unchanged
+  across repeated calls), but a firmware that took it at face value could read
   it as "store an empty TOU schedule".
 
   **Migration**: use :meth:`~nwp500.NavienAPIClient.get_tou_info`, which
-  returns the stored plan - rate name, utility, ZIP code and the seasonal
+  returns the stored plan: rate name, utility, ZIP code and the seasonal
   pricing intervals. The read itself is pure REST; it is keyed by the
   controller serial number, which only the MQTT device-info response
   publishes, so fetch that once and cache it.
@@ -420,12 +1124,12 @@ Fixed
   month list, so ``--months 5`` took the single-month branch and printed
   the same daily breakdown as ``--month 5`` instead of the monthly
   summary. The handler now takes an explicit ``daily`` flag set by the
-  option the user actually passed. ``energy`` also rejects ``--month``
+  option the user passed. ``energy`` also rejects ``--month``
   and ``--months`` together rather than silently preferring ``--month``,
   and validates the ``--months`` range and format the way ``--month``
   already did. All of that validation now happens while Click parses the
   arguments, so a bad invocation is a usage error (exit code 2) before any
-  authentication or MQTT connection is attempted - previously the command
+  authentication or MQTT connection is attempted. Previously the command
   body raised ``ClickException`` after connecting, where ``async_command``'s
   catch-all reported it as an "Unexpected Error" with a traceback, and
   anyone without working credentials saw an authentication failure instead
@@ -445,11 +1149,11 @@ Fixed
 - **``firmware_payload_capture.py`` captured almost nothing.** Its wildcards
   covered ``cmd/{type}/{client_id}/res/#`` and the event topic, but the device
   acknowledges control and query commands on
-  ``cmd/{type}/navilink-{mac}/{client_id}/res`` - which neither pattern
-  matches - so the device status and device info responses were missed, along
+  ``cmd/{type}/navilink-{mac}/{client_id}/res``, which neither pattern
+  matches, so the device status and device info responses were missed, along
   with every request published on the device path. A capture run recorded 2
   payloads where it should have recorded 11. It now also subscribes to
-  ``cmd/{type}/navilink-{mac}/#``, which additionally picks up traffic from
+  ``cmd/{type}/navilink-{mac}/#``, which also picks up traffic from
   other clients on the same device. Query results the device routes back to a
   client-keyed topic, such as reservations and energy usage, were already
   covered by the existing response wildcard.
@@ -459,8 +1163,8 @@ Version 9.3.0 (2026-08-03)
 
 **BREAKING CHANGES**: two independent corrections land together.
 
-Tank energy values were wrong in two ways - a 2.5x unit-scale error and
-two actively misleading field names - and both are corrected. Reported
+Tank energy values were wrong in two ways, a 2.5x unit-scale error and
+two actively misleading field names, and both are corrected. Reported
 tank energy is now 2.5x smaller and two public field names are removed.
 
 Separately, eight status flags change type from ``bool`` to
@@ -474,10 +1178,10 @@ Changed
   not. Because ``totalEnergyCapacity`` is a whole-tank quantity, its slope
   against the setpoint measures the quantum with no stratification
   assumption: on a 65-gallon NWP500 that is 70.25 raw counts per Kelvin.
-  The field turns out to be bimodal - at a fixed setpoint it takes one of
-  two values exactly 2 degC apart - but both branches give the same slope
+  The field is bimodal (at a fixed setpoint it takes one of
+  two values exactly 2 degC apart), but both branches give the same slope
   to within 0.2%, so the quantum is unaffected. Converting to Watt-hours needs a
-  water mass, and a "65 gallon" tank does not hold 65 gallons - so taking
+  water mass, and a "65 gallon" tank does not hold 65 gallons, so taking
   the quantum to be round, as every other conversion in this protocol is,
   4 Wh/count is the only candidate implying a water volume below the
   nameplate (241.7 L). Two further checks agree: 183 individual heating
@@ -489,7 +1193,7 @@ Changed
   be comparable.
 
 - **Energy fields renamed.**
-  ``availableEnergyCapacity`` is not available energy - it is the energy
+  ``availableEnergyCapacity`` is not available energy: it is the energy
   still *needed* to reach the setpoint. It falls as the tank heats and
   reaches zero when the tank is fully charged, so code treating it as
   stored energy had the signal backwards (regression against mean tank
@@ -515,7 +1219,7 @@ 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.
+  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
@@ -545,7 +1249,7 @@ Added
   fields are measured from the setpoint, so neither is a state of charge;
   subtracting them cancels the setpoint and leaves the tank's heat above
   the device's minimum operating temperature (104.9 degF), which is about
-  the lowest temperature usable for a shower. Robust despite
+  the lowest temperature usable for a shower. It holds despite
   ``full_recovery_energy`` being bimodal, since both fields shift
   together: the implied tank temperature tracks the thermistor mean to a
   standard deviation of 0.57 degF over 12275 samples. Rendered by the CLI
@@ -604,13 +1308,13 @@ Fixed
   in the changelog, the model field description and the protocol
   reference.
 - New ``docs/explanation/tank-energy.rst`` records what the two fields
-  actually measure and the calibration evidence behind the scale change,
+  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
+  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
   was applied to temperature converters and reported working sensors as
   missing during cold-weather operation.
@@ -675,7 +1379,7 @@ Documentation
   (``models/schedule.py``, ``models/_converters.py``). Corrected to
   "target temperature, half-degrees Celsius; °C = param/2", and fixed the
   accompanying doctest-style example, which showed a ``minute`` key where
-  the function actually returns ``min``.
+  the function returns ``min``.
 
 Version 9.2.0 (2026-07-06)
 ==========================
@@ -708,7 +1412,7 @@ Changed
   (``mqtt/_control_commands.py``) and ``DeviceSubscriptionsMixin``
   (``mqtt/_device_subscriptions.py``). ``NavienMqttClient`` now inherits
   both, so its public API is unchanged, while ``mqtt/client.py`` shrinks
-  from ~1572 to ~1196 lines and reads more clearly as connection
+  from ~1572 to ~1196 lines and reads as connection
   orchestration plus a public façade. No behavior change.
 - **Event system relationship clarified and de-duplicated** (`#102
   <https://github.com/eman/nwp500-python/issues/102>`_): ``events.py`` and
@@ -893,8 +1597,8 @@ Bug Fixes
   ``configure_recirculation_schedule()`` dumped the schedule models
   as-is, double-nesting the request (``request.reservation.reservation``
   / ``request.schedule.schedule``) and leaking pydantic computed display
-  fields — including a unit-converted ``temperature`` alongside the raw
-  half-Celsius ``param`` — into device commands. Both now send the flat,
+  fields (including a unit-converted ``temperature`` alongside the raw
+  half-Celsius ``param``) into device commands. Both now send the flat,
   raw protocol shape used by ``update_reservations()``. A new
   ``NavienBaseModel.to_protocol_dict()`` dumps only declared protocol
   fields.
@@ -922,7 +1626,7 @@ Bug Fixes
   so consumers kept displaying the stale error.
 - **Fix TOU price encoding**: ``encode_price()`` used banker's rounding,
   under-encoding exact half values at even boundaries (0.125 at
-  ``decimal_point=2`` encoded to 12 instead of 13) — now uses
+  ``decimal_point=2`` encoded to 12 instead of 13). It now uses
   ``Decimal`` half-up rounding. ``build_tou_period()`` also treated
   ``bool`` prices as pre-encoded integers (``True`` sent as price 1).
 - **Fix protocol documentation errors**: ``decode_reservation_hex()``
@@ -937,7 +1641,7 @@ Bug Fixes
   an undocumented SDK thread where asyncio operations are unsafe, and the
   handler registry could be mutated on the event loop while the CRT
   thread iterated it (``RuntimeError: dictionary changed size during
-  iteration``, dropping the message — most likely during the
+  iteration``, dropping the message, most likely during the
   reconnect/resubscribe window). The awscrt callback now only marshals
   the raw payload onto the event loop; parsing and dispatch run there,
   iterating snapshots of the handler registries.
@@ -950,7 +1654,7 @@ Bug Fixes
   ``set_unit_system()`` stored the preference in a ``ContextVar`` set in
   the caller's task. Tasks scheduled from AWS CRT callback threads never
   inherit that context, so the preference silently reverted to
-  auto-detect for all MQTT-delivered data — ``nwp-cli --unit-system
+  auto-detect for all MQTT-delivered data: ``nwp-cli --unit-system
   metric monitor`` logged temperatures in the device's native unit while
   labeling them °C. The preference is now a process-wide setting visible
   from every task and thread.
@@ -966,7 +1670,7 @@ Bug Fixes
   ``finally`` block.
 - **Fix wait_for() docstring examples**: examples showed
   ``args, _ = await emitter.wait_for(...)``, but ``wait_for`` returns
-  just the args tuple — following the documented pattern raised
+  just the args tuple, so following the documented pattern raised
   ``ValueError`` or silently mis-assigned.
 - **Serialize concurrent token refresh**: ``ensure_valid_token()`` and
   ``refresh_token()`` had no lock, so concurrent callers (API 401 retry,
@@ -991,7 +1695,7 @@ Bug Fixes
 - **Make** ``NavienAuthClient.__aenter__`` **idempotent**:
   ``create_navien_clients()`` pre-enters the context and its docstring
   instructs users to enter again with ``async with auth:``; the second
-  entry created a fresh session and orphaned the first — which the API
+  entry created a fresh session and orphaned the first, which the API
   client was still pinned to. Re-entering now reuses the existing
   session.
 - **Fall back to full sign-in when stored-token refresh fails**:
@@ -1100,7 +1804,7 @@ Bug Fixes
   (e.g. the sleeping task's timer callback had already been enqueued), the
   cancellation was silently dropped.  The stale ``_reconnect_with_backoff`` task
   would then complete its sleep, call ``_reconnect_func``, and tear down an
-  otherwise healthy connection — restarting the entire disconnect → reconnect →
+  otherwise healthy connection, restarting the entire disconnect → reconnect →
   ``AWS_ERROR_MQTT_UNEXPECTED_HANGUP`` cycle.  Fixed by replacing the direct
   ``task.cancel()`` call with a ``_cancel_pending_reconnect()`` coroutine scheduled
   via ``_schedule_coroutine``, so the cancellation runs on the event loop where
@@ -1118,7 +1822,7 @@ Bug Fixes
   SDK connection's built-in auto-reconnect would eventually succeed, creating two
   active connections sharing the same client ID. Because AWS IoT allows only one
   connection per client ID, the broker would kick one off, triggering
-  ``on_connection_interrupted`` and starting yet another reconnection — an
+  ``on_connection_interrupted`` and starting yet another reconnection: an
   infinite connect/disconnect loop. Fixed by adding ``MqttConnection.close()``
   (unconditional teardown regardless of ``_connected`` state) and calling it
   before creating the replacement connection in both ``_active_reconnect()`` and
@@ -1150,9 +1854,9 @@ Bug Fixes
   a different loop in multi-loop test setups.
 
 - **Reservation temperature validation was US-only**: ``build_reservation_entry``
-  validated set-point temperatures against hardcoded Fahrenheit bounds (95–150 °F)
+  validated set-point temperatures against hardcoded Fahrenheit bounds (95-150 °F)
   regardless of the active unit system. Validation now uses the current unit system
-  context: 35–65 °C in metric mode, 95–150 °F in US mode. Celsius users previously
+  context: 35-65 °C in metric mode, 95-150 °F in US mode. Celsius users previously
   received spurious ``ValueError`` rejections for valid temperatures.
 
 - **Malformed reservation data silently dropped**: ``build_reservation_entry`` now
@@ -1240,11 +1944,11 @@ integrations like Home Assistant:
 2.  **Refactor Control Calls**: Remove ``.control`` from all device command invocations.
     Instead of ``await mqtt.control.set_power(...)``, use ``await mqtt.set_power(...)``.
 3.  **Handle Unit Conversions**: If your integration previously performed its own
-    conversions or relied on the library's eager conversion, note that
+    conversions or relied on the library's eager conversion:
     ``DeviceStatus`` fields like ``dhw_temperature`` are now properties. They return
     values based on the global unit system context (``us_customary`` by default).
 
-    *   **Home Assistant Tip**: To ensure your state tracking is immune to unit system
+    *   **Home Assistant Tip**: To keep your state tracking immune to unit system
         toggles within the library, use the new ``*_raw`` fields (e.g.,
         ``status.dhw_temperature_raw``) for comparison logic, and use the properties
         only for display or when a converted value is explicitly needed.
@@ -1329,7 +2033,7 @@ Fixed
   ``are_aws_credentials_expired``, and ``time_until_expiry`` used
   ``datetime.now()`` (naive, local time). During DST transitions or timezone
   changes this could cause incorrect expiry detection, leading to premature
-  re-authentication or use of an actually-expired token. Fixed by using
+  re-authentication or use of an expired token. Fixed by using
   ``datetime.now(UTC)`` throughout, switching the ``issued_at`` field default
   to ``datetime.now(UTC)``, and adding a field validator to normalize any
   timezone-naive ``issued_at`` values loaded from old stored token files to UTC
@@ -1339,11 +2043,11 @@ Fixed
   format written by ``to_dict()`` for tokens stored before this fix.
 - **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.
+  but did not activate vacation mode; the operating mode remained unchanged.
   HAR capture of the official Navien app 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.
+  from 1-365 to 1-30 to match the device's actual constraint.
 - **Duplicate AWS IoT subscribe calls on reconnect**: ``resubscribe_all()``
   called ``connection.subscribe()`` (a network round-trip to AWS IoT) once per
   handler per topic. If a topic had N handlers, N identical subscribe requests
@@ -1366,7 +2070,7 @@ Fixed
 - **Once-Listener Becomes Permanent With Duplicate Callbacks**: ``emit()``
   identified once-listeners via a ``set`` of ``(event, callback)`` tuples. If
   the same callback was registered twice with ``once=True``, the set
-  deduplicated the tuple — after the first emit the second listener lost its
+  deduplicated the tuple: after the first emit the second listener lost its
   once-status and became permanent. Fixed by checking ``listener.once``
   directly on the ``EventListener`` object.
 - **Auth Session Leaked on Client Construction Failure**: In
@@ -1375,10 +2079,10 @@ Fixed
   ``auth_client.__aenter__()``, the auth session and its underlying
   ``aiohttp`` session would leak. Client construction is now wrapped in a
   ``try/except`` that calls ``auth_client.__aexit__()`` on failure.
-  Additionally, both ``except BaseException`` blocks have been replaced with
+  Both ``except BaseException`` blocks have been replaced with
   ``except Exception`` (passing real exception info to ``__aexit__``) plus a
   separate ``except asyncio.CancelledError`` block that uses
-  ``asyncio.shield()`` to ensure cleanup completes even when the task is
+  ``asyncio.shield()`` so cleanup completes even when the task is
   being cancelled.
 - **Hypothesis Tests Broke All Test Collection**: ``test_mqtt_hypothesis.py``
   imported ``hypothesis`` at module level; when it was not installed, pytest
@@ -1427,7 +2131,7 @@ Changed
 
 Fixed
 -----
-- **Week Bitfield Encoding (CRITICAL)**: 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.
+- **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``.
 - **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.
@@ -1567,13 +2271,13 @@ Changed
 
 Fixed
 -----
-- **Critical: Temperature Unit Bug in Set Operations**: Fixed incorrect temperature conversion when setting DHW temperature and reservations
+- **Temperature Unit Bug in Set Operations**: Fixed incorrect temperature conversion when setting DHW temperature and reservations
 
   - ``set_dhw_temperature()`` was calling ``fahrenheit_to_half_celsius()`` with unit-agnostic temperature parameter
   - ``build_reservation_entry()`` had the same issue
   - **Impact**: If user preferred Celsius, temperature would be interpreted as Fahrenheit, causing wrong setpoints
   - **Fix**: Use new ``preferred_to_half_celsius()`` that respects unit system context
-  - This was a critical data correctness bug that would cause incorrect device behavior for Celsius users
+  - This was a data correctness bug that would cause incorrect device behavior for Celsius users
 
 Version 7.3.2 (2026-01-25)
 ==========================
@@ -1623,7 +2327,7 @@ Added
   - Available devices and regions determine conversion support (validated at runtime)
   - ``get_field_unit()`` method retrieves the correct unit suffix for any field
   - All conversions use Pydantic ``WrapValidator`` for transparent, automatic conversion
-  - Comprehensive documentation in ``docs/guides/unit_conversion.rst``
+  - Documentation in ``docs/guides/unit_conversion.rst``
   - Example usage:
 
     .. code-block:: python
@@ -1678,7 +2382,7 @@ Fixed
 
   - **Issue**: Running ``nwp-cli --unit-system metric status`` displayed values in device's native format (imperial) with metric unit strings (e.g., "104.9 °C" instead of "40.5 °C")
   - **Root Cause**: MQTT callbacks from AWS CRT execute on different threads where context variables are not set. Since Python's context variables are task-local, the unit_system preference was not visible to validators
-  - **Solution**: Store unit_system in ``NavienMqttClient`` and ``MqttSubscriptionManager``. Before parsing MQTT messages, explicitly set the context variable in message handlers to ensure validators use the correct unit system regardless of thread context
+  - **Solution**: Store unit_system in ``NavienMqttClient`` and ``MqttSubscriptionManager``. Before parsing MQTT messages, explicitly set the context variable in message handlers so validators use the correct unit system regardless of thread context
   - **Result**: Values and units now correctly convert when ``--unit-system`` override is specified
   - **Testing**: All 393 tests pass including new unit system context override tests
 
@@ -1840,7 +2544,7 @@ Removed
   - ``DeviceCapabilityChecker`` → ``MqttDeviceCapabilityChecker``
   - ``DeviceInfoCache`` → ``MqttDeviceInfoCache``
 
-  All functionality remains identical - only the class names changed.
+  All functionality remains identical; only the class names changed.
 
 Added
 -----
@@ -1861,7 +2565,7 @@ Added
   - Simplified initialization for common use case (API + MQTT)
   - Proper async context manager support
   - Reduces boilerplate in application code
-  - Comprehensive documentation in ``docs/guides/authentication.rst``
+  - Documentation in ``docs/guides/authentication.rst``
   - Example: ``examples/intermediate/advanced_auth_patterns.py``
 
 - **VolumeCode Enum**: Tank capacity identification with gallon values
@@ -1896,7 +2600,7 @@ Added
   - ``tou_override_to_python()``: TOU override status conversion
   - ``div_10()``: Divide by 10.0 utility
   - ``enum_validator()``: Generic enum factory
-  - Comprehensive documentation explaining device protocol quirks
+  - Documentation explaining device protocol quirks
   - New ``converters.py`` module replacing scattered validators
 
 - **MQTT Event System**: Structured event handling for MQTT operations
@@ -1922,7 +2626,7 @@ Added
   - Eliminates hardcoded units in output formatter
   - Single source of truth: model metadata drives CLI display
 
-- **Comprehensive Protocol Documentation**: Complete protocol reference documentation
+- **Protocol Documentation**: Complete protocol reference documentation
 
   - New ``docs/protocol/quick_reference.rst`` with command codes, field formats, and conversions
   - Converted protocol documentation to RST format for Sphinx integration
@@ -1988,7 +2692,7 @@ Changed
   - Added factory function patterns and examples
   - Improved context manager documentation
   - Added best practices and common patterns
-  - More comprehensive code examples
+  - More code examples
 
 - **Model Refactoring**: Updated to use new converter modules
 
@@ -2068,7 +2772,7 @@ Added
   - ``configure_reservation_water_program()``: Water program reservation management
   - ``set_recirculation_mode()`` / ``configure_recirculation_schedule()`` / ``trigger_recirculation_hot_button()``: Recirculation pump control and scheduling
 
-- **CLI Documentation Updates**: Comprehensive documentation updates for subcommand-based CLI
+- **CLI Documentation Updates**: Documentation updates for subcommand-based CLI
   - Complete rewrite of ``docs/python_api/cli.rst`` with full command reference
   - Updated README.rst with new subcommand syntax and examples
   - Added 8+ practical usage examples (cron jobs, automation, monitoring)
@@ -2151,14 +2855,14 @@ Removed
 Added
 -----
 
-- **Python 3.12+ Optimizations**: Leverage latest Python features
+- **Python 3.12+ Optimizations**: Use the latest Python features
 
   - PEP 695: New type parameter syntax (``def func[T](...)`` instead of ``TypeVar``)
   - Use ``datetime.UTC`` constant instead of ``datetime.timezone.utc``
   - Native union syntax (``X | Y`` instead of ``Union[X, Y]``)
   - Cleaner generic type annotations throughout codebase
 
-- **Enumerations Module (``src/nwp500/enums.py``)**: Comprehensive type-safe enums for device control and status
+- **Enumerations Module (``src/nwp500/enums.py``)**: Type-safe enums for device control and status
 
   - Status value enums: ``OnOffFlag``, ``Operation``, ``DhwOperationSetting``, ``CurrentOperationMode``, ``HeatSource``, ``DREvent``, ``WaterLevel``, ``FilterChange``, ``RecirculationMode``
   - Time of Use enums: ``TouWeekType``, ``TouRateType``
@@ -2167,7 +2871,7 @@ Added
   - Error code enum: ``ErrorCode`` with complete error code mappings
   - Human-readable text mappings for all enums (e.g., ``DHW_OPERATION_SETTING_TEXT``, ``ERROR_CODE_TEXT``)
   - Exported from main package: ``from nwp500 import OnOffFlag, ErrorCode, CommandCode``
-  - Comprehensive documentation in ``docs/enumerations.rst``
+  - Documentation in ``docs/enumerations.rst``
   - Example usage in ``examples/error_code_demo.py``
 
 Changed
@@ -2194,7 +2898,7 @@ Changed
   - CLI and other consumers benefit from automatic enum name serialization
   - Text mappings available for custom formatting (e.g., `DHW_OPERATION_TEXT[enum]` → "Heat Pump Only")
 
-- **Documentation**: Comprehensive updates across protocol and API documentation
+- **Documentation**: Updates across protocol and API documentation
 
   - ``docs/guides/time_of_use.rst``: Clarified TOU override status behavior (1=OFF/override active, 2=ON/normal operation)
   - ``docs/protocol/data_conversions.rst``: Updated TOU field descriptions with correct enum values
@@ -2235,7 +2939,7 @@ Added
   - Export diagnostics to JSON for analysis and debugging
   - Home Assistant integration support for custom components
   - ``examples/mqtt_diagnostics_example.py`` demonstrating usage patterns
-  - Comprehensive documentation in ``docs/MQTT_DIAGNOSTICS.rst``
+  - Documentation in ``docs/MQTT_DIAGNOSTICS.rst``
   - Exported from main package: ``from nwp500 import MqttDiagnosticsCollector``
 
 Version 6.1.0 (2025-12-03)
@@ -2323,7 +3027,7 @@ Version 6.0.6 (2025-11-24)
 Added
 -----
 
-- **Field Descriptions**: Added comprehensive Field descriptions to ``DeviceStatus`` and ``DeviceFeature`` models with full documentation details including units, ranges, and usage context
+- **Field Descriptions**: Added Field descriptions to ``DeviceStatus`` and ``DeviceFeature`` models with full documentation details including units, ranges, and usage context
 
 Fixed
 -----
@@ -2341,7 +3045,7 @@ Version 6.0.5 (2025-11-21)
 Fixed
 -----
 
-- **CRITICAL Temperature Conversion Bug**: Corrected temperature conversion formula for 8 sensor fields that were displaying values ~100°F higher than expected. The v6.0.4 change incorrectly used division by 5 (pentacelsius) instead of division by 10 (decicelsius) for these fields:
+- **Temperature Conversion Bug**: Corrected temperature conversion formula for 8 sensor fields that were displaying values ~100°F higher than expected. The v6.0.4 change incorrectly used division by 5 (pentacelsius) instead of division by 10 (decicelsius) for these fields:
 
   - ``tank_upper_temperature`` - Water tank upper sensor
   - ``tank_lower_temperature`` - Water tank lower sensor
@@ -2568,7 +3272,7 @@ Fixed
   - Applied consistent cancellation handling across all MQTT operations (connect, disconnect, subscribe, unsubscribe, publish)
   - AWS CRT callbacks can now complete independently without raising InvalidStateError
   - Added debug logging when operations are cancelled for better diagnostics
-  - Ensures clean shutdown without spurious exception messages
+  - Clean shutdown without spurious exception messages
 
 Version 5.0.1 (2025-10-27)
 ==========================
@@ -2591,7 +3295,7 @@ Changed
 Version 5.0.0 (2025-10-27)
 ==========================
 
-**BREAKING CHANGES**: This release introduces a comprehensive enterprise exception architecture.
+**BREAKING CHANGES**: This release introduces an enterprise exception architecture.
 See migration guide below for details on updating your code.
 
 Added
@@ -2599,7 +3303,7 @@ Added
 
 - **Enterprise Exception Architecture**: Complete exception hierarchy for better error handling
 
-  - Created ``exceptions.py`` module with comprehensive exception hierarchy
+  - Created ``exceptions.py`` module with an exception hierarchy
   - Added ``Nwp500Error`` as base exception for all library errors
   - Added MQTT-specific exceptions: ``MqttError``, ``MqttConnectionError``, ``MqttNotConnectedError``,
     ``MqttPublishError``, ``MqttSubscriptionError``, ``MqttCredentialsError``
@@ -2608,9 +3312,9 @@ Added
     ``DeviceOperationError``
   - All exceptions now include ``error_code``, ``details``, and ``retriable`` attributes
   - Added ``to_dict()`` method to all exceptions for structured logging
-  - Added comprehensive test suite in ``tests/test_exceptions.py``
-  - **Added comprehensive exception handling example** (``examples/exception_handling_example.py``)
-  - **Updated key examples** to demonstrate new exception handling patterns
+  - Added a test suite in ``tests/test_exceptions.py``
+  - **Added an exception handling example** (``examples/exception_handling_example.py``)
+  - **Updated the main examples** to demonstrate new exception handling patterns
 
 Changed
 -------
@@ -2857,7 +3561,7 @@ Fixed
   - Preserves AWS credential expiration timestamps during token refresh
   - Prevents reconnection failures when connection interrupts after AWS credentials expire but before JWT tokens expire
   - Resolves AWS_ERROR_HTTP_WEBSOCKET_UPGRADE_FAILURE errors during reconnection attempts
-  - Improved test coverage for auth module from 31% to 60% with comprehensive test suite
+  - Improved test coverage for auth module from 31% to 60%
 
 Version 3.1.3 (2025-10-24)
 ==========================
@@ -2905,7 +3609,7 @@ Fixed
 
   - Updated callback to match latest AWS IoT SDK signature: ``(connection, error, **kwargs)``
   - Fixed type annotations in ``MqttConnection`` for proper type checking
-  - Resolves mypy type checking errors and ensures AWS SDK compatibility
+  - Resolves mypy type checking errors and keeps AWS SDK compatibility
   - Fixed E501 line length linting issue in connection interruption handler
 
 Version 3.0.0 (Unreleased)
@@ -2949,7 +3653,7 @@ Added
   - Prevents accidental comparison of user preferences with real-time states
   - Better IDE support with more specific enum types
 
-- **Migration Support**: Comprehensive tools for smooth migration
+- **Migration Support**: Tools for migration
 
   - ``migrate_operation_mode_usage()`` helper function with programmatic guidance
   - ``MIGRATION.md`` with step-by-step migration instructions
@@ -3001,12 +3705,12 @@ Version 0.2 (Unreleased)
 Added
 -----
 
-- **Local/CI Linting Synchronization**: Complete tooling to ensure consistent linting results
+- **Local/CI Linting Synchronization**: Tooling for consistent linting results
 
   - Multiple sync methods: tox (recommended), direct scripts, pre-commit hooks, Makefile commands
   - CI-identical scripts: ``scripts/lint.py`` and ``scripts/format.py`` mirror ``tox -e lint`` and ``tox -e format``
   - Pre-commit hooks configuration for automatic checking
-  - Comprehensive documentation: ``LINTING_SETUP.md``, ``DEVELOPMENT.md``, ``FIX_LINTING.md``
+  - Documentation: ``LINTING_SETUP.md``, ``DEVELOPMENT.md``, ``FIX_LINTING.md``
   - Makefile commands: ``make ci-lint``, ``make ci-format``, ``make ci-check``
   - Standardized ruff configuration across all environments
   - Eliminates "passes locally but fails in CI" issues
@@ -3057,7 +3761,7 @@ Added
   - Enabled by default for reliability
   - ``queued_commands_count`` property for monitoring
   - ``clear_command_queue()`` method for manual management
-  - Integrates seamlessly with automatic reconnection
+  - Works with automatic reconnection
   - Example: ``command_queue_demo.py``
   - Documentation: ``COMMAND_QUEUE.rst``
 
@@ -3096,7 +3800,7 @@ Added
   - ``subscribe_device_feature()`` - Automatic parsing of feature messages into ``DeviceFeature`` objects
   - ``subscribe_energy_usage()`` - Automatic parsing of energy usage responses into ``EnergyUsageResponse`` objects
   - Type-safe callbacks with IDE autocomplete support
-  - Comprehensive error handling and logging
+  - Error handling and logging
   - Example scripts demonstrating usage patterns
 
 - **Energy Usage API (EMS)**: Historical energy consumption data
@@ -3111,7 +3815,7 @@ Added
   - Energy consumption data (Watt-hours)
   - Efficiency percentage calculations
 
-- **Data Models**: Comprehensive type-safe models
+- **Data Models**: Type-safe models
 
   - ``DeviceStatus`` dataclass with 125 sensor and operational fields
   - ``DeviceFeature`` dataclass with 46 capability and configuration fields
@@ -3150,7 +3854,7 @@ Added
   - Typed callbacks implementation guide
   - Control command reference with verified command codes
   - Example scripts for common use cases
-  - Comprehensive troubleshooting guides
+  - Troubleshooting guides
   - Complete energy data reference (ENERGY_DATA_SUMMARY.md)
 
 - **Examples**: Production-ready example scripts
@@ -3192,14 +3896,14 @@ Changed
   - Removed "Optional Feature" and "not required for basic operation" phrases
   - Fixed table rendering in DEVICE_STATUS_FIELDS.rst
   - Fixed JSON syntax in code examples
-  - Added comprehensive reconnection documentation
-  - Added comprehensive command queue documentation
+  - Added reconnection documentation
+  - Added command queue documentation
   - Cleaned up backward compatibility references (new library)
 
 Fixed
 -----
 
-- **Critical Bug**: Thread-safe reconnection task creation from MQTT callbacks
+- **Bug**: Thread-safe reconnection task creation from MQTT callbacks
 
   - Fixed ``RuntimeError: no running event loop`` when connection is interrupted
   - Fixed ``RuntimeWarning: coroutine '_reconnect_with_backoff' was never awaited``
@@ -3207,9 +3911,9 @@ Fixed
   - Implemented ``_start_reconnect_task()`` helper method to properly create reconnection tasks
   - Uses existing ``_schedule_coroutine()`` method for thread-safe task scheduling
   - Prevents crashes during automatic reconnection after connection interruptions
-  - Ensures reconnection tasks are properly awaited and executed
+  - Reconnection tasks are awaited and executed
 
-- **Critical Bug**: Thread-safe event emission from MQTT callbacks
+- **Bug**: Thread-safe event emission from MQTT callbacks
 
   - Fixed ``RuntimeError: no running event loop in thread 'Dummy-1'``
   - MQTT callbacks run in separate threads created by AWS IoT SDK
@@ -3234,7 +3938,7 @@ Fixed
   - Updated built HTML documentation files
   - Protects privacy in public documentation
 
-- **Critical Bug**: Device control command codes
+- **Bug**: Device control command codes
 
   - Fixed incorrect command code usage causing unintended power-off
   - Power-off now uses command code ``33554433``
@@ -3242,7 +3946,7 @@ Fixed
   - DHW mode control now uses command code ``33554437``
   - Discovered through network traffic analysis of official app
 
-- **Critical Bug**: MQTT topic pattern matching with wildcards
+- **Bug**: MQTT topic pattern matching with wildcards
 
   - Fixed ``_topic_matches_pattern()`` to correctly handle ``#`` wildcard
   - Topics now match when message arrives on base topic (e.g., ``cmd/52/device/res``)
@@ -3262,9 +3966,9 @@ Fixed
   - Examples now subscribe to broader topic patterns
   - Subscribe to ``cmd/{device_type}/{device_topic}/#`` to catch all command messages
   - Subscribe to ``evt/{device_type}/{device_topic}/#`` to catch all event messages
-  - Ensures all device responses are received
+  - All device responses are received
 
-- **Enhancement**: Robust enum conversion with fallbacks
+- **Enhancement**: Enum conversion with fallbacks
 
   - Added try/except blocks for all enum conversions in ``DeviceStatus.from_dict()``
   - Added try/except blocks for all enum conversions in ``DeviceFeature.from_dict()``