Fix release workflow OIDC auth and add republish mode

.github/workflows/release.yml

@@ -12,6 +12,11 @@ on:
           - patch
           - minor
           - major
+      skip_bump:
+        description: 'Skip version bump (republish current version). When true, the `version` input above is ignored and the current package.json version is published as-is. Useful when a previous run succeeded at tagging/release creation but failed at npm publish.'
+        required: false
+        default: false
+        type: boolean
 
 jobs:
   release:
@@ -29,6 +34,16 @@ jobs:
           node-version: '22'
           cache: npm
 
+      - name: Upgrade npm (required for OIDC trusted publishing)
+        # OIDC trusted publishing requires npm >= 11.5.1. Node 22 ships with
+        # npm 10.x, which falls back to traditional auth and fails with
+        # ENEEDAUTH. We pin to npm@11 (major range) rather than @latest to
+        # avoid a MODULE_NOT_FOUND bug in the bundled npm's self-upgrade
+        # path when targeting @latest. If this ever breaks, a corepack-based
+        # fallback (`corepack prepare npm@latest --activate`) is the next
+        # option to try.
+        run: npm install -g npm@11
+
       # ── Test gate ─────────────────────────────────────────────────────
       # Install, build, and test BEFORE any mutating action (version bump,
       # git push, GitHub release, npm publish). If tests fail, the job
@@ -54,14 +69,17 @@ jobs:
 
       - name: Bump version
         id: bump
+        if: inputs.skip_bump != true
         run: |
           npm version ${{ inputs.version }} -m "chore: release v%s"
           echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
 
       - name: Push changes
+        if: inputs.skip_bump != true
         run: git push --follow-tags
 
       - name: Create GitHub Release
+        if: inputs.skip_bump != true
         uses: softprops/action-gh-release@v2
         with:
           tag_name: v${{ steps.bump.outputs.version }}

documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md

@@ -0,0 +1,21 @@
+## Problem
+
+The previous release workflow attempt reached the publish step but failed to authenticate with npm, even though everything upstream had completed successfully — tag created, GitHub release page live. The underlying cause was that the `npm` version shipped with the GitHub Actions runner is too old to use our secure publishing path.
+
+A prior change in this repo had removed the step that upgrades `npm`, assuming it was no longer needed. That turned out to be wrong: the upgrade is necessary for our preferred authentication method to work. Simply putting the old step back doesn't work either, because the bundled `npm` has a bug when upgrading itself to the latest version.
+
+## Solution
+
+Two changes:
+
+1. Restore the `npm` upgrade with a safer target version, avoiding the bundled bug.
+2. Add a "skip version bump" option to the release workflow so we can finish publishing a version whose tag and GitHub release already exist but whose npm publish failed partway through — without re-bumping the version.
+
+## Impact
+
+Once this merges, we can complete the stalled `v1.1.0` release by running the workflow with the skip-bump option enabled. Future releases will use the normal full flow.
+
+# Credits
+
+- Nabs (Architect)
+- JENA (Lead Developer)