diff --git a/secrets/README.md b/secrets/README.md
new file mode 100644
index 0000000..a6bde85
--- /dev/null
+++ b/secrets/README.md
@@ -0,0 +1,97 @@
+# Secrets Management
+
+This directory documents the secrets required for each Docker Swarm stack.
+
+## How It Works
+
+```
+Secret values live in Woodpecker (encrypted)
+    ↓ pipeline reads them at deploy time
+Docker Swarm secret store (encrypted Raft DB, replicated across all nodes)
+    ↓ mounted into containers at runtime
+/run/secrets/<secret_name>
+```
+
+## Files in This Directory
+
+Each `<stack>.secrets.example` file documents:
+- **Which keys are secrets** (sensitive — must go in Woodpecker)
+- **Which keys are non-secrets** (config values — can live in compose file or .env)
+- **The Woodpecker secret name** to use for each value
+- **What the value is used for**
+
+These files contain **NO actual values** — they are safe to commit to Git.
+
+## How to Add a Secret to Woodpecker
+
+1. Go to **https://woodpecker.bryanmail.net**
+2. Navigate to `homelab/compose-files` → **Settings** → **Secrets**
+3. Click **Add Secret**
+4. Set the **Name** exactly as shown in the `.secrets.example` file
+5. Paste the **Value** from the corresponding `.env` file on the host
+6. Save
+
+## How to Migrate a Stack
+
+### Step 1 — Add secrets to Woodpecker UI
+Use the stack's `.secrets.example` file as your checklist.
+
+### Step 2 — Add the stack's case to `.woodpecker.yml`
+In the `provision-secrets` step, add a case for the stack that calls
+`create_or_update_secret` for each secret.
+
+### Step 3 — Test by pushing a trivial change to the stack's yaml file
+Watch the pipeline run: provision-secrets → validate → deploy → verify → notify.
+
+### Step 4 — Remove the `.env` file from the host (optional)
+Once the pipeline is managing secrets, the host-side `.env` file is redundant.
+Keep it as a backup until you're confident.
+
+## Secret Naming Convention
+
+Docker secret names use underscores and lowercase. The convention used here is:
+```
+<stack>_<variable_purpose>
+```
+Examples:
+- `git_db_password`
+- `ai_aws_secret_access_key`
+- `security_crowdsec_api_key`
+
+## Important Notes
+
+- **Docker cannot update a secret in-place.** The `deploy/create-secrets.sh`
+  helper handles this by removing and recreating changed secrets automatically.
+  Services using the secret will continue running with the old value until the
+  stack is redeployed.
+
+- **Woodpecker cannot manage its own secrets.** The `woodpecker` stack must
+  always be managed manually. See `woodpecker.secrets.example` for details.
+
+- **PostgreSQL is highest risk.** Its master password is used by nearly every
+  other stack. Migrate it last.
+
+## Migration Status
+
+| Stack | Secrets in Woodpecker | Pipeline Step Added | .env Removed |
+|-------|----------------------|---------------------|--------------|
+| 3dprint | ⏳ | ⏳ | ⏳ |
+| ai | ⏳ | ⏳ | ⏳ |
+| auth | ⏳ | ⏳ | ⏳ |
+| entertainment | ⏳ | ⏳ | ⏳ |
+| gamma | ⏳ | ⏳ | ⏳ |
+| git | ⏳ | ⏳ | ⏳ |
+| guacamole | ⏳ | ⏳ | ⏳ |
+| homeassistant | ⏳ | ⏳ | ⏳ |
+| maintenance | ✅ N/A (no secrets) | ✅ N/A | ⏳ |
+| media | ✅ N/A (no secrets) | ✅ N/A | ⏳ |
+| mealie | ⏳ | ⏳ | ⏳ |
+| meshcentral | ⏳ | ⏳ | ⏳ |
+| n8n | ⏳ | ⏳ | ⏳ |
+| postgresql | ⏳ | ⏳ | ⏳ |
+| productivity | ⏳ | ⏳ | ⏳ |
+| security | ⏳ | ⏳ | ⏳ |
+| traefik | ⏳ | ⏳ | ⏳ |
+| unifi | ✅ N/A (no secrets) | ✅ N/A | ⏳ |
+| vaultwarden | ⏳ | ⏳ | ⏳ |
+| woodpecker | ⏳ Manual only | ⏳ N/A | ⏳ |