# Doku — Index, Lesereihenfolge, Pflegeregeln

_Stand 24.09.2026. Das Projekt heißt „Homelab Orchestrator"; der Bereich für die KI-Box heißt „Box-Wart", der für
den Proxmox-PC „Homelab". Bei Widerspruch gilt: Code vor Doku, [wissen/STACK.md](wissen/STACK.md) vor anderen
Dokumenten, aktuelle Doku vor dem Archiv._

## Lesereihenfolge

**Frischer Agent:**

1. [../AGENTS.md](../AGENTS.md): verbindliche Bau-Regeln.
2. [wissen/ARBEITSWEISE.md](wissen/ARBEITSWEISE.md): wer der User ist, die Regeln, was wohin gehört.
3. [wissen/STACK.md](wissen/STACK.md): Maschinen, Dienste, Modelle, Automatik.
4. [ARCHITEKTUR.md](ARCHITEKTUR.md): wie die Teile zusammenhängen.
5. [wissen/VERDIKTE.md](wissen/VERDIKTE.md): was entschieden ist.
6. [wissen/FALLEN.md](wissen/FALLEN.md): vor jeder Änderung an der Box.
7. [wissen/OFFENE-FAEDEN.md](wissen/OFFENE-FAEDEN.md): was als Nächstes ansteht.

**Betrieb und Störungen:** [BETRIEB.md](BETRIEB.md), dann je nach Thema [UPDATES.md](UPDATES.md),
[RADAR.md](RADAR.md), [WIEDERAUFBAU.md](WIEDERAUFBAU.md) und [../deploy/jobs/README.md](../deploy/jobs/README.md).

**User:** [BEDIENUNG.md](BEDIENUNG.md).

## Die Dateien

| Datei | Für | Inhalt |
|---|---|---|
| [BEDIENUNG.md](BEDIENUNG.md) | User | Oberfläche, Telegram-Nachrichten, was tun, wenn etwas hakt |
| [ARCHITEKTUR.md](ARCHITEKTUR.md) | Agenten, Technik | Prozesse, Rollen und Partner-Instanz, Modell-Rollen, wer was schreibt, Meldeweg, Schnittstellen |
| [BETRIEB.md](BETRIEB.md) | Agenten, Technik | Handgriffe, Meldungen, Wächter-Regeln, Deploy und Prüftor, Sicherung, Notfall |
| [UPDATES.md](UPDATES.md) | Agenten, Technik | Sonntags-Kette, Prüfungen, Festhalten und Freigeben, Handbetrieb |
| [RADAR.md](RADAR.md) | Agenten, Technik | Modell-Radar, Prüfstand, Stack-Radar |
| [WIEDERAUFBAU.md](WIEDERAUFBAU.md) | Technik | die KI-Box von null; Anhang A: llama-swap-Unit |
| [wissen/STACK.md](wissen/STACK.md) | Agenten | Stand-Wahrheit: Maschinen, Dienste, Modelle, Automatik |
| [wissen/VERDIKTE.md](wissen/VERDIKTE.md) | Agenten | Entscheidungen mit Datum und Grund; Abschnitt „Überholt" |
| [wissen/FALLEN.md](wissen/FALLEN.md) | Agenten | Fallen mit Datum und Symptom |
| [wissen/ARBEITSWEISE.md](wissen/ARBEITSWEISE.md) | Agenten | User-Profil, Regeln, Flächen |
| [wissen/OFFENE-FAEDEN.md](wissen/OFFENE-FAEDEN.md) | alle | Fahrplan und die eine Liste offener Punkte |
| [../deploy/jobs/README.md](../deploy/jobs/README.md) | Agenten, Technik | Hermes-Jobs und Timer, Daily News |

## Archiv

`archiv/` hält historische Dokumente mit Datumspräfix. Sie werden nicht mehr gepflegt; Aussagen und Links darin
können veraltet sein.

| Datei | Inhalt |
|---|---|
| `2026-06-30-optimierungsplan.md` | Audit und Plan zu Rollen, Warm-Set und Durchsatz (Juni) |
| `2026-06-30-zeroclaw-poc-auftrag.md`, `…-ergebnis.md` | ZeroClaw-Test; Beleg für „Hermes bleibt" |
| `2026-06-30-lucy-tts-plan.md` | Stimmen-Strategie für Lucy (Juni) |
| `2026-07-02-autonomie-plan.md` | „Die Box wartet sich selbst", Etappen E1–E6 |
| `2026-07-02-komplett-review.md` | Review von MC2 und Lucy |
| `2026-07-06-antigravity-review-prompt.md` | Review-Auftrag für Gemini |
| `2026-07-10-gemini-briefing.md` | Notfall-Briefing für Gemini |
| `2026-07-10-zielbild-abloesung.md` | Richtungs-Entscheid vom 10.07. |
| `2026-07-15-umbauplan-abloesung.md` | Abschluss-Review vom 15.07. mit Gateway- und Steward-Auszug |
| `2026-07-19-uebergabe-drei-welten.md` | Übergabe des Umbaus vom 19.07. |
| `2026-07-21-skill-gitea-workflow.md` | Beschreibung des früheren Skills gitea-workflow |
| `2026-08-07-hermes-setup.md` | Hermes-Runbook aus der Anfangszeit |
| `2026-08-20-savepoint.md` | Stand-Seite vom 20.08. |
| `2026-08-20-referenzaufgabe-gedaechtnis-ausbau.md`, `2026-08-20-referenz-check.sh` | Messlatte des Referenzlaufs (Ausbau des alten Gedächtnis-Dienstes) |
| `2026-08-21-hermes-werkzeuge.md` | Werkzeugsätze nach Bedarf; Kern steht in `wissen/FALLEN.md` |
| `2026-08-21-umbau-openchamber.md` | Aufbau der Coding-Bahn mit OpenChamber, Gitea-SSH |
| `2026-09-04-raphael-lucy-innere-stimme.md` | Lucy als innere Stimme (Entscheid 04.09.) |
| `2026-09-04-offene-faeden-alt.md` | Liste offener Punkte bis 04.09., mit den Lucy-Fäden |
| `gitea-host/` | Notizen zum Gitea-Host |
| `hermes-api_server-vision-patch-verwaist.diff` | verwaister Patch am Hermes-`api_server` (Bilder), nur zur Erinnerung |

Ganz gelöschte Dokumente (STATUS, CUTOVER, UPGRADE, AUDIT_KICKOFF, die Kopien unter `docs/memory/` u. a.) stehen in
der Git-Historie.

## Pflegeregeln

1. **Eine Wahrheit je Thema:** Stand → `wissen/STACK.md`; Entscheidungen → `wissen/VERDIKTE.md`; Fallen →
   `wissen/FALLEN.md`; offene Punkte → `wissen/OFFENE-FAEDEN.md` (die einzige Liste, keine zweite anlegen); Abläufe →
   `ARCHITEKTUR.md`, `BETRIEB.md`, `UPDATES.md`, `RADAR.md`.
2. **Verifizieren vor Behaupten:** Jede Aussage gegen Code oder Messung prüfen. Stand-Angaben tragen ein Datum, am
   besten mit Commit. Was nicht geprüft ist, heißt „offen" oder „nicht geprüft".
3. **Doku folgt dem Code im selben Branch:** Wer Units, Skripte, Routen, Meldungstexte oder Abläufe ändert, zieht die
   betroffenen Dokumente mit.
4. **Verdikte** ändern sich nur mit neuem, belegtem Anlass (Messung, Release, User-Entscheid); das alte wandert mit
   Datum nach „Überholt".
5. **Fallen** mit Datum und Symptom eintragen; Erledigtes streichen.
6. **Historisches** mit eigenem Wissen nach `archiv/` (Präfix `JJJJ-MM-TT-`), sonst löschen; die Git-Historie
   behält alles.
7. **Sprache:** Deutsch, knapp, Fakten statt Adjektive. `BEDIENUNG.md` in Alltagssprache ohne Fachjargon.
8. **Keine Geheimnisse** (Tokens, Passwörter, Chat-IDs) in die Doku; Sicherheitshinweise in einem Satz.
9. **Weg der Änderung:** Branch → `bash deploy/pruefen.sh` → Merge. Auf der Box kommt die Doku mit dem nächsten
   Deploy an.