Add MQTT backup reporting and trigger listener

README.md

@@ -135,6 +135,48 @@ sudo stages/90-prune.sh --dry-run
 `--force` runs a transfer method even when its `*_ENABLED` value is false. It
 still requires the method's destination to be configured and available.
 
+## MQTT reporting and Home Assistant trigger
+
+Enable retained run results in the host's `.env`:
+
+```bash
+MQTT_REPORT_ENABLED=1
+MQTT_HOST="beaver"
+MQTT_PORT=1883
+MQTT_USERNAME="dockerbackup"
+MQTT_PASSWORD_FILE="/etc/zorruno-docker-backup/mqtt-password"
+MQTT_STATUS_TOPIC="viewroad-status/dockerbackup/panda"
+MQTT_COMMAND_TOPIC="viewroad-commands/dockerbackup/panda/run"
+```
+
+The retained status JSON includes overall status, timestamps, duration, exit
+code, container totals, successful backups, dry-run counts, and error messages.
+Final reporting runs from an exit trap, so failures in any earlier stage are
+reported when MQTT remains available.
+
+Install the optional root-run command listener with:
+
+```bash
+cp systemd/zorruno-docker-backup-mqtt.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable --now zorruno-docker-backup-mqtt.service
+```
+
+It accepts only JSON containing the exact action `run` on the configured
+command topic:
+
+```json
+{"action":"run"}
+```
+
+Publish commands without MQTT retain. The listener also ignores retained
+messages, preventing an old command from starting another backup after a
+listener or broker restart.
+
+Restrict publish access to the command topic with broker ACLs. The listener
+runs as root because the backup stage controls Docker containers. The existing
+pipeline lock prevents concurrent runs.
+
 ## Adding another backup method
 
 Add an executable script named `methods/NN-name.sh`, for example