From ce55752249caad0ab7162d57faf781beaa0497f1 Mon Sep 17 00:00:00 2001 From: Hitonabi Date: Fri, 3 Jul 2026 19:16:45 +0200 Subject: [PATCH] =?UTF-8?q?Doku=20(B11d):=20AGENTS.md=20=E2=80=94=20Projek?= =?UTF-8?q?t-Geschmack=20fuer=20die=20Coding-Lane?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..184ca5f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# 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 ` 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.