ci(release): publish to GitHub Packages only; document manual npmjs

Drop npmjs automation and NPM_TOKEN. Tag workflow publishes @rethunk-ai/mcp-multi-root-git to npm.pkg.github.com (ephemeral package.json patch for required org scope), keeps GitHub Release tarball from @rethunk name. HUMANS/install/README/AGENTS describe GPR vs manual npm publish.

Author: AlbinoGeek

.github/workflows/release.yml

@@ -14,13 +14,13 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      packages: write
     steps:
       - uses: actions/checkout@v6
 
       - uses: actions/setup-node@v6
         with:
           node-version: "24"
-          registry-url: "https://registry.npmjs.org"
 
       - uses: oven-sh/setup-bun@v2
         with:
@@ -58,10 +58,26 @@ jobs:
           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
+      - name: Publish to GitHub Packages (npm registry)
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          node <<'NODE'
+          const fs = require("node:fs");
+          const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+          p.name = "@rethunk-ai/mcp-multi-root-git";
+          p.publishConfig = {
+            registry: "https://npm.pkg.github.com",
+            access: "public",
+          };
+          fs.writeFileSync("package.json", JSON.stringify(p, null, 2) + "\n");
+          NODE
+          {
+            echo "@rethunk-ai:registry=https://npm.pkg.github.com"
+            echo "//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}"
+          } > .npmrc
+          npm publish --access public
 
       - name: Create GitHub Release (official gh CLI, no third-party action)
         env:

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)). 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.
+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) (**GitHub Packages** npm publish under **`@rethunk-ai/mcp-multi-root-git`** + **GitHub Release** with tarball); **npmjs** is manual only — 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

@@ -43,6 +43,8 @@ With **multiple MCP file roots**, the server picks a root whose git toplevel def
 }
 ```
 
+If you installed from **GitHub Packages**, use **`./node_modules/@rethunk-ai/mcp-multi-root-git/git-mcp-presets.schema.json`** in **`$schema`** instead (see [docs/install.md](docs/install.md#github-packages)).
+
 **Layouts:**
 
 1. **Wrapped (recommended):** `{ "schemaVersion": "1", "presets": { "<name>": { ... } } }`.
@@ -90,22 +92,24 @@ bun run setup-hooks   # once per clone: use .githooks (pre-commit: check; pre-pu
 
 ## Publishing
 
-### npm (production) — version tags only
+### GitHub (automated) — 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"`).
+Tag pushes run [`.github/workflows/release.yml`](.github/workflows/release.yml): build, check, tests, then:
 
-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`
+1. **`npm pack`** using the committed **`package.json`** name [`@rethunk/mcp-multi-root-git`](https://github.com/Rethunk-AI/mcp-multi-root-git) — tarball attached to a **GitHub Release** for that tag.
+2. **GitHub Packages** (npm registry): the workflow temporarily rewrites the package **name** to **`@rethunk-ai/mcp-multi-root-git`** (required scope for org `Rethunk-AI` on GitHub) and runs **`npm publish`** to **`https://npm.pkg.github.com`** with **`GITHUB_TOKEN`** (`packages: write`). No npmjs token is used in CI.
 
-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.
+Prerequisite: push a **semver git tag** `vX.Y.Z` that **exactly matches** `version` in `package.json` (e.g. `v1.2.3` and `"version": "1.2.3"`).
 
-**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.
+### npmjs (manual) — maintainers only
 
-### Local publish (maintainers)
+npmjs no longer fits an unattended CI publish flow for this org; **do not** rely on automation to [npmjs](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git). To publish the **same** package name consumers already use (**`@rethunk/mcp-multi-root-git`**):
 
-```bash
-bun run prepublishOnly  # build + check + test
-bun publish
-```
+1. On a clean checkout at the release commit (usually **`main`** after bumping version), run **`bun run prepublishOnly`** (or `bun run build && bun run check && bun run test`).
+2. Log in to the public registry once per machine: **`npm login`** (or `npm adduser`) so **`npm whoami`** shows the account that owns **`@rethunk`** on npmjs.
+3. Ensure **`package.json`** still has **`"name": "@rethunk/mcp-multi-root-git"`** and **`publishConfig.access`** is **`"public"`** (no **`publishConfig.registry`** pointing at GitHub — leave default registry for npmjs).
+4. Publish: **`npm publish --access public`** (runs **`prepublishOnly`** again unless you pass **`--ignore-scripts`** after you already verified locally).
+
+**`package.json` `files`** must keep the whole **`dist/`** directory so every emitted chunk the entry imports is packed; if you add new `src/server/*.ts` modules, `tsc` emits matching **`dist/server/*.js`** files — do not narrow **`files`** back to a single **`server.js`** or installs break.
 
-`npm publish` works if `dist/` is built and checks pass. **`package.json` `files` includes the whole `dist/` directory** so every emitted chunk the entry imports is packed; if you add new `src/server/*.ts` modules, `tsc` will emit matching `dist/server/*.js` files—do not narrow `files` back to a single `server.js` or installs will break.
+**Preset `$schema`:** after **`npm install`**, the schema path is under **`node_modules/@rethunk/mcp-multi-root-git/`** for npmjs, or **`node_modules/@rethunk-ai/mcp-multi-root-git/`** when installing from GitHub Packages — adjust **`$schema`** accordingly (see [docs/install.md](docs/install.md)).

README.md

@@ -2,14 +2,16 @@
 
 [![CI](https://github.com/Rethunk-AI/mcp-multi-root-git/actions/workflows/ci.yml/badge.svg)](https://github.com/Rethunk-AI/mcp-multi-root-git/actions/workflows/ci.yml)
 [![Release](https://github.com/Rethunk-AI/mcp-multi-root-git/actions/workflows/release.yml/badge.svg)](https://github.com/Rethunk-AI/mcp-multi-root-git/actions/workflows/release.yml)
+[![GitHub release](https://img.shields.io/github/v/release/Rethunk-AI/mcp-multi-root-git?logo=github&label=release)](https://github.com/Rethunk-AI/mcp-multi-root-git/releases/latest)
 [![npm version](https://img.shields.io/npm/v/%40rethunk%2Fmcp-multi-root-git.svg)](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git)
 [![npm downloads](https://img.shields.io/npm/dm/%40rethunk%2Fmcp-multi-root-git.svg?label=npm%20downloads)](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git)
+[![GitHub Packages](https://img.shields.io/badge/github%20packages-%40rethunk--ai%2Fmcp--multi--root--git-24292f?logo=github)](https://github.com/Rethunk-AI/mcp-multi-root-git/pkgs/npm/mcp-multi-root-git)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22-339933.svg)](https://github.com/Rethunk-AI/mcp-multi-root-git/blob/main/package.json)
 
 Read-only **git** tools over MCP (status, multi-root inventory, `HEAD` parity, presets). **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
 
-**Repository:** [github.com/Rethunk-AI/mcp-multi-root-git](https://github.com/Rethunk-AI/mcp-multi-root-git) · **npm:** [`@rethunk/mcp-multi-root-git`](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git)
+**Repository:** [github.com/Rethunk-AI/mcp-multi-root-git](https://github.com/Rethunk-AI/mcp-multi-root-git) · **npmjs (manual releases):** [`@rethunk/mcp-multi-root-git`](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git) · **GitHub Packages (CI on each tag):** [`@rethunk-ai/mcp-multi-root-git`](https://github.com/Rethunk-AI/mcp-multi-root-git/pkgs/npm/mcp-multi-root-git) — see [docs/install.md](docs/install.md) and [HUMANS.md](HUMANS.md) Publishing.
 
 ## Documentation
 

docs/install.md

@@ -7,6 +7,7 @@ This package is an MCP **stdio** server. The client starts the process and passe
 ## Table of contents
 
 - [Prerequisites](#prerequisites)
+- [GitHub Packages](#github-packages)
 - [Ways to run the binary](#ways-to-run-the-binary)
 - [Configuration shape (stdio)](#configuration-shape-stdio)
 - [Cursor](#cursor)
@@ -22,17 +23,46 @@ This package is an MCP **stdio** server. The client starts the process and passe
 - **Git** on `PATH` (`git --version`). The server shells out to `git`; if it is missing, tools return `git_not_found`.
 - **Node.js ≥ 22** if you use **`npx`**, or **Bun** if you use **`bunx`** / **`bun`** (see `package.json` `engines` / `packageManager`).
 
+## GitHub Packages
+
+Every **version tag** on this repo is published to the **GitHub npm registry** as **`@rethunk-ai/mcp-multi-root-git`** (scope matches the GitHub org). The **npmjs** package name **`@rethunk/mcp-multi-root-git`** is updated **manually** by maintainers and may lag; prefer GitHub Packages for CI-aligned installs.
+
+1. Create a [GitHub personal access token](https://github.com/settings/tokens) with at least **`read:packages`** (and **`repo`** if the package were private).
+2. In **`~/.npmrc`** or the project **`.npmrc`** (do not commit secrets):
+
+   ```ini
+   @rethunk-ai:registry=https://npm.pkg.github.com
+   //npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE
+   ```
+
+3. Install or run, for example:
+
+   ```bash
+   npx -y @rethunk-ai/mcp-multi-root-git
+   ```
+
+   Or **`bunx @rethunk-ai/mcp-multi-root-git`** with the same registry configuration for that scope.
+
+**`$schema` in preset JSON:** point at the copy under **`node_modules/@rethunk-ai/mcp-multi-root-git/git-mcp-presets.schema.json`** when you install from GitHub Packages; use **`@rethunk/mcp-multi-root-git/...`** when installing from npmjs.
+
 ## Ways to run the binary
 
-Use any of these from a terminal to confirm the package runs (each starts the stdio server until EOF):
+Use any of these from a terminal to confirm the package runs (each starts the stdio server until EOF). **npmjs** name:
 
 ```bash
 npx -y @rethunk/mcp-multi-root-git
 bunx @rethunk/mcp-multi-root-git
 npm install -g @rethunk/mcp-multi-root-git && mcp-multi-root-git
 ```
 
-Published entrypoint: **`dist/server.js`** (see npm `bin` / `exports`). Clients typically invoke **`npx`** or **`bunx`** so a global install is optional.
+**GitHub Packages** name (after configuring **`.npmrc`** as in [GitHub Packages](#github-packages)):
+
+```bash
+npx -y @rethunk-ai/mcp-multi-root-git
+bunx @rethunk-ai/mcp-multi-root-git
+```
+
+Published entrypoint: **`dist/server.js`** (see `bin` / `exports`). Clients typically invoke **`npx`** or **`bunx`** so a global install is optional.
 
 ## Configuration shape (stdio)