feat(setup): platform-aware wizard with manifest-driven workflow recommendations (#365)

* Add platform-aware setup wizard and mcp-json output

Introduce platform selection to the setup wizard, recommend workflows
per platform, and avoid prompting for a simulator when macOS is the only
platform selected. Add helpers and constants (SetupPlatform,
PLATFORM_WORKFLOWS, PLATFORM_OPTIONS, infer/derive/filter helpers), a
multi-select platform prompt, and make the setup flow platform-aware
(seed workflow defaults, filter simulators, preserve platform in
sessionDefaults). Add selectionToMcpConfigJson() and a --format mcp-json
option to print a ready-to-paste MCP client config JSON block
(runSetupWizard supports 'mcp-json' early-exit). Update tests
(createPlatformPrompter and four platform-aware cases) and CHANGELOG.md
to document the new behavior.

* test(setup): expand platform-aware setup wizard coverage

Add focused tests requested by the PR audit:
- Stale deviceId, simulatorId, and simulatorName are cleared when
  re-running setup with macOS-only after a prior iOS-with-device config.
- YAML persistence for tvOS, watchOS, and visionOS single-platform
  selections writes the correct platform string and selects a
  platform-matching simulator from a multi-runtime simctl listing.
- Verify filterSimulatorsByPlatforms matches a SimRuntime-style
  visionOS runtime via the xrOS keyword.

* refactor(cli/setup): consolidate platform string mappings

Replace three parallel string-literal cascades for SetupPlatform <-> session-defaults
platform conversion with two derived lookup tables, reusing the existing XcodePlatform
enum so the session-defaults platform value has a single source of truth.

Replace the inline visionOS/xrOS branch in filterSimulatorsByPlatforms with a
SIMULATOR_RUNTIME_KEYWORDS table so runtime keyword matching is data-driven.

* refactor(setup): derive workflow recommendations from manifest metadata

Add `targetPlatforms` to the workflow manifest schema and populate it on
all built-in workflows. The setup wizard now derives recommended
workflows from this manifest metadata instead of a hand-coded
`PLATFORM_WORKFLOWS` map, and splits the prompt into recommended vs
additional workflows so the default selection stays minimal (macos
and/or simulator) while non-recommended workflows remain reachable.

Custom workflows from `config.yaml` and the workflow-discovery entry
declare empty `targetPlatforms`; tests for schema, exposure, registry,
and the setup wizard cover required/empty/invalid metadata and the new
recommended/additional prompt flow.

* feat(device): support tvOS, watchOS, and visionOS device builds

Extract a shared `devicePlatformSchema` and reuse `mapDevicePlatform`
across `build_device`, `build_run_device`, `get_device_app_path`, and
`test_device` so each device tool accepts a `platform` argument and
threads it into the xcodebuild invocation and log prefix.

The schema preprocesses simulator-flavored session defaults
(e.g. `tvOS Simulator`) down to the matching device platform so a
session configured for a simulator runtime still produces a valid
device build target. Tests cover the new platform argument, the
simulator-to-device normalization, and the rejected `macOS` case.

* docs(agents): scope review focus to branch regressions

Add a guidance line to AGENTS.md and CLAUDE.md telling reviewers to
focus on behavior changes caused by the current branch and to ignore
known test flakes, environment setup issues, and nondeterministic tool
output churn unless explicitly asked to investigate them.

* ci: remove tool authoring guidance workflow

The reminder workflow posted a PR comment when tool contract files
changed, but org-level GITHUB_TOKEN policy blocks the comment write
and the check stays failing without surfacing useful information on
the PR. Authoring guidance is maintained in the docs site at
xcodebuildmcp.com/docs/tool-authoring.

* refactor(setup): persist wizard platform selection in setupPreferences

The setup wizard was writing the user's "which platforms does this
project target?" answer into sessionDefaults.platform, conflating UI
memory with a runtime tool-param default. It also relied on
sessionDefaults.simulatorPlatform (an internal cache) to recover the
non-macOS half of multi-platform selections, which silently reverted
[macOS, visionOS] to [macOS, iOS] on re-run.

Move wizard memory to a dedicated top-level setupPreferences.platforms
field. sessionDefaults.platform/simulatorPlatform are no longer touched
by setup; they remain agent-controlled session defaults. The mcp-json
output still seeds XCODEBUILDMCP_PLATFORM for fresh clients, since that
is an explicit env-var bootstrap, not internal state.

Follow-up #366 tracks moving simulatorPlatform out of sessionDefaults.

* refactor(setup): remove unused SESSION_DEFAULT_TO_SETUP_PLATFORM

The reverse mapping had a single consumer in the legacy
inferPlatformsFromExisting branch. After 82d3101 moved wizard memory
to setupPreferences.platforms, that lookup is gone and the constant is
dead. CodeQL flagged it.

---------

Co-authored-by: Ismar Iljazovic <ismar@gmail.com>

Author: Cameron Cooke

.github/workflows/tool-authoring-guidance.yml

@@ -61,6 +61,7 @@ Use these sections under `## [Unreleased]`:
   - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.
   - Capture what you find before killing, so the root cause can be fixed rather than papered over.
 - If physical-device snapshot tests hang after the final test summary, the likely cause is Apple post-failure diagnostics invoking `devicectl diagnose`, which may prompt for a macOS password and wedge in automated runs.
+- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.
 
 ## **CRITICAL** Tool Usage Rules **CRITICAL**
 - NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.

AGENTS.md

@@ -5,6 +5,13 @@
 ### Added
 
 - Added `xcodebuildmcp upgrade` command to check for updates and upgrade in place. Supports `--check` (report-only) and `--yes`/`-y` (skip confirmation). Detects install method (Homebrew, npm-global, npx) and queries the appropriate channel source (`brew info`, `npm view`, or GitHub Releases) for the latest version. Non-interactive environments exit 1 when an auto-upgrade is possible but `--yes` was not supplied.
+- Added platform selection step to the `xcodebuildmcp setup` wizard. You now choose which platforms you are developing for (macOS, iOS, tvOS, watchOS, visionOS) before selecting workflows. Based on the selection, the wizard automatically recommends the appropriate workflow set ([#281](https://github.com/getsentry/XcodeBuildMCP/pull/281) by [@detailobsessed](https://github.com/detailobsessed)).
+
+### Changed
+
+- The `setup` wizard no longer prompts for a simulator or device when macOS is the only selected platform — macOS apps run natively and do not require a simulator or physical device ([#281](https://github.com/getsentry/XcodeBuildMCP/pull/281) by [@detailobsessed](https://github.com/detailobsessed)).
+- When a single platform is selected, `xcodebuildmcp setup` now writes `platform` to `sessionDefaults` in `config.yaml` and includes `XCODEBUILDMCP_PLATFORM` in `--format mcp-json` output. For multi-platform projects the platform key is omitted so the agent can choose per-command ([#281](https://github.com/getsentry/XcodeBuildMCP/pull/281) by [@detailobsessed](https://github.com/detailobsessed)).
+- The `setup` wizard remembers previous choices on re-run: existing `config.yaml` values (including the new `platform`) are pre-loaded as defaults for every prompt ([#281](https://github.com/getsentry/XcodeBuildMCP/pull/281) by [@detailobsessed](https://github.com/detailobsessed)).
 
 ## [2.3.2]
 

CHANGELOG.md

@@ -60,6 +60,7 @@ Use these sections under `## [Unreleased]`:
   - Do NOT just kill the run — first inspect the process tree (`ps -ef | grep -E "vitest|xcodebuild|simctl|devicectl"`) to identify what's stuck.
   - Common hang causes: locked physical device, stale simulator state, `devicectl diagnose` waiting for password, orphaned daemon process.
   - Capture what you find before killing, so the root cause can be fixed rather than papered over.
+- When asked to review changes or test failures, focus on regressions: behavior changes caused by the branch. Do not treat known/acceptable test flakes, environment setup issues, or nondeterministic tool output churn as regressions unless explicitly asked to investigate them.
 
 ## **CRITICAL** Tool Usage Rules **CRITICAL**
 - NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.

CLAUDE.md

@@ -1,6 +1,7 @@
 id: coverage
 title: Code Coverage
 description: View code coverage data from xcresult bundles produced by test runs.
+targetPlatforms: [iOS, macOS, tvOS, watchOS, visionOS]
 tools:
   - get_coverage_report
   - get_file_coverage

manifests/workflows/coverage.yaml

@@ -1,6 +1,7 @@
 id: debugging
 title: LLDB Debugging
 description: Attach LLDB debugger to simulator apps, set breakpoints, inspect variables and call stacks.
+targetPlatforms: [iOS, tvOS, watchOS, visionOS]
 tools:
   - debug_attach_sim
   - debug_breakpoint_add

manifests/workflows/debugging.yaml

@@ -1,6 +1,7 @@
 id: device
-title: iOS Device Development
-description: Complete iOS development workflow for physical devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro).
+title: Device Development
+description: Complete development workflow for physical devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro).
+targetPlatforms: [iOS, tvOS, watchOS, visionOS]
 tools:
   - build_device
   - build_run_device

manifests/workflows/device.yaml

@@ -1,6 +1,7 @@
 id: doctor
 title: MCP Doctor
 description: Diagnostic tool providing comprehensive information about the MCP server environment, dependencies, and configuration.
+targetPlatforms: []
 selection:
   mcp:
     autoInclude: true

manifests/workflows/doctor.yaml

@@ -1,6 +1,7 @@
 id: macos
 title: macOS Development
 description: Complete macOS development workflow for both .xcodeproj and .xcworkspace files. Build, test, deploy, and manage macOS applications.
+targetPlatforms: [macOS]
 tools:
   - build_macos
   - build_run_macos

manifests/workflows/macos.yaml

@@ -1,6 +1,7 @@
 id: project-discovery
 title: Project Discovery
 description: Discover and examine Xcode projects, workspaces, and Swift packages. Analyze project structure, schemes, build settings, and bundle information.
+targetPlatforms: [iOS, macOS, tvOS, watchOS, visionOS]
 tools:
   - discover_projs
   - list_schemes