Dokumentiere ersten HTTP-Statuspfad fuer den Agenten

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

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

API-MQTT-VERTRAG.md

@@ -163,6 +163,17 @@ Beispiel-Endpunkte:
 - `POST /api/v1/player/status`
 - `POST /api/v1/player/snapshot`
 
+## Aktuelle Entwicklungsstufe
+
+Bevor das volle Player-Sync- und MQTT-Modell umgesetzt ist, existiert fuer die Entwicklung bereits ein bewusst kleiner HTTP-Statuspfad.
+
+Aktuell gilt:
+
+- `POST /api/v1/player/status` ist der erste reale Backend-Agent-Pfad
+- die Payload enthaelt zunaechst Health- und Laufzeitdaten aus dem Agenten
+- das Backend validiert den Request und bestaetigt ihn mit `status=accepted`
+- Persistenz, Authentifizierung und die spaetere Trennung zwischen HTTP-Status und MQTT-Heartbeat folgen in spaeteren Schritten
+
 ### 7. Admin-Kommandos
 
 Zweck:

DEVELOPMENT.md

@@ -184,15 +184,18 @@ go run ./cmd/agent
 
 1. Backend: einheitliches Fehlerformat und Routing-Grundstruktur anlegen
 2. Backend: Konfigurations- und App-Lifecycle stabilisieren
-3. Agent: MQTT-, API- und Sync-Bausteine auf Basis des Health-Modells vorbereiten
-4. Agent: spaeter Connectivity- und Fehlerzustaende auf das Health-Modell aufsetzen
-5. Danach die Netzwerk- und Kommandopfade schrittweise produktionsnah ausbauen
+3. Agent und Backend: den ersten HTTP-Statuspfad um persistierte Speicherung und Screen-Identitaet erweitern
+4. Agent: danach Connectivity- und Fehlerzustaende auf das Health-Modell aufsetzen
+5. Danach die Netzwerk-, Sync- und Kommandopfade schrittweise produktionsnah ausbauen
 
 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
 - dateibasierte Agent-Konfiguration zusaetzlich zu Env-Overrides
 - strukturierte Agent-Logs mit internem Health-Snapshot und signalgesteuertem Shutdown
+- erster periodischer HTTP-Status-Reporter im Agent
 - lokales Compose-Grundgeruest fuer PostgreSQL und Mosquitto
 
 ## Arbeitsweise

README.md

@@ -21,6 +21,7 @@ Die Trennung von `/srv/docker/infoboard-netboot` ist sinnvoll, damit:
 - Template-/Kampagnenkonzept: `docs/TEMPLATE-KONZEPT.md`
 - `layout_json` fuer `message_wall`: `docs/LAYOUT-JSON.md`
 - Player-Agent-Lifecycle und Health-Modell: `docs/PLAYER-AGENT-LIFECYCLE.md`
+- Erster HTTP-Statuspfad fuer den Player-Agent: `docs/PLAYER-STATUS-HTTP.md`
 - Provisionierungskonzept: `docs/PROVISIONIERUNGSKONZEPT.md`
 - Player-Konzept: `docs/PLAYER-KONZEPT.md`
 - Server-Konzept: `docs/SERVER-KONZEPT.md`
@@ -37,8 +38,8 @@ Die Trennung von `/srv/docker/infoboard-netboot` ist sinnvoll, damit:
 
 ## Aktueller Implementierungsstand
 
-- `server/backend/` enthaelt ein lauffaehiges Go-Grundgeruest mit erster Tool-API fuer `message_wall`
-- `player/agent/` enthaelt ein Go-Grundgeruest mit dateibasierter/env-basierter Konfiguration, strukturierten Logs und internem Health-Modell
+- `server/backend/` enthaelt ein lauffaehiges Go-Grundgeruest mit erster Tool-API fuer `message_wall` und einem ersten `player/status`-Endpunkt
+- `player/agent/` enthaelt ein Go-Grundgeruest mit dateibasierter/env-basierter Konfiguration, strukturierten Logs, internem Health-Modell und erstem HTTP-Status-Reporter
 - `compose/` enthaelt ein lokales Grundgeruest fuer PostgreSQL und Mosquitto
 - `ansible/` enthaelt erste Platzhalter fuer Inventory und Playbook-Struktur
 

docs/PLAYER-STATUS-HTTP.md

@@ -0,0 +1,79 @@
+# Info-Board Neu - Erster HTTP-Statuspfad fuer den Player-Agent
+
+## Ziel
+
+Dieses Dokument beschreibt den ersten bewusst kleinen Statuspfad zwischen `player/agent` und `server/backend`.
+
+Er ist fuer die aktuelle Entwicklungsstufe gedacht und noch kein finales Persistenz-, Authentifizierungs- oder MQTT-Modell.
+
+## 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
+- der Pfad dient als erste echte Backend-Agent-Integration vor Registration, Sync und MQTT
+
+## Endpoint
+
+- `POST /api/v1/player/status`
+
+## Request-Felder
+
+Mindestens enthalten:
+
+- `screen_id`
+- `ts`
+- `status`
+
+Aktuell zusaetzlich enthalten:
+
+- `server_url`
+- `mqtt_broker`
+- `heartbeat_every_seconds`
+- `started_at`
+- `last_heartbeat_at`
+
+## Beispiel
+
+```json
+{
+  "screen_id": "info01-dev",
+  "ts": "2026-03-22T16:00:00Z",
+  "status": "running",
+  "server_url": "http://127.0.0.1:8080",
+  "mqtt_broker": "tcp://127.0.0.1:1883",
+  "heartbeat_every_seconds": 30,
+  "started_at": "2026-03-22T15:59:30Z",
+  "last_heartbeat_at": "2026-03-22T16:00:00Z"
+}
+```
+
+## Antwort
+
+Bei gueltigem Request liefert das Backend aktuell:
+
+```json
+{
+  "status": "accepted"
+}
+```
+
+Bei ungueltigen Requests wird wie bei den anderen API-Endpunkten der gemeinsame Fehlerumschlag verwendet.
+
+## Abgrenzung
+
+Noch nicht Teil dieser Stufe:
+
+- dauerhafte Speicherung in Datenbank oder State-Store
+- Screen-Authentifizierung
+- MQTT-Heartbeat oder MQTT-Status
+- Admin-UI-Anzeige des letzten Status
+- Retry-Queue oder lokale Zwischenspeicherung im Agent
+
+## Folgeschritte
+
+Auf diesem Pfad bauen spaeter auf:
+
+- Screen-Identitaet und Authentifizierung
+- persistierter letzter Heartbeat und letzter Status auf dem Server
+- Trennung zwischen HTTP-Snapshot und MQTT-Heartbeat
+- Admin-Vorschau fuer Online-/Offline- und Degraded-Zustaende