Dokumentiere Agent-Lifecycle fuer v1

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

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

docs/PLAYER-AGENT-LIFECYCLE.md

@@ -0,0 +1,76 @@
+# Info-Board Neu - Player-Agent Lifecycle und Health-Modell
+
+## Ziel
+
+Dieses Dokument beschreibt die erste belastbare Laufzeitstufe des `player/agent` fuer v1.
+
+Es legt fest, wie der Agent seinen internen Zustand fuehrt, welche strukturierten Log-Ereignisse er ausgibt und wie ein kontrollierter Stop funktioniert.
+
+## V1-Entscheidung
+
+- der Agent fuehrt zunaechst ein internes Health-Modell ohne externen HTTP-Endpunkt
+- Lifecycle-Wechsel werden ueber einen in-memory Snapshot verfolgt
+- Logs werden als stabile `key=value`-Ereignisse ausgegeben
+- Stop erfolgt signalgesteuert ueber `SIGINT` oder `SIGTERM`
+
+## Health-Snapshot
+
+Der Laufzeitsnapshot enthaelt mindestens:
+
+- `status`
+- `screen_id`
+- `server_base_url`
+- `mqtt_broker`
+- `heartbeat_every_seconds`
+- `started_at`
+- `last_heartbeat_at`
+
+Der Snapshot dient in v1 der internen Laufzeitbeobachtung und Testsicherheit.
+
+## Statusmodell
+
+Fuer die aktuelle Ausbaustufe gelten diese Stati:
+
+- `starting` vor dem Start der Run-Loop
+- `running` sobald Konfiguration uebernommen und der erste Heartbeat verarbeitet wurde
+- `stopped` nach kontrolliertem Verlassen der Run-Loop
+
+Ein separater Fehlerstatus wird in dieser Stufe noch nicht eingefuehrt.
+Technische Startfehler bleiben weiterhin normale Rueckgabefehler beim Initialisieren oder Starten.
+
+## Strukturierte Log-Ereignisse
+
+Der Agent emittiert in v1 mindestens diese Ereignisse:
+
+- `event=agent_starting`
+- `event=agent_configured`
+- `event=heartbeat_tick`
+- `event=agent_stopped`
+
+Ziel ist keine vollstaendige Logging-Plattform, sondern ein stabiler, maschinenlesbarer Anfang fuer lokale Verifikation, spaetere Journald-Auswertung und Device-Debugging.
+
+## Heartbeat-Verhalten
+
+- beim Start wird direkt ein erster Heartbeat verarbeitet und geloggt
+- danach laeuft der Heartbeat im konfigurierten Intervall weiter
+- jeder Heartbeat aktualisiert `last_heartbeat_at`
+
+Das direkte erste Tick-Verhalten vereinfacht lokale Checks und Tests, weil ein frisch gestarteter Agent sofort einen nachvollziehbaren Lebensnachweis liefert.
+
+## Shutdown-Verhalten
+
+- `cmd/agent` erstellt einen signalgebundenen Context
+- bei `SIGINT` oder `SIGTERM` verlaesst die Run-Loop kontrolliert den Ticker
+- vor Rueckkehr wird `event=agent_stopped` geloggt und der Snapshot auf `stopped` gesetzt
+
+## V1-Abgrenzung
+
+Nicht Teil dieser Stufe:
+
+- externer Health-Endpunkt
+- MQTT-Verbindungsstatus
+- Backend-Reachability-Pruefung
+- Snapshot-Persistenz
+- Kommandos oder Sync-Status
+
+Diese Punkte folgen erst, wenn echte Netzwerk- und Sync-Funktionalitaet eingebaut wird.

player/agent/README.md

@@ -18,4 +18,6 @@ Geplante Unterstruktur:
 Aktuell vorhanden:
 
 - Env-basierte und dateibasierte Konfiguration
-- einfacher Laufzeit-Loop mit Heartbeat-Ticks im Log
+- strukturierte Start-/Heartbeat-/Stop-Logs
+- interner Health-Snapshot fuer Laufzeitzustand und Timestamps
+- signalgesteuerter Stop ueber `SIGINT` und `SIGTERM`