docs: expand README with full installation, configuration and troubleshooting guide

readme.md

@@ -1,35 +1,174 @@
 # dont-stop-folding
 
-Home Assistant Add-on für [Folding@home](https://foldingathome.org/) – nutze die Rechenleistung
+![dont-stop-folding](icon.png)
-deines Home Assistant Servers, um zur wissenschaftlichen Forschung beizutragen.
+
+> Home Assistant Add-on für [Folding@home](https://foldingathome.org/) – nutze die Rechenleistung
+> deines Home Assistant Servers, um zur wissenschaftlichen Forschung beizutragen.
+
+---
 
 ## Was ist Folding@home?
 
-Folding@home ist ein verteiltes Rechenprojekt der Washington University. Es simuliert
+[Folding@home](https://foldingathome.org/) ist ein verteiltes Rechenprojekt der Washington University in St. Louis.
-Proteinfaltungen, um Krankheiten wie Alzheimer, Krebs und Virusinfektionen besser zu verstehen.
+Es simuliert die Faltung von Proteinen – also den Prozess, durch den sich Eiweißmoleküle zu ihrer
-Jeder Haushalt mit einem laufenden Server kann einen Beitrag leisten.
+dreidimensionalen Funktionsform falten. Fehler in diesem Prozess stehen im Zusammenhang mit
+Krankheiten wie Alzheimer, Parkinson, Krebs und COVID-19.
 
-## Installation
+Jeder Computer, der am Projekt teilnimmt, berechnet kleine Simulationsaufgaben (sogenannte *Work Units*)
+und sendet die Ergebnisse an die Forschungsserver zurück. Mit diesem Add-on läuft der Folding@home
+Client direkt auf deinem Home Assistant Server – vollständig im Hintergrund, ohne separate Hardware.
 
-1. **Repository hinzufügen** in Home Assistant:
+---
-   **Einstellungen → Add-ons → Add-on Store → ⋮ → Repositories**
-   ```
-   https://gitea.bitfire.work/retr0/dont-stop-folding
-   ```
-2. **Add-on installieren** – suche nach „Folding@home" im Store
-3. **Konfigurieren und starten**
-
-Eine vollständige Anleitung inkl. aller Konfigurationsoptionen findest du in der
-[Dokumentation](DOCS.md).
 
 ## Features
 
-- Folding@home Client 8.x
+- **Folding@home Client 8.x** – aktuelle Version mit verbesserter Effizienz
-- Web-Interface auf Port 7396
+- **Web-Interface** auf Port 7396 – Fortschritt, Statistiken und Steuerung direkt im Browser
-- Unterstützung für klassische Konten (user + passkey) und FAH 8 Online-Konten (account_token)
+- **Zwei Kontosysteme** – klassisch (Benutzername + Passkey) oder FAH 8 Online-Konto (Account Token)
-- Leistungsstufen: light, medium, full
+- **Team-Support** – standardmäßig im Home Assistant Community Team (247478)
-- Unterstützte Architekturen: `amd64`, `aarch64`
+- **Persistenz** – Work-Unit-Daten und Konfiguration bleiben bei Updates erhalten
-- Konfigurationsdaten bleiben bei Updates erhalten
+- **Unterstützte Architekturen:** `amd64`, `aarch64`
+
+---
+
+## Installation
+
+1. Öffne Home Assistant und navigiere zu:
+   **Einstellungen → Add-ons → Add-on Store**
+
+2. Klicke oben rechts auf **⋮ → Repositories** und füge folgende URL hinzu:
+   ```
+   https://gitea.bitfire.work/retr0/dont-stop-folding
+   ```
+
+3. Schließe den Dialog – das Add-on **Folding@home** erscheint nun im Store.
+
+4. Klicke auf das Add-on und dann auf **Installieren**.
+
+5. Wechsle in den Tab **Konfiguration** und trage deine Daten ein (siehe unten).
+
+6. Klicke auf **Starten**.
+
+---
+
+## Konfiguration
+
+### Optionen
+
+| Option          | Typ    | Standard  | Beschreibung |
+|-----------------|--------|-----------|--------------|
+| `user`          | string | _(leer)_  | Dein Folding@home-Benutzername für die Statistikseite. |
+| `team`          | string | `247478`  | Team-ID. `247478` ist das offizielle Home Assistant Community Team. |
+| `passkey`       | string | _(leer)_  | Persönlicher Passkey von foldingathome.org. Aktiviert Bonus-Punkte (Quick Return Bonus). |
+| `account_token` | string | _(leer)_  | Token für das FAH 8 Online-Konto. Empfohlen für neue Nutzer. |
+| `machine_name`  | string | _(leer)_  | Anzeigename dieser Maschine im FAH-Konto-Dashboard. |
+
+### Beispielkonfigurationen
+
+**Klassisches Konto (user + passkey):**
+```yaml
+user: "mein_benutzername"
+team: "247478"
+passkey: "abc123..."
+```
+
+**FAH 8 Online-Konto:**
+```yaml
+account_token: "eyJ..."
+machine_name: "homeassistant"
+```
+
+**Anonym falten** (keine Einträge nötig – einfach leer lassen):
+```yaml
+team: "247478"
+```
+
+> **Hinweis:** `account_token` und `user`/`passkey` schließen sich gegenseitig aus.
+> Wenn `account_token` gesetzt ist, wird er bevorzugt. Ohne beides wird anonym gefaltet.
+
+---
+
+## Web-Interface
+
+Nach dem Start ist die Folding@home Web-UI erreichbar unter:
+
+```
+http://<homeassistant-ip>:7396
+```
+
+Über das Web-Interface kannst du:
+
+- Aktuelle Work Units und deren Fortschritt einsehen
+- Folding pausieren und fortsetzen
+- Die Leistungsstufe (light / medium / full) anpassen
+- CPU- und GPU-Slots konfigurieren
+- Statistiken und deinen Beitrag abrufen
+
+---
+
+## Kontosysteme im Vergleich
+
+Folding@home bietet zwei Möglichkeiten, Beiträge einem Konto zuzuordnen:
+
+### Klassisch – Benutzername + Passkey
+
+Das bewährte System. Erstelle einen Account auf [foldingathome.org](https://foldingathome.org/),
+trage deinen Benutzernamen unter `user` ein. Mit einem optionalen `passkey` werden
+Bonus-Punkte freigeschaltet (Quick Return Bonus), die vergeben werden, wenn Work Units
+pünktlich abgegeben werden.
+
+### FAH 8 Online-Konto – Account Token
+
+Das neue System ab Version 8. Nach der Registrierung auf
+[foldingathome.org](https://foldingathome.org/) generierst du einen Token im
+Web-Dashboard und trägst ihn unter `account_token` ein. Optional kannst du unter
+`machine_name` einen Namen vergeben, damit du mehrere Maschinen im Dashboard unterscheiden kannst.
+
+---
+
+## Unterstützte Architekturen
+
+| Architektur | Status |
+|-------------|--------|
+| `amd64`     | ✅ Unterstützt |
+| `aarch64`   | ✅ Unterstützt (z. B. Raspberry Pi 4/5 mit 64-Bit-OS) |
+| `armhf`     | ❌ Nicht unterstützt (FAH 8 Client nicht verfügbar) |
+| `armv7`     | ❌ Nicht unterstützt (FAH 8 Client nicht verfügbar) |
+
+---
+
+## Datenspeicherung
+
+Der FAH Client speichert Konfiguration und Work-Unit-Daten persistent im
+Home Assistant Konfigurationsverzeichnis. Die Daten bleiben bei Neustarts
+und Add-on-Updates vollständig erhalten.
+
+---
+
+## Problembehandlung
+
+### Add-on startet nicht
+- Prüfe den **Log-Tab** des Add-ons auf Fehlermeldungen.
+- Stelle sicher, dass Port `7396` nicht von einem anderen Dienst belegt ist.
+
+### Web-Interface nicht erreichbar
+- Warte 30–60 Sekunden nach dem Start – der FAH Client benötigt etwas Zeit zur Initialisierung.
+- Prüfe, ob das Add-on im Status **Läuft** angezeigt wird.
+
+### Kein Fortschritt / keine Work Units
+- Der FAH-Server weist Work Units zu. Bei hoher Auslastung der Forschungsserver
+  kann es zu Wartezeiten kommen – das ist normal.
+- Prüfe im Web-Interface, ob der Client verbunden ist.
+- Stelle sicher, dass `user` und `team` korrekt eingetragen sind.
+- Für FAH 8: Ohne gültigen `account_token` werden keine Work Units zugeteilt.
+  Anonymes Falten funktioniert in FAH 8 nur eingeschränkt.
+
+### Beiträge erscheinen nicht in der Statistik
+- Statistiken werden verzögert aktualisiert (bis zu mehrere Stunden).
+- Stelle sicher, dass `user` korrekt geschrieben ist (Groß-/Kleinschreibung zählt).
+- Mit einem `passkey` werden Punkte zuverlässiger zugeordnet.
+
+---
 
 ## Lizenz