various tidyups

packages/ha_summary.yaml

@@ -1,11 +1,54 @@
 #:########################################################################################:#
-# Home Assistant Summary Package - V2                                                       #
+# Home Assistant Summary Package - V2                                                    #
 #:########################################################################################:#
 #
-# Uses V2 entity IDs to avoid stale/ghost entities from earlier versions.
+# TITLE:
+#   Home Assistant Summary V2
 #
-# Dashboard entity prefix:
-#   sensor.ha_summary_v2_...
+# FILE:
+#   packages/ha_summary.yaml
+#
+# VERSION:
+#   V2.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V2.1 2026-07-20
+#     - Added structured documentation for refresh behavior and counting rules.
+#     - Documented heuristic classifications and their limitations.
+#
+#   V2.0
+#     - Introduced V2 entity IDs to avoid stale entities from earlier versions.
+#
+# PURPOSE:
+#   Provides dashboard summary sensors for Home Assistant entities, devices,
+#   areas, cameras, scenes, scripts, automations, add-ons, and updates.
+#
+#   It also provides device and entity counts for ESPHome, Tasmota, ZHA,
+#   Zigbee2MQTT, Matter, and selected cloud integrations.
+#
+# OUTPUTS:
+#   Dashboard entity prefix:
+#     sensor.ha_summary_v2_...
+#
+# REFRESH:
+#   Sensors refresh when Home Assistant starts, when the entity, device, or area
+#   registries change, when core configuration changes, and every five minutes.
+#
+# COUNTING NOTES:
+#   - Total devices counts distinct device IDs associated with current entities.
+#     Devices without entities are not included.
+#   - Broken entities are entities whose state is unknown or unavailable.
+#   - Add-ons are inferred from Supervisor update entities, excluding the Core,
+#     Supervisor, and Operating System update entities.
+#   - Zigbee2MQTT devices and entities are identified by searching MQTT device
+#     metadata for "zigbee2mqtt".
+#   - Matter Wi-Fi and Thread classifications search device metadata for known
+#     transport terms. These are heuristics rather than authoritative transport
+#     data, and a device can match both categories.
+#   - Matter unclassified counts subtract Wi-Fi and Thread counts from totals, so
+#     overlapping classifications can affect the result.
+#   - Cloud counts use the explicit integration list in the final two sensors.
+#     Add or remove integration domains there when maintaining cloud coverage.
 #
 
 template: