mission-control-v2/AGENTS.md

AGENTS.md — Mission Control 2.0

Projekt-Geschmack für Coding-Agenten (Kilo Code, Claude Code lesen diese Datei). Kurz gehalten, nur die Wahrheiten, die man sonst schmerzhaft lernt. Details: README.md, docs/.

Was das ist

Lokaler Local-AI-Stack für die Box (Bosgame M5, Strix Halo, Vulkan/RADV). Schichten: Engine (llama-swap) · Builtin-Routing-Gateway (model: auto) · MC2 (FastAPI + React/shadcn) · Hermes-Agent (das autonome Gehirn "Lucy"). Backend Python (Box läuft Python 3.14), Frontend Vite/React/shadcn/Tailwind.

Hardware-Spezifikationen der Box (WICHTIG für alle Agenten):

• System: Bosgame M5 (AMD Strix Halo APU)
• Arbeitsspeicher (RAM/VRAM): 128 GB Shared Memory (ca. 122.7 GB nutzbar).
• Inference-Limit: Modelle im GGUF-Format dürfen maximal ca. 100-110 GB groß sein (entspricht ca. 150B Parametern bei Q4_K_M). Größere Modelle (wie 200B+ oder 2T Parameter) können lokal nicht ausgeführt werden und sind auszuschließen, es sei denn, es handelt sich um stark quantisierte MoEs. Gedächtnis & Dienste: Hermes ist das autonome Agenten-Gehirn („Lucy") und die alleinige Gedächtnis-Wahrheit — es führt sein Gedächtnis selbst. Der frühere Sidecar auf :8765 samt Memory-MCP-Server und MC2-Memory-Plugin wurde am 07.08.2026 abgelöst und am 27.08.2026 restlos ausgebaut (docs/wissen/VERDIKTE.md): MC2 hat keine /api/memory-Routen mehr, nichts darf mehr dorthin greifen. Governor, Zed-Workflows und alte Mittelschichten sind komplett gelöscht.

Sprache (nicht verhandelbar)

• Alles User-Sichtbare ist Deutsch: UI-Texte, Fehlermeldungen, Update-/Radar-Meldungen, Skills, LLM-Summaries, Commit-Messages, Code-Kommentare.
• Hermes' INTERNE System-Prompts bleiben Englisch (fremde Software, wir forken sie nicht). Antwort-Sprache ≠ Prompt-Sprache — Deutsch kommt aus SOUL.md, nicht aus den Tool-Prompts.

Build & Deploy (die häufigste Falle)

• frontend/dist WIRD committet. Auf der Box läuft KEIN Node-Build; das Backend liefert die gebauten Assets direkt aus. Nach jeder Frontend-Änderung: cd frontend && npm run build, dann das neue frontend/dist mit-committen. Vergessen = Box zeigt alten Stand.
• Deploy macht git pull origin main (deploy/deploy.sh). Heißt: main muss vor dem Deploy auf Gitea liegen, und Änderungen an getrackten Dateien im Box-Checkout lassen den Pull scheitern — dort nie von Hand ändern. Neue Schritte in deploy.sh greifen erst beim nächsten Lauf. Schritt 3 überschreibt die lebende llama-swap-Config, wenn sie vom Abzug abweicht (MC_DEPLOY_SKIP_SWAP_CONFIG=1 verhindert das).
• Nie direkt auf main arbeiten. Immer Branch (wartung/...), Gate grün, dann Merge/Deploy.

Agentic IDE & Vibe Coding

• Zero Middle-Layers: Coding passiert zu 100% lokal auf dem Dev-PC in der OpenCode Desktop IDE.
• Es gibt keinen Zed-Workflow, keine OpenCode-CLI-Mittelschicht und keinen Governor mehr.
• Der Agent in OpenCode Desktop nutzt via MCP (.agents/mcp_config.json) die API der Box (:9001/v1), um autonom Projekte zu bauen.
• Mix-Ansatz beim Testen: Der Agent testet lokal. Vor dem Push muss er prüfen, ob das Gitea-VERIFY-Skript fehlerfrei durchläuft.

Zeit & Umgebung

• Box = Ubuntu, läuft in Europe/Berlin (seit 03.07.2026; vorher UTC). Dev-PC = Windows. Naive/lokale Zeiten immer über MC_LOCAL_TZ (= Europe/Berlin) auflösen, nie datetime.now() ohne TZ annehmen (siehe backend/services/reminders.py).

Backend-Konventionen

• Router unter backend/routers/ (APIRouter(prefix="/api")), Logik in backend/services/ (Single Source of Truth — Router bleiben dünn). Beispiel-Lehre: Restart-Allowlist lebt NUR in services.maintenance (System-Dienste via sudo -n, User-Dienste via systemctl --user); keine zweite Allowlist in einem Router duplizieren.
• Gate vor Commit: python -m py_compile <geänderte .py> muss durchlaufen.
• Wartung ist sudo-frei gedacht (systemctl --user). Wo doch sudo nötig ist (llama-swap = System-Dienst), sauber über die NOPASSWD-Whitelist / password_required-Rückgabe, nie hart failen.
• ‼️ Die feingranularen sudoers.d-Regeln sind faktisch wirkungslos. In /etc/sudoers steht hitonabi ALL=(ALL) NOPASSWD: ALL — der Nutzer, unter dem alle MC2-Dienste laufen, darf ohnehin alles passwortlos. sudoers.d/mc2-autonomie und sudoers.d/mission-control dokumentieren also, was gebraucht würde, schränken aber nichts ein. Das ist eine bewusste Entscheidung für die Single-User-Appliance; verlasse dich beim Bauen nicht darauf, dass eine Whitelist dich bremst. Wer das wirklich härten will, kommt um einen eigenen Service-User nicht herum — die Pauschalzeile einfach zu ziehen, bricht OS-Update, Config-Sync und den wöchentlichen Auto-Neustart still. (Geprüft 27.08.2026; die doppelte Zeile wurde damals entfernt, Sicherung /root/sudoers.bak-*.)
• Lokal (Windows) müssen Box-Shell-Befehle harmlos fehlschlagen statt zu crashen.

Grenzen (Verdikt, eingehalten)

• Hermes-Quellcode nie selbst patchen (Fork verboten). Config/Deps ja, Code-Umbau nein.
• Security-Config (approvals, Tokens, ufw, command_allowlist) nie ohne explizites User-Ja.
• Alles reversibel halten: Branch + Backup + Pin.

Gitea

Remote = ssh://gitea@192.168.178.153:2222/Hitonabi/mission-control-v2.git (SSH, Push aus Git-Bash geht). Bei Aussetzern Push mit Retry. Neue Repos per API anlegen. Kein GitHub. Ungemergtes, das weg soll, erst als Tag archiv/<name> sichern, dann löschen.