> ## Documentation Index > Fetch the complete documentation index at: https://toolgrain.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Versioning and releases > Changesets release planning, automated publication, verification, and recovery. All six libraries share a stable version under npm's `latest` tag. Check [npm](https://www.npmjs.com/package/@toolgrain/mcp) for the current version and [package releases](https://github.com/keshavkatwe/toolgrain/releases) for release notes. The historical [v0.1.0 release](https://github.com/keshavkatwe/toolgrain/releases/tag/v0.1.0) and [RC0 prerelease](https://github.com/keshavkatwe/toolgrain/releases/tag/v0.1.0-rc.0) remain available. `next` still points to RC0. Changesets automation is active on `main`, with package-local changelogs and package-scoped GitHub releases. The publication workflow owns main-branch verification. It calls ordinary scoped CI/support checks when no publication is planned, and complete release verification when publishing. This avoids duplicate baseline/platform runs on release commits. The `publish.yml` filename, `npm` environment, and trusted-publisher bindings stay the same. ## Verified automated release The first complete automated cycle published **0.1.1** for all six libraries on 2026-10-26. [Release PR #37](https://github.com/keshavkatwe/toolgrain/pull/37) merged as commit `fed5a82826e66b485bad7cdb86fbc2238ae7a3e4`. The [publication run](https://github.com/keshavkatwe/toolgrain/actions/runs/40274053979) passed release verification, the supported runtime/platform matrix, archive packing, npm publication, package tags/releases, and registry integrity checks. Both **Published node consumers** and **Published bun consumers** passed against the public packages after publication. These results verify this release cycle; client-flow coverage remains limited to the [compatibility reports](https://toolgrain.mintlify.site/compatibility/protocol.md). ## Record a change Run `bun run changeset` for a user-facing library change. Select affected libraries, a bump type, and write release notes that explain the behavior and any migration steps. Include the Markdown record with the implementation when committing is authorized. Use `bun run changeset --empty` for repository-only changes that need no library release. Release PR versioning consumes all Changeset records. Keep that state when fixing a versioned Release PR: the pinned action selects no publication when only empty records remain. Consume an empty record during versioning rather than carrying a fresh one into the release merge. The pinned Changesets CLI 3.0.3 selects versions and updates dependencies. The six libraries form one explicit fixed group in `.changeset/config.json` and share a version; their manifests are the source of truth. Examples and repository tooling are unpublished npm workspaces and are ignored by Changesets. During `0.x`, compatible fixes use patch records, while features and breaking changes use minor records. From `1.0`, follow semantic versioning. The [support policy](https://toolgrain.mintlify.site/project/support-policy.md), including minimum increases and removal notices, still applies. `bun run release:status` previews the pending plan. Package-local `CHANGELOG.md` files are generated by Changesets and become the source for release notes. Review their summaries and migration guidance in the Release PR. The root [CHANGELOG.md](https://github.com/keshavkatwe/toolgrain/blob/main/CHANGELOG.md) preserves the historical RC0/0.1.0 notes; it is no longer a second release ledger that must be edited for each change. ## Automated release PR and publication The `npm publication` workflow runs on pushes to `main`, using Changesets Action v2.1.2's native `select-mode`, `version`, `pack`, and `publish` subactions. Its commit is pinned; CLI and Action upgrades must be reviewed together. 1. Merge an ordinary reviewed change with its changeset. Changesets creates or updates **Release Toolgrain packages** on `changeset-release/main`. 2. The bot runs `bun run release:version`, consuming records, updating all six versions/dependencies and package changelogs, and synchronizing Bun workspace versions. Review that diff and the CI results. With `GITHUB_TOKEN`, GitHub can require a maintainer to **Approve workflows to run** for bot-created PR runs; approve those runs during review. No personal token is required. 3. Merge the reviewed Release PR when ready to publish. **This merge approves automatic npm publication, package tags, and GitHub releases.** The workflow does not auto-merge the PR. Bot version commits/PRs are authorized by this automation policy; local agent commits still need an explicit user request. 4. On the merged main commit, the workflow runs Release verification: baseline, the full supported runtime/platform matrix, intermediate TypeScript versions, and stable dependency drift. Supported failures block publication; Node 26 and prerelease probes remain informational. 5. A separate job builds the libraries, checks contents and size budgets, and uses Changesets to create packed archives and its publish-plan artifact. Only the publish job gets OIDC permission. It publishes those archives to npm under `latest`, pushes package tags, and creates six GitHub releases from their package changelogs. Names follow `@toolgrain/mcp@0.1.1`, for example. 6. Post-publication checks verify all six `latest` tags in full and installer npm metadata, registry integrity, and downloaded archive bytes against the packed artifact. Fresh npm/Node and Bun consumers then check all six imports, minimum/current declarations, and the stdio/HTTP runtime flows. Reports are retained as workflow artifacts. A post-publication failure needs investigation; npm publication cannot be rolled back by a failed check. No local version bump, manual npm publish, combined `vX.Y.Z` tag, or separate GitHub release command is needed for this flow. The existing `v0.1.0` and RC0 release records are preserved. Repository-only changes use empty changesets and do not select a library release. User-facing changesets create or update the next automated Release PR. ## npm publication setup Only the six libraries are publishable, with public access, the explicit npmjs registry, and stable `latest` configuration. The workflow retains filename `publish.yml`, environment `npm`, and the six validated trusted-publisher bindings for `keshavkatwe/toolgrain`. No npm token secret or local login is required. The environment permits only main; it has no required reviewers. The reviewed Release PR is the publication gate. GitHub Actions must be allowed to create pull requests in repository settings (**Actions → General → Allow GitHub Actions to create and approve pull requests**). Keep default workflow permissions read-only. The version job requests pull-request write access; the reused baseline retains its PR-report permission. The workflow never approves reviews itself. External workflow Actions are pinned to full upstream commit SHAs. When updating an Action, verify the new commit in its canonical repository and update every reference, including composite actions. The repository's Actions allowlist must permit the new pin before workflows use it. Enable the full-SHA policy only after all active workflow branches use pinned references. The active tag ruleset blocks updates and deletions for every tag, without bypass actors. New release tags can still be created by the publication workflow. The source repository is public, so publications automatically request npm provenance. RC0 and 0.1.0 were published without provenance while the source was private. All six trusted publishers completed their first successful OIDC publication for 0.1.0; a new or replacement binding must complete its first successful publish within npm's two-day validation window. Changesets does not currently support Bun natively. The workflow-only npm adapter preserves the native planner, packed-artifact format, publishing order, tag reporting, and GitHub release handling. It uses Bun 1.3.14 to pack archives with rewritten `workspace:*` dependencies. Registry reads and npm 11.21.1 archive publication run outside the checkout, where npm does not encounter the repository's intentional Bun `devEngines` requirement. Archive lifecycle scripts are disabled. Ordinary development continues to use Bun. `release:version` retains the existing narrow Bun workaround: Bun 1.3.14 leaves stale workspace versions during lockfile-only installs, and packing reads them. The helper synchronizes only those six version fields, preserving external resolutions. `bun run release:check [--version X.Y.Z]` checks manifest/lock alignment. It does not select versions or write changelogs. ## Failures and recovery Six-package publication is not atomic. Inspect the run, its plan/archive artifacts, npm versions/tags, and GitHub tags/releases before recovery. Never unpublish or replace an existing version. The manual **Run workflow** action on main runs the same planner and all verification gates; it does not bypass them. Prefer a fresh run after checking partial state so Changesets can replan around already-published versions, rather than replaying a stale packed publish job. Existing remote tags with missing GitHub releases need explicit inspection and repair; the native action does not guarantee recreating missing release records. A maintainer can still dispatch **Release verification** on main with an expected version without publishing. Local preparation can use `release:status`, `release:version`, and `release:check` in a disposable checkout; do not version main manually alongside the bot's Release PR. This automation is intentionally for stable releases. It refuses prerelease state or versions. A future RC series needs a reviewed channel policy/workflow change before entering Changesets prerelease mode. Do not repeat the initial 0.0.0 bootstrap used to select RC0. The stable baseline's documented client limitations remain in the [published-package verification](https://toolgrain.mintlify.site/compatibility/published-packages.md). References: [Changesets automation](https://changesets.dev/guide/automating), [Action v2.1.2](https://github.com/changesets/action/tree/v2.1.2), and [GitHub workflow triggering rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.