docs: update deployment guide with comprehensive two-file architecture

- Add detailed two-file architecture overview explaining separation of environment and provider configurations
- Document provider configuration requirements with step-by-step instructions
- Add security notes about API token handling
- Update cloud deployment commands to use proper Makefile commands
- Remove 'Coming Soon' status - staging/production deployment ready
- Fix markdown formatting for proper guide structure

Resolves missing documentation about configuration architecture discovered during staging environment setup.

Author: josecelano

docs/guides/deployment-guide.md

@@ -90,20 +90,25 @@ make vm-ssh        # Connect to VM
 make infra-destroy
 ```
 
-### Cloud Deployment (Coming Soon)
+### Cloud Deployment
 
 ```bash
-# Setup Hetzner credentials
-export HCLOUD_TOKEN="your-hetzner-cloud-token"
-export HDNS_TOKEN="your-hetzner-dns-token"
+# Configure Hetzner provider with your API tokens first
+vim infrastructure/config/providers/hetzner.env
+
+# Generate staging environment configuration
+make infra-config-staging PROVIDER=hetzner
+
+# Generate production environment configuration
+make infra-config-production PROVIDER=hetzner
 
 # Deploy staging environment
-make infra-apply ENVIRONMENT_TYPE=staging ENVIRONMENT_FILE=staging-hetzner
-make app-deploy ENVIRONMENT_TYPE=staging ENVIRONMENT_FILE=staging-hetzner
+make infra-apply ENVIRONMENT=staging ENVIRONMENT_FILE=staging-hetzner
+make app-deploy ENVIRONMENT=staging ENVIRONMENT_FILE=staging-hetzner
 
 # Deploy production environment
-make infra-apply ENVIRONMENT_TYPE=production ENVIRONMENT_FILE=production-hetzner
-make app-deploy ENVIRONMENT_TYPE=production ENVIRONMENT_FILE=production-hetzner
+make infra-apply ENVIRONMENT=production ENVIRONMENT_FILE=production-hetzner
+make app-deploy ENVIRONMENT=production ENVIRONMENT_FILE=production-hetzner
 ```
 
 ---
@@ -839,6 +844,56 @@ TRACKER_ADMIN_TOKEN=MyAccessToken
 
 ### Production Environment Configuration
 
+#### Two-File Architecture Overview
+
+The deployment system uses a **two-file architecture** for maximum security and flexibility:
+
+1. **Environment Files**: Environment-specific settings (staging-hetzner.env, production-hetzner.env)
+2. **Provider Files**: API tokens and provider configuration (hetzner.env)
+
+**Benefits**:
+
+- **Security**: API tokens stored separately from environment settings
+- **Flexibility**: Same provider configuration works across multiple environments
+- **Deployment**: Scripts load both files independently during operations
+
+**File Locations**:
+
+- **Environment Files**: `infrastructure/config/environments/`
+- **Provider Files**: `infrastructure/config/providers/`
+
+#### Configure Hetzner Provider (Required)
+
+Before creating environment configurations, you must configure the Hetzner provider with your API tokens:
+
+```bash
+# Edit the Hetzner provider configuration
+vim infrastructure/config/providers/hetzner.env
+```
+
+**Required Changes**:
+
+1. Replace `HETZNER_API_TOKEN` with your Hetzner Cloud API token
+2. Replace `HETZNER_DNS_API_TOKEN` with your Hetzner DNS API token
+
+**Example Configuration**:
+
+```bash
+# === HETZNER CLOUD AUTHENTICATION ===
+HETZNER_API_TOKEN=your-actual-cloud-api-token-here
+
+# === HETZNER DNS AUTHENTICATION ===
+HETZNER_DNS_API_TOKEN=your-actual-dns-api-token-here
+
+# === HETZNER CLOUD SETTINGS ===
+HETZNER_SERVER_TYPE=cpx31  # 4 vCPU, 8GB RAM, 160GB SSD
+HETZNER_LOCATION=fsn1      # Falkenstein, Germany
+HETZNER_IMAGE=ubuntu-24.04
+```
+
+**⚠️ Security Note**: The provider file contains sensitive API tokens. Never commit real tokens
+to version control.
+
 #### Generate Secure Secrets
 
 Production deployment requires secure random secrets: