potatium/AGENTS.md

# AGENTS.md: verbindliche Leitlinien für Codex im Potatium-Repository

1. **Zuerst lesen:** `README.md`, `docs/PROJEKTPLAN.md`, `docs/PROTOKOLL_ENTWURF.md`, `docs/POP_FAIRNESS_UND_GEBUEHREN.md`, `docs/ROADMAP.md`, `docs/WEB_WALLET.md`, `docs/decisions/*.md`. Die letzte akzeptierte ADR entscheidet bei historischen Widersprüchen. Der *tatsächliche Git-Stand* ist maßgeblich.
2. **Bestandsaufnahme:** Umgebung Ubuntu 26.04 LTS im unprivilegierten LXC, Workspace `/home/potatium/src/potatium`, Go, private Gitea-Git-Remote. Bestehende Änderungen erhalten; nicht ungefragt branch/rebase/push oder `git clean/reset` verwenden.
3. **Architektur:** eigenständige Hobby-L1, Go, CometBFT/ABCI++ mit eigener deterministischer App als vorläufige Wahl, kein Cosmos SDK für den Start. Validatoren bestätigen Blöcke, Miner lösen nur PoP-Challenges. `linux/amd64` und `linux/arm64` als Ziel; Pi 4 als Benchmarkminimum.
4. **PoP v0.2 (akzeptierte Produktidee):** Jede Mining-Runde hat **3 zeitlich getrennte Fenster**. Fenster 1 gratis; Fenster 2/3 optional solange noch kein gültiges Ticket angenommen wurde und nach bestätigter **fixer + progressiver** Gebühr. Progressionsbasis: finalisierte PoP-Mining-Gewinne der zurückliegenden **ca. 90 Tage je registrierter Mining-Identität/Betreibergruppe**, **nicht Wallet-Guthaben**. Keine lebenslange Benachteiligung. **ADR 0007 hat die Gebührenverwendung geändert:** 100 % der PoP-Zusatzfenster- und Worker-Aktivierungsgebühren in den On-chain-Community-Fonds, 0 % Burn dieser Gebühren. Normale Transaktionsgebühren, Fondsausgaben und Tarifhöhen offen. Pro identifizierter Mining-Node **maximal ein Ticket je Gesamtrunde**. Nach Erfolg stoppen. Identität/Hardware und Betreiberzuordnung können Sybil nicht kryptografisch beweisen.
5. **Noch nicht entschieden:** BTC-artige Coin-Grenze, Mint je Runde, Gebührenbeträge/Schwellen, Nonce-Raum, exakte Fensteranzahl an Blöcken, p=70 %, feste Blockzeit, Wallet-Kryptografie, Beaconauswahl. Beispiele niemals als gültige Konsensregel kodieren. Vor PoP-Implementierung Simulationen und Pi-Messung samt ADR.
6. **Ziehung:** Ticketbestand vor künftiger überprüfbarer Zufallsquelle finalisieren. Kein `time.Now()`, externe Zufallsabfrage oder Float in deterministischen State-Transitions. Reorgs, Zeit-/Höhenfristen, Beacon-Ausfall, Zensur, Replay, Rundungsrest und Multi-Node-Gleichheit behandeln.
7. **Gebühren/Wallet:** Browser-Web-Wallet **ab erster funktionaler MVP-Version**; Keys erzeugen, importieren, verschlüsselt sichern/entsperren, Adresse, Balance, senden/empfangen, Verlauf/Netzstatus. Miner/Node erhalten nie Private Keys/Seeds. Zusatzfenster nur mit explizit begrenzter signierter Wallet-Freigabe, auf Runde/Identität/Fenster, Betrag, Nonce und Ablauf gebunden; noch nicht implementiert. UI-Vorschau niemals als funktionsfähig ausgeben.
8. **Tests:** Go `gofmt`, `go test ./...`, `go vet ./...`; passende Integrationstests, fuzzer/race tests. Für PoP Simulation und Pi 4 / Office-PC Benchmark, Fairness, Gebühren-Erwartungswerte, abweichenden Codepfad, Replay, Fondsgutschrift, echte Burns (falls vorgesehen) und Restart. Tests und Resultate **nie erfinden**.
9. **Sicherheit:** keine öffentlich gebundenen Test-APIs (nur `127.0.0.1`/SSH-Forward), keine echten Schlüssel/Tokens/Datenbank-/Wallet-Dateien in Git. Keine unverhältnismäßigen Dependencies, keine destruktiven Befehle ohne Backup. Entgeltliche Chance auf Lotteriegewinn birgt Rechtsrisiko; bis auf Weiteres **wertlose private Test-PTM**.
10. **Lieferstil:** Vor jeder größeren Änderung kurze Planung + Akzeptanzkriterien; danach Dateien/Änderungen, was real läuft, Testbefehle mit Ergebnissen, Grenzen und nächsten kleinen Schritt angeben. ADR für wesentliche Entscheidungen.

## Zukunftsvision F1–F4 (25.10.2026)

Geplante **spätere** PTM-Nutzungen sind digitale Sammlerstücke, ein interner PTM-Marktplatz und eine Handelsplattform für fiktive interne Assets mit Orderbuch, Kursen und Portfolio, optional mit **strikt getrenntem** Paper-Trading. Sie sind **noch nicht implementiert** und erfordern nach M6 eigene ADRs, sichere Eigentums-/Handelsabwicklung und klare Kennzeichnung interner vs. simulierter Kurse. **Nicht** auf Initiative von Codex vorziehen, keine Cosmos-/NFT-/DEX-Frameworks ungefragt integrieren, keine echten Preise oder Volumina erfinden. Sammlerstücke/Assetbesitz dürfen PoP-Chancen nicht erhöhen. Maßgeblich: `docs/ZUKUNFT_OEKOSYSTEM.md`, `docs/decisions/0004-zukunftsvision-internes-oekosystem.md`.

## Produktentscheidung ADR 0005: Hub/Worker/Operator (25.10.2026)

Ab M1/M2 nach `docs/HUB_WORKER_CLUSTER.md`, `docs/WORKER_GEBUEHREN_FORSCHUNG.md` und `docs/decisions/0005-hub-worker-cluster-und-betreiber.md` planen. **Hub** ist eine selbstständige Node mit optionalem Mining, Browser-Wallet und lokalem Node-Cockpit; **Worker** ist Hub-gebundener schlanker Miner mit Geräte-ID ohne Coin-Wallet/Full-Chain. Betreiberzuordnung `operator_id` aggregiert 90-Tage-Gewinne, Gebühren, Worker und Auszahlungen. **Pro Betreiber maximal ein kostenloser Hub-Mining-Platz**; zusätzliche Hub-Miner gelten wirtschaftlich als Worker. Jeder zugelassene Miner (auch Hub) maximal 1 Ticket/Runde. Das Hub-/Cluster-Cockpit hat Vorrang vor Admin-Web; Admin-CLI bei Bedarf. Private Wallet-Keys nie an Hub-Backend oder Worker weiterreichen. Fingerprint allein reicht nicht für Authentifizierung. Gebühren für Worker sind weiterhin **FORSCHUNG**, die erste 10-Worker-Grenze und Tarifzahlen sind **nicht beschlossen**; keine Konsenscodierung dieser Zahlen. Gebühren vor Kenntnis der jeweiligen Challenge. Keine offenen Admin/RPC Ports oder Node-seitige Wallet-Seeds.

## ADR 0006: Infrastruktur und frühe read-only Cockpits (25.10.2026)

Zusätzlich `docs/INFRASTRUKTUR_UND_DEPLOYMENT.md`, `docs/COCKPITS_UND_MONITORING.md` und ADR `0006-validator-infrastruktur-und-cockpits-ab-devnet.md` **zuerst lesen**. Konsens besteht nur über verfügbare Validatoren mit lokalem Go-App-State; kein zentraler Blockchain-DB-/Admin-Server. Einen 1-Validator-Devnet-Kern und später 4 getrennte Validatoren planen; normale Hubs sind Full Nodes **ohne zwingendes Validatorrecht**, Worker nur Miner. Read-only Network Admin und Hub-Statuscockpit **ab dem ersten lauffähigen Devnet** aus echten APIs speisen (bei noch nicht laufender Chain ehrlich `nicht verbunden`). Sensible schreibende Admin-Webfunktionen bleiben zurückgestellt; CLI nur mit gesondert autorisierten signierten Aktionen. Network Admin darf weder wallet-private Daten noch Coin-State verändern. Auf 127.0.0.1/SSH-Forward begrenzen. **ADR 0007:** PoP-Fenster-/Worker-Gebühren gehen zu 100 % in einen On-chain-Fonds (nicht burnen); andere Gebühren/Fondsausgaben offen. Bestehende Forschungsergebnisse nicht als beschlossene Tarife deuten. Kein Versprechen einer implementierten GUI oder Chain.

## Aktueller Architekturstand: ADR 0008 (ersetzt zentrale Network Services)

**VERBINDLICH:** Erst `docs/NETWORK_ZUGANG_UND_IDENTITAETEN.md`, `docs/INFRASTRUKTUR_UND_DEPLOYMENT.md`, `docs/COCKPITS_UND_MONITORING.md` und ADR 0008 lesen. **KEIN verpflichtendes `potatium-network`, kein zentrales Benutzerportal, kein zentraler Coin-Server** implementieren. Hub-P2P-Bootstrap anhand vertrauenswürdiger Chain-ID/Genesis und Peer-Liste lokal konfigurieren; Mining-Zulassung ausschließlich on-chain mit signierten Admin-Freigaben/Sperren. Frühestes Devnet muss lesendes Network Admin und Hub-Status-Cockpit mit echten Werten/nicht-verfügbar-Zuständen haben; Node-Signaturen, Wallet-Spend-Keys und Admin-Signatur streng getrennt. Admin-Web darf als frühe Ausnahme nur Identitätsfreigabe/Sperrung mit protokollseitig geprüftem signiertem Workflow auslösen; weder Guthaben noch Tarife noch Fonds eigenmächtig verändern. Optionaler Status-/Heartbeat-Sammler (und SQLite) ist *nicht* Blockchain-/P2P-/Registrierungspflicht. Keine vollständigen Live-Zahlen ohne Datenabdeckung behaupten.

**Forschung:** `docs/POP_DYNAMIK_FONDS_AUSWERTUNG_2026-10-25.md` liefert 36 Monte-Carlo-Läufe als **nicht bindende** Gebühren-/Fonds-Erkenntnisse; 1×/3×/5×, 720 Modellrunden/Tag, 1 PTM/Runde, höchstens 10 Worker und hypothetische Rückverteilung sind *keine* Protokollregeln. 100 % PoP-/Worker-Gebühren an Fonds, 0 % Burn sind dagegen beschlossen; Tx-Gebühren und Fonds-Ausgabeordnung bleiben offen.