diff --git a/.env.example b/.env.example
index 27f8b8bc..eca3d63b 100644
--- a/.env.example
+++ b/.env.example
@@ -212,8 +212,12 @@ COMPOSE_PROFILES=
 # For docker push/pull, run: docker login gitea.bnkops.com
 GITEA_REGISTRY_USER=admin
 GITEA_REGISTRY_PASS=
+# API token for the REMOTE registry (gitea.bnkops.com) — used by build-release.sh --upload
+# Create at: https://gitea.bnkops.com/user/settings/applications
+# This is NOT the same as GITEA_API_TOKEN (which is for the local platform Gitea below)
+GITEA_REGISTRY_API_TOKEN=
 
-# --- Gitea ---
+# --- Gitea (Local Platform Instance) ---
 GITEA_URL=http://gitea-changemaker:3000
 GITEA_PORT=3030
 GITEA_WEB_PORT=3030
@@ -230,7 +234,9 @@ GITEA_DOMAIN=git.cmlite.org
 # --- Gitea Docs Comments ---
 # Enable comments on MkDocs pages (backed by Gitea Issues)
 GITEA_COMMENTS_ENABLED=false
-# Personal access token with repo write scope (create in Gitea → Settings → Applications)
+# Personal access token for the LOCAL Gitea instance (docs comments, user provisioning, SSO)
+# Create at: http://localhost:3030/user/settings/applications (or https://git.DOMAIN/...)
+# This is NOT the same as GITEA_REGISTRY_API_TOKEN (which is for the remote registry above)
 GITEA_API_TOKEN=
 # Repository owner (Gitea username that will own the docs-comments repo)
 GITEA_COMMENTS_REPO_OWNER=
diff --git a/api/src/config/env.ts b/api/src/config/env.ts
index aa1edd85..e5763672 100644
--- a/api/src/config/env.ts
+++ b/api/src/config/env.ts
@@ -183,14 +183,15 @@ const envSchema = z.object({
   MEDIA_UPLOADS: z.string().default('/media/uploads'),
   MAX_UPLOAD_SIZE_GB: z.coerce.number().default(10),
 
-  // Container Registry
+  // Container Registry (remote — gitea.bnkops.com)
   GITEA_REGISTRY: z.string().default('gitea.bnkops.com/admin'),
   GITEA_REGISTRY_USER: z.string().default(''),
   GITEA_REGISTRY_PASS: z.string().default(''),
+  GITEA_REGISTRY_API_TOKEN: z.string().default(''), // For release uploads (build-release.sh)
 
-  // Gitea Docs Comments
+  // Gitea Docs Comments (local platform instance)
   GITEA_COMMENTS_ENABLED: z.string().default('false'),
-  GITEA_API_TOKEN: z.string().default(''),
+  GITEA_API_TOKEN: z.string().default(''), // Local Gitea — NOT the remote registry
   GITEA_COMMENTS_REPO_OWNER: z.string().default(''),
   GITEA_COMMENTS_REPO_NAME: z.string().default('docs-comments'),
   GITEA_OAUTH_CLIENT_ID: z.string().default(''),
diff --git a/scripts/build-release.sh b/scripts/build-release.sh
index ab3773a9..000e1451 100755
--- a/scripts/build-release.sh
+++ b/scripts/build-release.sh
@@ -198,14 +198,16 @@ success "Created: $TARBALL (${TARBALL_SIZE})"
 # --- Upload to Gitea (optional) ---
 if [[ "$UPLOAD" == "true" ]]; then
   source "$PROJECT_DIR/.env" 2>/dev/null || true
-  GITEA_TOKEN="${GITEA_API_TOKEN:-}"
+  # GITEA_REGISTRY_API_TOKEN is for the remote registry (gitea.bnkops.com)
+  # GITEA_API_TOKEN is for the local platform Gitea — do NOT use it here
+  GITEA_TOKEN="${GITEA_REGISTRY_API_TOKEN:-}"
   # GITEA_URL is the internal Docker hostname — use GITEA_REGISTRY for external access
   GITEA_REGISTRY_HOST="${GITEA_REGISTRY%%/*}"  # strip /admin path → gitea.bnkops.com
   GITEA_HOST="${GITEA_EXTERNAL_URL:-https://${GITEA_REGISTRY_HOST:-gitea.bnkops.com}}"
 
   if [[ -z "$GITEA_TOKEN" ]]; then
-    warn "GITEA_API_TOKEN not set — skipping upload"
-    warn "Set GITEA_API_TOKEN in .env and re-run with --upload"
+    warn "GITEA_REGISTRY_API_TOKEN not set — skipping upload"
+    warn "Set GITEA_REGISTRY_API_TOKEN in .env and re-run with --upload"
   else
     info "Creating Gitea release ${TAG}..."
     RELEASE_RESPONSE=$(curl -sf -X POST \