diff --git a/.backlog/tasks/task-030 - Make-installation-and-first-use-clear-in-the-README.md b/.backlog/tasks/task-030 - Make-installation-and-first-use-clear-in-the-README.md new file mode 100644 index 0000000..6cca97c --- /dev/null +++ b/.backlog/tasks/task-030 - Make-installation-and-first-use-clear-in-the-README.md @@ -0,0 +1,52 @@ +--- +id: TASK-030 +title: Make installation and first use clear in the README +status: Done +assignee: + - '@codex' +created_date: '2026-10-28T11:25:00Z' +updated_date: '2026-10-28T11:50:00Z' +labels: [] +dependencies: [] +references: + - README.md + - docs/getting-started.md + - /home/stephen/Work/kde-shortcuts/INSTALL.md +modified_files: + - README.md + - docs/getting-started.md +type: docs +ordinal: 68000 +--- + +## Description + + +The README leads with a development build and mixes first use with contributor and agent internals. Follow the Plasma Shortcut Explorer documentation pattern so users can install a release and reach a useful first command. + + +## Acceptance Criteria + +- [x] #1 README explains GHA and offers a short path from installation to first useful commands. +- [x] #2 Setup guide covers release downloads, verification, authentication, PATH, updates and removal with current supported platforms. +- [x] #3 Documented commands match the local capability inventory and local documentation links resolve. + + +## Definition of Done + +- [x] #1 Roadmap is mapped and all documentation is current +- [x] #2 CI passes, test coverage is 94.51%+ +- [x] #3 No `--confirm` arguments - the default call executes, `--dry-run` is the alternative + + +## Implementation Plan + + +Use the Plasma Shortcut Explorer split between a short user README and detailed setup guide. Rewrite README around purpose, install, first use and optional agent setup; expand docs/getting-started.md with verified release assets, platform selection, checksum and PATH steps, authentication, updates and uninstall. Validate documented command forms against the rebuilt local inventory and check local links. Keep release and development capabilities distinct; no runtime changes. + + +## Final Summary + + +Reworked README around release installation, first PR review, common workflows and optional agent setup, following Plasma Shortcut Explorer. Expanded getting-started with platform selection, checksums, PATH, source builds, authentication, updates and removal. Clarified that gh is optional: GHA prefers GHA_GITHUB_TOKEN, otherwise tries gh auth token, then continues unauthenticated. Verified published Linux archive checksum, extraction and live PR listing; current local command forms, text/JSON results, previews and documentation links. make check passed lint and race tests with 95.2% coverage; git diff --check passed. Documentation-only change; no runtime changes. + diff --git a/README.md b/README.md index 9f94ee6..5fd62b1 100644 --- a/README.md +++ b/README.md @@ -1,139 +1,159 @@ -# GHA - GitHub Assistant +# GHA — GitHub Assistant ![GitHub](https://img.shields.io/badge/go-1.26.5-blue.svg) [![CI](https://github.com/Raithlin/gha/actions/workflows/ci.yml/badge.svg?branch=master&event=push)](https://github.com/Raithlin/gha/actions/workflows/ci.yml?query=branch%3Amaster) [![Latest release](https://img.shields.io/github/v/release/Raithlin/gha?include_prereleases&sort=date)](https://github.com/Raithlin/gha/releases) ![License](https://img.shields.io/badge/license-MIT-green.svg) -GHA is a command-line assistant for developers working with GitHub and local repositories. It brings GitHub, Git, CI, and local-repository signals into clear workflows for tasks such as reviewing pull requests, inspecting branches, and preparing releases. The commands are useful directly in a terminal, and structured output lets coding agents use those same workflows when you want them to. +GHA helps you review pull requests, understand local branches, and prepare +releases. It combines GitHub, Git, and CI information into a summary with +suggested next steps, so you can see what needs attention before acting. -It complements rather than replaces `git` and `gh`: a GHA command should add context, safety, or workflow value beyond a raw provider invocation. +GHA is built for coding agents and developers. Use readable output in your +terminal or add `--format json` for scripts and agents. It works alongside +`git` and the GitHub CLI (`gh`). + +- Review a pull request's CI status, reviewers, unresolved threads, and risks. +- Inspect local branches and worktrees, including cleanup candidates. +- Preview branch, pull-request, and release changes before applying them. +- Give your coding agent the same workflows through a bundled GHA skill. ## Install On macOS, install the released binary through Homebrew: -```bash +```sh brew install --cask raithlin/tap/gha -# Upgrade later with: brew update && brew upgrade --cask gha ``` See [package installation and upgrades](docs/package-distribution.md) for -integrity checks, native Linux packages, and the release-maintained tap. -Native Linux packages become available with the first release containing +integrity checks, upgrades, native Linux packages, and the release-maintained +tap. Native Linux packages become available with the first release containing the packaging configuration; earlier releases provide archives. -To build from source: +You can also download a Linux or macOS archive from +[GitHub Releases](https://github.com/Raithlin/gha/releases). +Install Git for local repository workflows and pushes. The +[GitHub CLI (`gh`)](https://cli.github.com/) is optional; GHA can reuse its login +for GitHub access. -Prerequisites: Go 1.26.5 or later and Git. A GitHub account is required for -GitHub-backed workflows. +You do not need Go to use a release binary. -```bash -git clone https://github.com/raithlin/gha.git -cd gha -make build +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). -# Or build and install gha into GOBIN or GOPATH/bin. -make install -``` +GHA currently publishes alpha releases. 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. -The examples below use an installed `gha` command. If you only ran `make build`, use `bin/gha` in its place, or run `make install`. +## First use -## Quick start +If you use the GitHub CLI, sign in if you have not already: -Use GHA directly in your terminal. Text output is intended for people; add `--format json` when you need structured results for a script or agent. +```sh +gh auth login +``` -```bash -# Discover the commands and capabilities in this build. -gha --help -gha capabilities --format json -gha version --format json +GHA chooses GitHub credentials in this order: -# Inspect pull requests and local repository state. -gha prs -gha review 123 -gha releases --limit 10 -gha branches -gha analyze -gha branches cleanup --format json +1. Use `GHA_GITHUB_TOKEN` if set, without invoking `gh`. +2. Otherwise, try `gh auth token` to reuse your GitHub CLI login. +3. If `gh` is missing or cannot supply a token, continue without authentication. -# Prepare release notes from merged pull requests. -gha release create-notes --since 2026-09-01 +Local inspection works without GitHub credentials. Public GitHub requests can +also work without authentication, subject to lower API rate limits. Private +repositories and operations that require authentication need a token or a +working `gh` login. See the [authentication guide](docs/getting-started.md#authentication) +for token setup and permissions. -# Preview workflows that can make changes. -gha branch publish feature/reviews --dry-run -gha pr prepare --title "Improve reviews" --head feature/reviews -gha pr create --title "Improve reviews" --head feature/reviews --dry-run -gha release publish 1.2.3 --dry-run --format json +Open a terminal in a GitHub checkout and start with: + +```sh +gha prs --limit 10 ``` -For isolated PR work, follow the [PR worktree lifecycle guide](docs/pr-worktree-lifecycle.md). -It covers new development through `pr create`, existing PR checkout and resume -with `pr checkout`, fork updates, and safe cleanup with `pr retire`. +This lists up to ten open pull requests. Pick a number from the list and +inspect it, replacing `123` with that number: -## Use GHA with coding agents +```sh +gha review 123 +``` -GHA can also provide its structured GitHub and local-repository workflows to coding agents. It bundles a portable `gha` skill that explains how agents can use those workflows. To detect configured harnesses and install or refresh the guidance, run: +The review summary shows CI and merge readiness, outstanding reviews and +threads, risk signals, and recommended next actions. Missing or unsupported +signals appear as unavailable. -```bash -gha agent install -``` +## Common workflows -The command detects configured Codex, Claude Code, Pi, OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw setup directories and configures those harnesses without requiring their executables. Use `--agent` with comma-separated names to choose explicitly, or `--binary-only` to skip harness setup. If none are detected, GHA reports how to configure one later. It copies the bundled detailed skill into a discoverable global skill directory and idempotently adds a **compact** GHA guidance block where a documented global instruction file exists. Agents can use the detailed skill explicitly when a workflow needs it; the default block leaves simple Git tasks to Git. Existing skills are not overwritten, and modified GHA skills are preserved by update and uninstall. `gha agent list` shows recorded harnesses and current file presence. +These examples describe the current source build. Use your installed command's +`--help` to check its options. -```bash -# Preview paths without writing files. -gha agent install --agent codex,claude --dry-run +| What you want to do | Command | +| --- | --- | +| Find PRs awaiting your review | `gha prs --queue --limit 10` | +| Inspect another GitHub repository | `gha prs --repo owner/repo --limit 10` | +| Inspect local branches | `gha branches` | +| See branches worth checking for cleanup | `gha branches cleanup` | +| List local worktrees | `gha worktrees` | +| Analyze repository history, storage, and large files | `gha analyze` | +| List recent published releases | `gha releases --limit 10` | +| Get a structured review for an agent or script | `gha review 123 --format json` | -# Preview setup for Pi, OpenCode, Copilot, Gemini CLI, Cursor, Hermes, and OpenClaw. -gha agent install --agent pi,opencode,copilot,gemini,cursor,hermes,openclaw --dry-run +Local branch information uses cached Git refs unless you explicitly request a +refresh. Cleanup inspection lists candidates; it does not delete them. -# Remove GHA's managed guidance block and its installed skill. -gha agent uninstall --agent codex --dry-run +Commands that change state execute by default. Preview their effects with +`--dry-run` first. For example, for an existing local branch: -# Use the local build while developing GHA. -make skill-install +```sh +gha branch publish feature/reviews --dry-run ``` -Preview and refresh installed agent guidance with: +The preview shows the publication target and safety checks without pushing. +See the [command guide](docs/command-guide.md) for the full workflows, or the +[PR worktree guide](docs/pr-worktree-lifecycle.md) to work on a PR in an isolated +checkout and safely retire it afterward. -```bash -gha update --dry-run -gha update +## Use with a coding agent + +Install the bundled skill and guidance so your agent knows when and how to use +GHA. Preview the files first: + +```sh +gha agent install --dry-run ``` -Verify the product workflow without touching your agent setup: +The preview lists destinations for detected agent setups. Apply it with: -```bash -make test-skill-install +```sh +gha agent install ``` -GHA uses `GHA_GITHUB_TOKEN` when set; otherwise it uses `gh auth token` when the GitHub CLI is installed and authenticated. Without either, public API requests are unauthenticated. For private repositories or higher API rate limits, provide a fine-grained token restricted to the repositories GHA will access. The full command surface uses `Contents: read`, `Pull requests: write`, `Checks: read`, `Actions: read`, and `Issues: read`; `Pull requests: write` is required for `gha pr create` and includes pull-request read access. Git branch publication uses the checkout remote's authentication, not the GitHub API token. A classic token needs the `repo` scope for private repositories. +GHA supports Codex, Claude Code, Pi, OpenCode, GitHub Copilot, Gemini CLI, +Cursor, Hermes Agent, and OpenClaw. Use `--agent codex,claude` to select agents +explicitly. Existing releases may support fewer agents. -## Agent efficiency tests +See the [agent setup guide](docs/getting-started.md#set-up-a-coding-agent) for +selection, installed-file checks, and removal. Agent setup is optional for +terminal use. -Benchmarks of agent correctness, token use, and command effort are in the -[test results](docs/agent-efficiency-test-results.md). They include a -git/gh-only control and a check of compact default guidance. See the -[evaluation method and limitations](docs/agent-efficiency-evaluation.md) -for how the runs were scored. +## Updates and removal -## Documentation +Install a newer binary using the same method you used originally. +`gha update` refreshes installed **agent guidance**, not the GHA executable. +See [updates](docs/getting-started.md#update) and +[uninstall](docs/getting-started.md#uninstall) for the steps. -- [Getting started](docs/getting-started.md) — installation, authentication, and first commands -- [Command guide](docs/command-guide.md) — output contracts and examples for every available workflow -- [Contributing](docs/CONTRIBUTING.md) — bug reports, feature proposals, documentation, and pull requests -- [Development](docs/development.md) — build, test, quality, and repository layout -- [Tasks and architecture](docs/development.md#tasks-and-architecture) — optional, highly recommended Backlog.md and Groma workflows for contributors -- [Agent efficiency test results](docs/agent-efficiency-test-results.md) — benchmark tables and findings -- [Agent efficiency evaluation](docs/agent-efficiency-evaluation.md) — paired agent benchmark and reporting method -- [Release preparation](docs/development.md#preparing-a-release) — reviewed notes and tag publication -- [Roadmap](docs/roadmap.md) — delivered work, prioritized next steps, and future phases -- [Architecture](docs/architecture.md) — current implementation architecture -- [Explore the architecture](https://raithlin.github.io/gha/) — interactive Groma map of the committed architecture, flows, and source -- [Design](docs/design.md) — long-term vision and design principles -- [Architecture decision records](docs/adr/) — decisions behind the project structure +## Documentation and contributing -## License +- [Setup guide](docs/getting-started.md) — downloads, authentication, troubleshooting, and first use +- [Command guide](docs/command-guide.md) — commands, examples, and structured output contracts +- [Contributing](docs/CONTRIBUTING.md) — report problems, suggest features, and submit changes +- [Development](docs/development.md) — build, test, and contributor tooling +- [Roadmap](docs/roadmap.md) — current implementation and planned work +- [Architecture](docs/architecture.md) · [Interactive map](https://raithlin.github.io/gha/) — how GHA fits together +- [Agent evaluation results](docs/agent-efficiency-test-results.md) — measured correctness and command effort, with limitations +- [All documentation](docs/README.md) -GHA is distributed under the [MIT License](LICENSE). +[MIT licensed](LICENSE). diff --git a/docs/getting-started.md b/docs/getting-started.md index b63ed94..55eb135 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,107 +1,310 @@ # Getting started -GHA is an agent-first developer tool written in Go. It gives coding agents -bounded, versioned, decision-ready views of GitHub, Git, CI, and local -repositories; developers use the same commands through a clear terminal UI. +Install GHA, connect it to GitHub, then inspect a repository. Coding-agent +setup is optional. For a short tour, start with the [README](../README.md). -GHA does not aim to replace `git` or `gh`. It earns a command when it makes a -workflow easier or safer by combining local and provider signals, normalizing -them into a stable model, or exposing an actionable summary. Raw Git and GitHub -operations remain the right tool when they are the clearer or more efficient -choice. +## Requirements -## Prerequisites +- Git for local repository workflows and branch or tag pushes. +- Linux or macOS on x86-64 or ARM64 for the published binaries. +- Optional: [GitHub CLI (`gh`)](https://cli.github.com/) to reuse its login. + GHA also accepts `GHA_GITHUB_TOKEN` and continues without authentication if + neither source supplies a token. +- GitHub authentication for private repositories and authenticated workflows. -- Go 1.26.5 or later -- Git -- A GitHub account for GitHub-backed workflows +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. -## Installation +GHA publishes alpha releases. 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. -```bash -# Clone the repository -git clone https://github.com/raithlin/gha.git -cd gha +## Install a release + +For Homebrew on macOS or native Linux packages, follow +[package installation and upgrades](package-distribution.md). The steps below +cover manual archive installation. + +### Choose a download + +Open [GitHub Releases](https://github.com/Raithlin/gha/releases) and choose a +release. Download its archive and `checksums.txt` into a separate directory. +Choose the archive suffix for your machine: + +| Machine | Archive suffix | +| --- | --- | +| Linux, Intel or AMD x86-64 | `linux_amd64.tar.gz` | +| Linux, ARM64 | `linux_arm64.tar.gz` | +| macOS, Intel | `darwin_amd64.tar.gz` | +| macOS, Apple Silicon | `darwin_arm64.tar.gz` | + +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 +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. + +### Verify the download + +On Linux, from the directory containing the archive and checksum file, run: + +```sh +sha256sum --check --ignore-missing checksums.txt +``` + +Your archive should appear with `OK`. You do not need the other release assets. +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 +shasum -a 256 --check selected-checksum.txt +``` + +Expect `gha_0.3.0-alpha_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. + +### Install for your user + +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 +mkdir -p "$HOME/.local/bin" +install -m 755 gha "$HOME/.local/bin/gha" +``` + +This installs GHA for your user without sudo. On macOS, use your downloaded +`darwin` archive in the `tar` command. + +Add that directory to your current shell's PATH: + +```sh +export PATH="$HOME/.local/bin:$PATH" +gha --help +``` + +You should see GHA's commands and options. To keep the PATH change in new +terminals, add the export line once to your shell configuration, such as +`~/.bashrc` for Bash or `~/.zshrc` for Zsh. + +If you see `command not found`, try `~/.local/bin/gha --help`. If that works, +check your PATH and open a new terminal after saving the shell configuration. +Run `command -v gha` to check which binary your shell selects if you have more +than one installation. + +## Build from source + +Install Git and Go 1.26.5 or later. With Make available, run: -# Build the binary locally +```sh +git clone https://github.com/Raithlin/gha.git +cd gha make build +./bin/gha --help +``` + +This builds the current development checkout into `bin/gha`. The help output +lists its commands. To install the same source through Go, run: -# Build, then install gha into GOBIN or GOPATH/bin +```sh make install ``` -## Authentication and repository selection +Go puts `gha` in `GOBIN`, or `$(go env GOPATH)/bin` when `GOBIN` is unset. Add +that directory to your PATH. Without Make, run `go install ./cmd/gha` from the +checkout for the same Go installation. + +Building does not configure coding agents. See [agent setup](#set-up-a-coding-agent) +if you want that integration, or [Development](development.md) to work on GHA. + +## Authentication + +If you use the GitHub CLI, sign in and check your account: + +```sh +gh auth login +gh auth status +``` + +The status should identify the GitHub account you intend to use. GHA uses +`GHA_GITHUB_TOKEN` when set; otherwise it tries `gh auth token`. With neither, +public API requests remain unauthenticated and have lower rate limits. Local +commands such as `gha analyze` work without GitHub credentials. -GHA uses `GHA_GITHUB_TOKEN` when set. Otherwise, if `gh` is installed and -authenticated, it uses `gh auth token`. With neither credential, public API -requests remain unauthenticated; private-repository access and higher API rate -limits require authentication. A fine-grained token can be supplied through -`GHA_GITHUB_TOKEN`, restricted to the repositories GHA will access. For the -full current command surface, grant these repository permissions: +If you do not use `gh`, supply a fine-grained token through `GHA_GITHUB_TOKEN` +using your shell or secret manager. Restrict it to the repositories GHA needs. +Read-only inspection needs only the relevant read permissions; for the full +current command surface, grant: -- `Contents: read` for branch metadata, comparisons, and releases -- `Pull requests: write` for inspection and `gha pr create` -- `Checks: read` for CI status in `gha review` -- `Actions: read` to observe the tag-triggered release workflow -- `Issues: read` for `gha prs --assigned` +- `Contents: read` for branch metadata, comparisons, and releases. +- `Pull requests: write` for `gha pr create`; this includes PR read access. +- `Checks: read` for review CI status. +- `Actions: read` to observe release workflows. +- `Issues: read` for `gha prs --assigned`. -`Pull requests: write` includes read access. Branch and release-tag pushes use -the checkout remote's authentication, not the GitHub API token. A classic -token needs the `repo` scope for private repositories. +Git branch and tag pushes use your checkout remote's Git authentication, +separately from the API token. A classic token needs the `repo` scope for +private repositories. Do not put tokens in repository files or issue reports. -Repository-aware commands select a repository in this order: +If GitHub access fails, check the selected repository, authenticated account, +and token permissions. An explicitly set `GHA_GITHUB_TOKEN` takes precedence +over your `gh` login. -1. `--repo owner/repo` -2. the `origin` remote in an explicit `--path /path/to/checkout` -3. `GHA_REPOSITORY` -4. the current Git repository's `origin` remote +## Select a repository -`--path` identifies a local checkout; it does not clone or fetch it. +Run GHA inside your local checkout, or select a GitHub repository explicitly: + +```sh +gha prs --repo Raithlin/gha --limit 10 +``` + +This lists up to ten open PRs from that repository. An empty list is a valid +result. Repository-aware commands select their provider target in this order: + +1. `--repo owner/repo`. +2. The `origin` remote in an explicit `--path /path/to/checkout`. +3. `GHA_REPOSITORY`. +4. The current Git repository's `origin` remote. + +`--path` selects an existing local checkout; resolving it does not clone or +fetch. Local workflows need a checkout. Commands that combine a provider target +and local changes can also require the two to match; see their help. ## First commands -```bash -# See available commands and their help -gha --help +Inside your GitHub checkout, list open pull requests: -# See what this build can safely do, including unavailable features -gha capabilities --format json +```sh +gha prs --limit 10 +``` -# List pull requests in the current repository -gha prs +Choose a PR number from the list, then replace `123` below: -# Inspect one pull request +```sh gha review 123 +``` -# Prepare a provider-safe pull request preview before its remote write -gha pr prepare --head feature/reviews --format json +The summary reports merge and CI readiness, outstanding reviewers and threads, +risks, and suggested next actions. Optional signals that cannot be obtained +remain unavailable. -# Create only after reviewing the plan -gha pr create --title "Improve reviews" --head feature/reviews +Inspect local branches and worktrees: -# Inspect local branches and cached origin tracking branches +```sh gha branches +gha worktrees +``` + +These show local state. Branch output marks origin information as cached; +neither command fetches implicitly. Use `gha analyze` for offline history, +storage, and large-file analysis. + +For agent or script input, request the same result as JSON: + +```sh +gha review 123 --format json +``` + +Stdout contains the structured result; diagnostics go to stderr. Consult the +[command guide](command-guide.md) for schemas, filters, limits, and freshness. + +Commands that change state execute by default. Use `--dry-run` to preview +supported writes before applying them. For the local branch `feature/reviews`: + +```sh +gha branch publish feature/reviews --dry-run +``` + +This shows the target and safety checks without pushing. Follow the +[PR worktree lifecycle guide](pr-worktree-lifecycle.md) for isolated development, +existing PR checkout and resume, fork updates, and safe cleanup. + +## Set up a coding agent -# Review then explicitly refresh origin tracking refs when freshness matters -gha branches --refresh-origin --dry-run -gha branches --refresh-origin +GHA includes a skill and compact guidance for supported coding agents. Preview +setup before writing to your agent configuration: -# Analyze local worktree, history, storage, and largest tracked files offline -gha analyze +```sh +gha agent install --dry-run +``` + +The preview lists the files it would write for detected setups. Run +`gha agent install` to apply that selection. If none are detected, GHA explains +how to choose one explicitly. For example, to configure Codex and Claude Code: + +```sh +gha agent install --agent codex,claude --dry-run +gha agent install --agent codex,claude +``` + +The second command installs the bundled skill and managed guidance at the +previewed paths. Current source supports Codex, Claude Code, Pi, OpenCode, +GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw. Detection uses +setup directories and does not require agent executables. Use comma-separated +names with `--agent` to choose explicitly. + +Check GHA's recorded installations with: + +```sh +gha agent list +``` + +This reports recorded destinations and file presence, not every agent installed +on your machine. Existing skills are preserved; modified GHA skills are also +preserved during updates and removal. See the +[agent command details](command-guide.md#agent-guidance-installation) for ownership +and shared destinations. + +## Update -# Inspect a different local checkout without changing directory -gha branches --path ../other-checkout +For a release binary, download and verify a newer archive, then repeat the +installation steps to replace your `gha` executable. GitHub downloads do not +add a package-manager repository or automatic binary updates. + +For a source installation, update your checkout to the source you want and +repeat `make install`, or `make build` if you run `bin/gha` directly. + +After updating the executable, preview agent-guidance updates: + +```sh +gha update --dry-run +``` + +The preview checks the latest published guidance against your binary's +capabilities. Run `gha update` to apply compatible guidance to recorded agent +installations. It preserves incompatible skills and user content outside the +managed guidance blocks. **It does not update the GHA executable.** Published +guidance may lag a development build. + +## Uninstall + +If you configured agents, remove their GHA guidance before deleting the binary. +Use the names shown by `gha agent list`, for example: + +```sh +gha agent uninstall --agent codex,claude --dry-run +gha agent uninstall --agent codex,claude +``` -# Generate read-only release notes from merged pull requests -gha release create-notes --since 2026-09-01 +The first command previews removal; the second removes managed guidance and +unmodified managed skills. It preserves modified skills and files still shared +by another recorded agent. -# List published releases with a bounded, versioned result. -gha releases --limit 10 +For the per-user release installation in this guide, remove the executable: -# Review the tag, commit, CI, and workflow plan before publishing. -gha release publish 1.2.3 --dry-run --format json -gha release publish 1.2.3 +```sh +rm "$HOME/.local/bin/gha" ``` -For command-specific examples and automation contracts, see the -[command guide](command-guide.md). +For `make install` or `go install`, remove `gha` from the `GOBIN` or GOPATH +binary directory used at installation. Check `command -v gha` first to confirm +the location. A local build lives at `bin/gha` inside your source checkout. +Removing the executable leaves your repositories and GitHub data in place.