bump-version

name	bump-version
description	Bump the release version everywhere in the Brain3 project — Cargo.toml, pyproject.toml, README, first_run_setup.rs, and test fixtures — then execute the full release process: tag, CI workflow, and verification.

bump-version / release

Full release process for Brain3. Execute each step using the Bash tool — do not show commands for the user to copy-paste, run them directly.

Files updated by the bump script

File	What changes
apps/gateway/Cargo.toml	version = "X.Y.Z"
brain3-mcp-vault-tools/pyproject.toml	version = "X.Y.Z"
README.MD	S3 install URL (/releases/vX.Y.Z/install.sh)
crates/core/src/application/first_run_setup.rs	CURRENT_RELEASE = "vX.Y.Z"
brain3-mcp-vault-tools/tests/test_server_startup.py	Two version string fixtures
Cargo.lock	Auto-updated via cargo fetch
brain3-mcp-vault-tools/uv.lock	Regenerated via uv lock --project ./brain3-mcp-vault-tools

---

Step 0 — Ensure we're on a release branch

Before bumping anything, check the current branch:

git rev-parse --abbrev-ref HEAD

The version bump must happen on a dedicated release branch named bump_version_<XYZ> (the version with dots removed — e.g. 0.2.8 → bump_version_028), not on main.

• If already on the expected bump_version_<XYZ> branch, proceed to Step 1.
• Otherwise (on main or any other branch), stop and offer to create the branch for the user. Do not create it without confirmation. Once confirmed, run:

git checkout -b bump_version_<XYZ>

Only after we're on the release branch should you continue to Step 1.

---

Step 1 — Bump version in files

Run the bump script (it detects the current version from apps/gateway/Cargo.toml, applies all replacements, and refreshes Cargo.lock):

bash .claude/skills/bump-version/bump.sh VERSION

Then refresh and verify the Python lockfile (pyproject.toml was just bumped, so uv.lock will be stale):

uv lock --project ./brain3-mcp-vault-tools
uv lock --project ./brain3-mcp-vault-tools --check

Then run cargo test to verify nothing is broken.

Do NOT commit — tell the user to commit themselves, as per project instructions. Remind them that both brain3-mcp-vault-tools/pyproject.toml and brain3-mcp-vault-tools/uv.lock must be included in the commit.

---

Step 2 — Tag and push (triggers CI release workflow)

The tag does not require the PR to be merged first. The release workflow builds from whatever commit the tag points at, so you can tag the bump_version_<XYZ> branch HEAD directly — even while its PR is still open or blocked on review. Don't wait for the merge to cut the release.

Ask the user to confirm before tagging and pushing. Once confirmed, run (tags the current HEAD, i.e. the release branch commit):

VERSION=vX.Y.Z
git tag -a "$VERSION" -m "Release $VERSION"
git push origin "$VERSION"

Pushing the tag triggers .github/workflows/release.yml, which builds all four targets, signs SHA256SUMS, and publishes to GitHub Releases and S3 (~5–10 min).

Then monitor progress by running:

gh run watch

---

Step 3 — Verify

Once the workflow completes, run:

VERSION=vX.Y.Z
gh release view "$VERSION"

Report the listed assets to the user.

Then verify the Docker image published to GHCR by pulling it:

VERSION=vX.Y.Z
docker pull ghcr.io/tleyden/brain3-mcp-vault-tools:$VERSION

Confirm the pull succeeds and report the digest to the user.

---

Gotchas

• The version argument can have or omit a leading v — both 0.2.3 and v0.2.3 work.
• Push only the tag (git push origin "$VERSION"), not all branches — pushing everything can trigger unintended workflows.
• Tag and push after the user has committed the version bump.
• cargo fetch (not cargo build) is used to update Cargo.lock quickly.
• Any change to brain3-mcp-vault-tools/pyproject.toml or other package metadata requires regenerating brain3-mcp-vault-tools/uv.lock in the same commit — uv lock --project ./brain3-mcp-vault-tools --check will fail in CI otherwise.