Initial commit

README.md

@@ -0,0 +1,208 @@
+# Hermes Arch Stack
+
+Reproduzierbares Benutzer-Deployment für Hermes Agent auf Arch Linux mit:
+
+- offizieller Hermes-Git-Installation unter `~/.hermes/hermes-agent`
+- von Hermes erzeugtem systemd-User-Service für den Messaging Gateway
+- optionalem lokalen llama.cpp/OpenAI-kompatiblen Modellendpunkt
+- optionalem signal-cli HTTP-Daemon
+- robustem Hermes-Update mit Vorprüfung, Retry, Backup und Rollback
+- regelmäßigen Healthchecks und Selbstheilungsversuchen
+- Statusmeldungen an Telegram und Signal
+- systemd-Timern für Updates und Zustandsprüfungen
+- optionalem CUDA-Build von llama-server, llama-cli und llama-bench
+- Qwen-/RTX-3080-Profilen mit prüfbarem Wechsel und Rückweg
+
+Stand: 2026-09-05. Für deine **bestehende Workstation** zuerst
+[`docs/WORKSTATION.md`](docs/WORKSTATION.md) lesen. Der Schnellstart unten ist für
+eine neue Maschine. Hardware-Leistungsgewinne sind noch nicht auf deiner GPU
+gemessen. Es wird kein Gitea-Server angelegt und nichts automatisch gepusht.
+
+Das Repository enthält **keine Zugangsdaten, Signal-Sitzung oder
+Modellgewichte**. Diese Daten werden lokal angelegt und sind durch `.gitignore`
+ausgeschlossen.
+
+## Schnellstart auf einer neuen Arch-Maschine
+
+```bash
+git clone ssh://git@GITEA/OWNER/hermes-arch-stack.git
+cd hermes-arch-stack
+
+./install.sh --install-packages --install-hermes
+```
+
+Für den lokalen GPU-Endpunkt anschließend den
+[`CUDA-Installer`](docs/LLAMA_INSTALL.md) ausführen. Ein vorhandener Server kann
+stattdessen über `LLAMA_SERVER_BIN` verwendet werden. Der Installer benötigt
+funktionierende NVIDIA-Treiber; diese werden nicht von diesem Repo eingerichtet.
+`--install-packages` führt ein vollständiges `pacman -Syu` aus: bei Kernel-/
+Treiberänderungen einen Neustart einplanen.
+
+Danach die beim ersten Lauf erzeugten lokalen Konfigurationen bearbeiten:
+
+```bash
+$EDITOR ~/.config/hermes-stack-maintenance/config.env
+$EDITOR ~/.config/hermes-stack-maintenance/llama.env
+$EDITOR ~/.config/hermes-stack-maintenance/signal-cli.env
+$EDITOR ~/.hermes/.env
+```
+
+Hermes und die Messaging-Plattformen konfigurieren:
+
+```bash
+hermes setup
+hermes gateway setup
+hermes gateway install --force
+```
+
+In Hermes als lokalen OpenAI-kompatiblen Endpunkt `http://127.0.0.1:8080/v1`
+und als Modell-ID `qwen38-27b-local` wählen. Bestehende Hermes-Konfigurationen,
+Profile, Skills und Memories werden nicht durch generische Vorgaben ersetzt.
+Für Neuinstallationen diese Einstellungen interaktiv vornehmen oder die eigenen
+Daten gemäß Migration sicher übernehmen. Der Alias allein setzt kein Kontextlimit.
+
+Signal benötigt zusätzlich eine installierte/verknüpfte signal-cli-Instanz.
+Nach Konfiguration kann `./scripts/install-signal-cli.sh` den vorhandenen
+Signal-Updater aufrufen; siehe dessen Konfiguration und `docs/MIGRATION.md`.
+
+Optionale Dienste erst nach ihrer Konfiguration aktivieren:
+
+```bash
+systemctl --user enable --now signal-cli.service
+systemctl --user enable --now llama-qwen.service
+```
+
+Maintenance aktivieren:
+
+```bash
+systemctl --user enable --now \
+  hermes-stack-hermes-update.timer \
+  hermes-stack-health.timer \
+  hermes-stack-signal-health.timer \
+  hermes-stack-signal-update-check.timer
+```
+
+Für Start ohne interaktive Anmeldung:
+
+```bash
+sudo loginctl enable-linger "$USER"
+```
+
+Abschließend:
+
+```bash
+~/.local/libexec/hermes-stack-doctor
+```
+
+## Installationsoptionen
+
+```text
+./install.sh [Optionen]
+
+  --install-packages  Arch-Pakete mit pacman installieren
+  --install-hermes    offiziellen Hermes-Installer ausführen
+  --install-llama     CUDA-Build installieren (benötigt funktionierenden Treiber)
+  --llama-ref REF     expliziter llama.cpp-Tag/Commit oder bewusst master
+  --enable-timers     Maintenance-Timer sofort aktivieren
+  --skip-browser      Hermes ohne Browser-Automation installieren (Standard)
+  --with-browser      Browser-Automation nicht überspringen
+```
+
+Ohne Optionen installiert das Skript nur die versionierten Dateien und legt
+fehlende Beispielkonfigurationen an. Bestehende lokale Konfigurationen werden
+nicht überschrieben.
+Ersetzte Wrapper und Units werden vorher gesichert. Eine vorhandene
+hermes-gateway.service wird nicht neu erzeugt. Ein Modell wird erst beim echten
+Start des llama-Dienstes geladen, nicht bei der Konfigurationsprüfung.
+
+## RTX 3080 und Qwen
+
+```bash
+~/.local/libexec/hermes-stack-llama-run --check
+~/.local/libexec/hermes-stack-llama-profile list
+~/.local/libexec/hermes-stack-llama-report
+```
+
+`baseline` behält deine bisherigen 64K Kontext / 1536 MiB Fit-Zielmarge.
+`balanced` reduziert nur den Kontext auf 48K; `vram-plus` danach optional die
+Marge auf 1280 MiB. `compact` bietet 32K bei 1536 MiB. Das sind Vergleichsprofile,
+keine Garantie gegen Desktop-Speicherdruck. Details, Messprotokoll und Rücknahme:
+[`docs/RTX3080.md`](docs/RTX3080.md).
+
+Profilwechsel ändern zunächst nur eine separate Auswahl-Datei. Ein Neustart
+benötigt `hermes-stack-llama-restart --jobs-finished`. Der Healthcheck teilt das
+Update-Lock und löst bei Backend-HTTP-Timeouts keine Inferenz-Neustarts mehr aus.
+
+## Update-Verhalten
+
+`hermes-stack-hermes-update` führt folgende Schritte aus:
+
+1. exklusives Lock und Prüfung auf lokale Änderungen
+2. `origin/main`-Fetch mit begrenzten Retries und letztem HTTP/1.1-Fallback
+3. schneller Abschluss ohne Backup, wenn kein Update vorliegt
+4. komprimiertes Backup vor jeder Änderung
+5. Stoppen des Gateways und Aufruf von `hermes update`
+6. einmaliger Retry bei eindeutig transientem Fetch-Fehler
+7. Konfigurationsmigration und frischer Gateway-Neustart
+8. Gateway-Healthcheck; bei Fehler Wiederherstellung des gesicherten Checkouts und der erfassten Konfigurationsdateien
+9. separater llama.cpp-Healthcheck ohne unsinnigen Hermes-Rollback
+10. Aufbewahrung der drei neuesten Hermes-Backups
+
+Ein Fehler von Telegram oder Signal kann den Updateprozess niemals fehlschlagen
+lassen. Detaillierte Zwischenstände landen im Journal; nur zusammengefasste
+Ergebnisse werden versendet.
+
+## Bedienung
+
+```bash
+# Update manuell
+systemctl --user start hermes-stack-hermes-update.service
+
+# Status und Logs
+systemctl --user status hermes-stack-hermes-update.service
+journalctl --user -u hermes-stack-hermes-update.service -n 200
+journalctl --user -t hermes-stack-maintenance -n 100
+
+# Benachrichtigung testen
+~/.local/libexec/hermes-stack-notify \
+  "Hermes-Stack: Benachrichtigungstest"
+
+# signal-cli nach einer Update-Meldung aktualisieren
+~/.local/libexec/hermes-stack-signal-update
+
+# Gesamtprüfung
+~/.local/libexec/hermes-stack-doctor
+```
+
+## Migration
+
+Deployment-Code und Benutzerdaten werden bewusst getrennt behandelt. Siehe
+[`docs/MIGRATION.md`](docs/MIGRATION.md) für die Übernahme von Hermes-Daten,
+Signal-Sitzung und Modellgewichten.
+
+## Gitea
+
+Nach dem Entpacken oder Erzeugen des Repositories:
+
+```bash
+git init
+git add .
+git commit -m "Initial Hermes Arch deployment"
+git branch -M main
+git remote add origin ssh://git@GITEA/OWNER/hermes-arch-stack.git
+git push -u origin main
+```
+
+Die mitgelieferte Gitea-Actions-Workflowdatei führt Syntax- und Smoke-Tests aus.
+`make test` führt zusätzlich isolierte Funktionstests mit simulierten Programmen
+aus. Ein echter NVIDIA-/Arch-/Signal-/Hermes-End-to-End-Test bleibt auf der
+Zielmaschine erforderlich. `make archive` verwendet den letzten Commit (also
+zuerst eigene Änderungen prüfen und committen).
+
+## Grenzen der Reproduktion
+
+Das Repo reproduziert die Deployment-Logik, nicht deine privaten Daten oder ein
+eingefrorenes Arch-Abbild. Für denselben Modell-/Backendstand Quell-SHA sowie
+Modell-/Projektor-Prüfsummen notieren. Der offizielle Hermes-Installer und Arch
+liefern beim Neuaufsetzen sonst den dann verfügbaren Stand. Technische Quellen
+stehen in `docs/LLAMA_INSTALL.md` und `docs/RTX3080.md`.