secrets/README.md

@@ -6,9 +6,9 @@ This directory documents the secrets required for each Docker Swarm stack.
 
 ```
 Secret values live in Woodpecker (encrypted)
-    ↓ pipeline reads them at deploy time
+    → pipeline reads them at deploy time
 Docker Swarm secret store (encrypted Raft DB, replicated across all nodes)
-    ↓ mounted into containers at runtime
+    → mounted into containers at runtime
 /run/secrets/<secret_name>
 ```
 
@@ -38,7 +38,10 @@ 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.
+`create_or_update_secret` for each secret. (Or, preferred for new
+migrations: add an entry to `secrets/secrets-map.yaml` + a
+`<stack>.env.template` and call `deploy/provision-stack.py <stack>`
+instead — see the `ai` and `traefik` entries for the current pattern.)
 
 ### Step 3 — Test by pushing a trivial change to the stack's yaml file
 Watch the pipeline run: provision-secrets → validate → deploy → verify → notify.
@@ -71,10 +74,20 @@ Examples:
 - **PostgreSQL is highest risk.** Its master password is used by nearly every
   other stack. Migrate it last.
 
+- **Never commit a rendered env file, even by accident.** `traefik/traefik.env`
+  was committed to git for a period (discovered/fixed 2026-09-12) with a
+  literal "***REDACTED***" placeholder as KEEPALIVED_PASSWORD, which was
+  silently restored every time the file was deleted or the checkout resynced
+  from git — causing a real VRRP auth outage. `.gitignore` blanket-excludes
+  `*.env`, but that rule does NOT retroactively untrack a file already
+  committed before the rule existed. If you ever see a stack's `.env` file
+  show up in `git status` as tracked, stop and untrack it (`git rm --cached`)
+  before doing anything else.
+
 ## Migration Status
 
 | Stack | Secrets in Woodpecker | Pipeline Step Added | .env Removed |
-|-------|----------------------|---------------------|--------------|
+|-------|------------------------|----------------------|---------------|
 | 3dprint | ⏳ | ⏳ | ⏳ |
 | ai | ⏳ | ⏳ | ⏳ |
 | auth | ⏳ | ⏳ | ⏳ |
@@ -91,7 +104,7 @@ Examples:
 | postgresql | ⏳ | ⏳ | ⏳ |
 | productivity | ⏳ | ⏳ | ⏳ |
 | security | ⏳ | ⏳ | ⏳ |
-| traefik | ⏳ | ⏳ | ⏳ |
+| traefik | ✅ (manifest-driven, 2026-09-12) | ✅ (manifest-driven, 2026-09-12) | ⏳ |
 | unifi | ✅ N/A (no secrets) | ✅ N/A | ⏳ |
 | vaultwarden | ⏳ | ⏳ | ⏳ |
 | woodpecker | ⏳ Manual only | ⏳ N/A | ⏳ |