Prepare SillyHome Next 1.0.0 dashboard and API rework

docs/V1_0_0_OPERATING_GUIDE.md

@@ -0,0 +1,107 @@
+# SillyHome Next 1.0.0 Operating Guide
+
+Diese Version stabilisiert den produktiven Kern: schnelle Dashboard-Nutzung,
+lokales Caching, klare Aktor-/Sensor-Kategorien und nachvollziehbare Freigabe
+gelernter Aktionen.
+
+## Grundprinzip
+
+- Home Assistant bleibt die Quelle fuer aktuelle States und Services.
+- SillyHome cached schwere Entity-/Discovery-Metadaten lokal als JSON.
+- Die Startansicht liest nur lokale Store-/Cache-Daten.
+- Vollstaendige Discovery, Vorschlaege und Detailanalysen laden blockweise nach.
+- Es gibt keine externen Pings oder Cloud-Abfragen im Dashboard-Startpfad.
+
+## Wichtige Endpunkte
+
+- `GET /health`  
+  Lokaler API-Status ohne externe Abfrage.
+- `GET /health/websocket`  
+  Status des Home-Assistant-WebSocket-Listeners.
+- `GET /v1/actuators/dashboard`  
+  Schnelle Dashboard-Startdaten aus Store und JSON-Cache.
+- `GET /v1/actuators/summary`  
+  Schlanke Liste beobachteter Aktoren ohne Lernmuster-Payload.
+- `GET /v1/actuators/discovery`  
+  Aktor-Auswahl aus gecachten oder frisch geladenen HA-Entities.
+- `GET /v1/actuators/context-options?actuator_entity_id=...`  
+  Sensor-/Kontextvorschlaege fuer einen konkreten Aktor.
+- `POST /v1/actuators/{entity_id}/assignment`  
+  Manuelle Sensor-/Kontextzuordnung speichern.
+- `POST /v1/actuators/{entity_id}/activation`  
+  Freigabe oder Stop des automatischen Schaltens.
+
+## Cache
+
+Der Entity-Cache liegt neben dem Aktor-Store als `ha_entity_cache.json`.
+Er enthaelt HA-Entity-Metadaten wie Friendly Name, Bereich, Device und
+Kategoriegrundlagen.
+
+Der Cache wird geschrieben, wenn Discovery frische HA-Entities liest. Danach
+koennen Dashboard und Summary ohne erneute HA-Vollabfrage Namen, Raeume und
+Gruppen anzeigen.
+
+## Dashboard-Nutzung
+
+1. Startansicht oeffnen.
+2. `System & Cache` zeigt API, WebSocket, Cache-Groesse und geladene
+   Discovery-Gruppen.
+3. `Geraet zum Lernen auswaehlen` nutzt Suche, Typfilter und direkte
+   Entity-ID-Eingabe.
+4. `Beobachtete Geraete` zeigt gelernte Aktoren nach Raum oder Typ gruppiert.
+5. `Details` zeigt Lernfortschritt, Freigabe, Vorhersage, verwendete
+   Sensoren/Zustaende und Entscheidungsgruende.
+
+## Kategorien
+
+Aktoren:
+
+- Licht, LED, Lampen
+- Schalter, Steckdosen, Helper
+- Lueftung, Ventilatoren, Befeuchter/Entfeuchter
+- Heizungen/Klima
+- Rolllaeden/Cover
+- TV/Medien/Fernbedienungen
+- Szenen, Buttons, Schloesser, Ventile
+
+Sensoren und Kontext:
+
+- Luftfeuchtigkeit und Feuchte
+- Temperatur
+- Wetter
+- Helligkeit/Lux
+- Bewegung, Praesenz, Anwesenheit
+- Tuer/Fenster/Oeffnung
+- Licht-/Schalter-/Steckdosenstatus
+- Strom, Leistung, Energie, Einspeisung
+- PV, Akku, Wechselrichter
+- Helper und Szenen
+
+## Qualitaetspruefung
+
+Vor Release:
+
+```bash
+.venv/bin/pytest -q
+.venv/bin/ruff check .
+.venv/bin/mypy app backend tests
+git diff --check
+```
+
+Live nach Installation:
+
+```bash
+wget -qO- http://58adbe1e-sillyhome-next:8000/health
+wget -qO- http://58adbe1e-sillyhome-next:8000/health/websocket
+wget -qO /tmp/summary.json http://58adbe1e-sillyhome-next:8000/v1/actuators/summary
+wget -qO /tmp/dashboard.json http://58adbe1e-sillyhome-next:8000/v1/actuators/dashboard
+```
+
+## Rollback
+
+Der stabile Vor-1.0-Stand ist `v0.7.21`. Vor dem 1.0.0-Umbau wurde ein
+Git-Bundle-Backup erstellt:
+
+`/root/.openclaw/workspace/backups/sillyhome-next/`
+
+Bei Problemen kann auf `v0.7.21` zurueck installiert werden.