# 📖 Documentation Index

<!-- Badges -->
[![Pipeline](https://img.shields.io/badge/Pipeline-Packer%20→%20OpenTofu%20→%20Forgejo-blue)](.forgejo/workflows/release.yml)
[![Windows](https://img.shields.io/badge/Windows-11%20LTSC%202024-0078D6?style=flat&logo=windows)](https://www.microsoft.com/en-us/windows/windows-11-enterprise)

## Welcome

This is the comprehensive documentation index for the **Windows Automation on Proxmox** project. Use this guide to navigate through all available documentation.

---

## 🗂️ Documentation Map

```
┌─────────────────────────────────────────────────────────────────┐
│                     DOCUMENTATION TREE                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  📄 index.md (You are here)                                    │
│     ├── 📁 01-overview/                                        │
│     │    └── 📄 architecture.md                                 │
│     │         ├── System Components                            │
│     │         ├── Architecture Diagrams                         │
│     │         └── Design Decisions                             │
│     │                                                     │
│     ├── 📁 02-prerequisites/                                   │
│     │    ├── 📄 isos.md                                       │
│     │    │    ├── ISO Download Sources                         │
│     │    │    ├── Storage Location                             │
│     │    │    └── Verification Steps                           │
│     │    │                                              │
│     │    └── 📄 secrets.md                                      │
│     │         ├── Forgejo Secrets                              │
│     │         ├── Proxmox API Tokens                           │
│     │         └── Certificate Management                        │
│     │                                                     │
│     ├── 📁 03-packer/                                          │
│     │    ├── 📄 configuration.md                               │
│     │    │    ├── Packer HCL Syntax                            │
│     │    │    ├── Proxmox Builder Settings                     │
│     │    │    └── Provisioner Configuration                     │
│     │    │                                              │
│     │    └── 📄 autounattend.md                                 │
│     │         ├── XML Structure                                │
│     │         ├── WinRM Configuration                          │
│     │         └── FirstLogonCommands                           │
│     │                                                     │
│     ├── 📁 04-terraform/                                       │
│     │    ├── 📄 main.tf.md                                      │
│     │    │    ├── Provider Configuration                        │
│     │    │    ├── VM Resource Definition                        │
│     │    │    └── Clone Strategy                                │
│     │    │                                              │
│     │    └── 📄 variables.md                                    │
│     │         ├── Input Variables                              │
│     │         └── Variable Validation                          │
│     │                                                     │
│     ├── 📁 05-ansible/                                          │
│     │    └── 📄 pipeline.md                                     │
│     │         ├── Playbook Structure                           │
│     │         ├── WinRM Setup                                  │
│     │         └── Verification Tasks                           │
│     │                                                     │
│     ├── 📁 06-ci-cd/                                            │
│     │    └── 📄 forgejo-workflows.md                            │
│     │         ├── Workflow Syntax                               │
│     │         ├── Container Configuration                       │
│     │         ├── Step-by-Step Execution                       │
│     │         └── Environment Variables                        │
│     │                                                     │
│     └── 📁 07-advanced/                                         │
│          ├── 📄 evaluation.md                                   │
│          │    ├── 90-Day Timer Management                       │
│          │    ├── Rearm Procedure                               │
│          │    └── Monthly Rebuild Strategy                      │
│          │                                                 │
│          └── 📄 troubleshooting.md                              │
│               ├── Common Errors                                 │
│               ├── Debug Techniques                             │
│               └── FAQ                                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 🎯 Quick Navigation

### I want to...

| Goal | Start Here |
|------|------------|
| **Understand the system** | [Architecture Overview](01-overview/architecture.md) |
| **Set up prerequisites** | [ISO Requirements](02-prerequisites/isos.md) |
| **Build the golden image** | [Packer Configuration](03-packer/configuration.md) |
| **Provision test VMs** | [OpenTofu Resources](04-terraform/main.tf.md) |
| **Run the CI/CD pipeline** | [Forgejo Workflows](06-ci-cd/forgejo-workflows.md) |
| **Troubleshoot issues** | [Troubleshooting Guide](07-advanced/troubleshooting.md) |

---

## 📊 Architecture Overview

```mermaid
graph TD
    subgraph CI["Forgejo CI/CD"]
        direction LR
        Git[Git Push] --> |Triggers| WF[Workflow]
        WF --> |Cross-Compile| MC[MinGW]
        WF --> |Package| NS[NSIS]
        WF --> |Sign| CS[Code Sign]
    end
    
    subgraph Infra["Infrastructure"]
        CS --> |Provision| TF[OpenTofu]
        TF --> |Clone| VM[Windows VM]
    end
    
    subgraph Test["Testing"]
        VM --> |Deploy| Inst[Installer]
        Inst --> |Verify| Ans[Ansible]
        Ans --> |Result| Pass{✅ Pass}
        Ans --> |Result| Fail{❌ Fail}
    end
    
    style CI fill:#e1f5fe
    style Infra fill:#e8f5e9
    style Test fill:#fff3e0
```

---

## 📚 Section Descriptions

### 01. Overview
- **[architecture.md](01-overview/architecture.md)** - Complete system design including:
  - Component overview
  - Data flow diagrams
  - Design decisions and rationale
  - Technology stack explanation

### 02. Prerequisites
- **[isos.md](02-prerequisites/isos.md)** - ISO image requirements:
  - Download links for Windows ISOs
  - VirtIO driver sources
  - Proxmox storage configuration
  - File verification steps
- **[secrets.md](02-prerequisites/secrets.md)** - Credential management:
  - Forgejo secret configuration
  - Proxmox API token creation
  - Code signing certificate handling
  - Environment variable mapping

### 03. Packer
- **[configuration.md](03-packer/configuration.md)** - Packer template guide:
  - HCL syntax reference
  - Proxmox builder settings
  - Hardware configuration
  - Provisioner scripts
- **[autounattend.md](03-packer/autounattend.md)** - Windows无人值守安装:
  - XML structure reference
  - WinRM enabling
  - Firewall configuration
  - FirstLogonCommands详解

### 04. Terraform/OpenTofu
- **[main.tf.md](04-terraform/main.tf.md)** - Infrastructure as code:
  - Provider configuration
  - VM cloning strategy
  - Network settings
  - IP address assignment
- **[variables.md](04-terraform/variables.md)** - Variables reference:
  - Input variable definitions
  - Default values
  - Variable validation
  - Sensitive value handling

### 05. Ansible
- **[pipeline.md](05-ansible/pipeline.md)** - Automation playbook:
  - WinRM connection setup
  - File transfer tasks
  - Silent installation
  - Verification assertions
  - Error handling

### 06. CI/CD
- **[forgejo-workflows.md](06-ci-cd/forgejo-workflows.md)** - Pipeline configuration:
  - Workflow syntax
  - Container images
  - Step-by-step execution
  - Artifact publishing
  - Cleanup procedures

### 07. Advanced
- **[evaluation.md](07-advanced/evaluation.md)** - Evaluation management:
  - 90-day expiration explained
  - Rearm procedure
  - Automated rebuild strategy
  - Security considerations
- **[troubleshooting.md](07-advanced/troubleshooting.md)** - Problem resolution:
  - Common error messages
  - Debug commands
  - Log file locations
  - FAQ section

---

## 🔗 Cross-References

This documentation is fully interlinked. Key cross-references include:

| From | To | Context |
|------|-----|---------|
| README | docs/index.md | Documentation entry |
| architecture.md | isos.md | Prerequisites section |
| configuration.md | autounattend.md | Related Packer topics |
| main.tf.md | variables.md | Terraform variables |
| forgejo-workflows.md | pipeline.md | Ansible integration |
| pipeline.md | main.tf.md | Infrastructure reference |
| troubleshooting.md | All sections | Problem resolution |

---

## 🛠️ Tool Reference

| Tool | Version | Purpose | Docs Link |
|------|---------|---------|-----------|
| Packer | ≥ 1.1.0 | Image building | [configuration.md](03-packer/configuration.md) |
| OpenTofu | Latest | IaC provisioning | [main.tf.md](04-terraform/main.tf.md) |
| Ansible | Latest | Automation | [pipeline.md](05-ansible/pipeline.md) |
| Forgejo Actions | Latest | CI/CD | [forgejo-workflows.md](06-ci-cd/forgejo-workflows.md) |
| MinGW | Latest | Cross-compilation | [forgejo-workflows.md](06-ci-cd/forgejo-workflows.md) |
| NSIS | Latest | Installer creation | [forgejo-workflows.md](06-ci-cd/forgejo-workflows.md) |

---

## 📖 Reading Guide

1. **First Time Setup:** Read in order: 01 → 02 → 03 → 04 → 05 → 06
2. **Specific Task:** Use the Quick Navigation table above
3. **Deep Dive:** Follow cross-references from any section
4. **Troubleshooting:** Start with [troubleshooting.md](07-advanced/troubleshooting.md)

---

## 🔄 Document Version

| Property | Value |
|----------|-------|
| Version | 1.0.0 |
| Last Updated | February 2026 |
| Target OS | Windows 11 LTSC 2024 |
| Status | Active Development |

---

[← Back to README](../README.md) | [→ Architecture Overview](01-overview/architecture.md)