Document backup pipeline behaviour

lib/mqtt.sh

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Shared mosquitto_pub/mosquitto_sub argument construction.
+# Passwords are read from a protected file rather than placed in .env or Git.
 
 mqtt_common_args() {
   MQTT_ARGS=(-h "$MQTT_HOST" -p "$MQTT_PORT")
@@ -14,6 +16,8 @@ mqtt_publish() {
   [[ -n "$MQTT_HOST" ]] || die "MQTT_HOST is not configured"
   require_command mosquitto_pub
   mqtt_common_args
+  # Backup state is retained so Home Assistant receives the latest result after
+  # reconnecting. Command messages are handled separately and are never kept.
   (( retain )) && MQTT_ARGS+=(-r)
   mosquitto_pub "${MQTT_ARGS[@]}" -t "$topic" -m "$payload"
 }