Document Hermes update operation and verified stable no-op fix

docs/HERMES_UPDATE.md

@@ -0,0 +1,69 @@
+# Hermes-Update betreiben und prüfen
+
+## Bereits aktuelle Stable-Version
+
+Der Updater prüft zunächst den konfigurierten Remote-Branch (standardmäßig
+`origin/main`). Den tatsächlichen Zielstand wählt anschließend `hermes update`
+anhand des Hermes-Update-Kanals. Bei Stable kann der installierte Release-Commit
+aktuell sein, obwohl auf `main` neuere Entwicklungscommits liegen.
+
+Bis zur Korrektur vom 21.10.2026 endete dieser Fall trotz `Already up to date!`
+und Updater-Exitcode 0 mit einem fehlgeschlagenen Wartungsdienst. Das Skript
+forderte fälschlich einen Commitwechsel. Jetzt endet ein erfolgreicher Updater
+mit unverändertem Commit nach den Konfigurations- und Gateway-Prüfungen
+erfolgreich. Der Kanal wird durch diese Korrektur nicht geändert.
+
+Ein fehlgeschlagener Updater bei unverändertem Commit liefert weiterhin Exitcode
+1. Ein ungesunder Gateway löst weiterhin den vorhandenen Rollback aus. Der
+separate llama-Endpunkt wird unabhängig geprüft; dessen Ausfall führt nicht zu
+einem Hermes-Rollback.
+
+## Nur den korrigierten Wrapper installieren
+
+Im Repository-Verzeichnis ausführen, wenn gerade kein Update läuft. Vorher
+laufende Hermes-Aufgaben beenden lassen. Diese gezielte Installation ersetzt nur
+den Wrapper; `./install.sh` installiert dagegen alle versionierten Wrapper/Units.
+
+```bash
+make test
+backup_dir="$(mktemp -d "$HOME/.local/state/hermes-update-wrapper.XXXXXXXX")"
+cp -p ~/.local/libexec/hermes-stack-hermes-update "$backup_dir/"
+printf 'Wrapper-Sicherung: %s\n' "$backup_dir"
+install -m 0755 libexec/hermes-stack-hermes-update \
+  ~/.local/libexec/hermes-stack-hermes-update
+cmp libexec/hermes-stack-hermes-update \
+  ~/.local/libexec/hermes-stack-hermes-update
+```
+
+Die Unit bleibt unverändert; dafür ist kein `daemon-reload` erforderlich.
+Die vorherige Wrapper-Version liegt im ausgegebenen bzw. in `$backup_dir`
+gespeicherten Sicherungsverzeichnis. Bei Bedarf dieselbe Datei mit `install
+-m 0755` zurückkopieren, während kein Update läuft.
+
+## Manueller Lauf und Diagnose
+
+Der Lauf kann den Gateway kurz stoppen und neu starten. Er erzeugt nach dem
+Remote-Vergleich gegebenenfalls auch dann ein Backup, wenn Stable bereits aktuell
+ist. Standardmäßig werden die drei neuesten Hermes-Backups behalten.
+
+```bash
+systemctl --user start hermes-stack-hermes-update.service
+systemctl --user show hermes-stack-hermes-update.service \
+  -p ActiveState -p SubState -p Result -p ExecMainStatus
+systemctl --user is-active hermes-gateway.service
+journalctl --user -u hermes-stack-hermes-update.service -n 100 --no-pager
+journalctl --user -t hermes-stack-maintenance -n 100 --no-pager
+```
+
+Erwartet: `Result=success`, `ExecMainStatus=0` und ein aktiver Gateway. Als
+`Type=oneshot` ist der Update-Dienst nach erfolgreichem Abschluss selbst wieder
+`inactive/dead`. Die Meldung `Hermes ist im konfigurierten Update-Kanal bereits
+aktuell` bestätigt den erfolgreichen Lauf ohne Versionswechsel.
+
+Updater-Ausgaben liegen zusätzlich unter
+`~/.local/state/hermes-stack-maintenance/hermes-update-*.log`.
+Wrapper-Abschlussmeldungen stehen im Dienstjournal; die Benachrichtigung schreibt
+zusätzlich unter dem Tag `hermes-stack-maintenance`.
+
+Die Abnahme auf Archwork und ihre Prüfgrenzen stehen in
+[VALIDATION.md](VALIDATION.md).