diff --git a/.env.example b/.env.example
index 3e90244..885b6f9 100644
--- a/.env.example
+++ b/.env.example
@@ -1,5 +1,16 @@
 # Discord Bot Configuration
 # =============================================================================
+#
+# PRODUCTION ENV IS DECLARATIVE:
+# The runtime env files on the VPS (/etc/gmw/backend.env,
+# /etc/gmw/discord-gateway.env) are WRITTEN BY CI from Gitea Actions secrets
+# (BACKEND_ENV, GATEWAY_ENV) — see .gitea/workflows/deploy.yml.
+# To change production env: update the secret in Gitea repo settings
+# (Settings → Actions → Secrets), then push any commit to main. Never
+# SSH into the VPS to edit env files by hand — CI will overwrite them.
+#
+# This file documents every variable; values for production live in the
+# secrets, not here.
 
 # === Discord ===
 DISCORD_TOKEN=your_bot_token_here       # REQUIRED
diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml
index 98fec56..9761855 100644
--- a/.gitea/workflows/deploy.yml
+++ b/.gitea/workflows/deploy.yml
@@ -25,6 +25,11 @@ jobs:
           VPS_HOST: ${{ secrets.VPS_HOST }}
           VPS_USER: ${{ secrets.VPS_USER }}
           VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
+          # Declarative env: source of truth = Gitea secrets, CI writes the
+          # service env files on the VPS. Update env by editing the secret,
+          # never by SSH-ing into the VPS by hand.
+          BACKEND_ENV: ${{ secrets.BACKEND_ENV }}
+          GATEWAY_ENV: ${{ secrets.GATEWAY_ENV }}
         run: |
           set -eu
 
@@ -55,6 +60,30 @@ jobs:
           export NIX_SSHOPTS="-i $key_file -o StrictHostKeyChecking=no"
           nix copy --to "ssh://${VPS_USER}@${VPS_HOST}" "$STORE_PATH" 2>&1
 
+          # --- Deploy env (declarative, from Gitea secrets) ---
+          ENV_TARGET=""
+          ENV_VALUE=""
+          case "$SERVICE" in
+            backend)         ENV_TARGET="/etc/gmw/backend.env"; ENV_VALUE="$BACKEND_ENV" ;;
+            discord-gateway) ENV_TARGET="/etc/gmw/discord-gateway.env"; ENV_VALUE="$GATEWAY_ENV" ;;
+            proxy)           ;;  # nginx proxy has no env file
+          esac
+
+          if [ -n "$ENV_VALUE" ] && [ -n "$ENV_TARGET" ]; then
+            echo "=== Deploying env: $ENV_TARGET ==="
+            printf '%s\n' "$ENV_VALUE" | ssh -i "$key_file" -o StrictHostKeyChecking=no \
+              "${VPS_USER}@${VPS_HOST}" "
+              set -eu
+              mkdir -p /etc/gmw
+              cat > $ENV_TARGET
+              chown gmw:gmw $ENV_TARGET
+              chmod 600 $ENV_TARGET
+              echo \"env file lines: \$(grep -c '=' $ENV_TARGET)\"
+            "
+          else
+            echo "=== No env secret for $SERVICE — skipping env deploy ==="
+          fi
+
           ssh -i "$key_file" -o StrictHostKeyChecking=no \
             "${VPS_USER}@${VPS_HOST}" "
             if [ -d $PROFILE ] && [ ! -L $PROFILE ]; then