Document HTTPS Homebrew tap install and SSH update recovery

README.md

@@ -125,11 +125,11 @@ Tracks the default branch. For a reproducible install, choose a published tag fr
 ### Homebrew (macOS / Linux)
 
 ```bash
-brew tap tonythethompson/numan
+brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan
 brew install numan
 ```
 
-Uses the public [`homebrew-numan`](https://github.com/tonythethompson/homebrew-numan) tap. Formula digests update automatically after each GitHub Release (see [docs/PACKAGING.md](docs/PACKAGING.md)).
+Uses the public [`homebrew-numan`](https://github.com/tonythethompson/homebrew-numan) tap. Prefer the explicit HTTPS remote so `brew update` does not depend on SSH host keys. Formula digests update automatically after each GitHub Release (see [docs/PACKAGING.md](docs/PACKAGING.md)).
 
 ### winget (Windows)
 
@@ -177,7 +177,7 @@ Install with **one** of the options below, then run the activation path.
 **Homebrew (macOS / Linux)**
 
 ```bash
-brew tap tonythethompson/numan && brew install numan
+brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan && brew install numan
 ```
 
 **winget (Windows)**

docs/PACKAGING.md

@@ -17,7 +17,7 @@ After a GitHub Release is published (see [RELEASING.md](RELEASING.md)):
 4. Spot-check on a Mac or Linux Homebrew host:
 
    ```bash
-   brew tap tonythethompson/numan
+   brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan
    brew update
    brew install numan
    numan --version
@@ -37,7 +37,7 @@ python3 scripts/render_homebrew_formula.py --version X.Y.Z --sha256sums SHA256SU
 | GitHub Release | Download archive from [Releases](https://github.com/tonythethompson/numan/releases) |
 | crates.io | `cargo install numan-cli` |
 | From git | `cargo install --git https://github.com/tonythethompson/numan` |
-| Homebrew (tap) | `brew tap tonythethompson/numan && brew install numan` |
+| Homebrew (tap) | `brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan && brew install numan` |
 | winget (community) | `winget install tonythethompson.numan` |
 
 ## Archive layout
@@ -64,4 +64,15 @@ Release archives extract to `numan-<version>-<target>/` containing the `numan`
 The Homebrew tap repository must stay **public**. Private visibility is why
 `brew tap tonythethompson/numan` previously failed for most users.
 
+If `brew update` fails with `Host key verification failed` for this tap, the
+local clone is on an SSH remote and can leave an old formula installed. Uninstall
+the stale formula first so `brew untap` can proceed, then recover with:
+
+```bash
+brew uninstall numan
+brew untap tonythethompson/numan
+brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan
+brew install tonythethompson/numan/numan
+```
+
 Scoop is not packaged yet; see [Phase7Plan.md](plans/Phase7Plan.md).

docs/RELEASING.md

@@ -103,5 +103,5 @@ PY
 | GitHub Release | Download archive from [Releases](https://github.com/tonythethompson/numan/releases) |
 | crates.io | `cargo install numan-cli` |
 | From source | `cargo install --path .` or `cargo install --git https://github.com/tonythethompson/numan` |
-| Homebrew | `brew tap tonythethompson/numan && brew install numan` (see [PACKAGING.md](PACKAGING.md)) |
+| Homebrew | `brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan && brew install numan` (see [PACKAGING.md](PACKAGING.md)) |
 | winget | `winget install tonythethompson.numan` (see [PACKAGING.md](PACKAGING.md)) |

packaging/homebrew/README.md

@@ -8,19 +8,57 @@ review; digests and bottle stanzas may lag until the next tagged release whose
 pre-Linux-ARM contract (macOS ARM + Linux x86_64 only) because no published
 release yet ships `aarch64-unknown-linux-gnu`. The live tap is
 [`tonythethompson/homebrew-numan`](https://github.com/tonythethompson/homebrew-numan)
-(`brew tap tonythethompson/numan`), updated by the publish workflow after each
+(tap with the HTTPS remote below), updated by the publish workflow after each
 `v*.*.*` release.
 
 ## Install
 
+Prefer the explicit HTTPS remote so `brew update` does not depend on SSH host
+keys or GitHub SSH auth:
+
 ```bash
-brew tap tonythethompson/numan
+brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan
 brew install numan
 ```
 
+`brew tap tonythethompson/numan` alone also works when Homebrew clones over
+HTTPS (the usual default for public taps).
+
 The tap repository **must be public**. A private tap is the main reason earlier
 `brew tap` / `brew install` attempts failed for users.
 
+## Troubleshooting
+
+### `Host key verification failed` while updating the tap
+
+`brew update` fetches each tapped repo with git. If this tap was cloned (or
+rewritten) to an SSH remote (`git@github.com:...`) and SSH host-key checks
+fail, the tap stays stale and installs can keep an old formula.
+
+Recover by uninstalling the stale formula, switching the tap to HTTPS, then
+reinstalling:
+
+```bash
+brew uninstall numan
+brew untap tonythethompson/numan
+brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan
+brew install tonythethompson/numan/numan
+```
+
+Or keep the tap and only fix the remote:
+
+```bash
+git -C "$(brew --repo tonythethompson/numan)" remote set-url origin https://github.com/tonythethompson/homebrew-numan.git
+brew update
+brew reinstall tonythethompson/numan/numan
+```
+
+If git still rewrites HTTPS to SSH, check for `url.*.insteadOf` rules:
+
+```bash
+git config --global --get-regexp '^url\..*\.insteadof$'
+```
+
 ## Updating for a release
 
 Prefer the automated path: after a `v*.*.*` GitHub Release, the

packaging/homebrew/numan.rb

@@ -3,8 +3,8 @@
 
 # Homebrew formula for Numan (Nushell package manager).
 #
-# Tap install:
-#   brew tap tonythethompson/numan
+# Tap install (HTTPS remote avoids SSH host-key update failures):
+#   brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan
 #   brew install numan
 #
 # Generated by scripts/render_homebrew_formula.py — do not hand-edit digests.

scripts/render_homebrew_formula.py

@@ -83,8 +83,8 @@ def render_formula(version: str, digests: dict[str, str]) -> str:
 
 # Homebrew formula for Numan (Nushell package manager).
 #
-# Tap install:
-#   brew tap tonythethompson/numan
+# Tap install (HTTPS remote avoids SSH host-key update failures):
+#   brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan
 #   brew install numan
 #
 # Generated by scripts/render_homebrew_formula.py — do not hand-edit digests.

scripts/test_render_homebrew_formula.py

@@ -53,6 +53,10 @@ def test_parse_and_render(self):
             "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", text
         )
         self.assertIn('bin.install "numan"', text)
+        self.assertIn(
+            "brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan",
+            text,
+        )
         self.assertNotIn("arch_dir", text)
         self.assertNotIn("expected numan-* directory", text)
         self.assertIn("on_intel do", text)