fix: unbreak the npm publish, and track the theme by range in the docs

[jamesbeedy]

Two unrelated fixes, both surfaced by the v0.1.8 release attempt.

1. The publish job died before it published

Run 34061859713 failed inside the setup-node step, before installing anything:

error Failed to replace env in config: ${NODE_AUTH_TOKEN}
    at envReplace (/usr/local/lib/node_modules/yarn/lib/cli.js:95448:16)
    at NpmRegistry.normalizeConfig (...)

registry-url makes setup-node write an .npmrc containing the literal ${NODE_AUTH_TOKEN}, and cache: yarn then shells out to yarn to locate the cache directory. Yarn 1 expands env vars in .npmrc eagerly and dies on an unset one. The token was scoped to the npm publish step, so it did not exist yet.

Reproduced outside CI:

$ printf '//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}\n' > .npmrc
$ env -u NODE_AUTH_TOKEN yarn cache dir
error Failed to replace env in config: ${NODE_AUTH_TOKEN}
$ NODE_AUTH_TOKEN=dummy yarn cache dir
/home/…/.cache/yarn/v6

Fix: move NODE_AUTH_TOKEN to job-level env. It has to be present from the moment the .npmrc exists.

This did not bite before because the workflow was on actions/setup-node@v4, which restored the cache before writing the .npmrc. v7 reversed that order, so repinning to the latest SHA is what exposed it.

2. The docs site follows 0.4.x instead of one exact version

Per request. The site declared an exact 0.4.7, so a patch release reached readers only when someone remembered to bump it. Now ^0.4.7: below 1.0.0 npm reads a caret as "this minor only" (>=0.4.7 <0.5.0), so patches arrive on their own and a 0.5.0 stays a deliberate adoption.

A range in package.json is not enough on its own. npm ci is lockfile-exact by design, so the site would have sat on whatever version the lockfile was last regenerated against, however wide the range. Both workflows now run:

npm update --no-save @vantagecompute/docusaurus-theme

after installing. That takes the newest release in range while leaving the lockfile and package.json untouched, so every other dependency stays reproducible and CI never produces a diff.

just docs-pin now writes a caret range and is only needed to cross a minor. The consumer guidance on the installation page changed with it: it used to argue for an exact pin, which would have contradicted what this repository now does.

Verification

$ npm ci && npm update --no-save @vantagecompute/docusaurus-theme
$ git status --porcelain        # clean, no lockfile diff
$ npm run typecheck && npm run build
[SUCCESS] Generated static files in "build".

Separate problem, not fixed here

The release that triggered all this is tagged v0.1.8, in a repository whose package.json says 0.4.7. It is currently GitHub's "Latest". npm is unaffected (the publish failed before publishing, latest is still 0.4.7), but the tag is reachable from main, so getProjectVersion() will resolve git describe --tags to it and every future docs deploy will render a v0.1.8-N-gSHA badge until it is deleted. Worth deleting the tag and the release.

🤖 Generated with Claude Code