Release routine and npm publish workflow

.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: publish
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.release.tag_name }}
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          registry-url: https://registry.npmjs.org
+      - name: Tag must match package.json
+        run: |
+          tag="${{ github.event.release.tag_name }}"
+          ver="$(node -p "require('./package.json').version")"
+          test "$tag" = "v$ver" || { echo "tag $tag != package.json v$ver"; exit 1; }
+      - run: node --test tests/*.test.js
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -17,6 +17,8 @@ no dependencies.
 git diff | npx --yes github:skelvar/offcut scan --diff -
 ```
 
+Pin a version with `npx --yes github:skelvar/offcut#v0.4.0 scan --diff -`; marketplace installs accept the same tag as `--ref v0.4.0`.
+
 ```text
 src/phone.js (1)
   [new-dependency] Offcut: new dependency — what does this replace that four lines could not do?
@@ -124,6 +126,25 @@ node scripts/build-agents-md.js   # AGENTS.md is generated from rules/offcut.md
 
 Harness notes and benchmark receipts: [docs/development](docs/development/README.md).
 
+### Release
+
+1. Bump every version field (`package.json`, `plugin.json`, the three plugin manifests, the two `marketplace.json` files, `scripts/build-agents-md.js`, `skills/offcut-{review,audit,help}/SKILL.md`), then run:
+
+   ```bash
+   node scripts/build-agents-md.js
+   node scripts/build-plugin-package.mjs
+   ```
+
+2. Merge the bump to main through a pull request (CI checks version parity and the generated files).
+
+3. ```bash
+   gh release create vX.Y.Z --target main --title "Offcut vX.Y.Z" --notes-file notes.md --latest
+   ```
+
+   The Releases page is not updated by the version fields; this step is what updates it.
+
+4. Publishing the release triggers `.github/workflows/publish.yml`, which publishes `@skelvar/offcut` to npmjs with provenance. It needs a repository secret `NPM_TOKEN` (an npm granular access token with publish rights on the `@skelvar` scope).
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

plugins/offcut/README.md

@@ -17,6 +17,8 @@ no dependencies.
 git diff | npx --yes github:skelvar/offcut scan --diff -
 ```
 
+Pin a version with `npx --yes github:skelvar/offcut#v0.4.0 scan --diff -`; marketplace installs accept the same tag as `--ref v0.4.0`.
+
 ```text
 src/phone.js (1)
   [new-dependency] Offcut: new dependency — what does this replace that four lines could not do?
@@ -124,6 +126,25 @@ node scripts/build-agents-md.js   # AGENTS.md is generated from rules/offcut.md
 
 Harness notes and benchmark receipts: [docs/development](docs/development/README.md).
 
+### Release
+
+1. Bump every version field (`package.json`, `plugin.json`, the three plugin manifests, the two `marketplace.json` files, `scripts/build-agents-md.js`, `skills/offcut-{review,audit,help}/SKILL.md`), then run:
+
+   ```bash
+   node scripts/build-agents-md.js
+   node scripts/build-plugin-package.mjs
+   ```
+
+2. Merge the bump to main through a pull request (CI checks version parity and the generated files).
+
+3. ```bash
+   gh release create vX.Y.Z --target main --title "Offcut vX.Y.Z" --notes-file notes.md --latest
+   ```
+
+   The Releases page is not updated by the version fields; this step is what updates it.
+
+4. Publishing the release triggers `.github/workflows/publish.yml`, which publishes `@skelvar/offcut` to npmjs with provenance. It needs a repository secret `NPM_TOKEN` (an npm granular access token with publish rights on the `@skelvar` scope).
+
 ## License
 
 MIT — see [LICENSE](LICENSE).