docs: document the macOS Gatekeeper first-run steps for Homebrew install

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project are documented here. Format loosely
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions
 follow [SemVer](https://semver.org/).
 
-## [Unreleased]
+## [1.8.1]
 
 ### Added
 
@@ -42,6 +42,12 @@ follow [SemVer](https://semver.org/).
 
 ### Changed
 
+- **Homebrew install docs** (README and the landing page's `brew` tab)
+  now walk through the one-time Gatekeeper approval macOS still requires
+  on first launch (the cask clears the quarantine attribute, but the
+  binary is unsigned) — screenshots and steps courtesy of
+  [@Sk8teb0arder](https://github.com/Sk8teb0arder) (see
+  [#9](https://github.com/padovanl/pkgtui/issues/9)).
 - The `P` screen manages **third-party sources generally**, not just apt
   PPAs: flatpak remotes now use it too, each backend labelling them in its
   own words. A rebound `P` key keeps working — the setting is still stored

README.md

@@ -211,7 +211,30 @@ URL for repos named that way.
 
 The cask covers Apple Silicon, Intel Macs and Linuxbrew, and clears the
 Gatekeeper quarantine attribute itself, which matters because these
-binaries aren't notarized.
+binaries aren't notarized. macOS still requires one manual approval on
+the very first launch, since the binary is unsigned — not required again
+after that:
+
+1. Right after `brew install --cask pkgtui` finishes, macOS reports
+   *"pkgtui" Not Opened* since the binary isn't notarized — click
+   **Done** (not Move to Bin), it's already on your `PATH`.
+
+   <img src="https://raw.githubusercontent.com/padovanl/pkgtui/main/assets/macos-first-run/01-not-opened.png" alt="macOS dialog reading pkgtui Not Opened, with Done and Move to Bin buttons" width="420">
+
+2. Open **System Settings → Privacy & Security**, scroll down to the
+   note that *"pkgtui" was blocked to protect your Mac*, and click
+   **Allow Anyway**.
+
+   <img src="https://raw.githubusercontent.com/padovanl/pkgtui/main/assets/macos-first-run/02-allow-anyway.png" alt="macOS Privacy and Security settings showing pkgtui was blocked, with an Allow Anyway button" width="420">
+
+3. Open a terminal and run `pkgtui` again — an *Open "pkgtui"?* prompt
+   appears, click **Open Anyway**, then enter your password when asked.
+   `pkgtui` starts normally from then on.
+
+   <img src="https://raw.githubusercontent.com/padovanl/pkgtui/main/assets/macos-first-run/03-open-anyway.png" alt="macOS dialog asking Open pkgtui, with Move to Bin, Open Anyway and Done buttons" width="420">
+
+(Thanks to [@Sk8teb0arder](https://github.com/Sk8teb0arder) for walking
+through this and sharing the screenshots.)
 
 ### macOS without Homebrew
 

docs/index.html

@@ -341,6 +341,12 @@
   .install-panel.active { display: block; }
   .comment { color: var(--rust-dim); }
   .install-note { color: var(--rust); font-size: 0.88rem; font-family: var(--serif); }
+  .first-run { margin-top: 16px; border: 1px solid var(--hairline); border-radius: 6px; padding: 14px 18px; }
+  .first-run summary { cursor: pointer; color: var(--rust); font-family: var(--serif); font-size: 0.92rem; font-weight: 700; }
+  .first-run ol { margin: 12px 0 0; padding-left: 20px; color: var(--rust); font-family: var(--serif); font-size: 0.92rem; line-height: 1.6; }
+  .first-run li { margin-bottom: 14px; }
+  .first-run li:last-child { margin-bottom: 0; }
+  .first-run img { display: block; width: 100%; max-width: 420px; height: auto; border: 1px solid var(--hairline); border-radius: 4px; margin-top: 8px; }
 
   /* ---- keybinding reference ---- */
   .key-chips { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 34px; }
@@ -603,6 +609,18 @@ <h2>Installation</h2>
         <pre><span class="comment"># macOS (Apple Silicon or Intel) and Linuxbrew</span>
 brew tap padovanl/pkgtui https://github.com/padovanl/pkgtui
 brew install --cask pkgtui</pre>
+        <details class="first-run">
+          <summary>First launch on macOS: a few one-time clicks (Gatekeeper)</summary>
+          <ol>
+            <li>Right after <code class="mono">brew install --cask pkgtui</code> finishes, macOS reports <em>"pkgtui" Not Opened</em> since the binary isn't notarized — click <strong>Done</strong> (not Move to Bin), it's already been placed on your <code class="mono">PATH</code>.
+              <img src="https://raw.githubusercontent.com/padovanl/pkgtui/main/assets/macos-first-run/01-not-opened.png" alt="macOS dialog reading pkgtui Not Opened, with Done and Move to Bin buttons" loading="lazy"></li>
+            <li>Open <strong>System Settings → Privacy &amp; Security</strong>, scroll down to the note that <em>"pkgtui" was blocked to protect your Mac</em>, and click <strong>Allow Anyway</strong>.
+              <img src="https://raw.githubusercontent.com/padovanl/pkgtui/main/assets/macos-first-run/02-allow-anyway.png" alt="macOS Privacy and Security settings showing pkgtui was blocked, with an Allow Anyway button" loading="lazy"></li>
+            <li>Open a terminal and run <code class="mono">pkgtui</code> again — an <em>Open "pkgtui"?</em> prompt appears, click <strong>Open Anyway</strong>, then enter your password when asked. pkgtui starts normally from then on.
+              <img src="https://raw.githubusercontent.com/padovanl/pkgtui/main/assets/macos-first-run/03-open-anyway.png" alt="macOS dialog asking Open pkgtui, with Move to Bin, Open Anyway and Done buttons" loading="lazy"></li>
+          </ol>
+          <p class="install-note">Only needed once, on the very first launch — thanks to <a href="https://github.com/Sk8teb0arder">@Sk8teb0arder</a> for walking through this and sharing the screenshots.</p>
+        </details>
       </div>
       <div id="tab-mac" class="install-panel">
         <pre><span class="comment"># without Homebrew: darwin_arm64 on Apple Silicon, darwin_amd64 on Intel</span>