docs: expand xcodebuildmcp usage

docs/ai/ios-xcodebuildmcp.md

@@ -3,37 +3,70 @@
 This page focuses on MCP-based Xcode workflows and the XcodeBuildMCP setup.
 
 ## What XcodeBuildMCP Is (Plain Language)
-+XcodeBuildMCP can run build and test tasks without you switching into Xcode for every step. This reduces context switching and makes workflows repeatable.
-+
-+Think of it as a remote control for Xcode build actions. Instead of clicking around in Xcode, you ask the assistant to run the action and report the result.
-+
-+Common uses include:
+XcodeBuildMCP can run build and test tasks without you switching into Xcode for every step. This reduces context switching and makes workflows repeatable.
+
+Think of it as a remote control for Xcode build actions. Instead of clicking around in Xcode, you ask the assistant to run the action and report the result.
+
+Common uses include:
 +- Run a build for a target or scheme
 +- Run tests and return failures
 +- Capture build output so the assistant can summarize errors
-+
-+### Example Requests
+
+### Example Requests
 +- "Use XcodeBuildMCP to build the app and summarize any errors."
 +- "Run tests with XcodeBuildMCP and list the failing tests."
 +- "Build with XcodeBuildMCP and extract the first error message."
-+
-+## Xcode 26.3 MCP Setup (Detailed)
-+These steps reflect a common setup as of February 2026. Wording may vary slightly in release candidates.
-+
-+### Prerequisites
+
+## What It Can Do (Detailed Examples)
+Below are common tasks and how to ask for them. Adjust the wording to match your project.
+
+### Build
+Goal: Run a build and get a short error summary.
+
+Example:
+"Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets."
+
+### Unit Tests
+Goal: Run unit tests and list failures.
+
+Example:
+"Run unit tests with XcodeBuildMCP and list failing tests with file names."
+
+### UI Tests
+Goal: Run UI tests on a known simulator.
+
+Example:
+"Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures."
+
+### Screenshots (UI Testing)
+Goal: Trigger a UI test that captures screenshots and then list the generated images.
+
+Example:
+"Run the UI test that captures screenshots and list the output paths."
+
+### Build Output Parsing
+Goal: Extract the first error for quick diagnosis.
+
+Example:
+"Build with XcodeBuildMCP and extract the first error message only."
+
+## Xcode 26.3 MCP Setup (Detailed)
+These steps reflect a common setup as of February 2026. Wording may vary slightly in release candidates.
+
+### Prerequisites
 +- Xcode 26.3 (RC or full release), opened at least once with your project
 +- VS Code installed (stable or Insiders)
 +- GitHub Copilot extension installed and signed in
 +- Node.js and npm installed (for XcodeBuildMCP)
-+
-+### Step 1: Enable Xcode MCP Server
+
+### Step 1: Enable Xcode MCP Server
 +1. Open Xcode.
 +2. Go to Settings.
 +3. Open the Intelligence tab.
 +4. Find the Model Context Protocol section.
 +5. Toggle on Xcode Tools (or Allow external connections).
-+
-+### Step 2: Install And Configure XcodeBuildMCP (Recommended Bridge)
+
+### Step 2: Install And Configure XcodeBuildMCP (Recommended Bridge)
 +Install:
 +
 +```bash
@@ -54,8 +87,8 @@ This page focuses on MCP-based Xcode workflows and the XcodeBuildMCP setup.
 +```
 +
 +Restart VS Code or reload the window. Copilot should discover the tools.
-+
-+### Step 3: Optional Native Xcode MCP Bridge
+
+### Step 3: Optional Native Xcode MCP Bridge
 +Xcode 26.3 includes a native MCP bridge. This exposes Xcode tools directly.
 +
 +Add to VS Code:
@@ -78,32 +111,47 @@ This page focuses on MCP-based Xcode workflows and the XcodeBuildMCP setup.
 +
 +Example:
 +"Use XcodeBuildMCP to build and summarize errors. Then suggest fixes."
-+
-+### Tips And Caveats
+
+### Tips And Caveats
 +- Xcode must be running (or launchable) for MCP tools to respond.
 +- Native Xcode MCP is often best for previews.
 +- XcodeBuildMCP is often best for heavy builds and automation.
-+
-+### Install And Setup (Official)
+
+## Standardize The Simulator (Avoid Back-And-Forth)
+Pin a simulator name and OS version in your project guidance so the assistant always uses the same target.
+
+### Example Agent Guidance
+Add this to your Agents.md (or project instructions):
+
+```text
+When running iOS builds or tests, always use XcodeBuildMCP with the iOS simulator "iPhone 17 Pro Max" on iOS 26.2. Do not choose other simulators unless instructed.
+```
+
+### Why This Helps
+- Removes ambiguity about which simulator to use
+- Avoids repeated clarifying questions
+- Keeps build outputs consistent across developers
+
+### Install And Setup (Official)
 +Follow the official instructions: https://github.com/getsentry/XcodeBuildMCP
-+
-+### References
+
+### References
 +- https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-agentic-coding/
 +- https://github.com/cameroncooke/XcodeBuildMCP
 +- https://github.com/getsentry/XcodeBuildMCP
 +- https://code.visualstudio.com/docs/copilot/customization/mcp-servers
-+
-+## Xcode 26.3 And MCP Integration
+
+## Xcode 26.3 And MCP Integration
 +Apple announced that Xcode 26.3 exposes Xcode capabilities through the Model Context Protocol (MCP), which enables compatible agents and tools to interact with Xcode features directly.
-+
-+### What This Means (Plain Language)
+
+### What This Means (Plain Language)
 +- Xcode can be controlled by MCP-enabled tools.
 +- Agents can access more of Xcode's capabilities without you manually clicking through the UI.
-+
-+### Example Workflow
+
+### Example Workflow
 +1. You ask an agent to build the project.
 +2. The agent uses MCP to run the build inside Xcode.
 +3. The agent summarizes errors and suggests fixes.
-+
-+### Source
+
+### Source
 +https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-agentic-coding/