docs: improve macOS installation instructions

AGENTS.md

@@ -207,12 +207,17 @@ user's other hooks or config.
 
 ### One-click install test after changes
 
-After finishing a change (and its focused checks), run
-`scripts/install-macos.sh --local` (macOS only) to build the current workspace
-and install + launch it into `/Applications` so the user can test — do this
-proactively, without waiting for the user to ask. The script runs a release
-build and takes many minutes; run it in the background and follow it through
-to the final "完成" line.
+After finishing a code, configuration, packaging, or runtime-behavior change
+(and its focused checks), run `scripts/install-macos.sh --local` (macOS only)
+to build the current workspace and install + launch it into `/Applications` so
+the user can test — do this proactively, without waiting for the user to ask.
+The script runs a release build and takes many minutes; run it in the
+background and follow it through to the final "完成" line.
+
+For documentation-only changes, do not build, install, or launch the app unless
+the documentation is itself a build input or the user explicitly requests
+runtime verification. `git diff --check` is sufficient for ordinary Markdown
+edits.
 
 - `--local` skips the `git pull` and clean-tree guard and installs the working
   tree as-is (including uncommitted changes), which is what install-testing a

README.md

@@ -30,6 +30,22 @@ Familiar only manages its own Hook entries. Installation creates a backup and pr
 
 ## Install
 
+### Homebrew
+
+Install the desktop app on macOS:
+
+```bash
+brew install --cask Monster12138/familiar/familiar
+```
+
+Install the CLI on macOS or Linux:
+
+```bash
+brew install Monster12138/familiar/familiar-cli
+```
+
+### Download a release
+
 Download the latest release from [GitHub Releases](https://github.com/Monster12138/familiar/releases).
 
 Current release targets:
@@ -40,6 +56,30 @@ Current release targets:
 
 macOS packages are not notarized with an Apple Developer ID, and Windows packages are not code-signed. Gatekeeper or SmartScreen may require manual approval on first launch.
 
+### First launch on macOS
+
+Because Familiar is not yet notarized, macOS blocks it the first time you open
+it. If you installed Familiar from this repository's Homebrew tap or GitHub
+Releases, allow it manually:
+
+1. Open Familiar. When macOS says it cannot verify the app, click **Done**.
+
+   <img src="docs/images/macos-gatekeeper/01-unverified-app.jpg" alt="macOS cannot verify Familiar" width="420">
+
+2. Open **System Settings → Privacy & Security**, scroll to **Security**, find
+   the message that Familiar was blocked, and click **Open Anyway**.
+
+   <img src="docs/images/macos-gatekeeper/02-open-anyway-setting.jpg" alt="Open Anyway in macOS Privacy and Security settings" width="680">
+
+3. In the confirmation dialog, click **Open Anyway** again. Authenticate with
+   your password or Touch ID if macOS asks. Familiar will open normally from
+   then on.
+
+   <img src="docs/images/macos-gatekeeper/03-confirm-open.jpg" alt="Confirm opening Familiar on macOS" width="420">
+
+Only bypass this warning when you obtained Familiar from the official sources
+linked above.
+
 ## Build from source
 
 Requirements: Rust 1.88+, Node.js 18+, npm, and the desktop prerequisites for your platform.

README_zh.md

@@ -30,6 +30,22 @@ Familiar 只管理自己注入的 Hook。安装前会创建备份，并保留 Ag
 
 ## 安装
 
+### Homebrew
+
+在 macOS 上安装桌面应用：
+
+```bash
+brew install --cask Monster12138/familiar/familiar
+```
+
+在 macOS 或 Linux 上安装 CLI：
+
+```bash
+brew install Monster12138/familiar/familiar-cli
+```
+
+### 下载发布包
+
 从 [GitHub Releases](https://github.com/Monster12138/familiar/releases) 下载最新版本。
 
 当前发布目标：
@@ -40,6 +56,24 @@ Familiar 只管理自己注入的 Hook。安装前会创建备份，并保留 Ag
 
 macOS 安装包尚未使用 Apple Developer ID 签名和公证，Windows 安装包尚未进行代码签名。首次启动时，Gatekeeper 或 SmartScreen 可能要求手动允许。
 
+### macOS 首次启动
+
+由于 Familiar 尚未完成 Apple 公证，macOS 会在首次启动时阻止应用打开。如果你是通过本仓库的 Homebrew Tap 或 GitHub Releases 安装 Familiar，请按以下步骤手动允许：
+
+1. 打开 Familiar。macOS 提示无法验证应用时，点击**完成**。
+
+   <img src="docs/images/macos-gatekeeper/01-unverified-app.jpg" alt="macOS 无法验证 Familiar" width="420">
+
+2. 打开**系统设置 → 隐私与安全性**，向下滚动到**安全性**区域，找到 Familiar 已被阻止的提示，然后点击**仍要打开**。
+
+   <img src="docs/images/macos-gatekeeper/02-open-anyway-setting.jpg" alt="在 macOS 隐私与安全性设置中点击仍要打开" width="680">
+
+3. 在确认对话框中再次点击**仍要打开**。如果 macOS 要求认证，请输入密码或使用 Touch ID。此后 Familiar 即可正常打开。
+
+   <img src="docs/images/macos-gatekeeper/03-confirm-open.jpg" alt="确认在 macOS 上打开 Familiar" width="420">
+
+仅当 Familiar 来自上方链接的官方来源时，才应绕过此安全警告。
+
 ## 从源码构建
 
 需要 Rust 1.88+、Node.js 18+、npm，以及对应平台的桌面开发依赖。