diff --git a/DEV_WORKFLOW.md b/DEV_WORKFLOW.md
index 3e13cf8b..ac11eae2 100644
--- a/DEV_WORKFLOW.md
+++ b/DEV_WORKFLOW.md
@@ -262,7 +262,8 @@ docker compose exec api npx prisma migrate dev        # Create migration
 # ── Build & Publish ──
 ./scripts/build-and-push.sh                           # Build + push 4 images
 ./scripts/mirror-images.sh                            # Mirror 36 third-party images
-./scripts/build-release.sh --tag v2.2.0 --upload      # Package + upload release
+git tag --sort=-v:refname | head -3                   # Check latest version tags
+./scripts/build-release.sh --tag vX.Y.Z --upload      # Package + upload release
 
 # ── Deploy ──
 curl -fsSL .../install.sh | bash                      # New install (release)
@@ -276,13 +277,46 @@ docker compose ps                                     # Container status
 
 ---
 
+## Gitea API Tokens
+
+There are **two separate Gitea tokens** with different purposes. Using the wrong one is a common mistake:
+
+| Variable | Target | Used by | Create at |
+|----------|--------|---------|-----------|
+| `GITEA_REGISTRY_API_TOKEN` | Remote registry (`gitea.bnkops.com`) | `build-release.sh --upload`, release API calls | `https://gitea.bnkops.com/user/settings/applications` |
+| `GITEA_API_TOKEN` | Local Gitea instance | Docs comments, user provisioning, SSO | `http://localhost:3030/user/settings/applications` |
+
+**Key:** Release uploads and the Gitea Releases API require `GITEA_REGISTRY_API_TOKEN`. If you get `"user does not exist"` from the API, you're using the wrong token.
+
+---
+
 ## Checklist: Cutting a New Release
 
-1. [ ] All code changes committed and pushed to `v2` branch
+1. [ ] All code changes committed and pushed to `main` branch
 2. [ ] `docker compose up -d` works locally (smoke test)
-3. [ ] `./scripts/build-and-push.sh` — builds and pushes 4 production images
-4. [ ] `./scripts/mirror-images.sh` — only if third-party versions changed
-5. [ ] `./scripts/build-release.sh --tag vX.Y.Z --upload` — packages and uploads tarball
-6. [ ] Test clean install: `tar xzf ... && cd changemaker-lite && bash config.sh && docker compose up -d`
-7. [ ] Test upgrade: `./scripts/upgrade.sh` on an existing installation
-8. [ ] Verify: `curl http://localhost:4000/api/health` returns `{"status":"ok"}`
+3. [ ] **Determine version tag:**
+   ```bash
+   # Check the latest existing tag to pick the next version
+   git tag --sort=-v:refname | head -5
+   # Check commits since the last tag
+   git log $(git tag --sort=-v:refname | head -1)..HEAD --oneline
+   ```
+4. [ ] `./scripts/build-and-push.sh` — builds and pushes 4 production images
+5. [ ] `./scripts/mirror-images.sh` — only if third-party versions changed
+6. [ ] `./scripts/build-release.sh --tag vX.Y.Z --upload` — packages and uploads tarball
+7. [ ] **Add release notes** (via Gitea web UI or API):
+   ```bash
+   # Update release body via API (use GITEA_REGISTRY_API_TOKEN, not GITEA_API_TOKEN)
+   GITEA_TOKEN=$(grep -oP 'GITEA_REGISTRY_API_TOKEN=\K.*' .env)
+   # Find release ID
+   curl -s "https://gitea.bnkops.com/api/v1/repos/admin/changemaker.lite/releases?limit=1" \
+     -H "Authorization: token $GITEA_TOKEN" | python3 -c "import sys,json; r=json.load(sys.stdin)[0]; print(f'ID: {r[\"id\"]}, Tag: {r[\"tag_name\"]}')"
+   # Update with release notes (write JSON body to /tmp/release-notes.json first)
+   curl -s -X PATCH "https://gitea.bnkops.com/api/v1/repos/admin/changemaker.lite/releases/RELEASE_ID" \
+     -H "Authorization: token $GITEA_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d @/tmp/release-notes.json
+   ```
+8. [ ] Test clean install: `tar xzf ... && cd changemaker-lite && bash config.sh && docker compose up -d`
+9. [ ] Test upgrade: `./scripts/upgrade.sh` on an existing installation
+10. [ ] Verify: `curl http://localhost:4000/api/health` returns `{"status":"ok"}`