diff --git a/doc/PUBLISHING.md b/doc/PUBLISHING.md
index 5bf67c6b20e..311b43dfd88 100644
--- a/doc/PUBLISHING.md
+++ b/doc/PUBLISHING.md
@@ -213,7 +213,7 @@ The helper script:
 - only runs the real `npm publish --access public` when `--publish` is provided
 
 For the real `--publish` step, the maintainer machine must already be authenticated to npm.
-If `npm whoami` returns `401`, run `npm login` or `npm adduser` locally as an npm org member first, then rerun the helper.
+If `npm whoami` returns `401`, first run `npm logout --registry=https://registry.npmjs.org/` to clear any stale local auth, then run `npm login` or `npm adduser` locally as an npm org member, and finally rerun the helper.
 That local human auth is fine for the one-time bootstrap publish; we just do not want the same auth model inside CI.
 
 After that first publish succeeds:
diff --git a/scripts/bootstrap-npm-package.mjs b/scripts/bootstrap-npm-package.mjs
index b2bb5180b26..d887b6f6bc4 100644
--- a/scripts/bootstrap-npm-package.mjs
+++ b/scripts/bootstrap-npm-package.mjs
@@ -109,7 +109,8 @@ function ensureNpmAuth() {
     throw new Error(
       [
         "npm auth check failed.",
-        "Run `npm login` or `npm adduser` on this maintainer machine with an npm account that can publish to the @paperclipai scope, then rerun with --publish.",
+        "This usually means the machine is either not logged into npm yet or has a stale token in ~/.npmrc.",
+        "Run `npm logout --registry=https://registry.npmjs.org/` and then `npm login` or `npm adduser` on this maintainer machine with an npm account that can publish to the @paperclipai scope, then rerun with --publish.",
         "Do not use this auth flow in CI; it is only for the one-time human bootstrap publish.",
       ].join(" "),
     );