@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/ios-simulator/evals/evals.json

@@ -3,41 +3,41 @@
   "evals": [
     {
       "id": 1,
-      "prompt": "I need a command-line iOS Simulator test script for a maps feature. It should create or pick a simulator, boot it, install a simulator-built app, drive a custom route between two coordinates without using a GPX file, and clean up afterward. What simctl commands and caveats should I use?",
-      "expected_output": "A simctl-focused workflow that uses available device/runtime lookup, boots a simulator, installs a .app built for the simulator, uses simctl location start for custom command-line waypoints, clears location state, and shuts down or deletes test devices during cleanup.",
+      "prompt": "Write a shell script for CI that builds our map app, runs it on a fresh simulator, and drives it along a custom walking route I define as coordinates (I don't have a GPX file). Tidy up afterwards.",
+      "expected_output": "Creates or looks up a device without hard-coding a UDID, boots and waits before installing the simulator .app, uses location start with waypoints, and clears location and removes the device in cleanup.",
       "files": [],
       "assertions": [
-        "Uses `xcrun simctl location <device> start` for custom command-line waypoint routes instead of claiming only predefined scenarios are possible.",
-        "Explains that `location run` accepts predefined scenario names and does not take GPX file paths.",
-        "Boots before install or launch and installs a simulator-built `.app` rather than an `.ipa`.",
-        "Uses explicit UDID lookup or `booted` appropriately instead of hardcoding a simulator UDID.",
-        "Clears simulated location and shuts down or deletes simulator devices during cleanup."
+        "Drives the route with `xcrun simctl location <device> start` and lat,lon waypoints (or stdin), not with run",
+        "Points out that `location run` only takes the names of scenarios that ship with the simulator, so a GPX path will not work there",
+        "Boots and waits (bootstatus -b) before install and launch, and installs the .app produced for the simulator, not an .ipa",
+        "Obtains the UDID from create output, a JSON lookup, or uses booted with a single simulator, instead of a literal UDID",
+        "Clears the simulated location and shuts down and deletes the simulator in a cleanup step, for example a trap on EXIT"
       ]
     },
     {
       "id": 2,
-      "prompt": "Review this Simulator launch plan: pass FEATURE_FLAG=1 by running `xcrun simctl spawn booted env FEATURE_FLAG=1 /path/MyApp.app/MyApp`, use `simctl push` to prove APNs works for all notification types, and grant every privacy service in CI so we can remove usage description keys.",
-      "expected_output": "A correction-focused review that uses SIMCTL_CHILD_ environment variables with simctl launch, limits simctl push to local application remote notification simulation, preserves real-device APNs testing, and warns that simctl privacy can mask missing Info.plist usage descriptions.",
+      "prompt": "Please review this test script. It starts our app via `xcrun simctl spawn booted env FEATURE_FLAG=1 /path/to/App`, treats a successful `xcrun simctl push` as proof that APNs works, and calls `privacy grant all` so that NSCameraUsageDescription and NSPhotoLibraryUsageDescription can be deleted from Info.plist. What would you change?",
+      "expected_output": "Replaces spawn with launch plus SIMCTL_CHILD_ variables, explains that simctl push is local and limited, lists payload rules, and keeps usage-description keys and real prompt testing.",
       "files": [],
       "assertions": [
-        "Replaces the `spawn env` app launch pattern with `SIMCTL_CHILD_FEATURE_FLAG=1 xcrun simctl launch ...` or equivalent `SIMCTL_CHILD_` guidance.",
-        "Clarifies that `simctl spawn` is for arbitrary simulator processes, not the preferred path for launching an installed app with environment variables.",
-        "States that `simctl push` simulates local application remote push delivery only and does not prove APNs token registration, entitlements, server delivery, or unsupported push types.",
-        "Includes the `simctl push` payload constraints: top-level object, valid `aps`, and 4096-byte size limit.",
-        "Warns that `simctl privacy` does not remove the need for valid Info.plist usage description keys and normal prompt-flow testing."
+        "Recommends `SIMCTL_CHILD_FEATURE_FLAG=1 xcrun simctl launch <device> <bundle-id>` to pass the variable to the app",
+        "Explains that spawn exists for running arbitrary executables (log stream, for example) and is the wrong tool for starting an installed app",
+        "States that simctl push delivers locally and proves nothing about device token registration, entitlements or server delivery, and supports only application remote pushes (not VoIP, complication or File Provider)",
+        "Gives the payload constraints: the root must be a JSON object, it must include a well-formed aps dictionary, and it may not exceed 4096 bytes",
+        "Keeps the usage-description keys, because granting permissions from the command line does not replace them, and keeps testing the real system prompt"
       ]
     },
     {
       "id": 3,
-      "prompt": "We are deciding which tests can stay in iOS Simulator for a release candidate: camera capture, BLE pairing, barometer elevation, accelerometer controls, Face ID fallback, memory warnings, iCloud sync, push notifications, and Metal performance. Give the boundary and what must move to hardware.",
-      "expected_output": "A Simulator-versus-device boundary review grounded in Apple docs: hardware-only features move to real devices, simulated scenarios stay in Simulator where supported, and performance or APNs conclusions are verified on hardware.",
+      "prompt": "Release-candidate test plan: which of these belong on the Simulator and which need a physical device? Capturing photos with the camera, pairing our BLE scale, altitude from the barometer, step counting from the accelerometer, the passcode fallback after Face ID fails, reacting to memory warnings, iCloud syncing, push notification delivery, and how fast our Metal renderer runs.",
+      "expected_output": "Assigns hardware-only checks to devices, keeps triggerable behaviors in the simulator, treats iCloud and push as split items, and states that simulator performance is not representative across processing, graphics, memory and networking.",
       "files": [],
       "assertions": [
-        "Routes camera, Bluetooth/BLE, barometer, and accelerometer/gyroscope-dependent behavior to real hardware testing.",
-        "Treats Face ID/Touch ID fallback, memory warnings, and manual iCloud sync trigger as Simulator-supported scenarios.",
-        "States that Simulator is not an accurate performance proxy for processing, graphics, memory, networking, or Metal GPU behavior.",
-        "States that real APNs delivery must be verified on a device and `simctl push` is only local payload/display handling.",
-        "Keeps the answer focused on iOS Simulator boundaries instead of turning it into an Instruments, Core Motion, Core Bluetooth, or push server implementation guide."
+        "Puts camera capture, BLE pairing, barometer and accelerometer/gyroscope checks on physical devices",
+        "Keeps the passcode fallback after a biometric failure, memory-warning handling and a hand-triggered iCloud sync on the simulator, and sends automatic iCloud propagation and conflicts to devices",
+        "Says simulator numbers do not stand in for device processing, graphics, memory, networking or Metal GPU performance, and schedules those measurements on hardware",
+        "Assigns APNs delivery to a physical device and describes simctl push as local-only",
+        "Keeps to where the simulator ends and hardware begins, without drifting into guides for Instruments, Core Motion, Core Bluetooth or a push server"
       ]
     }
   ]

package/pipeline/skills/shared/external/ios-simulator/references/simctl-commands.md

@@ -1,316 +1,223 @@
-# simctl Command Reference
-
-Common `xcrun simctl` subcommands with syntax, flags, and examples. For workflows and patterns, see the main [SKILL.md](../SKILL.md).
-
-## Contents
-
-- [Device Management Commands](#device-management-commands)
-- [App Lifecycle Commands](#app-lifecycle-commands)
-- [Testing and Simulation Commands](#testing-and-simulation-commands)
-- [Media and IO Commands](#media-and-io-commands)
-- [JSON Output Parsing](#json-output-parsing)
-- [Privacy Service Names](#privacy-service-names)
-- [Status Bar Override Flags](#status-bar-override-flags)
-- [Troubleshooting](#troubleshooting)
-
-## Device Management Commands
-
-| Command | Synopsis | Notes |
-|---------|----------|-------|
-| `list` | `simctl list [devices\|devicetypes\|runtimes\|pairs] [search-term]` | Add `-j` for JSON. Add `available` to filter to usable devices. |
-| `create` | `simctl create <name> <device-type-id> [<runtime-id>]` | Returns the new UDID. Omitting runtime selects the newest compatible one. |
-| `clone` | `simctl clone <UDID> <new-name>` | Copies device state including installed apps. |
-| `delete` | `simctl delete <UDID\|unavailable\|all>` | `unavailable` removes devices whose runtime is missing. |
-| `rename` | `simctl rename <UDID> <new-name>` | |
-| `erase` | `simctl erase <UDID\|all>` | Factory reset  -  wipes apps and data, keeps the device. |
-| `boot` | `simctl boot <UDID>` | Starts the device runtime. |
-| `bootstatus` | `simctl bootstatus <UDID> [-b]` | Waits until the device finishes booting. Use `-b` in scripts to boot if needed and block until ready. |
-| `shutdown` | `simctl shutdown <UDID\|all>` | Stops the device runtime. |
-| `upgrade` | `simctl upgrade <UDID> <runtime-id>` | Upgrades device to a newer runtime. |
-| `pair` | `simctl pair <watch-UDID> <phone-UDID>` | Pairs a watchOS simulator with an iOS simulator. |
-| `unpair` | `simctl unpair <pair-UDID>` | Removes a watch/phone pairing. |
-
-### Device Type and Runtime IDs
+# simctl command reference
+
+Lookup tables for `xcrun simctl`. Workflows and the simulator-versus-hardware
+boundary are in [the main skill](../SKILL.md). `<dev>` below means a UDID, or
+`booted` when exactly one simulator is running. `xcrun simctl help <command>`
+prints the authoritative usage for the installed Xcode.
+
+## Devices
+
+| Command | What it does |
+|---|---|
+| `list [devices\|devicetypes\|runtimes\|pairs] [term\|available]` | Lists items; `-j` or `--json` for JSON; the `available` term hides unusable ones |
+| `create <name> <device-type-id> [<runtime-id>]` | Makes a device and prints its UDID; without a runtime, the newest compatible one is used |
+| `clone <dev> <new-name>` | Copies a device, installed apps and all |
+| `delete <dev>\|unavailable\|all` | Removes devices; `unavailable` means devices the current Xcode SDK cannot run (for example, a missing runtime) |
+| `rename <dev> <new-name>` | Renames |
+| `erase <dev>\|all` | Wipes content and settings, keeps the device |
+| `boot <dev>` | Starts the device's runtime |
+| `bootstatus <dev> [-b]` | Waits until boot completes; `-b` starts the boot first if needed |
+| `shutdown <dev>\|all` | Stops devices |
+| `upgrade <dev> <runtime-id>` | Moves a device to a newer runtime |
+| `pair <watch-dev> <phone-dev>` / `unpair <pair-id>` | Links a watchOS simulator to an iOS one, or removes the link |
+
+Identifiers look like `com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro`
+for device types and `com.apple.CoreSimulator.SimRuntime.iOS-26-0` for
+runtimes. `create` and `upgrade` take these identifier strings; read the
+exact values from `list devicetypes` and `list runtimes`.
+
+## Apps
+
+| Command | What it does |
+|---|---|
+| `install <dev> <path-to.app>` | Installs a simulator build; the device must be booted and the path is an `.app` folder, not an `.ipa` |
+| `uninstall <dev> <bundle-id>` | Removes the app and its data |
+| `launch [--console\|--console-pty] [--terminate-running-process] [--stdout=<file>] [--stderr=<file>] <dev> <bundle-id> [args...]` | Starts the app; `--terminate-running-process` stops a running copy first |
+| `terminate <dev> <bundle-id>` | Stops the running app |
+| `spawn <dev> <binary> [args...]` | Runs any executable inside the simulator, which is how `log stream` runs |
+| `get_app_container <dev> <bundle-id> [app\|data\|groups\|<group-id>]` | Prints a container path; `groups` lists every App Group container |
+| `appinfo <dev> <bundle-id>` | Prints information from the app's Info.plist |
+
+In scripts, prefer `bootstatus <dev> -b` followed by `install`. If a script
+calls `boot` by itself, add `bootstatus <dev>` before any install, launch,
+push or location command.
+
+### Arguments and environment
+
+- Extra words after the bundle ID reach the app as `CommandLine.arguments`.
+- Force a language and region for one run:
+  `xcrun simctl launch "$SIM" org.example.pantry -AppleLanguages "(ko)" -AppleLocale "ko_KR"`.
+- Environment variables for the launched app are taken from the calling
+  shell with a `SIMCTL_CHILD_` prefix, which simctl strips:
 
 ```bash
-# List all device types  -  use the identifier column
-xcrun simctl list devicetypes
-
-# Example output line:
-# iPhone 16 Pro (com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro)
-
-# List all runtimes
-xcrun simctl list runtimes
-
-# Example output line:
-# iOS 18.4 - com.apple.CoreSimulator.SimRuntime.iOS-18-4
+SIMCTL_CHILD_API_STAGE=beta SIMCTL_CHILD_VERBOSE_SYNC=1 xcrun simctl launch "$SIM" org.example.pantry
 ```
 
-Use the identifier strings (e.g., `com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro`) in `create` and `upgrade` commands.
-
-## App Lifecycle Commands
+`spawn` is for arbitrary processes such as `log stream`; it is not the way to
+start an installed app with custom environment variables.
 
-| Command | Synopsis | Notes |
-|---------|----------|-------|
-| `install` | `simctl install <UDID> <path-to-.app>` | Device must be booted. Path is a `.app` directory, not `.ipa`. |
-| `uninstall` | `simctl uninstall <UDID> <bundle-id>` | Removes app and its data. |
-| `launch` | `simctl launch [--console] [--terminate-running-process] <UDID> <bundle-id> [args...]` | `--console` streams stdout/stderr. `--terminate-running-process` kills existing instance first. |
-| `terminate` | `simctl terminate <UDID> <bundle-id>` | Sends SIGTERM to the running app. |
-| `spawn` | `simctl spawn <UDID> <path-to-binary> [args...]` | Runs an arbitrary binary inside the simulator. Used for `log stream`. |
-| `get_app_container` | `simctl get_app_container <UDID> <bundle-id> [app\|data\|groups\|<group-id>]` | Returns the filesystem path to the container. `groups` lists all App Group containers. |
-| `appinfo` | `simctl appinfo <UDID> <bundle-id>` | Prints Info.plist-derived information as JSON. |
-
-For scripts that boot a simulator before installing, prefer:
-
-```bash
-xcrun simctl bootstatus <UDID> -b
-xcrun simctl install <UDID> build/Build/Products/Debug-iphonesimulator/MyApp.app
-```
-
-`bootstatus -b` safely boots if needed and waits until the simulator finishes booting. If you call `simctl boot` separately, follow it with `xcrun simctl bootstatus <UDID>` before `install`, `launch`, `push`, or `location`.
-
-### Launch Arguments and Environment
-
-```bash
-# Pass launch arguments (received as CommandLine.arguments)
-xcrun simctl launch booted com.example.MyApp --reset-onboarding --debug-mode
-
-# Override language and locale
-xcrun simctl launch booted com.example.MyApp -AppleLanguages "(ja)" -AppleLocale "ja_JP"
-
-# Set environment variables for the launched app
-SIMCTL_CHILD_MY_VAR=value xcrun simctl launch booted com.example.MyApp
-```
+## Simulation
 
-Use the `SIMCTL_CHILD_` prefix for environment variables passed to `simctl launch`. Use `simctl spawn` for arbitrary processes inside the simulator, such as `log stream`, not as the default way to launch an installed app with environment.
+| Command | What it does |
+|---|---|
+| `push <dev> [<bundle-id>] <payload.json\|->` | Delivers a local remote-notification payload; the bundle ID may be omitted when the payload names it in `Simulator Target Bundle` (an explicit argument wins) |
+| `openurl <dev> <url>` | Opens a URL as if tapped |
+| `location <dev> set\|clear\|list\|run\|start [...]` | Simulated location |
+| `privacy <dev> grant\|revoke\|reset <service> [<bundle-id>]` | Permission state; some changes terminate the running app |
+| `keychain <dev> add-root-cert\|add-cert\|reset [path]` | Adds a trusted root or other certificate, or resets the keychain |
+| `status_bar <dev> override\|clear\|list [flags]` | Status bar overrides |
 
-## Testing and Simulation Commands
+## Push payloads
 
-| Command | Synopsis | Notes |
-|---------|----------|-------|
-| `push` | `simctl push <UDID> [<bundle-id>] <payload.json\|->` | Simulates local push delivery. Use `-` for stdin. Bundle ID is optional when the payload contains `Simulator Target Bundle`. |
-| `openurl` | `simctl openurl <UDID> <URL>` | Triggers universal links or custom URL schemes. |
-| `location` | `simctl location <UDID> <set\|clear\|list\|run\|start> [args]` | `set <lat,lon>`, `run <scenario>`, `list`, `start`, or `clear`. |
-| `privacy` | `simctl privacy <UDID> <grant\|revoke\|reset> <service> <bundle-id>` | See [Privacy Service Names](#privacy-service-names) for service values. |
-| `keychain` | `simctl keychain <UDID> <add-root-cert\|add-cert\|reset> [cert-path]` | Manages trusted certificates in the simulator keychain. |
-| `status_bar` | `simctl status_bar <UDID> <override\|clear> [flags]` | See [Status Bar Override Flags](#status-bar-override-flags). |
-
-### Push Payload Format
-
-The JSON payload mirrors the APNs payload format. The `Simulator Target Bundle` key is optional  -  when provided, the bundle ID argument can be omitted:
+The payload follows the APNs format:
 
 ```json
 {
-    "Simulator Target Bundle": "com.example.MyApp",
-    "aps": {
-        "alert": {
-            "title": "Order Update",
-            "subtitle": "Order #1234",
-            "body": "Your order has been shipped"
-        },
-        "badge": 1,
-        "sound": "default",
-        "category": "ORDER_STATUS",
-        "thread-id": "order-1234",
-        "interruption-level": "time-sensitive"
+  "Simulator Target Bundle": "org.example.pantry",
+  "aps": {
+    "alert": {
+      "title": "Delivery window changed",
+      "subtitle": "Order 1182",
+      "body": "Your groceries now arrive between 6 and 7 pm."
     },
-    "orderID": "1234"
+    "badge": 2,
+    "sound": "default",
+    "category": "DELIVERY_UPDATE",
+    "thread-id": "order-1182",
+    "interruption-level": "time-sensitive"
+  },
+  "orderID": "1182"
 }
 ```
 
-The payload must be a top-level JSON object, include a valid `aps` dictionary, and be 4096 bytes or less. `simctl push` supports only application remote push notifications; it does not support VoIP, Complication, File Provider, or other push types.
-
-### Location Scenarios
-
-The `run` subcommand accepts predefined scenario names, not GPX file paths:
-
-```bash
-# 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 -
-
-# Set a fixed coordinate
-xcrun simctl location booted set 37.3349,-122.0090
-
-# Clear the simulated location
-xcrun simctl location booted clear
-```
-
-Available scenarios include "City Run", "City Bicycle Ride", "Freeway Drive", and "Apple" (stationary at Apple Park). Use `list` to see all options on your system.
-
-Use `start` for command-line waypoint routes. It accepts at least two latitude/longitude pairs, optional speed, and either distance- or interval-based update cadence. The command boundary matters: `simctl location run` accepts built-in scenario names, not GPX file paths; for custom routes already stored as GPX files, use Xcode's Debug > Simulate Location menu instead.
+simctl checks three things: the top level is a JSON object, it contains a
+valid `aps` dictionary, and the whole payload is 4096 bytes or less. Only
+ordinary application remote notifications are supported; VoIP, complication,
+File Provider and other push types are rejected.
 
-## Media and IO Commands
+## Location
 
-| Command | Synopsis | Notes |
-|---------|----------|-------|
-| `io screenshot` | `simctl io <UDID> screenshot [--type png\|jpeg\|tiff\|bmp\|gif] [--mask ignored\|alpha\|black] <path>` | Default type is png. |
-| `io recordVideo` | `simctl io <UDID> recordVideo [--codec h264\|hevc] [--mask ignored\|alpha\|black] [--force] <path>` | Ctrl+C to stop. `--force` overwrites existing files. |
-| `addmedia` | `simctl addmedia <UDID> <path> [path...]` | Adds photos, live photos, videos, or contacts to the device. Supports PNG, JPEG, GIF, MOV, MP4, and vCard. |
+- Built-in scenarios include "Freeway Drive", "City Run", "City Bicycle Ride"
+  and "Apple" (a fixed point at the company campus); `list` prints what the
+  local runtime offers.
+- `start` needs at least two `lat,lon` waypoints and accepts
+  `--speed=<m/s>` (20 m/s when omitted) plus either `--distance=<meters>`
+  between updates or `--interval=<seconds>` between updates (1 s when neither
+  is given). Use `-` to read waypoints from stdin, one per line. Coordinates
+  use `.` for decimals and `,` between latitude and longitude.
+- `run` accepts scenario names only. A stored GPX route is played through
+  Xcode's Debug > Simulate Location.
 
-### Mask Options
+## Media and capture
 
-| Value | Effect |
-|-------|--------|
-| `ignored` | No mask applied (default). Full rectangular capture. |
-| `alpha` | Transparent pixels where the device bezel would be. Produces PNG with alpha channel. Not supported for video recording  -  falls back to `black`. |
-| `black` | Black pixels where the device bezel would be. Works with JPEG. |
+| Command | Notes |
+|---|---|
+| `io <dev> screenshot [--type=png\|jpeg\|tiff\|bmp\|gif] [--mask=ignored\|alpha\|black] <file>` | PNG unless a type is given; `-` writes to stdout |
+| `io <dev> recordVideo [--codec=h264\|hevc] [--mask=ignored\|black] [--force] <file>` | HEVC by default; stop with Ctrl+C; `--force` overwrites an existing file |
+| `addmedia <dev> <path> [path...]` | Imports photos, Live Photos (photo plus video), videos and vCard contacts; PNG, JPEG, GIF, MOV, MP4 and `.vcf` all work |
 
-## JSON Output Parsing
+Mask policies for non-rectangular screens:
 
-### Find a Booted Device UDID
+- `ignored` (default): the whole rectangular framebuffer.
+- `alpha`: pixels outside the screen shape become transparent, so a PNG keeps
+  the rounded corners. Video does not support it and renders the mask black.
+- `black`: pixels outside the screen shape are black; fine for JPEG.
 
-```bash
-xcrun simctl list -j devices booted | \
-    jq -r '[.devices[][] | select(.state == "Booted")] | first | .udid'
-```
+`recordVideo` prints "Recording started" to stderr once the first frame is
+captured, which scripts can wait for.
 
-### Find a Device by Name and Runtime
+## JSON with jq
 
 ```bash
-RUNTIME="com.apple.CoreSimulator.SimRuntime.iOS-18-4"
-xcrun simctl list -j devices available | \
-    jq -r --arg rt "$RUNTIME" \
-    '.devices[$rt][] | select(.name == "iPhone 16 Pro") | .udid'
-```
-
-### List All Available Runtimes
+xcrun simctl list devices booted --json |
+  jq -r '[.devices[][] | select(.state == "Booted") | .udid] | first'
 
-```bash
-xcrun simctl list -j runtimes | \
-    jq -r '.runtimes[] | select(.isAvailable == true) | "\(.name)  -  \(.identifier)"'
-```
+xcrun simctl list devices --json |
+  jq -r --arg rt com.apple.CoreSimulator.SimRuntime.iOS-26-0 \
+    '.devices[$rt][] | select(.name == "Checkout iPad") | .udid'
 
-### Get Device State
+xcrun simctl list runtimes --json |
+  jq -r '.runtimes[] | select(.isAvailable) | "\(.name)\t\(.identifier)"'
 
-```bash
-xcrun simctl list -j devices | \
-    jq -r --arg udid "$UDID" \
-    '[.devices[][] | select(.udid == $udid)] | first | .state'
+xcrun simctl list devices --json |
+  jq -r --arg id "$SIM" '.devices[][] | select(.udid == $id) | .state'
 ```
 
-## Privacy Service Names
-
-Service names accepted by `simctl privacy grant|revoke|reset`:
-
-| Service | Description |
-|---------|-------------|
-| `all` | All services. `grant` and `revoke` require a bundle identifier; `reset` may omit it. |
-| `calendar` | EventKit calendar access |
-| `contacts-limited` | Limited contacts access |
-| `contacts` | Full contacts access |
-| `location` | When-in-use location access |
-| `location-always` | Always location access |
-| `photos-add` | Add-only photo library access |
-| `photos` | Full photo library access |
-| `media-library` | Apple Music / media library |
-| `microphone` | Microphone access |
-| `motion` | Core Motion activity data |
-| `reminders` | EventKit reminders access |
-| `siri` | Siri integration |
-
-## Status Bar Override Flags
-
-All flags for `simctl status_bar <UDID> override`:
-
-| Flag | Type | Example |
-|------|------|---------|
-| `--time` | String | `"9:41"` |
-| `--dataNetwork` | String | `hide`, `wifi`, `3g`, `4g`, `lte`, `lte-a`, `lte+`, `5g`, `5g+`, `5g-uc`, `5g-uwb` |
-| `--wifiMode` | String | `searching`, `failed`, `active` |
-| `--wifiBars` | Integer | `0`-`3` |
-| `--cellularMode` | String | `notSupported`, `searching`, `failed`, `active` |
-| `--cellularBars` | Integer | `0`-`4` |
-| `--operatorName` | String | `""` (empty for clean screenshots) |
-| `--batteryState` | String | `charging`, `charged`, `discharging` |
-| `--batteryLevel` | Integer | `0`-`100` |
-
-### App Store Screenshot Preset
+In order: the UDID of the first booted device; a UDID by name and runtime;
+installed runtimes that can be used, with their identifiers; and the state of
+one device.
+
+## Privacy services
+
+| Service | Scope |
+|---|---|
+| `all` | Every service. `grant` and `revoke` still need a bundle ID; `reset` can omit it |
+| `calendar` | Calendar events (EventKit) |
+| `reminders` | Reminders (EventKit) |
+| `contacts-limited` | Basic contact details |
+| `contacts` | Full contact records |
+| `location` | Location while in use |
+| `location-always` | Location at all times |
+| `photos-add` | Adding to the library only |
+| `photos` | Full photo library |
+| `media-library` | Music and media library |
+| `microphone` | Audio input |
+| `motion` | Motion and fitness data (Core Motion) |
+| `siri` | Using the app with Siri |
+
+## Status bar flags
+
+| Flag | Accepted values |
+|---|---|
+| `--time` | Any string, for example `9:41`; a valid ISO date also sets the date |
+| `--dataNetwork` | `wifi` or `hide`; cellular types `3g`, `4g`, `lte`, `lte-a`, `lte+`, and the 5G family `5g`, `5g+`, `5g-uc`, `5g-uwb` |
+| `--wifiMode` | `searching`, `failed`, `active` |
+| `--wifiBars` | 0 to 3 |
+| `--cellularMode` | `notSupported`, `searching`, `failed`, `active` |
+| `--cellularBars` | 0 to 4 |
+| `--operatorName` | Any string; `''` for none |
+| `--batteryState` | `charging`, `charged`, `discharging` |
+| `--batteryLevel` | 0 to 100 |
+
+A preset for store screenshots:
 
 ```bash
-xcrun simctl status_bar booted override \
-    --time "9:41" \
-    --batteryState charged \
-    --batteryLevel 100 \
-    --cellularMode active \
-    --cellularBars 4 \
-    --wifiMode active \
-    --wifiBars 3 \
-    --dataNetwork wifi \
-    --operatorName ""
+xcrun simctl status_bar "$SIM" override \
+  --dataNetwork wifi --wifiMode active --wifiBars 3 \
+  --cellularMode active --cellularBars 4 --operatorName '' \
+  --batteryState charged --batteryLevel 100 --time "9:41"
 ```
 
 ## Troubleshooting
 
-### Stuck "Booting" State
+**Device stuck while booting** (boot fails because the device is already in
+the Booting state):
 
-The device shows state "Booting" and `simctl boot` returns "Unable to boot device in current state: Booting."
+1. `xcrun simctl shutdown <dev>`, then `erase <dev>`, then `boot <dev>`.
+2. Still failing: delete the device and create a new one.
+3. Last resort: `xcrun simctl shutdown all` and remove
+   `~/Library/Developer/CoreSimulator/Caches`.
 
-```bash
-# Step 1: force shutdown
-xcrun simctl shutdown <UDID>
+**Runtime missing** ("Invalid runtime", or nothing under `list runtimes`):
+check `xcrun simctl list runtimes`, then install one with
+`xcodebuild -downloadPlatform iOS` or from Xcode > Settings > Components.
+Runtimes can be larger than 5 GB, so CI images should have them preinstalled.
 
-# Step 2: erase the device
-xcrun simctl erase <UDID>
-
-# Step 3: boot again
-xcrun simctl boot <UDID>
-```
-
-If erasing does not resolve it, delete and recreate the device. As a last resort, clear the CoreSimulator caches:
+**CoreSimulator cache damage** shows up as boot failures, a stale
+`simctl list`, or "Unable to determine simulator device status". Full reset:
 
 ```bash
 xcrun simctl shutdown all
-rm -rf ~/Library/Developer/CoreSimulator/Caches
-```
-
-### Runtime Not Installed
-
-`simctl create` or `simctl boot` fails with "Invalid runtime" or the runtime does not appear in `simctl list runtimes`.
-
-```bash
-# Check what's installed
-xcrun simctl list runtimes
-
-# Download a runtime via xcodebuild
-xcodebuild -downloadPlatform iOS
-
-# Or download via Xcode > Settings > Platforms
-```
-
-Runtime downloads can be large (5+ GB). In CI, pre-install runtimes in the base image.
-
-### CoreSimulator Cache Corruption
-
-Symptoms: devices fail to boot, `simctl list` shows stale data, or "Unable to determine simulator device status."
-
-```bash
-# Nuclear option  -  reset everything
-xcrun simctl shutdown all
 xcrun simctl erase all
-rm -rf ~/Library/Developer/CoreSimulator/Caches
-# Restart CoreSimulatorService
-launchctl kickstart -k gui/$(id -u)/com.apple.CoreSimulator.CoreSimulatorService 2>/dev/null || true
+rm -rf "$HOME/Library/Developer/CoreSimulator/Caches"
+launchctl kickstart -k "gui/$UID/com.apple.CoreSimulator.CoreSimulatorService" || true
 ```
 
-After clearing caches, you may need to re-create custom devices. Default devices are recreated automatically by Xcode.
-
-### "Unable to boot device in current state: Shutdown"
+Afterwards, custom devices may need to be created again; Xcode recreates its
+default set by itself.
 
-This usually means the required runtime is not fully installed or is corrupted. Verify the runtime is available and re-download if needed:
-
-```bash
-xcrun simctl list runtimes
-# If the runtime shows (unavailable), re-download it
-xcodebuild -downloadPlatform iOS
-```
+**Boot fails from the Shutdown state** ("Unable to boot device in current
+state: Shutdown"): usually the runtime is missing or damaged. Look for
+"(unavailable)" next to it in `list runtimes` and download it again with
+`xcodebuild -downloadPlatform iOS`.