npm README Not Updating? The Registry Serves What You Published, Not What You Pushed

You fixed the README, committed, pushed — GitHub shows the new version — and npmjs.com is still serving the old one. Days later, it still is. Nothing is broken and nothing is coming: the npm registry does not read your repository. It renders the README that was inside the tarball of the latest published version, and it will keep doing so until you publish a new one. Here is the mechanism, the silent-auth trap that stops the fix from shipping, and how to verify a docs change actually reached the registry.

The mechanism: the registry serves the tarball, not the repo

npm publishsnapshots your package — README included — into a tarball. The package page renders from that snapshot. npm's own docs state it plainly: “The README.md file will only be updated on the package page when you publish a new version of your package.” The repository field is a link, not a data source. So the fix is always the same:

npm version patch        # 1.2.3 -> 1.2.4 (registry rejects re-publishing a used version)
npm publish
npm view <pkg> version   # confirm the registry has the new version

This matters more than it looks like it should. For a typical open-source funnel, the npm package page is where nearly all the traffic lands — we measured this on our own packages — so a stale README there means every reader is seeing your old install instructions, no matter how pristine the repo is.

“Committed” is not “shipped”

The silent-auth trap that eats the publish

The reason our publish never landed is worth its own section, because the failure is genuinely sneaky: npm auth tokens expire silently. There is no local warning, and the obvious health check lies to you:

• npm ping returns PONG — that only proves the network path.
• npm whoami returns 401 — this is the check that matters. Run it before any publish; an expired token turns your release script into a no-op with an error line scrolling past in CI output nobody reads.
• Granular access tokens have expiry dates you chose months ago and forgot. Put npm whoami at the top of the release script and fail loudly.

Verify from the registry, not from anything you control

The counterpart of “the registry is the source of truth” is that verification must read from the registry. In order of authority:

1. 1npm view <pkg> version — is the new version there at all?
2. 2curl -s https://registry.npmjs.org/<pkg> | jq -r .readme | head — is the new README text actually in the registry document? Diff it against your local file if you want a real receipt.
3. 3The npmjs.com page itself — last, because the website can lag the registry API by a few minutes after a publish. Registry says yes + page says old = wait; registry says old = your publish did not happen.

And do not “verify” against GitHub surfaces: raw.githubusercontent.com is CDN-cached minutes behind a push, which cuts both ways — we have watched a successful push read as failed because the raw URL still served the old bytes. If you need to confirm repo content programmatically, ask the API (gh api repos/OWNER/REPO/contents/PATH), never the scraped HTML or the raw CDN.

Why this belongs in your agent's rules, not just your head

Registry-vs-repo is exactly the shape of mistake coding agents make confidently: the agent edits the file, sees the commit land, and reports the README fixed — every check it ran passed, and the one that matters was not on its list. Our fix was procedural: any claim of “docs shipped” must carry a receipt fetched from the distribution surface itself (registry API, live domain, store listing), and a claim without that receipt fails the gate. The same discipline, applied to deploys, is written up in Vercel deployed but the domain serves the old version — different platform, identical lesson: done means verified on the surface users touch.

The release receipt, on one screen

1. edit README.md, commit, push          # necessary, nowhere near sufficient
2. npm whoami                            # 401 here = fix auth BEFORE bumping anything
3. npm version patch && npm publish
4. npm view <pkg> version                # registry has the new version
5. curl registry.npmjs.org/<pkg> | jq -r .readme | grep "<your new line>"
6. only now report the docs shipped

Reference: npm's docs on package READMEs. For the general habit of building verification into the work instead of remembering it, see why AI automations break in production.