homelab-infra/docs/archive/2026/homelab-doku-optimierung-2026-06-11.md

Homelab-Doku-Optimierung — Analyse und Vorschlag 2026-06-11

Typ: Analyse / Optimierungsvorschlag · Stand: 2026-06-11 · Status: umgesetzt am 2026-06-11 (archiviert; siehe docs/DECISIONS.md Eintrag 2026-06-11). Nicht umgesetzt blieben nur: Hermes-README-Kuerzung (beim Review 2026-07-25), PDF-Ablage extern (Operator), optionale Projekte aus Abschnitt 13.

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:

/                                   (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>/                     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/<datum>-<thema>.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".