Initial commit

docs/LLAMA_INSTALL.md

@@ -0,0 +1,77 @@
+# llama.cpp samt Server, CLI und Benchmark installieren
+
+Der Installer baut die drei Programme `llama-server`, `llama-cli`, `llama-bench`
+aus dem offiziellen Repository mit CUDA. Er überschreibt weder `/usr/bin` noch
+einen vorhandenen Build und startet keinen Dienst. Kein AUR-Helper erforderlich.
+
+## Neue Arch-Maschine
+
+Zuerst einen zur GPU passenden NVIDIA-Treiber einrichten. `nvidia-smi` muss
+funktionieren. Treiberwahl und Kernelupdates werden nicht automatisiert.
+
+```bash
+sudo pacman -Syu --needed base-devel git cmake ninja cuda openssl
+```
+
+Dies ist eine vollständige Arch-Systemaktualisierung. Bei Kernel-/Treiberupdate
+Jobs beenden und neu starten, bevor du die GPU-Installation testest. Keine
+partielle Aktualisierung durch Ausschließen einzelner Systempakete erzwingen.
+
+Dann aus dem Deployment-Repo:
+
+```bash
+# master bewusst ausgewählt, keine als stabil behauptete Release-Version:
+./scripts/install-llama-cpp.sh --ref master --jobs 4 --cuda-arch 86
+```
+
+`86` ist für RTX 3080 gewählt. Für einen anderen Rechner dessen GPU-Architektur
+angeben. Mit `--ref <vollständiger-Commit>` lässt sich derselbe Quellstand erneut
+bauen. Tags/Branches werden aufgelöst und im jeweiligen `BUILD-INFO.txt` zusammen
+mit der SHA gespeichert. CUDA/Compiler/Arch-Pakete bleiben rollende Abhängigkeiten;
+das ist kein bitidentisch eingefrorenes Betriebssystem-Image.
+`--prefix /absoluter/pfad` erlaubt einen anderen Build-Speicherort. Dann den
+ausgegebenen Binary-Pfad ausdrücklich in `LLAMA_SERVER_BIN` konfigurieren.
+
+Falls CUDA den installierten Hostcompiler ablehnt: kompatiblen Compiler nach
+CUDA-/Arch-Dokumentation wählen und CMake z.B. über `CC`, `CXX`, `CUDAHOSTCXX`
+konfigurieren. Kein automatisches `--allow-unsupported-compiler` und keine
+Treiber-/Systemdateipatches. Ein fehlgeschlagener Build lässt aktive Versionen
+unverändert und bleibt zur Diagnose erhalten.
+
+Der Installer kopiert das Build-bin-Verzeichnis einschließlich dortiger
+Begleitdateien. Die Projektbibliotheken werden statisch gebaut; CUDA- und
+Systembibliotheken bleiben Laufzeitabhängigkeiten. Auf neuer Hardware neu bauen,
+nicht nur die Binary übertragen.
+
+## Auswahl
+
+- Erster verwalteter Build: Link `~/.local/opt/llama.cpp/current` wird angelegt.
+- Spätere Builds: der Link bleibt stehen, der neue Pfad wird ausgegeben.
+- Expliziter `LLAMA_SERVER_BIN` in `llama.env` hat Vorrang vor dem Link.
+- Ohne expliziten Pfad: verwalteter Link, sonst `llama-server` aus PATH.
+
+Auf der bisherigen Workstation **zunächst `/usr/bin/llama-server` beibehalten**.
+Einen Backend-Versionswechsel und VRAM-Tuning nicht im selben Vergleich vermischen.
+Für einen späteren Build dessen ausgegebenen Pfad in `LLAMA_SERVER_BIN` eintragen,
+prüfen und erst nach Jobende mit dem Restart-Helfer aktivieren. Den alten Pfad
+notieren; Rücknahme bedeutet Pfad zurücksetzen und erneut kontrolliert starten.
+
+```bash
+~/.local/libexec/hermes-stack-llama-run --check
+```
+
+Die Prüfung lädt kein Modell. Das erste echte Starten mit `LLAMA_HF_REPO`
+benötigt Netzwerk, genug Plattenplatz und ein vorhandenes HF-Repository. Bei
+Download-/Modellproblemen die vom Nutzer angegebene Modell-ID prüfen; sie wurde
+hier nicht heruntergeladen. Für offline und feste Modellversionen lokale
+GGUF-Dateien und ggf. passenden Vision-Projektor verwenden, SHA256 notieren.
+Modell und Projektor werden separat gesichert, nicht im Git-Repo abgelegt.
+
+## Offizielle Grundlagen
+
+- [llama.cpp bauen, CUDA und GPU-Architekturen](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md)
+- [Arch CUDA-Paket](https://archlinux.org/packages/extra/x86_64/cuda/)
+- [NVIDIA Compute Capability](https://developer.nvidia.com/cuda-gpus)
+
+Ein echter CUDA-Build und Modellbetrieb müssen auf der Zielmaschine geprüft
+werden. Die mitgelieferten Tests benutzen keine GPU und laden keine Gewichte.

docs/MIGRATION.md

@@ -0,0 +1,83 @@
+# Migration auf eine neue Arch-Linux-Maschine
+
+Das Gitea-Repository reproduziert Programme, Units und Wartungslogik. Persönliche
+Hermes-Daten, Secrets, Signal-Geräteidentität und Modellgewichte werden separat
+übertragen.
+
+## 1. Deployment installieren
+
+```bash
+git clone ssh://git@GITEA/OWNER/hermes-arch-stack.git
+cd hermes-arch-stack
+./install.sh --install-packages --install-hermes
+```
+
+## 2. Hermes-Benutzerdaten übertragen
+
+Auf der alten Maschine Hermes und Gateway stoppen und ein verschlüsseltes
+Backup erstellen. Mindestens relevant sind:
+
+- `~/.hermes/config.yaml`
+- `~/.hermes/.env`
+- `~/.hermes/auth.json`, sofern vorhanden
+- Profile, Sessions, Memories, Skills und Cron-Daten unter `~/.hermes/`
+
+Der Upstream-Checkout `~/.hermes/hermes-agent/` muss nicht übertragen werden;
+er wird vom offiziellen Installer neu erzeugt. Ein unverschlüsseltes Archiv mit
+Secrets darf weder ins Repository noch auf einen ungeschützten Fileserver.
+
+Alternativ den jeweils aktuellen Hermes-Backup-/Import-Befehl verwenden und
+vorher dessen Hilfe prüfen:
+
+```bash
+hermes backup --help
+hermes import --help
+```
+
+## 3. Signal
+
+Entweder signal-cli auf dem neuen Rechner als neues verknüpftes Gerät anmelden
+oder das vollständige signal-cli-Datenverzeichnis verschlüsselt übertragen:
+
+```text
+~/.local/share/signal-cli/
+```
+
+Dieses Verzeichnis enthält Zugangsdaten und ist wie ein Passwort zu behandeln.
+Es darf niemals committed werden. Anschließend Account und Port in
+`~/.config/hermes-stack-maintenance/signal-cli.env` sowie in `~/.hermes/.env`
+abgleichen.
+Eine kopierte Signal-Geräteidentität nicht auf beiden Maschinen gleichzeitig
+betreiben. Für Parallelbetrieb die neue Maschine als separates Gerät verknüpfen.
+
+## 4. llama.cpp und Modell
+
+`llama-server` mit [LLAMA_INSTALL.md](LLAMA_INSTALL.md) installieren (CUDA-Build
+inklusive CLI und Benchmark) oder vorhandene Binary verwenden. Die GGUF-Datei
+und einen ggf. benötigten Vision-Projektor übertragen oder beim ersten Start
+über HF beziehen. Danach
+`~/.config/hermes-stack-maintenance/llama.env` anpassen. Modellgewichte gehören
+wegen Größe und Lizenz nicht in dieses Repository.
+
+Die RTX-3080-Profile sind für 10 GB VRAM und die bisherige CPU ausgelegt; auf
+anderer Hardware neu messen. `LLAMA_SERVER_BIN`, Modellpfad, Port und Alias
+zwischen Hermes und llama.cpp abgleichen. Der neue Rechner braucht seine eigenen
+NVIDIA-/Kernelpakete. Keine Binärkopie des alten CUDA-Builds erzwingen.
+
+## 5. Aktivieren und prüfen
+
+```bash
+hermes gateway install --force
+systemctl --user daemon-reload
+systemctl --user enable --now signal-cli.service llama-qwen.service
+systemctl --user enable --now \
+  hermes-stack-hermes-update.timer \
+  hermes-stack-health.timer \
+  hermes-stack-signal-health.timer \
+  hermes-stack-signal-update-check.timer
+
+~/.local/libexec/hermes-stack-doctor
+```
+
+Erst wenn der Doctor erfolgreich ist, die alte Maschine bzw. deren Signal-Gerät
+außer Betrieb nehmen.

docs/RTX3080.md

@@ -0,0 +1,98 @@
+# Qwen auf RTX 3080 10 GB / Hyprland
+
+Zielhardware: RTX 3080 mit 10 GiB, i9-13900KF, 64 GB RAM. Der Desktop und
+llama.cpp nutzen dieselbe GPU. Das 27B-Modell in Q4_K_M passt nicht vollständig
+in 10 GiB: CPU/RAM-Offload bleibt erforderlich. Mehr VRAM für Gewichte kann
+helfen; weder Voll-Offload noch eine bestimmte Beschleunigung werden versprochen.
+
+## Profile
+
+| Profil | Kontextlimit | Fit-Zielmarge | Einsatz |
+| --- | ---: | ---: | --- |
+| `baseline` | 65536 | 1536 MiB | bisherige Startparameter, Referenz und Rückweg |
+| `balanced` | 49152 | 1536 MiB | erster Vergleich, nur Kontext reduzieren |
+| `vram-plus` | 49152 | 1280 MiB | zweiter Vergleich, kleinere Zielmarge |
+| `compact` | 32768 | 1536 MiB | Alternative für kürzere Sitzungen |
+
+Alle Profile: ein Slot, K/V-Cache q8_0, Flash Attention auto, GPU-Layer auto,
+Fit an, 6 Generierungs-/16 Batch-Threads, Jinja, Reasoning auto/512/preserve,
+Image-Minimum 1024 Tokens und Idle-Sleep nach 300 Sekunden. Modellalias bleibt
+`qwen38-27b-local`. Es werden keine Sampling-Werte oder Hermes-Memories geändert.
+
+Die Definitionen stehen zentral in `libexec/hermes-stack-llama-run`.
+Die Konfiguration und Optionsnamen werden anhand der installierten Binary
+geprüft. Nicht unterstützte Optionen führen zum Abbruch, nicht zum stillen
+Weglassen. Diese Prüfung kann GPU-Laufzeitfehler oder ungültige Optionswerte
+nicht ausschließen. Auf anderer Hardware die Profile nicht ungeprüft übernehmen.
+
+**Fit-Zielmarge ist keine geschützte VRAM-Reservierung.** Sie beeinflusst die
+Speicheranpassung beim Laden; später wachsende Browser-/Desktop-/Bildlast kann
+trotzdem zu Speicherdruck führen. Verfügbare Layer und Puffer hängen auch von
+Modellarchitektur, Kontext, Projektor und llama.cpp-Version ab. Weniger Kontext
+bedeutet nicht proportional weniger Gesamtspeicher. 1024 MiB und weniger sind
+hier bewusst nicht als fertiges Profil vorgesehen.
+
+## Messung statt Auslastungsziel
+
+1. Zuerst `baseline` mit deiner normalen Browser-/Hyprland-Nutzung messen.
+2. Jobs beenden. `balanced` wählen und kontrolliert neu starten.
+3. Dieselben Aufgaben erneut ausführen: kurze Textantwort, längerer Agent-Task
+   mit Tools und eine repräsentative Bildaufgabe. Qualität mitbewerten.
+4. Kalten Start nach Idle-Sleep getrennt von warmem Prompt-Cache messen.
+5. Erst bei genügend Spielraum `vram-plus` probieren. Bei Rucklern, OOM,
+   Grafikfehlern oder deutlich schlechterer Latenz zurück auf `baseline`.
+
+```bash
+~/.local/libexec/hermes-stack-llama-profile list
+~/.local/libexec/hermes-stack-llama-report
+
+# Nur speichern, unterbricht nichts:
+~/.local/libexec/hermes-stack-llama-profile balanced
+
+# Ausschließlich nach Abschluss aller Backend-Jobs:
+~/.local/libexec/hermes-stack-llama-restart --jobs-finished
+journalctl --user -u llama-qwen.service -f
+```
+
+Laufende Inferenz überlebt diesen **llama.cpp-Neustart nicht**. Ein Hermes-Update
+ist davon getrennt. Die neue Healthcheck-Version startet einen laufenden
+llama-server nicht allein wegen eines HTTP-Timeouts neu. Ein inaktiver Dienst
+wird nur mit `LLAMA_HEALTH_AUTORESTART=1` automatisch wieder gestartet.
+
+GPU während aller Vergleichsläufe beobachten, nicht nur nach Modellstart:
+
+```bash
+nvidia-smi --query-gpu=timestamp,memory.used,memory.free,utilization.gpu \
+  --format=csv --loop=1
+```
+
+Pro Profil notieren: freie VRAM-Minima, tatsächlich ausgelagerte GPU-Layer,
+Prompt-tok/s, Generierungs-tok/s, Zeit bis erster Antwort, Job-Gesamtdauer,
+Desktop-Verhalten und Ergebnisqualität. Nicht die höchste VRAM-Anzeige gewinnt,
+sondern die beste zuverlässig nutzbare Leistung.
+
+Bei kleinerem Kontext auch Hermes' Kontextbudget passend konfigurieren: erst
+die in deiner Hermes-Version verfügbaren Modell-/Konfigurationsoptionen ansehen.
+Der Alias bleibt gleich, daher erkennt Hermes eine geänderte Grenze nicht
+zwingend automatisch. Lange alte Sitzungen nicht ungeprüft fortsetzen; eine
+frische Sitzung für den Vergleich verwenden. Das Deployment überschreibt deine
+`config.yaml` bewusst nicht.
+
+## Rückkehr
+
+```bash
+~/.local/libexec/hermes-stack-llama-profile baseline
+~/.local/libexec/hermes-stack-llama-restart --jobs-finished
+```
+
+Eine Profiländerung stellt keine anderen Konfigurationen zurück. Für alte
+vollständige Startparameter siehe `WORKSTATION.md`. Browserbeschleunigung,
+NVIDIA-Treiber, Hyprland und Kernelparameter werden nicht verändert.
+
+## Quellen
+
+Offizielle [llama.cpp-Argumentdefinitionen](https://github.com/ggml-org/llama.cpp/blob/master/common/arg.cpp)
+für Fit-Marge, Kontext, Cache und Idle-Sleep; geprüft am 2026-09-05. Maßgeblich
+für deinen Rechner bleibt `llama-server --help` seiner tatsächlich installierten
+Version. Die Profile übernehmen die von dir gezeigten Modellparameter; sie
+sind noch kein auf deiner GPU gemessener Optimalwert.

docs/SECURITY.md

@@ -0,0 +1,12 @@
+# Sicherheit
+
+- Keine ausgefüllten `.env`-Dateien, Signal-Daten oder Modellzugangsdaten committen.
+- Lokale Konfigurationen werden mit Modus `0600` angelegt.
+- Signal- und Telegram-Ziele werden ausschließlich aus `~/.hermes/.env` gelesen.
+- Signal-Zugriff per `SIGNAL_ALLOWED_USERS` oder Hermes-DM-Pairing beschränken.
+- `GATEWAY_ALLOW_ALL_USERS` nicht für einen Agenten mit Terminalzugriff verwenden.
+- Das Update löscht beim Rollback nur einen geprüften Pfad innerhalb von `$HOME`,
+  dessen letzter Bestandteil `hermes-agent` ist.
+- Backups enthalten Secrets und müssen wie Zugangsdaten geschützt werden.
+- Gitea-Repository privat halten, auch wenn keine Secrets eingecheckt werden.
+- Vor produktivem Einsatz `git diff --cached` und Secret-Scanning ausführen.

docs/VALIDATION.md

@@ -0,0 +1,22 @@
+# Validierung vom 2026-09-05
+
+Ausgeführt in einer isolierten Arbeitsumgebung, nicht auf der Workstation:
+
+- `make test`: erfolgreich.
+- `bash -n`: Installer, Uninstaller, alle libexec-/Installationsskripte und
+  alle vier Beispielkonfigurationen erfolgreich.
+- Python-Vertragstests: **25 Tests erfolgreich**. Fake-Binaries ersetzen
+  CUDA-Build, Git-Netzwerk, systemd, HTTP und Signal-Zustellung.
+- `git diff --check`: erfolgreich.
+- Einfacher Secret-Mustercheck des Smoke-Skripts: kein Treffer. Kein Ersatz
+  für einen vollständigen Secret-Scanner oder die Prüfung vor einem Push.
+- ShellCheck war hier nicht installiert und wurde nicht ausgeführt; die
+  mitgelieferte Gitea-CI installiert und verwendet ihn.
+
+Nicht durchgeführt: Arch-Paketinstallation, echter CUDA-Build, Modell-Download,
+GPU-/Hyprland-Benchmark, Hermes-Installation, End-to-End-Update/Rollback oder
+echte Signal-/Telegram-Nachrichten. Die 25 Tests sind kein Nachweis dafür.
+
+Vor Produktivbetrieb: `WORKSTATION.md` bzw. `MIGRATION.md` abarbeiten, danach
+`RTX3080.md` für kontrollierte Vergleiche. Kein Dienst auf der Workstation wurde
+durch die Erstellung dieses Pakets verändert.

docs/WORKSTATION.md

@@ -0,0 +1,97 @@
+# Bestehende Workstation behutsam übernehmen
+
+Nicht blind den Schnellstart für eine neue Maschine ausführen. Vorhandene
+Hermes-/Signal-Konfiguration bleibt privat und wird nicht durch das Repo ersetzt.
+Das aktuelle Deployment enthält deine gezeigten Anpassungen; weitere lokale,
+hier nicht übermittelte Änderungen können nicht automatisch rekonstruiert werden.
+
+## 1. Ausgangszustand sichern
+
+Jobs zu Ende laufen lassen, sicherstellen dass gerade kein Hermes-Update läuft.
+Vorhandene Startparameter, Versionen, Units und Drop-ins lokal dokumentieren:
+
+```bash
+systemctl --user cat llama-qwen.service
+systemctl --user cat hermes-gateway.service
+/usr/bin/llama-server --version
+systemctl --user list-timers --all --no-pager
+```
+
+Bestehende Maintenance-Timer während der Umstellung anhalten; zuvor aktive
+Timer notieren und nur diese später wieder aktivieren. Laufende Service-Jobs
+werden durch Stoppen ihrer Timer nicht beendet.
+
+```bash
+systemctl --user stop hermes-stack-health.timer hermes-stack-hermes-update.timer \
+  hermes-stack-signal-health.timer hermes-stack-signal-update-check.timer
+```
+
+Das folgende `install.sh` sichert ersetzte Dateien unter
+`~/.local/state/hermes-stack-deployment.*`, behält vorhandene env-Dateien und
+Gateway-Unit bei und startet ohne Optionen keine Timer und keinen Backend-Dienst.
+Eigene systemd-Drop-ins bleiben bestehen; sie können den neuen ExecStart übersteuern!
+Vergleiche nachher `systemctl --user cat llama-qwen.service`.
+
+```bash
+./install.sh
+```
+
+Nicht `--install-hermes`, `--install-llama` oder `--install-packages` verwenden,
+wenn zunächst nur das bestehende funktionierende Setup übernommen werden soll.
+
+## 2. llama.env bewusst migrieren
+
+Der Installer überschreibt `llama.env` nicht. Vergleiche sie mit
+`config/llama.env.example`. Vor manueller Bearbeitung eine datierte Kopie anlegen:
+
+```bash
+cp -a ~/.config/hermes-stack-maintenance/llama.env \
+  ~/.config/hermes-stack-maintenance/llama.env.before-rtx-tuning
+```
+
+Den Backup-Namen nur einmal verwenden oder ein neues Datum anhängen. Folgende
+Werte aus der Vorlage übernehmen, vorhandene individuelle Modellpfade prüfen:
+
+```bash
+LLAMA_SERVER_BIN="/usr/bin/llama-server"
+LLAMA_MODEL=""
+LLAMA_HF_REPO="ggml-org/Qwen3.8-27B-GGUF:Q4_K_M"
+LLAMA_ALIAS="qwen38-27b-local"
+LLAMA_MMPROJ=""
+LLAMA_HOST="127.0.0.1"
+LLAMA_PORT="8080"
+LLAMA_PROFILE="baseline"
+LLAMA_ARGS=()
+```
+
+Eine alte Konfiguration mit `LLAMA_MODEL` und vollständigem `LLAMA_ARGS` läuft
+weiter, solange `LLAMA_PROFILE` nicht gesetzt ist. Der Profilschalter verweigert
+unmigrierte Konfigurationen. Lokale GGUF statt HF: Modellpfad setzen und HF leeren.
+
+```bash
+~/.local/libexec/hermes-stack-llama-run --print
+~/.local/libexec/hermes-stack-llama-run --check
+```
+
+Kein Modellstart, kein Neustart. Erst nach erfolgreicher Prüfung und Jobende:
+
+```bash
+~/.local/libexec/hermes-stack-llama-restart --jobs-finished
+curl -fsS http://127.0.0.1:8080/health
+~/.local/libexec/hermes-stack-llama-report
+```
+
+Ein kurzzeitiges 503 während des Ladens ist noch kein Beweis für einen Defekt.
+Logs kontrollieren und auf Bereitschaft warten. Danach eine echte Text-/Bild-
+und Tool-Aufgabe in Hermes prüfen. Erst dann vorher aktive Timer wieder starten.
+`LLAMA_HEALTH_AUTORESTART=0` ist auch bei älterer config.env ohne diesen Schlüssel
+der neue Standard: HTTP-Probleme werden gemeldet, nicht durch Neustarts behandelt.
+
+## 3. Optimieren und zurücksetzen
+
+Nun gemäß [RTX3080.md](RTX3080.md) jeweils nur ein Profil vergleichen. Zurück:
+Profil `baseline` wählen und kontrolliert neustarten. Für vollständige Rückkehr
+alte llama.env und ggf. alte Unit/Wrapper aus der Deployment-Sicherung einzeln
+wiederherstellen, `daemon-reload` und Neustart nach Jobende. Nicht pauschal ein
+Archiv über dein gesamtes Home extrahieren. Die Datei `llama-profile.env` hat nur
+bei aktivem Profilbetrieb Vorrang; ihre vorherigen Stände liegen daneben.