| name | cbt-release |
| description | Publish @blit386/kit and create-blit386 to npm following the workspace PUBLISHING.md procedure. Publishing is manual-only (pnpm publish from vancura's machine) -- there is no CI publish workflow. Does not bump versions unless the user asks. |
Release (npm publish)
Guide a deliberate release of @blit386/kit and create-blit386. This skill does not auto-bump versions, open PRs,
push tags, or publish unless the user explicitly requests those steps.
Canonical procedure: workspace parent PUBLISHING.md (from this repo root: ../PUBLISHING.md when the three repos
share the _BLIT386_ parent folder). This skill mirrors it — if they ever disagree, PUBLISHING.md wins and this skill
is stale.
Usage
/cbt-release
Publishing is manual-only
There is no .github/workflows/publish.yml and no NPM_TOKEN secret. Nothing publishes on a tag push. Every release is
pnpm publish run by hand from vancura's machine, after npm login locally. This is a deliberate policy (2026-07-14,
see CREATE_BLIT386_DESIGN.md top status block and changelog) after the tag-driven workflow failed with ENEEDAUTH on
the 1.2.1 release because the NPM_TOKEN secret was missing — rather than re-provision it, CI publishing was removed
outright. Do not suggest re-adding a publish workflow or an NPM_TOKEN secret.
Tags are still cut and pushed after a manual publish, purely as a release marker in the repo history — they trigger
nothing.
Golden rules (never skip)
- Engine first. If this release's kit content documents a new engine API (for example audio –
content/docs/audio.md, the play-a-sound / design-a-sound skills), find the exact engine version that content
requires (check its own version callouts, e.g. audio.md's "Sound arrived in blit386 1.3.0" – don't assume
BLIT386_RANGE / blit386.engineRange are current, they may still lag behind and are only bumped in step 2 below),
then confirm via npm view blit386 version that the published version already satisfies it. Publishing kit
docs/skills ahead of the engine sends a twelve-year-old's AI assistant instructions for an API that does not exist
yet.
- Always
pnpm publish, never npm publish – only pnpm rewrites workspace:* to a real version.
- Publish
@blit386/kit before create-blit386 – the scaffolder depends on the kit.
- Versions are permanent – bump before republishing; never reuse a published version. Both packages release in lockstep
on the same version number.
- Release tags carry no
v prefix (1.2.0, not v1.2.0).
engineRange (kit package.json) and BLIT386_RANGE (scaffolder) are not the same mechanism. engineRange feeds
blit doctor's compatibility check against an already-installed engine on an existing project — leaving it stale
makes blit doctor report a false "compatible" once the kit's own content documents newer engine API than the range
admits. BLIT386_RANGE only affects what a fresh scaffold pins, and npm install always resolves that to the latest
version satisfying the range regardless of the exact floor. Bump both together for consistency, but engineRange is
the one doing safety-critical work.
Procedure
1. Confirm the engine dependency is satisfied
See golden rule 1. If nothing new in this release documents a new engine API, skip straight to step 2.
2. Bump versions
cd packages/kit && npm version patch --no-git-tag-version && cd ../..
cd packages/create-blit386 && npm version patch --no-git-tag-version && cd ../..
Use minor or major instead of patch when appropriate – both packages must land on the same version.
Also check whether BLIT386_RANGE in packages/create-blit386/src/scaffold.ts and blit386.engineRange in
packages/kit/package.json need updating (see golden rule 6).
3. Check locally, then land the bump through a PR
pnpm install
pnpm run preflight
main is protected: push a branch, open a PR, wait for checks, and squash-merge it. The version bump has to be on
main before you publish, because you publish from the merged commit.
4. Publish
git checkout main && git pull
npm whoami
pnpm --filter @blit386/kit publish --dry-run
pnpm --filter @blit386/kit publish
pnpm --filter create-blit386 publish --dry-run
pnpm --filter create-blit386 publish
pnpm publish refuses a dirty tree — commit first, or pass --no-git-checks only with explicit user sign-off.
If the browser-based OTP auth URL npm prints is redacted or unusable in the current terminal (some sandboxed/relayed
shells redact anything that looks like an auth token), have the user run the publish command in a plain, unproxied
terminal instead, or provide a 6-digit code from their authenticator app for --otp=.
5. Tag the release
git tag 1.2.1
git push origin 1.2.1
This is a record, not a trigger — nothing listens for it.
6. Verify the registry
npm view @blit386/kit version
npm view create-blit386 version
7. Smoke test (once the registry has propagated)
cd /tmp
npm create blit386@latest smoke-test
cd smoke-test
npm install
npm run dev
npx blit doctor
blit doctor's "blit386 X.Y.Z is compatible with this kit (^X.Y.Z)" line is a good live check that the engineRange
bump from step 2 actually took effect.
8. Publish the GitHub Release
Release notes are hand-written, not generated from commit messages. Draft them from the merged PRs since the last tag,
matching the style of prior releases at https://github.com/blit386/create-blit386/releases, then:
gh release create 1.2.1 --title "Release 1.2.1" --notes-file <path>
Troubleshooting
See Troubleshooting in PUBLISHING.md for the tag-pattern gotcha (no v prefix), 404 propagation lag, E401, EOTP,
dirty tree, version reuse (402), and scoped package access issues.
Report to the user
After a successful release:
- Published versions for
@blit386/kit and create-blit386
- Whether the engine-first gate applied, and what
npm view blit386 version showed
- Whether
BLIT386_RANGE / blit386.engineRange or kit content/docs/ were updated in the same release
- Confirmation the release tag (no
v prefix) is pushed and points at the merged main commit, and that the GitHub
Release is published
