mental / rules

---
description: Git tag vX.Y.Z, package.json, and the published npm version must be the same string.
alwaysApply: true
---

# Release versions (lockstep)

`package.json` `version` is source of truth. Git tag is `v` plus that string. npm must publish that same string. A GitHub Release is not done until `npm view @balacode/mental version` equals it.

## Before tagging

1. `node scripts/bump-version.mjs X.Y.Z` then `node scripts/bump-version.mjs --check`
2. Cut CHANGELOG `[Unreleased]` into `## [X.Y.Z] - YYYY-MM-DD`
3. Commit on `main` (prod) or `staging` (beta `X.Y.Z-beta.N`)
4. Tag **only** `vX.Y.Z` (or `vX.Y.Z-beta.N`). Never a tag that does not equal `package.json`.

## After GitHub Release

`.github/workflows/release.yml` publishes with `secrets.NPM_TOKEN` as `NODE_AUTH_TOKEN`. Watch the `Release` workflow, then:

```bash
npm view @balacode/mental version
```

That output **must** equal `package.json` (no `v`). If publish skipped or failed, the release is not done. Do not cut a new tag to “fix” npm — fix the workflow and `workflow_dispatch` (tag `v$(package.json version)` must already exist).

## Site deploy (Cloudflare)

https://getmental.dev is the Worker in `website/`. Production deploys go through GitHub, not a laptop. `.github/workflows/deploy-website.yml` runs `wrangler deploy` when `website/` changes on `main`, when a GitHub Release is published, or on `workflow_dispatch`. It uses `secrets.CLOUDFLARE_API_TOKEN` and `secrets.CLOUDFLARE_ACCOUNT_ID`. A release is not a site deploy until that workflow succeeds.

Keep Claude/Copilot copies of this rule in sync: `.claude/rules/release.md`, `.github/copilot-instructions.md`.

## Do not

- Ship a git tag whose npm version differs
- Put `version` on `.claude-plugin/marketplace.json` plugin entries
- Print or commit `NPM_TOKEN`, `CLOUDFLARE_API_TOKEN`, or `CLOUDFLARE_ACCOUNT_ID`
- `npm publish` or `wrangler deploy` the production site from a laptop
- Use `MENTAL_SKIP_HOST_PLUGIN_CHECK` outside tests