Files

T

Hitonabi ce55752249 Doku (B11d): AGENTS.md — Projekt-Geschmack fuer die Coding-Lane

Zed + Kilo Code lesen AGENTS.md nativ. Destilliert die Projekt-Wahrheiten, die man
sonst schmerzhaft lernt: Deutsch fuer alles User-Sichtbare (Hermes-Prompts bleiben
englisch), frontend/dist wird committet (kein Node-Build auf der Box), Deploy macht
reset --hard origin/main (nie direkt auf main), Box=UTC/MC_LOCAL_TZ=Berlin,
py_compile-Gate, Restart-Allowlist nur in services.maintenance, Hermes nie forken,
Security nie ohne User-Ja, Gitea-Push mit Retry.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-03 19:45:34 +02:00

2.9 KiB

Raw Blame History

AGENTS.md — Mission Control 2.0

Projekt-Geschmack für Coding-Agenten (Zed, 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. Backend Python (Box läuft Python 3.14), Frontend Vite/React/shadcn/Tailwind.

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. (Ausnahme: frontend/dist/avatar.vrm ist bewusst nicht in git — siehe .gitignore.)
Deploy macht git reset --hard origin/main (deploy/deploy.sh). Heißt: main muss vor dem Deploy auf Gitea liegen, und uncommittete Box-Änderungen gehen verloren (Absicht).
Nie direkt auf main arbeiten. Immer Branch (wartung/...), Gate grün, dann Merge/Deploy.

Zeit & Umgebung

Box = Ubuntu, läuft in 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.
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 = Hitonabi/mission-control-v2. Auth ist flatterhaft → Push mit Retry, nur über PowerShell/GCM. Neue Repos per API anlegen. Kein GitHub.

2.9 KiB Raw Blame History