chore(ci): prerelease pack artifacts and tag-triggered npm release

CI uploads an npm pack tarball per run (PR/main) as a downloadable artifact. New release workflow publishes to npm and attaches the pack to a GitHub Release when v*.*.* tags match package.json version; document NPM_TOKEN and flows in HUMANS and AGENTS.

Author: AlbinoGeek

.github/workflows/ci.yml

@@ -26,3 +26,40 @@ jobs:
 
       - name: Unit tests
         run: bun run test
+
+  prerelease-pack:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.11
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Pack npm tarball (prerelease snapshot)
+        id: pack
+        run: |
+          set -euo pipefail
+          npm pack
+          SRC=$(ls -t rethunk-mcp-multi-root-git-*.tgz | head -1)
+          DEST="rethunk-mcp-multi-root-git-prerelease-${{ github.sha }}.tgz"
+          mv "$SRC" "$DEST"
+          echo "tarball=$DEST" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: npm-pack-prerelease-${{ github.sha }}
+          path: ${{ steps.pack.outputs.tarball }}
+          if-no-files-found: error
+          retention-days: 90

.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.11
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Lint and format check
+        run: bun run check
+
+      - name: Unit tests
+        run: bun run test
+
+      - name: Verify git tag matches package.json version
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG=$(node -p "require('./package.json').version")
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::Git tag v$TAG must match package.json version $PKG (publish aborted)."
+            exit 1
+          fi
+
+      - name: Create tarball for GitHub Release
+        id: pack
+        run: |
+          set -euo pipefail
+          npm pack
+          echo "tarball=$(ls -t rethunk-mcp-multi-root-git-*.tgz | head -1)" >> "$GITHUB_OUTPUT"
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Upload release asset
+        uses: softprops/action-gh-release@v2
+        with:
+          files: ${{ steps.pack.outputs.tarball }}
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

AGENTS.md

@@ -34,7 +34,7 @@
 
 ## Validation and CI
 
-Local: `bun run build` (`rimraf dist && tsc`), `bun run check` (Biome), `bun run test` (`bun test` for [`src/repo-paths.test.ts`](src/repo-paths.test.ts)). CI runs the same after `bun install --frozen-lockfile` (see [`.github/workflows/ci.yml`](.github/workflows/ci.yml)).
+Local: `bun run build` (`rimraf dist && tsc`), `bun run check` (Biome), `bun run test` (`bun test` for [`src/repo-paths.test.ts`](src/repo-paths.test.ts)). GitHub Actions runs the same after `bun install --frozen-lockfile` on PRs and `main` ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)), then uploads a **prerelease `npm pack` artifact**. Pushes of tag **`v*.*.*`** matching `package.json` `version` run [`.github/workflows/release.yml`](.github/workflows/release.yml) (npm publish + GitHub Release); see [HUMANS.md](HUMANS.md) Publishing.
 
 Optional [`.githooks/`](.githooks): run **`bun run setup-hooks`** once per clone (`core.hooksPath` → `.githooks`). **pre-commit** = `check`; **pre-push** = frozen install + build + check. See [HUMANS.md](HUMANS.md) Development.
 

HUMANS.md

@@ -86,10 +86,23 @@ bun run setup-hooks   # once per clone: use .githooks (pre-commit: check; pre-pu
 
 **Git hooks:** after `setup-hooks`, **pre-commit** runs `bun run check`; **pre-push** runs `bun install --frozen-lockfile`, `bun run build`, `bun run check`, and `bun run test` (same order as CI). Set **`SKIP_GIT_HOOKS=1`** or use **`--no-verify`** to bypass.
 
-**CI:** pull requests run `bun install --frozen-lockfile`, `bun run build`, `bun run check`, and `bun run test` (see `.github/workflows/ci.yml`). Match that locally before opening a PR.
+**CI:** [`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs on pull requests and pushes to `main`: `bun install --frozen-lockfile`, `bun run build`, `bun run check`, and `bun run test`. A follow-up job **`prerelease-pack`** builds the same tree and runs **`npm pack`**, then uploads a **prerelease `.tgz` artifact** (named with the commit SHA) you can download from the workflow run’s **Artifacts** section (retention 90 days). Match the check job locally before opening a PR.
 
 ## Publishing
 
+### npm (production) — version tags only
+
+Releases to [npmjs](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git) are automated by [`.github/workflows/release.yml`](.github/workflows/release.yml) when you push a **semver git tag** `vX.Y.Z` that **exactly matches** `version` in `package.json` (e.g. tag `v1.2.3` and `"version": "1.2.3"`).
+
+1. Bump **`package.json` `version`**, commit on `main`.
+2. Create and push the tag: `git tag vX.Y.Z && git push origin vX.Y.Z`
+
+The workflow runs build, check, and tests, publishes with **`npm publish`**, then creates a **GitHub Release** for that tag and attaches the same **`.tgz`** as a downloadable asset.
+
+**Repository secret:** add **`NPM_TOKEN`** (granular npm access token with publish permission for `@rethunk/mcp-multi-root-git` or the scope). Without it, the publish step fails.
+
+### Local publish (maintainers)
+
 ```bash
 bun run prepublishOnly  # build + check + test
 bun publish