Phase 1: Cluster-Fundament – Nachrichten, Registry, Paarung, Discovery

- hms_cluster: ClusterMessage (§6.5: Pflichtfelder, Sequenzen, Revisionen,
  execute_at, Trace-ID), CommandTracker (idempotent, vorwärts-only:
  accepted->armed->executed/failed)
- NodeRegistry: online/degraded/stale/offline über Schwellen, UI-Kategorien
  discovered/paired/unknown/incompatible/offline, Doppel-Node-ID blockiert,
  IP-Wechsel erhaelt node_id (§6.3, §6.5)
- Pairing: PIN (TTL 120s, Versuchslimit), Fingerprint (SHA-256 gruppiert),
  Token nur als Hash, Scopes read/control/content_sync/admin, Ablauf +
  sofortiger Widerruf (§6.3, §27.1, ADR-0010)
- Discovery-Modell: _hmsmedia._tcp.local. TXT ohne Secrets, Capability-
  Digest, persistente manuelle Fallback-Liste (ADR-0009)
- ADR-0009 (mDNS + Fallback) und ADR-0010 (Paarung) dokumentiert
- 25 Unit-Tests; Gesamtsuite 183 Tests gruen, Ruff gruen

docs/adr/0009-discovery-mdns-fallback.md

@@ -0,0 +1,50 @@
+# ADR-0009: Node-Discovery – mDNS/DNS-SD mit manueller Fallback-Liste
+
+- **Status:** Angenommen
+- **Datum:** 2026-09-11
+- **Phase:** 1
+- **Bauplan:** §6.3, §27.1, §32 (ADR-Pflicht: Node-Discovery und manueller Subnetz-Fallback)
+
+## Entscheidung
+
+1. Discovery-Protokoll: mDNS/DNS-SD, Service-Typ `_hmsmedia._tcp.local.`
+   (§6.3).
+2. TXT-Record enthält ausschließlich kleine, nicht vertrauliche Daten:
+   `proto` (Protokollversion), `node` (Node-ID), `roles` (Rollen, kommasepariert),
+   `port` (API-Port), `caps` (Capability-Digest, kurzer Hash).
+   Keine Tokens, keine Secrets (§27.1).
+3. mDNS ist **keine Vertrauensentscheidung**: gefundene Nodes sind zunächst
+   `discovered`, steuerbar erst nach Paarung (ADR-0010).
+4. Für Umgebungen ohne Multicast (VLAN, geroutete Netze, blockiertes mDNS)
+   existiert eine **persistente manuelle Node-Liste** (Host/IP + Port) als
+   gleichwertiger Fallback (§6.3).
+5. Bibliothek: `zeroconf` (Standard-Python-mDNS) für den Betrieb auf
+   Zielsystemen. Kein Eigenbau des Multicast-Stacks; Alternativen (python-avahi,
+   Eigenbau) verworfen: plattformneutral unzureichend bzw. unnötiges Risiko
+   (§33). Im Entwicklungscontainer werden nur Modell und Registry getestet
+   (kein Multicast nötig); der Echtnetz-Test gehört zu Gate 1 (§29.2).
+
+## Alternativen
+
+- Avahi via D-Bus: Linux-only, ungeeignet für Windows-first.
+- Eigener Multicast-Code: hoher Aufwand, kein messbarer Nutzen.
+- Nur manuelle Liste: widerspricht §6.3 (Discovery ist Fundament).
+
+## Folgen
+
+- `hms_cluster.discovery` definiert ServiceInfo (Instanzname, TXT-Kodierung)
+   und Registry-Kategorien: `discovered`, `paired`, `unknown`, `incompatible`,
+   `offline` (§6.3: UI führt Gruppen getrennt auf).
+- Doppelte Node-IDs werden als Fehler blockiert, nicht still gemischt (§6.3).
+- Inkompatible Protokollversionen erscheinen als `incompatible`.
+
+## Messwerte / Nachweise
+
+- Unit-Tests: TXT-Roundtrip, Registry-Kategorien, Doppel-Node-ID-Blockade,
+  manuelle Liste, Protokoll-Inkompatibilität.
+- Multicast-Echtnetz-Test mit zwei Nodes: Teil von Gate 1 (§29.2), auf
+  echter Hardware bzw. im LAN-Test nachzuholen.
+
+## Freigabe
+
+- Standardumsetzung gemäß §6.3; zeroconf-Addition als ADR dokumentiert (§33).

docs/adr/0010-pairing-pin-token-scopes.md

@@ -0,0 +1,45 @@
+# ADR-0010: Node-Paarung – PIN/Fingerprint, Token-Scopes, Widerruf
+
+- **Status:** Angenommen
+- **Datum:** 2026-09-11
+- **Phase:** 1
+- **Bauplan:** §6.3, §27.1, §32 (ADR-Pflicht: Node-Paarung, TLS, Berechtigungsscopes)
+
+## Entscheidung
+
+1. Paarung: kurzlebige PIN + sichtbarer Identitäts-Fingerprint. Ein Node wird
+   erst nach erfolgreicher PIN-Prüfung steuerbar (§6.3).
+2. Nach Paarung erhält der Partner ein wiederrufbares Token mit getrennten
+   Scopes: `read`, `control`, `content_sync`, `admin` (§27.1).
+3. Tokens werden als Hash gespeichert, nie im Klartext; Widerruf = Deletion,
+   sofort wirksam.
+4. Ungepaarte Nodes geben ausschließlich minimale Discovery-/Pairing-
+   Informationen heraus (§27.1).
+
+## Umsetzung Phase 1
+
+- `hms_cluster.pairing`: PIN-Erzeugung (6-stellig, kryptographisch),
+  Fingerprint (SHA-256 über Identitäts-Public-Daten, hex-gruppiert sichtbar),
+  Paarungs-State, Token-Hash mit Scopes + Ablauf, Versuchslimit.
+- TLS-Transport und Zertifikatsaustausch folgen mit dem Cluster-WebSocket
+  (Phase 2); dieses ADR legt die Datenmodell-Basis.
+
+## Alternativen
+
+- Nur Zertifikate ohne PIN: anfällig für falsche Geräte in Setup-Situationen;
+  sichtbare PIN ist bewusst einfach (§6.3).
+- Statische API-Keys: keine Scopes, kein gezielter Widerruf.
+
+## Folgen
+
+- Gate-1-Test „sicher gepaart“: PIN-Prüfung + Token-Ausstellung + Widerruf
+  getestet; TLS-Handshake folgt in Phase 2 und bleibt in STATUS.md offen.
+
+## Messwerte / Nachweise
+
+- Unit-Tests: PIN-Format/-TTL, Fingerprint-Stabilität, Scope-Zuordnung,
+  Ablauf, Widerruf, Hash-only-Speicherung, Versuchslimit.
+
+## Freigabe
+
+- Standardumsetzung gemäß §6.3/§27.1.

docs/adr/README.md

@@ -10,6 +10,8 @@ mit ADR und Freigabe (PLAN.md §1).
 - ADR-0003: IPC – lokales TCP + length-prefixed MessagePack v1
 - ADR-0008: Build-first-Strategie – verzögerte Hardware-Validierung
   (Auftraggeber-Freigabe 2026-09-11)
+- ADR-0009: Node-Discovery – mDNS/DNS-SD mit manueller Fallback-Liste
+- ADR-0010: Node-Paarung – PIN/Fingerprint, Token-Scopes, Widerruf
 
 ## Vorläufig angenommen (Bestätigung im Windows-Durchlauf, ADR-0008)
 
@@ -20,6 +22,7 @@ mit ADR und Freigabe (PLAN.md §1).
 
 - ADR-0006: Frontend – React vs. Svelte (Entscheidung zu Beginn Phase 5)
 - ADR-0007: Typprüfung – mypy vs. pyright
-- weitere gemäß Bauplan §32 (Persistenz, Preview, Show-Codec, Ownership,
-  Display-Abstraktion, Adaptive-Quality-Policy, Discovery, Clusterprotokoll,
-  Paarung/TLS, Clock-Sync, UI-Design-Tokens)
+- weitere gemäß Bauplan §32 (Persistenz → erledigt in Phase 1 ohne eigene
+  ADR-Nummer, da §24-Vorgaben 1:1 umgesetzt; Preview, Show-Codec, Ownership,
+  Display-Abstraktion, Adaptive-Quality-Policy, Clusterprotokoll-Transport,
+  TLS-Details, Clock-Sync, UI-Design-Tokens)