docs: add comprehensive BOOTSTRAP.md guide for manual initialization

BOOTSTRAP.md

@@ -0,0 +1,52 @@
+# Bootstrap Guide
+
+This document outlines the manual, real-world steps required to initialize the NixOS GitOps environment for the first time. You must perform these steps before the CI/CD pipeline or any automated staging environments can function.
+
+## 1. Secret Management Initialization (SOPS-Nix)
+
+We use `sops-nix` to manage secrets, adhering to a strict separation between Production and Staging. You must generate these keys locally on a secure workstation.
+
+**Prerequisites:** Install `age` ([age documentation](https://github.com/FiloSottile/age)).
+
+1. **Generate the Production Master Key:**
+   ```bash
+   age-keygen -o prod-master.txt
+   ```
+   > [!CAUTION]
+   > Move `prod-master.txt` to a secure offline USB drive and/or print it on paper. **Do not** store this private key on any server.
+
+2. **Generate the Staging Master Key:**
+   ```bash
+   age-keygen -o staging-master.txt
+   ```
+
+3. **Update Configuration:**
+   Open both `.txt` files and copy their **Public Keys** (the strings starting with `age1...`). Open `.sops.yaml` in the root of this repository and replace the `# TODO` placeholders with your newly generated public keys. Commit and push this change.
+
+## 2. Proxmox Hypervisor Authentication
+
+The CI/CD pipeline needs restricted API access to Proxmox to provision Virtual Machines.
+
+**Prerequisites:** Install `terraform` ([Terraform installation](https://developer.hashicorp.com/terraform/downloads)).
+
+1. Ensure you have network access to your Proxmox host (e.g., via Tailscale).
+2. Execute the bootstrap script from the root of the repository:
+   ```bash
+   ./scripts/control-center-bootstrap.sh
+   ```
+3. Terraform will prompt you. You will need to provide your Proxmox `root@pam` credentials via environment variables or prompt.
+4. Upon successful completion, the script will output a secure **API Token**. Copy this token securely.
+
+## 3. Forgejo Secrets Configuration
+
+The CI/CD actions require access to the Proxmox token and the staging secret key.
+
+1. Navigate to your Forgejo Web UI.
+2. Go to **Settings > Actions > Secrets** for this repository.
+3. Add the following repository secrets:
+   *   `PROXMOX_TOKEN_SECRET`: Paste the token generated from Step 2.
+   *   `STAGING_AGE_KEY`: Paste the *entire contents* of your `staging-master.txt` file (the private key).
+   *   `RENOVATE_TOKEN`: Create a Personal Access Token (PAT) for your user in Forgejo with read/write access to code and pull requests, and paste it here.
+
+## Next Steps
+Once these bootstrap steps are complete, the foundational authentication is in place. The Forgejo CI actions will now have the necessary permissions to build images, provision VMs, and test staging environments autonomously.

README.md

@@ -2,6 +2,9 @@
 
 This branch contains the automated, pull-based GitOps architecture using `comin`, Terraform, and Forgejo.
 
+> [!IMPORTANT]
+> **Getting Started:** If you are setting up this repository from scratch, you **must** follow the steps in [BOOTSTRAP.md](file:///c:/Users/tibod/Documents/projects/Bos55/nix-config/BOOTSTRAP.md) before the automated pipelines can function.
+
 ## Secret Management (SOPS-Nix)
 
 This repository uses `sops-nix` for secret management, adhering to a strict separation between Production and Staging environments to prevent credential leakage during CI runs.