feat: Add professional hierarchical documentation

- Created comprehensive README.md with Mermaid diagrams, badges, and TOC
- Added docs/ directory with 7 sections and 14 markdown files
- Included architecture diagrams, flowcharts, and sequence diagrams
- All documentation is fully interlinked with cross-references
- Added ISO storage location on Proxmox development server
- Included troubleshooting guide and evaluation management docs
- All config files (Packer, Terraform, Ansible, Forgejo) documented
- Added icons and visual elements throughout documentation

docs/04-terraform/variables.md

@@ -0,0 +1,158 @@
+# 📊 Terraform Variables
+
+[![Terraform](https://img.shields.io/badge/Terraform-OpenTofu-green?style=flat&logo=terraform)](https://opentofu.org/)
+
+## Overview
+
+This document details all input variables for the OpenTofu configuration.
+
+---
+
+## Variables File
+
+**File:** [`terraform/variables.tf`](../../terraform/variables.tf)
+
+```hcl
+variable "build_id" {
+  description = "Unique identifier for the build"
+  type        = string
+}
+
+variable "template_vm_id" {
+  description = "VM ID of the Packer-built template"
+  type        = number
+  default     = 9000
+}
+```
+
+---
+
+## Variable Details
+
+### build_id
+
+| Property | Value |
+|----------|-------|
+| Description | Unique identifier for the build |
+| Type | String |
+| Required | Yes |
+| Example | `"2024-02-06-001"` |
+
+**Purpose:** Creates unique VM names for each pipeline run, enabling parallel builds and preventing naming conflicts.
+
+```hcl
+# Generated VM name
+name = "ci-win-build-${var.build_id}"
+# Example: ci-win-build-2024-02-06-001
+```
+
+### template_vm_id
+
+| Property | Value |
+|----------|-------|
+| Description | VM ID of the Packer-built template |
+| Type | Number |
+| Default | `9000` |
+| Required | No |
+
+**Purpose:** Specifies which template to clone when provisioning VMs.
+
+```hcl
+# Default value
+vm_id = 9000
+
+# Custom value
+vm_id = var.template_vm_id
+```
+
+---
+
+## Setting Variables
+
+### Method 1: Environment Variables
+
+```bash
+export TF_VAR_build_id="123"
+export TF_VAR_template_vm_id="9000"
+tofu plan
+```
+
+### Method 2: tfvars File
+
+Create `terraform/terraform.tfvars`:
+
+```hcl
+build_id       = "2024-02-06-001"
+template_vm_id = 9000
+```
+
+### Method 3: Command Line
+
+```bash
+tofu apply -var="build_id=123" -var="template_vm_id=9000"
+```
+
+---
+
+## Sensitive Variables
+
+| Variable | Sensitive | Reason |
+|----------|-----------|--------|
+| `build_id` | No | Public identifier |
+| `template_vm_id` | No | Configuration value |
+
+**Note:** Proxmox credentials are passed via environment variables, not variables file:
+- `PM_API_TOKEN_ID`
+- `PM_API_TOKEN_SECRET`
+
+---
+
+## Variable Validation
+
+```hcl
+variable "build_id" {
+  description = "Unique identifier for the build"
+  type        = string
+  
+  validation {
+    condition     = can(regex("^[a-zA-Z0-9-_]+$", var.build_id))
+    error_message = "build_id must contain only alphanumeric characters, hyphens, and underscores."
+  }
+}
+
+variable "template_vm_id" {
+  description = "VM ID of the Packer-built template"
+  type        = number
+  
+  validation {
+    condition     = var.template_vm_id >= 100 && var.template_vm_id <= 999999
+    error_message = "template_vm_id must be a valid VM ID (100-999999)."
+  }
+}
+```
+
+---
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| ✅ Use descriptive names | `build_id` vs `id` |
+| ✅ Set defaults | Provide safe defaults where possible |
+| ✅ Add validation | Prevent invalid configurations |
+| ✅ Document all variables | Clear description for each |
+| ✅ Use type constraints | Enforce correct data types |
+
+---
+
+## Next Steps
+
+| Goal | Next Document |
+|------|---------------|
+| View main.tf | [OpenTofu Resources](main.tf.md) |
+| Run provisioning | Apply Terraform configuration |
+| View Ansible | [Ansible Pipeline](../05-ansible/pipeline.md) |
+
+---
+
+[← Documentation Index](../index.md) | [← OpenTofu Resources](main.tf.md) | [→ Ansible Pipeline](../05-ansible/pipeline.md)