From 892c2ff70095afa37ca21f352f05f40c95c80e41 Mon Sep 17 00:00:00 2001
From: Toddy Mladenov <toddysm@gmail.com>
Date: Wed, 1 Jul 2026 18:10:35 -0700
Subject: [PATCH 1/2] Restore Homebrew install guide content

The file was committed empty in #64; add the intended install/upgrade/
uninstall documentation.
---
 docs/guides/homebrew-install.md | 57 +++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/docs/guides/homebrew-install.md b/docs/guides/homebrew-install.md
index e69de29..57ce54e 100644
--- a/docs/guides/homebrew-install.md
+++ b/docs/guides/homebrew-install.md
@@ -0,0 +1,57 @@
+# Installing RegShape with Homebrew
+
+RegShape is distributed through a [Homebrew](https://brew.sh) tap so you can
+install and update the CLI with a single command on macOS and Linux.
+
+## Install
+
+```bash
+brew install toddysm/regshape/regshape
+```
+
+This automatically taps `toddysm/regshape` and installs the `regshape` formula.
+You can also tap explicitly first:
+
+```bash
+brew tap toddysm/regshape
+brew install regshape
+```
+
+Verify the installation:
+
+```bash
+regshape --version
+regshape --help
+```
+
+## Upgrade
+
+```bash
+brew update
+brew upgrade regshape
+```
+
+## Uninstall
+
+```bash
+brew uninstall regshape
+brew untap toddysm/regshape
+```
+
+## How it works
+
+- The formula lives in the [toddysm/homebrew-regshape](https://github.com/toddysm/homebrew-regshape)
+  tap repository.
+- RegShape is installed into an isolated Python virtualenv with pinned
+  dependency resources, so it does not interfere with your system Python.
+- On every RegShape release, the project's release workflow publishes the new
+  version to PyPI and then opens a pull request in the tap to bump the formula
+  (source URL and checksum) to match. Once that PR is merged, `brew upgrade`
+  picks up the new version.
+
+## Troubleshooting
+
+- **`Error: No available formula`** — run `brew update` and ensure the tap is
+  present with `brew tap`.
+- **Stale version after a release** — the formula bump PR in the tap may not be
+  merged yet; check the [tap pull requests](https://github.com/toddysm/homebrew-regshape/pulls).

From 4b911478030f3d00062625633da27b9f2b71e5a8 Mon Sep 17 00:00:00 2001
From: Toddy Mladenov <toddysm@gmail.com>
Date: Wed, 1 Jul 2026 18:13:05 -0700
Subject: [PATCH 2/2] Address review: use 'Guide:' title prefix and fix brew
 tap hint

---
 docs/guides/homebrew-install.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/guides/homebrew-install.md b/docs/guides/homebrew-install.md
index 57ce54e..a448a92 100644
--- a/docs/guides/homebrew-install.md
+++ b/docs/guides/homebrew-install.md
@@ -1,4 +1,4 @@
-# Installing RegShape with Homebrew
+# Guide: Install RegShape with Homebrew
 
 RegShape is distributed through a [Homebrew](https://brew.sh) tap so you can
 install and update the CLI with a single command on macOS and Linux.
@@ -51,7 +51,7 @@ brew untap toddysm/regshape
 
 ## Troubleshooting
 
-- **`Error: No available formula`** — run `brew update` and ensure the tap is
-  present with `brew tap`.
+- **`Error: No available formula`** — run `brew update`, and ensure the tap is
+  installed with `brew tap toddysm/regshape`.
 - **Stale version after a release** — the formula bump PR in the tap may not be
   merged yet; check the [tap pull requests](https://github.com/toddysm/homebrew-regshape/pulls).