Trim documentation to active runbooks

docs/AI_CONTEXT.md

@@ -1,213 +1,54 @@
 # AI Context
 
-Stand: 2026-05-04
+Stand: 2026-05-31
 
-Diese Datei ist fuer KI-Agenten gedacht, die das Homelab-Repo schnell verstehen muessen. Sie ersetzt nicht die Detaildokumente, sondern fasst Zielbild, Betriebsmodell und Risiken zusammen.
+Kurzer Kontext fuer KI-Agenten. Nicht als Ersatz fuer die echten Runbooks lesen.
 
-## Kurzfassung
+## Systembild
 
-Dieses Repository beschreibt ein Unraid-basiertes Homelab namens `Kallilabcore`. Der Betrieb folgt GitOps: Gitea `origin/master` ist die Quelle der Wahrheit, der lokale Clone ist Arbeitskopie, Komodo deployed aus Gitea, Docker Runtime und Host sind Ergebnis, nicht Bearbeitungsort.
+- Host: Unraid `Kallilabcore`
+- Betriebsmodell: GitOps mit Gitea `origin/master` als Sollzustand
+- Deploy: Komodo zieht aus Gitea und startet Compose-Stacks
+- Ingress: Traefik; WAN-seitig bewusst nur `443/tcp`
+- Secrets: nie im Repo, meist unter `/mnt/user/appdata/secrets/`
+- Backup: Borg plus host-seitige Dumps; Hetzner ist Offsite, H:/ ist lokale Nearline-Kopie
 
-Traefik ist der zentrale Web-Einstieg fuer HTTP(S). Admin-/Ops-UIs liegen entweder hinter Authelia/secure headers oder sind als Ausnahme dokumentiert. Secrets liegen ausserhalb des Repos auf dem Host, meistens unter `/mnt/user/appdata/secrets/`.
+## Vor jeder Aenderung lesen
 
-## Zielbild des Homelabs
+1. `HOMELAB_ARCHITECTURE_MASTER_V2.md`
+2. `docs/WORKFLOW.md`
+3. betroffene Compose-Datei
+4. bei Service-Fragen `docs/SERVICE_CATALOG.md`
+5. bei Restore/DR `docs/DISASTER_RECOVERY.md` und `docs/RESTORE_MATRIX.md`
 
-- stabile Compose-first Infrastruktur
-- keine produktiven Dockerman-/Ad-hoc-Container als Dauerzustand
-- Traefik als einziger oeffentlicher Web-Eingang
-- GitOps ueber Gitea + Komodo
-- klare Trennung von Web-Netz, Backend-Netz und app-internen Netzen
-- saubere Backup-/Restore-Faehigkeit ueber Borg, Dumps und dokumentierte Pfade
-- keine stillen Host-Hotfixes ohne Repo-/Doku-Abgleich
-
-## Architekturblocke
-
-### Ingress / Netzwerk
-
-- `traefik` nimmt 80/443 entgegen.
-- Docker-Labels definieren Service-Routing.
-- `traefik/dynamic/*` bleibt nur fuer Middlewares, TLS und Dashboards.
-- Neue Service-Routen gehoeren nicht in den File-Provider.
-
-### DNS / Remote
-
-- AdGuard Home beantwortet LAN-DNS und nutzt Unbound als Upstream.
-- Tailscale stellt Remote-Zugang bereit und nutzt `network_mode: host`.
-
-### GitOps
-
-- Gitea hostet das Repo unter `git.kaleschke.info`.
-- Komodo ist Stack-Manager und Deploy-Consumer.
-- Komodo Periphery braucht Docker-Socket und `/mnt/user/services` Mount, um Stacks reproduzierbar zu deployen.
-- Neue produktive Komodo-Stacks aus `Micha/homelab-infra` muessen einen aktiven Gitea->Komodo-Webhook auf die aktuelle Stack-ID haben; Ausnahmen wie deaktivierte/pausierte Stacks muessen dokumentiert werden.
-- Der `komodo`-Self-Stack ist eine dokumentierte Ausnahme ohne aktiven Gitea-Webhook; Bootstrap/Recovery laeuft ueber `docs/SERVICES_RECOVERY.md`.
-
-### Identity / Security
-
-- Authelia stellt ForwardAuth fuer viele Admin-UIs bereit.
-- Authelia nutzt GMX SMTP fuer Identity-/2FA-Benachrichtigungen; Passwort liegt als Host-Secret `authelia_smtp_password.txt`.
-- Vaultwarden ist ein separater Passwort-Tresor.
-- Komodo ist bewusst nicht pauschal hinter Authelia, weil UI, API, Webhooks und Periphery-WebSocket sonst leicht gebrochen werden koennen.
-- Komodo-Compose, Komodo-Secrets und Komodo-Runtime nur gemeinsam mit dem Betreiber aendern; `KOMODO_WEBHOOK_SECRET` ist bewusst getrennt von `KOMODO_SECRET_KEY`. Gitea-Webhooks nicht pauschal vereinheitlichen: einzelne Komodo-Stacks koennen eigene per-Stack-Webhook-Secrets haben.
-
-### Apps
-
-Wichtige Apps sind Paperless, Immich, Mealie, Mail Archiver, Nextcloud, ntfy, Vaultwarden und Gitea. Admin-/Ops-Tools sind u. a. Glance, Komodo, Borg UI, Filebrowser, code-server, Glances, Scrutiny, Speedtest, Monitoring Grafana und Hermes Agent.
-
-### Hermes Agent — Architektur und Ops-Monitor
-
-Hermes laeuft nach Model C (siehe `ops/hermes-agent/README.md`):
-
-- `hermes-gateway` als Docker-Container auf dem Unraid-Host, intern auf `hermes_net:8642`
-- Terminal-Befehle werden via SSH auf eine dedizierte Linux-VM ausgefuehrt
-- VM-IP: `192.168.178.143`, SSH-User: `hermes`
-- Repo-Clone auf der VM: `/srv/hermes-workspace/homelab-infra/`
-
-**Fuer KI-Agenten wichtig:** Das Hermes-Terminal laeuft auf der VM, nicht auf dem Unraid-Host.
-`/mnt/user/...`-Pfade sind von der VM aus nicht direkt erreichbar.
-Docker-CLI ist auf der VM nicht installiert — fuer Homelab-Checks wird `check_health.py` verwendet.
-
-**Ops-Monitor (homelab-ops-monitor):**
-
-- Skill: `ops/hermes-agent/skills/homelab-ops-monitor.md`
-- Script: `ops/hermes-agent/scripts/check_health.py` — prueft Services via HTTP, keine externen Deps
-- Wissensbasis: `ops/hermes-agent/services.json` — maschinenlesbare Ableitung aus `docs/SERVICE_CATALOG.md`
-- Check-Strategie: HTTP GET fuer URL-basierte Services, interne Services (DBs, Redis) als `"internal"` markiert
-- ntfy-Topic fuer Alerts: `homelab-alerts` auf `https://ntfy.kaleschke.info`
-
-Nach Aenderungen an `services.json` oder `check_health.py`: `git pull` auf der VM ausfuehren.
-- Mail Archiver ist ein Hybrid-Dienst mit `frontend_net` fuer IMAP/Traefik und `backend_net` fuer PostgreSQL; die Web-UI liegt hinter Authelia und behaelt zusaetzlich App-eigene Auth.
-
-### Monitoring / Metriken
-
-- Zielzustand ist ein zentraler Stack `monitoring/` unter `https://monitoring.kaleschke.info`.
-- `monitoring-grafana` ist die zentrale UI fuer Prometheus, Loki und InfluxDB 3 Core.
-- `monitoring-prometheus` sammelt Infrastruktur-Metriken; `monitoring-loki` + `monitoring-promtail` sammeln Docker-Logs.
-- `monitoring-influxdb3-core` ist nicht public und nicht im `frontend_net`.
-- Home Assistant schreibt ueber LAN-only Port 8181 nach InfluxDB, gebunden ueber `INFLUXDB_BIND_IP`.
-- Ein `401 Unauthorized` von InfluxDB ohne Token ist beim Reachability-Test ein Erfolgssignal.
-- Die frueheren Altstaende `ops/loki` und `ops/grafana-influxdb` wurden aus dem aktiven Repo entfernt; fuer Monitoring immer `monitoring/` verwenden, Rollback nur ueber Git-Historie.
-- Uptime Kuma ist entfernt; HTTP-Verfuegbarkeit laeuft ueber Blackbox Exporter, Prometheus-Alerts und `Homelab / Availability` in Monitoring Grafana.
-
-## Deployment-Logik
-
-Normalfall:
-
-1. lokaler Clone synchronisieren
-2. betroffene Dokumente und Compose-Datei lesen
-3. minimal aendern
-4. lokal validieren
-5. committen und pushen
-6. Komodo-Webhook / Deploy beobachten
-7. Runtime testen
-8. Doku aktualisieren
-
-Wichtig: Komodo-Web-Editor ist nicht der Bearbeitungsort. Wenn Komodo und Git voneinander abweichen, zuerst Git und Komodo Workspace pruefen, nicht live herumprobieren.
-
-Beim Anlegen neuer produktiver Stacks ist der Gitea->Komodo-Webhook Pflicht. Nach dem Anlegen muss ein Test-Push oder Test-Delivery zeigen, dass Gitea die aktuelle Komodo-Stack-ID erreicht.
-
-## Netzwerkmodell
-
-| Netzwerk | Bedeutung |
-|---|---|
-| `frontend_net` | Web-/Proxy-Netz fuer Traefik-geroutete Dienste und Dienste mit Internetbedarf |
-| `backend_net` | internes Netz fuer shared PostgreSQL, Redis und Backends |
-| `dns_net` | AdGuard + Unbound |
-| app-interne Netze | Isolation von App + DB/Cache, z. B. Immich, Mealie, Nextcloud, Monitoring |
-| `host` | nur dokumentierte Sonderfaelle wie Tailscale/Plex |
-
-Regeln:
+## Harte Regeln
 
+- Keine Secrets zitieren oder ins Repo schreiben.
+- Keine produktiven Host-Hotfixes ohne Repo-Abgleich.
 - Datenbanken nie ins `frontend_net`.
-- Admin-UIs nur mit Traefik + Middleware oder dokumentierter Ausnahme.
-- Direkte Host-Ports sind Ausnahme, nicht Default.
-- Runtime-Netznamen koennen Compose-Projektpraefixe bekommen, z. B. `monitoring_monitoring_influx_lan`.
+- Direkte Host-Ports sind Ausnahme.
+- Traefik dynamic config und Authelia Host-Config sind manuelle Sync-Ausnahmen.
+- Bei Drift zuerst Git, Gitea, Komodo Workspace, Docker Runtime und Host getrennt pruefen.
+- Nach zwei fehlgeschlagenen Reparaturversuchen stoppen und `docs/GITOPS_DRIFT_RUNBOOK.md` nutzen.
 
-## Security-Modell
+## Bekannte Ausnahmen
 
-- Secrets nie ins Git.
-- Werte niemals zitieren, auch nicht aus `.env`, Stack ENV, Logs oder Screenshots.
-- Secret-Dateien bevorzugt unter `/mnt/user/appdata/secrets/`.
-- `_FILE`-Varianten bevorzugen, falls Image sie unterstuetzt.
-- Wenn `_FILE` nicht unterstuetzt wird, Komodo Stack Environment Variables verwenden.
-- Docker-Socket, `privileged: true`, Host-Netz und breite Mounts sind nur mit dokumentierter Begruendung akzeptabel.
-
-Bekannte Ausnahmen:
-
-- Traefik: 80/443
-- Gitea: SSH 222
-- AdGuard: DNS 53 direkt; Admin 8082 ist bewusst ohne Traefik/2FA, aber auf Tailscale-IP `100.80.98.33` begrenzt
-- Tailscale: Host-Netz, `NET_ADMIN`, `NET_RAW`, `/dev/net/tun`
+- Traefik: Host-Ports 80/443, WAN-Freigabe nur 443
+- Gitea: SSH auf Host-Port 222, keine WAN-Freigabe
+- AdGuard: DNS 53 direkt; Admin nur auf Tailscale-IP `100.80.98.33:8082`
+- Tailscale und Plex: Host-Netz
 - Scrutiny: privileged
-- Komodo: Docker-Socket, native Auth
-- InfluxDB: LAN-only 8181 fuer Home Assistant Writer
-- `monitoring-influxdb3-core`: `user: "0"` als dokumentierte Host-Appdata-Permissions-Ausnahme
-- Traefik dynamic config: manueller Host-Sync
+- Komodo/Periphery: Docker-Socket-Zugriff
+- InfluxDB 3 Core: `127.0.0.1:8181`, Root-User-Ausnahme dokumentiert
 
-## Backup- und Restore-Modell
+## Aktuelle Restpunkte
 
-Borg sichert kritische Appdaten, Secrets, Traefik-State und Dump-Artefakte. Datenbank-Restore soll bevorzugt ueber Dumps laufen, nicht ueber rohe Live-DB-Verzeichnisse.
+Authoritativ: `docs/AUDIT_2026-05-25_TODO.md`.
 
-Wichtige Pfade:
+Kurzfassung:
 
-- `/mnt/user/appdata`
-- `/mnt/user/appdata/secrets`
-- `/mnt/user/services`
-- `/mnt/user/documents`
-- `/mnt/user/photos`
-- `/mnt/user/backups/borg/dumps/latest`
-
-Dump-Skript:
-
-- `ops/borg-ui/scripts/pre-backup-dumps.sh`
-- soll auf dem Unraid Host laufen
-- soll nicht als Borg-UI Inline-Hook behandelt werden, solange die Architektur nicht bewusst geaendert wird
-
-Disaster Recovery folgt einer Bootstrap-Reihenfolge:
-
-1. Traefik, AdGuard, Tailscale
-2. PostgreSQL, Authelia, Redis, Gitea
-3. Komodo
-4. kritische Apps
-5. restliche Apps/Ops inklusive Hermes Agent
-
-## Typische Arbeitsweise im Repo
-
-- Fuer Fragen zuerst `HOMELAB_ARCHITECTURE_MASTER_V2.md` lesen.
-- Fuer operative Aenderungen `docs/WORKFLOW.md` lesen.
-- Fuer Service-Details `docs/SERVICE_CATALOG.md` und die Compose-Datei lesen.
-- Fuer Drift `docs/GITOPS_DRIFT_RUNBOOK.md` nutzen.
-- Fuer Rollback `docs/ROLLBACK.md` nutzen.
-- Fuer Restore `docs/DISASTER_RECOVERY.md` und `docs/RESTORE_MATRIX.md` nutzen.
-
-KI-Agenten sollen konservativ arbeiten: keine indirekten Live-Aenderungen, keine Deployments, keine Commits, keine Host-Schreibbefehle, wenn der Benutzer nur Analyse oder Doku verlangt.
-
-## Bekannte Risiken und Altlasten
-
-- Traefik dynamic config muss manuell auf den Host synchronisiert werden; Komodo deployed diese Dateien nicht automatisch.
-- `backend_net` und app-interne Netze muessen bei Runtime-Problemen live geprueft werden, weil Compose-Projektpraefixe Netznamen veraendern koennen.
-- Authelia `configuration.yml` ist Repo-Baseline fuer nicht geheime Einstellungen, wird aber nicht automatisch von Komodo auf den Host kopiert; die produktive Host-Datei kann OIDC-/Secret-Konfiguration enthalten. Bei Auth-Aenderungen Repo-Baseline, Host-Config und Compose-Middlewares pruefen und nicht blind ueberschreiben.
-- Authelia nutzt PostgreSQL, aber bewusst kein Redis-Session-Backend; Redis ist kein Authelia-Bootstrap-Blocker.
-- Authelia-Notifier ist SMTP; bei Auth-Aenderungen Host-Config backupen, `authelia validate-config` ausfuehren und erst danach neu starten.
-- `paperless-ngx` nutzt fuer DB/Redis bewusst Stack ENV statt `_FILE`.
-- `glance-docker-socket-proxy`, `glances` und `komodo-periphery` nutzen Docker-/Socket-Zugriff; Zugriff bewusst behandeln.
-- `borg-ui` und `filebrowser` haben breite Mounts; bei Hardening nicht ad hoc, sondern gezielt vorgehen.
-- `scrutiny` ist privilegiert und hat Device-Mounts.
-- `Plex-Media-Server` ist im Architekturziel als Host-Sonderfall dokumentiert, aber nicht als Repo-Compose-Stack enthalten.
-- Echte `stack.env`- und `.env`-Dateien gehoeren nicht ins Repo; fuer Hermes liegt nur `ops/hermes-agent/stack.env.example` im Git.
-- Einige Images nutzen mutable Tag plus Digest. Das friert den aktuellen Digest ein, ist aber kein automatisches Upgrade-Modell.
-- Stateful Images werden bevorzugt als Minor-/Patch-Tag plus Digest gepinnt; Redis-Caches bleiben bewusst ungedigestet.
-
-## Arbeitsregel bei Unsicherheit
-
-Nicht raten. Erst diese Reihenfolge:
-
-1. Repo-Doku lesen
-2. Compose-Datei lesen
-3. Git-Stand pruefen
-4. Komodo Workspace pruefen
-5. Docker Runtime pruefen
-6. Host-Listener / echten Request pruefen
-7. genau eine abweichende Ebene benennen
-
-Wenn zwei Reparaturversuche scheitern: keine weiteren Schreibbefehle, Pflichtmatrix aus `docs/GITOPS_DRIFT_RUNBOOK.md` ausfuellen.
+- naechsten Borg-Lauf nach den Dumps vom 2026-05-31 21:42 bestaetigen
+- Alt-Volumes fruehestens ab 2026-06-02 freigeben
+- Hetzner-Account-Hygiene und Borg `append-only` pruefen
+- FRITZ!Box-Servicefenster fuer Update, Config-Backup und IPv6-Exposure planen
+- Auth-/OIDC-/CrowdSec-/Hermes-Themen bewusst geparkt