Add pilot handbook and document sn-fair v0

pilot.md: step-by-step for connecting two households (link-agnostic),
measurement protocol M0-M4 (link baseline, uplink baseline, pooled,
concurrent downloads, sn-fair Soll/Ist comparison), safety/legal
checklist, and a results section to be filled after the pilot.
Cross-linked from Home, documentation README, roadmap, architecture
and server README; roadmap marks sn-fair v0 done.

README.md

@@ -25,7 +25,7 @@ Datensammlung, keine Bezahlung.
 | Ordner/Datei | Inhalt | Einstieg |
 |---|---|---|
 | `documentation/` | Idee, Ethos, Architektur, Rechtslage, Roadmap (Deutsch, Obsidian-freundlich mit `[[Wikilinks]]`; `documentation/Home.md` ist die Map of Content) | [README](documentation/README.md) |
-| `server/` | Die Software (Rust): `sn-fetch`, `sn-node`, `sn-exit`; geplant `sn-fair`, `sn-cache`, `sn-freenet` | [README](server/README.md) |
+| `server/` | Die Software (Rust): `sn-fetch`, `sn-node`, `sn-exit`, `sn-fair`; geplant `sn-cache`, `sn-freenet` | [README](server/README.md) |
 | `scripts/` | Repo-Setup (`bootstrap-gitea.sh`) | — |
 | `AGENTS.md` | Arbeitsanweisungen für Coding-Agents und Contributor:innen | [AGENTS.md](AGENTS.md) |
 | `LICENSE` | Code-Lizenz: AGPL-3.0-only | [LICENSE](LICENSE) |
@@ -53,8 +53,11 @@ Prototyp (Konzeptphase + erster Code):
 - **`sn-exit` v0** funktioniert: kontingentierter Uplink-Proxy (Byte-Relay,
   CONNECT-Tunnel für HTTPS, SSRF-Schutz, Source-Allowlist) — End-to-End
   mit `sn-fetch` gegen einen echten Server verifiziert
+- **`sn-fair` v0** funktioniert: Fairness-Engine (gewichtetes Max-Min,
+  Leech-Politik) + Demo-CLI — die Soll-Aufteilung für den Piloten
 - **Nächste Schritte:** Pilot mit 2–3 Haushalten (Yggdrasil-Overlay
-  verkabeln, Messwerte), Fairness-Scheduler — siehe
+  verkabeln, Messwerte — Handbuch:
+  [pilot.md](documentation/ideen/pilot.md)), `sn-node`-Daemon — siehe
   [Roadmap](documentation/ideen/roadmap.md)
 
 ## Doku lesen (Obsidian)

documentation/Home.md

@@ -26,6 +26,7 @@ Nachbarschaft betreibt ihre eigene Instanz nach eigenen Regeln.
 | [[Splitting]] | Was sich splitten lässt: Ranges, Flow-Verteilung, Realtime |
 | [[Lizenz]] | Lizenz-Optionen (Code & Doku) |
 | [[Roadmap]] | Phasen: Pilot → MVP → Rollout → Freenet → Backbone |
+| [[Pilot]] | Pilot-Handbuch: 2 Haushalte verkabeln, messen, dokumentieren |
 | [[Server-README|Server-Konzept]] | Software-Komponenten, Code-Standards |
 
 ## Lesereihenfolge zum Einstieg
@@ -44,6 +45,8 @@ Nachbarschaft betreibt ihre eigene Instanz nach eigenen Regeln.
 - [[Splitting]] ↔ [[Architektur]] (Schicht 2) — was der Exit-Pool tatsächlich nutzen kann
 - [[Overlay]] ↔ [[Architektur]] (Schicht 1) — Routing-Entscheidung und deren Grenzen
 - [[Overlay]] ↔ [[Server-README]] — `sn-node` generiert die Yggdrasil-Config, `sn-fetch` nutzt `Egress::Proxy`
+- [[Pilot]] ↔ [[Roadmap]] (Phase 1) und [[Overlay]] §Deployment — der Pilot ist der erste Real-Test
+- [[Pilot]] §M4 ↔ [[Architektur]] §Fairness-Scheduler — `sn-fair` berechnet die Soll-Aufteilung
 - [[Lizenz]] ↔ [[Ethos]] §6 (Transparenz) und `freenet-core` (AGPL)
 
 ## Außerhalb der Doku

documentation/README.md

@@ -17,6 +17,7 @@ unabhängige SpiderNet-Instanzen geben; wir providen nur die Werkzeuge.
 - [[Splitting]] — Was sich über mehrere Exits splitten/verteilen lässt (und was nicht)
 - [[Lizenz]] — Lizenz-Optionen und Empfehlung
 - [[Roadmap]] — Phasenplan vom Pilot bis zum Nachbarschafts-Backbone
+- [[Pilot]] — Pilot-Handbuch: Schritt-für-Schritt + Messprotokoll (Phase 1)
 - [[Server-README|Server-Konzept]] — geplante Software (`sn-node`, `sn-fetch`, …)
 
 ## Die Idee in einem Satz
@@ -29,10 +30,11 @@ ist — ohne Mehrkosten und mit besserer Versorgung schwacher Haushalte.
 ## Status
 
 Prototypphase (siehe [[Roadmap]]): `sn-fetch` (segmentierter Multi-Exit-
-Download mit Retry + Egress), `sn-node` v0 (Yggdrasil-Config + Status)
+Download mit Retry + Egress), `sn-node` v0 (Yggdrasil-Config + Status),
-und `sn-exit` v0 (kontingentierter Uplink-Proxy mit SSRF-Schutz) sind
+`sn-exit` v0 (kontingentierter Uplink-Proxy mit SSRF-Schutz) und `sn-fair`
-implementiert und getestet — Details in [`server/README.md`](../server/README.md).
+v0 (Fairness-Engine + Demo-CLI) sind implementiert und getestet —
-Nächster Meilenstein: Pilot mit 2–3 Haushalten (echtes Overlay, Messwerte).
+Details in [`server/README.md`](../server/README.md). Nächster
+Meilenstein: Pilot mit 2–3 Haushalten (Handbuch: [[Pilot]]).
 
 ## Verwandte Projekte (Prior Art)
 

documentation/ideen/architektur.md

@@ -133,6 +133,11 @@ siehe [[Splitting]].
 - Exit-Kontingente (Volumenlimit, Wartungszeit) werden respektiert
 - Leech-Nodes: niedrigste Priorität bei Knappheit, nie ausgeschlossen
 
+Status: **v0 implementiert** — gewichtetes Max-Min in zwei Klassen:
+Contributors teilen die volle Kapazität nach Max-Min, Leeches teilen
+die Restkapazität (bei Sättigung zuerst gedrosselt, nie ausgeschlossen).
+Details in `server/README.md`; Soll-Ist-Vergleich im Piloten: [[Pilot]] §M4.
+
 ### Nachbarschafts-Cache (`sn-cache`)
 
 - Transparenter Shared-Cache (lancache-Prinzip): große, populäre Objekte

documentation/ideen/pilot.md

@@ -0,0 +1,206 @@
+# Pilot: zwei Haushalte verbinden und messen
+
+> Prototyp-Betrieb, **keine Garantie** (AGPL §§ 15/16) — Nutzung auf eigene
+> Verantwortung, siehe [[Recht]] und [[Server-README]]. Persönliche Daten
+> (Namen, Adressen, Keys realer Nachbarn) bleiben **außerhalb des Repos**.
+
+Ziel der Phase 1 (siehe [[Roadmap]]) ist der Beweis, dass Bandbreiten-
+Pooling über zwei echte Anschlüsse real funktioniert — nicht auf dem
+Papier. Der Pilot liefert:
+
+1. **Messwerte:** 1-Exit-Baseline vs. 2-Exit-gepoolt (gleiche Datei)
+2. **Fairness-Daten:** zwei gleichzeitige Downloads teilen sich den Pool
+3. **Stolpersteine:** was die Doku/Software dadurch lernen muss
+
+Der Pilot ist **link-agnostisch**: Ob die Häuser per Glasfaser,
+SFP+-Direktkabel, Switch im Keller, 60-GHz-Richtfunk oder normalem
+Ethernet verbunden sind, entscheidet die Nachbarschaft — die Software
+misst, was da ist (siehe [[Architektur]], Schicht 0). Alle
+Angaben zu Link-Typen in dieser Datei sind Beispiele.
+
+## Voraussetzungen
+
+### Teilnehmer
+
+- 2 Haushalte (ideal 3, der dritte als **Leech** — Empfang ohne
+  Exit-Angebot, um genau diesen Modus mitzutesten)
+- Ein persönlicher Termin; technisches Onboarding gesicht zu gesicht
+  (Nachbarn sind der Trust-Anchor, siehe [[Architektur]])
+
+### Hardware (je Haushalt, Beispiele)
+
+- Ein Mini-PC oder Einplatinenrechner (≥ 2 GB RAM, Debian o. ä.) als
+  Node-Host — je eine NIC Richtung Heim-Router und Richtung
+  Nachbarschafts-Link (übergangsweise reicht auch eine NIC am
+  Mesh-Switch)
+- Verbindungsweg — **eins davon genügt:**
+  - Glasfaser/DAC-Direktkabel zwischen den SFP/SFP+-Ports
+  - gemeinsamer Switch im Keller/Treppenhaus
+  - 60-GHz-Richtfunk-Pair (Sichtlinie nötig, siehe [[Recht]] §3)
+  - vorhandenes Ethernet/WLAN (langsamer, aber null Aufwand)
+
+### Software
+
+- [yggdrasil](https://yggdrasil-network.github.io/) (Binary oder
+  Debian-Paket)
+- SpiderNet-Binaries bauen und rüberkopieren:
+
+```sh
+cd server
+cargo build --release --workspace
+# → target/release/sn-node, sn-exit, sn-fetch, sn-fair
+```
+
+### Vor dem Termin (Checkliste)
+
+- [ ] ISP-AGB der Teilnehmenden geprüft (Weitergabe an Dritte,
+  siehe [[Recht]] §2)
+- [ ] Nachbarschafts-Abkommen geklärt: wer spendiert wie viel
+  (Quota), Leechen ausdrücklich erlaubt, alles jederzeit widerruflich
+- [ ] Hardware vorhanden und bootfähig
+- [ ] Binaries gebaut und auf beide Nodes kopiert
+- [ ] Testdatei gewählt: Range-fähiger Server, ~750 MB, bekannte
+  SHA-256 (im PoC hat sich eine Debian-Netinst-ISO bewährt; die
+  offizielle `SHA256SUMS` der jeweiligen Version nutzen)
+
+## Termintag: Schritt-für-Schritt
+
+Die technischen Details (Config, Schlüssel, Admin-Socket) stehen in
+[[Overlay]] §Deployment — hier die Reihenfolge mit Checkpunkten.
+
+1. **Physik verbinden.** Link herstellen, L2-Test: `ping` über die
+   lokale Verbindung. Optional `iperf3` über den Link → das ist
+   **Messpunkt M0** (Kapazität des Nachbarschafts-Links).
+2. **Yggdrasil einrichten (beide Häuser).**
+
+   ```sh
+   sn-node genconf --listen "tcp://[::]:1337" \
+     --peer "tcp://[<Mesh-IP des Nachbarn>]:1337" \
+     --allow-key <Public-Key des Nachbarn> \
+     --private-key-path /etc/spidernet/node.key \
+     --out /etc/yggdrasil.conf
+   yggdrasil -useconffile /etc/yggdrasil.conf
+   sn-node status   # eigene Overlay-Adresse + Peering-Status
+   ```
+
+   - Im selben LAN reicht Multicast-Auto-Peering (ohne `--peer`).
+   - Config enthält den **privaten** Key (`chmod 600` macht
+     `genconf` selbst) — niemals teilen oder committen.
+   - Die eigenen Adressen/Keys werden **persönlich** ausgetauscht,
+     nicht per Chat/Repo.
+3. **Overlay-Test.** `sn-node status` zeigt auf *beiden* Seiten den
+   Nachbarn als Peer; `ping <Overlay-Adresse des Nachbarn>` geht.
+4. **Exit starten (Haus B spendiert):**
+
+   ```sh
+   sn-exit --bind "[<Overlay-Adresse B>]:8080" \
+     --allow <Overlay-Adresse A> \
+     --quota-mib 1024
+   ```
+
+   - `--allow` nie offen lassen (ohne Liste ist nur Loopback
+     erlaubt, das ist der Dev-Mode).
+   - Test von Haus A: ein HTTP-Request gegen einen Origin über
+     `http://[<Overlay-Adresse B>]:8080` als Proxy (z. B. mit
+     `sn-fetch --probe-only` oder `curl -x`).
+5. **Erster gepoolter Download (Haus A):**
+
+   ```sh
+   sn-fetch <url> -o testdatei.iso \
+     -e "1=1,2=1@http://[<Overlay-Adresse B>]:8080" \
+     --sha256 <erwarteter-hash>
+   ```
+
+6. **Kill-Switch-Test.** `sn-exit` auf B stoppen → laufender und
+   nächster Download fällt auf den eigenen Uplink zurück (Retry mit
+   Exit-Reassignment). Danach B wieder starten. Beides dokumentieren:
+   Dauer der Störung, verlorene Segmente.
+
+Wichtig zur Beruhigung: SpiderNet v0 installiert **keine
+Routing-Änderung** im Heimnetz. Geräte nutzen wie gewohnt den eigenen
+Router; nur `sn-fetch`-Downloads gehen (explizit) in den Pool. Alles
+stoppen (`sn-exit`, `yggdrasil`) = das Haus ist wie vorher.
+
+## Messprotokoll
+
+Regeln für belastbare Werte:
+
+- Gleiche Testdatei, gleiche Uhrzeit ± 1 h (ISP-Congestion schwankt
+  tageszeitabhängig)
+- Pro Szenario **3 Läufe**, Median notieren; zwischen Läufen Pause
+- Nichts anderes auf den Nodes laufen lassen; Messwerte immer mit
+  Datum/Uhrzeit und den beidseitigen Uplink-Tarifen notieren
+
+### Szenarien
+
+| # | Szenario | Wo | Was gemessen wird |
+|---|---|---|---|
+| M0 | Nachbarschafts-Link-Kapazität | A↔B | `iperf3` über den lokalen Link |
+| M1 | Uplink-Baseline | je Haus | nur eigener Uplink (`-e "1=1"`), ISP-Kapazität |
+| M2 | Gepoolt, 1 Download | A | 2 Exits (`-e "1=1,2=1@http://[B]:8080"`), Gesamt-Durchsatz vs. M1 |
+| M3 | Gepoolt, Konkurrenz | A + B | zwei `sn-fetch`-Läufe gleichzeitig, beide über beide Exits — wie teilen sich die Aufstellung |
+| M4 | Fairness-Soll | (Simulation) | `sn-fair` mit den M1/M2-Werten → Soll-Aufteilung zum Vergleich mit M3 |
+
+### Tabelle M2/M3 (Vorlage, pro Lauf eine Zeile)
+
+| Lauf | Szenario | Datum/Zeit | Durchsatz Mbit/s | Dauer | Segmente | Retries | Bemerkung |
+|---|---|---|---|---|---|---|---|
+| 1 | M2 | | | | | | |
+| 2 | M2 | | | | | | |
+| 3 | M2 | | | | | | |
+
+Zusätzlich notieren: Quota-Rest auf B, CPU/RAM der Node-Hosts,
+(evtl.) Firmware/Treiber des Link-Wegs.
+
+### Fairness-Soll mit `sn-fair` (M4)
+
+Die gemessenen Uplink-Kapazitäten (M1) als Pool-Kapazität und die
+gleichzeitigen Nachfragen (M3) einsetzen — das CLI arbeitet in
+Mbit/s:
+
+```sh
+sn-fair --capacity <M1-A + M1-B, Mbit/s> \
+  --participant 1=contributing \
+  --participant 2=contributing \
+  --participant 3=leeching \
+  --demand 1=<Nachfrage A> \
+  --demand 2=<Nachfrage B> \
+  --demand 3=<Nachfrage Leech>
+```
+
+Erwartung (Regelwerk in [[Architektur]] §Fairness-Scheduler):
+Contributors bekommen die Kapazität nach max-min Fairness (gewichtet),
+Leeches profitieren von Restkapazität — bei Sättigung zuerst gedrosselt,
+nie ausgeschlossen. Weicht M3 (Ist) deutlich von M4 (Soll) ab, landet
+das als Erkenntnis in der Ergebnisse-Sektion unten (die echte
+Runtime-Integration in `sn-fetch` ist Phase 2, siehe [[Roadmap]]).
+
+## Sicherheit & Recht (Checkliste während des Piloten)
+
+- [ ] `sn-exit` nur mit `--allow` (Allowlist) und Quota laufen lassen
+- [ ] SSRF-Schutz nie deaktivieren (verhindert Nachbarn-Zugriff auf
+  Heim-LAN/Admin-Sockets des Exit-Haushalts)
+- [ ] Keine Port-Forwards ins Internet, außer ein Peering braucht es
+  zwingend (siehe [[Overlay]] §Grenzen)
+- [ ] Logs minimal und lokal (keine Inhaltslogs, siehe [[Recht]] §4)
+- [ ] Haftungsausschluss ist den Teilnehmenden bekannt gezeigt
+- [ ] Sperrbarkeit praktisch geübt: Exit stoppen = Kill-Switch,
+  Teilnehmersperre = `--allow`-Liste ändern
+
+## Ergebnisse
+
+*(wird nach dem Piloten gefüllt — Messwerte, Erkenntnisse und
+Stolpersteine gehören hier ins Repo, nicht in den Chat)*
+
+### Messwerte
+
+*(Tabelle ergänzen — M0 bis M4, Mediane der 3 Läufe)*
+
+### Erkenntnisse
+
+*(kurz, ehrlich, mit Quellen/Logs wo sinnvoll)*
+
+### Stolpersteine & Anpassungen
+
+*(was in [[Architektur]], [[Overlay]], [[Roadmap]] oder der Software
+geändert werden muss, damit der nächste Pilot weniger stolpert)*

documentation/ideen/roadmap.md

@@ -14,6 +14,7 @@ endet mit etwas, das man benutzen kann.
 ## Phase 1 — Pilot (2–3 Haushalte)
 
 Ziel: Beweis, dass Pooling über zwei Anschlüsse real funktioniert.
+Handbuch mit Messprotokoll: [[Pilot]].
 
 - [x] `sn-fetch` PoC (lokal): Range-Probe, gewichteter Planner, parallele
       Segment-Downloads, Reassembly + SHA-256 — verifiziert gegen einen
@@ -27,10 +28,12 @@ Ziel: Beweis, dass Pooling über zwei Anschlüsse real funktioniert.
       WLAN/60-GHz), `sn-node`-Daemon orchestriert den Node
 - [x] `sn-exit` v0: HTTP-Proxy auf der Yggdrasil-Adresse (Kontingente,
       SSRF-Schutz, Kill-Switch = Prozess stoppen)
+- [x] `sn-fair` v0: Fairness-Engine (gewichtetes Max-Min über zwei
+      Klassen, Leech-Politik) + Demo-CLI; Runtime-Integration in
+      `sn-fetch` ist Phase 2
 - [ ] `sn-fetch` PoC über 2 echte Exits, plus Baseline-Messung
-      (1-Exit vs. 2-Exit, gleiche Datei)
+      (1-Exit vs. 2-Exit, gleiche Datei — Protokoll in [[Pilot]])
-- [ ] Fair-Share-Scheduler v0: zwei gleichzeitige Downloads, faire Aufteilung
+- [ ] Doku: Messwerte, Erkenntnisse, Stolpersteine → in [[Pilot]] §Ergebnisse
-- [ ] Doku: Messwerte, Erkenntnisse, Stolpersteine → hier in das Repo
 
 ## Phase 2 — MVP-Software
 

server/README.md

@@ -60,10 +60,26 @@ SHA-256 entspricht der offiziellen `SHA256SUMS`).
 - Verifiziert end-to-end: `sn-fetch` über einen laufenden `sn-exit`
   lädt die Debian-ISO (756 MB, 4 Segmente, SHA-256 korrekt)
 
-**Noch nicht drin:** `sn-node`-Daemon (Supervisor, der yggdrasil + sn-exit
+**`sn-fair` v0 ist implementiert** (siehe `crates/sn-fair/`):
-+ sn-fetch orchestriert), Fairness-Scheduler.
 
-Details zum Overlay: [[Overlay]].
+- Gewichtetes Max-Min-Fairness-Engine (zwei Klassen): **Contributors**
+  (Haushalte mit Exit-Angebot, konfigurierbares Gewicht) teilen sich
+  die Gesamtkapazität nach Max-Min-Fairness; **Leeches** (Empfang ohne
+  Beitrag, ausdrücklich legitim) bekommen die Restkapazität — bei
+  Sättigung zuerst gedrosselt, nie ausgeschlossen
+- Deterministische, overflow-sichere Berechnung (u128-Arithmetik,
+  Restverteilung in ID-Ordnung), validierte Newtypes
+  (`ParticipantId`, `Weight`, `Rate`, `Capacity`)
+- Demo-CLI in Mbit/s für den Piloten: Soll-Aufteilung simulieren und
+  gegen die gemessene Ist-Aufteilung halten (siehe [[Pilot]], M4)
+- Runtime-Integration in `sn-fetch` (echte gleichzeitige Downloads
+  drosseln) ist Phase 2, siehe [[Roadmap]]
+
+**Noch nicht drin:** `sn-node`-Daemon (Supervisor, der yggdrasil +
+sn-exit + sn-fetch orchestriert), Freenet-Integration, Cache.
+
+Details zum Overlay: [[Overlay]]. Pilot-Handbuch mit Messprotokoll:
+[[Pilot]].
 
 ## Haftungsausschluss (muss im Produkt sichtbar sein)
 
@@ -96,7 +112,7 @@ Einplatinenrechner), der:
 | `sn-node` | Node-Glue: Yggdrasil-Config (`genconf`), Overlay-Status (`status`), später Daemon/Supervisor |
 | `sn-exit` | Exit-Dienst: kontingentierter Uplink-Proxy auf der Yggdrasil-Adresse (v0: Byte-Relay + Quota + SSRF-Schutz) |
 | `sn-fetch` | Segmentierter Multi-Exit-Downloader (HTTP-API + CLI) |
-| `sn-fair` | Fairness-Scheduler (max-min, Exit-Kontingente, Karma, Leech-Modus) |
+| `sn-fair` | Fairness-Scheduler (max-min, Exit-Kontingente, Karma, Leech-Modus) — v0: zwei-Klassen-Max-Min-Engine + Demo-CLI |
 | `sn-cache` | Transparenter Nachbarschafts-Cache (DNS-basiert) |
 | `sn-freenet` | Integration von `freenet-core` (Contracts für Nachbarschafts-Inhalte) |