release

Releasing

package.json is the single source of truth for the version. The npm version lifecycle hook runs scripts/sync-version.mjs, which propagates it to src/version.ts, manifest.json, server.json (incl. the .mcpb release-asset URL), and CHANGELOG.md — it renames ## [Unreleased] to ## [<version>] - <date> and reopens a fresh, empty ## [Unreleased] above it, rolling the trailing compare-link block forward the same way; version.test.ts guards that the derived files never drift, and unit-tests the CHANGELOG rename directly (renderChangelogRelease). You do not need to rename the heading yourself — don't hand-edit it back to [Unreleased] after running npm version.

A preversion hook (scripts/preversion-check.mjs) runs first — it's a presence-only safety net, not a substitute for actually running the skill below as a real judgment step. It runs two checks, in order:

• Unpushed-tag race: if the current package.json version already has a local git tag, it blocks unless that tag is also on origin — this is the exact race that once orphaned a version in a sibling repo (npm version run twice within minutes, the first tag/commit never pushed, silently buried under the second). Push the dangling tag (git push origin vX.Y.Z) or delete it if it was a mistake (git tag -d vX.Y.Z), then retry.
• Empty changelog: it blocks npm version if CHANGELOG.md's [Unreleased] section is empty: run the changelog-style skill against the commits since the last tag first — it's what actually makes the entries short, self-describing, free of implementation detail, and linked to their commits; the hook only confirms something is there, not that it follows that style. (Or re-run with CONFIRM_EMPTY_CHANGELOG=1 if this release genuinely has no user-facing changes, e.g. a pure dependency bump.)

When invoked as this skill, run these as explicit steps, not optional — don't rely on the preversion hook alone to catch a skipped one:

1. Invoke the changelog-style skill against the commits since the last tag; write/fix the [Unreleased] entries per its style rules (heading rename happens later, automatically — see above).
2. Run the docs-consistency-check skill.
3. Commit all of the above.
4. npm version <patch|minor|major> — preversion gate, then bumps + syncs every file (including the CHANGELOG rename) + commits "release: vX.Y.Z"
   • tags vX.Y.Z.
5. git push --follow-tags — pushing the tag triggers .github/workflows/release.yml. Verify the tag actually reached the remote: git ls-remote --tags origin | grep vX.Y.Z. --follow-tags only pushes annotated tags (npm version's default) reachable from what's being pushed — if you ever re-tag by hand (e.g. git tag -f vX.Y.Z <commit> to fix something before pushing), that recreates it as a lightweight tag, which --follow-tags silently skips; push it explicitly instead (git push origin vX.Y.Z) and re-verify with git ls-remote. (Confirmed live 2026-07-29: a git tag -f without -a produced exactly this silent no-op.)

The tag push (v*) runs the Release workflow: check:api gate → build → test → pack .mcpb → GitHub Release → npm publish (OIDC trusted publishing, with provenance — no token) → publish to the official MCP Registry (mcp-publisher, GitHub OIDC; the binary is pinned to an exact version + verified SHA-256 rather than latest). The workflow's CHANGELOG-extraction step fails loudly (not silently) if it can't find a ## [<version>] section, as a backstop if the heading rename above is somehow bypassed. The npm publish step is itself pinned to an exact verified-good npm version — no token — and is skipped without failing the job if this version is already on npm, so a re-run after a partial failure doesn't abort. The .mcpb SHA-256 injection into server.json likewise fails loudly if the injection didn't actually match a package, instead of silently leaving a stale hash. Never hand-edit the version in the derived files; bump package.json via npm version and let the hook sync the rest.