fan-control docs: sync runbook/env/service/design to the HA-actuator + anti-flap model

The committed docs still described the 2026-06-04 presence-aware daemon. Bring
them in line with what is actually deployed: HA computes the setpoint, the host
is a thin actuator (COMMAND_ENTITY/STALE_SECS/HA_GRACE_SECS), additive bias,
anti-flap hold-last, and the new HA readout sensors (command/equilibrium/
cpu_load/fan_speed_avg/fan_power_avg). Earlier doc edits were made in a clone
lost in the workstation reshuffle; re-created here.

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

scripts/fan-control.env.example

@@ -1,21 +1,27 @@
-# /etc/fan-control.env  —  config for the fan-control daemon (chmod 600).
+# /etc/fan-control.env  —  config for the fan-control ACTUATOR (chmod 600).
 # Deployed manually to the PVE host; the real file holds a secret token and is
 # NOT committed. Copy this template, fill HA_TOKEN, scp to /etc/fan-control.env.
+#
+# The control logic lives in Home Assistant (curve + bias + hysteresis +
+# setpoint). This daemon only reads the HA-computed % and applies it over IPMI.
 
 # Long-lived ha-sofia access token (Home Assistant -> Profile -> Security ->
-# Long-lived access tokens). Empty => presence disabled, daemon runs COOL-only.
+# Long-lived access tokens). Used to read COMMAND_ENTITY. Empty/unreachable =>
+# the actuator hands the fans to Dell auto (it cannot compute a setpoint itself).
 HA_TOKEN=
 
 # --- optional overrides (defaults shown) ---
 # HA_URL=http://192.168.1.8:8123
-# GARAGE_ENTITY=sensor.garage_door_state_bg
-# GARAGE_OPEN_STATE=Отворена
-# HOLD_SECS=900            # quiet-mode hold after last garage activity (15 min)
+# COMMAND_ENTITY=sensor.r730_fan_command_pct  # HA-computed fan %; we only apply it
+# STALE_SECS=1800          # command older than this => stale. Loose on purpose:
+#                          # staleness only happens when CPU temp is flat (so the
+#                          # held value is still valid); a rising temp re-renders it.
+# HA_GRACE_SECS=300        # on a transient HA miss, HOLD the last applied % this
+#                          # long before handing the fans to Dell auto (anti-flap)
 # LOOP_INTERVAL=15
-# PRESENCE_INTERVAL=30
-# DEADBAND=3
-# CEILING=83               # degC: hand back to Dell auto at/above this
+# CEILING=83               # degC: hand back to Dell auto at/above this (hardware safety)
 # RESUME_BELOW=75
 # RESUME_STABLE=120
 # MAX_IPMI_FAILS=3
+# MIN_STEP=3               # smallest fan-% change worth an IPMI write (anti-jitter)
 PUSHGATEWAY_URL=http://10.0.20.100:30091