docs: Unify installation sections and update for v2.0.0 stable

Restructure README and GETTING_STARTED installation sections into
two clear paths (Homebrew vs npm/npx) with a single-package intro.
Replace all stale @beta references with @latest to match the 2.0.0
stable release. Add Homebrew substitution note before client-specific
config sections. Document AXe local bundling and release workflow
modes.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

README.md

@@ -7,24 +7,52 @@ A Model Context Protocol (MCP) server and CLI that provides tools for agent use
 
 ## Installation
 
-### CLI Installation
+XcodeBuildMCP ships as a single package with two modes: a **CLI** for direct terminal use and an **MCP server** for AI coding agents. Both installation methods give you both modes.
+
+### Option A — Homebrew
 
 ```bash
-npm install -g xcodebuildmcp@latest
+brew tap cameroncooke/xcodebuildmcp
+brew install xcodebuildmcp
+```
+
+Use the CLI:
+```bash
 xcodebuildmcp --help
 ```
 
-### MCP Server Installation
+MCP client config:
+```json
+"XcodeBuildMCP": {
+  "command": "xcodebuildmcp",
+  "args": ["mcp"]
+}
+```
+
+Upgrade later with `brew update && brew upgrade xcodebuildmcp`.
 
-Add XcodeBuildMCP to your MCP client configuration. Most clients use JSON configuration with the following server entry:
+### Option B — npm / npx (Node.js 18+)
 
+**For CLI use**, install globally:
+```bash
+npm install -g xcodebuildmcp@latest
+xcodebuildmcp --help
+```
+
+**For MCP server only**, no global install needed — add directly to your client config:
 ```json
 "XcodeBuildMCP": {
   "command": "npx",
   "args": ["-y", "xcodebuildmcp@latest", "mcp"]
 }
 ```
 
+To pin a specific version, replace `@latest` with an exact version (e.g. `xcodebuildmcp@2.0.0`).
+
+### Client-specific setup
+
+The examples below use npx (Option B). If you installed via Homebrew, replace the command with `"command": "xcodebuildmcp", "args": ["mcp"]` instead.
+
 <details>
   <summary>Cursor</summary>
   <br />
@@ -188,7 +216,7 @@ Add XcodeBuildMCP to your MCP client configuration. Most clients use JSON config
   tool_timeout_sec = 10000
   ```
 
-  > **NOTE**: 
+  > **NOTE**:
   > Codex Agent when running in Xcode has a limited PATH by default. The above example should work for most users but if you find the server doesn't start or is not available, it's likely because npx is not found so you might have to adjust the above configuration accordingly.
 
   <br />
@@ -217,23 +245,21 @@ Add XcodeBuildMCP to your MCP client configuration. Most clients use JSON config
   }
   ```
 
-  > **NOTE**: 
+  > **NOTE**:
   > Claude Code Agent when running in Xcode has a limited PATH by default. The above example should work for most users but if you find the server doesn't start or is not available, it's likely because npx is not found so you might have to adjust the above configuration accordingly.
 
   <br />
 </details>
 
 <br />
 
-For other installation options see [Getting Started](docs/GETTING_STARTED.md)
-
-When configuring a client manually, ensure the command includes the `mcp` subcommand (for example, `npx -y xcodebuildmcp@latest mcp`).
+For other installation options see [Getting Started](docs/GETTING_STARTED.md).
 
 ## Requirements
 
 - macOS 14.5 or later
 - Xcode 16.x or later
-- Node.js 18.x or later
+- Node.js 18.x or later (not required for Homebrew installation)
 
 ## Skills
 

docs/GETTING_STARTED.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 - macOS 14.5 or later
 - Xcode 16.x or later
-- Node.js 18.x or later
+- Node.js 18.x or later (not required for Homebrew installation)
 
 ## Choose Your Interface
 
@@ -16,40 +16,50 @@ XcodeBuildMCP provides a unified CLI with two modes:
 
 Both share the same tools and configuration.
 
-## MCP Server Installation
+## Installation
 
-Most MCP clients use JSON configuration. Add the following server entry to your client's MCP config:
+Both methods give you the CLI and the MCP server.
 
+### Option A — Homebrew (no Node.js required)
+
+```bash
+brew tap cameroncooke/xcodebuildmcp
+brew install xcodebuildmcp
+```
+
+Use the CLI:
+```bash
+xcodebuildmcp --help
+```
+
+MCP client config:
 ```json
 "XcodeBuildMCP": {
-  "command": "npx",
-  "args": [
-    "-y",
-    "xcodebuildmcp@beta",
-    "mcp"
-  ]
+  "command": "xcodebuildmcp",
+  "args": ["mcp"]
 }
 ```
 
-## CLI Installation
-
-```bash
-# Install globally
-npm install -g xcodebuildmcp@beta
-
-# Verify installation
-xcodebuildmcp --version
+Upgrade later with `brew update && brew upgrade xcodebuildmcp`.
 
-# List available tools
-xcodebuildmcp tools
+### Option B — npm / npx (Node.js 18+)
 
-# View CLI help
+**For CLI use**, install globally:
+```bash
+npm install -g xcodebuildmcp@latest
 xcodebuildmcp --help
+```
 
-# View tool help
-xcodebuildmcp <workflow> <tool> --help
+**For MCP server only**, no global install needed — add directly to your client config:
+```json
+"XcodeBuildMCP": {
+  "command": "npx",
+  "args": ["-y", "xcodebuildmcp@latest", "mcp"]
+}
 ```
 
+Using `@latest` ensures clients resolve the newest version on each run.
+
 See [CLI.md](CLI.md) for full CLI documentation.
 
 ## Project config (optional)
@@ -63,6 +73,8 @@ See [CONFIGURATION.md](CONFIGURATION.md) for the full schema and examples.
 
 ## Client-specific configuration
 
+The examples below use npx (Option B). If you installed via Homebrew, replace the command with `"command": "xcodebuildmcp", "args": ["mcp"]` instead.
+
 ### Cursor
 Recommended (project-scoped): create `.cursor/mcp.json` in your project root:
 
@@ -71,7 +83,7 @@ Recommended (project-scoped): create `.cursor/mcp.json` in your project root:
   "mcpServers": {
     "XcodeBuildMCP": {
       "command": "npx",
-      "args": ["-y", "xcodebuildmcp@beta", "mcp"]
+      "args": ["-y", "xcodebuildmcp@latest", "mcp"]
     }
   }
 }
@@ -86,7 +98,7 @@ If you use a global Cursor config at `~/.cursor/mcp.json`, use this variant to a
       "command": "/bin/zsh",
       "args": [
         "-lc",
-        "cd \"${workspaceFolder}\" && exec npx -y xcodebuildmcp@beta mcp"
+        "cd \"${workspaceFolder}\" && exec npx -y xcodebuildmcp@latest mcp"
       ]
     }
   }
@@ -99,7 +111,7 @@ Codex uses TOML for MCP configuration. Add this to `~/.codex/config.toml`:
 ```toml
 [mcp_servers.XcodeBuildMCP]
 command = "npx"
-args = ["-y", "xcodebuildmcp@beta", "mcp"]
+args = ["-y", "xcodebuildmcp@latest", "mcp"]
 env = { "XCODEBUILDMCP_SENTRY_DISABLED" = "false" }
 ```
 
@@ -115,10 +127,10 @@ https://github.com/openai/codex/blob/main/docs/config.md#connecting-to-mcp-serve
 ### Claude Code CLI
 ```bash
 # Add XcodeBuildMCP server to Claude Code
-claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@beta mcp
+claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp
 
 # Or with environment variables
-claude mcp add XcodeBuildMCP -e XCODEBUILDMCP_SENTRY_DISABLED=false -- npx -y xcodebuildmcp@beta mcp
+claude mcp add XcodeBuildMCP -e XCODEBUILDMCP_SENTRY_DISABLED=false -- npx -y xcodebuildmcp@latest mcp
 ```
 
 Note: XcodeBuildMCP requests xcodebuild to skip macro validation to avoid Swift Macro build errors.

docs/dev/CONTRIBUTING.md

@@ -51,6 +51,22 @@ brew tap cameroncooke/axe
 brew install axe
 ```
 
+#### Optional: Using a Local AXe Checkout for Bundling
+
+`npm run bundle:axe` defaults to downloading pinned AXe release artifacts from GitHub.
+
+To bundle from a local AXe source checkout instead:
+
+```bash
+AXE_USE_LOCAL=1 AXE_LOCAL_DIR=/absolute/path/to/AXe npm run bundle:axe
+```
+
+Rules:
+- Local mode is enabled only when `AXE_USE_LOCAL=1`.
+- `AXE_LOCAL_DIR` must point to a valid AXe repository (must contain `Package.swift`).
+- If `AXE_USE_LOCAL=1` and `AXE_LOCAL_DIR` is missing/invalid, bundling fails fast.
+- `AXE_FORCE_REMOTE=1` overrides local mode and forces remote artifact download.
+
 ### Installation
 
 1. Clone the repository

docs/dev/RELEASE_PROCESS.md

@@ -14,9 +14,35 @@ If the latest changelog section is `## [Unreleased]` and no matching version hea
 Preview release notes locally:
 
 ```bash
-node scripts/generate-github-release-notes.mjs --version 2.0.0-beta.1
+node scripts/generate-github-release-notes.mjs --version 2.0.0
 ```
 
+## Release Workflow Modes
+
+The release workflow (`.github/workflows/release.yml`) has two execution modes:
+
+### Tag push (`push` on `v*`)
+
+Production release behavior:
+- Publishes package to npm.
+- Creates GitHub release and uploads npm tarball.
+- Builds and verifies portable macOS artifacts (`arm64`, `x64`, `universal`).
+- Uploads portable artifacts to GitHub release assets.
+- Updates the Homebrew tap repository (`cameroncooke/homebrew-xcodebuildmcp`) directly when `HOMEBREW_TAP_TOKEN` is configured.
+- Attempts Smithery and MCP Registry publishes (best effort based on configured secrets).
+
+### Manual dispatch (`workflow_dispatch`)
+
+Validation behavior only (no production deployment):
+- Runs formatting/build/tests and packaging checks.
+- Runs npm publish in `--dry-run` mode.
+- Builds and verifies portable artifacts for release-pipeline validation.
+- Does **not** publish to npm.
+- Does **not** create GitHub release.
+- Does **not** upload portable assets to a release.
+- Does **not** update Homebrew tap.
+- Does **not** run Smithery or MCP Registry publish jobs.
+
 ## Step-by-Step Development Workflow
 
 ### 1. Starting New Work

src/version.ts

@@ -1,3 +1,3 @@
-export const version = '2.0.0-beta.1';
+export const version = '2.0.0';
 export const iOSTemplateVersion = 'v1.0.8';
 export const macOSTemplateVersion = 'v1.0.5';