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.