Restructure infra repo into documentation-first homelab platform

.github/ISSUE_TEMPLATE/decision.yml

@@ -0,0 +1,33 @@
+name: Decision
+description: Propose a significant architecture or process decision.
+title: "decision: <topic>"
+labels:
+  - decision
+body:
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What context drives this decision?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed decision
+      description: What do you propose and why?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: textarea
+    id: consequences
+    attributes:
+      label: Consequences
+  - type: input
+    id: adr_link
+    attributes:
+      label: ADR link (if created)
+      placeholder: docs/decisions/ADR-xxx-...md

.github/ISSUE_TEMPLATE/epic.yml

@@ -0,0 +1,34 @@
+name: Epic
+description: Track a multi-task initiative.
+title: "epic: <initiative name>"
+labels:
+  - epic
+body:
+  - type: textarea
+    id: objective
+    attributes:
+      label: Objective
+      description: What outcome does this epic deliver?
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: Why this work matters now.
+  - type: textarea
+    id: milestones
+    attributes:
+      label: Milestones
+      placeholder: |
+        - Mx: ...
+  - type: textarea
+    id: child_tasks
+    attributes:
+      label: Child tasks
+      placeholder: |
+        - [ ] #123 ...
+  - type: textarea
+    id: risks
+    attributes:
+      label: Risks and unknowns

.github/ISSUE_TEMPLATE/task.yml

@@ -0,0 +1,36 @@
+name: Task
+description: Track a focused implementation or documentation task.
+title: "task: <short description>"
+labels:
+  - task
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What needs to be done?
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope
+      description: In-scope and out-of-scope boundaries.
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Define done.
+      placeholder: |
+        - [ ] ...
+        - [ ] ...
+    validations:
+      required: true
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies / blockers
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes

.github/pull_request_template.md

@@ -0,0 +1,26 @@
+## Summary
+
+- What changed?
+- Why was it needed?
+
+## What to review first
+
+- Primary entry points for reviewers:
+  - 
+
+## Restructuring and archive notes
+
+- What was restructured:
+- What legacy content was archived:
+- Any redactions performed for safety:
+
+## TODOs intentionally left open
+
+- TODO:
+- TODO:
+
+## Validation
+
+- [ ] Documentation paths and links checked
+- [ ] No secrets/credentials added
+- [ ] ADR/backlog/roadmap updates included if needed

README.md

@@ -0,0 +1,79 @@
+# Homelab Infrastructure (Documentation-First)
+
+This repository is the planning and execution hub for a homelab/platform build centered on:
+
+- **Proxmox-first virtualization**
+- **Virtualized Kubernetes inside Proxmox**
+- **Argo CD for GitOps**
+- **TrueNAS as a separate storage anchor**
+- A path toward **self-hosted AI/agent platform capabilities**
+
+The previous bare-metal Talos/PXE implementation is preserved in `docs/archive/legacy-baremetal-talos-pxe/` for historical reference and is **not** the current primary direction.
+
+## Current architecture direction
+
+- Main compute: 3x Minisforum MS-A2 (96 GB RAM each, 10GbE)
+- Core platform direction: Proxmox cluster first, then Kubernetes as VMs
+- GitOps direction: Argo CD preferred over Flux
+- Storage: separate TrueNAS system
+- Network foundation: Ubiquiti stack (Cloud Gateway Fiber, Pro XG 8 PoE, Lite 16 PoE)
+
+Where details are not finalized, this repository uses explicit `TODO` markers rather than assumptions.
+
+## Repository structure
+
+```text
+docs/
+  vision/         # North-star goals and intent
+  inventory/      # Hardware, network, and service inventory
+  architecture/   # Target architecture and security/network models
+  decisions/      # ADRs (architecture decision records)
+  runbooks/       # Operational procedures
+  roadmap/        # Milestones, backlog, current phase
+  archive/        # Legacy direction and historical references
+proxmox/          # Proxmox planning/implementation docs and artifacts
+kubernetes/       # Kubernetes cluster design and implementation docs
+argocd/           # Argo CD bootstrap and app-of-apps patterns
+automation/       # Automation plans/scripts conventions
+ai/               # Future AI platform direction and experiments
+scripts/          # Safe utility scripts (no secrets)
+.github/          # GitHub issue/PR templates and project workflow docs
+```
+
+## Current phase
+
+See: `docs/roadmap/current-phase.md`.
+
+At time of this restructuring, the project is in **Foundation / Repository Realignment**.
+
+## How decisions are recorded
+
+Architectural decisions are documented as ADRs in `docs/decisions/`.
+
+Each ADR follows:
+- Title
+- Status
+- Context
+- Decision
+- Alternatives considered
+- Consequences
+
+## How work is tracked
+
+- Use GitHub Issues with templates in `.github/ISSUE_TEMPLATE/`
+- Track larger streams via epics and milestones
+- Use pull requests with `.github/pull_request_template.md`
+
+## How to navigate docs
+
+1. Start with `docs/vision/homelab-vision.md`
+2. Review current state in `docs/inventory/`
+3. Read target direction in `docs/architecture/`
+4. Check ADRs in `docs/decisions/`
+5. Use `docs/runbooks/bootstrap-sequence.md` for sequencing
+6. Follow execution in `docs/roadmap/`
+
+## Notes on sensitive data
+
+Do not commit live secrets, tokens, credentials, private domains, or operationally sensitive values.
+Use redacted examples with `TODO` placeholders where needed.

ai/README.md

@@ -0,0 +1,5 @@
+# AI Platform
+
+Future-facing workstream for self-hosted AI and agent platform capabilities.
+
+TODO: Define requirements, constraints, and initial pilot architecture.

argocd/README.md

@@ -0,0 +1,5 @@
+# Argo CD
+
+GitOps bootstrap and application management patterns for Kubernetes environments.
+
+TODO: Add bootstrap sequence, repo layout conventions, and access model.

automation/README.md

@@ -0,0 +1,5 @@
+# Automation
+
+Automation conventions and implementation plans.
+
+Keep scripts deterministic, documented, and free of secrets.

docs/README.md

@@ -0,0 +1,9 @@
+# Documentation Index
+
+- `vision/`: project direction and principles
+- `inventory/`: current known hardware/network/service/media state
+- `architecture/`: target design drafts and constraints
+- `decisions/`: ADRs
+- `runbooks/`: operational sequencing
+- `roadmap/`: milestones, backlog, current phase
+- `archive/`: legacy/superseded materials

docs/architecture/media-platform.md

@@ -0,0 +1,26 @@
+# Media Platform Architecture
+
+## Current state
+
+- Docker Compose media stack runs in a Proxmox VM.
+- Storage is NFS-backed from TrueNAS.
+- Plex currently uses NVIDIA-backed transcoding.
+
+## Future state (under evaluation)
+
+The final media platform design remains open.
+Current evaluation tracks:
+
+1. Plex vs Jellyfin vs Emby
+2. Media workloads on TrueNAS vs dedicated media VM
+3. Operational and backup model for media services
+
+## Design guardrail
+
+Keep media platform evolution separate from core lab control-plane reliability work.
+
+## TODOs
+
+- TODO: Define migration criteria (downtime tolerance, performance, maintainability).
+- TODO: Define decision timeline and ADR trigger points.
+- TODO: Define target observability for media workloads.

docs/architecture/network-topology.md

@@ -0,0 +1,21 @@
+# Network Topology (Draft)
+
+## Known topology anchors
+
+- Ubiquiti Cloud Gateway Fiber (gateway/routing role)
+- Ubiquiti Pro XG 8 PoE and Lite 16 PoE (switching fabric)
+- 10GbE-capable Proxmox compute nodes
+- Separate TrueNAS system
+
+## Target segmentation intent
+
+- Separate management/control traffic from workload traffic.
+- Ensure storage access paths are explicit and observable.
+- Keep externally exposed services constrained and auditable.
+
+## TODOs
+
+- TODO: Define VLAN layout and naming.
+- TODO: Define subnet and addressing model.
+- TODO: Define north-south ingress model for Kubernetes services.
+- TODO: Define east-west policy posture between major service zones.

docs/architecture/proxmox-k8s-strategy.md

@@ -0,0 +1,23 @@
+# Proxmox + Kubernetes Strategy
+
+## Strategy statement
+
+Build and stabilize Proxmox first, then deploy an initial Kubernetes cluster as VMs to accelerate platform learning while retaining infrastructure flexibility.
+
+## Why this approach
+
+- Faster iteration than immediate bare-metal Kubernetes rebuild.
+- Better isolation between host virtualization and guest orchestration concerns.
+- Easier phased migration of workloads and operational practices.
+
+## Implementation themes
+
+- Standardized VM templates for Kubernetes nodes.
+- Repeatable cluster bootstrap process (document first, automate next).
+- Clear separation of management, workload, and storage networking (details TODO).
+
+## TODOs
+
+- TODO: Define Kubernetes distro selection criteria.
+- TODO: Define control-plane and worker VM sizing profile.
+- TODO: Define day-2 operations model (upgrade cadence, patch windows).

docs/architecture/security-model.md

@@ -0,0 +1,21 @@
+# Security Model (Baseline)
+
+## Principles
+
+- Least privilege for identities, credentials, and network access.
+- Secret hygiene: no live secrets in repo.
+- Explicit trust boundaries between host, cluster, storage, and edge access.
+
+## Baseline controls
+
+- Git-based change review via pull requests.
+- ADR-backed architectural changes.
+- Segmented networks (details pending).
+- Prefer short-lived credentials and secure secret delivery patterns.
+
+## TODOs
+
+- TODO: Define secret management strategy for Proxmox/Kubernetes/Argo CD.
+- TODO: Define identity provider and RBAC model.
+- TODO: Define backup encryption and key handling practices.
+- TODO: Define minimum logging/auditing standards.

docs/architecture/target-architecture.md

@@ -0,0 +1,21 @@
+# Target Architecture (Working Draft)
+
+## High-level model
+
+1. Proxmox cluster provides virtualization and lifecycle management.
+2. Kubernetes runs inside Proxmox-hosted VMs.
+3. Argo CD manages Kubernetes desired state from Git.
+4. TrueNAS remains a separate storage/media anchor.
+5. Media platform remains logically separate from core platform control services.
+
+## Design constraints
+
+- Prefer incremental migration over all-at-once rebuilds.
+- Keep storage and media concerns decoupled from cluster control plane.
+- Use documentation and ADRs to reduce architectural drift.
+
+## TODOs
+
+- TODO: Define availability goals for each platform layer.
+- TODO: Define backup and disaster recovery boundaries.
+- TODO: Define observability baseline (metrics/logs/traces/events).

docs/archive/README.md

@@ -0,0 +1,5 @@
+# Archive
+
+This directory stores historical or superseded materials kept for reference.
+
+Archived content is not the active implementation path unless explicitly re-adopted via ADR.

docs/archive/legacy-baremetal-talos-pxe/README.md

@@ -0,0 +1,17 @@
+# Legacy: Bare-Metal Talos/PXE Direction
+
+This directory captures a **previous platform direction** focused on bare-metal Talos cluster deployment via PXE/Terraform-style workflows.
+
+## Archive intent
+
+- Preserved for historical/reference purposes.
+- Useful for extracting reusable ideas, patterns, or scripts.
+- **Not** the current primary architecture direction for this repository.
+
+## Current primary direction
+
+See top-level `README.md` and `docs/architecture/` for the active Proxmox-first, virtualized-Kubernetes approach.
+
+## Safety note
+
+Some legacy files may have been redacted during archival to avoid retaining environment-specific sensitive values.