From 58c3324557740ff7b42033f48713bb526463725a Mon Sep 17 00:00:00 2001 From: Micha Date: Thu, 11 Jun 2026 06:36:53 +0200 Subject: [PATCH] docs: add homelab documentation optimization proposal Co-Authored-By: Claude Fable 5 --- docs/homelab-doku-optimierung.md | 401 +++++++++++++++++++++++++++++++ 1 file changed, 401 insertions(+) create mode 100644 docs/homelab-doku-optimierung.md diff --git a/docs/homelab-doku-optimierung.md b/docs/homelab-doku-optimierung.md new file mode 100644 index 0000000..2e246ba --- /dev/null +++ b/docs/homelab-doku-optimierung.md @@ -0,0 +1,401 @@ +# Homelab-Doku-Optimierung — Analyse und Vorschlag 2026-06-11 + +Typ: Analyse / Optimierungsvorschlag · Stand: 2026-06-11 · Status: Entwurf zur Operator-Entscheidung + +Read-only-Analyse der gesamten Markdown-Dokumentation (Stand `master`, lokale +Arbeitskopie 2026-06-11). Es wurde nichts gelöscht, verschoben oder verändert; +dieses Dokument ist der einzige neue Inhalt. Abgrenzung: `docs/homelab-optimierung.md` +(2026-06-10) bewertet die **technische** Betriebsebene; dieses Dokument bewertet +ausschließlich die **Dokumentation und ihre Regeln**. + +--- + +## 1. Executive Summary + +Die Doku ist inhaltlich exzellent und ungewöhnlich diszipliniert gepflegt — +das Problem ist nicht Qualität oder Veralterung, sondern **Volumen, Mehrfachpflege +und fehlende Lebenszyklus-Regeln**. Kennzahlen: + +- **74 versionierte Markdown-Dateien, ~9.400 Zeilen** (davon `docs/`: 35 Dateien / ~5.050 Zeilen, `ops/`: 34 Dateien). +- Praktisch alle Dateien wurden in den letzten 4 Wochen angefasst — es gibt **kein Stale-Problem, aber ein Pflegelast-Problem**. +- Ein einzelner Sachverhalt wird heute an **6–9 Stellen** dokumentiert (Beispiele in Abschnitt 3.1). Jede Änderung erzeugt dadurch eine Update-Kaskade über viele Dateien. +- Vier parallele Status-/To-do-Listen plus Done-Logs in fast jedem Dokument. +- Abgeschlossene Sprints, Audits und Pläne bleiben als aktive Dateien liegen, obwohl `docs/README.md` (Zeile 5) genau das verbietet — die Policy existiert, wird aber nicht durchgesetzt. + +Kernempfehlung in einem Satz: **Nicht umstrukturieren, sondern konsolidieren** — +jeder Fakt bekommt genau ein Zuhause, Erledigtes verlässt die Arbeitskopie, +und ein neues Entscheidungs-Register (`docs/DECISIONS.md`) ersetzt die heute +über fünf Dateien verteilten Entscheidungs-Logs. Realistisches Ziel: **docs/ von +35 auf ~22 aktive Dateien, Gesamtbestand von ~9.400 auf ~6.500 Zeilen**, ohne +Wissensverlust (Git-Historie bleibt vollständig). + +--- + +## 2. Aktueller Eindruck + +### 2.1 Bestandsaufnahme + +| Bereich | Dateien | Charakter | +|---|---:|---| +| Root (`README.md`, `CLAUDE.md`, `HOMELAB_ARCHITECTURE_MASTER_V2.md`) | 3 | Einstieg, KI-Regeln, Architektur-Master (502 Zeilen) | +| `docs/` flach | 31 | Runbooks, Inventare, Statuslisten, Pläne, Snapshots — gemischt | +| `docs/audit/` | 2 | Audit-Snapshots (Workstation-Audit, DR-Readiness) | +| `docs/runbooks/` | 1 | neue Konvention, erst ein Dokument (`komodo-bulk-deploy-dns.md`) | +| `ops/restore-tests/` | 14 | README, schedule, 6× plan.md, 4× runbook.md, Hilfsdoku | +| `ops/windows-reinstall/docs/` | 8 | Workstation-Neuaufsetzen-Projekt vom Mai 2026, weitgehend abgeschlossen | +| `ops/borg-ui/`, `ops/policy-checks/`, übrige `ops/` | 12 | Tool-Doku, teils mit historischen Audits und generierten Reports | +| `monitoring/`, `services/` | 2 | Stack-/Skript-README | + +`memory/` und `.serena/` sind gitignored (Tool-Caches) und nicht Teil des Korpus. + +### 2.2 Stärken (bewusst erhalten) + +- `docs/README.md` als gepflegter Index mit expliziter Aktiv-vs.-Historie-Policy. +- `docs/REPO_MAP.md` enthält bereits eine Anti-Wildwuchs-Arbeitsregel ("Neue Doku nur, wenn dauerhaft als Runbook, Inventar oder Restliste gebraucht"). +- `docs/MASTER_TODO.md` hat Status-Kategorien (Aktiv/Entscheidung/Geparkt/Blockiert) mit Review-Triggern — das ist Best Practice. +- Runbooks sind hochwertig: konkrete Kommandos, Erfolgskriterien, Rollback (z. B. `docs/GITOPS_DRIFT_RUNBOOK.md`, `docs/GUEST_IOT_NETWORK.md`). +- Inventare trennen sauber Ist-Werte von Entscheidungen (`docs/HARDWARE_INVENTORY.md` "Betreiber-Entscheidungen"). +- Secret-Hygiene ist durchgängig: nur Namen/Pfade, nie Werte. +- Konsistente Verweis-Kultur ("Verwandte Dokumente"-Blöcke). + +Das eigentliche Asset — die Doku-Disziplin — soll erhalten bleiben. Die Optimierung +zielt darauf, dass dieselbe Disziplin **weniger Schreibarbeit pro Ereignis** kostet. + +--- + +## 3. Wichtigste Probleme + +### 3.1 P1 — Mehrfachpflege: ein Fakt, viele Heimaten (Hauptproblem) + +Gemessene Beispiele aus dem aktuellen Bestand: + +| Sachverhalt | Anzahl Stellen | Fundorte | +|---|---:|---| +| Tailscale-Docker-Stack-Abbau (2026-06-06) | **9** | `CLAUDE.md` (Ausnahmen), `HOMELAB_ARCHITECTURE_MASTER_V2.md` (§7.1 + §10), `docs/SERVICE_CATALOG.md`, `docs/RESTORE_MATRIX.md`, `docs/DISASTER_RECOVERY.md` (Phase-4-Hinweis), `docs/NETWORK_INVENTORY.md`, `docs/MASTER_TODO.md` (Done-Log), `docs/AI_CONTEXT.md` | +| Veeam-Erstbackup `baerchen` (53,8 GB / 0:11:31) | **8** | `docs/AI_CONTEXT.md`, `docs/MASTER_TODO.md` (2×), `docs/WEEKEND_STATUS_2026-06-05.md` (2×), `docs/WEEKEND_EXECUTION_PLAN_2026-06-05.md`, `docs/RESTORE_MATRIX.md`, `docs/DISASTER_RECOVERY.md` §10, `ops/windows-reinstall/docs/windows-image-backup-baseline.md` | +| Leseliste / GitOps-Hierarchie | **7** | `README.md`, `CLAUDE.md`, `docs/AI_CONTEXT.md`, `docs/WORKFLOW.md`, `HOMELAB_ARCHITECTURE_MASTER_V2.md` (§11.4 + §12), `docs/README.md`, `docs/REPO_MAP.md` | +| DR-Workstation-Smoke (2026-06-06) | **6** | `docs/EXTERNAL_DEPENDENCIES.md` (Review-Log), `docs/AUDIT_2026-05-25_TODO.md`, `docs/MASTER_TODO.md`, `docs/AI_CONTEXT.md`, `docs/audit/dr-workstation-readiness-2026-06-06.md`, `docs/DR_WORKSTATION_SETUP.md` (Einschub Schritt 6) | +| Liste der dokumentierten Ausnahmen | **5** | `CLAUDE.md`, `docs/AI_CONTEXT.md`, `HOMELAB_ARCHITECTURE_MASTER_V2.md` §10 (autoritativ), `docs/SERVICE_CATALOG.md` (Spalten), `ops/policy-checks/` (kodiert) | +| Restore-Test-Status je Dienst | **4–5** | `docs/RESTORE_MATRIX.md` (Reifegrad-Tabelle), `docs/RESTORE_HANDBOOK.md` §3, `ops/restore-tests/README.md` (Status), Done-Logs in `MASTER_TODO`/`AUDIT_2026-05-25_TODO` | +| Komodo-Kaltstart | **3–4** | `docs/DISASTER_RECOVERY.md` Phase 4 Stufe 3, `docs/SERVICES_RECOVERY.md` Stufen A–F, `ops/restore-tests/komodo-bootstrap-runbook.md` (+ `-plan.md`) | + +Ursache ist eine "Beleg-Kultur": jedes erledigte Ereignis wird als Nachweis in +alle thematisch berührten Dokumente kopiert, statt einmal dokumentiert und +verlinkt. Die Folge ist genau die Update-Kaskade, die `docs/WORKFLOW.md` +("Dokumentationspflicht": 7 Dateien prüfen pro Änderung) institutionalisiert. + +### 3.2 P2 — Vier parallele Statuslisten plus verteilte Done-Logs + +- `docs/MASTER_TODO.md` erklärt sich selbst zur führenden Liste — richtig. +- `docs/AUDIT_2026-05-25_TODO.md` bestätigt selbst, nur noch deckungsgleiche Restliste zu sein (1 offener Punkt); existiert faktisch nur als historische Hülle. +- `docs/WEEKEND_EXECUTION_PLAN_2026-06-05.md` + `docs/WEEKEND_STATUS_2026-06-05.md`: Sprint ist seit 2026-06-07 vorbei, alle Punkte erledigt; `WEEKEND_STATUS` nennt sich selbst "kurzlebig". +- `docs/AI_CONTEXT.md` führt einen eigenen Status-Block ("Aktuelle Restpunkte", "Letzte Bestaetigung", Zeilen 44–84), der `MASTER_TODO` dupliziert und bei jedem Ereignis mitgepflegt werden muss. +- Dazu eigene To-do-/Backlog-Abschnitte in `docs/DISASTER_RECOVERY.md` (§11), `docs/RESTORE_HANDBOOK.md` (§11), `docs/SERVICES_RECOVERY.md` ("Naechste Aufgaben" — alle erledigt), `docs/SERVICE_CATALOG.md` ("Bekannte offene Fragen"). +- Done-Logs wachsen unbegrenzt: `MASTER_TODO` besteht zu ~60 % aus dem Erledigt-Block; `docs/EXTERNAL_DEPENDENCIES.md` trägt 11 Review-Zeilen, die dieselben Ereignisse erneut erzählen. + +### 3.3 P3 — Restore-/DR-Wissen auf zu viele Schichten verteilt + +Sechs `docs/`-Dateien (`DISASTER_RECOVERY`, `RESTORE_MATRIX`, `RESTORE_HANDBOOK`, +`SERVICES_RECOVERY`, `ROLLBACK`, `GITOPS_DRIFT_RUNBOOK`) plus 14 Dateien unter +`ops/restore-tests/`. Konkrete Überschneidungen: + +- `docs/RESTORE_MATRIX.md` enthält ab Zeile 178 **eingebettete Runbook-Entwürfe** (Unraid-Flash, AdGuard, Tailscale, Redis) — dasselbe Genre, das unter `ops/restore-tests/*-runbook.md` bereits ein Zuhause hat. AdGuard und Redis sind dort inzwischen sogar als Skript automatisiert und validiert; die Matrix-Abschnitte sind damit doppelt. +- `docs/RESTORE_HANDBOOK.md` und `ops/restore-tests/README.md` beantworten zu ~80 % dieselben Fragen (Grundmuster, Verzeichnisse, Status je Dienst, Schnellstart) — zwei Pflegeorte für einen Prozess. +- Die `*-plan.md`-Dateien (6 Stück) waren Vor-Erstlauf-Planung; nach erfolgreichem Erstlauf sind Runbook + Skript die Wahrheit, die Pläne sind Historie (z. B. `gitea-plan.md` "Noch offen vor dem ersten echten Lauf" — der Lauf war am 2026-05-07). +- Restore-Kadenz steht dreifach: `RESTORE_HANDBOOK` §5, `ops/restore-tests/schedule.md`, `ops/restore-tests/unraid-user-scripts.md`. + +### 3.4 P4 — Historische Snapshots leben als aktive Doku weiter + +Trotz klarer Policy in `docs/README.md` ("Erledigte Audits, Chat-Handoffs ... +bleiben in der Git-Historie, aber nicht als dauerhafte Arbeitskopie"): + +- `docs/DR_DRILL_2026-06-03.md` (392 Zeilen): Findings sind laut `AUDIT_2026-05-25_TODO` vollständig in DR.md/EXTERNAL_DEPENDENCIES eingearbeitet — reines Belegmaterial. +- `docs/audit/system-audit-2026-06-05.md` (229 Zeilen): Windows-Workstation-Audit, thematisch nicht einmal Homelab-Betrieb. +- `docs/audit/dr-workstation-readiness-2026-06-06.md`: automatisch erzeugter Check-Output inkl. Rohblöcken. +- `docs/WEEKEND_*_2026-06-05.md` (2 Dateien): abgeschlossener Sprint. +- `docs/KalliLab_CORE_Audit_2026-06-06.pdf` (untracked): Binär-Report im `docs/`-Ordner. +- `ops/borg-ui/BACKUP_AUDIT_STATUS_QUO.md` (Stand 2026-04-15): Vor-Migrations-Ist-Aufnahme, von `BACKUP_SCOPE.md` abgelöst. +- `ops/policy-checks/last-report.md`: **generierter** Report, eingecheckt — bei jedem Lauf entsteht Diff-Rauschen. +- `ops/windows-reinstall/docs/` (8 Dateien, ~1.400 Zeilen): Projekt Mai 2026 ist abgeschlossen; aktiv gebraucht wird davon im Betrieb nur `windows-image-backup-baseline.md` (Veeam-Restore-Runbook, von `RESTORE_MATRIX` referenziert) und ggf. `laufwerks-neustruktur-2026-06-04.md` als Soll-Referenz. + +Es fehlt eine gelebte Archiv-Konvention — entweder konsequentes Löschen (Policy +existiert) oder ein sichtbares `docs/archive/`. + +### 3.5 P5 — Architektur-Master vermischt Zielbild und Entscheidungs-Log + +`HOMELAB_ARCHITECTURE_MASTER_V2.md` (502 Zeilen) ist Pflichtlektüre Nr. 1, trägt +aber in §13 ein unbegrenzt wachsendes Betriebs-/Entscheidungs-Log (FCP-Incident, +Plex-Reclaim-Erzählung, Digest-Pinning-Historie ...). Entscheidungen liegen +zusätzlich in `MASTER_TODO` (Geparkt-Tabelle mit Triggern), +`HARDWARE_INVENTORY` (Betreiber-Entscheidungen), `AUDIT_2026-05-25_TODO` +("Bewusst geparkt") und den Review-Logs der Inventare. Ein zentrales, +chronologisches Entscheidungs-Register (ADR-light) fehlt — +`docs/runbooks/komodo-bulk-deploy-dns.md` nennt sich bereits selbst +"Runbook / ADR-light" und zeigt den Bedarf. + +### 3.6 P6 — Einstiegs-Redundanz + +`README.md`, `CLAUDE.md`, `docs/AI_CONTEXT.md`, `docs/README.md`, +`docs/REPO_MAP.md`, `docs/WORKFLOW.md` (KI-Arbeitsregel) und +`HOMELAB_ARCHITECTURE_MASTER_V2.md` (§11/§12) wiederholen alle dieselben +Grundregeln (Quelle der Wahrheit, Leselisten, Ausnahmen) in leicht +unterschiedlichen Fassungen. Bei Regeländerungen müssen bis zu 7 Dateien +angefasst werden; die Leselisten weichen bereits leicht voneinander ab. + +### 3.7 P7 — Flacher Namensraum mit gemischten Typen und Zielgruppen + +In `docs/` liegen 31 Dateien flach nebeneinander: Familien-Doku +(`FAMILY_ONBOARDING.md`) neben Bare-Metal-DR, Statuslisten neben Inventaren, +Snapshots neben Dauer-Runbooks. Die begonnene Untergliederung +(`docs/runbooks/` mit 1 Datei, `docs/audit/` mit 2) ist inkonsistent: ~10 +Runbook-artige Dokumente liegen weiter flach. Namensstile mischen sich +(`SCREAMING_SNAKE.md` vs. `homelab-optimierung.md` vs. `komodo-bulk-deploy-dns.md`). + +### 3.8 P8 — Punktuelle Doppel-Dokumente + +- `docs/H_DRIVE_NEARLINE_PULL.md` (Pull-Workflow + Befund-Historie) vs. neues, untracked `ops/h-drive-nearline/README.md` (Struktur + Betrieb + Aufräum-Historie) vs. H:/-Abschnitt in `docs/CAPACITY_AND_LIFECYCLE.md` — drei Orte für ein Thema. +- `ops/restore-tests/README.md` pflegt eine manuelle Datei-Auflistung des eigenen Verzeichnisses ("Geplante Struktur", ~35 Zeilen) — das Verzeichnis listet sich selbst. +- `ops/hermes-agent/README.md` (367 Zeilen) ist überwiegend "Phase 1 Documentation Analysis" für einen Dienst, der bis mindestens 2026-07-25 deaktiviert geparkt ist. + +--- + +## 4. Best-Practice-Abgleich (Kurzfassung) + +| Prinzip | Heute | Lücke | +|---|---|---| +| Single Source of Truth pro Fakt | Git als SSoT für Konfig ✅; für Doku-Fakten ❌ (6–9 Kopien) | Regel "ein Fakt, ein Zuhause" fehlt | +| Trennung Architektur / Runbook / Entscheidung / Status | teilweise; Mischformen wie `RESTORE_MATRIX` (Referenz + Runbooks + Status) und Master §13 | Dokumenttypen nicht explizit definiert | +| README als Einstieg | ✅ vorhanden und gut | nur Redundanz mit 6 weiteren Einstiegen | +| ADRs für Entscheidungen | verteilt auf 5 Orte | zentrales Register fehlt | +| Runbooks für Wiederholbares | ✅ stark | doppelt gepflegt (Matrix-Einbettungen, Handbook vs. README) | +| Kurze Dokumente statt Sammeldateien | gemischt; Master 502 Z., DR 400 Z., Matrix 261 Z. | Status-/Historien-Anteile aufblähen Kerndokumente | +| Archivierung Veralteter Inhalte | Policy existiert (`docs/README.md`) | wird nicht durchgesetzt; kein `archive/` | +| Namenskonventionen | de facto SCREAMING_SNAKE | nicht dokumentiert, neue Dateien weichen ab | +| Ownership / Aktualisierungsrhythmus | Ein-Operator-Modell, Review-Trigger teils vorhanden | kein definierter Doku-Review-Rhythmus | + +--- + +## 5. Konkrete Verschlankungsvorschläge + +Bewertungslegende: Mehrwert (niedrig/mittel/hoch/sehr hoch) · Aufwand +(klein/mittel/groß) · Risiko (niedrig/mittel/hoch) · Ü = Wirkung Übersichtlichkeit, +W = Wirkung Wartbarkeit (–/+/++/+++). + +### 5.1 Statuslisten auf genau eine reduzieren + +| Maßnahme | Mehrwert | Aufwand | Risiko | Ü | W | +|---|---|---|---|---|---| +| `WEEKEND_EXECUTION_PLAN_2026-06-05.md` + `WEEKEND_STATUS_2026-06-05.md` löschen/archivieren (Inhalt vollständig in `MASTER_TODO` Done-Log) | hoch | klein | niedrig | ++ | + | +| `AUDIT_2026-05-25_TODO.md` auflösen: den 1 offenen Punkt + "Bewusst geparkt" in `MASTER_TODO` übernehmen, Datei löschen | hoch | klein | niedrig | ++ | ++ | +| `AI_CONTEXT.md` Status-Block (Z. 44–84) streichen; nur Pointer "Authoritativ: `docs/MASTER_TODO.md`" behalten → Datei schrumpft auf ~35 Zeilen reine Regeln/Pointer | hoch | klein | niedrig | + | +++ | +| `MASTER_TODO` Done-Log auf die letzten ~5 Einträge begrenzen; ältere Einträge ersatzlos streichen (Git-Historie + Host-Reports sind der Beleg) | hoch | klein | niedrig | ++ | +++ | +| To-do-Restabschnitte in Detail-Dokumenten entfernen: `SERVICES_RECOVERY` "Naechste Aufgaben" (alles erledigt), `RESTORE_HANDBOOK` §11 → als Einzeiler nach `MASTER_TODO` | mittel | klein | niedrig | + | ++ | + +### 5.2 Restore-/DR-Cluster konsolidieren + +| Maßnahme | Mehrwert | Aufwand | Risiko | Ü | W | +|---|---|---|---|---|---| +| `RESTORE_MATRIX.md` auf Referenz reduzieren: eingebettete Runbook-Entwürfe (Z. 178–343) nach `ops/restore-tests/` verschieben bzw. löschen, wo Skript + Runbook schon existieren (AdGuard, Redis); Matrix behält nur Tier-Tabellen + Reifegrad | hoch | mittel | niedrig | ++ | ++ | +| `RESTORE_HANDBOOK.md` und `ops/restore-tests/README.md` zu **einem** Betriebsdokument zusammenführen (Empfehlung: `ops/restore-tests/README.md` als Zuhause, da Skripte dort liegen; `docs/README.md`-Index verlinkt) | hoch | mittel | niedrig | ++ | ++ | +| Die 6 `*-plan.md` unter `ops/restore-tests/` archivieren/löschen — Runbook + Skript sind seit den Erstläufen die Wahrheit | mittel | klein | niedrig | + | + | +| Restore-Status nur noch in der Reifegrad-Tabelle der `RESTORE_MATRIX` führen; `ops/restore-tests/README.md` "Status"-Abschnitt durch Link ersetzen | mittel | klein | niedrig | + | ++ | +| Komodo-Kaltstart: `SERVICES_RECOVERY.md` bleibt kanonisch (Stufen A–F); `DISASTER_RECOVERY.md` Phase 4 Stufe 3 auf Verweis + 3 Kern-Stolperfallen kürzen | mittel | klein | niedrig | + | ++ | +| `ROLLBACK.md`: abgeschlossene Service-Rollbacks (Uptime-Kuma, Grafana/InfluxDB-Altstack, BentoPDF/Stirling) streichen — Rollback-Pfade für entfernte Dienste gehören in die Git-Historie | mittel | klein | niedrig | + | + | + +### 5.3 Entscheidungs-Register einführen (wichtigste strukturelle Maßnahme) + +| Maßnahme | Mehrwert | Aufwand | Risiko | Ü | W | +|---|---|---|---|---|---| +| Neues `docs/DECISIONS.md` (ADR-light, eine Datei, neueste oben): Datum, Entscheidung, Kontext, Alternativen, Review-Trigger — je Eintrag 5–15 Zeilen | sehr hoch | mittel | niedrig | ++ | +++ | +| `HOMELAB_ARCHITECTURE_MASTER_V2.md` §13 dorthin migrieren; §9 (historische Migration) auf 3 Zeilen kürzen → Master schrumpft von 502 auf ~300 Zeilen reines Zielbild | sehr hoch | mittel | mittel* | +++ | +++ | +| Künftige Entscheidungen **nur noch** dort; `MASTER_TODO` "Geparkt" verlinkt auf DECISIONS-Einträge statt sie zu wiederholen | hoch | klein | niedrig | ++ | +++ | + +*Risiko "mittel" nur, weil der Master Pflichtlektüre für alle Agenten ist — +Migration als ein sauberer Commit mit Verweis im Master ("Entscheidungs-Log: +siehe `docs/DECISIONS.md`") entschärft das vollständig. + +### 5.4 Historisches archivieren + +| Maßnahme | Mehrwert | Aufwand | Risiko | Ü | W | +|---|---|---|---|---|---| +| `docs/archive/` anlegen (oder konsequent löschen — Operator-Frage 1); dorthin: `DR_DRILL_2026-06-03.md`, `docs/audit/*` (beide), `HOME_ASSISTANT_INFLUXDB_ECOWITT.md` (selbst als archiviert markiert), Weekend-Dateien | hoch | klein | niedrig | +++ | ++ | +| `ops/windows-reinstall/docs/`: nur `windows-image-backup-baseline.md` (aktives Veeam-DR-Runbook) und `laufwerks-neustruktur-2026-06-04.md` (Soll-Referenz) bleiben aktiv; die übrigen 6 Dateien archivieren | mittel | klein | niedrig | ++ | + | +| `ops/borg-ui/BACKUP_AUDIT_STATUS_QUO.md` archivieren (`BACKUP_SCOPE.md` ist das aktive Zielbild) | mittel | klein | niedrig | + | + | +| `ops/policy-checks/last-report.md` aus Git entfernen und in `.gitignore` aufnehmen (generiertes Artefakt) | mittel | klein | niedrig | + | ++ | +| `docs/KalliLab_CORE_Audit_2026-06-06.pdf` nicht committen; Ablage auf Share/H: statt im GitOps-Repo | mittel | klein | niedrig | + | + | + +### 5.5 Punktuelle Zusammenführungen + +| Maßnahme | Mehrwert | Aufwand | Risiko | Ü | W | +|---|---|---|---|---|---| +| H:/-Thema: `ops/h-drive-nearline/README.md` (neu, derzeit untracked) committen und zur einzigen H:/-Doku machen; `docs/H_DRIVE_NEARLINE_PULL.md` auf Kurzverweis reduzieren oder auflösen; Befund-Historie 2026-05/06 → `DECISIONS.md` oder Git | mittel | klein | niedrig | + | ++ | +| `ops/restore-tests/README.md`: manuelle Datei-Auflistung ("Geplante Struktur") auf die 5 Einstiegs-Skripte kürzen | niedrig–mittel | klein | niedrig | + | + | +| `ops/hermes-agent/README.md` beim Hermes-Review (Deadline 2026-07-25) von 367 auf ~60 Zeilen Betriebs-README kürzen oder mit dem Stack entfernen | niedrig | klein | niedrig | + | + | +| Leselisten vereinheitlichen: `README.md` und `CLAUDE.md` behalten je **eine** Leseliste; `WORKFLOW`/`Master §12`/`AI_CONTEXT` verweisen nur noch darauf | mittel | klein | niedrig | + | ++ | + +--- + +## 6. Vorgeschlagene Zielstruktur + +Bewusst **keine** Big-Bang-Umordnung: Massen-Verschiebungen brechen die +Querverweise in ~30 Dokumenten, die Pflicht-Leselisten in `CLAUDE.md` und die +Pfade im Host-Spiegel. Die Struktur bleibt erkennbar, wird aber dünner und +bekommt drei neue Sammelpunkte: + +```text +/ (unverändert) +├── README.md Einstieg, eine Leseliste +├── CLAUDE.md KI-Arbeitsregeln (verweist statt wiederholt) +├── HOMELAB_ARCHITECTURE_MASTER_V2.md nur noch Zielbild (~300 Z.) +├── docs/ +│ ├── README.md Index (Pflicht, wie heute) +│ ├── MASTER_TODO.md EINZIGE Statusliste +│ ├── DECISIONS.md NEU: Entscheidungs-Register (ADR-light) +│ ├── AI_CONTEXT.md verschlankt: Regeln + Pointer, kein Status +│ ├── WORKFLOW.md / REPO_MAP.md unverändert +│ ├── SERVICE_CATALOG.md Referenz (unverändert) +│ ├── Inventare (6): HARDWARE_, NETWORK_, STORAGE_LAYOUT, +│ │ EXTERNAL_DEPENDENCIES, CAPACITY_, SECRETS_MAP +│ ├── Runbooks (flach, Bestand): DISASTER_RECOVERY, RESTORE_MATRIX (schlank), +│ │ SERVICES_RECOVERY, ROLLBACK, GITOPS_DRIFT_RUNBOOK, +│ │ GUEST_IOT_NETWORK, EXTERNAL_OPERATOR_RUNBOOK, +│ │ DR_WORKSTATION_SETUP, AUTHELIA_OIDC_PLAN, +│ │ FAMILY_ONBOARDING, RENOVATE, ALERT_RULES +│ ├── runbooks/ NEUE themenspezifische Runbooks (kebab-case), +│ │ Bestand bleibt wo er ist +│ └── archive/ NEU: abgeschlossene Snapshots/Drills/Audits +└── ops// Tool-Doku bleibt beim Tool (README + Runbook) +``` + +Netto-Effekt: `docs/` aktiv 35 → ~22 Dateien; Gesamtbestand ~74 → ~50 aktive +Dateien; geschätzt ~2.900 Zeilen weniger Pflegefläche. + +--- + +## 7. Empfohlene Dokumenttypen + +Jede Datei bekommt genau einen Typ (im Kopf deklariert): + +| Typ | Zweck | Beispiele (Bestand) | Lebenszyklus | +|---|---|---|---| +| **Einstieg/Index** | Navigation, Regeln | `README.md`, `docs/README.md`, `CLAUDE.md` | dauerhaft, klein halten | +| **Architektur/Zielbild** | Soll-Zustand, Prinzipien, Ausnahmen | `HOMELAB_ARCHITECTURE_MASTER_V2.md` | dauerhaft; Änderungen via DECISIONS begründet | +| **Inventar/Referenz** | Ist-Werte, Kataloge, Matrizen | `SERVICE_CATALOG`, `NETWORK_INVENTORY`, `RESTORE_MATRIX` | dauerhaft; nur Ist-Stand, keine Verlaufserzählung | +| **Runbook** | wiederholbare Abläufe mit Erfolgskriterium + Rollback | `GITOPS_DRIFT_RUNBOOK`, `DR_WORKSTATION_SETUP`, `ops/restore-tests/*-runbook.md` | dauerhaft; bei Ablösung archivieren | +| **Entscheidung (ADR-light)** | Was, warum, Alternativen, Review-Trigger | NEU: `docs/DECISIONS.md` | append-only, neueste oben | +| **Status/To-do** | offene Arbeit | `MASTER_TODO.md` (einzige Instanz) | lebend; Done-Einträge max. ~5 | +| **Snapshot/Beleg** | Audits, Drills, Sprint-Boards, Messungen | `DR_DRILL_*`, `audit/*`, `WEEKEND_*`, `mem-limits-baseline` | **befristet**: nach Einarbeitung → `archive/` oder löschen | + +--- + +## 8. Merge-/Archivierungs-Kandidaten (Gesamtliste, priorisiert) + +| # | Kandidat | Aktion | Prio | +|---|---|---|---| +| 1 | `docs/WEEKEND_EXECUTION_PLAN_2026-06-05.md`, `docs/WEEKEND_STATUS_2026-06-05.md` | löschen/archivieren | sofort | +| 2 | `docs/AUDIT_2026-05-25_TODO.md` | Rest in `MASTER_TODO` mergen, löschen | sofort | +| 3 | `docs/AI_CONTEXT.md` Z. 44–84 | streichen (Pointer auf MASTER_TODO) | sofort | +| 4 | `ops/policy-checks/last-report.md` | entgitten + `.gitignore` | sofort | +| 5 | `docs/KalliLab_CORE_Audit_2026-06-06.pdf` (untracked) | nicht committen, extern ablegen | sofort | +| 6 | `docs/DR_DRILL_2026-06-03.md`, `docs/audit/*` (2), `docs/HOME_ASSISTANT_INFLUXDB_ECOWITT.md` | → `docs/archive/` | Woche 1 | +| 7 | `ops/h-drive-nearline/README.md` + `docs/H_DRIVE_NEARLINE_PULL.md` | committen + zu einem Dokument | Woche 1 | +| 8 | `HOMELAB_ARCHITECTURE_MASTER_V2.md` §13 (+§9 kürzen) | → neues `docs/DECISIONS.md` | Woche 2 | +| 9 | `docs/ROLLBACK.md` historische Service-Abschnitte | streichen | Woche 2 | +| 10 | `docs/RESTORE_HANDBOOK.md` + `ops/restore-tests/README.md` | zu einem Dokument | Woche 3 | +| 11 | `docs/RESTORE_MATRIX.md` eingebettete Runbooks (Z. 178–343) | ausgliedern/löschen | Woche 3 | +| 12 | `ops/restore-tests/*-plan.md` (6) | archivieren/löschen | Woche 3 | +| 13 | `docs/SERVICES_RECOVERY.md` Done-Tabelle; `RESTORE_HANDBOOK` §11-Backlog | streichen / nach MASTER_TODO | Woche 3 | +| 14 | `ops/windows-reinstall/docs/` (6 von 8 Dateien) | archivieren | Woche 4 | +| 15 | `ops/borg-ui/BACKUP_AUDIT_STATUS_QUO.md` | archivieren | Woche 4 | +| 16 | `MASTER_TODO` Done-Log, `EXTERNAL_DEPENDENCIES` Review-Log | auf jüngste Einträge kürzen | Woche 4 | +| 17 | `ops/hermes-agent/README.md` | beim Hermes-Review 2026-07-25 kürzen/entfernen | später | + +--- + +## 9. Empfohlene Namenskonventionen + +1. **Bestand nicht umbenennen.** `SCREAMING_SNAKE.md` bleibt für die etablierte Kern-Doku in `docs/` — Renames erzeugen nur Link-Brüche ohne Informationsgewinn. +2. **Neue Dateien in Unterordnern in `kebab-case.md`** (so wie `docs/runbooks/komodo-bulk-deploy-dns.md` es bereits vormacht). +3. **Datum im Dateinamen nur für Snapshots** (`YYYY-MM-DD`), und Snapshots gehören nach `docs/archive/YYYY/`. Eine datierte Datei im `docs/`-Root ist künftig per Definition ein Aufräum-Kandidat. +4. **Kopfzeilen-Konvention** (3 Felder, eine Zeile, wie in diesem Dokument): `Typ: … · Stand: YYYY-MM-DD · Status: aktiv | geparkt (Trigger: …) | archiviert`. Viele Dokumente haben "Stand:" bereits — nur Typ/Status ergänzen. +5. **Archiv-Pfad:** `docs/archive/YYYY/-.md`, oben ein Einzeiler "Archiviert am …, abgelöst durch …". + +--- + +## 10. Minimale Doku-Regeln für die Zukunft + +Vorschlag als Ersatz/Ergänzung der bestehenden Arbeitsregel in `docs/REPO_MAP.md` +(und Kurzfassung in `CLAUDE.md`): + +1. **Ein Fakt, ein Zuhause.** Status → `MASTER_TODO`. Entscheidung → `DECISIONS`. Zielbild → Architektur/Inventar/Katalog. Ablauf → genau ein Runbook. Beleg → Host-Report (`/mnt/user/backups/restore-reports/`) oder Git-Commit. Alle anderen Stellen **verlinken**. +2. **Erledigt = raus aus der Arbeitskopie.** Abgeschlossene Pläne, Sprints, Audits und Drill-Reports wandern nach `docs/archive/` oder werden gelöscht — Git ist das Archiv (bestehende Policy aus `docs/README.md`, jetzt durchgesetzt). +3. **Neue Datei nur, wenn sie einem der 7 Typen aus Abschnitt 7 entspricht** — sonst ist es ein Eintrag in einer bestehenden Datei. +4. **Done-Einträge maximal 3 Zeilen.** Wer mehr Beleg braucht, verlinkt Commit oder Report. Done-Logs werden bei >5 Einträgen gekürzt. +5. **Snapshot-Dateien tragen ihr Ablaufdatum** ("Status: befristet bis …") und werden danach archiviert. +6. **Index-Pflicht bleibt:** jede neue/gelöschte Datei aktualisiert `docs/README.md` im selben Commit. +7. **Quartals-Gärtnern (15 min):** datierte Dateien im `docs/`-Root archivieren, Done-Logs kürzen, tote Links prüfen — passt zum bestehenden Quartals-Rhythmus (DR-Smoke, Restore-Drills). + +--- + +## 11. 30-Tage-Plan + +**Woche 1 — Quick Wins + Archiv-Fundament** (alles klein, risikolos): +Uncommitted Arbeitskopie klären (6 modifizierte Dateien, 2 untracked — deckt +sich mit `docs/homelab-optimierung.md` Empfehlung 9) · Kandidaten #1–#7 aus +Abschnitt 8 · `docs/archive/` anlegen. + +**Woche 2 — Entscheidungs-Register:** +`docs/DECISIONS.md` anlegen (Vorlage: 5 Felder) · Master §13 migrieren, §9 +kürzen, Verweis im Master setzen · `ROLLBACK.md` entschlacken · verstreute +"Bewusst geparkt"-Entscheidungen als DECISIONS-Einträge mit Review-Trigger +zusammenziehen. + +**Woche 3 — Restore-Cluster:** +`RESTORE_HANDBOOK` ↔ `ops/restore-tests/README.md` zusammenführen · +`RESTORE_MATRIX` auf Tabellen reduzieren, Runbook-Entwürfe ausgliedern · +`*-plan.md` archivieren · Restore-Status auf einen Ort (Reifegrad-Tabelle). + +**Woche 4 — Regeln verankern + Abschluss:** +Regeln aus Abschnitt 10 in `REPO_MAP.md`/`CLAUDE.md` einarbeiten · Leselisten +vereinheitlichen · `windows-reinstall`-Doku abschließen/archivieren · +Done-/Review-Logs kürzen · `docs/README.md`-Index final neu aufbauen · +dieses Dokument selbst nach `docs/archive/` verschieben (Regel 2 gilt auch hier). + +Jeder Schritt ist ein eigener kleiner Commit → Rollback ist immer ein +`git revert`; keine produktiven Pfade, keine Compose-Dateien betroffen. + +--- + +## 12. Quick Wins unter 30 Minuten + +| Quick Win | Wirkung | +|---|---| +| Weekend-Dateien (2) löschen | −161 Zeilen, eine Statusliste weniger | +| `AUDIT_2026-05-25_TODO.md` in `MASTER_TODO` auflösen | −57 Zeilen, Sync-Pflicht entfällt dauerhaft | +| `AI_CONTEXT` Status-Block streichen | KI-Kontext wird wartungsfrei | +| `last-report.md` entgitten + `.gitignore` | kein Diff-Rauschen pro Policy-Lauf | +| `docs/archive/` anlegen + 5 Snapshots verschieben | `docs/`-Root zeigt nur noch Aktives | +| `ops/h-drive-nearline/README.md` committen, `H_DRIVE_NEARLINE_PULL` zum Pointer machen | H:/-Thema hat ein Zuhause | +| PDF aus `docs/` entfernen (extern ablegen) | keine Binärdateien im GitOps-Repo | +| `MASTER_TODO` Done-Log auf 5 Einträge kürzen | −60 Zeilen in der führenden Liste | + +--- + +## 13. Größere Aufräumprojekte (später, bewusst optional) + +1. **Ordner-Restruktur `docs/{runbooks,inventory}/`** für den Bestand: nur angehen, wenn der flache Namensraum nach der Konsolidierung noch stört. Aufwand groß (Link-Churn in ~30 Dateien, `CLAUDE.md`-Leselisten, Host-Spiegel), Mehrwert nach der Verschlankung nur noch mittel, Risiko mittel. +2. **Doku-Linter im Policy-Check:** `ops/policy-checks/check_repo.ps1` um DOC-Checks erweitern — tote relative Links, datierte Dateien im `docs/`-Root, fehlende Typ/Stand-Kopfzeile. Passt zur bestehenden Check-Kultur; Aufwand mittel, Mehrwert hoch für die Dauerhaftigkeit der Regeln. +3. **Index-Generierung:** `docs/README.md`-Tabellen aus den Kopfzeilen generieren statt manuell pflegen. Nice-to-have für ein Ein-Personen-Lab; erst nach 2. +4. **Workstation-Doku entflechten:** prüfen, ob `baerchen`-Lifecycle-Doku (windows-reinstall, System-Audits) langfristig in ein eigenes Repo gehört; im Homelab-Repo bleibt nur das DR-relevante Veeam-Runbook. Mehrwert mittel, Aufwand mittel. +5. **Master-Diät Stufe 2:** Spalten-Überlappung zwischen Master §7-Tabellen und `SERVICE_CATALOG` reduzieren (Status/Netze doppelt). Vorsichtig angehen — beide sind Pflichtlektüre; erst nachdem DECISIONS etabliert ist. + +--- + +## 14. Offene Fragen an den Operator + +1. **Archivieren oder löschen?** `docs/archive/` macht Historie sichtbar, widerspricht aber der bestehenden "Git-Historie reicht"-Policy. Präferenz? (Empfehlung: `archive/` für Drill-/Audit-Belege mit Referenzwert, Löschen für Sprint-Boards und erledigte Pläne.) +2. **Wer konsumiert `docs/AI_CONTEXT.md`** außer Claude (Codex? Hermes? Gemini-Sessions)? Wenn nur Claude: mit `CLAUDE.md` zusammenlegen und eine Datei einsparen. Wenn mehrere: schlank behalten wie vorgeschlagen. +3. **`docs/audit/` als dauerhafte Konvention?** Sollen künftige Audit-Snapshots überhaupt ins Repo, oder reichen Host-Reports unter `/mnt/user/backups/restore-reports/` plus ein DECISIONS-/TODO-Eintrag? +4. **Folder-Restruktur (Projekt 13.1) gewünscht oder bewusst nie?** Eine klare Nein-Entscheidung wäre auch ein legitimer DECISIONS-Eintrag und beendet das Thema. +5. **Die 6 uncommitteten Doku-Änderungen** in der Arbeitskopie (u. a. `AI_CONTEXT`, `AUDIT_2026-05-25_TODO`, `WEEKEND_STATUS`, windows-reinstall-Dateien): committen oder verwerfen? Das sollte vor Umsetzung der Wochen-1-Schritte geklärt sein, damit Merges sauber bleiben. +6. **Soll `docs/WORKFLOW.md` "Dokumentationspflicht"** (7 Dateien pro Änderung prüfen) nach Einführung von Regel 1 ("ein Fakt, ein Zuhause") entsprechend verkürzt werden? Empfehlung: ja — die Prüfliste schrumpft auf "betroffenes Zuhause + Index".