@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/ios-simulator/SKILL.md

@@ -1,487 +1,359 @@
 ---
 name: ios-simulator
-description: "Manages iOS Simulator devices and tests app behaviour with xcrun simctl: device lifecycle, app install and launch, push notification and location simulation, privacy permission grants, deep links via openurl, status bar overrides, screenshot and video capture, os_log streaming, app container paths, and targetEnvironment(simulator) checks. Use when managing simulator devices, testing push without APNs, simulating GPS, resetting permissions, capturing screens from the command line, streaming device logs, or debugging simulator boot and CoreSimulator failures."
+description: "xcrun simctl from the command line: create, boot, erase and delete devices, install and launch apps, simulated pushes without APNs, GPS locations and routes, granting or resetting privacy permissions, openurl deep links, status bar overrides, screenshots and video, os_log streaming, app containers, targetEnvironment(simulator), boot and CoreSimulator failures. Use when scripting simulators for tests or CI or deciding what needs real hardware. Not for Instruments profiling, real APNs setup, or push-server, Core Bluetooth or Core Motion code."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# iOS Simulator
+# iOS Simulator with simctl
 
-Manage iOS Simulator devices and test app behavior from the command line using `xcrun simctl`. Covers the full device lifecycle, app deployment, push and location simulation, permission control, screenshot and video recording, log streaming, and compile-time simulator detection.
+`xcrun simctl` controls simulators without the Simulator app's menus, which is
+what test scripts and CI need. This skill covers the device lifecycle, app
+installation, the simulation commands, capture, logs, the compile-time
+simulator check, and where the simulator stops being a stand-in for hardware.
 
-For common subcommands, syntax, and examples, see [references/simctl-commands.md](references/simctl-commands.md).
+Every subcommand, flag table, jq recipe and troubleshooting step is in
+`references/simctl-commands.md`.
 
-## Contents
+## Devices
 
-- [Device Lifecycle](#device-lifecycle)
-- [App Install and Launch](#app-install-and-launch)
-- [Testing Workflows](#testing-workflows)
-- [Screenshot and Video Recording](#screenshot-and-video-recording)
-- [Log Streaming](#log-streaming)
-- [Compile-Time Simulator Detection](#compile-time-simulator-detection)
-- [Simulator Limitations](#simulator-limitations)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Device Lifecycle
-
-### Listing Devices and Runtimes
+### What is installed
 
 ```bash
-# List all available simulators grouped by runtime
 xcrun simctl list devices available
-
-# List installed runtimes
 xcrun simctl list runtimes
-
-# List only booted devices
 xcrun simctl list devices booted
-
-# JSON output for scripting
-xcrun simctl list -j devices available
+xcrun simctl list devices available -j
 ```
 
-Parse JSON output to find a specific device programmatically. See [references/simctl-commands.md](references/simctl-commands.md) for `jq` parsing examples.
+The first groups usable devices by runtime, the second lists runtimes, the
+third shows only running devices, and `-j` switches to JSON for scripts
+(parse it with `jq`; recipes in the reference).
 
-### Creating a Device
+### Making a device
 
 ```bash
-# Find available device types and runtimes
 xcrun simctl list devicetypes
-xcrun simctl list runtimes
-
-# Create a device  -  returns the new UDID
-xcrun simctl create "My Test Phone" "iPhone 16 Pro" "com.apple.CoreSimulator.SimRuntime.iOS-18-4"
-```
-
-Device types and runtime identifiers in examples throughout this skill are illustrative. Run `simctl list devicetypes` and `simctl list runtimes` to find the identifiers available on your system.
-
-The returned UDID identifies the device for all subsequent commands. Use descriptive names to distinguish devices in `simctl list` output.
-
-### Boot, Shutdown, Erase, Delete
-
-```bash
-# Boot a specific device
-xcrun simctl boot <UDID>
-
-# Boot if needed and wait until the device is ready
-xcrun simctl bootstatus <UDID> -b
-
-# Shutdown a running device
-xcrun simctl shutdown <UDID>
-
-# Factory reset  -  wipes all data, keeps the device
-xcrun simctl erase <UDID>
-
-# Delete a specific device
-xcrun simctl delete <UDID>
-
-# Delete all devices not available in the current Xcode
-xcrun simctl delete unavailable
-
-# Shutdown everything
-xcrun simctl shutdown all
+SIM=$(xcrun simctl create "Checkout iPad" "iPad Air 11-inch (M3)" com.apple.CoreSimulator.SimRuntime.iOS-26-0)
+echo "$SIM"
 ```
 
-Use `booted` as a UDID shorthand when exactly one simulator is running:
-
-```bash
-xcrun simctl shutdown booted
-```
+`create` prints the new device's UDID; keep it and pass it to later commands.
+Device type and runtime strings above are examples only, so read the real
+ones from `list devicetypes` and `list runtimes` on the machine. A descriptive
+name makes devices easy to tell apart.
 
-If multiple simulators are booted, `booted` picks one of them non-deterministically. Prefer explicit UDIDs when running parallel simulators.
+### Boot, stop, wipe, remove
 
-In scripts and CI, use `xcrun simctl bootstatus <UDID> -b` before install, launch, push, or location commands. If you call `simctl boot` separately, follow it with `xcrun simctl bootstatus <UDID>` before continuing.
+| Command | Effect |
+|---|---|
+| `xcrun simctl boot "$SIM"` | Starts the device |
+| `xcrun simctl bootstatus "$SIM" -b` | Boots when necessary, then waits for boot to finish |
+| `xcrun simctl shutdown "$SIM"` / `shutdown all` | Stops one device / every device |
+| `xcrun simctl erase "$SIM"` | Factory reset: data gone, device kept |
+| `xcrun simctl delete "$SIM"` | Removes the device |
+| `xcrun simctl delete unavailable` | Removes devices the current Xcode cannot run |
 
-## App Install and Launch
+- If only one simulator is up, the word `booted` can stand in for its UDID.
+  With several running, which one `booted` means is not defined; parallel
+  jobs must use explicit UDIDs.
+- In scripts and CI, run `bootstatus "$SIM" -b` before installing, launching,
+  pushing or setting a location. If you call `boot` on its own, follow it
+  with `bootstatus "$SIM"`.
 
-### Installing an App
+## Installing and launching
 
 ```bash
-# Build for simulator first
-xcodebuild build \
-    -scheme MyApp \
-    -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
-    -derivedDataPath build/
-
-# Boot and wait for SpringBoard/services before install
-xcrun simctl bootstatus <UDID> -b
-
-# Install the .app bundle
-xcrun simctl install <UDID> build/Build/Products/Debug-iphonesimulator/MyApp.app
+xcodebuild build -scheme Pantry \
+  -destination "platform=iOS Simulator,id=$SIM" \
+  -derivedDataPath build/
+xcrun simctl bootstatus "$SIM" -b
+xcrun simctl install "$SIM" build/Build/Products/Debug-iphonesimulator/Pantry.app
 ```
 
-The path must point to a `.app` directory built for the simulator architecture, not a `.ipa` file.
-
-### Launching and Terminating
+`install` wants the simulator-built `.app` folder, never an `.ipa`.
 
 ```bash
-# Launch by bundle ID
-xcrun simctl launch booted com.example.MyApp
-
-# Launch and stream stdout/stderr to the terminal
-xcrun simctl launch --console booted com.example.MyApp
-
-# Pass launch arguments
-xcrun simctl launch booted com.example.MyApp --reset-onboarding -AppleLanguages "(fr)"
-
-# Terminate a running app
-xcrun simctl terminate booted com.example.MyApp
+xcrun simctl launch "$SIM" org.example.pantry
+xcrun simctl launch --console "$SIM" org.example.pantry
+xcrun simctl launch "$SIM" org.example.pantry -seedDemoData YES -AppleLanguages "(de)"
+xcrun simctl terminate "$SIM" org.example.pantry
 ```
 
-`--console` is useful for debugging  -  it shows `print()` and `os_log` output directly in the terminal.
+- `--console` keeps the command attached and prints the app's stdout and
+  stderr, so `print()` output and `os_log` messages appear in the terminal.
+- Anything after the bundle ID becomes a launch argument.
 
-### App Container Paths
+Containers, for looking at sandboxed files, databases or defaults while
+debugging:
 
 ```bash
-# App bundle location
-xcrun simctl get_app_container booted com.example.MyApp app
-
-# Data container (Documents, Library, tmp)
-xcrun simctl get_app_container booted com.example.MyApp data
-
-# Shared app group container
-xcrun simctl get_app_container booted com.example.MyApp group.com.example.shared
+xcrun simctl get_app_container "$SIM" org.example.pantry app
+xcrun simctl get_app_container "$SIM" org.example.pantry data
+xcrun simctl get_app_container "$SIM" org.example.pantry group.org.example.pantry
 ```
 
-Use these paths to inspect sandboxed files, databases, or UserDefaults during debugging.
+`app` is the bundle, `data` the data container (Documents, Library, tmp),
+and a group identifier returns that App Group's shared container.
 
-## Testing Workflows
+## Simulating the outside world
 
-### Push Notification Simulation
+### Push notifications
 
-Create a JSON payload file:
-
-```json
+```bash
+cat > restock.json <<'JSON'
 {
-    "aps": {
-        "alert": {
-            "title": "New Message",
-            "body": "You have a new message from Alice"
-        },
-        "badge": 3,
-        "sound": "default"
-    },
-    "customKey": "customValue"
+  "aps": {
+    "alert": { "title": "Back in stock", "body": "Oat milk is available again" },
+    "badge": 1,
+    "sound": "default"
+  },
+  "itemID": "oat-milk-1l"
 }
+JSON
+xcrun simctl push "$SIM" org.example.pantry restock.json
+echo '{"aps":{"alert":"Pickup ready"}}' | xcrun simctl push "$SIM" org.example.pantry -
 ```
 
-Send it to the Simulator:
-
-```bash
-# Send push payload from file
-xcrun simctl push booted com.example.MyApp payload.json
-
-# Pipe payload from stdin
-echo '{"aps":{"alert":"Quick test"}}' | xcrun simctl push booted com.example.MyApp -
-```
-
-This simulates local delivery only  -  no APNs connection is involved. Use this to test payload handling, notification display, and notification actions. Always verify on a real device before shipping to confirm APNs delivery works end to end.
+A file path or `-` (stdin) supplies the payload. Delivery is local: nothing
+talks to APNs. That makes it good for payload parsing, presentation and
+notification actions, and useless as proof that APNs delivery works; check
+that end to end on a device before shipping.
 
-### Location Simulation
+### Location
 
 ```bash
-# Set a fixed coordinate (latitude, longitude)
-xcrun simctl location booted set 37.3349,-122.0090
-
-# List available predefined scenarios
-xcrun simctl location booted list
-
-# Run a predefined scenario
-xcrun simctl location booted run "City Run"
-
-# Follow custom command-line waypoints
-xcrun simctl location booted start --speed=15 --interval=1 \
-    37.3349,-122.0090 37.3317,-122.0307
-
-# Read waypoints from stdin, one "lat,lon" pair per line
-printf "37.3349,-122.0090\n37.3317,-122.0307\n" | \
-    xcrun simctl location booted start --distance=100 -
-
-# Clear the simulated location
-xcrun simctl location booted clear
+xcrun simctl location "$SIM" set 52.3702,4.8952
+xcrun simctl location "$SIM" list
+xcrun simctl location "$SIM" run "Freeway Drive"
+xcrun simctl location "$SIM" start --speed=12 --interval=2 52.3702,4.8952 52.3791,4.9003
+printf '52.37,4.89\n52.38,4.90\n52.39,4.91\n' | xcrun simctl location "$SIM" start --distance=50 -
+xcrun simctl location "$SIM" clear
 ```
 
-Use `set` for one coordinate, `run` for predefined scenario names, and `start` for custom waypoint routes. The command boundary matters: `simctl location run` accepts built-in scenario names (e.g., "City Run", "Freeway Drive"), not GPX file paths; `simctl location start` is the command-line path for custom coordinate waypoints. Use Xcode's Debug > Simulate Location menu for GPX-based routes.
+- One fixed point: `set`. A scenario that ships with the simulator: `run`. Your own path: `start`
+  with waypoints, or `-` to read one `lat,lon` per line from stdin.
+- `run` takes scenario names such as "City Run" or "Freeway Drive", not GPX
+  files. GPX routes are loaded from the Xcode menu instead (Debug >
+  Simulate Location).
+- A simulated location applies to every Core Location client on that device.
+  `clear` it when the test ends so later tests are not surprised.
 
-Location simulation affects all apps using Core Location on the booted device. Clear the location when done to avoid unexpected test results.
-
-### Privacy Permissions
+### Privacy permissions
 
 ```bash
-# Grant a permission
-xcrun simctl privacy booted grant photos com.example.MyApp
-
-# Revoke a permission
-xcrun simctl privacy booted revoke microphone com.example.MyApp
-
-# Reset all permissions for the app
-xcrun simctl privacy booted reset all com.example.MyApp
+xcrun simctl privacy "$SIM" grant photos org.example.pantry
+xcrun simctl privacy "$SIM" revoke microphone org.example.pantry
+xcrun simctl privacy "$SIM" reset all org.example.pantry
 ```
 
-Common service names: `photos`, `microphone`, `contacts`, `calendar`, `reminders`, `location`, `location-always`, `motion`, `siri`. See [references/simctl-commands.md](references/simctl-commands.md) for the full list.
-
-Pre-granting permissions in CI avoids system permission dialogs that block automated test runs, but it can mask missing usage description keys. Keep the required Info.plist privacy strings in place and still test the normal prompt flow.
+Services you will use most: `location`, `location-always`, `photos`,
+`contacts`, `calendar`, `reminders`, `microphone`, `siri`, `motion` (the
+reference has them all). Granting up front keeps CI from stalling on system
+alerts, but it can also hide a missing usage-description key. Keep the
+Info.plist privacy strings and still test the real prompt path.
 
-### Deep Links and URLs
+### Deep links
 
 ```bash
-# Open a URL (triggers universal links or custom URL schemes)
-xcrun simctl openurl booted "https://example.com/product/123"
-
-# Custom URL scheme
-xcrun simctl openurl booted "myapp://settings/notifications"
+xcrun simctl openurl "$SIM" "https://pantry.example.org/list/42"
+xcrun simctl openurl "$SIM" "pantry://list/42"
 ```
 
-For universal links, the app's associated domains entitlement must be configured. The Simulator uses the `apple-app-site-association` file from the domain.
+An `https` URL exercises universal links, which need the associated domains
+entitlement; the simulator downloads the domain's
+`apple-app-site-association` file. A custom scheme opens the app directly.
 
-### Status Bar Overrides
+### Status bar
 
 ```bash
-# Set a clean status bar for screenshots
-xcrun simctl status_bar booted override \
-    --time "9:41" \
-    --batteryState charged \
-    --batteryLevel 100 \
-    --cellularMode active \
-    --cellularBars 4 \
-    --wifiBars 3 \
-    --operatorName ""
-
-# Clear all overrides
-xcrun simctl status_bar booted clear
+xcrun simctl status_bar "$SIM" override --operatorName '' --time "9:41" \
+  --wifiBars 3 --cellularBars 4 --cellularMode active --batteryLevel 100 --batteryState charged
+xcrun simctl status_bar "$SIM" clear
 ```
 
-Use status bar overrides to produce consistent App Store screenshots. Always clear overrides after capturing to avoid confusing other testing.
+Overrides give App Store screenshots a consistent status bar. Clear them once
+the captures are done.
 
-## Screenshot and Video Recording
+## Screenshots and video
 
 ```bash
-# Capture a screenshot
-xcrun simctl io booted screenshot screenshot.png
-
-# Record video (press Ctrl+C to stop)
-xcrun simctl io booted recordVideo recording.mov
-
-# Screenshot with specific display mask
-xcrun simctl io booted screenshot --mask black screenshot.png
+xcrun simctl io "$SIM" screenshot home.png
+xcrun simctl io "$SIM" screenshot --mask=alpha framed.png
+xcrun simctl io "$SIM" recordVideo --mask=black onboarding.mov
 ```
 
-`--mask` options: `ignored` (default, no mask), `alpha` (transparent corners), `black` (black corners). Use `alpha` or `black` when capturing screenshots that show the device shape. The `alpha` mask is only supported for screenshots  -  video recording falls back to `black`.
+- Masks: `ignored` (default, plain rectangle), `alpha` (transparent rounded
+  corners), `black` (black corners). Pick `alpha` or `black` to show the
+  device outline.
+- `alpha` works for screenshots only; video falls back to `black`.
+- Recording runs until SIGINT (Ctrl+C) and the file is written only after it
+  stops. A SIGKILL ends it with no file at all.
 
-Video recording continues until the process receives SIGINT (Ctrl+C). The recording is saved only after stopping  -  killing the process with SIGKILL loses the file.
-
-## Log Streaming
-
-### Basic Log Stream
+## Logs
 
 ```bash
-# Stream all logs at debug level and above
-xcrun simctl spawn booted log stream --level debug
-
-# Filter by subsystem
-xcrun simctl spawn booted log stream --level debug \
-    --predicate 'subsystem == "com.example.app"'
-
-# Filter by subsystem and category
-xcrun simctl spawn booted log stream --level debug \
-    --predicate 'subsystem == "com.example.app" AND category == "networking"'
-
-# Filter by process name
-xcrun simctl spawn booted log stream \
-    --predicate 'process == "MyApp"'
+xcrun simctl spawn "$SIM" log stream \
+  --predicate 'subsystem == "org.example.pantry" AND category == "sync"' --level debug
+xcrun simctl spawn "$SIM" log stream --predicate 'process == "Pantry"'
 ```
 
-### Combining with os.Logger
-
-Design subsystems and categories for filterability:
+`--level debug` shows debug messages and everything above them. Filter by
+subsystem, add a category, or filter by process name. Design the logging so
+these filters are useful:
 
 ```swift
+import Foundation
 import os
 
-let networkLogger = Logger(subsystem: "com.example.app", category: "networking")
-let uiLogger = Logger(subsystem: "com.example.app", category: "ui")
-
-func fetchData() async throws -> Data {
-    networkLogger.debug("Starting request to /api/data")
-    let (data, response) = try await URLSession.shared.data(from: url)
-    networkLogger.info("Received \(data.count) bytes, status: \((response as? HTTPURLResponse)?.statusCode ?? 0)")
-    return data
+enum Diagnostics {
+    static let sync = Logger(subsystem: "org.example.pantry", category: "sync")
+    static let screens = Logger(subsystem: "org.example.pantry", category: "screens")
 }
-```
-
-Then filter the log stream to see only networking output:
-
-```bash
-xcrun simctl spawn booted log stream --level debug \
-    --predicate 'subsystem == "com.example.app" AND category == "networking"'
-```
-
-## Compile-Time Simulator Detection
-
-Use `#if targetEnvironment(simulator)` to exclude code that cannot run in the Simulator:
 
-```swift
-func registerForPush() {
-    #if targetEnvironment(simulator)
-    logger.info("Skipping APNs registration  -  running in Simulator")
-    #else
-    UIApplication.shared.registerForRemoteNotifications()
-    #endif
+func refreshShoppingList(from endpoint: URL) async throws -> Data {
+    Diagnostics.screens.info("Refreshing shopping list")
+    let (body, response) = try await URLSession.shared.data(for: URLRequest(url: endpoint))
+    let status = (response as? HTTPURLResponse)?.statusCode ?? -1
+    Diagnostics.sync.debug("List payload \(body.count) bytes, HTTP \(status)")
+    return body
 }
 ```
 
-Runtime detection via environment variables:
+## Detecting the simulator in code
 
 ```swift
-var isSimulator: Bool {
-    ProcessInfo.processInfo.environment["SIMULATOR_DEVICE_NAME"] != nil
-}
-```
-
-Prefer compile-time checks (`#if targetEnvironment(simulator)`) over runtime checks. The compiler strips excluded code entirely, preventing linker errors from unavailable symbols.
-
-## Simulator Limitations
-
-When classifying a test as Simulator-supported or hardware-required, separate "can trigger this behavior" from "can validate real-device fidelity":
-
-- Simulator-supported triggers/proxies: local push with `simctl push`, location changes, memory warnings, Face ID or Touch ID enrollment/match/nonmatch menu actions, manual iCloud sync trigger, privacy grants/resets, status bar overrides, screenshots, and video capture.
-- Hardware-required validation: APNs delivery, BLE and NFC, real camera or microphone input, motion sensors, Secure Enclave, App Attest, automatic iCloud propagation/conflicts/background behavior, CPU throughput, general processing speed, networking throughput or latency, Metal shader correctness, GPU limits, memory bandwidth, frame timing, memory pressure, Jetsam, and thermal behavior.
-
-Do not classify "iCloud sync" as a single hardware-only item. Split it explicitly:
-
-- Simulator-supported: manual iCloud sync triggering and basic app response to sync callbacks.
-- Hardware-required: automatic iCloud propagation, multiple real devices/accounts, conflict resolution, notification-triggered sync, background delivery, and account/device state differences.
-
-| Capability | Simulator Support |
-|-----------|------------------|
-| APNs push delivery | No  -  use `simctl push` for local simulation |
-| Performance fidelity | Relative only  -  Simulator is not accurate for CPU/processing performance, networking speed, graphics/Metal, memory bandwidth, frame timing, memory pressure, Jetsam, shader correctness, or thermal behavior; verify performance-sensitive work on hardware |
-| Metal GPU family parity | Partial  -  Simulator uses the host Mac GPU, not the device GPU; some shaders and limits differ |
-| Camera hardware | No  -  use photo library injection or mock `AVCaptureSession` |
-| Audio input / microphone | No general app audio input; Siri can be activated from Simulator menus |
-| Secure Enclave | No  -  `kSecAttrTokenIDSecureEnclave` operations fail |
-| App Attest (DCAppAttestService) | No  -  `isSupported` returns `false` |
-| DockKit motor control | No  -  no physical accessory connection |
-| Accelerometer / Gyroscope | No motion sensor support; use real devices for motion-dependent behavior |
-| Barometer | No |
-| NFC (Core NFC) | No |
-| Bluetooth (Core Bluetooth) | No  -  use a real device for BLE testing |
-| CarPlay display simulation | Supported through Simulator's external display/CarPlay option; still verify in vehicle or device setups |
-| Face ID / Touch ID hardware | No hardware  -  use Features > Face ID / Touch ID menu in Simulator |
-| Memory warnings, manual iCloud sync trigger, location changes | Supported through Simulator menus or `simctl` where available |
-| Automatic iCloud sync behavior | Not fully simulated  -  validate notification-triggered sync, real account/device propagation, conflicts, and background behavior on hardware |
-| Cellular network conditions | No  -  use Network Link Conditioner on Mac |
-
-Treat Simulator performance as a functional smoke signal only. When answering performance-boundary questions, explicitly name CPU throughput/general processing speed and networking throughput/latency alongside graphics, Metal shader correctness, memory bandwidth, frame timing, memory pressure, Jetsam behavior, and thermal behavior.
-
-Use this minimum wording in release-checklist answers: "Simulator is not an accurate performance proxy for processing/CPU, graphics/Metal, memory, networking throughput/latency, Metal GPU behavior, frame timing, memory pressure/Jetsam, or thermal behavior." If a prompt only names "Metal performance," still include processing, memory, and networking in the device-verification list.
-
-## Common Mistakes
-
-### DON'T: Hardcode simulator UDIDs in scripts
-
-UDIDs change when simulators are deleted and recreated. Hardcoded values break on other machines and CI.
-
-```bash
-# WRONG  -  hardcoded UDID
-xcrun simctl boot "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
-
-# CORRECT  -  look up by name and runtime
-UDID=$(xcrun simctl list -j devices available | \
-    jq -r '.devices["com.apple.CoreSimulator.SimRuntime.iOS-18-4"][] | select(.name == "iPhone 16 Pro") | .udid')
-xcrun simctl boot "$UDID"
-
-# CORRECT  -  use "booted" when one simulator is running
-xcrun simctl install booted MyApp.app
-```
-
-### DON'T: Install or launch on a shutdown simulator
-
-`simctl install` and `simctl launch` require a booted device. They fail silently or with an unhelpful error on a shutdown device.
-
-```bash
-# WRONG  -  device is not booted
-xcrun simctl install <UDID> MyApp.app  # fails
-
-# CORRECT  -  boot first, then install
-xcrun simctl boot <UDID>
-xcrun simctl install <UDID> MyApp.app
-xcrun simctl launch <UDID> com.example.MyApp
-```
-
-### DON'T: Leave zombie simulators running in CI
-
-Each booted simulator consumes memory and CPU. CI pipelines that create simulators without cleanup accumulate zombie devices.
+import UIKit
+import os
 
-```bash
-# WRONG  -  CI script creates and boots but never cleans up
-xcrun simctl create "CI Phone" "iPhone 16 Pro" "com.apple.CoreSimulator.SimRuntime.iOS-18-4"
-xcrun simctl boot "$UDID"
-# ... tests run, pipeline exits ...
-
-# CORRECT  -  always clean up in CI teardown
-cleanup() {
-    xcrun simctl shutdown all
-    xcrun simctl delete "$UDID"
+@MainActor
+func enableRemotePush() {
+    #if !targetEnvironment(simulator)
+    UIApplication.shared.registerForRemoteNotifications()
+    #else
+    Logger(subsystem: "org.example.pantry", category: "push").info("Remote push registration skipped in Simulator")
+    #endif
 }
-trap cleanup EXIT
-```
-
-### DON'T: Assume simctl push validates APNs delivery
-
-`simctl push` bypasses the entire APNs infrastructure. It tests payload parsing and notification UI, not token registration, entitlements, or server-side delivery.
-
-```bash
-# WRONG  -  only testing with simctl, shipping without real device testing
-xcrun simctl push booted com.example.MyApp payload.json
-# "Push works!"  -  no, it only proves the app handles the payload
-
-# CORRECT  -  use simctl for development iteration, then verify end-to-end on a real device
-# 1. simctl push during development for fast iteration
-# 2. Real device + APNs sandbox for integration testing before release
 ```
 
-### DON'T: Keep retrying boot on a stuck simulator
-
-A simulator stuck in the "Booting" state will not recover by retrying `boot`. The underlying CoreSimulator state is corrupted.
-
-```bash
-# WRONG  -  retry loop on a stuck device
-xcrun simctl boot "$UDID"  # "Unable to boot device in current state: Booting"
-xcrun simctl boot "$UDID"  # same error, forever
-
-# CORRECT  -  shut down, erase, and retry
-xcrun simctl shutdown "$UDID"
-xcrun simctl erase "$UDID"
-xcrun simctl boot "$UDID"
-
-# If that fails, reset CoreSimulator entirely
-xcrun simctl shutdown all
-xcrun simctl erase all
-# Last resort: rm -rf ~/Library/Developer/CoreSimulator/Caches
-```
-
-## Review Checklist
-
-- [ ] Simulator devices created with explicit device type and runtime identifiers
-- [ ] Scripts use `booted` or parsed UDID from JSON output, not hardcoded values
-- [ ] Push notification payloads tested via `simctl push` during development
-- [ ] Push notification delivery verified on a real device before release
-- [ ] Location simulation tested with fixed coordinates, predefined scenarios, and custom waypoints when needed
-- [ ] Privacy permissions pre-granted in CI to avoid blocking dialogs
-- [ ] `#if targetEnvironment(simulator)` guards around APIs unavailable in Simulator
-- [ ] Status bar overrides cleared after capturing screenshots
-- [ ] CI pipelines shut down and delete simulators in teardown
-- [ ] Log streaming configured with subsystem/category predicates for focused debugging
-- [ ] App container paths used for inspecting sandboxed data during debugging
+At run time, `ProcessInfo.processInfo.environment["SIMULATOR_DEVICE_NAME"] != nil`
+also tells you, but prefer the compile-time check: the excluded code is not
+compiled at all, so symbols that do not exist for the simulator cannot cause
+link errors.
+
+## Where the simulator ends
+
+Sort each test by two questions: can the simulator *trigger* the behavior, and
+does the test need *real-device fidelity*?
+
+The simulator can trigger or approximate: screenshots and video, status bar
+overrides, granting and resetting permissions, memory warnings, a new
+location, a push delivered locally with `simctl push`, a hand-started iCloud
+sync, and biometric enrollment with matching or failing faces and fingers
+from the Features menu.
+
+Real hardware is required to validate: delivery through APNs; NFC and
+Bluetooth LE; live camera and microphone input; motion sensors; App Attest
+and the Secure Enclave; iCloud changes that propagate on their own, their
+conflicts and their background delivery; processing speed and CPU
+throughput; how fast and how slow the network really is; whether Metal
+shaders render correctly and what the GPU allows; memory bandwidth; frame
+pacing; memory pressure and Jetsam; heat.
+
+iCloud is not one item. Triggering a sync by hand and checking that the app
+reacts are simulator work. Automatic propagation, several devices or
+accounts, conflict resolution, sync started by a push, background delivery,
+and differences in account or device state need hardware.
+
+| Capability | In Simulator | Notes |
+|---|---|---|
+| APNs push delivery | No | Local `simctl push` only |
+| Performance | Relative only | Says nothing reliable about CPU, networking, Metal or graphics, shader correctness, memory bandwidth or pressure, frame pacing, Jetsam or heat; measure on devices |
+| Metal GPU family parity | Partial | The Mac's GPU does the work, so limits and some shader behavior differ |
+| Camera | No | Add photos to the library or mock `AVCaptureSession` |
+| Microphone / audio input | No general app input | Siri can be triggered from the Simulator menus |
+| Secure Enclave | No | Operations using `kSecAttrTokenIDSecureEnclave` fail |
+| App Attest | No | `DCAppAttestService.shared.isSupported` is `false` |
+| DockKit motor control | No | Accessories cannot connect |
+| Accelerometer, gyroscope, barometer | No | |
+| Core Bluetooth | No | BLE testing needs a device |
+| Core NFC | No | |
+| CarPlay display | Yes | Offered with the external display options; confirm in an actual car or head unit too |
+| Face ID / Touch ID | No sensor | Enrollment and match results are simulated from the Features menu |
+| Memory warnings, manual iCloud sync, location changes | Yes | Menus or `simctl` |
+| Automatic iCloud sync | Not fully | Validate on hardware |
+| Cellular conditions | No | Shape traffic with the Mac's Network Link Conditioner |
+
+Numbers from the simulator only show that something works at all. Whenever a
+question touches performance limits, the answer lists every area that needs a
+device: processing and CPU, network speed and latency, graphics, whether Metal
+shaders are correct, memory bandwidth, frame pacing, memory pressure and
+Jetsam, and heat.
+
+A release checklist always carries this sentence, word for word:
+
+> Simulator timings do not predict device timings, so before release we
+> measure on real hardware: CPU and processing, graphics and Metal, Metal GPU
+> behavior, memory, memory pressure and Jetsam, frame pacing, network speed
+> and latency, and thermal behavior.
+
+Even a question about Metal alone gets processing, memory and networking in
+that device list.
+
+## Common mistakes
+
+1. **Hard-coded UDIDs.** They change whenever a device is deleted and
+   recreated and never match on another Mac or CI runner. Look the UDID up:
+
+   ```bash
+   SIM=$(xcrun simctl list devices available --json |
+     jq -r --arg rt "com.apple.CoreSimulator.SimRuntime.iOS-26-0" \
+       '.devices[$rt][] | select(.name == "Checkout iPad") | .udid')
+   ```
+
+   or use `booted` when exactly one simulator runs.
+2. **Installing or launching on a stopped device.** These fail silently or
+   with unhelpful errors. Boot, then install, then launch.
+3. **Simulators left running in CI.** They keep eating memory and CPU. Clean
+   up on every exit path:
+
+   ```bash
+   teardown() {
+     xcrun simctl shutdown "$SIM"
+     xcrun simctl delete "$SIM"
+     xcrun simctl shutdown all
+   }
+   trap teardown EXIT
+   ```
+
+4. **Taking `simctl push` as APNs proof.** It never touches APNs, so it says
+   nothing about token registration, entitlements or server delivery. Iterate
+   with it, then confirm on a device against the APNs sandbox before release.
+5. **Calling `boot` again on a stuck device.** When boot reports that the
+   device is already in the Booting state and never finishes, CoreSimulator's
+   state is damaged. Shut the
+   device down, erase it and boot again; if that fails, `shutdown all` plus
+   `erase all`; as a last resort delete the cache folder
+   (`~/Library/Developer/CoreSimulator/Caches`).
+
+## Review checklist
+
+- [ ] `create` calls pass explicit device-type and runtime identifiers
+- [ ] No literal UDIDs in scripts; `booted` or a JSON lookup instead
+- [ ] Push payloads exercised with `simctl push` during development
+- [ ] Push delivery confirmed on a physical device before release
+- [ ] Location covered with fixed points, built-in scenarios and custom waypoints as needed
+- [ ] CI grants privacy permissions up front
+- [ ] `#if targetEnvironment(simulator)` guards APIs the simulator lacks
+- [ ] Status bar overrides cleared after screenshots
+- [ ] CI teardown shuts down and deletes its simulators
+- [ ] Log streams filter by subsystem and category
+- [ ] App container paths used to inspect sandbox data
 
 ## References
 
-- [Running your app in Simulator or on a device](https://sosumi.ai/documentation/xcode/running-your-app-in-simulator-or-on-a-device)
-- [Downloading and installing additional Xcode components](https://sosumi.ai/documentation/xcode/installing-additional-simulator-runtimes)
-- [Testing in Simulator versus testing on hardware devices](https://sosumi.ai/documentation/xcode/testing-in-simulator-versus-testing-on-hardware-devices)
-- [Testing complex hardware device scenarios in Simulator](https://sosumi.ai/documentation/xcode/testing-complex-hardware-device-scenarios-in-simulator)
-- [Simulating an external display or CarPlay](https://sosumi.ai/documentation/xcode/simulating-an-external-display-or-carplay)
-- simctl command reference: [references/simctl-commands.md](references/simctl-commands.md)
+- `references/simctl-commands.md`
+- Running on simulated or physical devices: https://developer.apple.com/documentation/xcode/running-your-app-on-simulated-or-physical-devices
+- Downloading simulator runtimes and other components: https://developer.apple.com/documentation/xcode/downloading-and-installing-additional-xcode-components
+- Configuring a simulated device's environment: https://developer.apple.com/documentation/xcode/configuring-the-environment-of-a-simulated-device
+- Device Hub (managing simulated and physical devices): https://developer.apple.com/documentation/xcode/device-hub