docs: Dokumentation umfassend überarbeitet

docs/README.md

@@ -8,18 +8,18 @@ AdGuard Shield ist ein Go-Daemon, der das Query Log von AdGuard Home auswertet,
 
 | Dokument | Wofür es gedacht ist |
 |---|---|
-| [Architektur & Funktionsweise](architektur.md) | Erklärt den Aufbau, den Datenfluss, Firewall, SQLite, Hintergrundjobs und Sperrlogik |
-| [Befehle & Nutzung](befehle.md) | Vollständige CLI-Referenz mit typischen Betriebsabläufen |
-| [Konfiguration](konfiguration.md) | Alle Parameter aus `adguard-shield.conf` mit Beispielen und Empfehlungen |
+| [Architektur & Funktionsweise](architektur.md) | Erklärt den Aufbau, den Datenfluss, Firewall-Modell, SQLite-Schema, Hintergrundjobs und Sperrlogik |
+| [Befehle & Nutzung](befehle.md) | Vollständige CLI-Referenz mit Beispielen und typischen Betriebsabläufen |
+| [Konfiguration](konfiguration.md) | Alle Parameter aus `adguard-shield.conf` mit Beispielen, Empfehlungen und Beispielkonfigurationen |
 | [Docker-Installationen](docker.md) | Firewall-Modi für klassische Installation, Docker Host Network und veröffentlichte Docker-Ports |
-| [Benachrichtigungen](benachrichtigungen.md) | Einrichtung von Ntfy, Discord, Slack, Gotify und Generic Webhooks |
-| [E-Mail Report](report.md) | Report-Inhalte, Mailversand, Cron-Job und manuelle Tests |
-| [Update-Anleitung](update.md) | Update der Go-Version und Migration von alten Shell-Installationen |
-| [Tipps & Troubleshooting](tipps-und-troubleshooting.md) | Diagnosewege für API, Firewall, GeoIP, Reports, Listen und falsch gesetzte Sperren |
+| [Benachrichtigungen](benachrichtigungen.md) | Einrichtung von Ntfy, Discord, Slack, Gotify und Generic Webhooks mit Beispielinhalten |
+| [E-Mail Report](report.md) | Report-Inhalte, Formate, Mailversand, Cron-Job und manuelle Tests |
+| [Update-Anleitung](update.md) | Update der Go-Version, Konfigurationsmigration und Migration von alten Shell-Installationen |
+| [Tipps & Troubleshooting](tipps-und-troubleshooting.md) | Diagnosewege für API, Firewall, GeoIP, Reports, externe Listen und falsch gesetzte Sperren |
 
-## Wichtigster Unterschied zur alten Shell-Version
+## Das Binary
 
-Die frühere Version bestand aus mehreren Shell-Skripten, Hilfs-Workern, Cron-Jobs und einem separaten Watchdog. Die Go-Version bündelt diese Aufgaben in einem einzelnen Binary:
+Die Go-Version bündelt alle Aufgaben in einem einzelnen Binary:
 
 ```text
 /opt/adguard-shield/adguard-shield
@@ -27,11 +27,11 @@ Die frühere Version bestand aus mehreren Shell-Skripten, Hilfs-Workern, Cron-Jo
 
 Dieses Binary ist gleichzeitig:
 
-- Daemon für den produktiven Betrieb
-- CLI für Status, History, Logs, Firewall, Listen, GeoIP und Reports
-- Installer, Updater und Uninstaller
-- Report-Generator
-- Hintergrundprozess für externe Whitelist, externe Blocklist, GeoIP und Offense-Cleanup
+- **Daemon** für den produktiven Betrieb (Querylog-Polling, Erkennung, Sperren)
+- **CLI** für Status, History, Logs, Firewall, Listen, GeoIP und Reports
+- **Installer**, **Updater** und **Uninstaller**
+- **Report-Generator** für HTML- und Text-Reports
+- **Hintergrundprozess** für externe Whitelist, externe Blocklist, GeoIP und Offense-Cleanup
 
 Die meisten Befehle beginnen daher mit:
 
@@ -48,12 +48,35 @@ sudo ./adguard-shield update
 
 ## Empfohlener Lesefluss
 
-Wenn du AdGuard Shield neu einrichtest:
+### Neueinrichtung
 
-1. Lies zuerst [Architektur & Funktionsweise](architektur.md), damit klar ist, was genau gesperrt wird.
+1. Lies zuerst [Architektur & Funktionsweise](architektur.md), damit klar ist, was genau gesperrt wird und wie der Datenfluss aussieht.
 2. Passe danach [Konfiguration](konfiguration.md) an, besonders API-Zugang, Whitelist und Rate-Limits.
 3. Nutze [Befehle & Nutzung](befehle.md) für Installation, Dry-Run und Service-Start.
 4. Richte optional [Benachrichtigungen](benachrichtigungen.md), [Reports](report.md), GeoIP oder externe Listen ein.
 5. Bei Problemen hilft [Tipps & Troubleshooting](tipps-und-troubleshooting.md).
 
-Wenn du von der alten Shell-Version kommst, beginne mit [Update-Anleitung](update.md).
+### Migration von der Shell-Version
+
+Wenn du von der alten Shell-Version kommst, beginne mit [Update-Anleitung](update.md). Dort findest du den empfohlenen Migrationsablauf und Hinweise zu den erkannten Legacy-Artefakten.
+
+### Docker-Setups
+
+Wenn AdGuard Home in Docker läuft, lies [Docker-Installationen](docker.md) zusätzlich zur Grundkonfiguration. Der Firewall-Modus bestimmt, in welcher Chain die Sperren greifen.
+
+## Wichtigster Unterschied zur alten Shell-Version
+
+Die frühere Version bestand aus mehreren Shell-Skripten, Hilfs-Workern, Cron-Jobs und einem separaten Watchdog:
+
+| Alte Shell-Version | Go-Version |
+|---|---|
+| `adguard-shield.sh` (Hauptskript) | Ein Binary für alles |
+| `iptables-helper.sh` | Integriert im Binary |
+| `external-blocklist-worker.sh` | Goroutine im Daemon |
+| `external-whitelist-worker.sh` | Goroutine im Daemon |
+| `geoip-worker.sh` | Goroutine im Daemon |
+| `offense-cleanup-worker.sh` | Goroutine im Daemon |
+| `report-generator.sh` | Integriert im Binary |
+| `unban-expired.sh` | Integriert im Daemon |
+| Watchdog-Service + Timer | `Restart=on-failure` in systemd |
+| Mehrere Cron-Jobs | Ein optionaler Cron-Job für Reports |