docs: showpiece README — mermaid architecture, sensor/alert tables [#762]

Also absorbs PFVCluster operator tooling: tools/ha-ws-call.py and
docs/reference-packs/ (historical, NOT loaded by HA — clearly marked).
No live-config changes in this commit.

Detail: https://projects.knownelement.com/issues/762

docs/reference-packs/automations-ups-alerts.yaml

@@ -0,0 +1,140 @@
+# REFERENCE ONLY — historical packs, NOT loaded by HA (superseded by packages/; kept for lineage). Statuses in the repo README.
+# PFV UPS + plant alert automations for Home Assistant [#439]
+#
+# Paste into automations.yaml (or via UI: paste YAML directly into the
+# automation editor). Delivery target: notify.pushover (add the Pushover
+# integration first; interim targets that exist today:
+# notify.mobile_app_ultix_sidecar / notify.mobile_app_ultix_mini /
+# notify.mobile_app_allthes_ipad).
+#
+# ENTITY IDs: created by the NUT integration when you add the two UPS config
+# entries (Settings > Devices & Services > Add Integration > Network UPS
+# Tools; hosts pfv-tsys1.knel.net and pfv-tsys9.knel.net, port 3493, user
+# homeassistant + the upsd.users password). Suggested device names:
+# "tsys1 ups" and "tsys9 ups" -> entities below. If HA names them
+# differently, check Developer Tools > States (search "_ups_status") and
+# edit the entity_id lines to match. Nothing else needs changing.
+
+- alias: "PFV plant - UPS on battery"
+  id: pfv_plant_ups_on_battery
+  mode: single
+  triggers:
+    - trigger: state
+      entity_id:
+        - sensor.tsys1_ups_status
+        - sensor.tsys9_ups_status
+  conditions:
+    - condition: template
+      value_template: >-
+        {{ 'On Battery' in states(trigger.entity_id) }}
+  actions:
+    - action: notify.send_message
+      target:
+        entity_id: notify.pushover
+      data:
+        title: "POWER OUTAGE"
+        message: >-
+          {{ state_attr(trigger.entity_id, 'friendly_name') }} lost utility
+          power and is ON BATTERY at {{ states('sensor.' ~ trigger.entity_id.split('.')[1] | replace('_status', '_battery_charge')) }}% charge.
+
+- alias: "PFV plant - UPS battery low"
+  id: pfv_plant_ups_battery_low
+  mode: single
+  triggers:
+    - trigger: numeric_state
+      entity_id:
+        - sensor.tsys1_ups_battery_charge
+        - sensor.tsys9_ups_battery_charge
+      below: 40
+  conditions:
+    - condition: template
+      value_template: >-
+        {{ 'On Battery' in states(trigger.entity_id | replace('_battery_charge', '_status')) }}
+  actions:
+    - action: notify.send_message
+      target:
+        entity_id: notify.pushover
+      data:
+        title: "UPS BATTERY LOW"
+        message: >-
+          {{ trigger.entity_id }} at {{ states(trigger.entity_id) }}% while on
+          battery. Start graceful shutdown of VMs before hypervisors (#455 ordering).
+        data:
+          priority: 1
+
+- alias: "PFV plant - UPS communication lost"
+  id: pfv_plant_ups_comm_lost
+  mode: single
+  triggers:
+    - trigger: state
+      entity_id:
+        - sensor.tsys1_ups_status
+        - sensor.tsys9_ups_status
+      to: unavailable
+      for: "00:05:00"
+  actions:
+    - action: notify.send_message
+      target:
+        entity_id: notify.pushover
+      data:
+        title: "UPS COMMS LOST"
+        message: >-
+          {{ trigger.entity_id }} unreachable for 5 minutes (nut-server or
+          network path down; tsys1 also hosts pfv-bms itself).
+        data:
+          priority: 1
+
+- alias: "PFV plant - utility power restored"
+  id: pfv_plant_ups_power_restored
+  mode: single
+  triggers:
+    - trigger: state
+      entity_id:
+        - sensor.tsys1_ups_status
+        - sensor.tsys9_ups_status
+  conditions:
+    - condition: template
+      value_template: >-
+        {{ trigger.from_state is not none and 'On Battery' in trigger.from_state.state
+           and 'On Battery' not in states(trigger.entity_id) }}
+  actions:
+    - action: notify.send_message
+      target:
+        entity_id: notify.pushover
+      data:
+        title: "Power restored"
+        message: >-
+          {{ state_attr(trigger.entity_id, 'friendly_name') }} is back ONLINE.
+
+- alias: "PFV plant - high temperature"
+  id: pfv_plant_high_temperature
+  mode: single
+  triggers:
+    - trigger: numeric_state
+      entity_id:
+        - sensor.pfv_artroom_temperature
+        - sensor.pfv_garage_temperature
+        - sensor.pfv_tsys1_rack_temperature
+        - sensor.pfv_tsys3_cpu_temperature
+        - sensor.pfv_tsys4_ambient_temperature
+        - sensor.pfv_tsys5_ambient_temperature
+        - sensor.pfv_tsys6_cpu_temperature
+        - sensor.pfv_tsys7_cpu_temperature
+        - sensor.pfv_tsys9_cpu_temperature
+        - sensor.pfv_jetson_temperature
+        - sensor.pfv_svrpi_temperature
+        - sensor.pfv_subopi3_temperature
+        - sensor.pfv_subopi_dev_3_temperature
+        - sensor.pfv_subopi_dev_4_temperature
+      above: 104
+  actions:
+    - action: notify.send_message
+      target:
+        entity_id: notify.pushover
+      data:
+        title: "HIGH TEMPERATURE"
+        message: >-
+          {{ trigger.entity_id }} is {{ states(trigger.entity_id) }}°F
+          (threshold 104°F). Check cooling/airflow.
+        data:
+          priority: 1