ci: add npm publish workflow

Author: codexstar69

.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Run tests
+        run: node --test scripts/tests/*.test.cjs
+
+      - name: Verify release tag matches package version
+        if: github.event_name == 'release'
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          PACKAGE_VERSION="$(node -p "require('./package.json').version")"
+          TAG_VERSION="${RELEASE_TAG#v}"
+
+          if [ "$PACKAGE_VERSION" != "$TAG_VERSION" ]; then
+            echo "package.json version $PACKAGE_VERSION does not match release tag $RELEASE_TAG"
+            exit 1
+          fi
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- GitHub Actions npm publish workflow on release publish or manual dispatch, with version/tag verification before `npm publish`
+
 ## [3.0.4] — 2026-03-11
 
 ### Added

handoff.md

@@ -24,6 +24,8 @@
 - The structured-output migration plan is effectively complete; the remaining
   follow-up is only secondary doc cleanup where old `*.md` artifact wording may
   still appear in historical text.
+- Added `.github/workflows/publish.yml` so GitHub releases can publish the npm
+  package automatically once `NPM_TOKEN` is configured in repo secrets.
 
 ## Last prompts
 
@@ -55,12 +57,15 @@ Both passed on 2026-03-11.
 - `docs/plans/2026-03-11-structured-output-migration-plan.md`
 - `CHANGELOG.md`
 - `package.json`
+- `.github/workflows/publish.yml`
 
 ## Next steps
 
 - sweep remaining secondary docs for stale `*.md` phase-artifact references
 - decide whether `run-bug-hunter.cjs phase` should be documented in README or
   kept as an internal orchestration helper only
+- add repo secret `NPM_TOKEN`, then either rerun `v3.0.4` publish manually or
+  wait for the next tagged GitHub release
 
 ## Environment