refactor(11/12): update manifests, config, docs, and example projects (#329)

This is **PR 11 of 12** in a stacked PR series that decouples the rendering pipeline from MCP transport. Depends on PR 10 (boundary rewiring).

Updates all configuration files, YAML manifests, documentation, and example projects to reflect the rendering pipeline refactor. No behavioral code changes -- this is metadata, documentation, and project configuration.

All tool manifests updated to reflect the simplified handler contract. Changes are consistent across all manifests:
- Removed output format configuration that is now handled by the render session
- Updated parameter descriptions where they referenced the old rendering model

Added `manifests/resources/` directory with resource manifest definitions that were previously inline.

- `package.json` + `package-lock.json`: Dependency updates and script changes
- `knip.json`: Dead code analysis configuration for the new module structure
- `vitest.config.ts`: Minor updates for new test paths
- `vitest.flowdeck.config.ts` + `vitest.snapshot.config.ts`: New vitest configs for flowdeck integration tests and snapshot tests respectively

New developer documentation explaining the rendering pipeline architecture:
- `RENDERING_PIPELINE.md`: Architecture overview for contributors
- `RENDERING_PIPELINE_REFACTOR.md`: Migration guide and decision log
- `QUERY_TOOL_FORMAT_SPEC.md`: Specification for query tool output formatting
- `FIXTURE_DESIGNS.md`: Snapshot test fixture design documentation
- `STRUCTURED_XCODEBUILD_EVENTS_PLAN.md`: Design document for the xcodebuild event model
- Updated `ARCHITECTURE.md`, `TESTING.md`, `MANIFEST_FORMAT.md`, `TOOL_DISCOVERY_LOGIC.md`

Minor updates to example projects to work with the updated tool interfaces. Updated test files and project configuration.

- `AGENTS.md`: Updated project rules
- New test infrastructure: `test-helpers.ts`, `vitest-executor-safety.setup.ts`
- Build scripts updated: removed `copy-build-assets.js` (no longer needed), added benchmark and capture wrapper scripts

- PR 1-10/12: All code changes
- **PR 11/12** (this PR): Manifests, config, docs, examples
- PR 12/12: Snapshot test fixtures and benchmarks

- [ ] `npx vitest run` passes
- [ ] Manifest validation passes for all YAML files
- [ ] Documentation renders correctly in GitHub
- [ ] Example projects build successfully

Author: cameroncooke

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))`

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

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*

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*

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**