getsentry · cameroncooke · Apr 10, 2026 · Apr 8, 2026 · Apr 9, 2026 · Apr 9, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -46,6 +46,7 @@ Use these sections under `## [Unreleased]`:
 - Append to existing subsections (e.g., `### Fixed`), do not create duplicates
 - NEVER modify already-released version sections (e.g., `## [0.12.2]`)
 - Each version section is immutable once released
+- NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture
 -
 #### Attribution
 - **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/cameroncook/XcodeBuildMCP/issues/123))`

diff --git a/docs/CLI.md b/docs/CLI.md
@@ -77,6 +77,34 @@ xcodebuildmcp simulator launch-app --simulator-id <UDID> --bundle-id io.sentry.M
 xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj
 ```
 
+### Human-readable build-and-run output
+
+For xcodebuild-backed build-and-run tools:
+
+- CLI text mode prints a durable preflight block first
+- interactive terminals then show active phases as live replace-in-place updates
+- warnings, errors, failures, summaries, and next steps are durable output
+- success output order is: front matter -> runtime state/diagnostics -> summary -> execution-derived footer -> next steps
+- failed structured xcodebuild runs do not render next steps
+- compiler/build diagnostics should be grouped into a readable failure block before the failed summary
+- the final footer should only contain execution-derived values such as app path, bundle ID, app ID, or process ID
+- requested values like scheme, project/workspace, configuration, and platform stay in front matter and should not be repeated later
+- when the tool computes a concrete value during execution, prefer showing it directly in the footer instead of relegating it to a hint or redundant next step
+
+For example, a successful build-and-run footer should prefer:
+
+```text
+✅ Build & Run complete
+
+  └ App Path: /tmp/.../MyApp.app
+```
+
+rather than forcing the user to run another command just to retrieve a value the tool already knows.
+
+MCP uses the same human-readable formatting semantics, but buffers the rendered output instead of streaming it to stdout live. It is the same section model and ordering, just a different sink.
+
+`--output json` is still streamed JSONL events, not the human-readable section format.
+
 ### Testing
 
 ```bash
@@ -85,8 +113,15 @@ xcodebuildmcp simulator test --scheme MyAppTests --project-path ./MyApp.xcodepro
 
 # Run with specific simulator
 xcodebuildmcp simulator test --scheme MyAppTests --simulator-name "iPhone 17 Pro"
+
+# Run with pre-resolved test discovery and live progress
+xcodebuildmcp simulator test --json '{"workspacePath":"./MyApp.xcworkspace","scheme":"MyApp","simulatorName":"iPhone 17 Pro","progress":true,"extraArgs":["-only-testing:MyAppTests"]}'
 ```
 
+Simulator test output now pre-resolves concrete Swift XCTest and Swift Testing cases when it can, then streams filtered milestones for package resolution, compilation, and test execution plus a grouped failure summary instead of raw `xcodebuild` noise.
+
+For reproducible performance comparisons against Flowdeck CLI, see [dev/simulator-test-benchmark.md](dev/simulator-test-benchmark.md).
+
 For a full list of workflows and tools, see [TOOLS-CLI.md](TOOLS-CLI.md).
 
 ## Configuration

diff --git a/docs/TOOLS-CLI.md b/docs/TOOLS-CLI.md
@@ -2,7 +2,7 @@
 
 This document lists CLI tool names as exposed by `xcodebuildmcp <workflow> <tool>`.
 
-XcodeBuildMCP provides 76 canonical tools organized into 14 workflow groups.
+XcodeBuildMCP provides 71 canonical tools organized into 13 workflow groups.
 
 ## Workflow Groups
 
@@ -22,10 +22,10 @@ XcodeBuildMCP provides 76 canonical tools organized into 14 workflow groups.
 
 
 ### iOS Device Development (`device`)
-**Purpose**: Complete iOS development workflow for physical devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro). (17 tools)
+**Purpose**: Complete iOS development workflow for physical devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro). (15 tools)
 
 - `build` - Build for device.
-- `build-and-run` - Build, install, and launch on physical device. Preferred single-step run tool when defaults are set.
+- `build-and-run` - Build, install, and launch on physical device. Runtime logs are captured automatically and the log file path is included in the response. Preferred single-step run tool when defaults are set.
 - `clean` - Clean build products.
 - `discover-projects` - Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files. Use when project/workspace path is unknown.
 - `get-app-bundle-id` - Extract bundle id from .app.
@@ -37,38 +37,33 @@ XcodeBuildMCP provides 76 canonical tools organized into 14 workflow groups.
 - `list` - List connected devices.
 - `list-schemes` - List Xcode schemes.
 - `show-build-settings` - Show build settings.
-- `start-device-log-capture` - Start device log capture.
 - `stop` - Stop device app.
-- `stop-device-log-capture` - Stop device app and return logs.
 - `test` - Test on device.
 
 
 
 ### iOS Simulator Development (`simulator`)
-**Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. (23 tools)
+**Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. (20 tools)
 
 - `boot` - Defined in Simulator Management workflow.
 - `build` - Build for iOS sim (compile-only, no launch).
-- `build-and-run` - Build, install, and launch on iOS Simulator; boots simulator and attempts to open Simulator.app as needed. Preferred single-step run tool when defaults are set.
+- `build-and-run` - Build, install, and launch on iOS Simulator; boots simulator and attempts to open Simulator.app as needed. Runtime logs are captured automatically and the log file path is included in the response. Preferred single-step run tool when defaults are set.
 - `clean` - Defined in iOS Device Development workflow.
 - `discover-projects` - Defined in iOS Device Development workflow.
 - `get-app-bundle-id` - Defined in iOS Device Development workflow.
 - `get-app-path` - Get sim built app path.
 - `get-coverage-report` - Defined in Code Coverage workflow.
 - `get-file-coverage` - Defined in Code Coverage workflow.
 - `install` - Install app on sim.
-- `launch-app` - Launch app on simulator.
-- `launch-app-with-logs` - Launch sim app with logs.
+- `launch-app` - Launch app on simulator. Runtime logs are captured automatically and the log file path is included in the response.
 - `list` - Defined in Simulator Management workflow.
 - `list-schemes` - Defined in iOS Device Development workflow.
 - `open` - Defined in Simulator Management workflow.
 - `record-video` - Record sim video.
 - `screenshot` - Capture screenshot.
 - `show-build-settings` - Defined in iOS Device Development workflow.
 - `snapshot-ui` - Print view hierarchy with precise view coordinates (x, y, width, height) for visible elements.
-- `start-simulator-log-capture` - Defined in Log Capture workflow.
 - `stop` - Stop sim app.
-- `stop-simulator-log-capture` - Defined in Log Capture workflow.
 - `test` - Test on iOS sim.
 
 
@@ -87,16 +82,6 @@ XcodeBuildMCP provides 76 canonical tools organized into 14 workflow groups.
 
 
 
-### Log Capture (`logging`)
-**Purpose**: Capture and retrieve logs from simulator and device apps. (4 tools)
-
-- `start-device-log-capture` - Defined in iOS Device Development workflow.
-- `start-simulator-log-capture` - Start sim log capture.
-- `stop-device-log-capture` - Defined in iOS Device Development workflow.
-- `stop-simulator-log-capture` - Stop sim app and return logs.
-
-
-
 ### macOS Development (`macos`)
 **Purpose**: Complete macOS development workflow for both .xcodeproj and .xcworkspace files. Build, test, deploy, and manage macOS applications. (13 tools)
 
@@ -200,10 +185,10 @@ XcodeBuildMCP provides 76 canonical tools organized into 14 workflow groups.
 
 ## Summary Statistics
 
-- **Canonical Tools**: 76
-- **Total Tools**: 108
-- **Workflow Groups**: 14
+- **Canonical Tools**: 71
+- **Total Tools**: 99
+- **Workflow Groups**: 13
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-03-16T20:47:13.697Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-04-07T11:23:03.868Z UTC*
diff --git a/docs/TOOLS.md b/docs/TOOLS.md
@@ -1,6 +1,6 @@
 # XcodeBuildMCP MCP Tools Reference
 
-This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP provides 82 canonical tools organized into 16 workflow groups for comprehensive Apple development workflows.
+This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP provides 77 canonical tools organized into 15 workflow groups for comprehensive Apple development workflows.
 
 ## Workflow Groups
 
@@ -20,10 +20,10 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 
 ### iOS Device Development (`device`)
-**Purpose**: Complete iOS development workflow for physical devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro). (17 tools)
+**Purpose**: Complete iOS development workflow for physical devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro). (15 tools)
 
 - `build_device` - Build for device.
-- `build_run_device` - Build, install, and launch on physical device. Preferred single-step run tool when defaults are set.
+- `build_run_device` - Build, install, and launch on physical device. Runtime logs are captured automatically and the log file path is included in the response. Preferred single-step run tool when defaults are set.
 - `clean` - Clean build products.
 - `discover_projs` - Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files. Use when project/workspace path is unknown.
 - `get_app_bundle_id` - Extract bundle id from .app.
@@ -35,18 +35,16 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 - `list_devices` - List connected devices.
 - `list_schemes` - List Xcode schemes.
 - `show_build_settings` - Show build settings.
-- `start_device_log_cap` - Start device log capture.
 - `stop_app_device` - Stop device app.
-- `stop_device_log_cap` - Stop device app and return logs.
 - `test_device` - Test on device.
 
 
 
 ### iOS Simulator Development (`simulator`)
-**Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. (23 tools)
+**Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. (20 tools)
 
 - `boot_sim` - Defined in Simulator Management workflow.
-- `build_run_sim` - Build, install, and launch on iOS Simulator; boots simulator and attempts to open Simulator.app as needed. Preferred single-step run tool when defaults are set.
+- `build_run_sim` - Build, install, and launch on iOS Simulator; boots simulator and attempts to open Simulator.app as needed. Runtime logs are captured automatically and the log file path is included in the response. Preferred single-step run tool when defaults are set.
 - `build_sim` - Build for iOS sim (compile-only, no launch).
 - `clean` - Defined in iOS Device Development workflow.
 - `discover_projs` - Defined in iOS Device Development workflow.
@@ -55,18 +53,15 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 - `get_file_coverage` - Defined in Code Coverage workflow.
 - `get_sim_app_path` - Get sim built app path.
 - `install_app_sim` - Install app on sim.
-- `launch_app_logs_sim` - Launch sim app with logs.
-- `launch_app_sim` - Launch app on simulator.
+- `launch_app_sim` - Launch app on simulator. Runtime logs are captured automatically and the log file path is included in the response.
 - `list_schemes` - Defined in iOS Device Development workflow.
 - `list_sims` - Defined in Simulator Management workflow.
 - `open_sim` - Defined in Simulator Management workflow.
 - `record_sim_video` - Record sim video.
 - `screenshot` - Capture screenshot.
 - `show_build_settings` - Defined in iOS Device Development workflow.
 - `snapshot_ui` - Print view hierarchy with precise view coordinates (x, y, width, height) for visible elements.
-- `start_sim_log_cap` - Defined in Log Capture workflow.
 - `stop_app_sim` - Stop sim app.
-- `stop_sim_log_cap` - Defined in Log Capture workflow.
 - `test_sim` - Test on iOS sim.
 
 
@@ -85,16 +80,6 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 
 
-### Log Capture (`logging`)
-**Purpose**: Capture and retrieve logs from simulator and device apps. (4 tools)
-
-- `start_device_log_cap` - Defined in iOS Device Development workflow.
-- `start_sim_log_cap` - Start sim log capture.
-- `stop_device_log_cap` - Defined in iOS Device Development workflow.
-- `stop_sim_log_cap` - Stop sim app and return logs.
-
-
-
 ### macOS Development (`macos`)
 **Purpose**: Complete macOS development workflow for both .xcodeproj and .xcworkspace files. Build, test, deploy, and manage macOS applications. (13 tools)
 
@@ -216,10 +201,10 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 ## Summary Statistics
 
-- **Canonical Tools**: 82
-- **Total Tools**: 114
-- **Workflow Groups**: 16
+- **Canonical Tools**: 77
+- **Total Tools**: 105
+- **Workflow Groups**: 15
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-03-16T20:47:13.697Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-04-07T11:23:03.868Z UTC*
diff --git a/docs/dev/ARCHITECTURE.md b/docs/dev/ARCHITECTURE.md
@@ -38,20 +38,20 @@ XcodeBuildMCP is a Model Context Protocol (MCP) server that exposes Xcode operat
    - MCP server created with stdio transport
    - Plugin discovery system initialized
 
-3. **Plugin Discovery (Build-Time)**
-   - A build-time script (`build-plugins/plugin-discovery.ts`) scans the `src/mcp/tools/` and `src/mcp/resources/` directories
-   - It generates `src/core/generated-plugins.ts` and `src/core/generated-resources.ts` with dynamic import maps
-   - This approach improves startup performance by avoiding synchronous file system scans and enables code-splitting
-   - Tool code is only loaded when needed, reducing initial memory footprint
-
-4. **Plugin & Resource Loading (Runtime)**
-   - At runtime, `loadPlugins()` and `loadResources()` use the generated loaders from the previous step
-   - All workflow loaders are executed at startup to register tools
-- If `XCODEBUILDMCP_ENABLED_WORKFLOWS` is set, only those workflows (plus `session-management`) are registered; `workflow-discovery` is only auto-included when `XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY=true`
-
-5. **Tool Registration**
-   - Discovered tools automatically registered with server using pre-generated maps
-   - No manual registration or configuration required
+3. **Manifest-Driven Discovery**
+   - YAML manifests in `manifests/tools/`, `manifests/workflows/`, and `manifests/resources/` define all metadata
+   - `loadManifest()` reads and validates all YAML files at startup against Zod schemas
+   - Tool and resource code modules are dynamically imported on demand
+
+4. **Tool & Resource Loading (Runtime)**
+   - `registerWorkflowsFromManifest()` selects workflows based on config and predicate context, then dynamically imports tool modules
+   - `registerResources()` loads resource manifests, filters by predicates, and dynamically imports resource modules
+   - Both systems share the same `PredicateContext` for visibility filtering
+   - If `XCODEBUILDMCP_ENABLED_WORKFLOWS` is set, only those workflows (plus `session-management`) are registered; `workflow-discovery` is only auto-included when `XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY=true`
+
+5. **Tool & Resource Registration**
+   - Tools are registered via `server.registerTool()` after manifest-driven workflow selection
+   - Resources are registered via `server.resource()` after manifest-driven predicate filtering
    - Environment variables control workflow selection behavior
 
 5. **Request Handling**