diff --git a/packages/mosaic/framework/tools/git/detect-platform.sh b/packages/mosaic/framework/tools/git/detect-platform.sh
index a06452d1..5a78920c 100755
--- a/packages/mosaic/framework/tools/git/detect-platform.sh
+++ b/packages/mosaic/framework/tools/git/detect-platform.sh
@@ -246,6 +246,21 @@ PY
     } >&2
 }
 
+# Explain tea's most misleading failure. `user does not exist [uid: 0, name: ]` reads
+# as a missing account; it almost always means a REVOKED OR STALE TOKEN. `tea login`
+# keeps its OWN COPY of the token, so rotating the credential store does not update it.
+# Diagnostic only -- stderr, no control flow, no exit.
+explain_tea_user_does_not_exist() {
+    cat >&2 <<'MSG'
+NOTE: `user does not exist [uid: 0, name: ]` from tea usually means a REVOKED OR STALE TOKEN,
+      not a missing account. A `tea login` stores its OWN COPY of the token; rotating the
+      credential store does NOT update it.
+      CHECK: the login's cached copy (`tea login list` -- read the FULL table, never `| head`),
+             then re-register that login against the current token.
+      DO NOT probe capability with a mutating request; a POST is the action, not a check.
+MSG
+}
+
 get_gitea_login_for_host() {
     local host="${1:-}"
     local login
diff --git a/packages/mosaic/framework/tools/git/issue-create.sh b/packages/mosaic/framework/tools/git/issue-create.sh
index 96f890cf..5ab8f871 100755
--- a/packages/mosaic/framework/tools/git/issue-create.sh
+++ b/packages/mosaic/framework/tools/git/issue-create.sh
@@ -156,6 +156,7 @@ case "$PLATFORM" in
                 exit 0
             fi
             echo "Warning: tea issue create failed, trying Gitea API fallback..." >&2
+            declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist
         fi
         gitea_issue_create_api
         ;;
diff --git a/packages/mosaic/framework/tools/git/issue-view.sh b/packages/mosaic/framework/tools/git/issue-view.sh
index eccab98e..aaf48ae6 100755
--- a/packages/mosaic/framework/tools/git/issue-view.sh
+++ b/packages/mosaic/framework/tools/git/issue-view.sh
@@ -71,6 +71,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             exit 0
         fi
         echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2
+        declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist
     fi
     gitea_issue_view_api
 else
diff --git a/packages/mosaic/framework/tools/git/pr-create.sh b/packages/mosaic/framework/tools/git/pr-create.sh
index 46b82a64..380182ff 100755
--- a/packages/mosaic/framework/tools/git/pr-create.sh
+++ b/packages/mosaic/framework/tools/git/pr-create.sh
@@ -219,6 +219,7 @@ case "$PLATFORM" in
             exit 0
         fi
         echo "Warning: tea pr create failed, trying Gitea API fallback..." >&2
+        declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist
         gitea_pr_create_api
         ;;
     *)