ACT-001: actuator-first sensor lifecycle

docs/ml_training.md

@@ -3,10 +3,19 @@
 SillyHome Next trainiert ein lokales statistisches Baseline-Modell pro Sensor
 und Merkmal. Es benötigt keine Cloud und keine externe ML-Laufzeit.
 
+Seit `v0.4.0` ist der bevorzugte Weg aktor-zentriert: ein bestätigter Aktuator
+wird mit einem numerischen Primärsensor verknüpft, die Historie dieses Sensors
+wird automatisch geladen und in ein deterministisches Artefakt überführt.
+
 ## 1. Daten sammeln
 
 Alle Trainingsvektoren werden über `FeatureStore.add(...)` oder `add_batch(...)` eingepflegt. Jeder Vektor enthält eine Sensor-ID sowie ein Dictionary mit Merkmalen.
 
+Im Normalbetrieb erzeugt die Reconciliation diese Vektoren selbst aus realer
+Home-Assistant-History. Das Trainingsmerkmal heißt dabei immer `value`.
+Binäre Kontextsensoren bleiben Kontext und werden nicht als numerische Samples
+missverstanden.
+
 ## 2. Statistisches Artefakt erzeugen
 
 ```python
@@ -61,6 +70,21 @@ zustandslose Funktion `retrain_model(registry, artifact_id, vectors)` aufrufen.
 Der Service startet bewusst keinen eigenen Hintergrundprozess. Über
 `POST /ml/retrain` kann derselbe Ablauf per API angestoßen werden.
 
+## 6. Autonomer Lebenszyklus
+
+Der `ActuatorReconciliationService` verwaltet pro konfiguriertem Aktuator:
+
+- die automatische Sensor- und Kontextzuordnung mit Score, Confidence und Evidenz
+- persistente manuelle Overrides
+- den Modellstatus (`trained`, `pending_history`, `review_required`, `archived`, ...)
+- ein Audit-Protokoll mit Gründen für Training, Retraining oder Archivierung
+
+Retraining erfolgt nur, wenn:
+
+- genügend nutzbare numerische Historie vorliegt
+- die aktuelle Zuordnung eindeutig oder manuell bestätigt ist
+- die Historie sich materiell verändert hat oder das Modell als stale gilt
+
 ## Hinweise
 - Für reproduzierbare Sensor-Reihenfolgen wird in `TrainingPipeline.run(...)` eine sortierte Sensor-Liste verwendet.
 - Fehlende Trainingsdaten lösen `ValueError` aus; nicht registrierte Artefakte lösen `KeyError` aus.