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 and server.json (incl. the .mcpb release-asset URL); version.test.ts guards that they never drift. The same script also dates CHANGELOG.md's [Unreleased] section into this version's own heading (and leaves a fresh empty [Unreleased] above it) — don't hand-retitle it yourself, before or after npm version; that manual step was forgotten twice before this automation existed. version.test.ts guards this too (the newest dated heading must match package.json's version).

A preversion hook (scripts/preversion-check.mjs) runs first, with two checks:

• 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 [Unreleased]: presence-only safety net, not a substitute for actually running the skill below as a real judgment step. 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.
2. Run the docs-consistency-check skill.
3. STEAM_API_KEY=... npm run check:api locally with your own key, to also exercise the key-gated player endpoints (GetOwnedGames, GetFriendList, GetPlayerBans, ResolveVanityURL, GetSchemaForGame, …) against live Steam — release.yml runs check:api with no STEAM_API_KEY secret configured, so its key-gated checks always skip there and only the keyless Storefront/Web API checks actually gate CI.
4. Commit everything from steps 1–2.
5. Confirm every check the release was gated on actually finished and reported. A verification that is still running, or that died partway (a subagent lost to an API error, a tool outage), is not a pass — either re-run it to completion or tell the user which surface is unverified and let them decide. Your own narrower re-check is not a substitute: it is built from the diff you just wrote, so it inherits the same blind spots, while the skill's checklist is what covers the tools you did not touch. discover_games shipped in v0.13.0 with no output cap this way — a relaunched sweep was mid- flight at tag time and reported that blocker half an hour after publish.
6. npm version <patch|minor|major> — preversion gate, then bumps + syncs every file + commits "release: vX.Y.Z" + tags vX.Y.Z.
7. git push --follow-tags — pushing the tag triggers .github/workflows/release.yml.

The tag push (v*) runs the Release workflow: check:api gate → build → test → pack .mcpb → extract CHANGELOG.md's section for this version (fails loudly, not silently, if that section is empty — the workflow's own safety net for whatever slipped past sync-version.mjs/preversion-check.mjs) → GitHub Release → npm publish (OIDC trusted publishing, with provenance, pinned to an exact verified-good npm version — no token; skipped without failing the job if this version is already on npm, so a re-run after a partial failure doesn't abort) → inject the just-packed .mcpb's SHA-256 into server.json (fails loudly if the injection didn't actually match a package, instead of silently leaving a stale hash) → publish to the official MCP Registry (mcp-publisher, GitHub OIDC; mcp-publisher itself is pinned to an exact version + verified SHA-256 rather than latest, since this step runs with live OIDC publishing credentials). Never hand-edit the version in the derived files; bump package.json via npm version and let the hook sync the rest.