Homelab Documentation & Operational Guidelines

This document defines the structural and formatting conventions for the homelab-ops documentation library. All AI coding assistants and human maintainers must adhere to these guidelines when adding, modifying, or refactoring documentation.

---

🏛️ Documentation Directory Structure

Documentation is organized modularly under the docs/ directory by domain:

docs/
├── DOCUMENTATION_GUIDELINES.md       # Authoritative guidelines for documenting this lab (this file)
├── architecture/                     # Hardware, nodes, networking, and cluster-level design
│   ├── cluster-nodes.md              # Cluster topology, node inventory, hardware specs, roles
│   ├── networking.md                 # Network architecture, active-backup bonding, WoL, .link rules
│   ├── remote-access.md              # Ingress architecture: Cloudflare tunnels, Tailscale, Traefik
│   └── router-watchdog.md            # GL.iNet Flint 2 router & internet watchdog self-healing script
├── storage/                          # Storage pools, ZFS configurations, and permission models
│   ├── storage-map.md                # Global storage map, physical drive mapping, wearout status
│   ├── zfs-tank.md                   # Mass storage pool (tank), RAIDZ1 layout, datasets, health policy
│   └── lxc-permissions.md            # LXC UID/GID namespace shifting, POSIX ACLs, dual-user nas_shares
├── services/                         # Guest containers, VMs, Docker stacks, and hardware acceleration
│   ├── container-inventory.md        # Comprehensive inventory of LXCs, VMs, Docker compose stacks
│   ├── dockhand-gitops-sync.md       # Dockhand central management & 2-way GitOps sync architecture
│   ├── backrest-immich.md            # Backrest (Restic) offsite photo backups to Hetzner Storage Box
│   └── gpu-acceleration.md           # Intel QuickSync (QSV) passthrough, udev rules, cgroup permissions
└── runbooks/                         # Step-by-step disaster recovery, migration, and maintenance guides
    ├── universal-media-storage.md    # Universal /mnt/pve/tank_media mount & cross-node migration
    ├── drive-replacement-dr.md       # ZFS drive failure & replacement procedure
    ├── pbs-backup-sync.md            # Proxmox Backup Server integration & sync architectures
    ├── cold-backup-pipeline.md       # Automated Plug-and-Run offline cold backup to 2TB WD drive
    ├── pve1_reimage_zfs_runbook.md   # Historical PVE-1 ZFS root migration & re-imaging runbook
    ├── ksm-power-optimization.md     # Proxmox KSM & ksmtuned disablement for CPU C-state power saving
    └── realtek-2.5g-r8125-driver-fix.md # Realtek RTL8125 2.5GbE link flapping & DKMS driver fix

---

📝 Rules for AI Agents & Maintainers

1. Maintain Single Source of Truth

• The root README.md serves as a high-level overview, index, and executive summary.
• Deep technical specifics, raw configs, step-by-step commands, and architectural deep-dives belong in their respective docs/ subdirectories.
• Avoid duplicating long configuration files across multiple documents. Use cross-references (e.g., [LXC Permissions](../storage/lxc-permissions.md)).

2. When to Update Which Document

Action / Event	Document(s) to Update
New VM or LXC created / migrated	docs/services/container-inventory.md, root README.md (if core node role changes)
Docker Compose stack modified / added	docs/services/container-inventory.md & repository stack directory (docker-*/)
Physical drive added, replaced, or degraded	docs/storage/storage-map.md, docs/storage/zfs-tank.md
Network IP, bond, or MAC changed	docs/architecture/networking.md, docs/architecture/cluster-nodes.md
Storage mount, export, or ACL modified	docs/storage/lxc-permissions.md, docs/runbooks/universal-media-storage.md
New maintenance or recovery procedure	Create a new runbook under docs/runbooks/<procedure-name>.md

3. Documentation Style & Formatting Rules

• Markdown Links: Use relative markdown links between docs (e.g., [Storage Map](../storage/storage-map.md) or [Root README](../../README.md)).
• Admonitions / Alerts: Use standard GitHub alerts (> [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]) to highlight critical operational policies or failure traps.
• Commands & Code Blocks: Always specify language flags on fenced code blocks (e.g. bash, yaml, ini, udev, text). Include clear comments explaining critical flags.
• Hardware & Network Specifics: Keep serial numbers, WWNs, MAC addresses, device paths, and network interface names accurate and updated.
• Visuals: Use Mermaid diagrams (mermaid) where workflow or topology clarification is beneficial.