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

.github/workflows/ci.yml

@@ -92,6 +92,16 @@ jobs:
         working-directory: docusaurus
         run: npm ci
 
+      # `npm ci` is lockfile-exact by design, so the caret range in package.json
+      # alone would never pick up a newer 0.4.x: the site would sit on whatever
+      # version the lockfile was last regenerated against. This pulls the newest
+      # release matching the declared range, and `--no-save` leaves both the
+      # lockfile and package.json untouched, so every other dependency stays
+      # reproducible and CI never produces a diff.
+      - name: Take the newest theme release in range
+        working-directory: docusaurus
+        run: npm update --no-save @vantagecompute/docusaurus-theme
+
       - name: Typecheck
         working-directory: docusaurus
         run: npm run typecheck

.github/workflows/deploy-docs.yml

@@ -69,6 +69,16 @@ jobs:
         working-directory: docusaurus
         run: npm ci
 
+      # `npm ci` is lockfile-exact by design, so the caret range in package.json
+      # alone would never pick up a newer 0.4.x: the site would sit on whatever
+      # version the lockfile was last regenerated against. This pulls the newest
+      # release matching the declared range, and `--no-save` leaves both the
+      # lockfile and package.json untouched, so every other dependency stays
+      # reproducible and CI never produces a diff.
+      - name: Take the newest theme release in range
+        working-directory: docusaurus
+        run: npm update --no-save @vantagecompute/docusaurus-theme
+
       - name: Typecheck
         working-directory: docusaurus
         run: npm run typecheck

.github/workflows/publish.yml

@@ -11,6 +11,20 @@ permissions:
 jobs:
   publish:
     runs-on: ubuntu-latest
+
+    # Job level, not step level. `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, so with the token scoped to the
+    # publish step alone, setup-node itself failed:
+    #
+    #   error Failed to replace env in config: ${NODE_AUTH_TOKEN}
+    #
+    # The variable has to be in the environment from the moment the .npmrc
+    # exists, which means the whole job.
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
@@ -30,5 +44,3 @@ jobs:
 
       # Publish stays on the npm CLI: yarn 1 cannot emit provenance attestations.
       - run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -160,14 +160,15 @@ Full documentation is published as a spoke site on the Vantage docs hub:
 
 **https://docs.vantagecompute.ai/developer/docusaurus-theme/**
 
-It lives in `docusaurus/` in this repository and installs the theme from npm at
-a pinned version, so it renders what consumers actually get rather than the
-working tree.
+It lives in `docusaurus/` in this repository and installs the theme from npm, so
+it renders what consumers actually get rather than the working tree. The
+declared range is `^0.4.7`, so patch releases reach the site on the next deploy
+with no commit.
 
 ```bash
 just docs-serve         # local preview at /developer/docusaurus-theme/
 just docs-build         # build and link-check
-just docs-pin 0.4.8     # point the site at a newly published version
+just docs-pin 0.5.0     # move the range across a minor
 ```
 
 ## Development
@@ -187,7 +188,7 @@ The package uses TypeScript for the plugin entry point (`src/index.cts` -> `lib/
 just release 0.4.8
 ```
 
-Bumps `package.json`, commits, tags, pushes, and creates the GitHub release. The npm publish runs in CI on `release: published`, with provenance attestation. Afterwards, bump the docs site's pin with `just docs-pin`.
+Bumps `package.json`, commits, tags, pushes, and creates the GitHub release. The npm publish runs in CI on `release: published`, with provenance attestation. A patch release needs nothing else; a new minor needs `just docs-pin` for the docs site.
 
 ## License
 

docusaurus/docs/contributing.md

@@ -51,16 +51,20 @@ just docs-serve    # http://localhost:3000/developer/docusaurus-theme/
 just docs-build
 ```
 
-It installs the theme from npm at a pinned version rather than through a
-`file:` link to the repository around it. That is what makes the site an honest
-preview: it renders what consumers actually get, and it fails if a release ever
-ships a tarball missing something the build needs.
+It installs the theme from npm rather than through a `file:` link to the
+repository around it. That is what makes the site an honest preview: it renders
+what consumers actually get, and it fails if a release ever ships a tarball
+missing something the build needs.
 
-The pin therefore trails the package by up to one release, and moving it is a
-separate deliberate commit after the version is on npm:
+The declared range is `^0.4.7`, so a new 0.4.x patch reaches the site on the
+next deploy with no commit here. Both workflows run
+`npm update --no-save @vantagecompute/docusaurus-theme` after `npm ci`, because
+`npm ci` is lockfile-exact and the range on its own would never move.
+
+Moving to a new minor is deliberate:
 
 ```bash
-just docs-pin 0.4.8
+just docs-pin 0.5.0
 ```
 
 ## Releasing
@@ -81,8 +85,9 @@ Two details worth knowing:
 - The working tree must be clean; the recipe refuses to run otherwise, so a
   release can never contain something that was never committed.
 
-After the release lands on npm, bump this site's pin and, when the change
-matters to them, the pins in the consuming sites.
+A patch release needs nothing here: the site's range already covers it. A new
+minor needs `just docs-pin`, and the same bump in the consuming sites when the
+change matters to them.
 
 ## What belongs in the theme
 

docusaurus/docs/index.md

@@ -56,13 +56,11 @@ styles and nothing else.
 
 ## This site dogfoods the theme
 
-The site you are reading installs `@vantagecompute/docusaurus-theme` from npm
-at a pinned version, exactly as any other consumer does, not through a
-`file:` link to the repository it lives in. So it renders the design that is
-actually published, and a packaging mistake (a file the build needs that
-`files` in `package.json` does not ship) fails this build before it reaches
-anybody else.
+The site you are reading installs `@vantagecompute/docusaurus-theme` from npm,
+exactly as any other consumer does, not through a `file:` link to the
+repository it lives in. So it renders the design that is actually published,
+and a packaging mistake (a file the build needs that `files` in `package.json`
+does not ship) fails this build before it reaches anybody else.
 
-The trade-off is that this site trails the package by up to one release.
-Bumping the pin is a deliberate step after a version is on npm, not something
-a release does on its own.
+It follows the `^0.4.7` range, so each deploy picks up the newest 0.4.x
+release. A new minor is a deliberate bump.

docusaurus/docs/installation.md

@@ -30,23 +30,38 @@ site already installed rather than pulling in a second one. `@docusaurus/core`,
 
 The package itself depends only on `clsx` and `unist-util-visit`.
 
-## Pin the version
+## Declare the range
 
-Pin an exact version rather than a range:
+A caret range on the current minor:
 
 ```json
 {
   "dependencies": {
-    "@vantagecompute/docusaurus-theme": "0.4.7"
+    "@vantagecompute/docusaurus-theme": "^0.4.7"
   }
 }
 ```
 
-The theme changes how every page on the site looks. A caret range means a
-design change can land in a build nobody intended to change the design in,
-which is a bad way to find out about it. An exact pin makes the adoption a
-commit you can point at, and makes "which sites have this fix" a question
-`grep` answers.
+Below 1.0.0 npm reads a caret as "this minor only", so `^0.4.7` means
+`>=0.4.7 <0.5.0`. Patch releases within 0.4.x, which is where fixes land,
+arrive on their own. A 0.5.0 does not, so a release that changes the design
+deliberately stays a deliberate adoption in each site.
+
+:::caution `npm ci` will not move this on its own
+`npm ci` installs exactly what the lockfile says, by design, so a site whose CI
+uses it stays on whatever version the lockfile was last regenerated against
+however wide the range is. Either regenerate the lockfile when you want the
+newer theme, or refresh just this package after installing:
+
+```bash
+npm ci
+npm update --no-save @vantagecompute/docusaurus-theme
+```
+
+`--no-save` leaves the lockfile and `package.json` alone, so every other
+dependency stays reproducible and the build produces no diff. That is what this
+package's own documentation site does.
+:::
 
 ## What lands in `node_modules`
 

docusaurus/docusaurus.config.ts

@@ -8,16 +8,18 @@ import {
 } from '@vantagecompute/docusaurus-theme';
 
 // This site is the theme's own documentation, and it dogfoods the theme: the
-// dependency in package.json is the PUBLISHED version from npm, not a file:
+// dependency in package.json is the PUBLISHED package from npm, not a file:
 // link to the repository root. That is deliberate. A file: link would render
 // the working tree, so the site would show a design nobody can install yet and
 // would never catch a packaging mistake -- a file the build needs that
 // `files` in package.json does not ship. Building against the tarball readers
 // actually get is the only way this site stays honest.
 //
-// The consequence to keep in mind: the site trails the theme by up to one
-// release. Bumping the pin is a deliberate step after a version is on npm --
-// `just docs-pin <version>` -- not something a release does on its own.
+// The range is `^0.4.7`, so the site follows the newest 0.4.x automatically and
+// a 0.5.0 needs a deliberate bump. Note that `npm ci` is lockfile-exact, so the
+// range on its own would not move: both workflows run
+// `npm update --no-save @vantagecompute/docusaurus-theme` after installing to
+// take the newest release in range without writing a lockfile diff.
 //
 // From the theme rather than hand-rolled here, so every Vantage site advertises
 // its version the same way. It returns `git describe --tags --always`, so the

docusaurus/package.json

@@ -18,7 +18,7 @@
     "@docusaurus/preset-classic": "^3.10.2",
     "@docusaurus/theme-mermaid": "^3.10.2",
     "@mdx-js/react": "^3.1.1",
-    "@vantagecompute/docusaurus-theme": "0.4.7",
+    "@vantagecompute/docusaurus-theme": "^0.4.7",
     "clsx": "^2.1.1",
     "prism-react-renderer": "^2.4.1",
     "react": "^19.2.8",

justfile

@@ -30,12 +30,15 @@ clean:
 # Documentation site (docusaurus/)
 #
 # Published as a spoke under docs.vantagecompute.ai/developer/docusaurus-theme/.
-# It installs @vantagecompute/docusaurus-theme from npm at a PINNED version
-# rather than through a file: link to this working tree. That is deliberate: the
-# site then renders what consumers actually get, and a release that ships a
-# tarball missing something the build needs fails here first. The cost is that
-# the pin trails the package by up to one release -- move it with `docs-pin`
-# once the version is on npm.
+# It installs @vantagecompute/docusaurus-theme from npm rather than through a
+# file: link to this working tree. That is deliberate: the site then renders
+# what consumers actually get, and a release that ships a tarball missing
+# something the build needs fails here first.
+#
+# The declared range is ^0.4.7, so patch releases arrive on the next deploy with
+# no commit. `docs-pin` is for crossing a minor, which stays deliberate. Note
+# that `npm ci` is lockfile-exact, so both workflows run
+# `npm update --no-save @vantagecompute/docusaurus-theme` after installing.
 # ---------------------------------------------------------------------------
 
 # Install the docs site's dependencies
@@ -60,7 +63,8 @@ docs-build: docs-install
 docs-clean:
     rm -rf docusaurus/build docusaurus/.docusaurus
 
-# Point the docs site at a published theme version, and refresh its lockfile
+# Move the docs site's theme range to ^<version>, and refresh its lockfile.
+# Only needed to cross a minor: patch releases are already inside the range.
 [group("docs")]
 docs-pin version:
     #!/usr/bin/env bash
@@ -71,9 +75,9 @@ docs-pin version:
         exit 1
     fi
     cd docusaurus
-    npm pkg set 'dependencies.@vantagecompute/docusaurus-theme={{version}}'
+    npm pkg set 'dependencies.@vantagecompute/docusaurus-theme=^{{version}}'
     npm install
-    echo "✅ Docs site pinned to {{version}}. Commit docusaurus/package.json and package-lock.json."
+    echo "✅ Docs site now tracks ^{{version}}. Commit docusaurus/package.json and package-lock.json."
 
 # Bump version, commit, tag, push, and create GitHub release to trigger npm publish
 [group("release")]
@@ -104,5 +108,5 @@ help:
     @echo "  docs-serve      - Serve the docs site locally"
     @echo "  docs-build      - Build (and link-check) the docs site"
     @echo "  docs-clean      - Clean the docs site build output"
-    @echo "  docs-pin x.x.x  - Point the docs site at a published theme version"
+    @echo "  docs-pin x.x.x  - Move the docs site's theme range to ^x.x.x"
     @echo "  release x.x.x   - Bump, tag, push, and publish to npm"