docs: document brew trust step for Homebrew 6.0+

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` |

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

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">

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;