Releasing a toolkit version

A release is a commit and a tag on main plus the simulator builds attached to a GitHub Release.

1. Merge dev into main (pull request, CI green).
2. Run the Release workflow (.github/workflows/release.yml) with the version, for example 0.2.0 or 0.2.0-beta.1. It bumps release.json and CHANGELOG.md, commits, tags v0.2.0, builds the simulator for macOS arm64 and x64, uploads the zips with SHA256SUMS, and creates the release (pre-release when the version has a suffix).
3. Developers run minikit upgrade: the checkout moves to main, the CLI recompiles, and the matching simulator build is downloaded and verified.

release.json names every component version the checkout ships: the toolkit, the CLI, the packages, the protocol, the simulator version and its asset names per platform, and the Flutter range the toolkit was tested with. minikit version and minikit doctor read it.

Bump the simulator version when its build changes

minikit upgrade and minikit sim install download a simulator build only when its version is not cached yet. When anything under simulator/ changed, raise its version in simulator/rust/Cargo.toml, simulator/rust/Cargo.lock and simulator/pubspec.yaml, and set simulator.version in release.json to match. The running simulator reports that version on /health, and minikit doctor compares it with release.json.

Releasing without GitHub Actions

When the workflow cannot run (for example, the account's Actions budget is used up), release by hand from a Mac with the toolchain:

1. On dev, set toolkit and cli in release.json, bump the simulator if it changed, turn ## Unreleased in CHANGELOG.md into ## <version> (<date>), and commit Release <version>.

2. Push dev, open a pull request to main, and merge it.

3. Tag the merge commit and push the tag:

   git fetch origin
   git tag -a v<version> origin/main -m "minikit <version>"
   git push origin v<version>
   

4. Build the simulator from that commit. The app is universal (Apple silicon and Intel), so one build serves both asset names in release.json:

   cd simulator && flutter build macos --release
   app=build/macos/Build/Products/Release/mini_app_simulator.app
   ditto -c -k --keepParent "$app" mini_app_simulator-<sim>-macos-arm64.zip
   cp mini_app_simulator-<sim>-macos-arm64.zip mini_app_simulator-<sim>-macos-x64.zip
   shasum -a 256 mini_app_simulator-<sim>-macos-*.zip > SHA256SUMS
   

5. Publish the release. Keep --prerelease for versions with a suffix such as -alpha.2:

   gh release create v<version> --verify-tag --prerelease --title "minikit <version>" \
     --notes-file notes.md mini_app_simulator-<sim>-macos-*.zip SHA256SUMS
   

6. Fast-forward dev to main: git checkout dev && git merge --ff-only origin/main && git push.

7. Check the result: minikit sim install --force, minikit sim open, then curl -s http://127.0.0.1:8788/health must report the new simulator version.