CONTROL-001: add safe HA automation handoff

docs/OPERATIONS.md

@@ -0,0 +1,87 @@
+# Entwicklung, Release und Betrieb
+
+## Lokales Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+cp .env.example .env
+.venv/bin/uvicorn app.main:app --reload
+```
+
+`SILLYHOME_HA_URL` und `SILLYHOME_HA_TOKEN` nur lokal in `.env` setzen.
+
+## Qualitätsprüfung
+
+```bash
+.venv/bin/pytest -q
+.venv/bin/ruff check .
+.venv/bin/mypy app backend tests
+git diff --check
+```
+
+## Release
+
+1. Version in allen vier Stellen ändern:
+   `pyproject.toml`, `addon/config.yaml`, `app/main.py`, `CHANGELOG.md`.
+2. Qualitätsprüfung ausführen.
+3. Feature-Branch committen und pushen.
+4. Pull Request nach `main` erstellen und mergen.
+5. Annotiertes Tag auf dem Merge-Commit erstellen.
+6. Gitea-Release aus demselben Tag erstellen.
+
+Beispiel:
+
+```bash
+git tag -a v0.7.0 -m 'SillyHome Next 0.7.0'
+git push origin v0.7.0
+```
+
+## Home-Assistant-Update
+
+Vorher Teil-Backup des Add-ons erstellen. Danach:
+
+```bash
+ha store reload
+ha apps info 58adbe1e_sillyhome_next
+ha apps update 58adbe1e_sillyhome_next
+ha apps info 58adbe1e_sillyhome_next
+ha apps logs 58adbe1e_sillyhome_next
+```
+
+Kein Home-Assistant-Neustart ist erforderlich.
+
+## Live-Verifikation
+
+Pflicht:
+
+```bash
+wget -qO- http://58adbe1e-sillyhome-next:8000/health
+wget -qO- http://58adbe1e-sillyhome-next:8000/v1/actuators
+```
+
+Für einen Aktor prüfen:
+
+- `behavior.mode`
+- `behavior.activation_ready`
+- `behavior.activation_reason`
+- `behavior.related_automations`
+- `behavior.paused_automation_entity_ids`
+- `behavior.prediction.execution_reason`
+
+Bei einer Übernahme testen:
+
+1. Passende HA-Automation ist vorher `on`.
+2. SillyHome übernimmt.
+3. SillyHome ist `active`.
+4. Passende HA-Automation ist `off`.
+5. Trigger erzeugt erwartete Aktoraktion.
+6. Gegenaktion wird trotz Cooldown ausgeführt.
+7. SillyHome stoppen und Automationen fortsetzen.
+8. SillyHome ist `shadow`, HA-Automation wieder `on`.
+
+## Rollback
+
+Bevorzugt das vor dem Update erstellte HA-Teil-Backup wiederherstellen.
+Alternativ vorherige Git-Version in `addon/config.yaml` veröffentlichen und das
+Add-on erneut aktualisieren.