diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ffc7553..63cd4e7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -16,3 +16,17 @@ jobs:
         run: go build -o godo ./cmd/godo
       - name: CI gate (godo.yaml)
         run: ./godo ci
+
+  # Catches a broken .goreleaser.yaml on every push, instead of at tag time
+  # when a bad config means a failed release.
+  release-config:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - uses: goreleaser/goreleaser-action@v6
+        with:
+          version: "~> v2"
+          args: check
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a211146..28683e2 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -26,3 +26,5 @@ jobs:
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Optional: absent secret → tap/bucket push is skipped, not failed.
+          TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}
diff --git a/.goreleaser.yaml b/.goreleaser.yaml
index bc35914..dc9a45b 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -48,6 +48,44 @@ archives:
 checksum:
   name_template: checksums.txt
 
+# Packaging homes. Both pushes need a PAT with write access to those repos,
+# exposed to the release workflow as TAP_GITHUB_TOKEN; without it the release
+# still publishes, it just does not update the tap or the bucket.
+# Homebrew ships pre-built binaries as casks now; `brews` is deprecated and
+# makes `goreleaser check` fail. Casks are macOS-only — Linux installs go
+# through `go install` or the release binary (docs/install.md).
+homebrew_casks:
+  - name: godo
+    ids: [archive]
+    repository:
+      owner: MY-RV
+      name: homebrew-tap
+      branch: main
+      token: "{{ .Env.TAP_GITHUB_TOKEN }}"
+    directory: Casks
+    homepage: "https://github.com/MY-RV/godo"
+    description: "Thin repo command catalog"
+    skip_upload: '{{ if .Env.TAP_GITHUB_TOKEN }}false{{ else }}true{{ end }}'
+    hooks:
+      post:
+        install: |
+          if system_command("/usr/bin/xattr", args: ["-h"]).exit_status == 0
+            system_command "/usr/bin/xattr", args: ["-dr", "com.apple.quarantine", "#{staged_path}/godo"]
+          end
+
+scoops:
+  - name: godo
+    ids: [archive]
+    repository:
+      owner: MY-RV
+      name: scoop-bucket
+      branch: main
+      token: "{{ .Env.TAP_GITHUB_TOKEN }}"
+    homepage: "https://github.com/MY-RV/godo"
+    description: "Thin repo command catalog"
+    license: "MIT"
+    skip_upload: '{{ if .Env.TAP_GITHUB_TOKEN }}false{{ else }}true{{ end }}'
+
 changelog:
   sort: asc
   filters:
diff --git a/README.md b/README.md
index 9fd75bf..245e122 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ godo -e version
 ## Install
 
 ```bash
-brew install MY-RV/tap/godo
+brew install --cask MY-RV/tap/godo
 ```
 
 ```bash
diff --git a/docs/distribution.md b/docs/distribution.md
index 9cff58e..71c10b7 100644
--- a/docs/distribution.md
+++ b/docs/distribution.md
@@ -8,7 +8,7 @@ Package / binary name is always **`godo`**. Module import path stays `github.com
 |---------|-----|
 | GitHub Releases | Download bare binary or archive — [install.md](./install.md) |
 | Go | `go install github.com/my-rv/godo/cmd/godo@v0.2.0` |
-| Homebrew | `brew install MY-RV/tap/godo` ([tap](https://github.com/MY-RV/homebrew-tap)) |
+| Homebrew (macOS) | `brew install --cask MY-RV/tap/godo` ([tap](https://github.com/MY-RV/homebrew-tap)) |
 | Scoop | `scoop bucket add my-rv https://github.com/MY-RV/scoop-bucket` then `scoop install godo` |
 | Self-update | `godo -e update` / `godo --update-check` |
 
@@ -18,10 +18,10 @@ Shared across godo, hensu, and future CLIs:
 
 | Store | Home | Install |
 |-------|------|---------|
-| Homebrew | [MY-RV/homebrew-tap](https://github.com/MY-RV/homebrew-tap) | `brew install MY-RV/tap/godo` |
+| Homebrew | [MY-RV/homebrew-tap](https://github.com/MY-RV/homebrew-tap) | `brew install --cask MY-RV/tap/godo` (`Casks/godo.rb`) |
 | Scoop | [MY-RV/scoop-bucket](https://github.com/MY-RV/scoop-bucket) | `scoop bucket add my-rv https://github.com/MY-RV/scoop-bucket` then `scoop install godo` |
 
-Fully-qualified Homebrew avoids clashing with unrelated taps that also expose a `godo` formula.
+Homebrew ships pre-built binaries as **casks** (macOS-only). The fully-qualified name avoids clashing with unrelated taps.
 
 ## Later / optional
 
diff --git a/docs/install.md b/docs/install.md
index 3f6d45a..743c02b 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -37,9 +37,13 @@ go build -ldflags "-X github.com/my-rv/godo.Version=v0.2.0" -o godo ./cmd/godo
 ## Package managers
 
 ```bash
-brew install MY-RV/tap/godo
+brew install --cask MY-RV/tap/godo
 ```
 
+Homebrew ships pre-built binaries as a **cask**, and casks are macOS-only. On Linux use Go or the release binary.
+
+If you previously installed the Formula (`brew install MY-RV/tap/godo`), uninstall it first: `brew uninstall godo`, then install the cask.
+
 ```powershell
 scoop bucket add my-rv https://github.com/MY-RV/scoop-bucket
 scoop install godo
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 1450654..545ab2a 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -18,7 +18,7 @@ This is what we **commit to communicate**. Pre-1.0 APIs can still change within
 
 ## Post-v0.1 — intended (not promised dates)
 
-- Shared family packaging: `MY-RV/homebrew-tap` (`brew install MY-RV/tap/godo`), `MY-RV/scoop-bucket`
+- Shared family packaging: `MY-RV/homebrew-tap` (`brew install --cask MY-RV/tap/godo`), `MY-RV/scoop-bucket`
 - Optional: winget (`MY-RV.Godo`), later choco / AUR / Nix as demand appears
 - Engine command registry polish; more e2e
 - Dialects backlog only if explicitly promoted here