potatium/AGENTS.md

Codex-Projektregeln für Potatium

Diese Datei ist die kurze, maßgebliche Arbeitsanweisung für alle Coding-Agenten.

1. Projekt verstehen: README.md, docs/PROJEKTPLAN.md, docs/PROTOKOLL_ENTWURF.md, docs/ROADMAP.md, docs/WEB_WALLET.md zuerst lesen. Entscheidungen (docs/decisions) beachten. Ungeklärte Punkte nicht als festgelegt ausgeben.
2. Sicherer Anfang: Das vorhandene Repository ist nur ein compilierbares Grundgerüst. potatiumd zeigt eine statische Web-Wallet-Vorschau, hat noch keine Blockchain, keine Schlüsselverwaltung und keine echte API. Implementierten Status ehrlich halten.
3. Architektur: Go, CometBFT + ABCI++ als vorläufiger Stack; eigenständige PoP-Miner und Validatoren getrennt. UI ab erster funktionaler MVP-Version, nicht verschieben.
4. Mining: Ein gültiges Los je freigegebener Node-ID pro Runde; kleine PoW-Aufgabe; Teilnehmermenge fixieren, dann erst überprüfbare Zufallszahl ziehen; keine offensichtlichen Mehrfachlose; manuelle Nodefreigabe löst Sybil-Problematik nur organisatorisch.
5. Wallet-Sicherheit: Kein privater Schlüssel/Seed ans Backend oder ins Git. Browser-Krypto erst auf Basis einer explizit geprüften Schlüssel-/Signaturspezifikation und gepflegter Bibliotheken. Den UI-Entwurf nicht als funktionale Wallet verkaufen.
6. Arbeitsweise: Zuerst Bestandsaufnahme und kurze Umsetzungsplanung, dann kleine überprüfbare Änderungen. Keine unbegründeten neuen Frameworks oder großen Abhängigkeiten. Keine produktiven Ports nach außen.
7. Prüfen: gofmt, go test ./..., go vet ./..., Shell-Syntaxprüfung; bei Bugs Regressionstest. Tests und Grenzen nennen, nichts erfinden.
8. Docs synchron: Architektur-/Protokollentscheidungen in docs/decisions/ mit Status Proposed/Accepted/Rejected; Roadmap aktualisieren. Keine stillschweigenden Änderungen bereits angenommener Produktziele.
9. Git: Kleine logisch getrennte Commits vorschlagen; nicht ungefragt pushen, remotes überschreiben oder irreversible Befehle ausführen.
10. Zielplattform: Ubuntu Server 26.04 LTS im unprivilegierten Proxmox-LXC; Builds später für Linux AMD64/ARM64; Raspberry Pi 4 als Zielreferenz.