Dokumentiere Statusspeicherung und Connectivity-Zustaende

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

DEVELOPMENT.md

@@ -186,8 +186,8 @@ go run ./cmd/agent
 
 1. Backend: einheitliches Fehlerformat und Routing-Grundstruktur anlegen
 2. Backend: Konfigurations- und App-Lifecycle stabilisieren
-3. Agent und Backend: den ersten HTTP-Statuspfad um persistierte Speicherung und Screen-Identitaet erweitern
+3. Agent und Backend: den HTTP-Statuspfad als Grundlage fuer Identitaet, Persistenz und spaetere Admin-Vorschau erweitern
-4. Agent: danach Connectivity- und Fehlerzustaende auf das Health-Modell aufsetzen
+4. Agent: danach einen expliziten `offline`-Zustand und weitere Connectivity-Schwellenlogik aufsetzen
 5. Danach die Netzwerk-, Sync- und Kommandopfade schrittweise produktionsnah ausbauen
 
 Ergaenzt seit dem ersten Geruest:
@@ -195,9 +195,11 @@ Ergaenzt seit dem ersten Geruest:
 - `message_wall`-Resolver im Backend
 - Basisendpunkte und `message_wall`-Validierung im Backend testseitig breiter abgedeckt
 - erster `POST /api/v1/player/status`-Endpunkt im Backend
+- letzter bekannter Player-Status wird im Backend pro Screen in-memory vorgehalten und lesbar gemacht
 - dateibasierte Agent-Konfiguration zusaetzlich zu Env-Overrides
 - strukturierte Agent-Logs mit internem Health-Snapshot und signalgesteuertem Shutdown
 - erster periodischer HTTP-Status-Reporter im Agent
+- Server-Connectivity-Zustand im Agent (`unknown`, `online`, `degraded`) auf Basis der Report-Ergebnisse
 - lokales Compose-Grundgeruest fuer PostgreSQL und Mosquitto
 
 ## Arbeitsweise

docs/PLAYER-AGENT-LIFECYCLE.md

@@ -10,6 +10,7 @@ Es legt fest, wie der Agent seinen internen Zustand fuehrt, welche strukturierte
 
 - der Agent fuehrt zunaechst ein internes Health-Modell ohne externen HTTP-Endpunkt
 - Lifecycle-Wechsel werden ueber einen in-memory Snapshot verfolgt
+- Server-Erreichbarkeit wird getrennt vom Lifecycle als eigener Connectivity-Zustand gefuehrt
 - Logs werden als stabile `key=value`-Ereignisse ausgegeben
 - Stop erfolgt signalgesteuert ueber `SIGINT` oder `SIGTERM`
 
@@ -18,6 +19,7 @@ Es legt fest, wie der Agent seinen internen Zustand fuehrt, welche strukturierte
 Der Laufzeitsnapshot enthaelt mindestens:
 
 - `status`
+- `server_connectivity`
 - `screen_id`
 - `server_base_url`
 - `mqtt_broker`
@@ -38,6 +40,17 @@ Fuer die aktuelle Ausbaustufe gelten diese Stati:
 Ein separater Fehlerstatus wird in dieser Stufe noch nicht eingefuehrt.
 Technische Startfehler bleiben weiterhin normale Rueckgabefehler beim Initialisieren oder Starten.
 
+## Connectivity-Modell
+
+Getrennt vom Lifecycle fuehrt der Agent fuer die Server-Erreichbarkeit aktuell diese Zustaende:
+
+- `unknown` vor dem ersten erfolgreichen oder fehlgeschlagenen Status-Report
+- `online` nach einem erfolgreich bestaetigten HTTP-Status-Report
+- `degraded` nach einem fehlgeschlagenen HTTP-Status-Report
+
+Damit bleibt der Lifecycle sauber von Netz- und Gegenstellenproblemen getrennt.
+Ein Report-Fehler stoppt den Agenten nicht, sondern veraendert nur den Connectivity-Zustand.
+
 ## Strukturierte Log-Ereignisse
 
 Der Agent emittiert in v1 mindestens diese Ereignisse:
@@ -45,6 +58,8 @@ Der Agent emittiert in v1 mindestens diese Ereignisse:
 - `event=agent_starting`
 - `event=agent_configured`
 - `event=heartbeat_tick`
+- `event=status_report_sent`
+- `event=status_report_failed`
 - `event=agent_stopped`
 
 Ziel ist keine vollstaendige Logging-Plattform, sondern ein stabiler, maschinenlesbarer Anfang fuer lokale Verifikation, spaetere Journald-Auswertung und Device-Debugging.
@@ -69,8 +84,10 @@ Nicht Teil dieser Stufe:
 
 - externer Health-Endpunkt
 - MQTT-Verbindungsstatus
-- Backend-Reachability-Pruefung
 - Snapshot-Persistenz
 - Kommandos oder Sync-Status
 
+Die erste Backend-Reachability-Pruefung ist in dieser Stufe bereits ueber den HTTP-Status-Report abgebildet.
+Ein expliziter `offline`-Zustand, MQTT-Reachability und weitergehende Schwellenlogik folgen spaeter.
+
 Diese Punkte folgen erst, wenn echte Netzwerk- und Sync-Funktionalitaet eingebaut wird.

docs/PLAYER-STATUS-HTTP.md

@@ -9,7 +9,7 @@ Er ist fuer die aktuelle Entwicklungsstufe gedacht und noch kein finales Persist
 ## V1-Dev-Entscheidung
 
 - der Agent sendet zunaechst Statusdaten per HTTP an das Backend
-- das Backend validiert und bestaetigt den Request, speichert ihn in dieser Stufe aber noch nicht dauerhaft
+- das Backend validiert und bestaetigt den Request und haelt den letzten bekannten Status pro Screen in-memory vor
 - der Pfad dient als erste echte Backend-Agent-Integration vor Registration, Sync und MQTT
 
 ## Endpoint
@@ -59,6 +59,15 @@ Bei gueltigem Request liefert das Backend aktuell:
 
 Bei ungueltigen Requests wird wie bei den anderen API-Endpunkten der gemeinsame Fehlerumschlag verwendet.
 
+## Aktueller Read-Pfad
+
+Zusätzlich zur Write-Route gibt es in dieser Stufe:
+
+- `GET /api/v1/screens/{screenId}/status`
+
+Dieser Endpunkt liefert den zuletzt akzeptierten Status fuer einen Screen zurueck.
+Wenn fuer den Screen noch kein Status vorliegt, liefert das Backend `404` mit dem gemeinsamen Fehlerumschlag.
+
 ## Abgrenzung
 
 Noch nicht Teil dieser Stufe:
@@ -69,6 +78,8 @@ Noch nicht Teil dieser Stufe:
 - Admin-UI-Anzeige des letzten Status
 - Retry-Queue oder lokale Zwischenspeicherung im Agent
 
+Agent-seitig wird die Server-Erreichbarkeit aktuell lokal als `unknown`, `online` oder `degraded` aus dem Erfolg der HTTP-Reports abgeleitet.
+
 ## Folgeschritte
 
 Auf diesem Pfad bauen spaeter auf: