From 15415ada6f4a435986653d7cb51a05cf0fa1e00b Mon Sep 17 00:00:00 2001
From: Emmanuel Boudrant <eboudrant@netflix.com>
Date: Mon, 6 Jul 2026 11:27:13 -0700
Subject: [PATCH] docs: document brew trust step for Homebrew 6.0+ tap trust

Homebrew 6.0 (June 2026) requires third-party taps to be trusted before
it will load their casks, so install/upgrade now fails with "Refusing to
load cask ... from untrusted tap". Add the one-time `brew trust
eboudrant/tap` step to the README, the docs site, and the in-app update
banner command.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGES/2026-07-06_docs-brew-trust-tap.md | 40 +++++++++++++++++++++++
 README.md                                 |  8 +++++
 docs/index.html                           |  4 ++-
 static/js/home.js                         |  5 ++-
 4 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 CHANGES/2026-07-06_docs-brew-trust-tap.md

diff --git a/CHANGES/2026-07-06_docs-brew-trust-tap.md b/CHANGES/2026-07-06_docs-brew-trust-tap.md
new file mode 100644
index 0000000..e14ca0b
--- /dev/null
+++ b/CHANGES/2026-07-06_docs-brew-trust-tap.md
@@ -0,0 +1,40 @@
+# docs: document `brew trust` for Homebrew 6.0+ tap trust
+
+**Date:** 2026-07-06
+**Type:** Docs
+
+## Intent
+Homebrew 6.0 (June 2026) added a security requirement: third-party (non-official)
+taps must be explicitly trusted before Homebrew will load their casks. Users hit
+`Error: Refusing to load cask eboudrant/tap/papastudio from untrusted tap` on
+install and upgrade. Document the one-time `brew trust eboudrant/tap` step across
+the README, the docs site, and the in-app update banner.
+
+### Prompts summary
+1. User reported `brew upgrade --cask papastudio` failing with the untrusted-tap error.
+2. User asked to update the README and/or the in-product instructions.
+
+## Changes
+
+### `README.md`
+- Added `brew trust eboudrant/tap` to the Install block with a note that it's
+  Homebrew 6.0+ only and can be skipped on older versions.
+- Added an Update note pointing at `brew trust` when the upgrade hits the
+  untrusted-tap error.
+
+### `docs/index.html`
+- Added the `brew trust` line to the install `<pre>` block and a caption
+  explaining the 6.0+ requirement.
+
+### `static/js/home.js`
+- Chained `brew trust eboudrant/tap && ` into the in-app update banner's
+  `UPDATE_CMD` so the copy button yields a command that works on 6.0+.
+  `brew trust` is idempotent, so this stays a no-op once the tap is trusted.
+
+## Files modified
+
+| File | Change |
+|------|--------|
+| `README.md` | Install/Update instructions include `brew trust` step |
+| `docs/index.html` | Install block + caption document tap trust |
+| `static/js/home.js` | Update banner command chains `brew trust` |
diff --git a/README.md b/README.md
index c5c6bdc..507c895 100644
--- a/README.md
+++ b/README.md
@@ -16,15 +16,23 @@ https://github.com/user-attachments/assets/c8d35b14-fd80-4e6e-989f-63c041bea9a7
 
 ```
 brew tap eboudrant/tap
+brew trust eboudrant/tap        # Homebrew 6.0+ only
 brew install --cask papastudio
 ```
 
+Homebrew 6.0 (June 2026) requires third-party taps to be trusted before it will
+load their casks. If `brew trust` isn't recognized you're on an older Homebrew
+and can skip that line.
+
 ## Update
 
 ```
 brew update && brew upgrade --cask papastudio
 ```
 
+If the upgrade fails with *"Refusing to load cask ... from untrusted tap"*, run
+`brew trust eboudrant/tap` once, then retry.
+
 ## Run from source
 
 ```bash
diff --git a/docs/index.html b/docs/index.html
index 14355ba..bf65945 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -701,12 +701,14 @@ <h3>Review CI results remotely</h3>
 <section id="install">
   <span class="section-eyebrow reveal">Install</span>
   <h2 class="section-title reveal">Up and running in seconds</h2>
-  <p class="section-sub reveal">macOS via Homebrew. Single command, no extra setup.</p>
+  <p class="section-sub reveal">macOS via Homebrew. A few commands, no extra setup.</p>
   <div class="pre-wrap reveal">
     <pre>brew tap eboudrant/tap
+brew trust eboudrant/tap
 brew install --cask papastudio</pre>
     <button class="btn-copy" onclick="_copy(this)" aria-label="Copy install command">Copy</button>
   </div>
+  <p class="section-sub reveal"><code>brew trust</code> is required on Homebrew 6.0+ before it will load a third-party tap. On older Homebrew that line is unnecessary — skip it.</p>
 </section>
 
 <section id="screenshots">
diff --git a/static/js/home.js b/static/js/home.js
index 82c1daa..c2fa9a3 100644
--- a/static/js/home.js
+++ b/static/js/home.js
@@ -69,7 +69,10 @@ async function _loadHome() {
   _checkForUpdateOnce();
 }
 
-const UPDATE_CMD = 'brew upgrade --cask papastudio';
+// Homebrew 6.0+ (June 2026) requires third-party taps to be trusted before it
+// will load their casks; `brew trust` is idempotent and a no-op once trusted,
+// so chaining it keeps the copy-paste command working across upgrades.
+const UPDATE_CMD = 'brew trust eboudrant/tap && brew upgrade --cask papastudio';
 const UPDATE_DISMISSED_KEY = 'papastud_update_dismissed';
 let _updateChecked = false;