docs: make Homebrew the primary install path

.github/workflows/release.yml

@@ -52,13 +52,13 @@ jobs:
           ## Install
 
           \`\`\`bash
-          brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && HOMEBREW_CASK_OPTS=--no-quarantine brew install --cask JNHFlow21/tap/agent-switch
+          brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && brew install --cask JNHFlow21/tap/agent-switch
           \`\`\`
 
           This build is ad-hoc signed and not notarized because the project does
-          not yet have an Apple Developer ID. The install command deliberately
-          disables Gatekeeper quarantine for this cask installation. Review the
-          public source and checksums before installing.
+          not yet have an Apple Developer ID. The project-owned Cask removes
+          Gatekeeper quarantine after installation. Review the public source and
+          checksums before installing.
           EOF
           gh release create "$GITHUB_REF_NAME" \
             dist/Agent-Switch-"$version"-macos-universal.zip \

README.md

@@ -18,53 +18,46 @@ Agent Switch replaces those copies with one local registry, one private
 credential store, and deterministic per-agent projections.
 
 > [!IMPORTANT]
-> Agent Switch is **alpha software**. The current installer builds from source
-> and requires Xcode. The intended public distribution is a Developer ID-signed,
-> notarized GitHub Release installed through Homebrew Cask. That release channel
-> is not available yet, so this README does not advertise a fake `brew` command.
+> Agent Switch is **alpha software**. The public app is ad-hoc signed and is not
+> Apple-notarized. The project-owned Homebrew Cask therefore removes Gatekeeper
+> quarantine after installation. Review the [public source](https://github.com/JNHFlow21/agent-switch)
+> and [release checksums](https://github.com/JNHFlow21/agent-switch/releases/tag/v0.2.0)
+> before installing.
 
 ## Quick start
 
 ### Prerequisites
 
 - macOS 14 or newer
-- Git
-- Python 3.11 or newer
-- [`pipx`](https://pipx.pypa.io/)
-- Full Xcode with `xcodebuild`
-
-Install missing command-line prerequisites with:
-
-```bash
-brew install python pipx
-```
+- Homebrew 6.0 or newer
 
 ### Install
 
-Run one verified source-install command:
+Paste one verified command:
 
 ```bash
-git clone https://github.com/JNHFlow21/agent-switch.git && cd agent-switch && ./scripts/install.sh
+brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && brew install --cask JNHFlow21/tap/agent-switch
 ```
 
-The installer:
+Homebrew:
 
-1. verifies macOS, Python, pipx, and Xcode;
-2. installs the Python CLI in an isolated pipx environment;
-3. builds and installs the native app at `~/Applications/Agent Switch.app`;
-4. creates a neutral, empty Agent Switch config if none exists;
-5. opens the app without adopting MCPs or rewriting native agent configs.
+1. registers and explicitly trusts the project-owned Tap;
+2. installs the `agent-switch` CLI through `agent-switch-cli`;
+3. installs the universal native app at `/Applications/Agent Switch.app`;
+4. removes Gatekeeper quarantine because this alpha is not notarized;
+5. leaves MCP adoption and native agent configuration unchanged.
 
 Expected first result:
 
 ```text
 agent-switch --version  -> agent-switch 0.2.0
-Native app              -> opens from ~/Applications/Agent Switch.app
+Native app              -> /Applications/Agent Switch.app
 ```
 
-Then preview your existing user-level command/stdio MCPs:
+Open Agent Switch from Applications, or run:
 
 ```bash
+open -a "Agent Switch"
 agent-switch mcp import --dry-run --json
 agent-switch doctor
 ```
@@ -73,20 +66,20 @@ Review the detected MCP IDs, target apps, and required secret **names** before
 running `agent-switch mcp import --adopt` or `agent-switch reconcile`.
 
 <details>
-<summary>Why not npm, NPX, or a public Homebrew command?</summary>
+<summary>Why Homebrew instead of npm or NPX?</summary>
 
 Agent Switch is a native macOS application with a Python CLI; Node.js is not
 part of its runtime. npm/NPX would add an unrelated dependency and still need
 to build or download the macOS app.
 
-The correct end-user channel is:
+The current alpha distribution is:
 
 ```text
-signed + notarized release artifact -> GitHub Releases -> Homebrew Cask
+ad-hoc signed release artifact -> GitHub Releases -> project-owned Homebrew Cask
 ```
 
-Until that artifact exists, the source installer above is the shortest honest
-path. See the [roadmap](docs/roadmap.md).
+Developer ID signing and notarization remain the stable-release target. See the
+[roadmap](docs/roadmap.md).
 
 </details>
 
@@ -210,8 +203,8 @@ It does **not** yet provide:
 - migration for native HTTP/SSE transports or OAuth sessions;
 - project-scoped MCP discovery;
 - automatic support for unknown agents;
-- a signed and notarized downloadable app;
-- a published Homebrew Cask or Python package;
+- a Developer ID-signed and notarized downloadable app;
+- a published PyPI package;
 - a password-manager or hardware-backed credential vault.
 
 These are limitations, not hidden features. Planned work lives in the
@@ -247,10 +240,11 @@ safe import behavior.
 
 ## Update
 
-From the cloned repository:
+Homebrew installations:
 
 ```bash
-git pull --ff-only && ./scripts/install.sh
+brew update
+brew upgrade --cask JNHFlow21/tap/agent-switch
 ```
 
 Agent Switch does not silently update itself, third-party CLIs, or Skill
@@ -268,6 +262,15 @@ sources.
 
 ## Development
 
+The source installer remains available for contributors who have Python 3.11+,
+`pipx`, and full Xcode:
+
+```bash
+git clone https://github.com/JNHFlow21/agent-switch.git && cd agent-switch && ./scripts/install.sh
+```
+
+For an editable CLI environment:
+
 ```bash
 git clone https://github.com/JNHFlow21/agent-switch.git
 cd agent-switch

README.zh-CN.md

@@ -17,53 +17,45 @@ Agent Switch 用一个本地 MCP 注册表、一个私密凭据存储和可重
 配置替代这些副本。
 
 > [!IMPORTANT]
-> Agent Switch 目前仍是 **Alpha 软件**。当前安装器会在本机从源码构建，因此需要
-> Xcode。正式面向用户的发行方式应当是经过 Developer ID 签名和 Apple 公证的
-> GitHub Release，并通过 Homebrew Cask 安装。这个发行通道尚未完成，所以这里不会
-> 放一个实际上不能使用的 `brew` 命令。
+> Agent Switch 目前仍是 **Alpha 软件**。公开 App 使用 ad-hoc 签名，尚未经过
+> Apple 公证，因此项目自己的 Homebrew Cask 会在安装完成后移除 Gatekeeper
+> quarantine。安装前请先检查[公开源码](https://github.com/JNHFlow21/agent-switch)
+> 和[发行校验和](https://github.com/JNHFlow21/agent-switch/releases/tag/v0.2.0)。
 
 ## 快速开始
 
 ### 前置条件
 
 - macOS 14 或更高版本
-- Git
-- Python 3.11 或更高版本
-- [`pipx`](https://pipx.pypa.io/)
-- 包含 `xcodebuild` 的完整 Xcode
-
-缺少命令行依赖时，可以运行：
-
-```bash
-brew install python pipx
-```
+- Homebrew 6.0 或更高版本
 
 ### 安装
 
-运行下面这一条经过验证的源码安装命令：
+复制执行下面这一条经过验证的命令：
 
 ```bash
-git clone https://github.com/JNHFlow21/agent-switch.git && cd agent-switch && ./scripts/install.sh
+brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && brew install --cask JNHFlow21/tap/agent-switch
 ```
 
-安装器会：
+Homebrew 会：
 
-1. 检查 macOS、Python、pipx 和 Xcode；
-2. 在独立的 pipx 环境中安装 Python CLI；
-3. 构建原生应用并安装到 `~/Applications/Agent Switch.app`；
-4. 仅在配置不存在时创建一个中立、空白的 Agent Switch 配置；
-5. 打开应用，但不会自动接管 MCP，也不会改写原生 Agent 配置。
+1. 注册并显式信任项目自己的 Tap；
+2. 通过 `agent-switch-cli` 安装 `agent-switch` CLI；
+3. 把通用架构原生 App 安装到 `/Applications/Agent Switch.app`；
+4. 因为当前 Alpha 尚未公证，所以移除 Gatekeeper quarantine；
+5. 不会自动接管 MCP，也不会改写原生 Agent 配置。
 
 首次安装成功后应当看到：
 
 ```text
 agent-switch --version  -> agent-switch 0.2.0
-原生应用                  -> 从 ~/Applications/Agent Switch.app 打开
+原生应用                  -> /Applications/Agent Switch.app
 ```
 
-然后先预览已有的用户级 command/stdio MCP：
+从“应用程序”打开 Agent Switch，或者运行：
 
 ```bash
+open -a "Agent Switch"
 agent-switch mcp import --dry-run --json
 agent-switch doctor
 ```
@@ -72,19 +64,18 @@ agent-switch doctor
 之前，请先检查检测到的 MCP ID、目标应用和所需密钥的**名称**。
 
 <details>
-<summary>为什么不使用 npm、NPX 或直接写一个 Homebrew 命令？</summary>
+<summary>为什么使用 Homebrew，而不是 npm 或 NPX？</summary>
 
 Agent Switch 是原生 macOS 应用加 Python CLI，Node.js 并不是它的运行时。
 npm/NPX 只会引入无关依赖，最终仍然需要构建或下载 macOS 应用。
 
-正确的用户发行链路应当是：
+当前 Alpha 的发行链路是：
 
 ```text
-签名并公证的发行产物 -> GitHub Releases -> Homebrew Cask
+ad-hoc 签名的发行产物 -> GitHub Releases -> 项目自己的 Homebrew Cask
 ```
 
-在这个产物真正存在之前，上面的源码安装器是最短且诚实的路径。详情见
-[路线图](docs/roadmap.md)。
+Developer ID 签名和 Apple 公证仍然是稳定版目标。详情见[路线图](docs/roadmap.md)。
 
 </details>
 
@@ -200,8 +191,8 @@ Agent Switch 是本地优先工具，但它**不是密码保险库**。
 - 原生 HTTP/SSE Transport 或 OAuth Session 迁移；
 - 项目级 MCP 发现；
 - 对未知 Agent 的自动支持；
-- 已签名并公证的可下载应用；
-- 已发布的 Homebrew Cask 或 Python 包；
+- 经过 Developer ID 签名并公证的可下载应用；
+- 已发布的 PyPI 包；
 - 密码管理器或硬件保护的凭据保险库。
 
 这些是明确限制，不是隐藏功能。计划中的工作记录在[路线图](docs/roadmap.md)中。
@@ -235,10 +226,11 @@ agent-switch reconcile
 
 ## 更新
 
-在已经克隆的仓库中运行：
+通过 Homebrew 安装的版本：
 
 ```bash
-git pull --ff-only && ./scripts/install.sh
+brew update
+brew upgrade --cask JNHFlow21/tap/agent-switch
 ```
 
 Agent Switch 不会静默更新自己、第三方 CLI 或 Skill 源。
@@ -255,6 +247,14 @@ Agent Switch 不会静默更新自己、第三方 CLI 或 Skill 源。
 
 ## 开发
 
+需要 Python 3.11+、`pipx` 和完整 Xcode 的贡献者仍然可以使用源码安装器：
+
+```bash
+git clone https://github.com/JNHFlow21/agent-switch.git && cd agent-switch && ./scripts/install.sh
+```
+
+创建可编辑的 CLI 开发环境：
+
 ```bash
 git clone https://github.com/JNHFlow21/agent-switch.git
 cd agent-switch

docs/roadmap.md

@@ -23,9 +23,8 @@ distribution.
    explicit ownership choice before adoption.
 3. Add adapters through a documented contract and fixture suite rather than
    guessing unknown agent configuration formats.
-4. Ship a Developer ID-signed and notarized macOS release that packages the app
-   and CLI together, publish it through GitHub Releases, and make Homebrew Cask
-   the one-line end-user install path.
+4. Replace the current ad-hoc signed Homebrew alpha with a Developer ID-signed
+   and notarized release, then remove the Cask's Gatekeeper-quarantine bypass.
 5. Add complete English and Chinese localization plus a first-run wizard that
    previews targets, MCP IDs, and secret names before any write.
 6. Add a first-class backup browser and guided restore flow.

tests/test_docs.py

@@ -21,11 +21,19 @@ def test_docs_reference_current_commands_and_boundaries(self) -> None:
         self.assertIn("README.zh-CN.md", "\n".join(readme.splitlines()[:12]))
         self.assertIn("README.md", "\n".join(readme_zh.splitlines()[:12]))
         install_command = (
-            "git clone https://github.com/JNHFlow21/agent-switch.git && "
-            "cd agent-switch && ./scripts/install.sh"
+            "brew tap JNHFlow21/tap && brew trust --tap JNHFlow21/tap && "
+            "brew install --cask JNHFlow21/tap/agent-switch"
         )
         self.assertIn(install_command, readme)
         self.assertIn(install_command, readme_zh)
+        source_command = (
+            "git clone https://github.com/JNHFlow21/agent-switch.git && "
+            "cd agent-switch && ./scripts/install.sh"
+        )
+        self.assertIn(source_command, readme)
+        self.assertIn(source_command, readme_zh)
+        self.assertIn("removes Gatekeeper quarantine", readme)
+        self.assertIn("移除 Gatekeeper quarantine", readme_zh)
         self.assertIn("agent-*", compat)
         self.assertIn("CC Switch", compat)
         self.assertIn("agent-switch reconcile", recovery)