Restructure repo to docs-first Proxmox homelab platform and archive legacy Talos/PXE

.github/ISSUE_TEMPLATE/decision.yml

@@ -0,0 +1,34 @@
+name: Decision Record Proposal
+description: Propose or revise an architecture decision
+labels: [decision]
+body:
+  - type: input
+    id: adr
+    attributes:
+      label: Proposed ADR ID/Title
+      placeholder: ADR-00X - Title
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What problem or tradeoff is being addressed?
+    validations:
+      required: true
+  - type: textarea
+    id: options
+    attributes:
+      label: Options Considered
+    validations:
+      required: true
+  - type: textarea
+    id: recommendation
+    attributes:
+      label: Recommendation
+    validations:
+      required: true
+  - type: textarea
+    id: consequences
+    attributes:
+      label: Expected Consequences

.github/ISSUE_TEMPLATE/epic.yml

@@ -0,0 +1,27 @@
+name: Epic
+description: Track a multi-step initiative with multiple issues
+labels: [epic]
+body:
+  - type: textarea
+    id: objective
+    attributes:
+      label: Objective
+      description: What larger outcome does this epic deliver?
+    validations:
+      required: true
+  - type: textarea
+    id: milestones
+    attributes:
+      label: Milestones
+      placeholder: |
+        - [ ] M1 ...
+        - [ ] M2 ...
+  - type: textarea
+    id: child_issues
+    attributes:
+      label: Child Issues
+      description: Link planned tasks
+  - type: textarea
+    id: risks
+    attributes:
+      label: Risks / Unknowns

.github/ISSUE_TEMPLATE/task.yml

@@ -0,0 +1,31 @@
+name: Task
+description: Track a concrete, reviewable unit of work
+title: "[Task] "
+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: What is in scope and out of scope?
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance Criteria
+      description: What conditions indicate completion?
+      placeholder: |
+        - [ ] ...
+        - [ ] ...
+    validations:
+      required: true
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies / Blockers

.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## Summary
+
+- What was changed?
+- Why was it changed?
+
+## What was restructured
+
+- 
+
+## What was archived
+
+- 
+
+## New docs added
+
+- 
+
+## Intentional TODOs / unknowns
+
+- 
+
+## Review order
+
+1. `README.md`
+2. `docs/vision/`
+3. `docs/architecture/`
+4. `docs/decisions/`
+5. `docs/roadmap/`

README.md

@@ -0,0 +1,64 @@
+# Homelab Infrastructure (Documentation-First)
+
+This repository is the planning, architecture, and operations source of truth for a homelab platform pivoting to a **Proxmox-first** model with:
+
+- Virtualized Kubernetes running inside Proxmox
+- Argo CD for GitOps
+- TrueNAS as a separate storage/media anchor
+- A documented path toward future AI/agent platform capabilities
+
+## Current Direction
+
+The prior bare-metal Talos/PXE direction is now treated as legacy reference material. The active path is:
+
+1. Stabilize documentation and inventory
+2. Build/validate Proxmox platform foundations
+3. Stand up Kubernetes in VMs on Proxmox
+4. Bootstrap Argo CD and GitOps workflows
+5. Incrementally migrate/support media and future AI workloads
+
+## Repository Structure
+
+- `docs/vision/` - mission, goals, and operating principles
+- `docs/inventory/` - hardware, network, and service inventories
+- `docs/architecture/` - target architecture and strategy documents
+- `docs/decisions/` - ADRs (architecture decision records)
+- `docs/runbooks/` - operational bootstrap and procedures
+- `docs/roadmap/` - milestones, backlog, and current phase
+- `docs/archive/` - preserved legacy material
+- `proxmox/` - Proxmox-specific implementation notes/artifacts
+- `kubernetes/` - Kubernetes platform design/implementation notes
+- `argocd/` - Argo CD bootstrap and app-of-apps patterns
+- `automation/` - automation workflow notes/scripts
+- `ai/` - future AI/agent platform planning
+- `scripts/` - helper scripts used by docs/runbooks
+- `.github/` - issue and PR templates for GitHub-native planning
+
+## Current Phase
+
+See `docs/roadmap/current-phase.md` for the active phase and near-term focus.
+
+## How Decisions Are Recorded
+
+Architectural decisions are captured as ADRs in `docs/decisions/` using a consistent format:
+
+- Title
+- Status
+- Context
+- Decision
+- Alternatives considered
+- Consequences
+
+## How Work Is Tracked
+
+- Use GitHub Issues with templates in `.github/ISSUE_TEMPLATE/`
+- Use PR review for implementation changes
+- Keep roadmap and backlog updated under `docs/roadmap/`
+
+## Start Here
+
+1. `docs/vision/homelab-vision.md`
+2. `docs/inventory/hardware-inventory.md`
+3. `docs/architecture/target-architecture.md`
+4. `docs/decisions/ADR-001-proxmox-first.md`
+5. `docs/runbooks/bootstrap-sequence.md`

ai/README.md

@@ -0,0 +1,3 @@
+# AI Area
+
+Future self-hosted AI and agent platform planning artifacts belong here.

argocd/README.md

@@ -0,0 +1,8 @@
+# Argo CD Area
+
+Argo CD bootstrap and GitOps structure artifacts belong here.
+
+## TODO
+
+- Add Argo CD bootstrap plan
+- Add initial app-of-apps repository pattern notes

automation/README.md

@@ -0,0 +1,3 @@
+# Automation Area
+
+Automation workflows and supporting assets for this repo belong here.

docs/architecture/media-platform.md

@@ -0,0 +1,27 @@
+# Media Platform Architecture (Current + Future)
+
+## Current State
+
+- Media stack runs as Docker Compose inside a Proxmox VM.
+- Includes Plex plus supporting media ecosystem services.
+- Uses NFS-mounted media storage from TrueNAS.
+- Uses NVIDIA-backed Plex transcoding in current deployment.
+
+## Position in Overall Platform
+
+- Media is important but remains a separate domain from core platform modernization.
+- Core lab platform work (Proxmox, Kubernetes, Argo CD) should not be blocked by unresolved media end-state decisions.
+
+## Future State (Under Evaluation)
+
+Open questions:
+
+- Preferred media server platform (Plex vs Jellyfin vs Emby)
+- Runtime location (apps directly on TrueNAS vs dedicated media VM)
+- Long-term operational model and migration phasing
+
+## TODO
+
+- TODO: Build decision matrix for media server/runtime options.
+- TODO: Define migration guardrails and rollback strategy.
+- TODO: Identify which services remain VM-native vs move to other runtime models.

docs/architecture/network-topology.md

@@ -0,0 +1,22 @@
+# Network Topology
+
+## Current Known Components
+
+- Ubiquiti Cloud Gateway Fiber
+- Ubiquiti Pro XG 8 PoE
+- Ubiquiti Lite 16 PoE
+- Three MS-A2 compute nodes (10GbE)
+- Separate TrueNAS storage node
+
+## Target Topology Intent
+
+- Isolate management and workload concerns where practical.
+- Preserve clear path for storage traffic between compute and TrueNAS.
+- Support VM-based Kubernetes networking without overcomplicating initial rollout.
+
+## TODO
+
+- TODO: Produce canonical topology diagram.
+- TODO: Define management network, workload network, and storage network boundaries.
+- TODO: Define VLAN IDs and subnet/IP plan.
+- TODO: Define baseline firewall and east-west controls.

docs/architecture/proxmox-k8s-strategy.md

@@ -0,0 +1,24 @@
+# Proxmox + Kubernetes Strategy
+
+## Strategy Statement
+
+Use Proxmox as the primary platform substrate, then deploy Kubernetes as virtualized nodes to improve flexibility, isolation, and recoverability compared to direct bare-metal coupling.
+
+## Why This Approach
+
+- Faster platform iteration via VM-level change management
+- Cleaner separation between host lifecycle and Kubernetes lifecycle
+- Easier experimentation for future platform domains
+
+## Proposed Sequence
+
+1. Validate Proxmox host readiness and cluster plan.
+2. Define Kubernetes VM topology and bootstrap path.
+3. Bring up a baseline Kubernetes cluster in Proxmox.
+4. Bootstrap Argo CD and transition app delivery to GitOps.
+
+## TODO
+
+- TODO: Select Kubernetes provisioning method (e.g., kubeadm, Talos-in-VM, other).
+- TODO: Define VM networking mode(s) and failure domain expectations.
+- TODO: Document etcd/control-plane resilience targets.

docs/architecture/security-model.md

@@ -0,0 +1,20 @@
+# Security Model (Initial)
+
+## Principles
+
+- Least privilege access for platform administration
+- Separation of management, data, and workload planes where possible
+- Secrets managed outside plaintext repo content
+- Change tracking through PR review and ADR records
+
+## Controls (Planned)
+
+- GitHub PR-based review for platform changes
+- Explicit ADR decisions for major architectural/security tradeoffs
+- Redaction of sensitive environment details in shared docs
+
+## TODO
+
+- TODO: Define identity and access model for Proxmox/TrueNAS/Kubernetes.
+- TODO: Define secrets management pattern for GitOps workflows.
+- TODO: Define baseline backup, restore, and incident response procedure.

docs/architecture/target-architecture.md

@@ -0,0 +1,24 @@
+# Target Architecture (Planned)
+
+## High-Level Direction
+
+1. **Proxmox-first virtualization layer** on the three MS-A2 hosts
+2. **Virtualized Kubernetes cluster** hosted in Proxmox VMs
+3. **Argo CD GitOps control plane** for Kubernetes applications
+4. **TrueNAS as separate storage anchor** for shared storage/media
+5. **Media platform as separate concern** from core platform modernization
+6. **Future AI/agent capabilities** built after platform foundations stabilize
+
+## Logical Layers
+
+- **Layer 1: Physical + network** (power, switching, routing)
+- **Layer 2: Virtualization** (Proxmox cluster and host operations)
+- **Layer 3: Container platform** (Kubernetes in VMs)
+- **Layer 4: GitOps & app delivery** (Argo CD)
+- **Layer 5: Workload domains** (core apps, media, future AI)
+
+## TODO
+
+- TODO: Define initial control-plane and worker VM sizing assumptions.
+- TODO: Define storage class strategy for Kubernetes workloads.
+- TODO: Define ingress/DNS/TLS standards for platform services.

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

@@ -0,0 +1,19 @@
+# Legacy Archive: Bare-Metal Talos/PXE Direction
+
+This archive contains material from a **previous platform direction** focused on bare-metal Talos provisioning through PXE and Terraform/OpenTofu-style workflows.
+
+## Archive Intent
+
+- Preserve historical implementation/reference context
+- Keep Git history and prior work accessible
+- Avoid presenting this as the active platform path
+
+## Current Status
+
+- This is **not** the current primary direction.
+- The active direction is documentation-first, Proxmox-first, virtualized Kubernetes, and Argo CD GitOps.
+
+## Notes
+
+- Some legacy files may contain environment-specific values from past operations.
+- Treat archived content as reference only; do not assume it reflects current standards.

docs/archive/legacy-baremetal-talos-pxe/infra-legacy/live/prod/terraform.auto.tfvars

@@ -0,0 +1,28 @@
+# REDACTED LEGACY EXAMPLE
+#
+# This file preserves the structure of the previous environment-specific tfvars
+# while removing private operational values.
+
+cluster_nodes = {
+  nx0 = {
+    hostname        = "<redacted-hostname>"
+    ip              = "<redacted-ip>"
+    mac_address     = "<redacted-mac>"
+    wake_on_lan_mac = "<redacted-mac>"
+    install_disk    = "<redacted-disk>"
+    role            = "controlplane"
+    bootstrap       = true
+  }
+}
+
+cluster_info = {
+  name        = "<redacted-cluster-name>"
+  nameservers = ["<redacted-ns-ip>"]
+  virtual_ip  = "<redacted-vip>"
+  endpoint    = "https://<redacted-endpoint>:6443"
+}
+
+k8s_version = "<redacted-k8s-version>"
+
+github_organization = "<redacted-org>"
+github_repository   = "<redacted-repo>"

docs/decisions/ADR-001-proxmox-first.md

@@ -0,0 +1,19 @@
+# ADR-001: Proxmox-First Infrastructure Direction
+
+## Status
+Accepted
+
+## Context
+The repository previously centered on a bare-metal Talos/PXE provisioning path. Current goals prioritize virtualization flexibility, operational clarity, and staged modernization.
+
+## Decision
+Adopt Proxmox as the primary infrastructure foundation for current and near-term homelab operations.
+
+## Alternatives considered
+- Continue bare-metal Talos/PXE as primary path
+- Mixed ad-hoc host virtualization without cluster-level direction
+
+## Consequences
+- Requires Proxmox cluster planning and host lifecycle runbooks.
+- Enables cleaner layering for Kubernetes and future workloads.
+- Legacy bare-metal workflows move to archive/reference status.