docs: promote Homebrew to primary installation path across docs and website

README.md

@@ -106,7 +106,7 @@ Same accuracy, dramatically better Apple platform integration.
 ## 📋 Requirements
 
 - **macOS 13 (Ventura)** or later
-- **Apple Silicon Mac** (M1/M2/M3/M4) — **Intel Macs are not supported.** The released DMG is built for `arm64` only.
+- **Apple Silicon Mac** (M1/M2/M3/M4) — **Intel Macs are not supported.** VocaMac is built for `arm64` only.
 - **Xcode 15+** or Swift 5.9+ (only for building from source)
 
 ### Permissions
@@ -125,7 +125,23 @@ VocaMac requires three macOS permissions:
 
 ## 🚀 Quick Start
 
-### Option 1: Download DMG (Recommended)
+### Option 1: Install via Homebrew (Recommended)
+
+```bash
+brew tap jatinkrmalik/vocamac
+brew trust --cask jatinkrmalik/vocamac/vocamac
+brew install --cask vocamac
+```
+
+Homebrew installs VocaMac to `/Applications/VocaMac.app`. Launch it from Spotlight or your Applications folder. Updates are a single command away:
+
+```bash
+brew upgrade --cask vocamac
+```
+
+> **Why Homebrew?** Terminal-based install. One-command updates. Permissions persist across upgrades. No manual DMG downloads. See [`docs/HOMEBREW.md`](docs/HOMEBREW.md) for the full Homebrew guide.
+
+### Option 2: Download DMG
 
 1. **Download** the latest `VocaMac-x.x.x-arm64.dmg` from the [Releases page](https://github.com/jatinkrmalik/vocamac/releases)
 2. **Open** the DMG and drag VocaMac to Applications
@@ -134,7 +150,7 @@ VocaMac requires three macOS permissions:
 
 > VocaMac is **Developer ID signed and notarized** by Apple — macOS will open it without any security warnings.
 
-### Option 2: Build from Source (Recommended)
+### Option 3: Build from Source
 
 ```bash
 git clone https://github.com/jatinkrmalik/vocamac.git
@@ -144,7 +160,7 @@ make install
 
 This builds VocaMac, installs it to `/Applications`, and launches it. Permissions are granted directly to VocaMac, just like the DMG method.
 
-### Option 3: CLI Commands (For Developers)
+### Option 4: CLI Commands (For Developers)
 
 ```bash
 git clone https://github.com/jatinkrmalik/vocamac.git
@@ -179,6 +195,14 @@ Nightly builds are automated builds from the latest `main` branch, published eve
 
 **How to install:**
 
+**Via Homebrew (recommended):**
+```bash
+brew tap jatinkrmalik/vocamac
+brew trust --cask jatinkrmalik/vocamac/vocamac-nightly
+brew install --cask vocamac-nightly
+```
+
+**Or via DMG:**
 1. Download the latest `VocaMac-nightly-*.dmg` from the [Nightly Release](https://github.com/jatinkrmalik/vocamac/releases/tag/nightly)
 2. Open the DMG and drag VocaMac to Applications
 3. Grant permissions when prompted (same as a stable release)

docs/ARCHITECTURE.md

@@ -301,7 +301,7 @@ Apple Silicon:
 
 > The `recommendModel` function in `SystemInfo.swift` retains a defensive
 > Intel branch (smaller models, no Metal). It exists only to keep the
-> code valid if someone compiles from source on Intel; the released DMG
+> code valid if someone compiles from source on Intel; the released binary
 > is `arm64`-only and Intel Macs are not a supported configuration.
 
 #### 3.2.8 `TextInjector` - System-Wide Text Insertion
@@ -337,9 +337,9 @@ CGEventSource(stateID: .hidSystemState)
 
 #### 3.2.9 `UpdateChecker` - GitHub Release Updates
 
-**Responsibility:** Detect new stable releases from GitHub, download the latest signed DMG, verify integrity, and guide the user through drag-to-replace installation.
+**Responsibility:** Detect new stable releases from GitHub and manage updates. For Homebrew-installed copies, it shows a `brew upgrade` command instead of in-app DMG downloads.
 
-**Update Flow:**
+**Update Flow (DMG installs):**
 ```
 On launch (max once every 24h)
   → GET /repos/jatinkrmalik/vocamac/releases/latest
@@ -351,6 +351,14 @@ On launch (max once every 24h)
   → Open DMG in Finder (user drags app to /Applications)
 ```
 
+**Update Flow (Homebrew installs):**
+```
+On launch (max once every 24h)
+  → Detect /Caskroom/ in Bundle.main.bundlePath
+  → If newer release available: show "brew upgrade --cask vocamac" banner
+  → User copies command and upgrades via Homebrew
+```
+
 **Manual Check:**
 - Settings → About includes **Check for Updates...**
 
@@ -495,8 +503,8 @@ swift build -c release
 
 ### 7.3 Distribution Strategy
 
-1. **GitHub Releases** — Developer ID signed & notarized DMG and ZIP, built by CI
-2. **Homebrew Cask** - `brew install --cask vocamac` (see docs/HOMEBREW.md)
+1. **Homebrew Cask** — `brew install --cask vocamac` (recommended, see `docs/HOMEBREW.md`)
+2. **GitHub Releases** — Developer ID signed & notarized DMG and ZIP, built by CI
 3. **Mac App Store** - Future consideration (requires sandbox compliance)
 
 ---

docs/HOMEBREW.md

@@ -1,19 +1,22 @@
 # VocaMac Homebrew Distribution Guide
 
+> **🍺 Homebrew is the recommended way to install VocaMac.** See the [README](../README.md#-quick-start) for the full installation options.
+
 ## Overview
 
 VocaMac is distributed via Homebrew as a **cask**, not a formula. This distinction matters:
 
 - **Formula** — for command-line tools and libraries built from source
 - **Cask** — for pre-built macOS applications distributed as binaries (`.app`, `.dmg`)
 
-Since VocaMac is a native macOS `.app` distributed as a signed and notarized DMG via GitHub Releases, a cask is the correct packaging format. Users get the exact same binary as the manual download, installed with a single command.
+Since VocaMac is a native macOS `.app` primarily distributed via Homebrew (with DMG downloads also available via GitHub Releases), a cask is the correct packaging format.
 
 ## Quick Start (For Users)
 
 ```bash
 # Install
 brew tap jatinkrmalik/vocamac
+brew trust --cask jatinkrmalik/vocamac/vocamac
 brew install --cask vocamac
 
 # Upgrade to latest version
@@ -31,6 +34,8 @@ After installation, VocaMac appears in `/Applications/VocaMac.app`. Launch it fr
 A nightly cask is also available, built daily from the latest `main` branch:
 
 ```bash
+brew tap jatinkrmalik/vocamac
+brew trust --cask jatinkrmalik/vocamac/vocamac-nightly
 brew install --cask vocamac-nightly
 ```
 
@@ -40,6 +45,7 @@ The nightly cask uses `version :latest` and `sha256 :no_check` because the DMG c
 
 ```bash
 brew uninstall --cask vocamac
+brew trust --cask jatinkrmalik/vocamac/vocamac-nightly
 brew install --cask vocamac-nightly
 ```
 
@@ -75,17 +81,26 @@ The cask lives in a custom tap repository: `jatinkrmalik/homebrew-vocamac`.
    git push origin main
    ```
 
-Users can then install with `brew tap jatinkrmalik/vocamac && brew install --cask vocamac`.
+Users can then install with:
+
+```bash
+brew tap jatinkrmalik/vocamac
+brew trust --cask jatinkrmalik/vocamac/vocamac
+brew install --cask vocamac
+```
 
 ## Testing Locally
 
-Before pushing a cask update to the tap, test it locally against a real DMG:
+Before pushing a cask update to the tap, test it from a tap checkout against a real DMG. Homebrew 6 rejects loose cask files outside a tap, so copy the cask into a local tap checkout first:
 
 ```bash
-brew install --cask ./homebrew/Casks/vocamac.rb
+brew tap jatinkrmalik/vocamac
+cp homebrew/Casks/vocamac.rb "$(brew --repository jatinkrmalik/vocamac)/Casks/vocamac.rb"
+brew trust --cask jatinkrmalik/vocamac/vocamac
+brew install --cask vocamac
 ```
 
-This installs the cask directly from the file path, bypassing the tap. It requires a real DMG to exist at the URL specified in the cask (i.e., a published GitHub Release).
+This installs the cask from the local tap checkout. It requires a real DMG to exist at the URL specified in the cask (i.e., a published GitHub Release).
 
 To verify the installation:
 
@@ -100,6 +115,8 @@ To uninstall after testing:
 brew uninstall --cask vocamac
 ```
 
+Then restore or commit the tap checkout changes, depending on whether the test was for a local-only change or a real tap update.
+
 ## Manual Cask Update
 
 When a new VocaMac version ships, the cask needs two updates: the `version` string and the `sha256` checksum.
@@ -226,6 +243,18 @@ A previous installation exists at `/Applications/VocaMac.app`.
 **Fix:** Remove the existing app first:
 ```bash
 rm -rf /Applications/VocaMac.app
+brew trust --cask jatinkrmalik/vocamac/vocamac
+brew install --cask vocamac
+```
+
+### Homebrew refuses to load the cask from an untrusted tap
+
+Homebrew 6 requires explicit trust for casks from third-party taps.
+
+**Fix:** Trust the VocaMac cask, then install again:
+
+```bash
+brew trust --cask jatinkrmalik/vocamac/vocamac
 brew install --cask vocamac
 ```
 

web/content/features/github-release-updates.md

@@ -1,22 +1,24 @@
 ---
 title: "GitHub Release Updates"
-subtitle: "VocaMac checks GitHub Releases, downloads the latest signed DMG, and guides you through drag-to-replace updates."
+subtitle: "VocaMac checks GitHub Releases for updates. Homebrew users run `brew upgrade`. DMG users get in-app downloads."
 description: "VocaMac includes built-in update checks powered by the GitHub Releases API. See new versions in-app, download the signed DMG with progress, and install safely."
 keywords: "mac app update checker, github releases updater, signed dmg updates, menu bar app update flow, vocamac updates"
 icon: "⬇️"
 ---
 
 ## Built-In Update Checks
 
-VocaMac can now check for new releases directly from GitHub. It compares your current app version to the latest stable release, then shows an in-app update banner when a newer version is available.
+VocaMac checks for new releases directly from GitHub. It compares your current app version to the latest stable release, then shows an in-app update banner when a newer version is available.
+
+If you installed VocaMac via Homebrew (`brew install --cask vocamac`), updates are managed by Homebrew — simply run `brew upgrade --cask vocamac`. VocaMac detects Homebrew installs and guides you accordingly.
 
 The check is lightweight and rate-limit friendly:
 
 - automatic check on launch (at most once every 24 hours)
 - manual **Check for Updates...** button in **Settings -> About**
 - no extra account, login, or update service required
 
-## Update Flow
+## Update Flow (DMG Installs)
 
 When an update is found, VocaMac shows a clear, non-intrusive banner in the menu bar popover. From there, you can open update details, review release notes, and start the download.
 

web/content/features/smart-model-selection.md

@@ -12,7 +12,7 @@ Every Apple Silicon Mac is different. An 8 GB MacBook Air has very different hea
 
 On first launch, VocaMac analyzes your chip generation, CPU core count, Neural Engine availability, and installed RAM. It then suggests the optimal model tier. You remain free to choose any model, but the recommendation gets you great results immediately without guesswork.
 
-> **Note:** VocaMac is Apple Silicon only. The released DMG does not run on Intel Macs.
+> **Note:** VocaMac is Apple Silicon only — it does not run on Intel Macs.
 
 ## Five Model Tiers