diff --git a/changelog.d/57.md b/changelog.d/57.md
new file mode 100644
index 0000000..3f6d6d0
--- /dev/null
+++ b/changelog.d/57.md
@@ -0,0 +1 @@
+- Clarified Debian publish authentication failures with the CI secret source and the local remedies. (#57).
diff --git a/scripts/publish-deb.sh b/scripts/publish-deb.sh
index 1e7e3a6..f3b7e66 100755
--- a/scripts/publish-deb.sh
+++ b/scripts/publish-deb.sh
@@ -9,7 +9,7 @@
 #   component     APT component, default: main
 #
 # Authentication (first match wins):
-#   1. STOKE_TOKEN environment variable
+#   1. STOKE_TOKEN environment variable (set from secrets.RELEASE_TOKEN in CI)
 #   2. The token stored by `stoke auth login`
 #
 # The Forgejo URL defaults to the instance in the stoke config, falling back
@@ -30,7 +30,15 @@ CONFIG_JSON="$(node -e "const c = require('$ROOT/src/config').loadConfig(); if (
 TOKEN="${STOKE_TOKEN:-$(node -pe "(JSON.parse(process.argv[1] || '{}').token) || ''" "$CONFIG_JSON")}"
 FORGE_URL="${FORGE_URL:-$(node -pe "(JSON.parse(process.argv[1] || '{}').url) || 'https://forgejo.heavyduty.builders'" "$CONFIG_JSON")}"
 
-[ -n "$TOKEN" ] || { echo "error: no token. Set STOKE_TOKEN or run: stoke auth login" >&2; exit 1; }
+if [ -z "$TOKEN" ]; then
+  cat >&2 <<'EOF'
+error: no token.
+  In CI, this step reads STOKE_TOKEN from secrets.RELEASE_TOKEN; an empty value
+  means the secret is unset or unreadable by this workflow, not that the tool is missing.
+  Locally: export STOKE_TOKEN, or run `stoke auth login`.
+EOF
+  exit 1
+fi
 
 URL="$FORGE_URL/api/packages/$OWNER/debian/pool/$DISTRIBUTION/$COMPONENT/upload"
 echo "Uploading $(basename "$DEB") to $URL"