docs: prepare v0.4.0-beta.1 release

README.md

@@ -43,7 +43,7 @@ Follow the [setup guide](docs/getting-started.md#install-a-release) to choose
 your download, verify its checksum, and put `gha` on your PATH. The guide also
 covers [building from source](docs/getting-started.md#build-from-source).
 
-GHA currently publishes alpha releases. This README describes the current
+GHA is in prerelease development. This README describes the current
 source; an older release may have fewer commands. Run `gha --help` to check
 your installation, or `gha capabilities --format json` if your build supports it.
 

docs/getting-started.md

@@ -16,7 +16,7 @@ Release binaries do not require Go. Building from source requires Go 1.26.5
 or later; Make is optional. Published archives currently cover Linux and macOS,
 not Windows.
 
-GHA publishes alpha releases. These docs describe the current source, which
+GHA publishes prereleases. These docs describe the current source, which
 may have commands an older binary lacks. Check `gha --help` and, when available,
 `gha capabilities --format json` for what your installation supports. Build
 from source if you need features that have not reached a release.
@@ -43,7 +43,7 @@ Choose the archive suffix for your machine:
 Run `uname -m` if you are unsure of the CPU architecture. `x86_64` means
 `amd64`; `aarch64` or `arm64` means `arm64`.
 
-The commands below use the published `0.3.0-alpha` Linux x86-64 archive as an
+The commands below use the published `0.4.0-beta.1` Linux x86-64 archive as an
 example. Substitute the exact filename you downloaded throughout. Release
 archives contain a `gha` executable, README, and license; they do not install
 coding-agent guidance automatically.
@@ -62,11 +62,11 @@ Stop if its checksum fails.
 On macOS, select the line for your exact archive and check it:
 
 ```sh
-grep ' gha_0.3.0-alpha_darwin_arm64.tar.gz$' checksums.txt > selected-checksum.txt
+grep ' gha_0.4.0-beta.1_darwin_arm64.tar.gz$' checksums.txt > selected-checksum.txt
 shasum -a 256 --check selected-checksum.txt
 ```
 
-Expect `gha_0.3.0-alpha_darwin_arm64.tar.gz: OK`. Use the `darwin_amd64` filename
+Expect `gha_0.4.0-beta.1_darwin_arm64.tar.gz: OK`. Use the `darwin_amd64` filename
 for an Intel Mac. An empty selection is not a successful check. This verifies
 the download against the release's checksum file.
 
@@ -76,7 +76,7 @@ Extract the verified archive and copy the executable into `~/.local/bin`.
 On Linux x86-64, for example:
 
 ```sh
-tar -xzf gha_0.3.0-alpha_linux_amd64.tar.gz
+tar -xzf gha_0.4.0-beta.1_linux_amd64.tar.gz
 mkdir -p "$HOME/.local/bin"
 install -m 755 gha "$HOME/.local/bin/gha"
 ```

docs/releases/v0.4.0-beta.1.md

@@ -0,0 +1,84 @@
+# v0.4.0-beta.1
+
+GHA's first beta brings isolated PR worktrees, clearer outcomes when a mutation
+partly fails, broader coding-agent setup, and package-manager installation.
+The core workflows are ready for wider testing. This remains a prerelease:
+please report unexpected behavior with the output of `gha version --format json`.
+
+## Installation and upgrades
+
+- On macOS, install with `brew install --cask raithlin/tap/gha`, or run
+  `brew update` followed by `brew upgrade --cask gha` for an existing install.
+  The release workflow now maintains the [Homebrew tap](https://github.com/Raithlin/homebrew-tap).
+- Debian/Ubuntu, Fedora, and Arch packages join the macOS/Linux archives for
+  amd64 and arm64. Verify the downloaded package against this release's
+  `checksums.txt` before installation. Native package managers own executable
+  upgrades; these are downloadable packages, not hosted apt/dnf/pacman repositories.
+- See the [setup guide](https://github.com/Raithlin/gha/blob/v0.4.0-beta.1/docs/getting-started.md)
+  and [distribution guide](https://github.com/Raithlin/gha/blob/v0.4.0-beta.1/docs/package-distribution.md)
+  for installation, authentication, checksum verification, and upgrade instructions.
+  macOS binaries are not Developer ID signed or notarized.
+
+## Changes
+
+- **Isolated PR work:** inspect, add, and safely remove Git worktrees. Use
+  `gha pr checkout <number> --worktree <path>` to check out or resume an existing
+  PR with an explicit fork-aware push destination. `gha pr retire` explains
+  whether a closed PR's checkout can be removed and preserves dirty, unpublished,
+  locked, or uncertain work. [#23](https://github.com/Raithlin/gha/pull/23),
+  [#26](https://github.com/Raithlin/gha/pull/26).
+- **Safer mutations and useful failure results:** branch operations check the
+  actual origin write target and local operation state. Partial failures retain
+  completed effects in structured output, and origin branch renames use atomic
+  pushes. [#21](https://github.com/Raithlin/gha/pull/21),
+  [#24](https://github.com/Raithlin/gha/pull/24),
+  [#25](https://github.com/Raithlin/gha/pull/25).
+- **More coding-agent harnesses:** guidance setup supports Codex, Claude Code,
+  Pi, OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw.
+  Installation detects configured harnesses without requiring their executables;
+  use `--agent` for explicit selection. Compact default guidance keeps the
+  detailed skill available when needed. [#14](https://github.com/Raithlin/gha/pull/14),
+  [#19](https://github.com/Raithlin/gha/pull/19),
+  [#20](https://github.com/Raithlin/gha/pull/20),
+  [#22](https://github.com/Raithlin/gha/pull/22).
+- **Compatible guidance updates:** `gha update` refreshes recorded agent
+  installations while checking skill requirements against the installed binary.
+  Incompatible or customized skills are preserved. The command does not upgrade
+  the executable. [#18](https://github.com/Raithlin/gha/pull/18),
+  [#19](https://github.com/Raithlin/gha/pull/19).
+- **Authentication and PR preparation:** GHA can reuse `gh` authentication when
+  `GHA_GITHUB_TOKEN` is unset. `gha pr prepare` drafts descriptions from local
+  commits without fetching or creating a PR. [#15](https://github.com/Raithlin/gha/pull/15),
+  [#17](https://github.com/Raithlin/gha/pull/17).
+- **Release readiness and diagnostics:** CI evaluation accounts for exact-commit
+  workflow attempts, required checks, and supported skipped/neutral outcomes.
+  Build identity, unpublished release branches, and pruned upstreams have clearer
+  results. Reviewed release notes and guarded tag publication are part of the
+  release workflow. [#12](https://github.com/Raithlin/gha/pull/12),
+  [#13](https://github.com/Raithlin/gha/pull/13),
+  [#26](https://github.com/Raithlin/gha/pull/26),
+  [#28](https://github.com/Raithlin/gha/pull/28).
+- **Distribution and first use:** automated native install/upgrade tests now
+  cover Debian, Fedora, Arch, Intel Mac, and Apple Silicon, including checksum
+  rejection and guidance preservation. The README and setup guide explain a
+  complete first-use path. [#31](https://github.com/Raithlin/gha/pull/31),
+  [#32](https://github.com/Raithlin/gha/pull/32).
+
+## Migration from v0.3.0-alpha
+
+Mutating commands now **execute by default** after their safety checks. Use
+`--dry-run` to preview changes; the old confirmation-flag workflow has been
+removed. Review existing scripts before upgrading, particularly any that relied
+on a default invocation being a preview. Explicit targets and preflight safety
+checks remain. [#16](https://github.com/Raithlin/gha/pull/16).
+
+Upgrade the executable through its package manager or release archive first.
+Then use `gha update --dry-run` to inspect guidance updates and `gha update`
+to apply compatible updates. Agent setup is separate from package installation.
+Use `gha capabilities --format json` to discover this binary's command contracts.
+
+Release-status/wait and downloaded-asset verification workflows remain planned;
+this beta does not add those commands. Check the GitHub Actions run, published
+release, and downloaded assets to verify a publication completed.
+
+Contributor: @Raithlin.