Releases

/gaia-release cuts a new release of GAIA itself. Only the maintainer runs it; you never need to. The command and the gaia-maintainer binary it drives are excluded from the release bundle by .gaia/release-exclude, so no project scaffolded from GAIA has them.

Why contributors should know it exists

If you change CLI source, hooks, rules, or shipped wiki content, a release will eventually package your change. The release checks it in three ways:

• Manifest regeneration. .gaia/manifest.json gives each file in the bundle a class, which tells /update-gaia how to treat that file in a project:

  • owned: GAIA controls the file, and projects are not expected to change it.
  • shared: GAIA provides a starting version that the project is expected to change.
  • wiki-owned: handled exactly like shared, for the wiki pages GAIA seeds.

  A file that is not in the manifest belongs to the project, and /update-gaia leaves it alone. Before the manifest is regenerated, every file that would ship for the first time needs a decision: ship it, or withhold it. The maintainer makes that call. If your pull request adds a file that would ship to projects, say so in the pull request description, along with whether you think it should ship.

• Bundle-time scrub. The release workflow builds a tree from git ls-files, removes the paths in .gaia/release-exclude, then removes gaia:maintainer-only blocks and checks for leaks. Any leak fails the build.

• Distribution test gate. The release workflow runs the distribution tests against that tree before anything publishes.

If your change touches any of these, expect the next release to catch anything out of step.

What /gaia-release does

The command takes a patch, minor, or major argument. It starts with a preflight and stops unless:

• It runs on main with a clean working tree.
• The wiki is current (wiki/.state.json). If it has drifted, the maintainer runs /gaia-wiki and lets its pull request merge first.
• Every check the release expects to be required is required by the default branch’s rules.

After the preflight, in outline, it:

• Bumps the version in .gaia/VERSION, package.json, and frontend/package.json
• Graduates the CHANGELOG’s ## [Unreleased] section into a dated ## [X.Y.Z] entry
• Resets wiki/log.md, so new projects start with a clean log
• Regenerates .gaia/manifest.json and rebuilds the bundled CLIs
• Commits on a release/vX.Y.Z branch and opens a pull request, which passes the same checks and the same Code Audit Team audit as any other
• Tags the merge commit once it lands, which triggers release.yml
• Then brings create-gaia, the website, and these docs in line with the release

A 2.x release ships gaia-bundle-<tag>.tar.gz with a .sha256 asset, and any migration notes it needs travel inside the bundle under .gaia/migrations/ (see Migration notes). While 1.x projects can still reach a 2.x release, the release body opens with a line that sends a 1.6.1 project to the 2.0.0 migration.

The two CLI binaries

The CLI bundles two binaries from two entry points. .gaia/cli/gaia is the binary every project gets; .gaia/cli/gaia-maintainer carries the release surface and is excluded by .gaia/release-exclude. esbuild keeps the release code out of the shipped binary, so gaia has no way to cut a release. See CLI surface.

Step-by-step runbook

The step-by-step runbook is .claude/commands/gaia-release.md in the GAIA repo. It is not reproduced here.