Add Homebrew distribution

.github/workflows/release.yml

@@ -52,3 +52,34 @@ jobs:
             --verify-tag \
             --notes-file "docs/releases/$GITHUB_REF_NAME.md" \
             --title "Bible CLI $GITHUB_REF_NAME"
+
+      - name: Check Homebrew tap credentials
+        if: ${{ !contains(github.ref_name, '-') }}
+        id: homebrew-token
+        env:
+          HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+        run: |
+          if [[ -n "$HOMEBREW_TAP_TOKEN" ]]; then
+            echo "available=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "available=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update Homebrew tap
+        if: ${{ steps.homebrew-token.outputs.available == 'true' }}
+        uses: mislav/bump-homebrew-formula-action@f865c8b0dbebd6e263cc06782a0e974c61cf12d2 # v4
+        with:
+          formula-name: bible-cli
+          formula-path: Formula/bible-cli.rb
+          homebrew-tap: vmrocha/homebrew-tap
+          base-branch: main
+          create-pullrequest: false
+          create-branch: false
+        env:
+          COMMITTER_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Report missing Homebrew tap credentials
+        if: ${{ steps.homebrew-token.outputs.available == 'false' }}
+        run: |
+          echo "::warning::HOMEBREW_TAP_TOKEN is not configured; the Homebrew formula was not updated."

README.md

@@ -164,11 +164,17 @@ text licensing requirements.
 
 ## Installation
 
+Install the latest stable release with Homebrew on macOS or Linux:
+
+```console
+brew install vmrocha/tap/bible-cli
+```
+
 Tagged releases ship checksummed single-binary archives for macOS and Linux on
 Intel/AMD64 and ARM64. Public release downloads require no GitHub account, API
 token, or GitHub CLI. See the [installation guide](docs/INSTALL.md) for archive
-verification, installation, source builds, and Bash, Zsh, Fish, and PowerShell
-completion setup.
+verification, Homebrew upgrades, source builds, and Bash, Zsh, Fish, and
+PowerShell completion setup.
 
 ## License
 

docs/INSTALL.md

@@ -1,5 +1,22 @@
 # Installing Bible CLI
 
+## Homebrew
+
+Install the latest stable release from the project tap on macOS or Linux:
+
+```console
+brew install vmrocha/tap/bible-cli
+```
+
+The formula builds from the immutable tagged source archive and installs the
+`bible` executable plus Bash, Zsh, and Fish completions. Upgrade or remove it
+with the usual Homebrew commands:
+
+```console
+brew upgrade bible-cli
+brew uninstall bible-cli
+```
+
 ## Release archives
 
 Tagged releases provide single-binary archives for:

docs/RELEASING.md

@@ -3,14 +3,24 @@
 Release tags publish checksummed, self-contained archives through GitHub
 Actions. A release must come from a reviewed commit on `main`.
 
+## Homebrew credentials
+
+The `HOMEBREW_TAP_TOKEN` repository secret must contain a fine-grained GitHub
+personal access token restricted to `vmrocha/homebrew-tap`, with repository
+contents read and write access. The workflow uses this token only to update the
+tap after a stable release; the tag-bound `GITHUB_TOKEN` cannot write to a
+different repository.
+
 ## Prepare
 
 1. Confirm `main` is clean, synchronized with `origin/main`, and green in CI.
 2. Choose a semantic version that has never been used.
 3. Add `docs/releases/<version>.md` with user-facing release notes.
 4. Confirm the installation examples and supported platforms are still
    accurate.
-5. Run `make check` locally.
+5. Confirm the `HOMEBREW_TAP_TOKEN` repository secret can write contents in
+   `vmrocha/homebrew-tap`.
+6. Run `make check` locally.
 
 Pull-request CI builds all four archives once and executes the matching packaged
 binary on native macOS and Linux runners. The smoke test verifies checksums,
@@ -27,7 +37,10 @@ git push origin v0.1.0
 ```
 
 The release workflow reruns `make check`, creates deterministic archives, and
-publishes them with `checksums.txt` and the matching release-notes file.
+publishes them with `checksums.txt` and the matching release-notes file. For a
+stable tag, it then updates `Formula/bible-cli.rb` in
+`vmrocha/homebrew-tap` with the new source URL and SHA-256. Prerelease tags do
+not update Homebrew.
 
 ## Verify
 
@@ -36,6 +49,8 @@ publishes them with `checksums.txt` and the matching release-notes file.
 3. Download the archive for the current machine and verify its checksum.
 4. Run `bible version` and confirm the version, commit, and build date.
 5. Run `bible read "John 3:16"` without network access.
+6. Confirm the tap formula references the new tag, then run
+   `brew update && brew upgrade bible-cli` and `brew test bible-cli`.
 
 Never move or reuse a published tag. If publishing fails after a release becomes
 visible, preserve the tag and diagnose the workflow before taking further

website/guide/installation.md

@@ -1,8 +1,18 @@
 # Installation
 
-Bible CLI releases are single-binary archives for macOS and Linux on AMD64 and
-ARM64. Downloads include checksums for verification and do not require a
-GitHub account.
+Bible CLI supports Homebrew and single-binary release archives on macOS and
+Linux.
+
+## Homebrew
+
+Install the latest stable release from the project tap:
+
+```console
+brew install vmrocha/tap/bible-cli
+```
+
+Homebrew also installs Bash, Zsh, and Fish completions. Use
+`brew upgrade bible-cli` to install future stable releases.
 
 ## Download a release