Neustart-Erkennung dokumentiert (AGENTS.md CZ)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

AGENTS.md

@@ -11902,3 +11902,73 @@ Wert sofort in `fahrzeugprofil.json`.
 Dasselbe Muster wie beim Koordinatenfehler in Abschnitt CS: **ein fehlgeschlagener
 synthetischer Test ist kein Fehlerbeweis.** Erst mit echten Ereignissen pruefen,
 dann urteilen.
+
+## CZ. Nicht jedes Update braucht einen Neustart (2026.9.5.24)
+
+Frage des Eigentuemers: *"warum brauchen unsere updates immer einen HA reboot?
+kannst du das nicht anders loesen?"* - Teils ja.
+
+### Zwei Faelle, nur einer ist unvermeidlich
+
+**Python-Code: Neustart noetig.** Home Assistant importiert die Module der
+Integration einmal in seinen laufenden Prozess; daran haengen dann Entitaeten,
+Zeittakte, Horcher, der Koordinator. Eine ausgetauschte `.py` auf der Platte
+aendert daran nichts. `importlib.reload()` ueber alle Module waere technisch
+moeglich, liesse aber alte Objekte referenziert und ergaebe eine Mischung aus
+altem und neuem Code. Auch HACS verlangt deshalb einen Neustart. Bleibt so.
+
+**Oberflaechendateien: Neustart war unnoetig.** `frontend/` wird direkt von der
+Platte ausgeliefert - `StaticPathConfig(STATIK_URL, ordner, False)`, also ohne
+lange Cache-Vorgabe. Eine ersetzte `.js` ist sofort wirksam, es braucht nur ein
+Neuladen im Browser. Gebunden war das nur an unseren eigenen Cache-Brecher
+`?v={version}`, und der kam aus `async_get_integration()` - das liest aus
+`hass.data[DATA_INTEGRATIONS]` und haelt das Manifest fuer die Laufzeit fest.
+
+### Die Unterscheidung ist bewusst schief
+
+`aktualisierung.neustart_noetig(alt, neu)` vergleicht beide Ordner ueber sha256
+je Datei (ohne `__pycache__`) und meldet **"kein Neustart" nur, wenn JEDE
+Abweichung** unter `frontend/` liegt oder die `manifest.json` ist. Alles
+andere - `.py`, `services.yaml`, `translations/`, `vorlage/` - gilt als
+neustartpflichtig, auch wo es das im Einzelfall nicht waere.
+
+Der Grund fuer die Schieflage: ein faelschlich ausgelassener Neustart laesst
+neuen Python-Code nie anlaufen, und der Fehler wird an ganz anderer Stelle
+gesucht. Ein ueberfluessiger Neustart kostet eine Minute.
+
+`manifest.json` ist ausgenommen, weil sich ihre Versionsnummer bei **jeder**
+Veroeffentlichung aendert - ohne die Ausnahme waere jedes Update ein
+Neustart-Update und die Unterscheidung wertlos. Weil HA das Manifest
+zwischenspeichert, liest `version_von_platte()` die Nummer direkt von der
+Platte, und `koordinator.version_neu_lesen()` zieht sie nach einem
+neustartfreien Update nach - sonst zeigten Panel und App weiter die alte
+Fassung, und niemand wuesste, ob das Update angekommen ist.
+
+Panel und App zeigen dann "Seite neu laden" statt "Installation abschliessen -
+Jetzt neu starten".
+
+### Bekannte Schwaeche: Zeilenenden
+
+Verglichen werden Datei-Inhalte. Steht die installierte Fassung mit CRLF auf
+der Platte (Windows-Checkout, install.ps1) und kommt die neue aus dem
+Gitea-Archiv mit LF, unterscheiden sich **alle** Dateien - auch die
+`.py`-Dateien, deren Inhalt sachlich gleich ist. Das erste Update nach dieser
+Aenderung meldet deshalb moeglicherweise "Neustart noetig", obwohl nur die
+Oberflaeche gewechselt hat. Ab dem zweiten Update stammen beide Seiten aus dem
+Archiv und der Vergleich stimmt. Bewusst nicht wegnormalisiert: die
+Fehlerrichtung ist die sichere.
+
+### Stand der Pruefung
+
+Neun neue Testfaelle in `tests/aktualisierung/test_aktualisierung.py` decken
+die Unterscheidung ab (nur frontend, nur manifest, geaenderte/neue/entfallene
+`.py`, services.yaml, `__pycache__`, unlesbarer Ordner) - 23 Tests der Suite
+gruen.
+
+**Der Durchlauf ueber den echten Gitea-Weg steht noch aus.** Er braucht eine
+angemeldete Sitzung, und die war nach einem Browser-Neustart weg; ich melde
+mich nicht selbst an. Vorbereitet ist er: Gitea steht auf **2026.9.5.24** mit
+einer reinen Kommentaraenderung in `audi-dashboard-app.js` plus Versionsnummer,
+die Testinstanz auf **2026.9.5.23**. Ein "Update installieren" dort muss
+"nur Oberflaechendateien, kein Neustart noetig" melden. Die Probeaenderung
+gehoert danach wieder heraus.