chore: snapshot current workspace changes

USAGE_GUIDE.md

@@ -562,6 +562,34 @@ Add a cron job on the MacBook (or any machine with SSH access to both servers):
 0 2 * * * cd /path/to/gitea-migration && ./backup/backup_primary.sh >> /var/log/gitea-backup.log 2>&1
 ```
 
+### Backing up .env to Bitwarden
+
+The `.env` file is gitignored (it contains passwords and tokens) but is needed for ongoing operations — teardown, runner management, backup/restore, and token rotation. If you lose it, you lose the ability to manage the migration.
+
+**Export .env to Bitwarden:**
+
+```bash
+./setup/env_to_bitwarden.sh -o bitwarden-import.json
+```
+
+This creates a Bitwarden-importable JSON file with a secure note called `gitea-migration-env`. Each `.env` variable becomes a custom field — passwords and tokens are marked as hidden fields.
+
+Import it: Bitwarden Web Vault → Tools → Import Data → Format: Bitwarden (json) → Upload the file. Delete `bitwarden-import.json` from disk afterward.
+
+**Restore .env from Bitwarden:**
+
+```bash
+bw unlock                              # unlock your vault first
+./setup/bitwarden_to_env.sh --bw       # fetches just the one item
+./preflight.sh                         # validate the restored .env
+```
+
+The script uses `.env.example` as a template to preserve section headers and comments. Run preflight afterward to confirm all variables are correct and connectivity works.
+
+**Important**: Do not use `bw export` (full vault export) to get the data — it dumps your entire vault to a plaintext JSON file on disk. The `--bw` flag fetches only the `gitea-migration-env` item.
+
+**After cleanup**: `teardown_all.sh --cleanup` uninstalls the `bw` CLI from your Mac, but the secure note remains in your Bitwarden vault. Reinstall with `brew install bitwarden-cli` if you need to restore later.
+
 ---
 
 ## Runner Management